Skip to content

Commit a704002

Browse files
zoomote[bot]roomoteedelauna
authored
[Docs] Specify P1 persisted ownership and add the run-state kernel target architecture (#1706)
* docs(lifecycle): specify P1 persisted ownership and generation blocks (#1689) * lifecycl docs on main * docs(lifecycle): address taltas review: replay increment points, routed-field comparison, roll-forward test --------- Co-authored-by: Roomote <[email protected]> Co-authored-by: Elliott de Launay <[email protected]>
1 parent 632ef53 commit a704002

8 files changed

Lines changed: 1542 additions & 64 deletions
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# ADR-0003: Attempt generation, increment at resume, and replay settlement
2+
3+
## Status
4+
5+
Proposed (2026-09-27). Decider: @edelauna, core maintainer. The P1 spec applies it in LIFE-BLK-P1-012 ([task-lifecycle-persisted-ownership-model.md](../task-lifecycle-persisted-ownership-model.md)).
6+
7+
## Context
8+
9+
A delayed completion from an earlier attempt of a child can be accepted after the child was resumed (`LIFE-GAP-012`). The persisted record has no attempt identity. `PendingTaskAction.actionId` is an approval identity, not an attempt identity.
10+
11+
Three facts constrain the design:
12+
13+
- A resumed child keeps the status `interrupted` while it runs, because `interrupted → completed` is the only legal move out of `interrupted` (`taskLifecycle.ts:9`).
14+
- `markDelegatedChildInterrupted` skips every child that is not `active` (`ClineProvider.ts:710`). The cancel path skips a child that is already `interrupted` (`:3610`). So a stop of a resumed child, which is still `interrupted`, writes nothing.
15+
- The webview, API, and IPC resume surfaces all reach one of two methods in `Task`: `resumeTaskFromHistory` and `resumeAfterDelegation`.
16+
- `resumeTaskFromHistory` runs as soon as a `Task` is built from history (`Task.ts:699, 1017, 2225`), before the user answers the `resume_task` ask. So it runs when a task opens, not only when it resumes.
17+
18+
Line references are at commit `7c291bb08`.
19+
20+
## Decision
21+
22+
1. Add an optional persisted field, `attemptGeneration`, to the child record. A record without it is read as `g0`.
23+
2. Increment the generation when a resumed attempt starts to act: after the `resume_task` ask returns, after a pending-action replay's approval and before its commit, before the task loop starts after a denied replay or a replay answered with feedback, and at the start of `Task.resumeAfterDelegation`. Never write the increment to a `completed` record.
24+
3. A completion carries the generation of the attempt that produced it. A lock-time generation check in the child file's merge rejects a completion whose generation is not current.
25+
4. A replay stamps the new generation onto its `pendingAction` at the same point as the increment. Settlement compares `(actionId, generation)`, and so does the pending-action match in `reopenParentFromDelegation`. `actionId` stays `sanitizeToolUseId(toolCallId)`.
26+
27+
## Consequences
28+
29+
- Every stop and resume cycle gets a fresh generation. A stale completion from any earlier attempt is rejected after the next resume.
30+
- Opening or viewing a task changes nothing. Another window keeps its running attempt, and a completed record stays unchanged (model invariant 6).
31+
- A completion that is already in flight when the user stops the child can still land before the next resume. This is accepted. Once stopped, the instance is aborted and cannot ask again.
32+
- A downgrade reader ignores the field and does not enforce the check.
33+
- A stale settlement from another host cannot clear a replayed action, because the generations differ.
34+
- The lifecycle checker models the generation as current versus stale, so repeated cycles keep a finite state space.
35+
36+
## Alternatives considered
37+
38+
- Increment when the task opens. Rejected. Opening a child in a second window would fence the attempt that runs in the first window, and viewing a completed task would rewrite it.
39+
- Increment at stop. Rejected. A second stop writes nothing, because both stop paths skip a child that is not `active`. So only the first stop fences the old attempt.
40+
- Write a generation-only fence at every stop. Rejected. It needs a new reducer and changes to both stop paths, for a narrow gain.
41+
- Mint a new `actionId` on replay. Rejected. It breaks the tie to the tool call that `LIFE-GAP-038` relies on.
42+
- Accept the replay race as fail-closed. Rejected. Multi-window use is supported, and the fix is one more field in the compare-and-clear.
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# ADR-0005: Roll forward a half-finished pair write
2+
3+
## Status
4+
5+
Proposed (2026-09-27). Decider: @edelauna, core maintainer. The P1 spec applies it in LIFE-BLK-P1-001 ([task-lifecycle-persisted-ownership-model.md](../task-lifecycle-persisted-ownership-model.md)). `LIFE-BLK-P2-004` owns the implementation.
6+
7+
## Context
8+
9+
`TaskHistoryStore.atomicUpdatePair` writes the child record first and the parent record second (`TaskHistoryStore.ts:1040-1043`). Each file has its own lock, so the pair is not atomic. If the parent write is rejected or fails, the child write has already committed.
10+
11+
Existing mechanisms:
12+
13+
- `reconcileDelegationStateCore` already rolls a delegated parent forward from a `completed` awaited child (`TaskHistoryStore.ts:478-494`). It runs only at startup (`:133`) and after migration (`:827`). It writes with `skipTransitionCheck` and has no ownership check.
14+
- `replayDelegationRepairIntent` (`TaskHistoryStore.ts:127`) completes a two-record repair whose intent was durable.
15+
16+
Line references are at commit `7c291bb08`.
17+
18+
## Decision
19+
20+
The system never undoes the child write.
21+
22+
1. If the parent write is rejected because ownership moved, the superseded child's committed state is final. The parent keeps its newer delegation. The host logs a warning that names the child, the parent, and the parent's newer awaited child.
23+
2. If the parent write fails for another reason, the failing host retries it at once through the normal write path, with the lock-time ownership check.
24+
3. If the process stops before the retry, startup reconciliation is the backstop.
25+
4. A new reconciliation rule releases a delegated parent whose awaited child no longer links back to it. This is a behavior change. Today such a parent stays delegated (`TaskHistoryStore.ts:403-407`).
26+
27+
## Consequences
28+
29+
- A superseded child's result is lost, but the warning makes the loss visible.
30+
- A parent left delegated by the fail-closed cancel detach (`ClineProvider.ts:3638`) is released instead of waiting for a child that can never report back.
31+
- `LIFE-BLK-P2-004` decides whether the roll-forward writes a repair intent through `replayDelegationRepairIntent`, and owns the fault-injection tests.
32+
33+
## Alternatives considered
34+
35+
- Write the parent first. Rejected. The lock-time generation check lives in the child file, so it could no longer reject before anything commits.
36+
- Roll back the child. Rejected. The undo can fail, and another host may already have read the child.
37+
- An operation intent log for every pair write. Deferred to the P2 program. It is the complete answer, but it is XL-sized.

0 commit comments

Comments
 (0)