@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0069-create-subagent-runtime.md

@@ -1,345 +0,0 @@
----
-issue: 69
-issue_title: "refactor: eliminate module-scope mutable state in pi-subagents — create SubagentRuntime"
----
-
-# Create SubagentRuntime
-
-## Problem Statement
-
-`pi-subagents` still uses pre-refactor patterns that `pi-permission-system` eliminated in #43.
-`agent-runner.ts` holds module-scope mutable `let` variables (`defaultMaxTurns`, `graceTurns`) with getter/setter pairs that are called from `settings.ts` via callback injection.
-`index.ts` holds closure-scoped `let` variables (`currentCtx`, `widget`) and a `Map` (`agentActivity`) that are captured by arrow closures and cannot be tested in isolation.
-Both patterns hide real dependencies behind module-scope and closure-scope state, making isolated testing impossible.
-
-## Goals
-
-- Introduce a `SubagentRuntime` interface and `createSubagentRuntime()` factory in a new `src/runtime.ts`.
-- Move `defaultMaxTurns`, `graceTurns`, `agentActivity`, `currentCtx`, and the widget reference into the runtime.
-- Thread `defaultMaxTurns` and `graceTurns` through `RunOptions` so `agent-runner.ts` reads them from its call-time options — not from module scope.
-- Give `AgentManager` a config getter so it can pass runtime values in `RunOptions`.
-- Reduce `index.ts` to a composition root that creates the runtime and passes it to factories — no closure-scoped mutable `let` variables remain.
-- Remove the module-scope `let` declarations and getter/setter exports from `agent-runner.ts`.
-- No behavior change; pure structural refactor.
-
-## Non-Goals
-
-- Refactoring `AgentManager` into an options-object constructor (follow-up cleanup).
-- Extracting event handlers into separate files.
-- Changing tool behavior or the `SubagentsService` interface.
-- Changing the `SettingsAppliers` interface in `settings.ts` — the callback pattern is already clean; only the closure targets change.
-
-## Background
-
-### Prior art
-
-`pi-permission-system` solved the identical problem in #43.
-`src/runtime.ts` there defines an `ExtensionRuntime` interface with all mutable state, a `createExtensionRuntime()` factory, and pure helper functions like `refreshExtensionConfig(runtime, ctx)` that write to the runtime instead of module-scope variables.
-The extension's `index.ts` calls `createExtensionRuntime()` once and passes the runtime to handlers and factories.
-This plan follows the same pattern.
-
-### Module-scope state in agent-runner.ts
-
-Two `let` variables and four getter/setter exports:
-
-```typescript
-let defaultMaxTurns: number | undefined;
-let graceTurns = 5;
-
-export function getDefaultMaxTurns(): number | undefined { ... }
-export function setDefaultMaxTurns(n: number | undefined): void { ... }
-export function getGraceTurns(): number { ... }
-export function setGraceTurns(n: number): void { ... }
-```
-
-`runAgent` reads both from module scope during the turn-limit subscription callback:
-
-```typescript
-const maxTurns = normalizeMaxTurns(
-  options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns,
-);
-// ...
-} else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
-```
-
-### Closure-scoped state in index.ts
-
-```typescript
-const agentActivity = new Map<string, AgentActivity>();
-let widget: AgentWidget;
-let currentCtx: { pi: unknown; ctx: unknown } | undefined;
-```
-
-`widget` is assigned *after* `AgentManager` construction, but `notifications` closes over it immediately via arrow callbacks (`(id) => widget.markFinished(id)`).
-`currentCtx` is written by `session_start` and read by `createSubagentsService`.
-`agentActivity` is shared across the notification system, widget, agent tool, and menu handler.
-
-### Settings flow
-
-`settings.ts` defines `SettingsAppliers` with three setter callbacks.
-`applyAndEmitLoaded(appliers, emit)` loads persisted settings and calls them.
-`index.ts` wires the appliers to `setDefaultMaxTurns` / `setGraceTurns` from `agent-runner.ts` and `manager.setMaxConcurrent`.
-After this refactor, the appliers closure targets change to the runtime — the `SettingsAppliers` interface itself stays the same.
-
-### Data flow for defaultMaxTurns / graceTurns
-
-Current: `settings.ts → setDefaultMaxTurns() → module-scope let → runAgent reads module scope`.
-
-After: `settings.ts → applier closure → runtime.defaultMaxTurns → AgentManager.getRunConfig() → RunOptions → runAgent reads options`.
-
-### Relevant constraints from AGENTS.md
-
-- Keep modules focused and composable (one concern per file).
-- Prefer explicit configuration over hidden behavior.
-- Pi SDK imports stay out of business-logic modules — `runtime.ts` must not import Pi SDK types.
-- Do not read `process.env` / `process.cwd()` inside library functions — accept as parameter.
-- Narrow interfaces per consumer — do not pass a shared dependency bag when a function only uses a subset.
-
-## Design Overview
-
-### SubagentRuntime interface
-
-```typescript
-export interface SubagentRuntime {
-  // ── Execution config (was module-scope in agent-runner.ts) ──
-  defaultMaxTurns: number | undefined;
-  graceTurns: number;
-
-  // ── Session state (was closure-scoped in index.ts) ──
-  currentCtx: { pi: unknown; ctx: unknown } | undefined;
-  readonly agentActivity: Map<string, AgentActivity>;
-  widget: AgentWidget | null;
-}
-```
-
-The interface is flat (no sub-objects) to match the prior art in `pi-permission-system`.
-`agentActivity` is `readonly` because the Map itself is never replaced — only its entries change.
-`widget` is nullable because it is constructed after `AgentManager` and assigned later.
-
-### createSubagentRuntime factory
-
-```typescript
-export function createSubagentRuntime(): SubagentRuntime {
-  return {
-    defaultMaxTurns: undefined,
-    graceTurns: 5,
-    currentCtx: undefined,
-    agentActivity: new Map(),
-    widget: null,
-  };
-}
-```
-
-No parameters needed — the factory returns defaults.
-Tests construct a fresh runtime per test for isolation.
-
-### RunConfig — narrow interface for agent-manager
-
-```typescript
-export interface RunConfig {
-  readonly defaultMaxTurns: number | undefined;
-  readonly graceTurns: number;
-}
-```
-
-`AgentManager` receives `getRunConfig?: () => RunConfig` as a constructor parameter.
-When constructing `RunOptions` for `runAgent`, it calls `getRunConfig()` and spreads the values.
-During the lift-and-shift phase (before module-scope removal), `runAgent` falls back to the module-scope values when the RunOptions fields are absent.
-
-### RunOptions changes
-
-Two new optional fields:
-
-```typescript
-export interface RunOptions {
-  // ... existing fields ...
-  /** Default max turns from runtime config. Overridden by per-agent maxTurns. */
-  defaultMaxTurns?: number;
-  /** Grace turns after soft limit steer. */
-  graceTurns?: number;
-}
-```
-
-`runAgent` changes its resolution chain from:
-
-```typescript
-const maxTurns = normalizeMaxTurns(
-  options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns,
-);
-```
-
-To:
-
-```typescript
-const maxTurns = normalizeMaxTurns(
-  options.maxTurns ?? agentConfig?.maxTurns ?? options.defaultMaxTurns,
-);
-const effectiveGraceTurns = options.graceTurns ?? 5;
-```
-
-### normalizeMaxTurns stays in agent-runner.ts
-
-`normalizeMaxTurns` is a pure function used by both the runtime setter logic (in `index.ts` wire-up) and `runAgent`'s maxTurns resolution.
-It stays exported from `agent-runner.ts`.
-
-### index.ts wire-up changes
-
-After refactoring, the extension factory:
-
-1. Calls `createSubagentRuntime()` to get the runtime.
-2. Wires `applyAndEmitLoaded` appliers to write to `runtime.defaultMaxTurns` and `runtime.graceTurns` (with normalization).
-3. Passes `getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns })` to `AgentManager`.
-4. Uses `runtime.agentActivity` instead of a local `const agentActivity`.
-5. Uses `runtime.currentCtx` instead of a local `let currentCtx`.
-6. Sets `runtime.widget = new AgentWidget(...)` instead of a local `let widget`.
-7. Arrow closures in notification deps, tool deps, and menu deps reference `runtime.widget!` / `runtime.agentActivity` / `runtime.currentCtx` by capturing `runtime` by reference.
-
-No closure-scoped `let` variables remain.
-
-### Edge cases
-
-- **Widget null access**: Notification system callbacks reference `runtime.widget!.markFinished(id)`.
-  This is safe because notifications only fire after agents complete, which is always after widget construction.
-  The `!` assertion documents the invariant.
-- **currentCtx undefined**: `getCtx: () => runtime.currentCtx` behaves identically to the current `() => currentCtx` — the arrow closure captures the runtime object by reference and reads the field at call time.
-- **Backward compatibility during lift-and-shift**: During intermediate steps, `runAgent` falls back to module-scope state when `options.defaultMaxTurns` / `options.graceTurns` are absent, so the test suite stays green throughout.
-
-## Module-Level Changes
-
-### `src/runtime.ts` (new)
-
-- `SubagentRuntime` interface — all mutable state fields.
-- `RunConfig` interface — narrow config subset for `AgentManager`.
-- `createSubagentRuntime()` factory — returns a fresh runtime with defaults.
-
-### `src/agent-runner.ts` (modified)
-
-- Add `defaultMaxTurns?: number` and `graceTurns?: number` to `RunOptions`.
-- Update `runAgent`'s maxTurns resolution to prefer `options.defaultMaxTurns` over module scope (step 2), then remove module scope entirely (step 6).
-- Update `graceTurns` usage in the turn-limit callback to prefer `options.graceTurns` over module scope (step 2), then remove fallback (step 6).
-- Remove `let defaultMaxTurns`, `let graceTurns`, `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns` exports (step 6).
-- `normalizeMaxTurns` stays exported (pure function, no state dependency).
-
-### `src/agent-manager.ts` (modified)
-
-- Add optional `getRunConfig?: () => RunConfig` parameter to constructor.
-- In `startAgent`, call `getRunConfig?.()` and pass `defaultMaxTurns` and `graceTurns` in the `RunOptions` object given to `runAgent`.
-
-### `src/index.ts` (modified)
-
-- Import `createSubagentRuntime` from `./runtime.js`.
-- Create `const runtime = createSubagentRuntime()` at the top of the factory.
-- Replace `const agentActivity = new Map<>()` with `runtime.agentActivity`.
-- Replace `let widget: AgentWidget` with `runtime.widget`.
-- Replace `let currentCtx` with `runtime.currentCtx`.
-- Wire `applyAndEmitLoaded` appliers to `runtime.defaultMaxTurns` / `runtime.graceTurns` with normalization.
-- Pass `getRunConfig` to `AgentManager` constructor.
-- Update `snapshotSettings` to read from `runtime.defaultMaxTurns` / `runtime.graceTurns`.
-- Remove imports of `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns` from `agent-runner.js`.
-- All arrow closures in notification, tool, menu, and service deps capture `runtime` by reference.
-
-### `test/runtime.test.ts` (new)
-
-- Factory returns expected defaults.
-- Fields are independently mutable.
-- Multiple instances are isolated.
-
-### `test/agent-runner-settings.test.ts` (modified → removed or substantially rewritten)
-
-- Current tests exercise `setDefaultMaxTurns` / `getDefaultMaxTurns` / `setGraceTurns` / `getGraceTurns` as module-scope getters/setters.
-- After step 6 removes those exports, these tests must migrate.
-- `normalizeMaxTurns` tests stay as-is (the function remains exported).
-- Setter-behavior tests (clamping, unlimited marker) become tests of the normalization logic applied in `index.ts` wire-up or `runtime.test.ts`.
-- The `runAgent` integration with `defaultMaxTurns` / `graceTurns` is tested via RunOptions in `agent-runner.test.ts`.
-
-### `test/agent-manager.test.ts` (modified)
-
-- Constructor calls gain `getRunConfig` parameter (or omit it — default is no-op).
-- Existing tests pass `undefined` for `getRunConfig` (backward compatible).
-- New tests verify that `runAgent` receives `defaultMaxTurns` / `graceTurns` from `getRunConfig`.
-
-## Test Impact Analysis
-
-### New unit tests enabled by the extraction
-
-1. `test/runtime.test.ts` — `createSubagentRuntime` factory returns correct defaults, fields are independently mutable, multiple instances don't share state.
-2. `test/agent-runner.test.ts` additions — `runAgent` uses `options.defaultMaxTurns` and `options.graceTurns` when provided, with correct fallback behavior.
-3. `test/agent-manager.test.ts` additions — `AgentManager` calls `getRunConfig()` and passes values in `RunOptions`.
-
-### Existing tests that become redundant
-
-- `test/agent-runner-settings.test.ts` tests for `setDefaultMaxTurns` / `getDefaultMaxTurns` / `setGraceTurns` / `getGraceTurns` — these getter/setter pairs are removed.
-  The normalization behavior they test is preserved via `normalizeMaxTurns` (which stays) and runtime wire-up tests.
-
-### Existing tests that stay as-is
-
-- `test/settings.test.ts` — tests `SettingsAppliers` via mock callbacks; interface unchanged.
-- `test/service-adapter.test.ts` — tests `AdapterDeps` via mock callbacks; `getCtx` interface unchanged.
-- `test/agent-runner.test.ts` — existing final-output-capture and usage-callback tests are unaffected (they don't test maxTurns/graceTurns state).
-- All other test files (agent-types, custom-agents, notification, renderer, tools, UI, etc.) — no dependency on the moved state.
-
-## TDD Order
-
-1. **Create `src/runtime.ts` with SubagentRuntime interface and factory.**
-   Write `test/runtime.test.ts` testing factory defaults and instance isolation.
-   Commit: `feat: add SubagentRuntime interface and factory`
-
-2. **Add `defaultMaxTurns` and `graceTurns` to RunOptions; update `runAgent` to prefer them over module scope.**
-   In `agent-runner.ts`, add two optional fields to `RunOptions`.
-   Change maxTurns resolution to `options.maxTurns ?? agentConfig?.maxTurns ?? options.defaultMaxTurns ?? defaultMaxTurns` (backward compatible — module-scope fallback retained).
-   Change graceTurns usage to `options.graceTurns ?? graceTurns` (module-scope fallback retained).
-   Add tests in `agent-runner.test.ts` verifying that when `options.defaultMaxTurns` / `options.graceTurns` are provided, they are used.
-   Run `pnpm run check` to verify types.
-   Commit: `feat: thread defaultMaxTurns and graceTurns through RunOptions`
-
-3. **Wire `AgentManager` to pass runtime config in RunOptions.**
-   Add `getRunConfig?: () => RunConfig` as the 5th constructor parameter (optional, backward compatible).
-   In `startAgent`, call `getRunConfig?.()` and spread into the RunOptions for `runAgent`.
-   Add agent-manager test verifying `runAgent` receives the config values.
-   Existing tests omit the param — green with no changes.
-   Commit: `refactor: agent-manager threads run config into RunOptions`
-
-4. **Wire SubagentRuntime into index.ts — replace closure-scoped state.**
-   Import `createSubagentRuntime` and call it at the top of the factory.
-   Replace `const agentActivity`, `let widget`, and `let currentCtx` with runtime fields.
-   Wire settings appliers to `runtime.defaultMaxTurns` (via `normalizeMaxTurns`) and `runtime.graceTurns` (via `Math.max(1, n)`).
-   Pass `getRunConfig` callback to `AgentManager`.
-   Update `snapshotSettings` to read from runtime.
-   Remove imports of `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`.
-   Run full test suite.
-   Commit: `refactor: wire SubagentRuntime into extension factory`
-
-5. **Remove module-scope state from `agent-runner.ts`.**
-   Delete `let defaultMaxTurns`, `let graceTurns`, and all four getter/setter functions.
-   Remove the module-scope fallback from `runAgent`'s resolution chain — `options.defaultMaxTurns` and `options.graceTurns` are now the sole source (with hardcoded defaults as a safety net: `undefined` and `5`).
-   Update `test/agent-runner-settings.test.ts`: remove tests for deleted getters/setters, keep `normalizeMaxTurns` tests.
-   Run `pnpm run check` and full test suite.
-   Commit: `refactor: remove module-scope mutable state from agent-runner`
-
-6. **Final cleanup and acceptance verification.**
-   Verify acceptance criteria: `agent-runner.ts` contains no module-scope mutable state.
-   `index.ts` contains no closure-scoped `let` variables that outlive their initialization block.
-   `SubagentRuntime` interface exists with all mutable session state.
-   Tests can construct a runtime and pass it to factories without importing `index.ts`.
-   Full test suite passes.
-   Remove any dead imports or vestigial code.
-   Commit: `refactor: finalize SubagentRuntime migration (#69)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                                              | Mitigation                                                                                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Backward-compatibility break during incremental migration — removing module-scope state before all consumers switch to RunOptions | Lift-and-shift: steps 2–3 introduce the new path alongside the old (module-scope fallback); step 5 removes the old path only after all consumers use the new path.                                                         |
-| AgentManager constructor gains a 5th positional parameter — fragile and hard to read                                              | Parameter is optional with no default behavior change. Plan notes this as a follow-up cleanup (convert to options object).                                                                                                 |
-| `runtime.widget!` non-null assertions in notification closures could NPE if initialization order changes                          | Assertion documents the invariant; widget is always constructed before any agent can complete. Add a defensive `if (!runtime.widget) return;` guard in the notification callbacks as a safety net.                         |
-| `normalizeMaxTurns` stays in `agent-runner.ts` after getter/setter removal — unclear ownership                                    | `normalizeMaxTurns` is a pure function used by the turn-limit logic in `runAgent`. It belongs in the module that uses it. If a future refactor moves turn-limit logic, the function moves with it.                         |
-| Test file `agent-runner-settings.test.ts` needs substantial rewrite — risk of losing coverage                                     | Keep `normalizeMaxTurns` tests intact (they test the same pure function). The setter/getter behavior tests are replaced by runtime factory tests and RunOptions integration tests that cover the same normalization logic. |
-
-## Open Questions
-
-- Should `AgentManager`'s constructor be converted from positional parameters to a named-options object?
-  This is natural cleanup but widens the blast radius.
-  Defer to a follow-up issue if the 5th positional parameter feels too fragile during implementation.
-- Should `SubagentRuntime` include utility methods (e.g., `reset()`, `shutdown()`) for session lifecycle?
-  The issue's acceptance criteria focus on state ownership, not lifecycle methods.
-  Defer until a pattern of scattered resets emerges in practice.

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

@@ -1,306 +0,0 @@
----
-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.