@gotgenes/pi-subagents 18.0.1 → 18.0.2

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

@@ -1,250 +0,0 @@
----
-issue: 373
-issue_title: "Extract SubagentState; make Subagent execution deps mandatory"
----
-
-# Extract `SubagentState`; make `Subagent` execution deps mandatory
-
-## Problem Statement
-
-`Subagent` is simultaneously a passive record and an executor.
-Its `SubagentInit` carries ~20 fields — nearly all optional with "required for `run()`, optional for tests" semantics — and `run()` compensates with two runtime guards that throw `"Subagent not configured for execution"`.
-This violates the construct-complete principle: one class is both a display-only snapshot (tests and the UI read `.status`/`.result`/stats) and an executor (production wires the session factory, observer, run config, and workspace provider).
-
-The earlier framing — split `SubagentInit` into a present-or-absent `SubagentRunSpec` + `SubagentExecutionDeps` pair — only *type-encodes* the duality; it does not remove it.
-The stronger move (captured in the architecture doc's "First-principles refinement") observes that the passive-record need is *test-only*: production constructs a `Subagent` in exactly one place (`SubagentManager.spawn`), always fully wired.
-So the readable state is the common denominator (extract it as a value object), and the execution deps are the optional-only-for-tests part (make them mandatory; push the passive case into the test factory).
-
-## Goals
-
-- Extract `SubagentState` — a value object owning status, result, error, timestamps, and stats (`toolUses`, `lifetimeUsage`, `compactionCount`) plus their transition (`markRunning`, `markCompleted`, …) and accumulation (`incrementToolUses`, `addUsage`, `incrementCompactions`) methods.
-- `Subagent` holds one `SubagentState` privately; its existing getters and `markX`/`incrementX`/`addUsage` methods become one-line delegations, leaving the ~40 read sites and the external mutation callers (`markStopped` in the manager, `markCompleted` in `get-result-tool.test.ts`) unchanged.
-- Collapse the ~12 remaining execution inputs into a single **mandatory** `SubagentExecution` collaborator; `SubagentManager.spawn` always supplies it.
-- Delete the two `"not configured for execution"` throws in `run()` — impossible by construction.
-- Move the passive-record construction entirely into `test/helpers/make-subagent.ts`.
-- Retarget `subscribeSubagentObserver` at `SubagentState` so state-machine and observer tests need no stub execution.
-
-This change is **not breaking** for the published service surface.
-`src/service/service.ts` exposes `SubagentRecord`, `SubagentStatus`, and the spawn-config types — not `SubagentInit` or the `Subagent` constructor.
-The read API (getters, `SubagentStatus`) is unchanged; only the internal constructor signature changes.
-
-## Non-Goals
-
-- Hoisting **metrics** (tool uses, token usage, compaction count) into a projection over the child session's event stream — stats stay on `SubagentState` for now (the third of four domains in the refinement, deferred).
-- Extracting **result delivery** (`notification` / `resultConsumed`) into its own domain — the fourth domain, deferred.
-- Encapsulating run start / making `promise` and `notification` read-only — that is Step 3 (#374); `notification` stays created in the constructor here.
-- Extracting run-listener / workspace-bracket collaborators — Step 4 (#375).
-- Renaming `record-observer.ts` — only its parameter type changes.
-
-## Background
-
-- `src/lifecycle/subagent.ts` — the class under change.
-  State fields (`_status`, `_result`, `_error`, `_startedAt`, `_completedAt`, `_toolUses`, `_lifetimeUsage`, `_compactionCount`) sit behind getters; transition/accumulation methods mutate them.
-  `run()` reads the execution inputs and throws if `createSubagentSession`/`snapshot`/`prompt` are missing.
-  `resume()` reads `observer` and throws only on a missing session (a genuine runtime condition — kept).
-- `src/lifecycle/subagent-manager.ts` — `spawn()` (line ~139) is the **only** production `new Subagent(...)` site; it sets the initial status (`queued` for background so the limiter thunk's `status !== "queued"` guard works, `running` for foreground).
-- `src/observation/record-observer.ts` — `subscribeSubagentObserver(session, record, { onCompact })` calls `record.incrementToolUses()`, `record.addUsage(…)`, `record.incrementCompactions()`, and forwards `onCompact(record, info)`.
-- `src/lifecycle/usage.ts` — `LifetimeUsage` type and the `addUsage(into, delta)` accumulator that `SubagentState` will own.
-- `test/helpers/make-subagent.ts` — `createTestSubagent` builds passive records; stat shorthands apply via mutation methods.
-- `test/lifecycle/subagent.test.ts` (~700 LOC) and `test/observation/record-observer.test.ts` — the test files that construct `Subagent` directly.
-
-AGENTS.md / code-design constraints that apply:
-
-- Keep Pi SDK imports out of `SubagentState` — it is a pure value object (imports only `LifetimeUsage`/`addUsage`).
-- `Subagent` is exported from the `types.ts` barrel; verify the barrel re-export still resolves after the file split.
-- `SubagentStatus` is re-exported by `src/service/service.ts` from `#src/lifecycle/subagent` — keep that import path valid (re-export `SubagentStatus` from `subagent.ts` even if its definition moves to `subagent-state.ts`), so the public type bundle path is unchanged.
-
-## Design Overview
-
-### `SubagentState` value object (`src/lifecycle/subagent-state.ts`)
-
-A pure, independently constructible value object. `SubagentStatus` moves here (its natural home) and is re-exported from `subagent.ts`.
-
-```ts
-export type SubagentStatus =
-	| "queued" | "running" | "completed" | "steered"
-	| "aborted" | "stopped" | "error";
-
-export interface SubagentStateInit {
-	status?: SubagentStatus;
-	result?: string;
-	error?: string;
-	startedAt?: number;
-	completedAt?: number;
-	// stats always start at zero; callers accumulate via mutation methods
-}
-
-export class SubagentState {
-	constructor(init?: SubagentStateInit); // status ?? "queued", startedAt ?? Date.now()
-	// getters: status, result, error, startedAt, completedAt,
-	//          toolUses, lifetimeUsage (Readonly), compactionCount
-	// transitions: markRunning, markCompleted, markAborted, markSteered,
-	//              markError, markStopped, resetForResume
-	// accumulators: incrementToolUses, addUsage, incrementCompactions
-}
-```
-
-It owns its mutations (no output arguments — methods write only its own private fields) and carries no upstream dependency beyond `usage.ts`.
-
-### `SubagentExecution` collaborator (in `src/lifecycle/subagent.ts`)
-
-```ts
-export interface SubagentExecution {
-	createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
-	snapshot: ParentSnapshot;
-	prompt: string;
-	baseCwd: string;
-	observer?: SubagentLifecycleObserver;
-	getRunConfig?: () => RunConfig;
-	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
-	model?: Model<any>;
-	maxTurns?: number;
-	thinkingLevel?: ThinkingLevel;
-	parentSession?: ParentSessionInfo;
-	signal?: AbortSignal;
-}
-```
-
-The four fields the old `run()` guards required (`createSubagentSession`, `snapshot`, `prompt`, plus `baseCwd`) are mandatory; the genuinely-optional behavior knobs stay optional.
-
-### `Subagent` constructor
-
-```ts
-export interface SubagentInit {
-	id: string;
-	type: SubagentType;
-	description: string;
-	invocation?: AgentInvocation;
-	execution: SubagentExecution;   // mandatory — no more "optional for tests"
-	state?: SubagentState;          // defaults to new SubagentState() (fresh "queued")
-}
-```
-
-`SubagentInit` drops from ~20 fields to 5.
-`Subagent` keeps `id`/`type`/`description`/`invocation`, `abortController`, `subagentSession?`, `notification?`, steer buffer, and per-run listener handles; it holds `private readonly state` and `private readonly execution`.
-Getters and mutation methods delegate one line to `this.state`.
-`notification` is still created in the constructor from `execution.parentSession?.toolCallId` (Step 3 moves it).
-
-### Consumer call site — `SubagentManager.spawn`
-
-```ts
-const execution: SubagentExecution = {
-	createSubagentSession: this.createSubagentSession,
-	snapshot, prompt, baseCwd: this.baseCwd,
-	observer: this.buildObserver(options),
-	getRunConfig: this.getRunConfig,
-	getWorkspaceProvider: () => this._workspaceProvider,
-	model: options.model, maxTurns: options.maxTurns,
-	thinkingLevel: options.thinkingLevel,
-	parentSession: options.parentSession, signal: options.signal,
-};
-const record = new Subagent({
-	id, type, description: options.description, invocation: options.invocation,
-	execution,
-	state: new SubagentState({ status: options.isBackground ? "queued" : "running", startedAt: Date.now() }),
-});
-```
-
-Tell-Don't-Ask: the execution bundle is assembled once and handed over; nothing reaches back into `spawn`'s locals afterward.
-
-### Observer retarget (`src/observation/record-observer.ts`)
-
-The observer accumulates *stats*, not lifecycle — point it at `SubagentState` and drop the record from `onCompact`:
-
-```ts
-export function subscribeSubagentObserver(
-	session: SubscribableSession,
-	state: SubagentState,
-	options?: { onCompact?: (info: CompactionInfo) => void },
-): () => void
-```
-
-`Subagent.run()`/`resume()` wire it with `this.state` and close over `this` to forward itself to the lifecycle observer:
-
-```ts
-this.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
-	onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
-}));
-```
-
-This removes the observer's only dependency on `Subagent`, so observer tests construct a `SubagentState` directly.
-`SubagentLifecycleObserver.onCompacted(agent, info)` is unchanged — it still receives the `Subagent`.
-
-Decision: the observer takes `SubagentState` concretely rather than a one-off narrow `incrementToolUses`/`addUsage`/`incrementCompactions` interface.
-`SubagentState` is a cohesive owned value object, not a wide dependency bag, and a single internal call site does not justify a speculative interface (recorded in Open Questions).
-
-### Edge cases
-
-- **Initial status for the limiter guard** — production passes `state: new SubagentState({ status: queued|running })`; the background path still observes `queued` so `limiter.schedule(() => record.status !== "queued" ? … : record.run())` behaves identically.
-- **`resume()` without a prior run** — the `"not configured for resume — missing session"` throw stays; it guards a genuine runtime state (no session was ever created), not a construction concern.
-- **`make-subagent.ts` passive records** — built as `state: new SubagentState({ status: "completed", result, startedAt, completedAt })` plus a `makeStubExecution()`; stat shorthands keep delegating through `Subagent`'s methods.
-
-## Module-Level Changes
-
-- **`src/lifecycle/subagent-state.ts`** (new) — `SubagentState`, `SubagentStateInit`, and the `SubagentStatus` type (moved from `subagent.ts`).
-- **`src/lifecycle/subagent.ts`** —
-  - Re-export `SubagentStatus` from `subagent-state.ts` (keeps service.ts import path valid).
-  - Add `SubagentExecution`; rewrite `SubagentInit` to the 5-field shape; remove the flat execution/run-config fields.
-  - Remove the (unused) `isBackground?` field from `SubagentInit` — never read in this class.
-  - Hold `private readonly state` / `private readonly execution`; convert getters and `markX`/`incrementX`/`addUsage`/`resetForResume` to delegations.
-  - `run()`: delete the two `"not configured for execution"` throws; read inputs from `this.execution`; wire the observer at `this.state`.
-  - `resume()`: read `observer` from `this.execution`; keep the missing-session throw.
-- **`src/lifecycle/subagent-manager.ts`** — `spawn()` builds the `SubagentExecution` bundle and the initial `SubagentState`; no other change (`markStopped` calls untouched).
-- **`src/observation/record-observer.ts`** — param `record: Subagent` → `state: SubagentState`; `onCompact` signature `(record, info)` → `(info)`; update the JSDoc bullet wording.
-- **`test/helpers/make-subagent.ts`** — add `makeStubExecution()`; build the passive record via `state` + `execution`.
-- **`test/lifecycle/subagent.test.ts`** — funnel constructions through a local helper (prep refactor); move the pure state-machine `describe` blocks to the new state test; supply `execution` everywhere; update the missing-factory test (the throw is gone — replace with a type-level/construction assertion or remove).
-- **`test/lifecycle/subagent-state.test.ts`** (new) — state-machine + accumulation tests targeting `SubagentState` directly.
-- **`test/observation/record-observer.test.ts`** — `makeRecord` → build a `SubagentState`; assert stats on it; `onCompact` test uses `(info)`.
-- **Docs** —
-  - `docs/architecture/architecture.md`: add `subagent-state.ts` to the lifecycle directory listing; update the `Subagent` class diagram (state delegations, new collaborators); mark **Step 2 ✅ Complete**; refresh the Phase 17 problem-statement prose (line ~879) and the type-complexity table (`SubagentInit` row at line ~649, add `SubagentExecution`).
-  - `.pi/skills/package-pi-subagents/SKILL.md`: Lifecycle domain `10 → 11` modules (add `subagent-state.ts`); total `56 → 57` files.
-
-Grep sweep confirmed no other `src/`, `test/`, or `SKILL.md` references to the removed flat fields or the `"not configured for execution"` string outside `subagent.ts`.
-
-## Test Impact Analysis
-
-1. **New tests the extraction enables** — `test/lifecycle/subagent-state.test.ts` exercises every transition and accumulator on `SubagentState` with no `Subagent`, no execution stub, no session.
-   This is the construct-complete payoff: the state machine is now unit-testable in isolation.
-2. **Tests that become redundant** — the state-machine `describe` blocks in `subagent.test.ts` (`markRunning`, `markCompleted`, `markAborted`, `markSteered`, `markError`, `markStopped`, `incrementToolUses`, `addUsage`, `incrementCompactions`, `resetForResume`, and the pure constructor-defaults cases) move out, leaving `subagent.test.ts` to cover identity, session-encapsulation delegation, abort, `run()`/`resume()`, `completeRun`/`failRun`, and listeners.
-   `record-observer.test.ts` no longer constructs a `Subagent` — it builds a `SubagentState`.
-3. **Tests that must stay as-is** — `run()`/`resume()` integration tests genuinely exercise the executor (factory wiring, observer lifecycle, workspace bracket); the `createTestSubagent` consumers across `test/ui/` and `test/tools/` exercise read sites and are unaffected (the helper absorbs the construction change).
-
-## TDD Order
-
-1. **Extract `SubagentState` (pure addition; lift-and-shift prep).**
-   - Create `src/lifecycle/subagent-state.ts` and `test/lifecycle/subagent-state.test.ts` (red → green for every transition/accumulator).
-   - Refactor `Subagent` to hold a `SubagentState` built from the *existing* `SubagentInit` fields; getters/mutators delegate. `SubagentStatus` moves to `subagent-state.ts`, re-exported from `subagent.ts`.
-   - In `subagent.test.ts`, introduce a local construction helper and route call sites through it; move the pure state-machine `describe` blocks into `subagent-state.test.ts`.
-   - No consumer breaks (init shape unchanged). `pnpm run check` + `test`.
-   - Commit: `refactor: extract SubagentState value object (#373)`.
-2. **Retarget the observer at `SubagentState`.**
-   - Change `subscribeSubagentObserver` to accept `SubagentState` and an `onCompact(info)`; update the two `subagent.ts` call sites (pass `this.state`, close over `this`).
-   - Rewrite `record-observer.test.ts` to build a `SubagentState`.
-   - Commit: `refactor: target SubagentState in subagent observer (#373)`.
-3. **Make execution mandatory (the atomic construction flip).**
-   - Add `SubagentExecution`; rewrite `SubagentInit` to the 5-field shape; remove flat execution/run-config fields and `isBackground?`; delete the two `run()` throws; read from `this.execution`.
-   - Update the single production site (`subagent-manager.ts spawn`) and `make-subagent.ts` (`makeStubExecution` + `state`) and the `subagent.test.ts` helper/`createRunnableAgent`/`createResumableAgent` in the **same commit** — removing the optional fields breaks every construction at the type level simultaneously.
-   - Adjust the now-obsolete "missing session factory" test (throw is gone).
-   - `pnpm run check`, `lint`, `test`, `fallow dead-code`.
-   - Commit: `refactor: make Subagent execution deps mandatory (#373)`.
-4. **Docs.**
-   - Update `architecture.md` (file listing, class diagram, mark Step 2 complete, prose, type table) and `SKILL.md` (domain counts).
-   - Commit: `docs: record SubagentState extraction in architecture and skill (#373)`.
-
-Optionally run `pnpm run verify:public-types` after Step 3 to confirm the public bundle is unaffected (expected: no change — the bundle does not reference `SubagentInit`).
-
-## Risks and Mitigations
-
-- **Large test file churn (`subagent.test.ts`, ~700 LOC).**
-  Mitigated by lift-and-shift: Step 1 funnels constructions through a local helper and moves state tests out, so Step 3's mandatory-execution flip edits the helper + two run/resume factories rather than rewriting the file.
-- **Initial-status regression for the limiter.**
-  Production explicitly sets `state` status in `spawn`; a `subagent-manager` test should assert a background spawn reports `queued` before its slot opens (existing coverage; re-verify).
-- **`SubagentStatus` re-export path.**
-  Keep `SubagentStatus` re-exported from `subagent.ts`; `verify:public-types` (and `pnpm run check`) confirm `service.ts` still resolves it.
-- **Circular import (`subagent.ts` ↔ `subagent-state.ts`).**
-  Avoided: `subagent-state.ts` defines `SubagentStatus` and imports nothing from `subagent.ts`; `subagent.ts` imports `SubagentState`/`SubagentStatus` from `subagent-state.ts`.
-
-## Open Questions
-
-- Whether the observer should accept a narrow `{ incrementToolUses; addUsage; incrementCompactions }` interface instead of `SubagentState` concretely — deferred; revisit if a second consumer of the stats sink appears (defer-until-needed, per the metrics-projection work in a later phase).
-- Whether the `make-subagent.ts` stat shorthands should construct `SubagentState` directly rather than delegating through `Subagent` — cosmetic; left until Step 7's fixture consolidation (#378).

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

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