@gotgenes/pi-subagents 16.1.0 → 16.1.1

package/docs/retro/0373-extract-subagent-state.md

@@ -0,0 +1,94 @@
+---
+issue: 373
+issue_title: "Extract SubagentState; make Subagent execution deps mandatory"
+---
+
+# Retro: #373 — Extract SubagentState; make Subagent execution deps mandatory
+
+## Stage: Planning (2026-06-14T03:34:51Z)
+
+### Session summary
+
+Produced the implementation plan at `packages/pi-subagents/docs/plans/0373-extract-subagent-state.md`.
+The architecture doc (Phase 17 Step 2 + "First-principles refinement") already specified the design precisely and the issue body matched it, so planning was confirmation-and-detailing rather than discovery.
+Issue is first-party (`gotgenes`) and unambiguous — skipped the `ask_user` gate.
+
+### Observations
+
+- **Not breaking** for the published surface: `src/service/service.ts` exposes `SubagentRecord`/`SubagentStatus`/spawn-config, never `SubagentInit` or the `Subagent` constructor.
+  Only the internal constructor signature changes.
+- **Single production construction site** confirmed: `SubagentManager.spawn` (~line 139) is the only `new Subagent(...)` outside tests — this is what makes mandatory execution deps viable.
+- **Observer retarget is required**, not optional: making execution mandatory would otherwise force `record-observer.test.ts` to stub execution.
+  Pointing `subscribeSubagentObserver` at `SubagentState` (and dropping the record from `onCompact`, closing over `this` in `subagent.ts`) is the move that lets observer tests target `SubagentState` directly.
+- **`resume()`'s missing-session throw stays** — it guards a genuine runtime state, not a construction concern.
+  Only the two `run()` "not configured for execution" throws are deleted.
+- **`SubagentStatus` home**: moved to `subagent-state.ts` but re-exported from `subagent.ts` to keep `service.ts`'s import path (and the public type bundle path) unchanged, and to avoid a circular import.
+- **Lift-and-shift for the large test file**: `test/lifecycle/subagent.test.ts` (~700 LOC).
+  Step 1 funnels constructions through a local helper and moves the state-machine `describe` blocks to the new `subagent-state.test.ts`, so Step 3's mandatory-execution flip is bounded to the helper + two run/resume factories.
+  Step 3 is unavoidably one atomic commit (removing optional fields breaks every construction at the type level at once).
+- **Doc updates identified**: `architecture.md` (lifecycle file listing, `Subagent` class diagram, mark Step 2 ✅ Complete, Phase 17 prose ~line 879, type-complexity table ~line 649) and `SKILL.md` (Lifecycle 10→11 modules, total 56→57 files).
+- Deferred per scope boundary: metrics-as-projection and result-delivery domain extraction (the other two of the four conflated domains).
+
+## Stage: Implementation — TDD (2026-06-14T09:23:00Z)
+
+### Session summary
+
+Executed all four planned steps as separate commits: (1) extract `SubagentState` value object + new `subagent-state.test.ts`, (2) retarget `subscribeSubagentObserver` at `SubagentState`, (3) the atomic flip making `SubagentExecution` a mandatory collaborator and deleting the two `run()` throws, (4) docs.
+Test count moved 966 → 967 (net): +26 new `SubagentState` tests, minus the migrated state-machine duplicates and the obsolete missing-factory test.
+Pre-completion reviewer returned **PASS**; `check`/`lint`/`test`/`fallow` all clean.
+
+### Observations
+
+- The plan held exactly — every file in Module-Level Changes was touched and nothing else.
+  The `createTestSubagent` consumers (`conversation-viewer`, `notification`, `get-result-tool`, `make-subagent.test`) stayed untouched as predicted; the helper absorbed the construction change via a `TestSubagentOptions` shape that splits passive-state shorthands from identity/execution.
+- **Explicit-`undefined` preservation** (testing-skill warning) mattered: `createTestSubagent` and the local `makeSubagent` build their `SubagentState` via spread of the rest-captured state overrides (`{ defaults, ...stateOverrides }`) so callers passing `completedAt: undefined` (running-status records in `get-result-tool.test`) still get `undefined`, not the `2000` default.
+- The lift-and-shift prep in Step 1 (local `makeSubagent` helper + perl-routing the single-line constructions) paid off: Step 3's breaking flip only had to edit the helper, `createRunnableAgent`, `createResumableAgent`, `createCompletionAgent`, and the constructor describe — not the whole file.
+- Removed the obsolete "throws when the session factory is missing" test (the guard is gone by construction); the construct-complete invariant is now type-level, not runtime-testable.
+  An initial replacement comment was dropped per reviewer/operator feedback as unhelpful.
+- `SubagentExecution` carries 12 fields (4 mandatory).
+  Reviewer flagged it as wide but accepted per the plan's recorded decision to keep it concrete rather than split further.
+- Pre-completion reviewer: **PASS** (no WARN findings).
+
+## Stage: Final Retrospective (2026-06-14T17:20:00Z)
+
+### Session summary
+
+Shipped #373 end-to-end across one conversation spanning Planning → TDD → Ship → Retro: four implementation commits, CI green, issue closed, no release-please PR (a `refactor:`-only change does not trigger a release).
+The plan held exactly — zero rework, and the pre-completion reviewer returned PASS with nothing to fix.
+The single user intervention was a one-line comment removal during TDD Step 3.
+
+### Observations
+
+#### What went well
+
+- **Plan-to-ship with zero rework.**
+  Every file in the plan's Module-Level Changes was touched and nothing else; the `createTestSubagent` consumers stayed untouched exactly as predicted.
+  The lift-and-shift prep (Step 1 funneling constructions through a local `makeSubagent` helper) bounded the breaking Step 3 flip to the helper plus three factories — the atomic-construction-change concern from the plan never materialized as churn.
+- **Clean model allocation across stages.**
+  Planning ran on `claude-opus-4-8`, TDD on `claude-sonnet-4-6`, Ship on `opencode-go/deepseek-v4-flash` (mechanical git/CI/close work), the pre-completion reviewer subagent on `claude-sonnet-4-6`, and Retro on `claude-opus-4-8`.
+  Judgment-heavy work landed on reasoning-strong models; the cheap model handled only the mechanical ship sequence.
+- **Incremental verification.** `pnpm run check` ran after every TDD step (not just at the end), catching the shared-type breakage at the right boundary; the affected test files were run per-step before the full suite.
+
+#### What caused friction (agent side)
+
+- `other` (tombstone comment) — after removing the obsolete "throws when the session factory is missing" test in TDD Step 3, left a comment narrating the *absence* of the guard (`// No "missing session factory" guard: execution is a mandatory constructor collaborator …`).
+  The user flagged it as unhelpful and asked for removal.
+  Impact: one extra `Edit` + a blank-line cleanup + a `--amend` of the Step 3 commit.
+  No behavioral rework; user-caught.
+
+#### What caused friction (user side)
+
+- None of consequence.
+  The single intervention (comment removal) was light mechanical oversight on an otherwise self-driving session; no earlier context would have changed the outcome.
+
+### Diagnostic details
+
+- **Model-performance correlation** — no mismatch.
+  The only subagent dispatch (pre-completion-reviewer) ran on `claude-sonnet-4-6`, appropriate for judgment-heavy review; it returned PASS.
+  The Ship stage on `deepseek-v4-flash` was purely mechanical (git push, `ci_find`/`ci_watch`, `issue_close`, `release_pr_find`) and the one judgment point (the batch-vs-release `ask_user`) was handled correctly.
+- **Escalation-delay / unused-tool / feedback-loop** — nothing notable: no rabbit-holes, no error-chasing sequences, and verification ran incrementally throughout.
+  Lenses skipped.
+
+### Changes made
+
+1. `.pi/skills/code-design/SKILL.md` (§ Names over comments) — added a line forbidding tombstone comments that narrate removed code or the absence of a guard/test/branch, prompted by the user-caught over-comment in TDD Step 3.

package/docs/retro/0381-replace-concurrency-queue-with-limiter.md

@@ -46,4 +46,50 @@ Test count went 975 → 966 (−22 deleted queue tests, +13 new limiter tests);
 - Pre-completion reviewer: WARN (no FAILs).
   Reviewer warnings: the single stale-comment finding at `index.ts:125` — now fixed in commit `90135005`.
 
+## Stage: Final Retrospective (2026-06-14T00:30:00Z)
+
+### Session summary
+
+Shipped #381 across planning, TDD, and release: `pi-subagents` `16.0.0` → `16.1.0`, tag `pi-subagents-v16.1.0`.
+Four commits landed (one `feat`, two `refactor`, one `docs`) plus two `docs(retro)` notes; CI passed first try, the issue was closed with an implemented-in summary, and the release-please PR was merged.
+The plan — written down to code sketches — held up across all three TDD cycles with no design rework.
+
+### Observations
+
+#### What went well
+
+- The plan's fidelity paid off: the `clear()`-settles-pending-promises decision, the atomic step-2 sequencing (migrate consumers + delete queue + delete old test in one commit), and the `void`-prefix prediction for floating promises were all made at planning time and executed without surprise.
+  The `queueing and concurrency` manager tests passed unchanged after only the `createManager` helper swap, validating the planning claim that they exercise behavior, not queue internals.
+- The pre-completion-reviewer (on `anthropic/claude-sonnet-4-6`, 161s, 21 tool uses) caught a stale comment at `src/index.ts:125` that all four deterministic gates (`check`, `lint`, `test`, `fallow dead-code`) passed over.
+  This is the backstop working exactly as intended — a judgment-model review surfacing residue that pattern-matchers cannot.
+- Verification cadence was incremental, not end-loaded: file-scoped `vitest` + `biome` + `eslint` after step 1, `pnpm run check` immediately after the shared-interface change mid-step-2 (per the plan's own instruction), then lifecycle suite → full suite → full lint, then `rumdl` for the docs step, then the full gates + `fallow` before push.
+
+#### What caused friction (agent side)
+
+- `missing-context` (self/reviewer-caught) — the stale comment `// before startAgent / queue drain` at `src/index.ts:125` referenced two deleted concepts but was not cataloged in the plan's Module-Level Changes, despite the planning grep output having surfaced that exact line.
+  The grep hit was visible but never converted into a plan action or an explicit leave-as-is.
+  Impact: one small follow-up commit (`90135005`, `refactor:`); no rework, no design impact — the reviewer backstop absorbed it before ship.
+
+#### What caused friction (user side)
+
+- None.
+  The single user touchpoint — the release-timing gate in `/ship-issue` (release now vs. batch the Phase 17 sequence) — was strategic judgment the agent correctly deferred, not mechanical oversight.
+
+### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`) on `anthropic/claude-sonnet-4-6`; appropriate match for judgment-heavy review, and it returned the session's only actionable finding.
+- **Escalation-delay tracking** — no rabbit-holes; the lone lint error (`@typescript-eslint/no-floating-promises`, 18 sites) was resolved in a single test-file rewrite, far under the 5-call escalation threshold.
+- **Unused-tool detection** — nothing under-tooled; `colgrep`/`grep` were used during planning exploration and the reviewer subagent was dispatched as designed.
+- **Feedback-loop gap analysis** — no gap; verification ran after every cycle, with `pnpm run check` correctly invoked right after the shared-interface change rather than at end-of-session.
+
+#### Process note (no inline change)
+
+- The release-please PR merge required the documented `UNSTABLE` → `gh pr merge` fallback (step 6.4 of `/ship-issue`) because default-`GITHUB_TOKEN` release PRs never get checks.
+  This recurs every release; the prompt already handles it, so it is recorded here only as a standing pattern, not a friction point.
+
+### Changes made
+
+1. Added this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0381-replace-concurrency-queue-with-limiter.md`.
+2. No prompt or `AGENTS.md` changes — the operator chose retro-file-only, since the single friction (the stale `src/index.ts:125` comment) was a one-off execution slip already caught by the pre-completion-reviewer backstop, and the candidate grep-hit rule was judged not worth the prompt verbosity.
+
 [#378]: https://github.com/gotgenes/pi-packages/issues/378

package/docs/retro/0403-abort-subagents-on-interrupt.md

@@ -0,0 +1,49 @@
+---
+issue: 403
+issue_title: "Pressing Escape does not stop subagent/background agent"
+---
+
+# Retro: #403 — Pressing Escape does not stop subagent/background agent
+
+## Stage: Planning (2026-06-14T00:00:00Z)
+
+### Session summary
+
+Investigated the third-party bug report that ESC does not stop subagents and traced the abort path through both the package and the pinned Pi SDK peer deps.
+Found that foreground subagents already receive the parent abort signal end-to-end, while background subagents are detached with no interrupt wiring — the reproducible bug.
+Confirmed direction with the operator via `ask_user` (third-party gate): implement ESC-to-abort for both modes, with a foreground guard test, aborting all running and queued background agents.
+Wrote and committed plan `0403-abort-subagents-on-interrupt.md`.
+
+### Observations
+
+- Key SDK fact that de-risks the design: in `pi-agent-core` `agent.js`, each run creates a fresh `AbortController` and `finishRun()` discards it **without** aborting on normal completion.
+  So the parent signal's `abort` event fires only on a real ESC interrupt — latching `abortAll()` to it will not spuriously kill background agents at turn end.
+- Chosen mechanism: a small `InterruptHandler` driven by `pi.on("turn_start", ...)`, re-latching `ctx.signal` each turn so the latch tracks the live per-run signal even across runs and tool-less turns.
+  `turn_start` was preferred over `tool_execution_start` because a background agent can outlive the run that spawned it; a turn-level latch still holds the current run's signal when the user interrupts a later tool-less turn.
+- Reused the existing `manager.abortAll()` rather than adding `abortBackground()`.
+  Foreground agents are already aborted via their own `wireSignal`, so `abortAll()`'s overlap is redundant-but-harmless (status-guarded `abort()`, idempotent `markStopped`).
+  The manager does not store `isBackground` on the record, so distinguishing modes would need extra state — deferred as an Open Question.
+- Classified as a non-breaking `fix:` (not `fix!:`): no config key, default, or output shape changes; detached-survives-ESC was a limitation, not a contract.
+  Noted the behavior change explicitly in Goals.
+- Foreground path is believed already-correct from the code trace; the plan adds a regression guard in `subagent-session.test.ts` (`forwardAbortSignal` is currently untested for the parent-signal path) and will fix only if the guard fails.
+
+## Stage: Implementation — TDD (2026-06-14T18:00:00Z)
+
+### Session summary
+
+Completed all three TDD cycles against a green baseline (967 tests).
+Added the foreground-abort guard, implemented `InterruptHandler` + `turn_start` wiring, and updated the architecture doc.
+Test count went from 967 to 975 (+8: 6 `InterruptHandler` unit tests, 2 foreground guard tests); `check`, `lint`, `test`, and `fallow dead-code` all pass.
+
+### Observations
+
+- The foreground guard (Step 1) passed on the first run, confirming the planning-stage code trace: the parent signal already reaches the child `session.abort()` via `forwardAbortSignal`.
+  No code fix was needed, so it landed as `test:` exactly as the plan anticipated.
+- `InterruptHandler` came out clean against the `code-design` heuristics — one field read from `ctx`, one method on a one-method `InterruptManager` interface, latch state owned internally, `{ once: true }` listener.
+  The reviewer's code-design check was PASS with no structural concerns.
+- `abortAll()` gained a second narrow-interface consumer (the new handler) on top of the shutdown path; `fallow dead-code` stayed green, so its existing `fallow-ignore-next-line unused-class-member` comment was left untouched.
+- Pre-completion reviewer: **WARN**.
+- Reviewer warnings: stale source-file counts in `architecture.md`.
+  Fixed the current-state prose claim (`56` → `58` source files).
+  Left the fallow health-metrics snapshot rows (line ~650, `7,778 (57 files)`) intact — those are point-in-time analysis tables where the file count was computed alongside LOC and other metrics, so bumping one cell in isolation would desync the snapshot.
+  Amended the fix into the docs commit (not yet pushed).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.1.0",
+  "version": "16.1.1",
   "type": "module",
   "exports": {
     ".": {

package/src/handlers/index.ts

@@ -1,2 +1,3 @@
+export { InterruptHandler } from "#src/handlers/interrupt";
 export { SessionLifecycleHandler } from "#src/handlers/lifecycle";
 export { ToolStartHandler } from "#src/handlers/tool-start";

package/src/handlers/interrupt.ts

@@ -0,0 +1,49 @@
+/**
+ * turn_start event handler that aborts subagents on a parent interrupt (ESC).
+ *
+ * The parent agent loop creates a fresh AbortController per run and only aborts
+ * it on an explicit interrupt — never on normal completion. So latching to the
+ * current run's signal and aborting on its `abort` event fires exactly on ESC.
+ *
+ * `turn_start` carries the live per-run `ctx.signal`, so re-latching each turn
+ * keeps the handler tracking the current signal across runs and tool-less turns.
+ */
+
+/** Narrow manager interface — only the method the interrupt handler calls. */
+export interface InterruptManager {
+  abortAll(): number;
+}
+
+/** Minimal context shape — only the field the handler reads. */
+interface InterruptCtx {
+  signal: AbortSignal | undefined;
+}
+
+/**
+ * Latches the current parent abort signal and aborts all subagents when it fires.
+ *
+ * The latch dedups by reference: most turns reuse the same signal (no-op); a new
+ * run's signal triggers a detach-and-rewire. The `abort` listener is one-shot.
+ */
+export class InterruptHandler {
+  private latched?: AbortSignal;
+  private detach?: () => void;
+
+  constructor(private readonly manager: InterruptManager) {}
+
+  handleTurnStart(ctx: InterruptCtx): void {
+    const signal = ctx.signal;
+    if (signal === this.latched) return;
+
+    this.detach?.();
+    this.detach = undefined;
+    this.latched = signal;
+    if (!signal) return;
+
+    const onAbort = (): void => {
+      this.manager.abortAll();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    this.detach = () => signal.removeEventListener("abort", onAbort);
+  }
+}

package/src/index.ts

@@ -22,7 +22,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
-import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
+import { InterruptHandler, SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
@@ -185,6 +185,10 @@ export default function (pi: ExtensionAPI) {
   const toolStart = new ToolStartHandler(runtime);
   pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
+  // Abort all subagents when the parent agent loop is interrupted (ESC).
+  const interrupt = new InterruptHandler(manager);
+  pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx));
+
   // ---- Agent tool ----
 
   pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());

package/src/lifecycle/subagent-manager.ts

@@ -14,6 +14,7 @@ import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
 import type { SubagentSession } from "#src/lifecycle/subagent-session";
+import { SubagentState } from "#src/lifecycle/subagent-state";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
@@ -140,23 +141,25 @@ export class SubagentManager {
       id,
       type,
       description: options.description,
-      status: options.isBackground ? "queued" : "running",
-      startedAt: Date.now(),
       invocation: options.invocation,
-      // Run config
-      snapshot,
-      prompt,
-      model: options.model,
-      maxTurns: options.maxTurns,
-      thinkingLevel: options.thinkingLevel,
-      parentSession: options.parentSession,
-      signal: options.signal,
-      // Shared deps
-      createSubagentSession: this.createSubagentSession,
-      observer: this.buildObserver(options),
-      getRunConfig: this.getRunConfig,
-      baseCwd: this.baseCwd,
-      getWorkspaceProvider: () => this._workspaceProvider,
+      state: new SubagentState({
+        status: options.isBackground ? "queued" : "running",
+        startedAt: Date.now(),
+      }),
+      execution: {
+        createSubagentSession: this.createSubagentSession,
+        snapshot,
+        prompt,
+        baseCwd: this.baseCwd,
+        observer: this.buildObserver(options),
+        getRunConfig: this.getRunConfig,
+        getWorkspaceProvider: () => this._workspaceProvider,
+        model: options.model,
+        maxTurns: options.maxTurns,
+        thinkingLevel: options.thinkingLevel,
+        parentSession: options.parentSession,
+        signal: options.signal,
+      },
     });
     this.agents.set(id, record);
 

package/src/lifecycle/subagent-state.ts

@@ -0,0 +1,156 @@
+/**
+ * subagent-state.ts — SubagentState value object: lifecycle status and metrics.
+ *
+ * Owns the passive, readable state of a subagent — status, result, error,
+ * timestamps, and stats (toolUses, lifetimeUsage, compactionCount) — together
+ * with the transition methods (markRunning, markCompleted, …) and accumulation
+ * methods (incrementToolUses, addUsage, incrementCompactions) that mutate it.
+ *
+ * State is encapsulated behind getters; external code reads through them but
+ * mutates only via the transition/accumulation methods. The value object owns
+ * all of its own mutations — no field is written from outside.
+ *
+ * Subagent holds one of these privately and delegates its getters and mutation
+ * methods to it. Extracting it lets the lifecycle state machine and the
+ * session-event observer be unit-tested without constructing an executor.
+ */
+
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import { addUsage } from "#src/lifecycle/usage";
+
+export type SubagentStatus =
+	| "queued"
+	| "running"
+	| "completed"
+	| "steered"
+	| "aborted"
+	| "stopped"
+	| "error";
+
+export interface SubagentStateInit {
+	status?: SubagentStatus;
+	result?: string;
+	error?: string;
+	startedAt?: number;
+	completedAt?: number;
+}
+
+export class SubagentState {
+	// Transition state — encapsulated behind getters, mutated only via transition methods
+	private _status: SubagentStatus;
+	get status(): SubagentStatus { return this._status; }
+
+	private _result?: string;
+	get result(): string | undefined { return this._result; }
+
+	private _error?: string;
+	get error(): string | undefined { return this._error; }
+
+	private _startedAt: number;
+	get startedAt(): number { return this._startedAt; }
+
+	private _completedAt?: number;
+	get completedAt(): number | undefined { return this._completedAt; }
+
+	// Stats — accumulated via mutation methods, readable via getters
+	private _toolUses = 0;
+	get toolUses(): number { return this._toolUses; }
+
+	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+	get lifetimeUsage(): Readonly<LifetimeUsage> { return this._lifetimeUsage; }
+
+	private _compactionCount = 0;
+	get compactionCount(): number { return this._compactionCount; }
+
+	constructor(init: SubagentStateInit = {}) {
+		this._status = init.status ?? "queued";
+		this._result = init.result;
+		this._error = init.error;
+		this._startedAt = init.startedAt ?? Date.now();
+		this._completedAt = init.completedAt;
+	}
+
+	/** Increment tool use count. Called by record-observer on tool_execution_end. */
+	incrementToolUses(): void {
+		this._toolUses++;
+	}
+
+	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
+	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Increment compaction count. Called by record-observer on compaction_end. */
+	incrementCompactions(): void {
+		this._compactionCount++;
+	}
+
+	/** Transition to running state. Sets status and startedAt. */
+	markRunning(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+	}
+
+	/**
+	 * Transition to completed state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markCompleted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "completed";
+		}
+	}
+
+	/**
+	 * Transition to aborted state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markAborted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "aborted";
+		}
+	}
+
+	/**
+	 * Transition to steered state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markSteered(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "steered";
+		}
+	}
+
+	/**
+	 * Transition to error state.
+	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
+	 */
+	markError(error: unknown, completedAt?: number): void {
+		this._error = error instanceof Error ? error.message : String(error);
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "error";
+		}
+	}
+
+	/** Transition to stopped state. Always valid — no guard. */
+	markStopped(completedAt?: number): void {
+		this._status = "stopped";
+		this._completedAt = completedAt ?? Date.now();
+	}
+
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	resetForResume(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+		this._completedAt = undefined;
+		this._result = undefined;
+		this._error = undefined;
+	}
+}