@gotgenes/pi-subagents 11.1.0 → 11.2.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [11.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.1.0...pi-subagents-v11.2.0) (2026-05-28)
+
+
+### Features
+
+* add Agent.resume() with internal observer lifecycle ([6cffb47](https://github.com/gotgenes/pi-packages/commit/6cffb47079e385b0ccd12e358c12357291be2ef0))
+
+
+### Bug Fixes
+
+* release abort-signal listener when worktree setup fails ([ce2cac6](https://github.com/gotgenes/pi-packages/commit/ce2cac6788ffc90316f759e40e4df29576a70128))
+
 ## [11.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.0.1...pi-subagents-v11.1.0) (2026-05-28)
 
 

package/docs/architecture/architecture.md

@@ -121,6 +121,8 @@ classDiagram
         +markError()
         +markStopped()
         +resetForResume()
+        +run()
+        +resume(prompt, signal)
         +abort(): boolean
         +queueSteer(message)
         +flushPendingSteers(session)
@@ -136,7 +138,7 @@ classDiagram
     class AgentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
-        +resume(id, snapshot, exec)
+        +resume(id, prompt, signal)
         +getRecord(id): Agent
         +listAgents(): Agent[]
         +abort(id)
@@ -738,15 +740,15 @@ The scheduling concern (queue, concurrency counter, drain) is tangled into `Agen
 
 ### Findings summary
 
-| Finding                                                            | Category     | Impact | Risk | Priority |
-| ------------------------------------------------------------------ | ------------ | ------ | ---- | -------- |
-| ~~`AgentRecord` is anemic — no behavior, manager reaches in 37×~~  | B: Oversized | 5      | 3    | ✅       |
-| Agent cannot run itself — manager orchestrates 10 external touches | C: Coupling  | 5      | 3    | 15       |
-| Scheduling tangled into `AgentManager` (3 fields, 3 methods)       | A: Coupling  | 4      | 2    | 12       |
-| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~  | C: Callbacks | 3      | 2    | ✅       |
-| ~~`onSessionCreated` callback flows through 3 layers~~             | C: Callbacks | 3      | 2    | subsumed |
-| `resume()` duplicates observer subscribe/unsubscribe pattern       | A: Redundant | 2      | 1    | 8        |
-| `exec`/`registry` relay-only deps on `AgentManager`                | C: Coupling  | 2      | 1    | 6        |
+| Finding                                                                | Category     | Impact | Risk | Priority |
+| ---------------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
+| ~~`AgentRecord` is anemic — no behavior, manager reaches in 37×~~      | B: Oversized | 5      | 3    | ✅       |
+| ~~Agent cannot run itself — manager orchestrates 10 external touches~~ | C: Coupling  | 5      | 3    | ✅       |
+| ~~Scheduling tangled into `AgentManager` (3 fields, 3 methods)~~       | A: Coupling  | 4      | 2    | ✅       |
+| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~      | C: Callbacks | 3      | 2    | ✅       |
+| ~~`onSessionCreated` callback flows through 3 layers~~                 | C: Callbacks | 3      | 2    | subsumed |
+| ~~`resume()` duplicates observer subscribe/unsubscribe pattern~~       | A: Redundant | 2      | 1    | ✅       |
+| ~~`exec`/`registry` relay-only deps on `AgentManager`~~                | C: Coupling  | 2      | 1    | ✅       |
 
 ### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
 
@@ -812,7 +814,7 @@ Drain calls `agent.run()` directly — no worktree setup, no args threading.
 - Smell: A (tangled concerns) + C (cross-concern leak via `notifyConcurrencyChanged`)
 - Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable; queue interface is trivial (agent has everything)
 
-### Step 6: Agent.resume() with internal observer lifecycle — [#232]
+### Step 6: Agent.resume() with internal observer lifecycle — [#232] ✅
 
 Agent has the runner from construction.
 `Agent.resume(prompt, signal)` manages its own observer subscription lifecycle using the same internal wiring as `run()`.

package/docs/plans/0232-agent-resume-internal-observer-lifecycle.md

@@ -0,0 +1,180 @@
+---
+issue: 232
+issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
+---
+
+# Agent.resume() with internal observer lifecycle
+
+## Problem Statement
+
+After #229 (`Agent.run()` absorbs `startAgent`), the agent owns its entire run lifecycle but `AgentManager.resume()` still duplicates the observer subscribe/use/release pattern that `run()` handles internally.
+The manager manually calls `subscribeAgentObserver`, wraps `runner.resume()` in a try/catch/finally, marks completion/error, and unsubscribes — the same acquire → use → release resource shape `Agent.run()` already encapsulates.
+This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (priority 8, smell A: redundant pattern).
+
+## Goals
+
+- Add `Agent.resume(prompt, signal?)` that owns its observer subscription lifecycle, mirroring `run()`'s internal wiring.
+- Reduce `AgentManager.resume()` to a guard-plus-delegation method (no `subscribeAgentObserver`, no try/finally).
+- Preserve the existing public contract of `AgentManager.resume()` exactly: same signature, same `Agent | undefined` return, same behavior when the record or session is missing.
+- Keep the change non-breaking (`feat:`, not `feat!:`).
+
+## Non-Goals
+
+- No change to `runner.resume()` / `resumeAgent()` in `agent-runner.ts`.
+- No change to the abort semantics of resume — the parent `signal` continues to flow straight through to `runner.resume({ signal })` (resume does not route through the agent's `abortController`, matching today's behavior).
+- No queue interaction on resume — resume is not subject to the concurrency queue, so `onStarted`/`onRunFinished` are not fired (unchanged from today).
+- No full rewrite of the stale `AgentManager`/`Agent` class diagram in `architecture.md` — that diagram already diverged in #229 (missing `run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures); a comprehensive diagram refresh is out of scope here.
+
+## Background
+
+Relevant modules (all under `packages/pi-subagents/src/`):
+
+- `lifecycle/agent.ts` — the `Agent` class.
+  Already owns the per-run listener state (`_unsub`, `_detachFn`), the `attachObserver(unsub)` / `releaseListeners()` pair, `resetForResume(startedAt)` (which calls `releaseListeners()`), and `markCompleted` / `markError`.
+  Holds `_runner` and `observer` (an `AgentLifecycleObserver`) from construction (#229).
+  `Agent.run()` is the template to follow: it wires the observer via `attachObserver(subscribeAgentObserver(session, this, { onCompact: (r, info) => this.observer?.onCompacted?.(r, info) }))`.
+- `lifecycle/agent-manager.ts` — `AgentManager.resume()` currently does the manual subscribe/try-finally dance and imports `subscribeAgentObserver` solely for that.
+- `observation/record-observer.ts` — `subscribeAgentObserver(session, record, options)` returns an unsubscribe function; observes `tool_execution_end`, `message_end`, `compaction_end`.
+- `lifecycle/agent-runner.ts` — `AgentRunner.resume(session, prompt, options?)` returns `Promise<string>` (the response text).
+
+Constraint from AGENTS.md / `package-pi-subagents` skill: pi-subagents is a narrow core; this is a pure internal refactor (Tell-Don't-Ask, "state owns its mutations") with no policy or API-surface change.
+
+### Observer routing equivalence
+
+The manager's old resume wired compaction to the `AgentManagerObserver`:
+
+```typescript
+subscribeAgentObserver(session, record, {
+  onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+});
+```
+
+`Agent.resume()` instead routes through the per-agent `AgentLifecycleObserver` (`this.observer?.onCompacted?.`), exactly as `run()` does.
+That lifecycle observer is built by `AgentManager.buildObserver()`, whose `onCompacted` forwards to `this.observer?.onAgentCompacted(agent, info)`.
+Net routing is identical — compaction events still reach the manager-level `AgentManagerObserver.onAgentCompacted`.
+
+## Design Overview
+
+### `Agent.resume()`
+
+```typescript
+async resume(prompt: string, signal?: AbortSignal): Promise<void> {
+  if (!this._runner) {
+    throw new Error("Agent not configured for execution — missing runner");
+  }
+  const session = this.session;
+  if (!session) {
+    throw new Error("Agent not configured for resume — missing session");
+  }
+
+  this.resetForResume(Date.now()); // sets running, clears result/error, releases stale listeners
+  this.attachObserver(subscribeAgentObserver(session, this, {
+    onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+  }));
+
+  try {
+    const responseText = await this._runner.resume(session, prompt, { signal });
+    this.markCompleted(responseText);
+  } catch (err) {
+    this.markError(err);
+  } finally {
+    this.releaseListeners();
+  }
+}
+```
+
+Decision model:
+
+- `resetForResume()` already calls `releaseListeners()`, so any leftover handle from a prior run/resume is cleared before the new subscription is attached.
+- The new subscription handle is stored via `attachObserver()` (reusing the `_unsub` slot shared with `run()`), and released in `finally` via `releaseListeners()`.
+- Errors are captured (`markError`) rather than rethrown — `resume()` resolves like `run()`.
+- The two guards (missing runner, missing session) mirror `run()`'s guard style.
+  They are defensive: the manager guards `agent?.session` before delegating, so the session guard is unreachable in normal flow but protects the invariant for direct `Agent.resume()` callers/tests.
+
+### `AgentManager.resume()` (delegation)
+
+```typescript
+async resume(id: string, prompt: string, signal?: AbortSignal): Promise<Agent | undefined> {
+  const agent = this.agents.get(id);
+  if (!agent?.session) return undefined;
+  await agent.resume(prompt, signal);
+  return agent;
+}
+```
+
+Edge cases preserved:
+
+- Missing record → `undefined` (no throw).
+- Record present but no session → `undefined` (no throw).
+- Session present → delegate, return the agent.
+
+After this change `agent-manager.ts` no longer references `subscribeAgentObserver` — that import must be removed.
+`this.runner` is still used by `spawn()` (passed to the `Agent` constructor), so the `runner` field stays.
+
+## Module-Level Changes
+
+- `src/lifecycle/agent.ts`
+  - Add the public async method `resume(prompt: string, signal?: AbortSignal): Promise<void>` (placed near `run()` per the stepdown rule).
+  - No new imports — `subscribeAgentObserver` is already imported for `run()`.
+- `src/lifecycle/agent-manager.ts`
+  - Replace the body of `resume()` with the guard-plus-delegation form above.
+  - Remove the now-unused `import { subscribeAgentObserver } from "#src/observation/record-observer";`.
+  - No other methods change.
+- `src/lifecycle/agent-runner.ts` — unchanged.
+- `src/observation/record-observer.ts` — unchanged.
+- `docs/architecture/architecture.md` — light doc touch:
+  - In the class diagram, update `AgentManager.resume(id, snapshot, exec)` → `resume(id, prompt, signal)` and add `Agent.resume(prompt, signal)` (and, while there, `Agent.run()`, which #229 omitted).
+  - Mark Step 6 in the Phase 15 roadmap table/section as complete (`✅`).
+  - Note: the class diagram has pre-existing staleness from #229; this touch only corrects the resume-related entries, not the whole diagram.
+
+Symbol-removal check: the only removed symbol is the `subscribeAgentObserver` import in `agent-manager.ts`.
+`grep` confirms `subscribeAgentObserver` is still imported and used in `agent.ts` and defined in `record-observer.ts`, so the export stays live.
+
+No file in Module-Level Changes is claimed unchanged in Non-Goals (the Non-Goals list `agent-runner.ts` and `record-observer.ts`, which are genuinely untouched).
+
+## Test Impact Analysis
+
+This is an extraction/relocation of behavior from the manager into the agent.
+
+1. New unit tests enabled — `Agent.resume()` can now be tested directly on `Agent` (file `test/lifecycle/agent.test.ts`), which was previously impossible because resume logic lived only in the manager.
+   New direct coverage:
+   - `resume()` transitions to `completed` and sets `result` from the runner's response text.
+   - `resume()` transitions to `error` (and does not throw) when `runner.resume()` rejects.
+   - `resume()` subscribes the record-observer to the session (usage/compaction events accumulate on the agent) and releases the subscription in `finally` (handle cleared after completion and after error).
+   - `resume()` throws on missing runner / missing session (guard symmetry with `run()`).
+   - Compaction during resume forwards through `this.observer?.onCompacted?.`.
+
+2. Existing tests that become redundant — none should be deleted.
+   The two manager-level resume tests in `test/lifecycle/agent-manager.test.ts` (`resume() also accumulates usage and increments compactions on the same record` and `calls injected runner.resume when resuming an agent`) now exercise the delegation + observer-forwarding integration rather than the inlined logic.
+   They stay as integration coverage of `AgentManager.resume()` → `Agent.resume()` and the `onCompacted` → `onAgentCompacted` routing.
+   `test/helpers/make-deps.test.ts` (calls `manager.resume(...)`) stays.
+
+3. Existing tests that must stay as-is — the manager-level resume tests above genuinely exercise the manager's guard + delegation seam and the observer routing through `buildObserver`, which the agent-level tests do not cover.
+
+## TDD Order
+
+1. `test/lifecycle/agent.test.ts` — add `Agent.resume()` happy-path + error + guard tests, then implement `Agent.resume()` in `agent.ts`.
+   Covers: completed/result on success, error (no throw) on rejection, observer subscribe + `releaseListeners()` in `finally`, compaction forwarding via `onCompacted`, and the missing-runner / missing-session guards.
+   At this point both the new `Agent.resume()` and the old `AgentManager.resume()` body coexist (lift-and-shift: introduce the new method alongside the old logic).
+   Commit: `feat: add Agent.resume() with internal observer lifecycle`
+2. `test/lifecycle/agent-manager.test.ts` — keep the existing resume tests green, then collapse `AgentManager.resume()` to the guard-plus-delegation form and remove the unused `subscribeAgentObserver` import in the same commit.
+   Removing the import and rewriting the body must land together — the type checker flags the unused import immediately, and the existing manager-level resume tests verify the delegation still satisfies the same contract.
+   Commit: `refactor: delegate AgentManager.resume() to Agent.resume()`
+3. `docs/architecture/architecture.md` — update the class diagram resume entries (and add `Agent.run()`/`Agent.resume()`), mark Step 6 complete.
+   Commit: `docs: mark Phase 15 Step 6 (Agent.resume) complete`
+
+## Risks and Mitigations
+
+- Risk: observer routing diverges (compaction events stop reaching `onAgentCompacted`).
+  Mitigation: the existing manager-level test `resume() also accumulates usage and increments compactions on the same record` asserts `compactionCount` after resume; it stays green only if routing is preserved.
+- Risk: listener leak if `releaseListeners()` is missed on the error path.
+  Mitigation: `releaseListeners()` is in `finally`; a dedicated agent-level test asserts the unsub handle is released after both success and error.
+- Risk: behavior change in abort handling if resume is rerouted through `abortController`.
+  Mitigation: explicitly keep `signal` flowing straight to `runner.resume({ signal })` (Non-Goal), identical to today.
+- Risk: removing the `subscribeAgentObserver` import while another caller still needs it.
+  Mitigation: `grep` confirms `agent.ts` is the only other importer and `record-observer.ts` still exports it.
+
+## Open Questions
+
+- Whether to later refresh the full `AgentManager`/`Agent` class diagram in `architecture.md` (stale since #229).
+  Deferred — out of scope for this issue; a focused follow-up can resync the whole diagram.

package/docs/retro/0232-agent-resume-internal-observer-lifecycle.md

@@ -0,0 +1,45 @@
+---
+issue: 232
+issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
+---
+
+# Retro: #232 — Agent.resume() with internal observer lifecycle (Phase 15, Step 6)
+
+## Stage: Planning (2026-05-28T18:00:00Z)
+
+### Session summary
+
+Produced a 3-step plan to move the observer subscribe/use/release pattern out of `AgentManager.resume()` into a new `Agent.resume(prompt, signal?)`, mirroring the `run()` wiring added in #229.
+This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (Step 6, priority 8).
+Confirmed the prerequisite #229 is closed and `Agent` already holds `_runner`, `observer`, `attachObserver`/`releaseListeners`, and `resetForResume`.
+
+### Observations
+
+- Non-breaking (`feat:`) — `AgentManager.resume()` keeps its signature and `Agent | undefined` contract; `Agent.resume()` is additive.
+  No `ask_user` needed; the issue's proposed change is concrete and unambiguous.
+- Observer routing equivalence verified: old code wired `onCompact` → `AgentManagerObserver.onAgentCompacted`; new code routes through the per-agent `AgentLifecycleObserver.onCompacted`, which `buildObserver()` forwards to `onAgentCompacted`.
+  Net routing identical.
+- Abort semantics intentionally preserved — `signal` flows straight to `runner.resume({ signal })`, not through the agent's `abortController` (resume differs from `run()` here; flagged as a Non-Goal to avoid accidental behavior change).
+- Removing the `subscribeAgentObserver` import from `agent-manager.ts` must land in the same commit as the body rewrite (type checker flags the unused import). `grep` confirmed `agent.ts` remains the importer and `record-observer.ts` keeps the export live.
+- Discovered the `architecture.md` class diagram is stale from #229 (missing `Agent.run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures, old `resume(id, snapshot, exec)`).
+  Scoped only a light touch (resume-related entries + Step 6 ✅); full diagram refresh deferred as a follow-up.
+- Lift-and-shift TDD order: step 1 introduces `Agent.resume()` alongside the old manager logic; step 2 collapses the manager method and removes the import together.
+  Existing manager-level resume tests act as the integration safety net and stay.
+
+## Stage: Implementation — TDD (2026-05-28T19:00:00Z)
+
+### Session summary
+
+Completed all 3 TDD steps in 3 commits plus a bonus `fix:` commit, totalling 4 new commits.
+`Agent.resume()` added with full observer lifecycle, `AgentManager.resume()` collapsed to guard-plus-delegation, `subscribeAgentObserver` import removed from `agent-manager.ts`, and `architecture.md` updated.
+Test count: 1042 → 1053 (+11).
+
+### Observations
+
+- **Bonus fix found mid-session:** A user question revealed a listener leak introduced in #229 — `Agent.run()` called `wireSignal()` before `setupWorktree()`, but the worktree-failure catch block returned without `releaseListeners()`, leaving the parent `AbortSignal` holding a reference to the errored agent.
+  Fixed TDD-style: failing test first (`"releases the parent-signal listener when worktree setup fails"` in `agent.test.ts`), then one-line fix adding `this.releaseListeners()` to the catch block in `run()`.
+  Committed as a separate `fix:` commit with a body attributing the regression to #229.
+- **Pre-completion reviewer: WARN** — one non-blocking finding: the Phase 15 findings-summary table in `architecture.md` didn't mark the resolved rows (consistent pre-existing pattern from #229–#231).
+  Fixed by adding strikethrough + ✅ to all four resolved finding rows (#229 "Agent cannot run itself", #230 "Scheduling", #231 "exec/registry", #232 "resume()") in an additional `docs:` commit.
+  All other reviewer checks passed (Mermaid diagrams validated with `mmdc`, fallow clean, code design clean).
+- **Reviewer warning resolved:** The findings table gap was pre-existing across four issues; closing it in this commit makes the table accurate going into Phase 16.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-manager.ts

@@ -15,7 +15,6 @@ import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 
-import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
@@ -173,34 +172,17 @@ export class AgentManager {
 
   /**
    * Resume an existing agent session with a new prompt.
+   * Delegates to Agent.resume(), which owns the observer subscription lifecycle.
    */
   async resume(
     id: string,
     prompt: string,
     signal?: AbortSignal,
   ): Promise<Agent | undefined> {
-    const record = this.agents.get(id);
-    const session = record?.session;
-    if (!session) return undefined;
-
-    record.resetForResume(Date.now());
-
-    const unsubResume = subscribeAgentObserver(session, record, {
-      onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-    });
-
-    try {
-      const responseText = await this.runner.resume(session, prompt, {
-        signal,
-      });
-      record.markCompleted(responseText);
-    } catch (err) {
-      record.markError(err);
-    } finally {
-      unsubResume();
-    }
-
-    return record;
+    const agent = this.agents.get(id);
+    if (!agent?.session) return undefined;
+    await agent.resume(prompt, signal);
+    return agent;
   }
 
   getRecord(id: string): Agent | undefined {

package/src/lifecycle/agent.ts

@@ -250,6 +250,7 @@ export class Agent {
 			this.setupWorktree();
 		} catch (err) {
 			this.markError(err);
+			this.releaseListeners();
 			this.observer?.onRunFinished?.(this);
 			return;
 		}
@@ -285,6 +286,39 @@ export class Agent {
 		}
 	}
 
+	/**
+	 * Resume an existing session with a new prompt, managing the observer
+	 * subscription lifecycle internally (same wiring as run()).
+	 *
+	 * Requires runner and an existing session (set when the original run created it).
+	 * The returned promise always resolves (errors are captured internally).
+	 * The parent signal flows straight through to runner.resume — resume does not
+	 * route through this.abortController.
+	 */
+	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
+		if (!this._runner) {
+			throw new Error("Agent not configured for execution — missing runner");
+		}
+		const session = this.session;
+		if (!session) {
+			throw new Error("Agent not configured for resume — missing session");
+		}
+
+		this.resetForResume(Date.now());
+		this.attachObserver(subscribeAgentObserver(session, this, {
+			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		}));
+
+		try {
+			const responseText = await this._runner.resume(session, prompt, { signal });
+			this.markCompleted(responseText);
+		} catch (err) {
+			this.markError(err);
+		} finally {
+			this.releaseListeners();
+		}
+	}
+
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
 	incrementToolUses(): void {
 		this._toolUses++;