Terminal dispositions disagree on claim retention: stack-pop deletes, release-runbook and the fence retain

[tobyhede]

The execution loop's two terminal dispositions disagree about what happens to a run's claims, and the disagreement is observable to an orchestrator.

applyExecutionTerminalRelease (packages/cli/src/services/execution.ts):

• release-runbook → releaseRunbook(runbookId, { retainClaimsAsTerminal: true }), with the rationale stated inline: "Natural child completion: retain the claim as a terminal tombstone so rd pass/fail --claim-id can confirm-or-conflict against the child's outcome (idempotent post-work commands). Explicit teardown (abort/stop/complete) keeps deleting the claim."
• stack-pop → releaseRunbook(runbookId), which takes the default and deletes every claim controlling the run (projectRunbookRelease, the else arm).

Meanwhile the fenced command mutation retains tombstones in both modes, with a comment saying explicitly that this must not be keyed on the mode.

So the same run reaching the same terminal state leaves a claim id resolving terminal or missing depending on which disposition the loop happened to be given — and stack-pop is the default for every non-claim-addressed run.

Why it is filed rather than fixed

PR #780 changed stack-pop from the positional popRunbook() to releaseRunbook(runbookId). Claim disposition was deliberately held constant there — the bare form deletes claims exactly as the positional pop did — because changing addressing and retention in one commit would make a regression in either untraceable to the other.

What to decide

1. Whether stack-pop should retain tombstones like its sibling and like the fence. The argument for: an orchestrator holding a run-control claim gets the same answer regardless of which internal disposition ran. The argument against: stack-pop covers explicit teardown paths, and the release-runbook comment above draws the line at exactly that distinction — so the current split may be intentional and merely undocumented.
2. Whether the mode union still earns its shape once both arms call the same method with the same addressing and differ only in one boolean. Note this is not a licence to collapse it to a boolean: the exhaustive switch carries a comment explaining that "not release-runbook" must not come to mean "stack-pop", and defer-to-caller is a third arm that releases nothing. Any collapse has to preserve that.

Acceptance

• The retention rule is stated once, in a place both dispositions read from, rather than inferred from two call sites.
• A test pins what a run-control claim resolves to after each disposition — terminal vs missing — so the contract is observable rather than implied.
• If the split is intentional, the reason is recorded at the stack-pop arm; today only release-runbook explains itself.

Related: #597 (unify terminal session-release behind one machine-owned seam) and #734 — both concern which seam owns a terminal release, and this is the claim-disposition half of the same question.

[tobyhede]

A retaining release is not idempotent — 2026-08-16

Measured while writing tests for #780, against a real store:

releaseRunbook(run, { retainClaimsAsTerminal: true })   // first release
releaseRunbook(run)                                     // second release
  -> { status: 'released', removedFromDefaultStack: false, ... }
  -> the retained claim is gone from session.claims afterwards

So a claim retained as a "terminal tombstone" stays active in the session projection. It is not inert: a later default-disposition release of the same run finds it, deletes it, and reports released rather than not-found.

Two consequences worth folding into the decision here:

1. The two dispositions are order-dependent, not just different. A run released by release-runbook and then again by stack-pop ends with its claim deleted — the retention is undone by whichever release runs last. Any argument that the split is intentional has to say what happens when both run for the same run, which is reachable on the inline paths where a child is released by its own loop and again by a parent seam.
2. not-found is not a stable answer for an already-released run. It only holds once every claim controlling the run is gone. That matters for fix(cli): release the loop's own run at terminal, not whatever is on top #780's premise that a terminal release can be issued unconditionally: the call is safe to repeat, but the result of repeating it is not constant, so nothing should branch on not-found as "already released".

Neither is a defect on its own — recording them because the retention rule is currently inferred from two call sites, and this is the behaviour those two sites compose into.

Verified by direct probe, not by reading: a review suggestion asserting the opposite (that a second release returns not-found with the retained claim intact) failed on both counts.

[tobyhede]

Audit: verified, reproduced, and two corrections to this issue — 2026-08-17

Checked against dfc8490b5, and reproduced end to end with a freshly built CLI.

Every code claim in this issue holds

• execution.ts:376 retains, :398 revokes by omission, and the fence at :1740 retains in both modes with a comment saying the decision must not be keyed on the mode.
• The rule the release-runbook comment states — natural completion retains, explicit teardown deletes — is contradicted by lifecycle-command-service.ts:2998 / :3015 / :3106. Those are the complete / stop / terminal-confirm paths and all three retain. Collateral children revoke explicitly (:1865, :2267).
• Per the comment above, a revoked claim is not deleted: applySession tombstones it superseded (runbook-store.ts:1558-1585), and a non-delegated run-control claim then resolves reason: 'claim-rotated' (session-service.ts:699-700).

Reproduced: one command, two answers

Two rundown run invocations, same project, both ending runbook_stopped:

# 1. command exits 1, handler is FAIL STOP
$ rundown run rb.md --allow-all
  claims table:  rdclk_0906… | active
  rundown pass --claim-id …  =>  already-resolved, lifecycle completed

# 2. the delegation runbook does not resolve
$ rundown run parent.md
  {"type":"runbook_stopped","reason":"delegation_resolution_failed",…}
  claims table:  rdclk_0629… | superseded
  rundown status --claim-id …  =>
    "Claim id rdclk_0629… was released or replaced and is no longer authority.
     Claim the parent's current delegation instead of reusing this id."

In case 2 the run row survives with lifecycle = stopped and the session stack is empty, so this is :398 and not a prune. The orchestrator holding the runbook_started.claim_id is told its claim was rotated, and is pointed at a delegation that does not exist. No race, no second process, and no successful delegation is needed to get there.

Correction 1: stack-pop is not what fires on an ordinary completion

This issue implies every non-claim-addressed run takes the revoking path. It does not. A run that reaches terminal through the fenced command mutation returns at execution.ts:1849 and never calls applyExecutionTerminalRelease — confirmed: a run that completes normally keeps its claim active.

:398 is reached from the entry-time terminal checks — :1258 → :1309 and :1318 → :1325 — that is, runs already terminal when the loop is entered. Case 2 above is exactly that: the delegation actor fails during initialization and writes lifecycle: 'stopped' before the loop starts, which is the case the comment at :1292-1296 names.

This matters for acceptance item 2. A characterisation test built on a plain completion pins the fence's retention and passes for the wrong reason; the test has to construct an already-terminal loop entry.

Correction 2: the axis is neither of the two on offer

transitions.ts:253, lifecycle-command-service.ts:2606 / :2902 and goto-workflow.ts:196-205 all select release-runbook iff the target was resolved through a claim — and goto's helper literally returns stack-pop when the run has no claim.

So stack-pop encoded "this run is unclaimed". That was true until rundown run began minting a run-control claim over every default-stack root; :398 is the site that never noticed. That is a more precise account than natural-vs-explicit (wrong, above) or addressed-vs-collateral (right for the other 15 sites, but it reads this one as a policy choice rather than as a stale precondition).

Acceptance items

• Item 3 is stale. The stack-pop arm does explain itself now, at execution.ts:386-391 — it records fix(cli): release the loop's own run at terminal, not whatever is on top #780's deferral rather than a policy. The item is really "replace the deferral note with the rule".
• Item 2 is open. The tests assert the call shape (toHaveBeenCalledWith(runbookId) vs { retainClaimsAsTerminal: true }), never what the claim resolves to.

Two adjacent findings

• applyExecutionTerminalRelease is also called for runs that are not terminal — execution.ts:1561, :1612, :1638 — and in stack-pop mode each revokes the claims of a live run that has, by construction, issued delegations. Filed as Terminal release fires on non-terminal runs: the frontier refusal arms revoke a live run's claims #789. Fixing :398 fixes those arms too.
• In stack-pop mode a terminal reached through the drain gets no release at all (:1428, :1440), and the drain's core primitive touches only run state (completion-service.ts:1431). Such a run stays on the default stack after it finishes. Same observation as the design note's "separate behaviour change", now confirmed in core.

Corrections to the design note (docs/superpowers/notes/2026-08-17-781-claim-retention-release-cause.md)

• §7's idempotence property is false against the code. A repeated release reports released, not not-found, because projectRunbookRelease counts retained claims in its not-found test (session-service.ts:163-170). The 2026-08-16 comment above measured this correctly; the note contradicts it.
• Nothing in product code reads the release result payload — only .kind on the mutation wrapper. ReleaseRunbookResult.status has no consumer, so both "not-found is a safe no-op" arguments concern a value no caller observes, and the graft returning retainedClaimKeys / revokedClaimKeys has no consumer either.
• §5's "a retention decision lives in packages/cli" is about an unreachable branch. Both production callers of orchestrateTransition pass releaseRunbook: false, so transition-orchestrator.ts:135 never fires; the true policies from createPass/FailTransitionConfig go to core's fenced terminalRelease instead (transitions.ts:646). The live CLI decisions are execution.ts:376 and :1740.
• §2 says the projection computes the retained/removed lists and discards them; it uses them for the not-found decision.

Priority

P3: low reads "deferrable; mitigation already in place". There is no mitigation: one ordinary command yields a false claim-rotated and an instruction the caller cannot follow. Raising to P2.

[tobyhede]

Design assessment of the note's §3–§5 — 2026-08-17

Produced under the codebase-design skill. I checked every fact cited below against the code myself; the citations are those checks.

Short version: the diagnosis in §1–§3 is right and well-evidenced. The recommendation in §5 needs changes that remove both of design C's distinguishing mechanisms, and the seam set is about a third too small.

1. The design covers the wrong set of seams

The note treats SessionService.releaseRunbook / releaseRunbooks as the seam. At least six dispositions never reach SessionService at all. They travel as data on EffectfulActorMutationRunnerInput.terminalRelease and on AggregateTerminalRelease, and are projected by calling projectRunbookRelease directly inside the mutation runner's synchronous, in-place session callback (effectful-actor-mutation-runner.ts:355, :541). execution.ts:1740, lifecycle-command-service.ts:1865, :2267, :3363-3366 and collection-service.ts:735 all sit on that path.

Three consequences:

• A design that unifies only SessionService.release(...) states the rule in two places, which is the thing §1 objects to.
• The policy function's contract is stricter than §4 states. It must be synchronous and in-place, because that is what commitOwnedState({ updateSession }) accepts — not merely "pure inside a mutateState callback".
• runAll throws when a release names a run outside the owned target set (effectful-actor-mutation-runner.ts:382-386). So a batch of discarded runs cannot route through it, and prune.ts:180 has to stay on the SessionService path.

2. §5's base and its first graft are mutually exclusive

ReleaseScope { addressedRunId, runIds } encodes the count of addressed runs in field arity. Graft 1 adds a third role, which makes the role a per-run property that arity cannot carry. And prune.ts:180 releases N runs with no addressed run at all, which a mandatory addressedRunId cannot express.

Drop ReleaseScope. Use readonly RunRelease[] with RunRelease = { runId, role }: per-run roles, one shape for single and batch, literal construction in tests, no brand and no runtime throw. "Release nothing" is the empty array — execution.ts already spells that onComplete: false, so the defer-to-caller role is not needed either.

3. A rename does not fix this issue, because the defect is a derivation

execution.ts:398 never chose stack-pop. Two derivations chose it for it:

• runbook-pipeline.ts:1158 — from options.sessionActivation?.kind, a launch input rather than a fact about the run. default-stack always mints a run-control claim (:993-995, :1088), so this arm asserts the exact inverse of the truth.
• goto-workflow.ts:196-205 — loads the session and returns stack-pop when the run has no claim. One caller, run.ts:375, whose launch already holds the answer.

§8 step 3 says to move call sites while preserving today's disposition. Those two derivations will compute role: 'collateral' from the same stale premise, and the defect crosses the refactor wearing a new name. The load-bearing commit is the one that deletes both derivations — not the one that flips :398.

4. The mode union should collapse to an ownership question

Both releasing arms make the same call to the same address and differ by one boolean. That boolean is a property of how the run ended, not of the caller. The fence already hard-codes retention in both modes and says so explicitly (execution.ts:1732-1740).

/** Who commits the terminal session release for the run this loop drives. */
export type ExecutionReleaseOwner = 'loop' | 'caller';

The comment at :366-368 guards against "not release-runbook" coming to mean "stack-pop". Deleting the arm removes that hazard rather than defending against it; keep the exhaustive switch / never discipline on the two-arm union.

Core already owns the decision: LifecycleTerminalReleaseMode, decided at lifecycle-command-service.ts:2606 / :2902, returned on the resolveRunNavigation outcome and consumed at goto-workflow.ts:271. The four CLI derivations duplicate or contradict it. goto-workflow.ts:196-205 in particular is a Category-B side effect stranded in the CLI — pure loadSession plus a lifecycle decision, no external dependency.

The drain gap closes as a by-product. :1411 and :1431 test the mode where they mean to ask who owns the release; with a two-arm union both become owner === 'loop', and a run that finishes inside the drain stops being stranded on the stack. Moving the drain's release inside completion-service.ts's own transaction, the way the command fence does, remains a separate change — combining the two risks a double release.

5. Rejected grafts

• The ESLint ban is an admission, not enforcement. The Error.isError precedent bans a platform global that cannot be deleted. This identifier is repo-owned; once it is gone the exhaustive union is the enforcement. The ban would also have to enumerate retainClaimsAsTerminalRunId and the AggregateTerminalRelease field, and it stops nobody adding retainClaimsAsX. Keep it as a cheap tripwire if you like — not as the reason to prefer C.
• retainedClaimKeys / revokedClaimKeys on the result: no. §7 already argues the assertion belongs at the resolution seam rather than at the projection, which is an argument against returning them. The payload is nearly dead already: ReleaseRunbookResult.status has exactly one reader in the tree (session-service.ts:1873, building releasedRunIds), and releasedRunIds / nextDefaultRunbookId are read by nobody — prune.ts:180 and lifecycle-command-service.ts:3251 / :3480 check only .kind. Delete ReleaseRunbookResult rather than widen it.

6. Prerequisite

#788 needs a stack-only projection beside the release. If this work lands first without it, popRunbookIfActive stays on the release primitive and #788 becomes a second edit to the same seam. The seam is specified in the design comment on #788.

7. Interface, assembled

// packages/core/src/runbook/session-release.ts — sync, pure, no IO
export type ReleaseRole = 'addressed' | 'collateral' | 'discarded';
export type ClaimDisposition = 'retain-as-terminal-evidence' | 'revoke';
export function claimDisposition(role: ReleaseRole): ClaimDisposition;

export interface RunRelease { readonly runId: RunId; readonly role: ReleaseRole }

export function projectRunRelease(session: SessionData, release: RunRelease): boolean;
export function projectStackDeactivation(session: SessionData, runId: RunId): …;  // #788

// SessionService — one method replaces releaseRunbook + releaseRunbooks
release(releases: readonly RunRelease[]): Promise<SessionMutationResult<ReleaseOutcome>>;

// the mutation-runner seam, which must take the same vocabulary
readonly terminalRelease?: { onComplete: boolean; onStopped: boolean; role: ReleaseRole };
readonly releases?: readonly (RunRelease & { when?: 'always' | 'terminal' })[];

Note the trigger axis C proposes already exists, as onComplete / onStopped and when: 'always' | 'terminal'. It has to be reconciled with those rather than introduced; onComplete and onStopped are equal at every live call site and look collapsible.