@gotgenes/pi-subagents 11.1.0 → 11.3.0

package/docs/retro/0256-extract-worktree-isolation.md

@@ -0,0 +1,45 @@
+---
+issue: 256
+issue_title: "Extract WorktreeIsolation collaborator"
+---
+
+# Retro: #256 — Extract WorktreeIsolation collaborator
+
+## Stage: Planning (2026-05-28T23:44:23Z)
+
+### Session summary
+
+Produced a numbered implementation plan for extracting a `WorktreeIsolation` collaborator (Phase 16, Step 1) that owns the worktree lifecycle (`setup`, `path`, `cleanup`) so `Agent` tells one collaborator instead of orchestrating `_worktrees` + `_isolation` + `worktreeState` itself.
+The plan covers the new module, `Agent`/`AgentManager`/`service-adapter` wiring, the `WorktreeState` deletion, doc updates, and a 4-cycle TDD order.
+
+### Observations
+
+- Decision: fold `WorktreeState` into `WorktreeIsolation` (delete `worktree-state.ts`) rather than wrap it.
+  The architecture target table already lists `WorktreeIsolation` as absorbing `worktrees` + `isolation` + `worktreeState`, and the user confirmed a fold preference when the doc had already decided it.
+- `WorktreeManager.cleanup(wt, ...)` mutates `wt.branch` in place; `WorktreeIsolation` must store a mutable `WorktreeInfo` (`_info`) to preserve that behavior — flagged as the top risk.
+- `AgentInit` net field change is −1 (removes `worktrees` + `isolation`, adds `worktree`), not −2 as the issue text loosely states; instance fields drop by 2 and `setupWorktree()` is removed.
+- The `missing worktrees dependency` defensive branch becomes structurally impossible (collaborator is only built with a manager) and is dropped.
+- Verified no consumer imports the `WorktreeCleanupResult`/`WorktreeInfo` re-exports from `worktree-state.ts` — they all import from `worktree.ts`, so deletion is safe.
+- Step 2 (the integration) is a single commit because the type checker forbids removing `AgentInit` fields while call sites still pass them; bulk of `agent.test.ts` is untouched, only worktree helpers/describe blocks change.
+- Doc updates needed: architecture class diagram + layout listing, and the package `SKILL.md` Lifecycle domain row (module count stays 9).
+- This step is independent of Step 2 (#257, `ChildSessionFactory`) per the architecture's Track A.
+
+## Stage: Implementation — TDD (2026-05-29T00:01:54Z)
+
+### Session summary
+
+Implemented all 4 planned TDD cycles: added `WorktreeIsolation` + unit tests, wired it into `Agent`/`AgentManager`/`service-adapter` (removing `_worktrees`/`_isolation`/`worktreeState`/`setupWorktree()`), deleted the folded `WorktreeState` class and its test, and updated the architecture doc + package skill.
+Full suite green at 1047 tests (baseline 1053; +7 new `worktree-isolation` tests, −4 removed `setupWorktree` tests, −9 removed `worktree-state` tests); `check`, `lint`, and `fallow dead-code` all clean.
+
+### Observations
+
+- One pre-existing baseline failure: `rumdl` flagged 5 orphaned issue link definitions (`[#227]`–`[#232]`, minus the still-used `[#231]`) in `architecture.md`, introduced by an earlier Phase 15 archive commit.
+  Fixed as a separate `docs:` cleanup commit before starting TDD to establish a green baseline.
+- Deviation from a literal 1:1 test mapping: `WorktreeIsolation` deliberately exposes `path` + `cleanupResult` but no `branch` getter (branch is an internal `_info` detail surfaced via `cleanupResult`).
+  The two `agent-manager.test.ts` tests that asserted `worktreeState.branch` now assert `record.worktree?.path` and `record.worktree?.cleanupResult`.
+  Noted in the Step 2 commit body.
+- `Agent.worktree` is `readonly` (set at construction), unlike the old mutable public `worktreeState` field.
+  Tests that previously mutated `record.worktreeState = new WorktreeState(...)` after construction were reworked to pass a pre-`setup()` `WorktreeIsolation` via the constructor (`createSetUpWorktree` helper in `agent.test.ts`; `setUpWorktree` helper in `service-adapter.test.ts`).
+- `createTestAgent` spreads `init` into the `Agent` constructor, so injecting `worktree` needed no helper change.
+- The Step 2 integration landed cleanly in a single commit as the plan predicted; the type checker pinpointed every stale call site.
+- Pre-completion reviewer: PASS (all deterministic checks, acceptance criteria, conventional commits, docs, code design, test artifacts, Mermaid, and dead-code gates green).

package/package.json

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

package/src/lifecycle/agent-manager.ts

@@ -14,8 +14,8 @@ import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
+import { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 
-import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
@@ -130,12 +130,14 @@ export class AgentManager {
       maxTurns: options.maxTurns,
       isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
-      isolation: options.isolation,
       parentSession: options.parentSession,
       signal: options.signal,
       // Shared deps
       runner: this.runner,
-      worktrees: this.worktrees,
+      worktree:
+        options.isolation === "worktree"
+          ? new WorktreeIsolation(this.worktrees, id)
+          : undefined,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
     });
@@ -173,34 +175,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

@@ -11,7 +11,10 @@
  * Behavior (abort, steer buffering, worktree setup) lives on the agent
  * rather than on AgentManager — each agent manages its own lifecycle concerns.
  *
- * Phase-specific collaborators (execution, worktreeState, notification) are attached
+ * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
+ * (set at construction when isolation is requested); its presence IS the mode.
+ *
+ * Phase-specific collaborators (execution, notification) are attached
  * after construction as lifecycle information becomes available.
  */
 
@@ -23,12 +26,11 @@ import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
-import type { WorktreeManager } from "#src/lifecycle/worktree";
-import { WorktreeState } from "#src/lifecycle/worktree-state";
+import type { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Per-agent lifecycle observer — created by AgentManager for each spawn. */
 export interface AgentLifecycleObserver {
@@ -67,7 +69,7 @@ export interface AgentInit {
 
 	// Shared deps (required for run(), optional for tests)
 	runner?: AgentRunner;
-	worktrees?: WorktreeManager;
+	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 
@@ -78,7 +80,6 @@ export interface AgentInit {
 	maxTurns?: number;
 	isolated?: boolean;
 	thinkingLevel?: ThinkingLevel;
-	isolation?: IsolationMode;
 	parentSession?: ParentSessionInfo;
 	isBackground?: boolean;
 	signal?: AbortSignal;
@@ -124,7 +125,8 @@ export class Agent {
 
 	// Shared deps — optional (required for run())
 	private readonly _runner?: AgentRunner;
-	private readonly _worktrees?: WorktreeManager;
+	/** Worktree isolation collaborator — present only when isolation: "worktree". */
+	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 
@@ -135,37 +137,13 @@ export class Agent {
 	private readonly _maxTurns?: number;
 	private readonly _isolated?: boolean;
 	private readonly _thinkingLevel?: ThinkingLevel;
-	private readonly _isolation?: IsolationMode;
 	private readonly _parentSession?: ParentSessionInfo;
 	private readonly _signal?: AbortSignal;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
-	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
-	/**
-	 * Create a git worktree for isolated execution, set worktreeState, and return the worktree path.
-	 * Returns undefined if isolation is not "worktree".
-	 * Throws if worktree creation fails (strict isolation).
-	 * Uses this._worktrees and this._isolation (set at construction).
-	 */
-	setupWorktree(): string | undefined {
-		if (this._isolation !== "worktree") return undefined;
-		if (!this._worktrees) {
-			throw new Error("Agent not configured for worktree isolation — missing worktrees dependency");
-		}
-		const wt = this._worktrees.create(this.id);
-		if (!wt) {
-			throw new Error(
-				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-				'Initialize git and commit at least once, or omit `isolation`.',
-			);
-		}
-		this.worktreeState = new WorktreeState(wt);
-		return wt.path;
-	}
-
 	// Steer buffer — messages queued before the session is ready
 	private _pendingSteers: string[] = [];
 	/** Number of steer messages waiting to be delivered. */
@@ -205,7 +183,7 @@ export class Agent {
 
 		// Shared deps
 		this._runner = init.runner;
-		this._worktrees = init.worktrees;
+		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 
@@ -216,7 +194,6 @@ export class Agent {
 		this._maxTurns = init.maxTurns;
 		this._isolated = init.isolated;
 		this._thinkingLevel = init.thinkingLevel;
-		this._isolation = init.isolation;
 		this._parentSession = init.parentSession;
 		this._signal = init.signal;
 
@@ -247,9 +224,10 @@ export class Agent {
 		this.wireSignal(this._signal, () => this.abort());
 
 		try {
-			this.setupWorktree();
+			this.worktree?.setup();
 		} catch (err) {
 			this.markError(err);
+			this.releaseListeners();
 			this.observer?.onRunFinished?.(this);
 			return;
 		}
@@ -258,7 +236,7 @@ export class Agent {
 		try {
 			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
 				context: {
-					cwd: this.worktreeState?.path,
+					cwd: this.worktree?.path,
 					parentSession: this._parentSession,
 				},
 				model: this._model,
@@ -285,6 +263,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++;
@@ -431,11 +442,9 @@ export class Agent {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		if (this.worktreeState && this._worktrees) {
-			const wtResult = this.worktreeState.performCleanup(this._worktrees, this.description);
-			if (wtResult.hasChanges && wtResult.branch) {
-				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-			}
+		const wtResult = this.worktree?.cleanup(this.description);
+		if (wtResult?.hasChanges && wtResult.branch) {
+			finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
 		}
 
 		if (result.aborted) this.markAborted(finalResult);
@@ -455,11 +464,9 @@ export class Agent {
 		this.markError(err);
 		this.releaseListeners();
 
-		if (this.worktreeState && this._worktrees) {
-			try {
-				this.worktreeState.performCleanup(this._worktrees, this.description);
-			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
-		}
+		try {
+			this.worktree?.cleanup(this.description);
+		} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
 
 		this.observer?.onRunFinished?.(this);
 	}

package/src/lifecycle/worktree-isolation.ts

@@ -0,0 +1,59 @@
+/**
+ * worktree-isolation.ts — WorktreeIsolation: collaborator that owns the
+ * git-worktree lifecycle for an isolated agent.
+ *
+ * Constructed by AgentManager only when isolation === "worktree", bound to a
+ * WorktreeManager and the agent id. Agent tells it `setup()` and
+ * `cleanup(description)` instead of managing worktree internals itself.
+ *
+ * The presence/absence of this collaborator IS the isolation mode: Agent calls
+ * `this.worktree?.setup()` rather than checking an isolation string.
+ */
+
+import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
+
+export class WorktreeIsolation {
+	private _info?: WorktreeInfo;
+	private _cleanupResult?: WorktreeCleanupResult;
+
+	constructor(
+		private readonly worktrees: WorktreeManager,
+		private readonly agentId: string,
+	) {}
+
+	/** Absolute worktree path — undefined before setup(). */
+	get path(): string | undefined {
+		return this._info?.path;
+	}
+
+	/** Cleanup outcome — undefined until cleanup() runs. */
+	get cleanupResult(): WorktreeCleanupResult | undefined {
+		return this._cleanupResult;
+	}
+
+	/**
+	 * Create the git worktree and store its info.
+	 * Throws on failure (strict isolation — no silent fallback).
+	 */
+	setup(): void {
+		const wt = this.worktrees.create(this.agentId);
+		if (!wt) {
+			throw new Error(
+				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+					"Initialize git and commit at least once, or omit `isolation`.",
+			);
+		}
+		this._info = wt;
+	}
+
+	/**
+	 * Perform worktree cleanup and record the result.
+	 * No-op returning { hasChanges: false } if setup never ran.
+	 */
+	cleanup(description: string): WorktreeCleanupResult {
+		if (!this._info) return { hasChanges: false };
+		const result = this.worktrees.cleanup(this._info, description);
+		this._cleanupResult = result;
+		return result;
+	}
+}

package/src/service/service-adapter.ts

@@ -128,7 +128,7 @@ export function toSubagentRecord(record: Agent): SubagentRecord {
   if (record.result !== undefined) out.result = record.result;
   if (record.error !== undefined) out.error = record.error;
   if (record.completedAt !== undefined) out.completedAt = record.completedAt;
-  const worktreeResult = record.worktreeState?.cleanupResult;
+  const worktreeResult = record.worktree?.cleanupResult;
   if (worktreeResult !== undefined) out.worktreeResult = worktreeResult;
 
   return out;

package/src/lifecycle/worktree-state.ts

@@ -1,45 +0,0 @@
-/**
- * worktree-state.ts — WorktreeState: lifecycle-phase object for worktree-isolated agents.
- *
- * Constructed once when the worktree is set up (before the run begins).
- * Only exists for agents with isolation: "worktree".
- * cleanupResult is recorded once at completion or error — it is not set at construction.
- */
-
-import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
-
-export type { WorktreeCleanupResult, WorktreeInfo };
-
-export class WorktreeState {
-	/** Absolute path to the worktree directory. */
-	readonly path: string;
-	/** Branch name created for this worktree. */
-	readonly branch: string;
-
-	private _cleanupResult?: WorktreeCleanupResult;
-
-	constructor(info: WorktreeInfo) {
-		this.path = info.path;
-		this.branch = info.branch;
-	}
-
-	/** Result of the worktree cleanup — undefined until recordCleanup is called. */
-	get cleanupResult(): WorktreeCleanupResult | undefined {
-		return this._cleanupResult;
-	}
-
-	/** Record the cleanup result. Called once on agent completion or error. */
-	recordCleanup(result: WorktreeCleanupResult): void {
-		this._cleanupResult = result;
-	}
-
-	/**
-	 * Perform worktree cleanup and record the result.
-	 * Tell-Don't-Ask: callers no longer need to orchestrate cleanup + recordCleanup separately.
-	 */
-	performCleanup(worktrees: WorktreeManager, description: string): WorktreeCleanupResult {
-		const result = worktrees.cleanup(this, description);
-		this._cleanupResult = result;
-		return result;
-	}
-}