@gotgenes/pi-subagents 16.1.1 → 16.2.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.1.1...pi-subagents-v16.2.0) (2026-06-14)
+
+
+### Features
+
+* encapsulate Subagent.start(), promise, and notification ([#374](https://github.com/gotgenes/pi-packages/issues/374)) ([048b4a0](https://github.com/gotgenes/pi-packages/commit/048b4a0a859ec83e1c73c1386484a747e37ba224))
+
 ## [16.1.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.1.0...pi-subagents-v16.1.1) (2026-06-14)
 
 

package/docs/architecture/architecture.md

@@ -940,7 +940,7 @@ Priority = Impact × (6 − Risk).
 - Targets: `src/lifecycle/concurrency-queue.ts` (→ `concurrency-limiter.ts`), `src/lifecycle/subagent-manager.ts`, `src/index.ts`, `test/lifecycle/concurrency-queue.test.ts`, `test/lifecycle/subagent-manager.test.ts`.
 - Smell: Category C (forward references: the queue's ID-registry design forces a start callback that reaches back into the manager, duplicated between `index.ts` and the test helper) and Category A (dual counting: the queue's `running` counter is fed by `markStarted`/`markFinished` relays in the manager's observer, mirroring state the agents already carry).
 - Change: replace the ID-registry queue with a `ConcurrencyLimiter` that schedules thunks FIFO against a dynamic `getLimit()` — the injected limiter knows nothing about agents, IDs, or the manager.
-  Spawn gates background runs with `limiter.schedule(() => record.run())` (the thunk guards on `queued` status, covering abort-while-queued; Step 3 later folds the guard into `Subagent.start()`); foreground and `bypassQueue` runs invoke directly.
+  Spawn gates background runs with `limiter.schedule(() => record.start())` — `start()` owns the abort-while-queued status guard and stores the promise internally; foreground and `bypassQueue` runs invoke `record.start()` directly.
   The settings `onMaxConcurrentChanged` hook wires to `limiter.recheck()` in `index.ts`; `dispose()` calls `limiter.clear()` to drop pending thunks.
 - Outcome: dependency direction is strictly manager → limiter (no callback back-edge; the `prefer-const` eslint-disable in the test helper is deleted); the observer's two queue relays are gone; every spawned agent has a `promise` at spawn, collapsing `waitForAll`'s `while (true)` drain loop and its eslint-disable.
 
@@ -960,16 +960,17 @@ Priority = Impact × (6 − Risk).
   `subscribeSubagentObserver` targets `SubagentState`, so observer and state-machine tests no longer stub execution.
   `SubagentExecution` is a mandatory constructor collaborator (production wires it in the single `spawn()` site; passive records build via `make-subagent.ts`), and the two `run()` throws are gone.
 
-#### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374])
+#### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374]) ✅ Complete
 
-- Targets: `src/lifecycle/subagent.ts`, `src/lifecycle/subagent-manager.ts`, `test/tools/get-result-tool.test.ts`, `test/lifecycle/subagent-manager.test.ts`, `test/service/service-adapter.test.ts`, `test/observation/notification.test.ts`, `test/helpers/make-subagent.ts`.
-- Smell: Category C — output arguments: external writes to `record.promise` (3 production/test sites) and `record.notification` (7 test sites).
-- Change: add `Subagent.start()` that runs and stores its own promise (plus an awaitable accessor for `spawnAndWait`/`waitForAll`); make `promise` and `notification` externally read-only; tests attach notification state through `SubagentExecution.parentSession.toolCallId` or a dedicated options field.
-- Outcome: zero external writes to `Subagent` fields outside its own methods (grep-verifiable: `\.promise =` and `\.notification =` appear only inside `subagent.ts`).
+- Targets: `src/lifecycle/subagent.ts`, `src/lifecycle/subagent-manager.ts`, `test/tools/get-result-tool.test.ts`, `test/lifecycle/subagent-manager.test.ts`, `test/service/service-adapter.test.ts`, `test/observation/notification.test.ts`, `test/helpers/make-subagent.test.ts`, `test/lifecycle/subagent.test.ts`.
+- Smell: Category C — output arguments: external writes to `record.promise` (2 production sites in `subagent-manager.ts`, 4 test sites) and `record.notification` (7 test sites; the production path was resolved in Step 2 — the constructor creates `notification` from `execution.parentSession?.toolCallId`, so Step 3's remaining work is making the field read-only and updating tests to supply it via `parentSession`).
+- Change: add `Subagent.start()` that runs and stores its own promise (plus an awaitable accessor for `spawnAndWait`/`waitForAll`); make `promise` and `notification` externally read-only (private `_promise`/`_notification` fields backed by public getters); the abort-while-queued status guard folds into `start()`, removing the inline check from the limiter callback; tests use `createTestSubagent({ toolCallId })` or spawn with `parentSession.toolCallId` instead of post-construction assignment.
+- Outcome: zero external writes to `Subagent` fields outside its own methods (grep-verifiable: `\.promise =` and `\.notification =` appear only inside `subagent.ts`); 6 new unit tests for `start()` behaviour; test count +6 (975 → 981).
+- Landed: `Subagent.start()` in `src/lifecycle/subagent.ts` owns the promise and status guard; `SubagentManager.spawn()` calls `record.start()` (scheduled or immediate); `TestSubagentOptions.toolCallId` wires notification state via the constructor path.
 
 #### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
 
-- Targets: `src/lifecycle/subagent.ts` (533 LOC — largest source file, accelerating churn).
+- Targets: `src/lifecycle/subagent.ts` (455 LOC after Step 2 extracted SubagentState — still the largest source file).
 - Smell: Category B (oversized class; per-run listener fields declared mid-class) and Category C (state owns its mutations: workspace dispose logic appears in `run()`'s catch, `completeRun`, and `failRun`).
 - Change: extract a `RunListeners` object owning the observer-unsubscribe and signal-detach handles (`attach`/`release`), and a workspace-bracket collaborator owning prepare/dispose-with-addendum, so the three dispose paths collapse into one.
 - Outcome: `subagent.ts` ≤ 450 LOC; workspace disposal logic in exactly one place; listener handles no longer raw nullable fields.

package/docs/plans/0374-encapsulate-subagent-start-notification.md

@@ -0,0 +1,268 @@
+---
+issue: 374
+issue_title: "Encapsulate run start and notification attachment on Subagent"
+---
+
+# Encapsulate Subagent.start() and read-only promise/notification
+
+## Problem Statement
+
+`Subagent.promise` is assigned from outside the class in three places — `SubagentManager.spawn()` (two sites: scheduled and immediate paths) — and `record.notification` is assigned from outside the class in seven test sites.
+Both are output-argument smells (design-review check 3): the object should own the state its own methods read.
+`Subagent.run()` already exists; the promise that tracks it lives outside the object purely so callers can `await record.promise`.
+`notification` was already moved to the constructor in Phase 17 Step 2 (wired from `execution.parentSession?.toolCallId`), but the field is still publicly writable, so tests bypass the constructor path with direct assignment.
+
+## Goals
+
+- Add `Subagent.start()` that calls `run()`, stores the resulting promise internally, and returns it.
+- Fold the abort-while-queued status guard into `start()`, removing the inline check from `SubagentManager`.
+- Make `promise` externally read-only: private `_promise` field backed by a public `get promise()` accessor.
+- Make `notification` externally read-only: private `_notification` field backed by a public `get notification()` accessor.
+- Add `toolCallId?: string` to `TestSubagentOptions` so tests wire notification state via the constructor path without external writes.
+- Achieve grep-verifiable outcome: `\.promise =` and `\.notification =` appear only inside `subagent.ts`.
+
+## Non-Goals
+
+- Extracting `RunListeners` or workspace-bracket collaborators from `Subagent` (Phase 17 Step 4, Issue [#375]).
+- Extracting the manager observer from `index.ts` (Phase 17 Step 5, Issue [#376]).
+- Any other Phase 17 step beyond Step 3.
+
+## Background
+
+Phase 17 Step 1 ([#381]) replaced `ConcurrencyQueue` with a `ConcurrencyLimiter` — the manager now calls `this.limiter.schedule(thunk)` and stores the scheduled promise on `record.promise`.
+Phase 17 Step 2 ([#373]) extracted `SubagentState`, made `SubagentExecution` mandatory, and wired `notification` in the constructor via `execution.parentSession?.toolCallId`.
+
+Current external write sites after Step 2:
+
+| Field                 | Location                  | Count                                                                                                                    |
+| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `record.promise`      | `SubagentManager.spawn()` | 2 (scheduled + immediate)                                                                                                |
+| `record.promise`      | Test files                | 3 (`get-result-tool.test.ts`, `service-adapter.test.ts`, `make-subagent.test.ts`)                                        |
+| `record.notification` | Test files                | 7 (`get-result-tool.test.ts` ×2, `subagent-manager.test.ts` ×2, `service-adapter.test.ts` ×1, `notification.test.ts` ×2) |
+
+`SubagentManager.spawnAndWait()` and `waitForAll()` read `record.promise` via the public field — these become getter reads after the change.
+`get-result-tool.ts` reads `record.promise` to `await` it when `wait=true` — unchanged (getter).
+
+The `AGENTS.md` constraint that applies: **output arguments** — if a function sets a field on a received object, it is doing work that belongs inside the owning object.
+
+## Design Overview
+
+### `Subagent.start()` and the status guard
+
+```typescript
+private _promise?: Promise<void>;
+
+/** Awaitable handle to the running promise. Set by start(). */
+get promise(): Promise<void> | undefined {
+  return this._promise;
+}
+
+/**
+ * Start execution: call run(), store the promise, and return it.
+ * Guards against non-active states (e.g. abort-while-queued): if the agent
+ * is neither queued nor running, the promise resolves immediately (no-op).
+ */
+start(): Promise<void> {
+  if (this.status !== "queued" && this.status !== "running") {
+    this._promise = Promise.resolve();
+    return this._promise;
+  }
+  this._promise = this.run();
+  return this._promise;
+}
+```
+
+The guard allows:
+
+- `"queued"` — background agent waiting in the limiter; `run()` proceeds normally.
+- `"running"` — foreground agent (status set to `"running"` at construction in the manager); `run()` proceeds normally.
+- Any terminal state (`"stopped"`, `"error"`, `"completed"`, etc.) — agent was aborted while queued; `start()` becomes a no-op returning an immediately-resolving promise.
+
+This folds the inline `if (record.status !== "queued") return Promise.resolve()` guard out of the `SubagentManager` limiter callback.
+
+### `SubagentManager.spawn()` after the change
+
+```typescript
+// Queued background path
+this.limiter.schedule(() => record.start());
+
+// Immediate path (foreground or bypassQueue)
+record.start();
+```
+
+`spawnAndWait()` continues to `await record.promise` (now uses the getter, no behavior change).
+`waitForAll()`'s `pendingPromises()` continues to `r.promise` (getter — no behavior change).
+
+### `notification` encapsulation
+
+The constructor already writes to `this.notification` internally.
+After the change, the constructor writes to `this._notification`:
+
+```typescript
+private _notification?: NotificationState;
+
+get notification(): NotificationState | undefined {
+  return this._notification;
+}
+
+// In constructor:
+const toolCallId = init.execution.parentSession?.toolCallId;
+if (toolCallId) {
+  this._notification = new NotificationState(toolCallId);
+}
+```
+
+No production writes to `notification` outside the constructor — only test sites need updating.
+
+### `TestSubagentOptions` shorthand
+
+Add `toolCallId?: string` so tests that need a `NotificationState` use the constructor path:
+
+```typescript
+// Before
+const record = createTestSubagent();
+record.notification = new NotificationState("tc-1");
+
+// After
+const record = createTestSubagent({ toolCallId: "tc-1" });
+```
+
+In `createTestSubagent`, `toolCallId` routes through `makeStubExecution({ parentSession: { toolCallId } })`.
+
+### Tests that write `record.promise`
+
+- **`service-adapter.test.ts`** ("strips promise from the record" tests): the test only needs `promise` to be absent from the serialized output.
+  Since `toSubagentRecord()` already builds an explicit object without `promise`, these tests pass without any promise being set on the record.
+  Remove the `record.promise = ...` setup.
+- **`make-subagent.test.ts`** ("allows setting promise directly"): the test's intent was to verify the field was settable.
+  Replace with a test that `start()` sets `promise` internally via the stub execution.
+- **`get-result-tool.test.ts`** ("waits for promise when wait=true"): the test needs a running agent whose promise resolves and updates status to completed.
+  Replace with an execution stub where `runTurnLoop` returns `{ responseText: "Finished after wait.", aborted: false, steered: false }` and call `record.start()`.
+  The `createSubagentSessionStub()` default already resolves with `{ responseText: "done", ... }` — override `runTurnLoop` to return the expected text.
+
+### `subagent-manager.test.ts` notification tests (lines 82, 100)
+
+Tests that reproduce the race-condition bug (notification set post-spawn) become:
+
+```typescript
+const id = manager.spawn(STUB_SNAPSHOT, "general-purpose", "test", {
+  description: "bg",
+  isBackground: true,
+  parentSession: { toolCallId: "tc-1" },
+});
+const record = manager.getRecord(id)!;
+// notification is already wired from the constructor
+await record.promise;
+record.notification?.markConsumed();
+```
+
+The behavior under test (race: `markConsumed()` after `await` is too late) is unchanged.
+
+## Module-Level Changes
+
+- `src/lifecycle/subagent.ts`
+  - Remove public writable `promise?: Promise<void>` field.
+  - Add `private _promise?: Promise<void>`.
+  - Add `get promise(): Promise<void> | undefined`.
+  - Add `start(): Promise<void>` with the status guard.
+  - Rename `this.notification` write in constructor to `this._notification`.
+  - Remove public writable `notification?: NotificationState` field.
+  - Add `private _notification?: NotificationState`.
+  - Add `get notification(): NotificationState | undefined`.
+- `src/lifecycle/subagent-manager.ts`
+  - Replace `record.promise = this.limiter.schedule(() => { if (...) return ...; return record.run(); })` with `this.limiter.schedule(() => record.start())`.
+  - Replace `record.promise = record.run()` with `record.start()`.
+- `test/helpers/make-subagent.ts`
+  - Add `toolCallId?: string` to `TestSubagentOptions`.
+  - In `createTestSubagent`, map `toolCallId` to `makeStubExecution({ parentSession: { toolCallId } })`.
+- `test/helpers/make-subagent.test.ts`
+  - Replace "allows setting promise directly after construction" with a test that `start()` stores promise via the execution stub.
+- `test/tools/get-result-tool.test.ts`
+  - Replace `record.promise = Promise.resolve().then(...)` setup with a stub execution + `record.start()`.
+  - Replace `record.notification = new NotificationState("tc-1")` (×2) with `createTestSubagent({ toolCallId: "tc-1" })`.
+- `test/lifecycle/subagent-manager.test.ts`
+  - Replace `record.notification = new NotificationState("tc-1")` (×2) with spawn options carrying `parentSession: { toolCallId: "tc-1" }`.
+- `test/service/service-adapter.test.ts`
+  - Remove `record.promise = Promise.resolve()` setup (×2) from tests that only need to verify `toSubagentRecord()` strips the field.
+  - Replace `record.notification = new NotificationState("tc-1")` with `createTestSubagent({ toolCallId: "tc-1" })`.
+- `test/observation/notification.test.ts`
+  - Replace `record.notification = new NotificationState("tc-123/tc-1")` (×2) with `createTestSubagent({ toolCallId: "tc-123/tc-1" })`.
+- `docs/architecture/architecture.md`
+  - Mark Step 3 `✅ Complete` and add a "Landed" note.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled**: `start()` behavior (promise stored, status guard no-op) can be tested directly in `subagent.test.ts` without touching the manager.
+2. **Existing tests simplified**: The 7 test sites that do `record.notification = ...` drop an artificial mutation and instead use the natural constructor path — the tests are shorter and closer to production semantics.
+3. **Tests that must stay**: The manager's race-condition tests (lines 74–120) verify ordering of `markConsumed()` vs `await promise` — they change setup only (spawn with toolCallId), not intent.
+4. **Tests removed**: The `make-subagent.test.ts` "allows setting promise" test is replaced, since direct write is no longer possible.
+
+## TDD Order
+
+1. **Add `Subagent.start()` alongside the existing public `promise?` field**
+
+   In `test/lifecycle/subagent.test.ts`, add tests:
+   - `start()` on a running agent returns a defined promise.
+   - `start()` on a stopped agent returns a resolving promise immediately (no-op guard).
+   - After `start()`, `record.promise` matches the returned promise.
+
+   In `src/lifecycle/subagent.ts`: add `private _promise`, `get promise()` (shadowing the old field — TypeScript will require removing the duplicate; advance to step 2 immediately), and `start()`.
+   Commit: `test: add Subagent.start() tests and initial implementation (#374)`
+
+2. **Make `promise` read-only — remove public field, update all write sites**
+
+   Breaking change at the type level.
+   Atomic commit must include:
+   - `src/lifecycle/subagent.ts` — remove `promise?: Promise<void>` public field (only `private _promise` + getter remain).
+   - `src/lifecycle/subagent-manager.ts` — replace both `record.promise = ...` sites with `record.start()` calls; limiter thunk becomes `() => record.start()`.
+   - `test/helpers/make-subagent.test.ts` — replace write-promise test with `start()` test.
+   - `test/tools/get-result-tool.test.ts` — replace `record.promise = ...` setup; use execution stub + `record.start()`.
+   - `test/service/service-adapter.test.ts` — remove `record.promise = Promise.resolve()` setup (×2).
+
+   Run `pnpm --filter @gotgenes/pi-subagents run check` to verify.
+   Commit: `feat: make Subagent.promise read-only, add start() (#374)`
+
+3. **Make `notification` read-only — remove public field, update all write sites**
+
+   Breaking change at the type level.
+   Atomic commit must include:
+   - `src/lifecycle/subagent.ts` — rename public `notification?` to `private _notification`; add `get notification()`; constructor write becomes `this._notification = ...`.
+   - `test/helpers/make-subagent.ts` — add `toolCallId?: string` to `TestSubagentOptions`; route through `makeStubExecution`.
+   - `test/tools/get-result-tool.test.ts` — replace `record.notification = new NotificationState(...)` (×2) with `createTestSubagent({ toolCallId: ... })`.
+   - `test/lifecycle/subagent-manager.test.ts` — replace `record.notification = new NotificationState(...)` (×2) with spawn options carrying `parentSession: { toolCallId: ... }`.
+   - `test/service/service-adapter.test.ts` — replace `record.notification = new NotificationState(...)` with `createTestSubagent({ toolCallId: ... })`.
+   - `test/observation/notification.test.ts` — replace `record.notification = new NotificationState(...)` (×2) with `createTestSubagent({ toolCallId: ... })`.
+
+   Run `pnpm --filter @gotgenes/pi-subagents exec vitest run` and `pnpm --filter @gotgenes/pi-subagents run check`.
+   Commit: `feat: make Subagent.notification read-only, update tests (#374)`
+
+4. **Update architecture doc**
+
+   In `docs/architecture/architecture.md`, mark Step 3 `✅ Complete` and add a "Landed" note summarizing the outcome.
+   Also update the note at line 943 that says "Step 3 later folds the guard into `Subagent.start()`" to reflect it is now done.
+   Commit: `docs: mark Phase 17 Step 3 complete in architecture.md (#374)`
+
+## Risks and Mitigations
+
+- **Risk**: Adding both `private _promise` and `get promise()` while the public `promise?` field still exists is a TypeScript error (duplicate identifier).
+  **Mitigation**: Steps 1 and 2 are merged into one commit: introduce `start()`, remove the public writable field, and fix all consumers atomically.
+  The TDD order describes testing `start()` first, but both the public field removal and the consumer updates land in the same `feat:` commit.
+- **Risk**: The status guard in `start()` allows `"running"` for foreground agents, which have `status = "running"` at construction.
+  If a foreground agent is stopped before `start()` is called (edge case), `run()` would call `markRunning()` on an already-stopped agent.
+  **Mitigation**: Foreground agents are started synchronously at the end of `spawn()` — there is no window between construction and `start()` during which the abort path can fire.
+  The guard is conservative and causes no regression.
+- **Risk**: The race-condition test in `subagent-manager.test.ts` (lines 74–107) verifies that `markConsumed()` called after `await record.promise` is "too late" for the observer.
+  Switching from `record.notification = new NotificationState("tc-1")` to the constructor path does not change timing semantics.
+  **Mitigation**: The test body stays structurally identical; only the setup changes.
+- **Risk**: `service-adapter.test.ts` tests that call `record.promise = Promise.resolve()` might be testing that the field exists on the Subagent type.
+  **Mitigation**: The tests are testing `toSubagentRecord()` output, not the field type.
+  Removing the setup doesn't change the assertion.
+
+## Open Questions
+
+- None.
+  The design is fully specified by the Phase 17 Step 3 architecture note and the existing class structure.
+
+[#373]: https://github.com/gotgenes/pi-packages/issues/373
+[#375]: https://github.com/gotgenes/pi-packages/issues/375
+[#381]: https://github.com/gotgenes/pi-packages/issues/381

package/docs/retro/0374-encapsulate-subagent-start-notification.md

@@ -0,0 +1,38 @@
+---
+issue: 374
+issue_title: "Encapsulate run start and notification attachment on Subagent"
+---
+
+# Retro: #374 — Encapsulate run start and notification attachment on Subagent
+
+## Stage: Planning (2026-06-14T00:00:00Z)
+
+### Session summary
+
+Read issue #374 (Phase 17 Step 3 — output-argument encapsulation), loaded skills, explored `subagent.ts`, `subagent-manager.ts`, `notification-state.ts`, and all seven test files with external writes.
+Produced a 4-step TDD plan in `packages/pi-subagents/docs/plans/0374-encapsulate-subagent-start-notification.md`.
+
+### Observations
+
+- The `notification` field was already constructor-wired in Phase 17 Step 2 (from `execution.parentSession?.toolCallId`); the remaining work is making both `promise` and `notification` externally read-only and updating the 7 + 3 test write sites.
+- Steps 1 and 2 in the TDD order are effectively merged: introducing `private _promise` alongside the existing public `promise?` field is a TypeScript duplicate-identifier error, so the public field removal and all consumer updates must land in one atomic commit (`feat: make Subagent.promise read-only, add start() (#374)`).
+- The status guard (`if (status !== "queued" && status !== "running")`) in `start()` allows foreground agents (constructed with `status: "running"`) to pass through cleanly, while stopping aborted-while-queued agents; this folds the inline guard out of the `SubagentManager` limiter callback.
+- `service-adapter.test.ts` tests that set `record.promise = Promise.resolve()` only test that `toSubagentRecord()` strips the field — the setup is vestigial once `promise` becomes a getter; simply removing it is sufficient.
+- The "waits for promise when wait=true" test in `get-result-tool.test.ts` needs a more realistic execution stub (`runTurnLoop` returning `{ responseText: "Finished after wait.", aborted: false, steered: false }`) so `record.start()` triggers the full run pipeline and calls `markCompleted()` internally.
+- `TestSubagentOptions.toolCallId?: string` is the cleanest shorthand for the 5 test files that create passive records but need a `NotificationState`; it routes through `makeStubExecution({ parentSession: { toolCallId } })`, matching the production constructor path exactly.
+
+## Stage: Implementation — TDD (2026-06-14T16:31:00Z)
+
+### Session summary
+
+Implemented all 4 plan steps in 2 substantive commits: one atomic `feat:` commit for `start()` + `promise`/`notification` read-only + all test site updates, and one `docs:` commit for the architecture doc.
+Test count went from 975 to 981 (+6 new `start()` unit tests).
+Pre-completion reviewer returned PASS with one WARN (stale test count in `package-pi-subagents` SKILL.md — fixed immediately).
+
+### Observations
+
+- Plan steps 1–3 landed in a single commit because making `notification` private required the same `subagent.ts` file as making `promise` private; splitting would have required complex partial staging.
+- The `void record.start()` and `void this.limiter.schedule(...)` patterns were needed in `subagent-manager.ts` to satisfy `@typescript-eslint/no-floating-promises` — `start()` returns a `Promise<void>` but the manager stores the state internally; callers don't need to await it.
+- The "waits for promise when wait=true" test in `get-result-tool.test.ts` required `void record.start()` (intentional fire-and-forget) for the same reason.
+- Grep-verifiable outcome confirmed: `\.promise =` and `\.notification =` appear only inside `subagent.ts` (as `this._promise =` and `this._notification =`).
+- Pre-completion reviewer: PASS (no FAIL findings; WARN on stale skill test count addressed inline).

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

@@ -47,3 +47,44 @@ Test count went from 967 to 975 (+8: 6 `InterruptHandler` unit tests, 2 foregrou
   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).
+
+## Stage: Final Retrospective (2026-06-14T20:00:00Z)
+
+### Session summary
+
+Shipped issue #403 end-to-end across four stages (plan → TDD → ship → live verification): root-caused the bug, implemented the `InterruptHandler` (single `fix:` commit), guarded the already-working foreground path, and released `pi-subagents-v16.1.1`.
+The operator then live-tested all three abort paths (background subagent, foreground subagent, main agent) and confirmed a single Escape aborts each immediately.
+Near-zero rework: one reviewer WARN (stale doc file count) fixed by amend, no follow-up commits, no failed CI.
+
+### Observations
+
+#### What went well
+
+1. The planning-stage SDK trace paid dividends two stages later.
+   When the operator asked during live testing "is it supposed to take two Escapes or just one?", the answer came straight from the `restoreQueuedMessagesToEditor → agent.abort()` trace captured at planning time — no re-investigation.
+   The same trace explained the main-agent and foreground-subagent abort paths immediately.
+2. The keystone de-risking finding (`finishRun()` discards the per-run `AbortController` without aborting it, so the `abort` event fires only on a real interrupt) held up in practice — no spurious turn-end aborts were observed in live testing.
+3. The foreground guard test passed on its first run, confirming the planning trace, so the plan's pre-typed `test:` commit type was correct and the whole implementation landed with zero rework.
+4. Verification was incremental throughout TDD: green baseline first, per-step affected-file runs, `pnpm run check` after the interface-touching step, and full `test`/`check`/`lint`/`fallow` at the end.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — when adding the new source file `interrupt.ts`, I updated the `handlers/` directory listing in `architecture.md` but not the prose total-file count at line 277 (which was already stale: `56` vs the pre-change actual of `57`).
+   Impact: one pre-completion reviewer WARN, fixed by amending the docs commit before push — no rework, no extra commit, no CI cost.
+
+#### What caused friction (user side)
+
+1. None.
+   The operator's involvement was high-value: the third-party-issue direction gate (planning) and the live three-path abort verification (post-ship) validated behavior that unit tests cannot reach (real ESC keypress through the interactive TUI).
+
+### Diagnostic details
+
+1. Model-performance correlation — ship stage and the `pre-completion-reviewer` subagent both ran on `claude-sonnet-4-6` (mechanical orchestration and checklist review — appropriate); retro synthesis on `claude-opus-4-8` (judgment — appropriate).
+   No mismatch.
+2. Escalation-delay tracking — no `rabbit-hole` friction points; the planning SDK dig was productive forward exploration, not repeated calls against one error.
+3. Unused-tool detection — the planning SDK trace navigated minified `node_modules/.pnpm` dist files by hand; `colgrep` (project-code semantic search) and an Explore subagent (project-code understanding) were not suited to reverse-engineering pinned third-party `dist` JS, so no tool was wrongly skipped.
+4. Feedback-loop gap analysis — no gap; verification ran incrementally per TDD step, not only at the end.
+
+### Changes made
+
+1. Added an "Abort / interrupt signal lifecycle" section to `.pi/skills/pi-extension-lifecycle/SKILL.md` documenting the per-run `AbortController`, the ESC → `agent.abort()` path, the `finishRun()` discard-without-abort behavior, and the `ctx.signal` / `tool.execute(signal)` exposure — so future interrupt-timing work need not re-derive it from the pinned SDK `dist` files.

package/package.json

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

package/src/lifecycle/subagent-manager.ts

@@ -168,16 +168,12 @@ export class SubagentManager {
     }
 
     if (options.isBackground && !options.bypassQueue) {
-      // Schedule on the limiter — started when a slot frees. The status guard
-      // makes an abort-while-queued task a no-op (Step 3 folds it into start()).
-      record.promise = this.limiter.schedule(() => {
-        if (record.status !== "queued") return Promise.resolve();
-        return record.run();
-      });
+      // Schedule on the limiter — start() guards against abort-while-queued.
+      void this.limiter.schedule(() => record.start());
       return id;
     }
 
-    record.promise = record.run();
+    void record.start();
     return id;
   }
 

package/src/lifecycle/subagent.ts

@@ -107,8 +107,10 @@ export class Subagent {
 
 	/** AbortController for cancelling this agent. Created at construction. */
 	readonly abortController: AbortController;
-	/** Promise for the full agent run (including post-processing). Set by run(). */
-	promise?: Promise<void>;
+	/** Backing store for the run promise. Set by start(). */
+	private _promise?: Promise<void>;
+	/** Awaitable handle to the running promise. Set by start(). */
+	get promise(): Promise<void> | undefined { return this._promise; }
 
 	// Execution machinery — a single mandatory collaborator (no per-field fallbacks).
 	private readonly execution: SubagentExecution;
@@ -118,7 +120,9 @@ export class Subagent {
 	// Phase-specific collaborators — each born complete when their info becomes available
 	/** The born-complete child session — set when the factory returns inside run(). */
 	subagentSession?: SubagentSession;
-	notification?: NotificationState;
+	private _notification?: NotificationState;
+	/** Notification state for background agents — wired from parentSession.toolCallId. */
+	get notification(): NotificationState | undefined { return this._notification; }
 
 	// Steer buffer — messages queued before the session is ready
 	private _pendingSteers: string[] = [];
@@ -190,7 +194,7 @@ export class Subagent {
 		// Notification state — created from parentSession.toolCallId if present
 		const toolCallId = init.execution.parentSession?.toolCallId;
 		if (toolCallId) {
-			this.notification = new NotificationState(toolCallId);
+			this._notification = new NotificationState(toolCallId);
 		}
 	}
 
@@ -264,6 +268,22 @@ export class Subagent {
 		}
 	}
 
+	/**
+	 * Start execution: call run(), store the promise internally, and return it.
+	 *
+	 * Guards against non-active states (e.g. abort-while-queued): if the agent
+	 * is neither queued nor running, the promise resolves immediately (no-op).
+	 * This folds the inline status guard out of SubagentManager's limiter callback.
+	 */
+	start(): Promise<void> {
+		if (this.status !== "queued" && this.status !== "running") {
+			this._promise = Promise.resolve();
+			return this._promise;
+		}
+		this._promise = this.run();
+		return this._promise;
+	}
+
 	/**
 	 * Resume an existing session with a new prompt, managing the observer
 	 * subscription lifecycle internally (same wiring as run()).