@gotgenes/pi-subagents 16.1.1 → 16.2.1

package/docs/plans/0375-extract-run-listener-workspace-bracket.md

@@ -0,0 +1,300 @@
+---
+issue: 375
+issue_title: "Extract run-listener and workspace-bracket collaborators from Subagent"
+---
+
+# Extract run-listener and workspace-bracket collaborators from Subagent
+
+## Problem Statement
+
+`subagent.ts` is the largest source file in `pi-subagents` and an accelerating churn hotspot.
+Two concerns inflate the `Subagent` class beyond its core responsibility (own a child's execution lifecycle):
+
+1. The per-run listener handles (`_unsub`, `_detachFn`) are raw nullable fields declared mid-class, with `wireSignal`/`attachObserver`/`releaseListeners` scattered around them.
+2. Workspace teardown logic appears at two run-completion call sites — `completeRun` (success/abort/steer) and `failRun` (error) — each re-deriving the `if (this._workspace) … dispose() … resultAddendum` shape.
+
+This is Phase 17 Step 4 (core consolidation).
+The goal is to lift both concerns into small owned collaborators so the class shrinks and the dispose logic lives in one place.
+
+## Goals
+
+- Extract a `RunListeners` collaborator that owns the observer-unsubscribe and signal-detach handles, so the two listener handles stop being raw nullable fields on `Subagent`.
+- Extract a `WorkspaceBracket` collaborator that owns prepare-at-run-start and dispose-with-result-addendum, so the workspace-disposal *logic* lives in exactly one place.
+- Bring `subagent.ts` to ≤ 450 LOC (currently 488).
+- Preserve all observable run/resume behavior exactly: observer-callback order, listener release on complete/fail/resume, workspace dispose status mapping, addendum folding, and the distinct error-handling semantics of the two dispose call sites.
+
+This change is **not breaking**: it is a pure internal restructuring with no change to observable behavior, output shape, public service surface, or defaults.
+`RunListeners` and `WorkspaceBracket` are internal lifecycle collaborators, not part of the published `dist/public.d.ts` surface.
+
+## Non-Goals
+
+- No change to `SubagentState`, `SubagentExecution`, the `WorkspaceProvider`/`Workspace` seam interfaces (`src/lifecycle/workspace.ts`), or `subagent-manager.ts` wiring.
+- No change to the run/resume control flow, the abort path, the steer buffer, or the notification field.
+- No unification of the two dispose call sites' *error-handling* semantics (see Design Overview — they are intentionally different lifecycle contexts).
+- Phase 17 Steps 5–9 (manager observer extraction, widget delegation split, test-fixture consolidation, cross-package settings-loader duplication) are separate issues.
+
+## Background
+
+Relevant modules:
+
+- `src/lifecycle/subagent.ts` — the `Subagent` class.
+  After Phase 17 Step 2 ([#373]) extracted `SubagentState` and Step 3 ([#374]) encapsulated `start`/`promise`/`notification`, the remaining structural debt is the listener fields and the workspace dispose duplication.
+- `src/lifecycle/workspace.ts` — the generative workspace seam (ADR 0002): `WorkspaceProvider.prepare(ctx)` returns a `Workspace` (a `cwd` plus a `dispose(outcome)` hook returning an optional `resultAddendum`).
+- `src/lifecycle/subagent-manager.ts` — the only production constructor of `Subagent` (`spawn`); it resolves the registered provider lazily via `getWorkspaceProvider: () => this._workspaceProvider`.
+  It calls `record.disposeSession()` but none of the listener/workspace methods being moved.
+- `test/lifecycle/subagent.test.ts` — directly tests `wireSignal`, `attachObserver`, `releaseListeners` (3 `describe` blocks) and the workspace dispose paths via `run()`.
+
+Current listener fields and methods on `Subagent`:
+
+```typescript
+private _unsub?: () => void;
+private _detachFn?: () => void;
+wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void { … } // sets _detachFn
+attachObserver(unsub: () => void): void { … }                                // sets _unsub
+releaseListeners(): void { … }                                               // clears both
+```
+
+The two handles are attached at different moments: `wireSignal` at run start, `attachObserver` after the session is created; `resume()` only attaches the observer.
+So a single combined `attach(unsub, detach)` (the issue's first-cut sketch) does not match the real call pattern — the collaborator must expose the two attach points separately.
+
+Current workspace state and dispose call sites:
+
+```typescript
+private _workspace?: Workspace;
+// run(): const provider = this.execution.getWorkspaceProvider?.(); if (provider) { this._workspace = await provider.prepare({…}); cwd = this._workspace?.cwd; }
+// completeRun(): if (this._workspace) { finalStatus = …; const r = this._workspace.dispose({status, description}); if (r?.resultAddendum) finalResult += r.resultAddendum; }
+// failRun():     try { if (this._workspace) this._workspace.dispose({status:"error", description}); } catch (e) { debugLog(…); }
+```
+
+Note: the issue's "three places" wording counts `run()`'s prepare-failure catch as a teardown path, but that catch has no prepared workspace to dispose — it only releases listeners and notifies.
+The actual `dispose()` call appears at **two** sites (`completeRun`, `failRun`).
+
+Constraint from AGENTS.md / code-design: business-logic modules stay SDK-free.
+Both new collaborators use only globals (`AbortSignal`) and the local `workspace.ts` types — no Pi SDK imports.
+Import siblings via `#src/...` aliases.
+
+### Invariants from prior Phase 17 steps (must not regress)
+
+Per the [#374] retro lesson — a later phase step must not regress an earlier step's documented `Outcome:` with a green suite.
+This step touches the `Subagent` run/resume surface, so the at-risk invariants are:
+
+- **Step 1 ([#381]) — "every spawned agent has a `promise` at spawn."**
+  Pinned by the regression test in `test/lifecycle/subagent-manager.test.ts` (queued agent has a `promise` at spawn) and `scheduleVia` unit tests in `subagent.test.ts`.
+  This step does **not** touch `start`/`scheduleVia`/`guardedRun`/`_promise` — low risk, but the suite pins it.
+- **Step 2 ([#373]) — "`Subagent` is construct-complete; no 'not configured for execution' throws."**
+  Pinned by the grep check (no "not configured for execution" in `subagent.ts`) and the constructor tests.
+  Both new collaborators are constructed **inside** the `Subagent` constructor (no new optional init fields), so construct-completeness is preserved.
+- **Step 3 ([#374]) — "zero external writes to `Subagent` fields outside its own methods."**
+  Pinned by the grep check (`\.promise =` / `\.notification =` only in `subagent.ts`).
+  The removed `_unsub`/`_detachFn`/`_workspace` fields had no external writers; removing the public `wireSignal`/`attachObserver`/`releaseListeners` methods reduces the surface further.
+
+## Design Overview
+
+Two small owned value objects, each owning state plus the behavior that reads/writes it (principle 9 — state and behavior in a class, not raw fields scattered through a host).
+Neither is procedure-splitting: each owns mutable state and returns a value (`prepare` → cwd, `dispose` → addendum) or encapsulates lifecycle handles.
+
+### `RunListeners` — `src/lifecycle/run-listeners.ts`
+
+Owns the two per-run teardown handles and the wire/release behavior.
+
+```typescript
+export class RunListeners {
+	private unsub?: () => void;
+	private detach?: () => void;
+
+	/** Wire a parent AbortSignal so it stops the run when fired. No-op when no signal. */
+	wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
+		if (!signal) return;
+		const listener = () => onAbort();
+		signal.addEventListener("abort", listener, { once: true });
+		this.detach = () => signal.removeEventListener("abort", listener);
+	}
+
+	/** Store the record-observer unsubscribe handle. */
+	attachObserver(unsub: () => void): void {
+		this.unsub = unsub;
+	}
+
+	/** Release the observer + signal handles. Idempotent. */
+	release(): void {
+		this.unsub?.();
+		this.unsub = undefined;
+		this.detach?.();
+		this.detach = undefined;
+	}
+}
+```
+
+### `WorkspaceBracket` — `src/lifecycle/workspace-bracket.ts`
+
+Owns the prepared `Workspace` and the prepare/dispose logic.
+It captures the provider *resolver* (not the provider) so resolution stays at run-start, matching today's `getWorkspaceProvider?.()` timing.
+
+```typescript
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/** Resolve the registered provider and prepare the child workspace; returns its cwd (undefined when none). */
+	async prepare(ctx: WorkspacePrepareContext): Promise<string | undefined> {
+		const provider = this.resolveProvider();
+		if (!provider) return undefined;
+		this.prepared = await provider.prepare(ctx);
+		return this.prepared?.cwd;
+	}
+
+	/** Dispose the prepared workspace (if any); returns the result addendum verbatim ("" when none). */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		if (!this.prepared) return "";
+		return this.prepared.dispose(outcome)?.resultAddendum ?? "";
+	}
+}
+```
+
+### `Subagent` interaction with the collaborators
+
+Constructed in the `Subagent` constructor (construct-complete):
+
+```typescript
+private readonly listeners = new RunListeners();
+private readonly workspaceBracket: WorkspaceBracket;
+// in constructor:
+this.workspaceBracket = new WorkspaceBracket(this.execution.getWorkspaceProvider ?? (() => undefined));
+```
+
+Call sites in `run()` / `resume()` / `completeRun()` / `failRun()`:
+
+```typescript
+// run() start:
+this.listeners.wireSignal(this.execution.signal, () => this.abort());
+const cwd = await this.workspaceBracket.prepare({ agentId: this.id, agentType: this.type, baseCwd: this.execution.baseCwd, invocation: this.invocation });
+// run() after session created:
+this.listeners.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, { onCompact: … }));
+
+// completeRun():
+const finalStatus: SubagentStatus = result.aborted ? "aborted" : result.steered ? "steered" : "completed";
+let finalResult = result.responseText + this.workspaceBracket.dispose({ status: finalStatus, description: this.description });
+// failRun():
+try { this.workspaceBracket.dispose({ status: "error", description: this.description }); }
+catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
+```
+
+This follows Tell-Don't-Ask: callers tell the bracket to `dispose(outcome)` and receive the addendum string; they do not reach through to `workspace.dispose(…).resultAddendum` (the prior Law-of-Demeter reach-through is absorbed into the bracket).
+
+### Why the two dispose call sites stay separate (structural-duplication check)
+
+The issue asks to "collapse the three dispose paths into one."
+Tracing why the two `dispose()` calls differ (per the code-design "structural reasons before extracting duplication" heuristic) shows they are **different lifecycle contexts**, not incidental duplication:
+
+| Call site     | Status source                                     | Addendum                    | Error handling                                                    |
+| ------------- | ------------------------------------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `completeRun` | derived from `result` (completed/aborted/steered) | folded into the result text | propagates (a dispose throw flows to `run()`'s catch → `failRun`) |
+| `failRun`     | hardcoded `"error"`                               | discarded                   | best-effort `try/catch` + `debugLog`                              |
+
+So the resolution is: the dispose **logic** (the `if (prepared)` guard, the `.dispose()` call, the addendum unwrap) centralizes into `WorkspaceBracket.dispose()` — exactly one place, satisfying the issue's "disposal logic in exactly one place" outcome.
+The two callers retain their distinct status derivation and error handling, because forcing them into one call would require a discriminator parameter that papers over a real lifecycle difference (Sandi Metz: "duplication is cheaper than the wrong abstraction").
+`WorkspaceBracket.dispose()` deliberately does **not** wrap in `try/catch` — the best-effort behavior stays at `failRun`'s call site, preserving the existing semantics line-for-line (including the pre-existing success-path-throw → `failRun` re-dispose behavior).
+
+## Module-Level Changes
+
+- **Added** `src/lifecycle/run-listeners.ts` — `RunListeners` class (`wireSignal`, `attachObserver`, `release`).
+- **Added** `src/lifecycle/workspace-bracket.ts` — `WorkspaceBracket` class (`prepare`, `dispose`).
+- **Added** `test/lifecycle/run-listeners.test.ts` — direct unit tests for `RunListeners`.
+- **Added** `test/lifecycle/workspace-bracket.test.ts` — direct unit tests for `WorkspaceBracket`.
+- **Changed** `src/lifecycle/subagent.ts`:
+  - Remove fields `_unsub`, `_detachFn`, `_workspace` and the public methods `wireSignal`, `attachObserver`, `releaseListeners`.
+  - Add `private readonly listeners = new RunListeners()` and `private readonly workspaceBracket: WorkspaceBracket` (constructed from `execution.getWorkspaceProvider`).
+  - Rewire `run()`, `resume()`, `resetForResume()`, `completeRun()`, `failRun()` to call `this.listeners.*` and `this.workspaceBracket.*`.
+  - Add imports for the two new modules; drop the now-unused `Workspace` type import if no longer referenced (keep `WorkspaceProvider` only if still referenced — verify with the type checker).
+- **Changed** `test/lifecycle/subagent.test.ts`:
+  - Remove the `wireSignal`, `attachObserver / releaseListeners`, and `resetForResume releases listeners` `describe` blocks (their coverage moves to `run-listeners.test.ts`); the `run()`/`completeRun`/`failRun`/`resume` behavioral tests stay and continue to exercise the wired collaborators.
+  - Remove the `attachObserver(unsub)` calls inside the `completeRun`/`failRun` "releases listeners" tests — assert listener release via the run/resume path instead, or via a `RunListeners` unit test.
+
+Doc updates (architecture references the moved symbols and module count):
+
+- **Changed** `docs/architecture/architecture.md`:
+  - File-tree listing (`lifecycle/` block) — add `run-listeners.ts` and `workspace-bracket.ts` entries.
+  - `Subagent` class diagram (key domain types) — remove `+wireSignal`, `+attachObserver`, `+releaseListeners`; optionally add `RunListeners` / `WorkspaceBracket` classes with composition edges.
+  - Findings/health tables — bump `57 files` → `59 files` (lines ~650 and ~897).
+  - Phase 17 Step 4 entry — append a `Landed:` note recording the two collaborators and the final `subagent.ts` LOC.
+- **Changed** `.pi/skills/package-pi-subagents/SKILL.md` — "seven domains (57 files)" → "(59 files)"; Lifecycle domain module count `11` → `13` and add the two modules to the directory list; update the test count if it is cited.
+
+Grep confirmation done while planning: `wireSignal`/`attachObserver`/`releaseListeners`/`_workspace`/`_unsub`/`_detachFn` appear only in `subagent.ts` and `subagent.test.ts` (plus the architecture class diagram); the SKILL does not name them.
+`disposeSession` (the one listener-adjacent method used by `subagent-manager.ts`) is **not** part of this change.
+
+## Test Impact Analysis
+
+1. **New unit tests the extraction enables.**
+   `RunListeners` and `WorkspaceBracket` become directly constructible and testable without booting a `Subagent` or a full `run()`:
+   - `run-listeners.test.ts` — `wireSignal` attaches and `release()` detaches the abort listener; `wireSignal(undefined, …)` is a no-op; `attachObserver` + `release()` calls and clears the unsub; `release()` is idempotent (double-call safe).
+   - `workspace-bracket.test.ts` — `prepare` with no provider returns `undefined`; with a provider returns `workspace.cwd`; with a provider resolving `undefined` returns `undefined`; `dispose` with no prepared workspace returns `""`; `dispose` returns the `resultAddendum` verbatim; `dispose` returns `""` when the workspace returns no addendum; a throwing `dispose` propagates (not swallowed).
+2. **Existing tests that become redundant.**
+   The `wireSignal`, `attachObserver / releaseListeners`, and `resetForResume releases listeners` `describe` blocks in `subagent.test.ts` (~7 tests) duplicate what `run-listeners.test.ts` now covers at a lower level — remove them.
+3. **Existing tests that must stay as-is.**
+   The `run()` workspace tests (prepare threads cwd into the factory, dispose status mapping for completed/error, addendum folding, no-provider path, prepare-failure path) genuinely exercise the *integration* of the bracket into the run lifecycle — they stay and verify the wiring preserved behavior.
+   The `completeRun`/`failRun`/`resume`/`abort` behavioral tests stay.
+
+## Invariants at risk
+
+| Invariant (prior step)                                                                                       | Pinning test                                                                      | Risk from this step                                                                   |
+| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Every spawned agent has a `promise` at spawn ([#381])                                                        | `subagent-manager.test.ts` queued-agent regression test; `scheduleVia` unit tests | None — `start`/`scheduleVia`/`_promise` untouched                                     |
+| `Subagent` construct-complete; no "not configured for execution" throws ([#373])                             | `subagent.test.ts` constructor tests + grep check                                 | None — both collaborators constructed in the constructor, no new optional init fields |
+| Zero external writes to `Subagent` fields ([#374])                                                           | grep check (`\.promise =` / `\.notification =` only in `subagent.ts`)             | None — removes fields/methods, adds no external writers                               |
+| Listener release on complete/fail/resume; observer-callback order; dispose status mapping + addendum folding | `subagent.test.ts` `run()`/`completeRun`/`failRun`/`resume` blocks                | Preserved by keeping the call sequence identical; run-suite pins it                   |
+
+No invariant lives only in prose here — each is already pinned by a named test, and the run-lifecycle tests stay green through the wiring step.
+
+## TDD Order
+
+1. **Add `RunListeners` (red → green → commit).**
+   Write `test/lifecycle/run-listeners.test.ts` (fails — module absent), then implement `src/lifecycle/run-listeners.ts`.
+   Pure addition; `Subagent` not yet touched, suite otherwise unchanged.
+   Commit: `test: add RunListeners with wire/attach/release behavior (#375)` (or a single `refactor:` if test+impl land together — prefer the red/green split).
+2. **Add `WorkspaceBracket` (red → green → commit).**
+   Write `test/lifecycle/workspace-bracket.test.ts` (fails — module absent), then implement `src/lifecycle/workspace-bracket.ts`.
+   Pure addition.
+   Commit: `test: add WorkspaceBracket prepare/dispose behavior (#375)` then `refactor: add WorkspaceBracket collaborator (#375)` — or one `refactor:` commit for the red/green pair.
+3. **Wire both into `Subagent`; remove the raw fields/methods (atomic).**
+   Rewire `run`/`resume`/`resetForResume`/`completeRun`/`failRun` to the collaborators; remove `_unsub`/`_detachFn`/`_workspace` and the public `wireSignal`/`attachObserver`/`releaseListeners`; construct `listeners` and `workspaceBracket` in the constructor.
+   In the **same commit**, update `test/lifecycle/subagent.test.ts`: removing the three public methods breaks that file at the type level, so the deletion of the redundant `describe` blocks and the construction/wiring change must land together.
+   Run `pnpm run check` immediately after (interface-shape change).
+   Commit: `refactor: extract RunListeners and WorkspaceBracket from Subagent (#375)`.
+4. **Update docs (commit).**
+   `architecture.md` (file tree, class diagram, `57 → 59` file counts, Step 4 `Landed:` note with final LOC) and `package-pi-subagents` SKILL.md (file count, Lifecycle module list/count, test count if cited).
+   Commit: `docs: record run-listener and workspace-bracket extraction (#375)`.
+
+Verification gates after step 3 and before review: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code` (confirm no orphaned imports in `subagent.test.ts` after the `describe` removals), and `wc -l src/lifecycle/subagent.ts` (assert ≤ 450).
+
+## Risks and Mitigations
+
+- **Risk: the wiring step silently changes dispose error semantics.**
+  Mitigation: `WorkspaceBracket.dispose()` deliberately does not `try/catch`; the best-effort wrapper stays at `failRun`'s call site, preserving the success-path-throw → `failRun` behavior line-for-line.
+  A `workspace-bracket.test.ts` case asserts a throwing `dispose` propagates.
+- **Risk: `subagent.ts` does not reach ≤ 450 LOC.**
+  Mitigation: removing 3 fields + 3 methods (≈ 25 lines incl. comments) and simplifying the two dispose blocks nets ≈ 40 lines below the current 488; `wc -l` is a gate.
+  If it lands at 451–455, that is an acceptable near-miss to note, not a blocker.
+- **Risk: orphaned imports in `subagent.test.ts` after removing `describe` blocks.**
+  Mitigation: Biome `noUnusedImports` is warning-level (exit 0), so run `pnpm fallow dead-code` and re-check imports manually as part of step 3.
+- **Risk: release cadence.**
+  This issue is internal-only; with `refactor:`/`docs:`/`test:` commits it will not trigger a release-please version bump — it ships bundled with the next feature release.
+  If a standalone release is desired (matching prior Phase 17 per-step cadence), that is a ship-time decision, not a planning one.
+
+## Open Questions
+
+- Whether to add `RunListeners` / `WorkspaceBracket` as classes with composition edges to the architecture class diagram, or only update the file tree.
+  Defer to the doc step — add them if the diagram stays readable.
+- The pre-existing untested success-path-`dispose`-throw → `failRun` re-dispose behavior is preserved but remains unpinned by a `Subagent`-level test.
+  Defer pinning it unless the implementer finds it cheap to add — the extraction does not change it.
+
+[#373]: https://github.com/gotgenes/pi-packages/issues/373
+[#374]: https://github.com/gotgenes/pi-packages/issues/374
+[#381]: https://github.com/gotgenes/pi-packages/issues/381

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

@@ -0,0 +1,171 @@
+---
+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).
+
+## Stage: Final Retrospective (2026-06-14T17:30:00Z)
+
+### Session summary
+
+Shipped issue #374 (Phase 17 Step 3) cleanly across three stages: a planning session produced a 4-step plan, a TDD session implemented it in 2 substantive commits (test count 975 → 981), and a ship session pushed, verified CI, closed the issue, and released `pi-subagents-v16.2.0`.
+No rework, no user corrections, no CI failures — the only mid-stream fixes were two self-identified lint adjustments inside the TDD session.
+
+### Observations
+
+#### What went well
+
+- The cross-session retro bridge worked exactly as designed: the planning stage wrote three concrete breadcrumbs — steps 1+2 must merge (TypeScript duplicate-identifier), the `get-result-tool.test.ts` "waits for promise" test needs a realistic `runTurnLoop` stub, and `TestSubagentOptions.toolCallId` is the cleanest notification shorthand — and the TDD stage consumed all three directly without re-deriving them.
+  This is the first time the breadcrumb-to-implementation handoff is visibly load-bearing rather than ceremonial.
+- The grep-verifiable completion criterion (`\.promise =` and `\.notification =` appear only inside `subagent.ts`) gave an objective, one-command done-check (session turns 123–124) instead of a subjective "looks encapsulated."
+
+#### What caused friction (agent side)
+
+- `missing-context` — the plan did not anticipate that replacing `record.promise = record.run()` (assignment consumes the promise) with a bare `record.start()` call would trip `@typescript-eslint/no-floating-promises` at the two manager call sites and one test site.
+  Self-identified via lint.
+  Impact: two extra `void` edits (turns 106, 111) inside the same commit — no commit reorder, no rework beyond the fixups.
+- `wrong-abstraction` (surfaced by operator pushback during the retro) — the `void this.limiter.schedule(() => record.start())` fix is safe but marks an unfinished design seam, not a tidy idiom.
+  `run()`/`start()` carry a hard "always resolves, errors captured internally" contract, so `void` is the ESLint-sanctioned annotation (no unhandled-rejection risk).
+  But the encapsulation regressed the promise-capture timing: before #374, `record.promise = this.limiter.schedule(...)` set the handle eagerly at spawn (even queued agents had `.promise`); after #374, `.promise` stays undefined until the limiter fires the thunk and `start()` runs, so promise ownership is now split between `Subagent._promise` and the limiter's internal completion handle (which the `void` discards).
+  `waitForAll()` still worked only via `pendingPromises()`'s `null`-filter plus re-poll loop, so the in-code comment "a single `allSettled` covers the queued case" became inaccurate.
+  This regressed Step 1's (#381) documented invariant "every spawned agent has a `promise` at spawn" — a cross-step regression within the same phase, not (as first claimed in this retro) work deferred to a future domain split.
+  Corrected in a follow-up `fix:` (see the second retrospective stage below): `Subagent.scheduleVia(schedule)` captures the limiter promise eagerly inside the agent, restoring the invariant without reintroducing an external `.promise =` write.
+  Impact: one follow-up `fix:` commit (+1 regression test, +2 `scheduleVia` unit tests).
+- `wrong-abstraction` — the plan decomposed the work into 3 TDD steps (promise read-only, notification read-only, doc) but steps 1–3 collapsed into a single atomic commit because both fields live in `subagent.ts` and making each read-only is one type-level change.
+  The planning retro half-anticipated this (it flagged steps 1+2 merging) but did not extend the reasoning to step 3.
+  Impact: plan/reality granularity mismatch, documented as a deviation; no rework.
+
+#### What caused friction (user side)
+
+- None.
+  User involvement was a single well-placed strategic decision (the batch-vs-release-now `ask_user` gate in the ship stage), not mechanical oversight.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning and TDD ran on `claude-sonnet-4-6` (appropriate); the pre-completion reviewer subagent ran on its frontmatter default; the final retro ran on `claude-opus-4-8` (appropriate for judgment-heavy synthesis).
+  The **ship stage ran on `opencode-go/deepseek-v4-flash`** — a weak model driving release management (interpreting the `UNSTABLE` merge state, the batch-vs-release decision, merging the release PR, closing the issue).
+  It executed cleanly this time, but these are irreversible high-stakes operations; pinning a stronger model for `/ship-issue` would de-risk them.
+- **Escalation-delay tracking** — no rabbit-holes; each lint failure resolved within 1–2 tool calls.
+- **Unused-tool detection** — exploration used `cat`/`grep` via `bash` rather than the `Read` tool or `colgrep`; for finding exact `.promise =` write sites, grep is the correct choice (exact-pattern matching), so colgrep non-use was appropriate.
+  The `cat`-via-`bash` habit (vs `Read`) added no harm here but bypasses structured-read benefits.
+- **Feedback-loop gap analysis** — verification was incremental: affected-file tests after the first edits (turn 81), full suite + `check` + `lint` mid-cycle (turns 102–113), and the `fallow dead-code` gate before review.
+  No end-only-verification gap.
+
+### Follow-ups
+
+1. The `start()` / limiter promise-ownership split was reclassified as a regression and **fixed** via `scheduleVia` (see the second retrospective stage), not deferred.
+
+### Considered but not proposed
+
+1. **Floating-promise ESLint rule** (proposed, then retracted on operator pushback): codifying "replace the assignment with `void record.start()`" as a `code-design` idiom would train reflexive lint suppression without checking the always-resolves contract.
+   The `void` is correct here but signals unfinished domain work; the lesson lives in this retro, not in the skill.
+2. **Pin a stronger model for `/ship-issue`**: an operator model-selection choice, not an `AGENTS.md`/prompt rule; noted in Diagnostic details for awareness.
+
+### Changes made
+
+1. `packages/pi-subagents/docs/retro/0374-encapsulate-subagent-start-notification.md` — added the Final Retrospective stage entry (session summary, friction points, diagnostic lenses, follow-ups); no skill or prompt edits landed (the sole proposal was retracted on operator pushback).
+
+## Stage: Regression Correction — Process Retrospective (2026-06-14T18:00:00Z)
+
+### Session summary
+
+Operator pushback on the first retro's "`void` is safe, defer it" framing surfaced that #374 had **regressed a sibling step's invariant**: Step 1 (#381) guaranteed "every spawned agent has a `promise` at spawn," and #374's `void limiter.schedule(() => record.start())` made a queued agent's promise lazy.
+Fixed via `Subagent.scheduleVia` (eager capture, control inverted so no external `.promise =` write returns) in commit `4f08c6c3` (+1 regression test, +2 unit tests; suite 981 → 982), then ran this process retrospective on how the regression slipped through plan, implementation, and review.
+
+### How the regression happened (root-cause chain)
+
+1. **Planning blind spot.**
+   The #374 plan's acceptance criterion was grep-verifiable encapsulation (`\.promise =` only in `subagent.ts`).
+   That measured the *goal* (hide the field) but never the *invariant at risk* (the field is an awaitable handle with an at-spawn timing contract that #381 established).
+   The plan treated `promise` as a field to hide, not as a contract to preserve.
+2. **Implementation masked the semantics.**
+   Converting `record.promise = limiter.schedule(...)` to a bare `limiter.schedule(() => record.start())` tripped `no-floating-promises`; the reflexive `void` fix silenced the lint *and* discarded the eager handle in the same stroke.
+   The lint fix was the exact site of the behavior change, which made it feel mechanical rather than semantic.
+3. **No executable guard.**
+   The #381 invariant lived only in an architecture-doc "Outcome:" bullet (prose).
+   No test pinned "a queued agent has a `promise` at spawn," so the full suite stayed green through the regression.
+4. **Review inherited the blind spot.**
+   The pre-completion reviewer checks deterministic gates + the plan's acceptance criteria; since the criteria never named the cross-step invariant, criteria-driven review could not flag its loss.
+
+The through-line: in a phased refactor, each step's "Outcome:" bullets establish invariants later steps inherit implicitly, and nothing converts those prose invariants into executable guards — so a later step regresses an earlier one with a green suite and a passing review.
+
+### Observations
+
+#### What caused friction (agent side)
+
+- `missing-context` — the plan did not enumerate the invariants that prior Phase 17 steps had established on the shared `Subagent`/limiter surface, so the at-spawn-promise contract was invisible during both planning and implementation.
+  Impact: a shipped regression (latent — `waitForAll` re-polls — but a real invariant break), caught only by operator pushback during the retro, requiring a follow-up `fix:`.
+- `wrong-abstraction` — the proximate trigger was treating a `void` lint fix as mechanical.
+  `void` on a promise-returning call discards whatever the promise carried (here: the eager capture handle); it deserves a semantic check, not a reflex.
+
+#### What went well
+
+- Operator pushback ("I'm sure that rule exists for a reason… are we heading toward a better design, or an awkward intermediary state?") was the single intervention that converted a rationalized smell into a found regression.
+  This is the bidirectional-feedback ideal: a redirecting question, not a correction, that reframed the agent's own analysis.
+
+### Diagnostic details
+
+- **Feedback-loop gap analysis** — every gate (check, lint, test, fallow, pre-completion review) was green across #374; none could see the regression because the invariant was prose, never a test.
+  The gap is upstream of the gates: the invariant was never made executable.
+
+### Diagnostic details — model assignment
+
+- Operator pushback also corrected a misconception: planning was assumed to run on Opus, but session turns 2–45 (`/plan-issue`) ran on `claude-sonnet-4-6`, and `.pi/prompts/plan-issue.md` had **no `model:` directive** — so planning silently inherited the session model.
+  The judgment-heaviest, highest-leverage stage (where this regression originated) was running on an inherited, weaker model by default.
+  Resolved by pinning `/plan-issue` and `/retro` to Opus via frontmatter (the `pi-prompt-template-model` extension was already loaded but unused for model selection).
+  Caveat recorded: a stronger planner raises the odds of noticing an unstated invariant but is not a substitute for the explicit rule — the rule is the dependable fix, the model is a complementary lever.
+
+### Proposals (all accepted and implemented)
+
+1. `/plan-issue` prompt — "Invariants at risk" plan section: list prior phase steps' documented invariants (roadmap `Outcome:`/`Landed:` bullets) and pin each with a named test.
+2. `code-design` skill (ESLint section) — "void on a promise-returning call" guard: before `void`-ing to silence `no-floating-promises`, confirm the discarded promise carried no semantics.
+3. `pre-completion-reviewer` agent — new section `2h. Cross-step invariant preservation`: FAIL on a regressed prior-step invariant, WARN when an invariant holds but is pinned only by prose.
+4. Model pinning — `/plan-issue` and `/retro` pinned to `anthropic/claude-opus-4-8`.
+
+### Changes made
+
+1. `packages/pi-subagents/src/lifecycle/subagent.ts` — added `scheduleVia(schedule)` (eager limiter-promise capture) and `guardedRun()` (shared abort-while-queued guard); `start()` now returns `void`.
+2. `packages/pi-subagents/src/lifecycle/subagent-manager.ts` — `spawn()` queued path uses `record.scheduleVia(...)`; removed the `void` workarounds.
+3. `packages/pi-subagents/test/lifecycle/subagent-manager.test.ts` — added regression test (queued agent has a `promise` at spawn).
+4. `packages/pi-subagents/test/lifecycle/subagent.test.ts` — rewrote `start()` tests for the `void` return; added two `scheduleVia` unit tests.
+5. `packages/pi-subagents/test/helpers/make-subagent.test.ts`, `packages/pi-subagents/test/tools/get-result-tool.test.ts` — updated for the `void`-returning `start()`.
+6. `packages/pi-subagents/docs/architecture/architecture.md` — Step 3 `Landed`/`Correction` notes record the regression and `scheduleVia` fix.
+7. `.pi/prompts/plan-issue.md` — added the "Invariants at risk" section and pinned `model: anthropic/claude-opus-4-8`.
+8. `.pi/prompts/retro.md` — pinned `model: anthropic/claude-opus-4-8`.
+9. `.pi/skills/code-design/SKILL.md` — added the "void on a promise-returning call" ESLint guard.
+10. `.pi/agents/pre-completion-reviewer.md` — added section `2h`, its output block, and severity-model entries.
+11. `AGENTS.md` — added cross-step invariant preservation to the reviewer's documented coverage.
+12. The regression fix landed in commit `4f08c6c3` (`fix:`); these retro/process changes land in the `docs(retro):` commit.

package/docs/retro/0375-extract-run-listener-workspace-bracket.md

@@ -0,0 +1,51 @@
+---
+issue: 375
+issue_title: "Extract run-listener and workspace-bracket collaborators from Subagent"
+---
+
+# Retro: #375 — Extract run-listener and workspace-bracket collaborators from Subagent
+
+## Stage: Planning (2026-06-14T19:25:00Z)
+
+### Session summary
+
+Read issue #375 (Phase 17 Step 4 — core consolidation), loaded the package, code-design, design-review, testing, colgrep, and markdown skills, and explored `subagent.ts`, `workspace.ts`, `subagent-manager.ts`, and `subagent.test.ts`.
+Produced a 4-step plan in `packages/pi-subagents/docs/plans/0375-extract-run-listener-workspace-bracket.md` extracting a `RunListeners` collaborator and a `WorkspaceBracket` collaborator out of the 488-LOC `Subagent` class.
+
+### Observations
+
+- The issue's first-cut `attach(unsub, detach)` sketch does not match the real call pattern: `wireSignal` fires at run-start and `attachObserver` after session creation, and `resume()` only attaches the observer — so `RunListeners` exposes the two attach points separately (`wireSignal` / `attachObserver` / `release`), not a single combined `attach`.
+- The issue's "three dispose paths" is really **two** `dispose()` call sites (`completeRun`, `failRun`); `run()`'s prepare-failure catch has no prepared workspace to dispose.
+- The two dispose sites have genuinely different lifecycle semantics — `completeRun` derives status from the result, folds the addendum, and lets a throw propagate; `failRun` hardcodes `"error"`, discards the addendum, and is best-effort `try/catch`.
+  Per the code-design structural-duplication heuristic, I kept them separate: `WorkspaceBracket.dispose()` centralizes the *logic* (the `if (prepared)` guard + addendum unwrap) in one place but deliberately does **not** wrap `try/catch`, so each caller's error handling is preserved line-for-line.
+  This honestly satisfies the issue's "disposal logic in exactly one place" without forcing a discriminator parameter.
+- `WorkspaceBracket` captures the provider *resolver* (`execution.getWorkspaceProvider`), not the provider, so resolution stays at run-start — matching today's `getWorkspaceProvider?.()` timing — while letting the bracket be constructed in the `Subagent` constructor (construct-complete, preserving the Step 2 invariant).
+- Per the #374 retro lesson, I added an "Invariants at risk" section: the three prior Phase 17 invariants (at-spawn `promise`, construct-complete, zero external field writes) are each already pinned by a named test and are low-risk here because this step does not touch `start`/`scheduleVia`/`_promise` or add optional init fields.
+- Step 3 (wiring) must be atomic: removing the public `wireSignal`/`attachObserver`/`releaseListeners` methods breaks `subagent.test.ts` at the type level, so the `describe`-block deletions land in the same commit.
+- Suite is at 982 tests (verified by running the suite); expect roughly +5 net (≈ −7 redundant `Subagent` listener tests, +6 each new collaborator suite).
+- First-party issue (author `gotgenes` == gh user) with an unambiguous proposed change, so the `ask-user` gate was skipped.
+- Commit types are `test:`/`refactor:`/`docs:` — internal-only, no release-please bump; release cadence is a ship-time decision flagged in Risks.
+
+## Stage: Implementation — TDD (2026-06-14T21:40:00Z)
+
+### Session summary
+
+Implemented all 4 plan steps in 4 commits (2 `refactor:`, 1 additional `refactor:` for the wiring step, 1 `docs:`).
+Test count went from 982 to 994 (+12: 7 `RunListeners` tests + 13 `WorkspaceBracket` tests − 8 redundant `Subagent` listener tests removed).
+`subagent.ts` landed at 448 LOC (target was ≤ 450).
+Pre-completion reviewer returned WARN (2 non-blocking findings; the doc metric rows were fixed inline before committing).
+
+### Observations
+
+- **Microtask-boundary deviation from plan**: the plan showed `const cwd = await this.workspaceBracket.prepare(...)` unconditionally in `run()`.
+  `async` functions always create a microtask boundary even when they return immediately (no-provider path), which broke `subagent-manager.test.ts`'s synchronous assertion that `factory.toHaveBeenCalledOnce()` — the factory call had been deferred to the next microtask tick.
+  Fix: added `WorkspaceBracket.hasProvider()` (a synchronous provider-existence check) and guarded the `await` with `if (this.workspaceBracket.hasProvider())`, restoring the original timing semantics.
+  The `hasProvider()` method is a mild Tell-Don't-Ask trade-off (the caller queries bracket state to decide whether to call it), documented at the call site and noted as a WARN by the pre-completion reviewer.
+  The underlying cause: `SubagentManager.spawn()` always injects `getWorkspaceProvider: () => this._workspaceProvider` as a function, even when no provider is registered, so the naïve `if (this.execution.getWorkspaceProvider)` guard was always true.
+- **Step 3 collapsed into one commit as expected**: removing `wireSignal`/`attachObserver`/`releaseListeners` from `Subagent` broke `subagent.test.ts` at the type level; the redundant `describe` block deletions and the production wiring landed atomically.
+- **LOC target met**: `subagent.ts` went from 488 → 448 (plan estimated ≤ 450; actual 448).
+  The gap between estimated removal (≈ 40 lines) and actual (40 lines) was closed by trimming the stale module-level doc comment and redundant field-level comments.
+- **Prior-step invariants held**: all three Phase 17 cross-step invariants (at-spawn `promise`, construct-complete, zero external field writes) passed grep-verification and the 994-test suite confirms no regressions.
+- **Pre-completion reviewer WARN findings** (both addressed inline):
+  1. `architecture.md` health-metric rows still carried "→ 59 after Step 4" annotations after landing — updated to actual counts (60 files, 8,356 LOC) and the docs commit amended.
+  2. `WorkspaceBracket.hasProvider()` TDA trade-off — documented in the `run()` call-site comment; noted here for Phase 18 awareness.

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.1",
   "type": "module",
   "exports": {
     ".": {

package/src/lifecycle/run-listeners.ts

@@ -0,0 +1,37 @@
+/**
+ * run-listeners.ts — Per-run observer-unsubscribe and signal-detach handles.
+ *
+ * Owns the two teardown handles that a Subagent wires at run start (signal
+ * listener) and after session creation (record-observer unsub), releasing
+ * both atomically when the run ends or the agent is resumed.
+ */
+
+/** Owns the per-run observer-unsubscribe and signal-detach handles. */
+export class RunListeners {
+	private unsub?: () => void;
+	private detach?: () => void;
+
+	/**
+	 * Wire a parent AbortSignal so it triggers onAbort when fired.
+	 * No-op when signal is undefined.
+	 */
+	wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
+		if (!signal) return;
+		const listener = () => onAbort();
+		signal.addEventListener("abort", listener, { once: true });
+		this.detach = () => signal.removeEventListener("abort", listener);
+	}
+
+	/** Store the record-observer unsubscribe handle. */
+	attachObserver(unsub: () => void): void {
+		this.unsub = unsub;
+	}
+
+	/** Release the observer + signal handles. Idempotent. */
+	release(): void {
+		this.unsub?.();
+		this.unsub = undefined;
+		this.detach?.();
+		this.detach = undefined;
+	}
+}