@gotgenes/pi-subagents 5.6.0 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [5.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.6.0...pi-subagents-v5.7.0) (2026-05-20)
+
+
+### Features
+
+* add session-context methods to SubagentRuntime ([3bbc6af](https://github.com/gotgenes/pi-packages/commit/3bbc6af5c3d9e6faef2112f6c92f991c4b27e38d))
+* add widget delegation methods to SubagentRuntime ([36350f4](https://github.com/gotgenes/pi-packages/commit/36350f413f44f432b14b0a42e27df2c8f5444a08))
+
+
+### Documentation
+
+* add [#87](https://github.com/gotgenes/pi-packages/issues/87) to architecture roadmap and fix package scope hallucinations ([ddee1a0](https://github.com/gotgenes/pi-packages/commit/ddee1a011acc3e20d17d2bdf46cc4603604c092d))
+* plan evolving SubagentRuntime from data bag to object with methods ([#87](https://github.com/gotgenes/pi-packages/issues/87)) ([4f2f16a](https://github.com/gotgenes/pi-packages/commit/4f2f16a8eea67e4959a754d172a9238b4b8662b1))
+* plan extract event handlers from index.ts ([#70](https://github.com/gotgenes/pi-packages/issues/70)) ([5fc115f](https://github.com/gotgenes/pi-packages/commit/5fc115f61bc52c5c88630ea7c869e1e34bde0130))
+* **retro:** add retro notes for issue [#72](https://github.com/gotgenes/pi-packages/issues/72) ([5b53189](https://github.com/gotgenes/pi-packages/commit/5b53189d6242b6f2262b9e7cd2d9dbdbe2a28c60))
+* update architecture roadmap with [#72](https://github.com/gotgenes/pi-packages/issues/72), [#76](https://github.com/gotgenes/pi-packages/issues/76), [#80](https://github.com/gotgenes/pi-packages/issues/80), [#84](https://github.com/gotgenes/pi-packages/issues/84) status ([176cb68](https://github.com/gotgenes/pi-packages/commit/176cb682001b21b7c223656b353b8cf2af412b0c))
+
 ## [5.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.5.0...pi-subagents-v5.6.0) (2026-05-20)
 
 

package/docs/architecture/architecture.md

@@ -59,7 +59,7 @@ There is also a `Symbol.for("pi-subagents:manager")` export on `globalThis` that
 
 ```text
   ┌────────────────────────────────────────────────────────┐
-  │  @earendil-works/pi-subagents  (this package)          │
+  │  @gotgenes/pi-subagents  (this package)                 │
   │                                                        │
   │  Exports:                                              │
   │    SubagentsAPI interface                              │
@@ -131,7 +131,7 @@ After removal and `index.ts` decomposition, the core shrinks from ~6,300 to ~5,4
 
 ## SubagentsAPI
 
-The `SubagentsAPI` interface, accessor functions, and serializable types are exported directly from this package (`@earendil-works/pi-subagents`).
+The `SubagentsAPI` interface, accessor functions, and serializable types are exported directly from this package (`@gotgenes/pi-subagents`).
 No separate API package is needed.
 
 Consumers declare this package as an optional peer dependency:
@@ -139,10 +139,10 @@ Consumers declare this package as an optional peer dependency:
 ```json
 {
   "peerDependencies": {
-    "@earendil-works/pi-subagents": ">=2.0.0"
+    "@gotgenes/pi-subagents": ">=2.0.0"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-subagents": { "optional": true }
+    "@gotgenes/pi-subagents": { "optional": true }
   }
 }
 ```
@@ -150,7 +150,7 @@ Consumers declare this package as an optional peer dependency:
 At runtime, consumers use dynamic import for type-safe access to the accessor functions:
 
 ```typescript
-const { getSubagentsAPI } = await import("@earendil-works/pi-subagents");
+const { getSubagentsAPI } = await import("@gotgenes/pi-subagents");
 const api = getSubagentsAPI();
 if (api) {
   api.spawn("Explore", "Check for stale TODOs");
@@ -238,14 +238,14 @@ They are fire-and-forget broadcast events — no request IDs, no reply channels.
 
 ```typescript
 // package.json:
-// "peerDependencies": { "@earendil-works/pi-subagents": ">=2.0.0" }
-// "peerDependenciesMeta": { "@earendil-works/pi-subagents": { "optional": true } }
+// "peerDependencies": { "@gotgenes/pi-subagents": ">=2.0.0" }
+// "peerDependenciesMeta": { "@gotgenes/pi-subagents": { "optional": true } }
 
 export default function (pi) {
   pi.on("session_start", async (event, ctx) => {
     let getSubagentsAPI;
     try {
-      ({ getSubagentsAPI } = await import("@earendil-works/pi-subagents"));
+      ({ getSubagentsAPI } = await import("@gotgenes/pi-subagents"));
     } catch {
       return; // pi-subagents not installed
     }
@@ -269,7 +269,7 @@ export default function (pi) {
     const { id } = data as { id: string };
     let getSubagentsAPI;
     try {
-      ({ getSubagentsAPI } = await import("@earendil-works/pi-subagents"));
+      ({ getSubagentsAPI } = await import("@gotgenes/pi-subagents"));
     } catch {
       return;
     }
@@ -330,7 +330,7 @@ Resolve model strings inside the adapter (fixing upstream [tintinweb/pi-subagent
 Extracted tools, notifications, activity tracking, and the `/agents` command into separate modules.
 `src/index.ts` shrank from ~1,619 lines to ~265 lines.
 
-### Phase 6 (future): Extract UI to `@earendil-works/pi-subagents-ui`
+### Phase 6 (future): Extract UI to `@gotgenes/pi-subagents-ui`
 
 Move `ui/agent-widget.ts`, `ui/conversation-viewer.ts`, the `/agents` command, notifications, and activity tracking to a separate extension that consumes `SubagentsAPI` + lifecycle events.
 This phase is deferred until the API boundary is proven stable in production.
@@ -353,44 +353,53 @@ Together they eliminate module-scope mutable state, create a testable functional
    - Split `runAgent()` into a pure configuration assembler (~200 lines) and an IO shell (~200 lines).
    - The assembler becomes independently testable without mocking the Pi SDK.
 
-3. **gotgenes/pi-packages#76** — Inject `cwd` into `AgentManager`
-   - Replace the `process.cwd()` call in `dispose()` with a constructor parameter.
-   - A small, mechanical prerequisite for Issue #72.
+3. **gotgenes/pi-packages#76** ✓ — Inject `cwd` into `AgentManager`
+   - Replaced the `process.cwd()` call in `dispose()` with a constructor parameter.
 
-4. **gotgenes/pi-packages#80** — Consolidate `getConfig` / `getAgentConfig` into a single resolution path
-   - Replace the two overlapping lookup functions with a single `resolveAgentConfig(type): AgentConfig` that handles the unknown-type fallback internally.
-   - Eliminates the duplicated fallback chain exposed by #71 and simplifies test mock setup.
+4. **gotgenes/pi-packages#80** ✓ — Consolidate `getConfig` / `getAgentConfig` into a single resolution path
+   - Replaced the two overlapping lookup functions with a single `resolveAgentConfig(type): AgentConfig` that handles the unknown-type fallback internally.
+   - Eliminated the duplicated fallback chain exposed by #71 and simplified test mock setup.
 
 ### Phase 2: Core decomposition
 
 These build on Phase 1 and should land after it.
 
-4. **gotgenes/pi-packages#72** — Dependency-inject `AgentManager`'s collaborators
-   - Introduce `AgentRunner` and `WorktreeManager` interfaces and inject them into `AgentManager`.
-   - Removes direct imports of `agent-runner.ts` and `worktree.ts` from `agent-manager.ts`.
+1. **gotgenes/pi-packages#84** ✓ — Extract `GitWorktreeManager` class from `worktree.ts`
+   - Added `WorktreeManager` interface and `GitWorktreeManager` class that captures `cwd` at construction.
+   - Prerequisite for #72 — separated the real-object extraction from the DI refactor.
 
-5. **gotgenes/pi-packages#70** — Extract event handlers into `src/handlers/`
+2. **gotgenes/pi-packages#72** ✓ — Dependency-inject `AgentManager`'s collaborators
+   - Defined `AgentRunner` interface (execution boundary) and `ResumeOptions` type in `agent-runner.ts`.
+   - Converted `AgentManager` constructor from 6 positional parameters to an `AgentManagerOptions` bag with injected `AgentRunner` and `WorktreeManager`.
+   - Removed all runtime imports of `agent-runner.ts` and `worktree.ts` from `agent-manager.ts` (only `import type` remains).
+   - Migrated all tests from `vi.mock()` module stubs to `vi.fn()` interface stubs.
+
+3. **gotgenes/pi-packages#87** — Evolve `SubagentRuntime` from data bag to object with methods
+   - Add session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
+   - Prerequisite for #70 — without runtime methods, extracted handlers would move LoD violations and output-argument smells into handler classes.
+
+4. **gotgenes/pi-packages#70** — Extract event handlers into `src/handlers/`
    - Move the four inline lambdas (`session_start`, `session_before_switch`, `session_shutdown`, `tool_execution_start`) into named handler modules.
-   - Requires Issue #69 because handlers need the `SubagentRuntime` as their deps bag.
+   - Requires Issues #69 and #87 because handlers need the `SubagentRuntime` with methods as their deps.
    - Target: `src/index.ts` ≤150 lines.
 
 ### Phase 3: Interface polish
 
 Small cleanups that are safest after the structural changes settle.
 
-6. **gotgenes/pi-packages#66** — Replace `as any` casts with proper SDK types
+1. **gotgenes/pi-packages#66** — Replace `as any` casts with proper SDK types
    - Type-only change in the tool/menu factory dep interfaces.
    - Best done after Issues #69 and #70 when the interfaces are stable.
 
-7. **gotgenes/pi-packages#77** — Add `projectAgentsDir` to `AgentMenuDeps`
+2. **gotgenes/pi-packages#77** — Add `projectAgentsDir` to `AgentMenuDeps`
    - Remove the inline `process.cwd()` lambda from the menu handler.
 
 ### Phase 4: Features and cross-cutting concerns
 
-8. **gotgenes/pi-packages#61** — Port transcript logging to Pi's official JSONL session format
+1. **gotgenes/pi-packages#61** — Port transcript logging to Pi's official JSONL session format
    - Feature work that should happen after structural refactoring is complete so the output-file subsystem has a stable home.
 
-9. **gotgenes/pi-packages#22** — Parent-session resolution for `nicobailon/pi-subagents` children
+2. **gotgenes/pi-packages#22** — Parent-session resolution for `nicobailon/pi-subagents` children
    - Cross-extension issue that spans `pi-permission-system` and `pi-subagents`.
    - Requires coordination on env-var conventions.
    - Not blocked by the structural refactor but logically separate from it.
@@ -398,15 +407,13 @@ Small cleanups that are safest after the structural changes settle.
 ### Dependency graph
 
 ```text
-#69 (SubagentRuntime) ✓ ─┬─► #70 (handler extraction)
-                        │
-                        └─► #72 (AgentManager DI) ──(optional)──► #70
-
-#71 (pure assembler) ✓ ──► #80 (consolidate getConfig/getAgentConfig)
-
-#76 (cwd injection) ────► #72
-
-#80 (config lookup) ────(independent, simplifies #72 and test mocks)
+#69 (SubagentRuntime) ✓ ──► #87 (runtime methods) ─┬─► #70 (handler extraction)
+                                                   │
+#71 (pure assembler) ✓                              │
+#80 (config lookup) ✓                               │
+#76 (cwd injection) ✓                               │
+#84 (WorktreeManager) ✓                             │
+#72 (AgentManager DI) ✓ ────────────────────────────┘──(optional)──► #70
 
 #66 (type casts) ◄─────(after structural changes settle)
 #77 (projectAgentsDir) ◄─(after #66 or parallel)
@@ -420,15 +427,16 @@ Small cleanups that are safest after the structural changes settle.
 The recommended sequence is:
 
 ```text
-#69 ✓ → #71 ✓ → #80 → #76 → #72 → #70 → #66 → #77 → #61
+#69 ✓ → #71 ✓ → #80 ✓ → #76 ✓ → #84 ✓ → #72 ✓ → #87 → #70 → #66 → #77 → #61
 ```
 
-Issue #80 slots after #71 because it cleans up the redundant lookup that #71 exposed, and simplifies mock setup for subsequent issues.
+Phase 1 is complete; Phase 2 is in progress.
+The next issue is #87 (runtime methods), which unblocks #70 (handler extraction).
 Issue #22 is a parallel cross-extension track and does not gate the structural work.
 
 ## Relationship with upstream
 
-This fork ([earendil-works/pi-subagents]) is now a hard fork of [tintinweb/pi-subagents].
+This fork (`@gotgenes/pi-subagents` in the [gotgenes/pi-packages] monorepo) is now a hard fork of [tintinweb/pi-subagents].
 The decomposition diverges materially from upstream's direction.
 
 The three upstream PRs (#71, #72, #73) remain open.
@@ -439,5 +447,5 @@ Upstream fixes and ideas are cherry-picked when they align with this fork's scop
 The upstream test suite is run periodically as a regression canary for the agent-runner core.
 
 [earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
-[earendil-works/pi-subagents]: https://github.com/earendil-works/pi-subagents
+[gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
 [tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents

package/docs/plans/0070-extract-event-handlers.md

@@ -0,0 +1,306 @@
+---
+issue: 70
+issue_title: "refactor: extract event handlers from pi-subagents index.ts into src/handlers/"
+---
+
+# Extract event handlers from index.ts
+
+## Problem Statement
+
+After #54 and #69, `src/index.ts` is still ~281 lines.
+Four event handlers (`session_start`, `session_before_switch`, `session_shutdown`, `tool_execution_start`) are inline lambdas inside the factory closure.
+They cannot be tested in isolation because they reach into closure-scoped objects (`runtime`, `manager`, `notifications`, `pi`).
+`pi-permission-system` solved the same problem in #42 by extracting all handlers into `src/handlers/` as classes receiving narrow constructor-injected dependencies.
+
+## Goals
+
+- Create `src/handlers/` with dedicated modules for each handler group.
+- Define handler classes with constructor-injected narrow interfaces that replace closure-captured state with explicit, testable contracts.
+- Reduce `src/index.ts` by moving handler bodies out — target ≤ 200 lines (the remaining bulk is tool/menu wiring, which is out of scope).
+- Enable unit testing of each handler module via mocked deps.
+- No behavior change — pure structural refactor.
+
+## Non-Goals
+
+- Extracting tool registration or menu wiring from `index.ts` (separate concern; not in scope).
+- Changing the `SubagentsService` interface.
+- Refactoring `AgentManager` constructor signature.
+- Consolidating notification callbacks — the notification system's shape is unchanged.
+
+## Background
+
+### Current handler bodies in index.ts
+
+```typescript
+// session_start (~3 lines)
+runtime.currentCtx = { pi, ctx };
+manager.clearCompleted();
+
+// session_before_switch (~1 line)
+manager.clearCompleted();
+
+// session_shutdown (~5 lines)
+unpublishSubagentsService();
+runtime.currentCtx = undefined;
+manager.abortAll();
+notifications.dispose();
+manager.dispose();
+
+// tool_execution_start (~2 lines)
+runtime.widget!.setUICtx(ctx.ui as UICtx);
+runtime.widget!.onTurnStart();
+```
+
+### Prior art: pi-permission-system src/handlers/
+
+Issue #42 extracted lifecycle, agent-prep, and permission-gate handlers into classes that receive narrow constructor deps.
+Each class exposes handler methods matching the Pi SDK event signatures.
+`index.ts` constructs the handler objects and wires `pi.on(event, handler.method)`.
+
+This plan follows the same class-based pattern.
+Although the individual handler bodies are small (1–5 lines), the lifecycle handlers share `runtime` and `manager` as collaborators — shared state that a class captures naturally via constructor injection rather than threading through each call.
+
+### Prerequisite status
+
+- Issue #69 (SubagentRuntime) — **closed / implemented**.
+  The runtime object exists in `src/runtime.ts` and is already wired into `index.ts`.
+- Issue #87 (evolve SubagentRuntime from data bag to object with methods) — **open / must land first**.
+  Adds `setSessionContext()` / `clearSessionContext()` and widget delegation methods (`setUICtx()`, `onTurnStart()`, `markFinished()`, `updateWidget()`, `ensureTimer()`).
+  Without #87, extracted handlers would just move the output-argument and LoD smells from `index.ts` into handler classes.
+  With #87, handlers call methods on narrow runtime interfaces — no raw field writes, no `widget!` reach-throughs.
+
+### Relevant constraints from AGENTS.md / code-style skill
+
+- Keep modules focused and composable (one concern per file).
+- Do not pass a shared dependency bag to functions that only use a subset — define narrow interfaces per consumer.
+- Keep Pi SDK imports out of business-logic modules — handler modules should accept lean local payload interfaces, not full SDK event types.
+- Prefer explicit configuration over hidden behavior.
+
+## Design Overview
+
+### Module layout
+
+```text
+src/handlers/
+  lifecycle.ts    # session_start, session_before_switch, session_shutdown
+  tool-start.ts   # tool_execution_start
+  index.ts        # barrel re-export
+```
+
+No shared `types.ts` file — each module defines its own narrow constructor interfaces.
+This follows the code-style guidance ("do not pass a shared dependency bag to functions that only use a subset") and matches the permission-system's prior art where each handler class takes its own narrow constructor deps.
+
+### Narrow constructor interfaces
+
+Each class defines local interfaces for its collaborators, exposing only the methods the class actually calls.
+This keeps tests simple (mock only what's used) and decouples handlers from concrete types.
+
+#### SessionLifecycleHandler (in lifecycle.ts)
+
+```typescript
+/** Narrow manager interface — only the methods lifecycle handlers call. */
+export interface LifecycleManager {
+  clearCompleted(): void;
+  abortAll(): void;
+  dispose(): void;
+}
+
+/** Narrow runtime interface — only the methods lifecycle handlers call. */
+export interface LifecycleRuntime {
+  setSessionContext(pi: unknown, ctx: unknown): void;
+  clearSessionContext(): void;
+}
+
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly pi: unknown,
+    private readonly runtime: LifecycleRuntime,
+    private readonly manager: LifecycleManager,
+    private readonly disposeNotifications: () => void,
+    private readonly unpublishService: () => void,
+  ) {}
+
+  handleSessionStart(_event: unknown, ctx: unknown): void { ... }
+  handleSessionBeforeSwitch(): void { ... }
+  async handleSessionShutdown(): Promise<void> { ... }
+}
+```
+
+Five constructor params — `runtime` and `manager` are shared across all three methods (the key insight the plain-function design missed), while `disposeNotifications` and `unpublishService` are shutdown-only callbacks.
+
+`LifecycleRuntime` exposes methods, not mutable fields — the handler *tells* the runtime to set/clear session context instead of writing raw fields (the output-argument smell that #87 eliminates).
+
+#### ToolStartHandler (in tool-start.ts)
+
+```typescript
+/** Narrow runtime interface — only the widget-delegation methods the handler calls. */
+export interface ToolStartRuntime {
+  setUICtx(ctx: UICtx): void;
+  onTurnStart(): void;
+}
+
+export class ToolStartHandler {
+  constructor(
+    private readonly runtime: ToolStartRuntime,
+  ) {}
+
+  handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void { ... }
+}
+```
+
+After #87, the runtime owns widget delegation — `runtime.setUICtx()` delegates to `this.widget?.setUICtx()` internally, handling the null check.
+The handler takes a narrow `ToolStartRuntime` interface (just the two methods it calls) and does not know about `widget` or `SubagentRuntime` at all.
+
+### Event payload interfaces
+
+Following the code-style skill ("prefer lean local payload interfaces over full SDK event types"), each handler defines minimal payload types for the events it consumes.
+
+`session_start` receives `(event, ctx)` — but the current handler ignores the event payload entirely and only reads `ctx`.
+`tool_execution_start` receives `(event, ctx)` — the handler reads `ctx.ui`.
+
+Since handlers ignore event payloads, the method signatures use `_event: unknown`.
+
+### index.ts wire-up
+
+After extraction, `index.ts` constructs handler instances and binds:
+
+```typescript
+import { SessionLifecycleHandler } from "./handlers/index.js";
+import { ToolStartHandler } from "./handlers/index.js";
+
+const lifecycle = new SessionLifecycleHandler(
+  pi,
+  runtime,
+  manager,
+  () => notifications.dispose(),
+  unpublishSubagentsService,
+);
+
+pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
+
+const toolStart = new ToolStartHandler(runtime);
+
+pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
+```
+
+Handler instances are constructed once and hold their collaborators for the extension's lifetime — the same pattern as pi-permission-system's `SessionLifecycleHandler`.
+`runtime` satisfies both `LifecycleRuntime` and `ToolStartRuntime` structurally — TypeScript matches the narrow interface without an explicit cast.
+
+### Edge cases
+
+- `session_shutdown` calls `unpublishSubagentsService()` which is a module-level import — the handler receives it as a constructor callback, keeping the handler SDK-free.
+- Constructor params are narrow interfaces (`LifecycleManager`, `LifecycleRuntime`, `ToolStartRuntime`) rather than concrete types (`AgentManager`, `SubagentRuntime`), so tests construct mocks without importing production classes.
+- Widget null safety: after #87, the runtime's delegation methods handle null internally (`this.widget?.setUICtx(ctx)`), so handlers never see the null case.
+  `ToolStartHandler` tests mock the narrow `ToolStartRuntime` interface directly — no widget null logic to test in the handler.
+
+## Module-Level Changes
+
+### `src/handlers/lifecycle.ts` (new)
+
+- `LifecycleManager` interface (narrow: `clearCompleted`, `abortAll`, `dispose`).
+- `LifecycleRuntime` interface (narrow: `setSessionContext`, `clearSessionContext`).
+- `SessionLifecycleHandler` class — constructor takes `(pi, runtime, manager, disposeNotifications, unpublishService)`.
+- `handleSessionStart(_event, ctx)` — calls `this.runtime.setSessionContext(this.pi, ctx)`, calls `this.manager.clearCompleted()`.
+- `handleSessionBeforeSwitch()` — calls `this.manager.clearCompleted()`.
+- `handleSessionShutdown()` — calls `this.unpublishService()`, `this.runtime.clearSessionContext()`, `this.manager.abortAll()`, `this.disposeNotifications()`, `this.manager.dispose()`.
+
+### `src/handlers/tool-start.ts` (new)
+
+- `ToolStartRuntime` interface (narrow: `setUICtx`, `onTurnStart`).
+- `ToolStartCtx` local interface (`{ ui: UICtx }`).
+- `ToolStartHandler` class — constructor takes `runtime: ToolStartRuntime`.
+- `handleToolExecutionStart(_event, ctx)` — calls `this.runtime.setUICtx(ctx.ui)`, `this.runtime.onTurnStart()`.
+
+### `src/handlers/index.ts` (new)
+
+- Barrel re-export of handler classes and their narrow interfaces.
+
+### `src/index.ts` (modified)
+
+- Add imports from `./handlers/index.js`.
+- Construct `SessionLifecycleHandler` with `(pi, runtime, manager, () => notifications.dispose(), unpublishSubagentsService)`.
+- Construct `ToolStartHandler` with `runtime`.
+- Replace inline `pi.on("session_start", ...)` lambda with `lifecycle.handleSessionStart` delegation.
+- Replace inline `pi.on("session_before_switch", ...)` lambda with `lifecycle.handleSessionBeforeSwitch` delegation.
+- Replace inline `pi.on("session_shutdown", ...)` lambda with `lifecycle.handleSessionShutdown` delegation.
+- Replace inline `pi.on("tool_execution_start", ...)` lambda with `toolStart.handleToolExecutionStart` delegation.
+- `unpublishSubagentsService` import stays — passed to the handler constructor.
+
+### `test/handlers/lifecycle.test.ts` (new)
+
+- Construct `SessionLifecycleHandler` with mocked `LifecycleManager`, `LifecycleRuntime`, and stub callbacks.
+- `handleSessionStart`: verify `runtime.setSessionContext` called with `(pi, ctx)`, `manager.clearCompleted` called.
+- `handleSessionBeforeSwitch`: verify `manager.clearCompleted` called.
+- `handleSessionShutdown`: verify all five cleanup calls in correct order (unpublish → clearSessionContext → abortAll → disposeNotifications → dispose manager).
+
+### `test/handlers/tool-start.test.ts` (new)
+
+- Construct `ToolStartHandler` with a mock `ToolStartRuntime`.
+- Verify `setUICtx` and `onTurnStart` called with correct arguments.
+
+### `test/print-mode.test.ts` (unchanged)
+
+- This integration test calls `handlers.get("session_shutdown")` on the extension's registered handlers.
+  The extraction is transparent — the Pi event registration is still in `index.ts`, just delegating to extracted functions.
+  No changes needed.
+
+## Test Impact Analysis
+
+### New unit tests enabled by the extraction
+
+1. `test/handlers/lifecycle.test.ts` — Each lifecycle handler tested in isolation with mocked deps.
+   Previously impossible because handlers were inline lambdas with closure-captured `runtime`, `manager`, `notifications`, and `pi`.
+2. `test/handlers/tool-start.test.ts` — `tool_execution_start` handler tested with mocked widget.
+   Previously untestable because the handler was an inline lambda closing over `runtime.widget`.
+3. Widget null-safety is not the handler's concern — the runtime handles it internally after #87.
+
+### Existing tests that become redundant
+
+None.
+No existing tests directly test the event handler bodies — they were untestable inline lambdas.
+The extraction creates *new* coverage, not duplicate coverage.
+
+### Existing tests that stay as-is
+
+- `test/print-mode.test.ts` — calls `session_shutdown` via the extension's registered handler map; still works because `index.ts` still registers the event, just delegates to extracted functions.
+- All other test files — no dependency on handler internals.
+
+## TDD Order
+
+1. **Create `src/handlers/lifecycle.ts` with `SessionLifecycleHandler` class.**
+   Write `test/handlers/lifecycle.test.ts` constructing the handler with mocked narrow interfaces.
+   Verify: `handleSessionStart` sets `currentCtx` and calls `clearCompleted`; `handleSessionBeforeSwitch` calls `clearCompleted`; `handleSessionShutdown` calls all five cleanup steps in order.
+   Commit: `feat: add SessionLifecycleHandler`
+
+2. **Create `src/handlers/tool-start.ts` with `ToolStartHandler` class.**
+   Write `test/handlers/tool-start.test.ts` constructing the handler with a mock getter.
+   Verify: calls `setUICtx` and `onTurnStart` on widget; no-op when widget is null.
+   Commit: `feat: add ToolStartHandler`
+
+3. **Create `src/handlers/index.ts` barrel and wire handlers into `src/index.ts`.**
+   Add barrel re-export in `src/handlers/index.ts`.
+   Replace inline lambdas in `src/index.ts` with handler instance method delegation.
+   Construct `SessionLifecycleHandler` and `ToolStartHandler` in the factory.
+   Run full test suite to verify no regressions.
+   Run `pnpm run check` to verify types.
+   Commit: `refactor: wire extracted handlers into extension factory (#70)`
+
+## Risks and Mitigations
+
+| Risk                                                                    | Mitigation                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Handler extraction changes call order in `session_shutdown`             | Test explicitly asserts call order; current order is preserved exactly.                                                                                                                                                                                                                |
+| `SessionLifecycleHandler` has 5 constructor params                      | Reviewed against design-review: `runtime` and `manager` are shared across all three methods (the core shared-state argument for a class). The two callbacks (`disposeNotifications`, `unpublishService`) are shutdown-only but small enough to not warrant a second class. Acceptable. |
+| `print-mode.test.ts` integration test breaks                            | Test calls `session_shutdown` via the extension's handler map, not the extracted function directly. The delegation is transparent. Verified no changes needed.                                                                                                                         |
+| `UICtx` type import in `tool-start.ts` couples handler to widget module | `UICtx` is a lean interface already exported from `ui/agent-widget.ts`. The handler only references it in the `ToolStartCtx` local type. Acceptable coupling.                                                                                                                          |
+
+## Open Questions
+
+- Should the `session_shutdown` handler call cleanup in a specific guaranteed order (e.g., unpublish → abort → dispose)?
+  The current inline code uses a specific order; the extraction preserves it.
+  If order matters for correctness, add a code comment documenting it.
+  Decide during implementation.
+- Should the `ToolStartHandler` also handle `UICtx` type re-export, or should `tool-start.ts` import `UICtx` from `ui/agent-widget.ts` directly?
+  Decide during implementation — if the handler defines its own `ToolStartCtx` with `{ ui: unknown }`, it avoids the import entirely.

package/docs/plans/0087-evolve-subagent-runtime-methods.md

@@ -0,0 +1,240 @@
+---
+issue: 87
+issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
+---
+
+# Evolve SubagentRuntime from data bag to object with methods
+
+## Problem Statement
+
+`SubagentRuntime` (introduced in #69) consolidates all mutable extension state into one object, but it remains a plain data bag — an interface with public mutable fields and no methods.
+This causes two structural smells in `index.ts`:
+
+1. **Output arguments** — handlers write raw fields on the runtime instead of calling methods:
+   `runtime.currentCtx = { pi, ctx }` and `runtime.currentCtx = undefined`.
+2. **Law of Demeter violations** — 8 occurrences of `runtime.widget!.method()` across 4 call sites in `index.ts`, where callers reach through the runtime to talk to the widget with unsafe `!` non-null assertions.
+
+Issue #70 (extract event handlers) explicitly lists this issue as a prerequisite.
+Without these methods, extracted handlers would just move the output-argument and LoD smells from `index.ts` into handler classes.
+
+## Goals
+
+- Convert `SubagentRuntime` from an interface + factory to a class with methods.
+- Add session-context methods: `setSessionContext(pi, ctx)` and `clearSessionContext()`.
+- Add widget delegation methods that absorb the `runtime.widget!` reach-throughs: `setUICtx()`, `onTurnStart()`, `markFinished()`, `updateWidget()`, `ensureTimer()`.
+- Update all 10 call sites in `index.ts` to use the new methods — eliminate raw `currentCtx` field writes and `widget!` assertions.
+- No behavior change; pure structural refactor.
+
+## Non-Goals
+
+- Extracting event handlers into separate files (that is #70).
+- Adding methods for `defaultMaxTurns` / `graceTurns` writes — those field writes remain as-is; the issue scope covers `currentCtx` and `widget!` only.
+- Changing the `SubagentsService` interface.
+- Making `widget` private — `index.ts` still assigns `runtime.widget = new AgentWidget(...)` after construction.
+- Adding new features.
+
+## Background
+
+### Prior art
+
+`pi-permission-system`'s `PermissionSession` is a class with lifecycle methods (`refreshConfig`, `resetForNewSession`, `shutdown`).
+Lifecycle handlers in `src/handlers/lifecycle.ts` call those methods instead of writing fields.
+This issue brings `SubagentRuntime` to the same level.
+
+### Current runtime shape
+
+`src/runtime.ts` exports a `SubagentRuntime` interface and a `createSubagentRuntime()` factory:
+
+```typescript
+export interface SubagentRuntime {
+  defaultMaxTurns: number | undefined;
+  graceTurns: number;
+  currentCtx: { pi: unknown; ctx: unknown } | undefined;
+  readonly agentActivity: Map<string, AgentActivity>;
+  widget: AgentWidget | null;
+}
+```
+
+### Call sites to migrate
+
+Two `currentCtx` writes (output arguments):
+
+| Line | Current                            | After                                |
+| ---- | ---------------------------------- | ------------------------------------ |
+| 126  | `runtime.currentCtx = { pi, ctx }` | `runtime.setSessionContext(pi, ctx)` |
+| 138  | `runtime.currentCtx = undefined`   | `runtime.clearSessionContext()`      |
+
+Eight `widget!` reach-throughs (LoD violations):
+
+| Line | Current                                     | After                               |
+| ---- | ------------------------------------------- | ----------------------------------- |
+| 60   | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
+| 61   | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
+| 149  | `runtime.widget!.setUICtx(ctx.ui as UICtx)` | `runtime.setUICtx(ctx.ui as UICtx)` |
+| 150  | `runtime.widget!.onTurnStart()`             | `runtime.onTurnStart()`             |
+| 204  | `runtime.widget!.setUICtx(ctx as UICtx)`    | `runtime.setUICtx(ctx as UICtx)`    |
+| 205  | `runtime.widget!.ensureTimer()`             | `runtime.ensureTimer()`             |
+| 206  | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
+| 207  | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
+
+### Dependency chain
+
+Issue #69 (SubagentRuntime) is closed/implemented.
+This issue (#87) is a prerequisite for #70 (extract event handlers).
+The #70 plan defines narrow handler interfaces (`LifecycleRuntime`, `ToolStartRuntime`) that the runtime class satisfies structurally.
+
+### Relevant constraints from AGENTS.md / code-style skill
+
+- Keep modules focused and composable (one concern per file).
+- Do not pass a shared dependency bag to functions that only use a subset — define narrow interfaces per consumer.
+- Do not write back into a received dependency bag (output arguments).
+- Do not reach through an injected collaborator to talk to a stranger (Law of Demeter).
+- When multiple callers perform the same reach-through, the missing abstraction is a method on the intermediate object that delegates internally.
+
+## Design Overview
+
+### Class conversion
+
+Convert `SubagentRuntime` from an interface to a class.
+Public fields stay as-is — callers that read `runtime.defaultMaxTurns`, `runtime.currentCtx`, `runtime.agentActivity`, etc. continue to work.
+The `createSubagentRuntime()` factory becomes a thin alias returning `new SubagentRuntime()`, preserving backward compatibility for `index.ts` and existing tests during the transition.
+
+```typescript
+export class SubagentRuntime {
+  defaultMaxTurns: number | undefined = undefined;
+  graceTurns: number = 5;
+  currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;
+  readonly agentActivity: Map<string, AgentActivity> = new Map();
+  widget: AgentWidget | null = null;
+
+  setSessionContext(pi: unknown, ctx: unknown): void {
+    this.currentCtx = { pi, ctx };
+  }
+
+  clearSessionContext(): void {
+    this.currentCtx = undefined;
+  }
+
+  setUICtx(ctx: UICtx): void {
+    this.widget?.setUICtx(ctx);
+  }
+
+  onTurnStart(): void {
+    this.widget?.onTurnStart();
+  }
+
+  markFinished(id: string): void {
+    this.widget?.markFinished(id);
+  }
+
+  updateWidget(): void {
+    this.widget?.update();
+  }
+
+  ensureTimer(): void {
+    this.widget?.ensureTimer();
+  }
+}
+```
+
+### Widget delegation null safety
+
+Current code uses `runtime.widget!.method()` — an unsafe non-null assertion that would throw if widget were null.
+The delegation methods use optional chaining (`this.widget?.method()`), which silently no-ops when widget is null.
+This is safe and intentional: widget is always assigned before any agent can complete, so the null path is unreachable in practice, but the delegation removes the assertion smell.
+The #70 plan explicitly expects this behavior: "Widget null safety: after #87, the runtime's delegation methods handle null internally."
+
+### UICtx type import
+
+`runtime.ts` already imports `AgentActivity` and `AgentWidget` from `ui/agent-widget.ts`.
+Adding `UICtx` to the same type import is consistent with the existing dependency.
+`UICtx` is a lean local interface (two method signatures), not a Pi SDK type.
+
+### What stays unchanged
+
+- `RunConfig` interface — remains as-is.
+- `defaultMaxTurns` / `graceTurns` field writes from settings appliers — out of scope per non-goals.
+- `runtime.currentCtx` reads via getter callbacks (`getCtx: () => runtime.currentCtx`) — reads are not output arguments.
+- `runtime.widget = new AgentWidget(...)` assignment — `widget` stays public.
+- `agentActivity` map usage across notification, tool, and menu deps — unchanged.
+
+## Module-Level Changes
+
+### `src/runtime.ts` (modified)
+
+- Convert `SubagentRuntime` from `export interface` to `export class` with field initializers.
+- Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
+- Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` delegation methods.
+- Add `UICtx` to the existing type import from `./ui/agent-widget.js`.
+- Keep `createSubagentRuntime()` as `() => new SubagentRuntime()` for backward compat.
+- Keep `RunConfig` interface unchanged.
+
+### `src/index.ts` (modified)
+
+- Replace `runtime.currentCtx = { pi, ctx }` with `runtime.setSessionContext(pi, ctx)` (line 126).
+- Replace `runtime.currentCtx = undefined` with `runtime.clearSessionContext()` (line 138).
+- Replace all 8 `runtime.widget!.method()` reach-throughs with `runtime.method()` delegation calls (lines 60, 61, 149, 150, 204–207).
+- No import changes needed — `runtime` is already imported via the factory.
+
+### `test/runtime.test.ts` (modified)
+
+- Add tests for `setSessionContext` / `clearSessionContext` methods.
+- Add tests for each widget delegation method using duck-typed widget stubs.
+- Add test verifying delegation methods no-op when widget is null.
+- Existing tests remain — factory defaults, field mutability, instance isolation, and widget assignment all still apply.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+1. `test/runtime.test.ts` additions — `setSessionContext` sets `currentCtx` correctly; `clearSessionContext` resets it to `undefined`.
+2. `test/runtime.test.ts` additions — Each widget delegation method forwards to the widget's corresponding method; all delegation methods silently no-op when widget is null.
+
+### Existing tests that become redundant
+
+None.
+The existing `runtime.test.ts` tests cover factory defaults, field mutability, and instance isolation — all still valid with the class conversion.
+The "fields are independently mutable" test exercises direct field writes, which remain supported.
+
+### Existing tests that stay as-is
+
+- `test/runtime.test.ts` — All 5 existing tests pass unchanged (the class satisfies the same structural contract as the previous interface-based object).
+- `test/print-mode.test.ts` — Calls `session_shutdown` via the extension's handler map; transparent to runtime internals.
+- All other test files — No dependency on `SubagentRuntime` fields or methods.
+
+## TDD Order
+
+1. **Convert `SubagentRuntime` to a class; add session-context methods.**
+   Convert the interface to a class with field initializers matching current defaults.
+   Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
+   Update `createSubagentRuntime()` to return `new SubagentRuntime()`.
+   Add tests in `runtime.test.ts`: `setSessionContext` sets `currentCtx`; `clearSessionContext` resets to `undefined`; round-trip set→clear.
+   Run existing tests to verify no regressions.
+   Commit: `feat: add session-context methods to SubagentRuntime`
+
+2. **Add widget delegation methods; add tests.**
+   Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` methods to the class.
+   Add `UICtx` to the type import from `./ui/agent-widget.js`.
+   Add tests in `runtime.test.ts`: each delegation method forwards to the widget stub; all methods no-op when widget is null.
+   Commit: `feat: add widget delegation methods to SubagentRuntime`
+
+3. **Migrate all call sites in `index.ts` to use the new methods.**
+   Replace the 2 `currentCtx` writes with `setSessionContext` / `clearSessionContext`.
+   Replace the 8 `widget!` reach-throughs with delegation methods.
+   Run full test suite and `pnpm run check`.
+   Commit: `refactor: use SubagentRuntime methods in extension factory (#87)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                  | Mitigation                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Class conversion breaks code that constructs `SubagentRuntime` as a plain object                      | Only `createSubagentRuntime()` constructs runtime instances (in `index.ts` and tests). The factory is updated to return `new SubagentRuntime()`. No code constructs a `{ ... } as SubagentRuntime` literal. |
+| Widget delegation silently swallows errors when widget is null (changes behavior from throw to no-op) | The null path is unreachable in practice — widget is always assigned before any agent completes. The silent no-op is strictly safer than the `!` assertion. The #70 plan explicitly expects this behavior.  |
+| Adding `UICtx` import to `runtime.ts` increases coupling to the widget module                         | `runtime.ts` already imports `AgentActivity` and `AgentWidget` from the same module. `UICtx` is a lean 2-method interface, not a Pi SDK type. Coupling is minimal and consistent.                           |
+| Remaining output-argument writes (`defaultMaxTurns`, `graceTurns`) are left unaddressed               | Explicitly out of scope per the issue's acceptance criteria. Can be addressed in a follow-up if the pattern becomes painful.                                                                                |
+
+## Open Questions
+
+- Should `createSubagentRuntime()` be removed in favor of `new SubagentRuntime()` directly?
+  The factory adds no value over a no-arg constructor, but removing it widens the blast radius without benefit.
+  Defer — remove it as part of #70 or a future cleanup if it feels redundant.

package/docs/retro/0072-inject-agent-manager-collaborators.md

@@ -0,0 +1,46 @@
+---
+issue: 72
+issue_title: "refactor: dependency-inject AgentManager's collaborators"
+---
+
+# Retro: #72 — dependency-inject AgentManager's collaborators
+
+## Final Retrospective (2026-05-20T17:50:00Z)
+
+### Session summary
+
+Defined `AgentRunner` and `WorktreeManager` interfaces, converted `AgentManager`'s 6-positional-parameter constructor to an options bag with injected collaborators, migrated all 19 test sites from `vi.mock()` to `vi.fn()` stubs, and added 7 new DI-enabled tests.
+The planning phase required significant user redirection to arrive at the right abstractions; the TDD execution phase was clean with zero rework.
+Released as `pi-subagents-v5.6.0`.
+
+### Observations
+
+#### What went well
+
+- The `ask_user` interactions during planning surfaced genuine design decisions (options bag vs positional constructor, lifecycle callback grouping) that the issue body left open.
+  The user's responses were substantive and redirecting.
+- The user's "make the change that makes the change easy" framing identified #84 (`GitWorktreeManager` extraction) as a prerequisite, which made #72's implementation clean — zero type-shuffling needed.
+- The lift-and-shift test migration (Phase B → Phase C) worked exactly as planned: introduce `createManager()` helper under the old constructor, then switch it to the options bag atomically.
+  All 19 test sites migrated with no logic changes.
+- `Promise.withResolvers` (ES2024) in the new queueing test made controlled async coordination clean — no manual resolve/reject wiring.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Spent ~4 analysis cycles on "how to move types between files" (`ToolActivity`, `RunOptions`, `WorktreeInfo` → `types.ts`) when the real question was "what objects want to exist?"
+  The user had to redirect three times: "are there real objects with state?", "what state IS in AgentRunner?", and "we haven't pulled all the threads."
+  Impact: added ~10 minutes of back-and-forth during planning, but ultimately produced a better design (stateful `WorktreeManager` vs stateless `AgentRunner` seam, plus #84 as prep).
+  The dependency-graph analysis itself was sound — it confirmed no circular deps — but it answered a question nobody was asking.
+
+- `premature-convergence` — First draft of the plan included `WorktreeManager` extraction as "Phase A step 1" inside #72.
+  The user asked "did we create another issue that we need to tackle first?"
+  — pointing out that the prep work should be its own issue.
+  Impact: minor rework to update the plan and file #84; no code rework since it was caught during planning. (User-caught.)
+
+#### What caused friction (user side)
+
+- The user's early redirect ("take a step back — does the AgentManager really need six params?") could have been even more direct — e.g., "before we discuss constructor shape, what higher-level abstractions are missing?"
+  That said, the Socratic approach ultimately led to a better shared understanding of why `WorktreeManager` is a real object and `AgentRunner` is a seam.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0072-inject-agent-manager-collaborators.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/index.ts

@@ -57,8 +57,8 @@ export default function (pi: ExtensionAPI) {
   const notifications = createNotificationSystem({
     sendMessage: (msg, opts) => pi.sendMessage(msg as any, opts as any),
     agentActivity: runtime.agentActivity,
-    markFinished: (id) => runtime.widget!.markFinished(id),
-    updateWidget: () => runtime.widget!.update(),
+    markFinished: (id) => runtime.markFinished(id),
+    updateWidget: () => runtime.updateWidget(),
   });
 
   // Background completion: emit lifecycle event and delegate to notification system
@@ -123,7 +123,7 @@ export default function (pi: ExtensionAPI) {
   publishSubagentsService(service);
 
   pi.on("session_start", async (_event, ctx) => {
-    runtime.currentCtx = { pi, ctx };
+    runtime.setSessionContext(pi, ctx);
     manager.clearCompleted();
   });
 
@@ -135,7 +135,7 @@ export default function (pi: ExtensionAPI) {
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
     unpublishSubagentsService();
-    runtime.currentCtx = undefined;
+    runtime.clearSessionContext();
     manager.abortAll();
     notifications.dispose();
     manager.dispose();
@@ -146,8 +146,8 @@ export default function (pi: ExtensionAPI) {
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   pi.on("tool_execution_start", async (_event, ctx) => {
-    runtime.widget!.setUICtx(ctx.ui as UICtx);
-    runtime.widget!.onTurnStart();
+    runtime.setUICtx(ctx.ui as UICtx);
+    runtime.onTurnStart();
   });
 
   /** Build the full type list text dynamically from the unified registry. */
@@ -201,10 +201,10 @@ export default function (pi: ExtensionAPI) {
       listAgents: () => manager.listAgents(),
     },
     widget: {
-      setUICtx: (ctx) => runtime.widget!.setUICtx(ctx as UICtx),
-      ensureTimer: () => runtime.widget!.ensureTimer(),
-      update: () => runtime.widget!.update(),
-      markFinished: (id) => runtime.widget!.markFinished(id),
+      setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
+      ensureTimer: () => runtime.ensureTimer(),
+      update: () => runtime.updateWidget(),
+      markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,
     emitEvent: (name, data) => pi.events.emit(name, data),

package/src/runtime.ts

@@ -6,7 +6,7 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
-import type { AgentActivity, AgentWidget } from "./ui/agent-widget.js";
+import type { AgentActivity, AgentWidget, UICtx } from "./ui/agent-widget.js";
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -23,27 +23,65 @@ export interface RunConfig {
  * Created once inside `piSubagentsExtension()` via `createSubagentRuntime()`.
  * Tests construct a fresh runtime per test for full isolation.
  */
-export interface SubagentRuntime {
+export class SubagentRuntime {
   // ── Execution config (was module-scope in agent-runner.ts) ──────────────
   /** Default max turns for all agents. undefined = unlimited. */
-  defaultMaxTurns: number | undefined;
+  defaultMaxTurns: number | undefined = undefined;
   /** Additional turns allowed after the soft-limit steer message. */
-  graceTurns: number;
+  graceTurns: number = 5;
 
   // ── Session state (was closure-scoped in index.ts) ───────────────────────
   /** Active Pi session context — set on session_start, cleared on session_shutdown. */
-  currentCtx: { pi: unknown; ctx: unknown } | undefined;
+  currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;
   /**
    * Per-agent live activity state shared across the notification system,
    * widget, and tool handlers. The Map itself is never replaced.
    */
-  readonly agentActivity: Map<string, AgentActivity>;
+  readonly agentActivity: Map<string, AgentActivity> = new Map();
   /**
    * Persistent widget reference. Null until constructed after AgentManager.
-   * Notification closures use `runtime.widget!` — safe because agents always
-   * complete after widget construction.
+   * Delegation methods use optional chaining so callers never need `widget!`.
    */
-  widget: AgentWidget | null;
+  widget: AgentWidget | null = null;
+
+  // ── Session-context methods ──────────────────────────────────────────────
+
+  /** Store the active Pi session context (called from session_start). */
+  setSessionContext(pi: unknown, ctx: unknown): void {
+    this.currentCtx = { pi, ctx };
+  }
+
+  /** Clear the session context (called from session_shutdown). */
+  clearSessionContext(): void {
+    this.currentCtx = undefined;
+  }
+
+  // ── Widget delegation methods ─────────────────────────────────────────────
+
+  /** Delegate to widget.setUICtx — no-op when widget is null. */
+  setUICtx(ctx: UICtx): void {
+    this.widget?.setUICtx(ctx);
+  }
+
+  /** Delegate to widget.onTurnStart — no-op when widget is null. */
+  onTurnStart(): void {
+    this.widget?.onTurnStart();
+  }
+
+  /** Delegate to widget.markFinished — no-op when widget is null. */
+  markFinished(id: string): void {
+    this.widget?.markFinished(id);
+  }
+
+  /** Delegate to widget.update — no-op when widget is null. */
+  updateWidget(): void {
+    this.widget?.update();
+  }
+
+  /** Delegate to widget.ensureTimer — no-op when widget is null. */
+  ensureTimer(): void {
+    this.widget?.ensureTimer();
+  }
 }
 
 /**
@@ -52,11 +90,5 @@ export interface SubagentRuntime {
  * Call once at extension startup; pass the result to factories and handlers.
  */
 export function createSubagentRuntime(): SubagentRuntime {
-  return {
-    defaultMaxTurns: undefined,
-    graceTurns: 5,
-    currentCtx: undefined,
-    agentActivity: new Map(),
-    widget: null,
-  };
+  return new SubagentRuntime();
 }