Design the durable PR babysitter lifecycle and completion fence

[barryollama]

Purpose

Design the durable lifecycle for routed and issue-created PR babysitters before routed-PR activation is enabled. PR #223 ships only declarative intake and read-only discovery; ROUTED_PR_BABYSITTER_ACTIVATION_ENABLED remains false.

This is a design record, not implementation-ready work. Do not add a dispatch/readiness label until the lifecycle is reviewed and decomposed.

Governing invariant

Only an active, current-generation babysitter whose durable completion CAS succeeds may emit a completion outcome.

Every provisional, quarantined, stale, cleanup, released, or orphan state must suppress issue advancement. Retry is the sole valid transition from retained/quarantined back to active.

State model

Definitions:

• T: the issue record tracks the babysitter in record.agents.
• F: #issueBabysitterClaims holds that agent's claim token/fence.
• R: fleet release has been confirmed.
• E: an exit may be interpreted as successful PR completion and advance the issue to Human Review.

State	T	F	R	Reachable today?	Required completion rule
Provisional spawn/adopt	1	0	0	Yes: from spawn/adopt until persist + markRunning + local fence installation	E=0 until markRunning succeeds
Active current generation	1	1	0	Yes: normal running state	E=1 only when the durable completion CAS returns true
Claim lost / cleanup in flight	1	0	unknown	Yes: before and during the release await	E=0, synchronously before the first await
Release failed, retained for retry	1	0	0	Yes	E=0; only a retry that atomically reclaims and marks running may return it to active
Release confirmed, cleanup transient	1	0	1	Yes	E=0, then promptly become released/untracked
Released/untracked terminal	0	0	1	Yes; desired terminal state	E=0
Stale local fence / replaced durable generation	1	stale	0	Yes after takeover until observed	E=0 unless the durable completion CAS succeeds
Fence without record	0	1	either	Yes, but forbidden: retirement does not clear the issue-claim map; resume can retarget the record without retargeting its claim-map key	E=0; clean up the stale fence
Live orphan	0	0	0	Yes, but forbidden: standalone routed spawn can reach it if markRunning fails and direct release throws before registry installation	E=0; recover or release explicitly

Reachable but forbidden states

Fence without record

Retirement does not clear the issue-claim map. Resume can retarget the record without retargeting its claim-map key, leaving a fence that no longer corresponds to the tracked record.

Live orphan

The standalone routed spawn path can successfully create a process, then fail markRunning, then fail the direct release before registry installation. The process is live but absent from both the issue record and local claim fence.

The design must make both states unrepresentable or define synchronous, durable recovery that preserves the governing invariant.

Open P1s subsumed by this design

• Late completion after lease expiry can suppress re-admission for 30 days. A lease is currently only a timestamp; the durable completion operation can accept the same generation after expiry. A local lease check alone can create duplicate babysitting, so generation and transition semantics must be designed together.
• Tracked-but-unfenced completion can advance an issue after failed release. A retained process without a valid issue claim can exit as “complete” while PR ownership mapping is still present. Advancement must be conditional on the successful durable completion CAS, not local tracking alone.

Neither P1 should be patched independently. They are constraints on one lifecycle.

Design deliverables

• Name every durable and local phase, its allowed transitions, and which transition owns each side effect.
• Define generation/token creation, takeover, renewal, expiry, completion CAS, quarantine, retry, release, retirement, and restart recovery.
• Make issue advancement consume only a successful durable completion outcome from the current generation.
• Specify crash boundaries around spawn, markRunning, registry installation, local fence installation, release, and exit handling.
• Prove the two forbidden states are either unreachable or durably recoverable.
• Define tests for every row in the state table and for races between expiry/takeover, cleanup/exit, resume/retirement, and spawn/release failure.
• Only after review, decompose implementation work and define the change that may turn routed-PR activation on.

Related

• Intake/discovery split: Add routed-PR intake and discovery (activation disabled) #223
• Original routed-intake request: [factory] The automatic babysitter only covers Factory-created PRs, so it shepherds almost nothing #222

[barryollama]

Historical negative results from #223

These constraints came out of the stopped implementation and should be preserved so the lifecycle design does not repeat the review loop:

1. A rollout flag is not a lifecycle boundary. The safe split was achieved by removing the claim/state-store/orchestrator execution diff entirely, not by leaving it dormant behind ROUTED_PR_BABYSITTER_ACTIVATION_ENABLED. Against Add routed-PR intake and discovery (activation disabled) #223's merge base, the effective diff for src/ports/state.ts, both state stores, and src/orchestrator/factory.ts was empty. The removed identifiers included completeRoutedPrBabysitter, #issueBabysitterClaims, markRoutedPrBabysitterRunning, and releaseBabysitterBestEffort.

2. The two P1 reproductions were properties of that removed shared-claim design, not the pre-existing issue-created babysitter path. Issue-created babysitters pre-existed, but the PR work-unit claim with a 15-minute lease did not ship. The existing StateStore exposes babysitter session set/list/clear only; its remaining leases are dispatch-lifecycle leases.

3. A bare lease check on completion is not a complete fix. In the removed design, lease expiry only changed a timestamp; it did not mutate status or generation. Before a replacement generation was minted, the old claim token remained current. Rejecting all post-expiry completion can cause the same open PR to be re-admitted while the original babysitter is still live, trading stale completion for duplicate babysitting.

4. A local quarantine boolean is not a complete fix. Completion had to be suppressed in provisional spawn/adopt, claim-loss cleanup before the first await, release-await races, retained-after-release-failure, replaced durable generations, resume/retirement retargeting, and standalone spawn failures. A flag placed only in the reported cleanup branch did not cover the neighboring states.

5. Best-effort release has a two-sided failure mode. Deleting tracking after an unconfirmed release creates an invisible live orphan. Retaining tracking avoids invisibility but creates a tracked process without a valid claim; that process must be completion-ineligible until retry atomically reclaims the work, marks the same generation running, and reinstalls the local fence.

6. Local ownership is not generation proof. A deterministic agent name or the local PR ownership map cannot establish that an exit belongs to the durable current generation. The exit path must treat the boolean result of the durable completion CAS as the authority; “the local map still points at this PR” is insufficient.

7. Retry must be the only reactivation path. Retained/quarantined state cannot become active through observation, resume retargeting, or a later exit. Reactivation must be one atomic protocol (or an explicitly crash-safe sequence) that reclaims/generates ownership, marks running, installs the local fence, and only then permits completion.

8. Two identity-retargeting holes must be designed together with completion. Retirement previously could leave the issue-claim map keyed to a removed record, and resume could retarget the record/PR ownership name without retargeting that claim-map key. Separately, the standalone routed spawn could become live before registry installation. Fixing completion alone would leave both recovery identities ambiguous.

These are design constraints, not proposed patches. The next implementation should derive its transitions from the state table and invariant rather than reapplying the rejected local fixes.

[khaliqgant]

PR Babysitter Durable Lifecycle Design

Author: factory-230-lead-0811
Date: 2026-08-11
Issue: #230
Status: DESIGN RECORD — not implementation-ready; do not add dispatch/readiness label

---

0. Code Verification (required by brief)

Before designing, I read the actual implementation. Summary of what exists today:

routed-pr-babysitter.ts (PR #223): ROUTED_PR_BABYSITTER_ACTIVATION_ENABLED = false. Only discoverRoutedPullRequests() and RoutedPrCandidate types exist — no spawn path, no claim map, no lifecycle. The routed babysitter has no active code.

factory.ts — current issue-created babysitter spawn path (#ensureBabysitter, ~lines 10465–10676):

1. #babysitterPr.set(key, { repo, prNumber, agentName: '' }) — local fence, provisional
2. #babysitterSpawned.add(key) — dedup guard
3. #spawnAgent(record, spec, false) — process created; record.agents populated via batch.recordSpawn
4. #babysitterPr.set(key, { ..., agentName: spawned.name }) — fence updated with real name
5. #persistBabysitterSession(...) — durable session saved
6. #saveDispatchLifecycle(record, 'running') — lifecycle phase updated

Current exit/completion path:

• Babysitter exit → #maybeAdvanceToHumanReview → checks #babysitterPr and #babysitterReady (local only) → #completeIssue
• #completeIssue calls #assertDispatchLifecycleOwner (lease renewal check), but performs no generation-level CAS before advancing the issue

#issueBabysitterClaims and markRunning: These do not exist in the current codebase. They are design terms from this issue that the implementation must introduce.

Verification of forbidden states in current source:

1. Live orphan (T=0, F=0, R=0): CONFIRMED reachable in the future routed spawn path (not yet implemented). The standalone path has a related gap: #ensureBabysitter's catch block (line 10660) deletes local tracking but does not call fleet.release(spawned.name). An agent whose spawn succeeds but whose post-spawn registration throws ends up tracked in record.agents (T=1) with its local fence cleared (F=0) and no release (R=0) — the retained-for-retry state. The true T=0 orphan arises in the routed path where spawn precedes registry installation.

2. Fence without record (T=0, F=1): CONFIRMED structurally reachable once #issueBabysitterClaims is introduced. The risk: if #issueBabysitterClaims is keyed by agent name but #babysitterPr is keyed by babysitterOwnershipKey(issueKey, repo, prNumber), retirement that clears #babysitterPr and record.agents may leave the old agent-name key in #issueBabysitterClaims pointing to nothing. The design below prevents this by requiring a single shared ownershipKey for both maps.

---

1. Governing Invariant (reproduced)

Only an active, current-generation babysitter whose durable completion CAS succeeds may emit a completion outcome.

Every other state must suppress issue advancement. Retry is the sole valid transition from retained/quarantined back to active.

---

2. Definitions

Term	Meaning
ownershipKey	babysitterOwnershipKey(issueKey, repo, prNumber) — stable composite key shared by all local maps and the durable store
generationId	Random UUID created atomically by markRunning; incremented only on takeover (new spawn after expiry/crash). Renewal preserves the same generationId.
T	The issue record tracks this babysitter: record.agents has an entry for it
F	#issueBabysitterClaims holds a live claim token/fence for this agent
R	Fleet release has been confirmed (fleet.release returned successfully)
E	May an exit be interpreted as successful PR completion and advance the issue?
markRunning	Atomic durable operation: write { generationId, agentName, claimedAtMs } under ownershipKey IFF no active generation exists (or active lease is expired and this is a takeover)
durable completion CAS	Atomic durable operation: transition generation record from active → completed IFF generationId matches the stored value. Returns true on success only.
pendingSpawn fence	Durable record written before fleet.spawn to enable orphan recovery on crash

---

3. State Table (extended and resolved)

State	T	F	R	Reachable?	E	Completion rule
Not spawned	0	0	0	Yes: before any spawn attempt	0	N/A
Provisional spawn/adopt	1	0	0	Yes: from fleet.spawn ack until markRunning succeeds + local fence installed	0	E=0; suppressed synchronously at #issueBabysitterClaims check
Active current generation	1	1	0	Yes: normal running state	1	E=1 only if durable completion CAS returns true
Claim lost / cleanup in flight	1	0	?	Yes: synchronously before any release await	0	E=0 synchronously; local fence check fails before first await
Release failed, retained for retry	1	0	0	Yes: failed release path	0	E=0; only retry → markRunning may return it to Active
Release confirmed, cleanup transient	1	0	1	Yes: between fleet release and record cleanup	0	E=0; promptly transition to Released/untracked
Released/untracked	0	0	1	Yes: desired terminal	0	E=0; terminal
Stale local fence / replaced generation	1	stale	0	Yes: after takeover, before old agent observes new generationId	0	E=0; durable completion CAS fails (generationId mismatch)
Fence without record	0	1	either	Forbidden; design makes unrepresentable (see §6.1)	0	E=0; recovery sweep clears stale fence
Live orphan	0	0	0	Forbidden for routed path; pendingSpawn fence + recovery makes durable (see §6.2)	0	E=0; recovery sweep releases

---

4. Phase Definitions

4.1 Durable phases (in BabysitterGenerationRecord stored under ownershipKey)

Phase	Description
claimed	markRunning succeeded; generationId assigned; this is the Active state
completed	Durable completion CAS succeeded; issue may advance
released	Fleet release confirmed; record may be cleared

The existing DispatchLifecycle.phase continues to track the issue-level phase (running, publishing, etc). The new BabysitterGenerationRecord tracks the babysitter-level phase independently.

4.2 Local phases (in-memory, per ownershipKey)

Phase	#babysitterPr	#issueBabysitterClaims	Interpretation
Reserved	present, agentName: ''	absent	Provisional — slot reserved, spawn in flight
Active	present, real agentName	present, matching generationId	Normal running
Quarantined	present, real agentName	absent	Retained for retry; fence cleared on claim loss
Cleanup	present, real agentName	absent	Release in flight; do not accept completion
Cleared	absent	absent	Released/untracked

4.3 Transitions and side-effect ownership

From	To	Trigger	Side effects (in order)
Not spawned	Reserved	#ensureBabysitter acquires ownershipKey	Write pendingSpawn to state store; set #babysitterPr[key] = { agentName: '' }
Reserved	Active	markRunning success	1. Write BabysitterGenerationRecord { generationId, agentName, claimedAtMs } atomically; 2. Install #issueBabysitterClaims[key] = { generationId, agentName }; 3. Delete pendingSpawn record; 4. Persist BabysitterSessionState with generationId
Reserved	Live orphan (forbidden)	Spawn success + markRunning fails + release fails	pendingSpawn record enables recovery (see §6.2)
Reserved	Not spawned	Spawn fails	Delete pendingSpawn; clear #babysitterPr[key]; clear #babysitterSpawned
Active	Quarantined	Fleet release begins	Synchronously clear #issueBabysitterClaims[key] before first release await
Quarantined	Active	Retry: new markRunning succeeds	Same as Reserved → Active transition
Quarantined	Released	Retry release succeeds	fleet.release; clearBabysitterSession; clearBabysitterGenerationRecord
Active	Completed	Durable completion CAS	durableCompletionCas(ownershipKey, generationId) returns true → advance issue
Active	Released	Normal release (lifecycle complete)	Clear #issueBabysitterClaims[key]; fleet.release; clear durable records
Stale	Cleared	Takeover + old agent exits	CAS fails; clear local state

---

5. Generation/Token Lifecycle

5.1 Creation

markRunning(workspaceId, ownershipKey, agentName, nowMs) → { generationId: string } | null

Atomic precondition: no existing record OR existing record has leaseUntilMs < nowMs (expiry-based takeover). Returns null if precondition fails.

The ownershipKey is babysitterOwnershipKey(issueKey, repo, prNumber). The generationId is a random UUID created inside markRunning.

5.2 Takeover

Same as creation, but called with a { force: true } flag that changes the CAS condition to: any existing record with an expired lease is overwritten. Takeover creates a new generationId. The prior generationId is stale.

Consequence: if the old babysitter is still running and later exits, its completion CAS will fail because the stored generationId no longer matches.

5.3 Renewal

renewBabysitterGeneration(workspaceId, ownershipKey, generationId, nowMs, leaseMs) → boolean

Renews leaseUntilMs atomically IFF the stored generationId matches. The generationId does NOT change on renewal. Returns false if generation was replaced (stale fence).

5.4 Expiry

A lease expires when leaseUntilMs < now. Lease expiry:

• Permits takeover (a new owner may call markRunning)
• Does NOT invalidate the generationId for completion CAS purposes

P1a fix: The durable completion CAS checks only generationId, not leaseUntilMs. An old babysitter that finishes real work and exits before a new owner has spawned may complete successfully even if its lease has expired. Only if a new owner has called markRunning (incrementing the generationId) does the old babysitter's CAS fail.

5.5 Completion CAS

durableCompletionCas(workspaceId, ownershipKey, generationId) → boolean

Atomically: transition BabysitterGenerationRecord.phase from claimed → completed IFF stored generationId === input generationId. Returns true exactly once per generation. Idempotent: a second call with the same generationId returns false (already completed).

This is the single gate that allows issue advancement. The completion CAS is called only after the local fence check passes.

5.6 Quarantine

If markRunning fails (CAS fails because a newer generation exists), the babysitter transitions to Quarantined:

1. Do NOT call fleet.release yet (the process may be useful for retry context)
2. Clear #issueBabysitterClaims[key] synchronously
3. Leave #babysitterPr[key] intact (T=1 retained)
4. Log quarantine with the ownershipKey and agent name
5. Schedule retry

5.7 Retry

Retry is the only valid transition from Quarantined → Active:

1. Attempt fleet.release(quarantinedAgentName) — best effort
2. Spawn a new agent
3. Call markRunning for the new agent
4. On success: install new #issueBabysitterClaims[key] entry, update #babysitterPr[key].agentName
5. On failure: return to Quarantined, schedule next retry with backoff

5.8 Release (normal, non-completion)

When the babysitter lifecycle ends without completion (superseded, issue abandoned, takeover):

1. Synchronously clear #issueBabysitterClaims[key] (prevents any concurrent exit from completing)
2. await fleet.release(agentName) — if this fails, retain and schedule retry
3. On release success: clearBabysitterSession(workspaceId, ownershipKey)
4. clearBabysitterGenerationRecord(workspaceId, ownershipKey) — or leave expired; the CAS guards are sufficient
5. Delete #babysitterPr[key], #babysitterIssueRefs[key], #babysitterSpawned

5.9 Retirement

Retirement = release a babysitter because its work is superseded (new PR, new route, issue restarted):

• Calls the same release sequence as §5.8
• Must atomically clear both #babysitterPr[key] and #issueBabysitterClaims[key] in the same synchronous step before any await. This is the invariant that prevents Fence without Record.
• The current #cancelBabysitterWake must be refactored to enforce this ordering.

5.10 Restart recovery

On Factory restart, #restoreBabysitterOwnership reads all BabysitterSessionState records. For each:

1. Read BabysitterGenerationRecord from durable store by ownershipKey
2. If record exists and generationId matches the session's persisted generationId: restore as Active (reinstall local fence)
3. If record is missing or generationId mismatches: restore as Quarantined (local fence absent, scheduled for retry)
4. Read all pendingSpawn records; for each older than 2 minutes and not superseded by a confirmed session: treat as potential orphan (§6.2 recovery)

---

6. Forbidden States: Proof of Unreachability or Durable Recovery

6.1 Fence without record (T=0, F=1)

Root cause verified in code: If #issueBabysitterClaims is keyed by agent name but #babysitterPr/issue record tracking uses babysitterOwnershipKey(issueKey, repo, prNumber), retirement that removes the ownership-keyed entry but not the agent-name-keyed fence leaves a dangling fence.

Design resolution — single shared key:

Both #issueBabysitterClaims and #babysitterPr are keyed by ownershipKey = babysitterOwnershipKey(issueKey, repo, prNumber). The claim record stores { agentName, generationId } — the agent name is a field, not the key.

Invariant: ∀ ownershipKey: #issueBabysitterClaims.has(ownershipKey) → #babysitterPr.has(ownershipKey)

Maintained by: A single function #releaseLocalBabysitterFence(ownershipKey) is the only code path that deletes from #issueBabysitterClaims. It always runs synchronously before any await and always also deletes from #babysitterPr in the same synchronous block. No other code path may delete from #issueBabysitterClaims.

Resume/retarget preserves the invariant: #retargetBabysitterAgent updates ref.agentName in #babysitterPr[ownershipKey] and updates #issueBabysitterClaims[ownershipKey].agentName in the same synchronous step. The ownershipKey is unchanged.

Proof of unreachability: The only way to have F=1, T=0 is to have #issueBabysitterClaims[key] set after #babysitterPr[key] is deleted. Under the design, #releaseLocalBabysitterFence deletes from both simultaneously. Since #babysitterPr.delete runs before any await and #issueBabysitterClaims.delete runs in the same synchronous block, there is no interleaving where one is present and the other absent.

6.2 Live orphan (T=0, F=0, R=0) for routed spawn path

Root cause verified: The routed spawn path (not yet implemented) would call fleet.spawn directly without going through #ensureBabysitter. If spawn succeeds but markRunning fails and fleet.release also throws before the agent is inserted into record.agents, the process is live and untracked.

Design resolution — pre-spawn durable fence:

Before calling fleet.spawn for any babysitter (routed or issue-created), write a durable record:

await state.setPendingBabysitterSpawn(workspaceId, ownershipKey, {
  issueKey, repo, prNumber,
  agentNameAttempted: spec.name,
  requestedAtMs: nowMs,
})

Then the spawn sequence:

1. setPendingBabysitterSpawn — durable fence (crash-safe)
2. fleet.spawn(...) — process created
3. markRunning(...) — if fails: go to step 4
4. fleet.release(spawned.name) — if fails: leave pendingSpawn for recovery sweep
5. On all success: deletePendingBabysitterSpawn(ownershipKey) (superseded by confirmed session)

Restart recovery sweep (#recoverStalePendingSpawns):

• Reads all pendingSpawn records older than PENDING_SPAWN_TTL_MS (e.g. 2 minutes)
• For each: attempts fleet.release(agentNameAttempted) — idempotent
• Clears the pendingSpawn record
• Schedules retry if the issue is still in-flight

Proof of durable recovery: No process can be live for more than PENDING_SPAWN_TTL_MS without either a confirmed BabysitterSessionState or a pendingSpawn record. The recovery sweep runs on every restart and on a periodic timer, ensuring eventual release of any orphaned process.

---

7. Crash Boundaries

7.1 Around spawn (routed path)

[setPendingBabysitterSpawn] ← crash here → recovery sweep releases on restart
[fleet.spawn] ← crash here → spawn may or may not have happened; recovery sweep tries release
[markRunning] ← crash here → pendingSpawn intact; recovery releases
[deletePendingBabysitterSpawn] ← crash here → idempotent release on restart (harmless double-attempt)

7.2 Around spawn (current issue-created path, existing gap)

Current code: #ensureBabysitter catch block does NOT call fleet.release. Fix: Add fleet.release(spawned.name) to the catch block, best-effort, before clearing local state. This closes the current retained-but-unreleasable gap without requiring the full pendingSpawn machinery.

7.3 Around markRunning

markRunning is a single durable write. Before it: process is live, pendingSpawn record exists. After it: generation is active. Crash between fleet.spawn and markRunning leaves the pendingSpawn record as the recovery anchor.

7.4 Around registry installation (record.agents)

record.agents is in-memory; rebuilt from BabysitterSessionState on restart. BabysitterSessionState is persisted after markRunning succeeds, so any persisted session has a confirmed generation. No crash boundary here — the durable store is the authority.

7.5 Around local fence installation (#issueBabysitterClaims)

The local fence is installed synchronously after markRunning returns. Since there are no awaits between markRunning success and fence installation, there is no crash boundary. The fence is re-installed from the durable BabysitterGenerationRecord on restart.

7.6 Around release

Release is not atomic. Two crash points:

1. Crash after fence cleared but before fleet.release: next exit from the process has no fence → suppressed. The process eventually times out or is reaped. The pendingSpawn record (if from the initial spawn) was already deleted; no stale record. The babysitter session record remains until the release succeeds.
2. Crash after fleet.release but before clearBabysitterSession: on restart, the session record exists but the fleet agent is gone. The restart recovery sweep sees a session with no fleet presence, calls release again (idempotent no-op), and clears the session.

7.7 Around exit handling (most sensitive boundary)

The critical invariant is that no exit signal may advance the issue unless the durable CAS succeeds. The sequence in #maybeAdvanceToHumanReview:

1. [SYNCHRONOUS] Check #issueBabysitterClaims[ownershipKey].generationId === myGenerationId
   — fail here → return immediately, no side effects
2. [SYNCHRONOUS] Set completionInFlight guard
3. [ASYNC] durableCompletionCas(ownershipKey, generationId) 
   — returns false → log, return, no advancement
   — returns true → issue MAY advance
4. [ASYNC] Read issue state, advance to Human Review

If the process crashes between step 3 (CAS success) and step 4 (issue advancement), the CAS record shows phase: completed. On restart, the recovery sweep detects completed-but-not-advanced lifecycles and replays step 4. The CAS is idempotent so a second call returns false; the recovery uses the persisted completion record directly.

---

8. The Two P1s: Resolved by This Design

P1a: Late completion after lease expiry suppresses re-admission for 30 days

Cause: The existing isResumed dedup check uses recoveryKey = "${runId}:${agentName}". If a babysitter expires and is replaced, the old babysitter's late exit would hit isResumed as a seen key and be suppressed — but then the 30-day isResumed TTL prevents re-admission of the legitimate new agent under the same runId.

Resolution: The completion CAS check replaces the isResumed check in the babysitter exit path:

• If the old babysitter's generationId matches the stored generation (no new takeover occurred): CAS succeeds, issue advances correctly. No re-admission needed.
• If a new generation exists (takeover occurred): CAS fails. The old babysitter's exit is suppressed without touching the isResumed ledger.
• The isResumed ledger is NOT consulted for babysitter completion exits. Only the generationId CAS matters.

The 30-day suppression bug is thus structurally eliminated: the completion gate is a generationId CAS, not a named-exit dedup.

P1b: Tracked-but-unfenced completion can advance an issue after failed release

Cause (verified in code): #maybeAdvanceToHumanReview checks #babysitterPr.has(ownershipKey) but does not check the claim fence (#issueBabysitterClaims). A retained agent (T=1, F=0) whose #babysitterPr entry was not cleared can pass this check and reach #completeIssue.

Resolution:

1. Synchronous fence check added as the first gate in #maybeAdvanceToHumanReview:

   const fence = this.#issueBabysitterClaims.get(ownershipKey)
   if (!fence || fence.agentName !== agentName) {
     this.#increment('trackedButUnfencedCompletionSuppressed')
     return // No await before this return
   }
   const { generationId } = fence

2. Durable completion CAS replaces the unconditional #completeIssue call:

   const completed = await this.#state.durableCompletionCas(
     this.#workspaceId, ownershipKey, generationId
   )
   if (!completed) {
     this.#increment('babysitterCompletionCasFailed')
     return
   }

3. Because the fence is cleared synchronously at the start of #releaseLocalBabysitterFence, any retained agent without a fence fails step 1 before any await. No retained agent can pass step 2.

---

9. Test Matrix

9.1 State table rows (one test per row)

Test	Scenario	Expected
provisional-exit-suppressed	Spawn succeeds; markRunning not yet called; babysitter exits	Issue NOT advanced; fence check fails; metric provisionalExitSuppressed incremented
active-cas-gates-completion	Active babysitter exits with completed reason; CAS called	CAS returns true → issue advanced; second exit → CAS returns false → suppressed
claim-lost-synchronous-suppression	Fence cleared synchronously; concurrent exit arrives	Exit returns before any await; no issue advancement
retained-only-retry-activates	Release fails; agent retained (F=0); exit arrives	Fence check fails → suppressed; retry → markRunning → fence reinstalled → next exit advances
release-confirmed-cleanup	fleet.release returns success	Session record cleared; generation record cleared; both local maps deleted
released-terminal	Released/untracked state; spurious exit event	No record in batch → unowned-agent metric; no issue advancement
stale-fence-cas-fails	Takeover creates new generationId; old babysitter exits	Old generationId != stored → CAS false → suppressed; new babysitter continues
fence-without-record-unreachable	Any sequence of retire/resume/retarget	Invariant: #issueBabysitterClaims.has(k) → #babysitterPr.has(k) holds after every operation
live-orphan-recovery	pendingSpawn record older than TTL on restart	Recovery sweep calls fleet.release; record cleared; issue retry scheduled

9.2 Races

Test	Scenario	Expected
expiry-before-takeover	Lease expires; old babysitter exits before new spawn	generationId still matches → CAS succeeds → issue advances correctly
expiry-after-takeover	New owner spawns + markRunning; old babysitter exits	New generationId != old → CAS fails → old exit suppressed; new babysitter continues
cleanup-concurrent-exit	fleet.release starts (fence cleared); concurrent exit arrives	Synchronous fence check fails before any await; exit suppressed; no double-advance
resume-before-retirement-clears	Agent resumed (new name); old name retired	Retarget updates both maps at ownershipKey simultaneously; retirement finds empty maps → no-op
spawn-release-failure-pendingspawn	Spawn succeeds; markRunning fails; fleet.release throws	pendingSpawn record remains; recovery sweep calls release; pendingSpawn cleared
completion-cas-concurrent	Two concurrent exit signals for same agent	CAS is atomic → first returns true (advances issue); second returns false (suppressed)
restart-mid-release	Factory crashes after fence cleared, before fleet.release	On restart: session record present, no fleet agent → recovery calls release (idempotent); clears session
restart-mid-cas	Factory crashes after CAS succeeds, before issue advancement	On restart: generation record shows phase: completed; recovery replays advancement without re-calling CAS

---

10. New StateStore Operations Required

// Written atomically before fleet.spawn; deleted after markRunning or release
setPendingBabysitterSpawn(workspaceId: string, ownershipKey: string, record: PendingBabysitterSpawn): Promise<void>
listPendingBabysitterSpawns(workspaceId: string): Promise<Array<[string, PendingBabysitterSpawn]>>
clearPendingBabysitterSpawn(workspaceId: string, ownershipKey: string): Promise<void>

// Atomic CAS: write generationId+agentName IFF no active generation (or takeover)
markRunning(
  workspaceId: string,
  ownershipKey: string,
  agentName: string,
  nowMs: number,
  leaseMs: number,
  opts?: { force?: boolean }, // takeover
): Promise<{ generationId: string } | null>

// Renew lease IFF generationId matches
renewBabysitterGeneration(
  workspaceId: string,
  ownershipKey: string,
  generationId: string,
  nowMs: number,
  leaseMs: number,
): Promise<boolean>

// Transition claimed → completed IFF generationId matches; idempotent
durableCompletionCas(
  workspaceId: string,
  ownershipKey: string,
  generationId: string,
): Promise<boolean>

// Read current generation record
getBabysitterGeneration(workspaceId: string, ownershipKey: string): Promise<BabysitterGenerationRecord | undefined>
clearBabysitterGeneration(workspaceId: string, ownershipKey: string): Promise<void>

---

11. Implementation Decomposition (scoping only; not implementation-ready)

Only after this design is reviewed and decomposed:

1. Add new StateStore operations (§10) to the interface and both implementations (file-state-store.ts, in-memory-state-store.ts)
2. Add #issueBabysitterClaims: Map<string, { agentName: string; generationId: string }> to factory; refactor #cancelBabysitterWake into #releaseLocalBabysitterFence (always clears both maps atomically)
3. Add setPendingBabysitterSpawn call before fleet.spawn in #ensureBabysitter; add fleet.release to the existing catch block (closes current gap)
4. Add markRunning call after spawn, between #persistBabysitterSession and #saveDispatchLifecycle
5. Add synchronous fence check + durableCompletionCas gate at the top of #maybeAdvanceToHumanReview
6. Add #recoverStalePendingSpawns to #restoreBabysitterOwnership
7. Build the routed-PR spawn path (a new code path, separate from #ensureBabysitter) using the same pendingSpawn + markRunning protocol
8. Write tests for all rows in §9 and all races in §9.2
9. Gate: only after steps 1–8 pass review → set ROUTED_PR_BABYSITTER_ACTIVATION_ENABLED = true

---

12. What Is Explicitly Not In This Design

• Any change to ROUTED_PR_BABYSITTER_ACTIVATION_ENABLED (remains false)
• Any implementation of the routed spawn path itself
• Any merge or PR that touches activation
• This document is the design record. Implementation decomposition (step 11) requires a separate review gate.