@gotgenes/pi-subagents 13.0.0 → 13.1.0

package/docs/retro/0264-remove-extension-lifecycle-control.md

@@ -46,3 +46,44 @@ Test count went 1016 → 951 (−65): deleted `skill-loader.test.ts` and `safe-f
 - The `spawn-config.test.ts` `agentInvocation` snapshot carried a stale `isolation: undefined` leftover (from the #263 worktree eviction) that `toEqual` had been silently ignoring; removed it alongside `isolated: false` for a clean exact-match assertion.
 - `verify:public-types` confirmed the breaking `SpawnOptions.isolated` removal type-checks against an external consumer; no lockfile changes; `dist/` correctly gitignored after the type-bundle build.
 - Pre-completion reviewer: **PASS** — both acceptance criteria code-verified, all deterministic checks green, 6 Mermaid diagrams render, docs accurate, zero dead code.
+
+## Stage: Final Retrospective (2026-05-30T01:13:26Z)
+
+### Session summary
+
+Shipped #264 end-to-end across three stages (Planning → TDD → Ship) in one conversation: planned the four-cycle removal, implemented it as three `feat!:` commits plus docs, and released `pi-subagents-v13.0.0` via the release-please PR (#276).
+The run had zero rework and a PASS pre-completion review; test count moved 1016 → 951.
+
+### Observations
+
+#### What went well
+
+- The planning-stage `ask-user` gate caught a real scope trap before any code was written.
+  The issue named three fields (`isolated`, `extensions: false`, `noSkills`), but `noSkills` turned out to be the single mechanism behind **two** skill-restriction modes (skill-disable and `skills: string[]` preload).
+  Removing it while keeping `AgentConfig.skills` would have left a field that silently stops restricting — a mid-cycle-3 wall.
+  Catching it at planning time expanded the clean scope to four collapsing fields and produced a symmetric, reviewable plan.
+- The four-cycle split (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) held with no cross-cycle dangling references, validating the lift-and-shift discipline for shared-interface removal.
+- Verification ran incrementally (`pnpm run check` + `pnpm run test` after every cycle), so each commit landed green; the only end-of-run surprise was a pre-commit `end-of-file-fixer` hook touching `custom-agents.ts` (handled with a re-add, no rework).
+
+#### What caused friction (agent side)
+
+- `other` (tooling) — BSD `sed` on macOS does not support `\|` alternation in basic regex; the first bulk fixture-deletion attempt silently matched nothing.
+  Impact: one wasted tool call, no rework; resolved by switching to `sed -E`.
+
+#### What caused friction (user side)
+
+- The opening sequencing question ("is there work that should precede this") was first read literally as a prerequisite check (#261/#262/#263), and the user had to rephrase to get at the within-issue sequencing point that surfaced the `noSkills`/`skills` coupling.
+  Opportunity, not criticism: offering both readings of an ambiguous "what comes first" question up front would have reached the valuable discovery one turn sooner.
+
+#### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`, 325s, 43 tool uses) on a judgment-heavy review task; appropriate assignment.
+  No Explore/Plan subagents were needed — planning-stage exploration was direct file reads and targeted greps, efficient for this removal's scope.
+- **Escalation-delay tracking** — no rabbit-holes; the `sed` issue resolved in one retry.
+- **Feedback-loop gap analysis** — no gap; `check`/`test`/`lint` ran after each cycle, with `fallow dead-code` and `verify:public-types` at the end.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
+2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
+   No prompt or `AGENTS.md` changes were made this retro.

package/docs/retro/0265-born-complete-subagent-session.md

@@ -0,0 +1,58 @@
+---
+issue: 265
+issue_title: "Born-complete child execution; dissolve the runner"
+---
+
+# Retro: #265 — Born-complete child execution; dissolve the runner
+
+## Stage: Planning (2026-05-30T02:30:00Z)
+
+### Session summary
+
+Produced the implementation plan for dissolving the `agent-runner` and introducing a born-complete `SubagentSession`.
+Most of the session was a design dialogue that resolved naming, the turn-loop home, a discovered Law-of-Demeter cluster, and the workspace-ownership fork before any plan text was written.
+Plan committed as `0265-born-complete-subagent-session.md`; a side-quest filed #277 and added an architecture-doc breadcrumb for discovered debt.
+
+### Observations
+
+- Vocabulary was pinned down explicitly because "execution" is overloaded: granular execution = one turn loop (one `session.prompt()`, run or resume); the born-complete object spans the whole session lifetime (run + resumes).
+  The object is named `SubagentSession` (matches the existing `SubagentType` / `SubagentSessionDir` / `SubagentSessionRegistry` family; cohesive with the deferred `Agent` → `Subagent` rename).
+  Turn driving is `runTurnLoop` / `resumeTurnLoop`; resume is *not* an SDK `session.resume()` — it is `session.prompt()` again on the retained session.
+- The turn-loop home is **on `SubagentSession`** (methods), not inline on `Agent` and not a free function.
+  The user caught that `subagent.driveTurnLoop(subagentSession.session, …)` is a Law-of-Demeter reach-through; putting the behavior on the object that owns the `AgentSession` is both LoD-correct and more testable (satisfying the user's conditional "inline only if straightforward to test").
+- Workspace ownership locked to **Option A** (session-only `SubagentSession`; `Agent` keeps workspace prepare/dispose).
+  Decisive reasoning: the workspace and the session have genuinely different lifetimes (workspace dies at run-completion to fold its `resultAddendum` into the result; session survives to cleanup for resume + the new registry boundary), so they are different resources.
+  Option B would fuse them into one object needing two teardown methods, and would thread the `WorkspaceProvider` + prepare-context through the factory just to call `prepare()` — a parameter-relay smell the user flagged.
+  The factory takes a resolved `cwd` value (used directly), never the provider.
+- Worktrees are already out of the core (#263) — confirmed zero git code in `pi-subagents/src/` (only doc comments).
+  The A/B fork is purely about how the core sequences its abstract `WorkspaceProvider` seam; `@gotgenes/pi-subagents-worktrees` is untouched.
+- Registry semantics: moving `disposed` from run-completion to true session disposal makes resume executions registry-detected (closes the gap deferred from #261).
+  The permission system's subscription code does not change; only *when* `disposed` fires moves.
+  Edge case planned: `createSubagentSession` must dispose on a post-`session-created` failure to avoid a registry leak.
+- Discovered debt captured (the user's "it is in doing the work that we discover the work to be done"): filed #277 for the remaining `agent.session` reach-throughs (steer buffer-or-deliver duplicated across `steer-tool` + `service-adapter`, conversation viewing, resume-readiness guards) and added a "Session encapsulation debt (Law of Demeter)" subsection to `architecture.md` (commit `038a1283`).
+  `SubagentSession` exposes a `.session` accessor in #265 so observer wiring + consumers keep working; #277 retires those.
+- Two follow-ups deliberately deferred and noted in the plan's Non-Goals / Open Questions: the `Agent` → `Subagent` class rename (mechanical, ~19 files — separate issue) and resume-aware workspaces (a worktree's lifetime is one turn loop; worktree + resume is degenerate today).
+- The change is non-breaking (no `feat!:`): the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are internal, so `public.d.ts` is unaffected.
+  TDD order uses lift-and-shift across 7 steps to keep each commit compiling; transient duplication of the turn-loop helpers/assembly exists between steps 3–5 and is deleted in step 6.
+
+## Stage: Implementation — TDD (2026-05-29T22:18:00Z)
+
+### Session summary
+
+Executed all 7 TDD steps from the plan via lift-and-shift, one commit per step, each leaving the suite green.
+Introduced `SubagentSession` (`runTurnLoop`/`resumeTurnLoop`/`steer`/`dispose`) and the `createSubagentSession()` assembly factory, swapped `Agent`/`AgentManager`/`index.ts` onto them, then deleted `agent-runner.ts` + `execution-state.ts` and the three runner test files.
+Package test count went 951 → 960 (net +9: new `subagent-session`/`create-subagent-session`/`turn-limits` suites added, the redundant runner suites deleted).
+Pre-completion reviewer: initial FAIL (MD060 table alignment in SKILL.md, auto-fixed by `rumdl fmt`), PASS on re-check after fix + stale doc cleanup.
+
+### Observations
+
+- The plan sketch's `TurnLoopOptions` listed only `maxTurns`/`graceTurns`/`signal`, but preserving the old `runAgent` precedence `per-call ?? agentMaxTurns ?? defaultMaxTurns` required threading `defaultMaxTurns` through `TurnLoopOptions` and storing `agentMaxTurns` + `parentContext` in `SubagentSession` meta (both are session-level facts known at creation).
+  This is a correctness-preserving deviation, well covered by three precedence tests plus a parent-context-prepend test in `subagent-session.test.ts`.
+- The atomic call-site swap (step 5) touched more test files than the plan's step-5 list anticipated: every tool/service test that set `record.execution = { session, outputFile }` (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) had to migrate to `record.subagentSession = toSubagentSession(createSubagentSessionStub(...))`.
+  Added `createSubagentSessionStub`/`toSubagentSession` to `mock-session.ts` so the migration was a one-line change per call site; the stub's `steer`/`dispose` delegate to the underlying `MockSession` so existing session-spy assertions kept working unchanged.
+- `disposed` moved from `runAgent`'s `finally` (run-completion) to `SubagentSession.dispose()`, invoked by `AgentManager` via the new `Agent.disposeSession()` (routing both `record.session?.dispose?.()` call sites at `agent-manager.ts:235,309`).
+  The full cross-package suite confirms the permission system (1504 tests) is unaffected — its subscription code did not change, only *when* `disposed` fires.
+- Test-helper gotcha: `makeSubagentSession`'s `outputFile` default initially swallowed an explicit `undefined` via `?? default`; fixed with an `"outputFile" in metaOverrides` presence check (the testing-skill "Partial spread erases explicit undefined" family).
+- `print-mode.test.ts` now mocks `#src/lifecycle/create-subagent-session` (was `#src/lifecycle/agent-runner`); `index.ts` wraps the factory as `(params) => createSubagentSession(params, deps)`, so the module mock still intercepts it.
+- fallow stayed clean throughout — the transient duplication of IO interfaces + turn-loop helpers between `agent-runner.ts` and the new modules (steps 3–5) was removed in step 6 before the pre-completion gate ran.
+- Reviewer's two minor non-blocking notes: SKILL.md Session-domain count now lists `conversation.ts` but still omits the pre-existing `content-items.ts` (drift predates this issue); `create-subagent-session.ts` keeps an accurate "old runner's runAgent()" provenance comment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -24,9 +24,9 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
@@ -132,7 +132,7 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
-  const runnerDeps: RunnerDeps = {
+  const subagentSessionDeps: SubagentSessionDeps = {
     io: {
       detectEnv,
       getAgentDir,
@@ -162,7 +162,7 @@ export default function (pi: ExtensionAPI) {
   );
 
   const manager = new AgentManager({
-    runner: new ConcreteAgentRunner(runnerDeps),
+    createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
     baseCwd: process.cwd(),
     observer,
     queue,

package/src/lifecycle/agent-manager.ts

@@ -10,9 +10,10 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import { debugLog } from "#src/debug";
 import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
-import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SubagentSession } from "#src/lifecycle/subagent-session";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
@@ -28,7 +29,8 @@ export interface AgentManagerObserver {
 }
 
 export interface AgentManagerOptions {
-  runner: AgentRunner;
+  /** Assembly factory that produces a born-complete SubagentSession per spawn. */
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
   /** Base working directory handed to a workspace provider (the parent cwd). */
@@ -64,7 +66,7 @@ export class AgentManager {
   private agents = new Map<string, Agent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: AgentManagerObserver;
-  private readonly runner: AgentRunner;
+  private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   private readonly queue: ConcurrencyQueue;
   private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
@@ -76,7 +78,7 @@ export class AgentManager {
   }
 
   constructor(options: AgentManagerOptions) {
-    this.runner = options.runner;
+    this.createSubagentSession = options.createSubagentSession;
     this.queue = options.queue;
     this.baseCwd = options.baseCwd;
     this.observer = options.observer;
@@ -152,7 +154,7 @@ export class AgentManager {
       parentSession: options.parentSession,
       signal: options.signal,
       // Shared deps
-      runner: this.runner,
+      createSubagentSession: this.createSubagentSession,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
       baseCwd: this.baseCwd,
@@ -231,8 +233,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: Agent): void {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
-    record.session?.dispose?.();
+    record.disposeSession();
     this.agents.delete(id);
   }
 
@@ -306,7 +307,7 @@ export class AgentManager {
     // Clear queue
     this.queue.clear();
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.disposeSession();
     }
     this.agents.clear();
   }

package/src/lifecycle/agent.ts

@@ -14,16 +14,16 @@
  * 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 (execution, notification) are attached
+ * Phase-specific collaborators (subagentSession, notification) are attached
  * after construction as lifecycle information becomes available.
  */
 
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
-import type { ExecutionState } from "#src/lifecycle/execution-state";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SubagentSession, TurnLoopResult } from "#src/lifecycle/subagent-session";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
@@ -36,7 +36,7 @@ import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType,
 export interface AgentLifecycleObserver {
 	/** Fires when the agent transitions to running (inside run(), after markRunning). */
 	onStarted?(agent: Agent): void;
-	/** Fires when the runner creates the session — delivers the session to external consumers. */
+	/** Fires once the session is created — delivers the session to external consumers. */
 	onSessionCreated?(agent: Agent, session: AgentSession): void;
 	/** Fires once when the run completes or fails (for concurrency drain). */
 	onRunFinished?(agent: Agent): void;
@@ -68,7 +68,8 @@ export interface AgentInit {
 	error?: string;
 
 	// Shared deps (required for run(), optional for tests)
-	runner?: AgentRunner;
+	/** Assembly factory that produces a born-complete SubagentSession. */
+	createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
@@ -126,7 +127,7 @@ export class Agent {
 	promise?: Promise<void>;
 
 	// Shared deps — optional (required for run())
-	private readonly _runner?: AgentRunner;
+	private readonly _createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
@@ -144,7 +145,8 @@ export class Agent {
 	private readonly _signal?: AbortSignal;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
-	execution?: ExecutionState;
+	/** The born-complete child session — set when the factory returns inside run(). */
+	subagentSession?: SubagentSession;
 	notification?: NotificationState;
 
 	// Steer buffer — messages queued before the session is ready
@@ -154,12 +156,12 @@ export class Agent {
 
 	/** The active agent session, or undefined before the session is created. */
 	get session(): AgentSession | undefined {
-		return this.execution?.session;
+		return this.subagentSession?.session;
 	}
 
 	/** Path to the agent's session JSONL file, or undefined if not yet available. */
 	get outputFile(): string | undefined {
-		return this.execution?.outputFile;
+		return this.subagentSession?.outputFile;
 	}
 
 	constructor(init: AgentInit) {
@@ -185,7 +187,7 @@ export class Agent {
 		this.abortController = new AbortController();
 
 		// Shared deps
-		this._runner = init.runner;
+		this._createSubagentSession = init.createSubagentSession;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 		this._getWorkspaceProvider = init.getWorkspaceProvider;
@@ -207,16 +209,16 @@ export class Agent {
 	}
 
 	/**
-	 * Execute the full agent lifecycle: workspace preparation, runner invocation,
-	 * session-creation handling, observer wiring, workspace disposal, and
+	 * Execute the full agent lifecycle: workspace preparation, session creation
+	 * via the factory, observer wiring, the turn loop, workspace disposal, and
 	 * status transitions.
 	 *
-	 * Requires runner and snapshot to be set at construction.
+	 * Requires the session factory and snapshot to be set at construction.
 	 * The returned promise always resolves (errors are captured internally).
 	 */
 	async run(): Promise<void> {
-		if (!this._runner) {
-			throw new Error("Agent not configured for execution — missing runner");
+		if (!this._createSubagentSession) {
+			throw new Error("Agent not configured for execution — missing session factory");
 		}
 		if (!this._snapshot || !this._prompt) {
 			throw new Error("Agent not configured for execution — missing snapshot or prompt");
@@ -247,29 +249,35 @@ export class Agent {
 			return;
 		}
 
-		const runConfig = this._getRunConfig?.();
 		try {
-			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
-				context: {
-					cwd,
-					parentSession: this._parentSession,
-				},
+			this.subagentSession = await this._createSubagentSession({
+				snapshot: this._snapshot,
+				type: this.type,
+				cwd,
+				parentSession: this._parentSession,
 				model: this._model,
+				thinkingLevel: this._thinkingLevel,
+			});
+		} catch (err) {
+			// The factory disposed its own session on a post-creation failure.
+			this.failRun(err);
+			return;
+		}
+
+		const session = this.subagentSession.session;
+		this.flushPendingSteers();
+		this.attachObserver(subscribeAgentObserver(session, this, {
+			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		}));
+		this.observer?.onSessionCreated?.(this, session);
+
+		const runConfig = this._getRunConfig?.();
+		try {
+			const result = await this.subagentSession.runTurnLoop(this._prompt, {
 				maxTurns: this._maxTurns,
 				defaultMaxTurns: runConfig?.defaultMaxTurns,
 				graceTurns: runConfig?.graceTurns,
-				thinkingLevel: this._thinkingLevel,
 				signal: this.abortController.signal,
-				onSessionCreated: (session) => {
-					// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
-					const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
-					this.execution = { session, outputFile };
-					this.flushPendingSteers(session);
-					this.attachObserver(subscribeAgentObserver(session, this, {
-						onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
-					}));
-					this.observer?.onSessionCreated?.(this, session);
-				},
 			});
 			this.completeRun(result);
 		} catch (err) {
@@ -281,27 +289,24 @@ 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).
+	 * Requires an existing SubagentSession (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
+	 * The parent signal flows straight through to resumeTurnLoop — 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) {
+		const subagentSession = this.subagentSession;
+		if (!subagentSession) {
 			throw new Error("Agent not configured for resume — missing session");
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeAgentObserver(session, this, {
+		this.attachObserver(subscribeAgentObserver(subagentSession.session, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 
 		try {
-			const responseText = await this._runner.resume(session, prompt, { signal });
+			const responseText = await subagentSession.resumeTurnLoop(prompt, signal);
 			this.markCompleted(responseText);
 		} catch (err) {
 			this.markError(err);
@@ -407,11 +412,11 @@ export class Agent {
 
 	/**
 	 * Flush all buffered steer messages to the session and clear the buffer.
-	 * Called from onSessionCreated once the session is available.
+	 * Called once the session is available, delegating to SubagentSession.steer.
 	 */
-	flushPendingSteers(session: AgentSession): void {
+	flushPendingSteers(): void {
 		for (const msg of this._pendingSteers) {
-			session.steer(msg).catch(() => {});
+			this.subagentSession?.steer(msg).catch(() => {});
 		}
 		this._pendingSteers = [];
 	}
@@ -451,8 +456,8 @@ export class Agent {
 		this._detachFn = undefined;
 	}
 
-	/** Complete a run: release listeners, dispose the workspace, status transition, execution update, notify observer. */
-	completeRun(result: RunResult): void {
+	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
+	completeRun(result: TurnLoopResult): void {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
@@ -470,14 +475,14 @@ export class Agent {
 		else if (result.steered) this.markSteered(finalResult);
 		else this.markCompleted(finalResult);
 
-		this.execution = {
-			session: result.session,
-			outputFile: result.sessionFile ?? this.execution?.outputFile,
-		};
-
 		this.observer?.onRunFinished?.(this);
 	}
 
+	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
+	disposeSession(): void {
+		this.subagentSession?.dispose();
+	}
+
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);