@gotgenes/pi-subagents 16.2.0 → 16.2.1

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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.0...pi-subagents-v16.2.1) (2026-06-15)
+
+
+### Bug Fixes
+
+* restore at-spawn promise for queued subagents ([#374](https://github.com/gotgenes/pi-packages/issues/374)) ([4f08c6c](https://github.com/gotgenes/pi-packages/commit/4f08c6c37814b5386a23cd60479efc39c4b22612))
+
 ## [16.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.1.1...pi-subagents-v16.2.0) (2026-06-14)
 
 

package/docs/architecture/architecture.md

@@ -130,9 +130,6 @@ classDiagram
         +completeRun(result)
         +failRun(err)
         +disposeSession()
-        +wireSignal(signal, onAbort)
-        +attachObserver(unsub)
-        +releaseListeners()
     }
 
     class SubagentState {
@@ -309,8 +306,10 @@ src/
 │   ├── create-subagent-session.ts  assembly factory: session creation, binding, tool filtering
 │   ├── subagent-session.ts         born-complete child session: turn loop, steer, dispose
 │   ├── turn-limits.ts              normalizeMaxTurns (turn-count policy)
-│   ├── subagent.ts                 owns full execution lifecycle (run, abort, steer, workspace)
+│   ├── subagent.ts                 owns full execution lifecycle (run, abort, steer)
 │   ├── subagent-state.ts           lifecycle status + metrics value object (transitions, accumulators)
+│   ├── run-listeners.ts            per-run observer-unsub and signal-detach handles
+│   ├── workspace-bracket.ts        child workspace prepare/dispose lifecycle
 │   ├── concurrency-limiter.ts       background admission gate: schedules run thunks FIFO against the limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
@@ -644,17 +643,17 @@ That method — testability friction as a boundary probe, with its limits — is
 
 ### Health metrics
 
-| Metric                     | Value                             |
-| -------------------------- | --------------------------------- |
-| Health score               | 78/100 (B)                        |
-| Total LOC                  | 7,778 (57 files)                  |
-| Dead code                  | 0 files, 0 exports                |
-| Maintainability index      | 90.8 (good)                       |
-| Avg cyclomatic complexity  | 1.4                               |
-| P90 cyclomatic complexity  | 2                                 |
-| Production duplication     | 11 lines (1 internal clone group) |
-| Test duplication           | 42 clone groups, 661 lines        |
-| Fallow refactoring targets | 0                                 |
+| Metric                     | Value                                   |
+| -------------------------- | --------------------------------------- |
+| Health score               | 78/100 (B)                              |
+| Total LOC                  | 8,356 (60 files, as of Phase 17 Step 4) |
+| Dead code                  | 0 files, 0 exports                      |
+| Maintainability index      | 90.8 (good)                             |
+| Avg cyclomatic complexity  | 1.4                                     |
+| P90 cyclomatic complexity  | 2                                       |
+| Production duplication     | 11 lines (1 internal clone group)       |
+| Test duplication           | 42 clone groups, 661 lines              |
+| Fallow refactoring targets | 0                                       |
 
 ### Dependency bag inventory
 
@@ -894,7 +893,7 @@ Updated health metrics (fallow, package-wide including tests):
 | Metric                     | Phase 16 baseline              | Current                                       |
 | -------------------------- | ------------------------------ | --------------------------------------------- |
 | Health score               | 78/100 (B)                     | 78/100 (B)                                    |
-| Source LOC                 | 7,778 (57 files)               | ~7,400 (57 files)                             |
+| Source LOC                 | 7,778 (57 files)               | 8,356 (60 files, landed Phase 17 Step 4)      |
 | Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
 | Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
 | Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
@@ -966,14 +965,21 @@ Priority = Impact × (6 − Risk).
 - 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.
+- Landed: `Subagent.start()` (immediate path) and `Subagent.scheduleVia(schedule)` (queued path) own the promise and the shared `guardedRun()` status guard; `SubagentManager.spawn()` calls one or the other; `TestSubagentOptions.toolCallId` wires notification state via the constructor path.
+- Correction (post-merge): the first cut used `void this.limiter.schedule(() => record.start())`, which left a queued agent's `promise` unset until its slot opened — silently regressing Step 1's "every spawned agent has a `promise` at spawn" invariant.
+  Fixed by inverting control: `scheduleVia` captures the limiter promise eagerly inside the agent (no external `.promise =` write), restoring the invariant.
+  Lesson: a step's acceptance criteria must include the cross-step invariants it could regress, not only its own grep-verifiable outcome.
 
 #### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
 
 - 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.
+- Change: extract a `RunListeners` object owning the observer-unsubscribe and signal-detach handles (`wireSignal`/`attachObserver`/`release`), and a `WorkspaceBracket` collaborator owning prepare/dispose-with-addendum, centralising the dispose logic.
 - Outcome: `subagent.ts` ≤ 450 LOC; workspace disposal logic in exactly one place; listener handles no longer raw nullable fields.
+- Landed: `RunListeners` (`src/lifecycle/run-listeners.ts`) owns the signal-detach and observer-unsub handles with a single `release()` call; `WorkspaceBracket` (`src/lifecycle/workspace-bracket.ts`) owns prepare-at-run-start and dispose-with-addendum — `completeRun` and `failRun` call `workspaceBracket.dispose(outcome)` and receive the addendum string (or `""`) without reaching through to the workspace object directly.
+  `Subagent.wireSignal`, `attachObserver`, and `releaseListeners` are removed.
+  `subagent.ts`: 488 → 448 LOC.
+  Test count: 982 → 994 (+12: 7 RunListeners + 13 WorkspaceBracket − 8 redundant Subagent listener tests).
 
 #### Step 5 — Extract the manager observer from index.ts into a class ([#376])
 

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

@@ -36,3 +36,136 @@ Pre-completion reviewer returned PASS with one WARN (stale test count in `packag
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.2.0",
+  "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;
+	}
+}

package/src/lifecycle/subagent-manager.ts

@@ -168,12 +168,14 @@ export class SubagentManager {
     }
 
     if (options.isBackground && !options.bypassQueue) {
-      // Schedule on the limiter — start() guards against abort-while-queued.
-      void this.limiter.schedule(() => record.start());
+      // Schedule on the limiter — scheduleVia captures the limiter promise
+      // eagerly, so a queued agent is awaitable from spawn; guardedRun guards
+      // against abort-while-queued when the slot frees.
+      record.scheduleVia((thunk) => this.limiter.schedule(thunk));
       return id;
     }
 
-    void record.start();
+    record.start();
     return id;
   }
 

package/src/lifecycle/subagent.ts

@@ -1,21 +1,9 @@
 /**
- * subagent.ts — Subagent class with encapsulated status-transition logic and per-subagent behavior.
+ * subagent.ts — Subagent class: identity, lifecycle status, and per-subagent behavior.
  *
- * Status transitions (status, result, error, startedAt, completedAt) are owned
- * by the class and exposed via transition methods. External code reads these
- * fields through public properties but cannot write them directly.
- *
- * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
- * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
- *
- * Behavior (abort, steer buffering) lives on the subagent rather than on
- * SubagentManager — each subagent manages its own lifecycle concerns.
- *
- * The child's working directory is supplied by a registered WorkspaceProvider
- * (the workspace seam); with no provider the child runs in the parent cwd.
- *
- * Phase-specific collaborators (subagentSession, notification) are attached
- * after construction as lifecycle information becomes available.
+ * Status/stats are delegated to the SubagentState value object; listener
+ * lifecycle to RunListeners; workspace prepare/dispose to WorkspaceBracket.
+ * Behavior (abort, steer buffering) lives here rather than on SubagentManager.
  */
 
 import type { Model } from "@earendil-works/pi-ai";
@@ -23,10 +11,12 @@ import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { RunListeners } from "#src/lifecycle/run-listeners";
 import type { SubagentSession, TurnLoopResult } from "#src/lifecycle/subagent-session";
 import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
-import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
@@ -105,23 +95,16 @@ export class Subagent {
 	get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
 	get compactionCount(): number { return this.state.compactionCount; }
 
-	/** AbortController for cancelling this agent. Created at construction. */
 	readonly abortController: AbortController;
-	/** 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;
-	/** Workspace prepared at run-start by a provider — undefined when none is registered. */
-	private _workspace?: Workspace;
+	private readonly listeners = new RunListeners();
+	private readonly workspaceBracket: WorkspaceBracket;
 
-	// 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;
 	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
@@ -191,6 +174,11 @@ export class Subagent {
 		// Execution machinery — a single mandatory collaborator
 		this.execution = init.execution;
 
+		// Per-run lifecycle collaborators
+		this.workspaceBracket = new WorkspaceBracket(
+			this.execution.getWorkspaceProvider ?? (() => undefined),
+		);
+
 		// Notification state — created from parentSession.toolCallId if present
 		const toolCallId = init.execution.parentSession?.toolCallId;
 		if (toolCallId) {
@@ -210,27 +198,26 @@ export class Subagent {
 	async run(): Promise<void> {
 		this.markRunning(Date.now());
 		this.execution.observer?.onStarted?.(this);
-		this.wireSignal(this.execution.signal, () => this.abort());
+		this.listeners.wireSignal(this.execution.signal, () => this.abort());
 
+		// Guard the await so the no-provider path stays synchronous, preserving
+		// the original run() timing: the factory is called in the same turn as
+		// spawn() when no workspace provider is registered.
 		let cwd: string | undefined;
-		try {
-			// A registered workspace provider supplies the child's cwd and owns its
-			// teardown; with no provider the child runs in the parent cwd.
-			const provider = this.execution.getWorkspaceProvider?.();
-			if (provider) {
-				this._workspace = await provider.prepare({
+		if (this.workspaceBracket.hasProvider()) {
+			try {
+				cwd = await this.workspaceBracket.prepare({
 					agentId: this.id,
 					agentType: this.type,
 					baseCwd: this.execution.baseCwd,
 					invocation: this.invocation,
 				});
-				cwd = this._workspace?.cwd;
+			} catch (err) {
+				this.markError(err);
+				this.listeners.release();
+				this.execution.observer?.onRunFinished?.(this);
+				return;
 			}
-		} catch (err) {
-			this.markError(err);
-			this.releaseListeners();
-			this.execution.observer?.onRunFinished?.(this);
-			return;
 		}
 
 		try {
@@ -249,7 +236,7 @@ export class Subagent {
 		}
 
 		this.flushPendingSteers();
-		this.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
+		this.listeners.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
 			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 		this.execution.observer?.onSessionCreated?.(this);
@@ -269,19 +256,32 @@ 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 execution immediately (foreground / bypassQueue paths).
+	 * Stores the run promise so it is awaitable via the `promise` getter.
 	 */
-	start(): Promise<void> {
-		if (this.status !== "queued" && this.status !== "running") {
-			this._promise = Promise.resolve();
-			return this._promise;
-		}
-		this._promise = this.run();
-		return this._promise;
+	start(): void {
+		this._promise = this.guardedRun();
+	}
+
+	/**
+	 * Schedule execution through an external concurrency scheduler (the limiter).
+	 * Captures the scheduler's promise eagerly, so a still-queued agent is
+	 * awaitable via the `promise` getter from spawn — not only once its slot opens.
+	 * The guard in guardedRun() makes an abort-while-queued run a no-op when the
+	 * slot finally frees.
+	 */
+	scheduleVia(schedule: (thunk: () => Promise<void>) => Promise<void>): void {
+		this._promise = schedule(() => this.guardedRun());
+	}
+
+	/**
+	 * Run unless the agent left the active set before its slot opened
+	 * (e.g. abort-while-queued): a non-queued, non-running status resolves
+	 * immediately without running.
+	 */
+	private guardedRun(): Promise<void> {
+		if (this.status !== "queued" && this.status !== "running") return Promise.resolve();
+		return this.run();
 	}
 
 	/**
@@ -300,7 +300,7 @@ export class Subagent {
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
+		this.listeners.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
 			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 
@@ -310,7 +310,7 @@ export class Subagent {
 		} catch (err) {
 			this.markError(err);
 		} finally {
-			this.releaseListeners();
+			this.listeners.release();
 		}
 	}
 
@@ -406,48 +406,21 @@ export class Subagent {
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
 	resetForResume(startedAt: number): void {
 		this.state.resetForResume(startedAt);
-		this.releaseListeners();
-	}
-
-	// --- Per-run listener state (released on completion or resume reset) ---
-	private _unsub?: () => void;
-	private _detachFn?: () => void;
-
-	/** Wire a parent AbortSignal so it stops this agent when fired. */
-	wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
-		if (!signal) return;
-		const listener = () => onAbort();
-		signal.addEventListener("abort", listener, { once: true });
-		this._detachFn = () => signal.removeEventListener("abort", listener);
-	}
-
-	/** Store the record-observer unsubscribe handle. */
-	attachObserver(unsub: () => void): void {
-		this._unsub = unsub;
-	}
-
-	/** Release observer + signal listener handles. */
-	releaseListeners(): void {
-		this._unsub?.();
-		this._unsub = undefined;
-		this._detachFn?.();
-		this._detachFn = undefined;
+		this.listeners.release();
 	}
 
 	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
 	completeRun(result: TurnLoopResult): void {
-		this.releaseListeners();
-
-		let finalResult = result.responseText;
-		if (this._workspace) {
-			const finalStatus: SubagentStatus = result.aborted
-				? "aborted"
-				: result.steered
-					? "steered"
-					: "completed";
-			const disposeResult = this._workspace.dispose({ status: finalStatus, description: this.description });
-			if (disposeResult?.resultAddendum) finalResult += disposeResult.resultAddendum;
-		}
+		this.listeners.release();
+
+		const finalStatus: SubagentStatus = result.aborted
+			? "aborted"
+			: result.steered
+				? "steered"
+				: "completed";
+		const finalResult =
+			result.responseText +
+			this.workspaceBracket.dispose({ status: finalStatus, description: this.description });
 
 		if (result.aborted) this.markAborted(finalResult);
 		else if (result.steered) this.markSteered(finalResult);
@@ -464,10 +437,10 @@ export class Subagent {
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);
-		this.releaseListeners();
+		this.listeners.release();
 
 		try {
-			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
+			this.workspaceBracket.dispose({ status: "error", description: this.description });
 		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
 		this.execution.observer?.onRunFinished?.(this);

package/src/lifecycle/workspace-bracket.ts

@@ -0,0 +1,59 @@
+/**
+ * workspace-bracket.ts — Owned prepare/dispose lifecycle for a child workspace.
+ *
+ * Captures the provider resolver (not the provider itself) so provider
+ * resolution stays lazy at run-start. The prepared Workspace is held
+ * privately; dispose() centralises the guard and addendum-unwrap so callers
+ * never reach through to workspace.dispose().resultAddendum directly.
+ *
+ * dispose() deliberately does NOT catch errors — the best-effort try/catch
+ * for failRun() belongs at the call site, preserving the per-caller semantics.
+ */
+
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+/** Owns the child workspace lifecycle: prepare at run-start, dispose at run-end. */
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/**
+	 * Returns true when a workspace provider is currently registered.
+	 * Use to guard the `await prepare(...)` call and avoid an unnecessary
+	 * microtask boundary in the no-provider path.
+	 */
+	hasProvider(): boolean {
+		return this.resolveProvider() !== undefined;
+	}
+
+	/**
+	 * Resolve the registered provider and prepare the child workspace.
+	 * Returns the workspace's cwd, or undefined when no provider is registered
+	 * or the provider resolves to undefined.
+	 */
+	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) and return the result addendum
+	 * verbatim. Returns an empty string when no workspace was prepared or when
+	 * the workspace returns no addendum.
+	 *
+	 * Throws propagate — wrap in try/catch at the call site when best-effort
+	 * disposal is desired (e.g. failRun).
+	 */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		if (!this.prepared) return "";
+		return this.prepared.dispose(outcome)?.resultAddendum ?? "";
+	}
+}