@gotgenes/pi-subagents 5.5.0 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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)
+
+
+### Features
+
+* convert AgentManager to options-bag constructor with DI ([1292cec](https://github.com/gotgenes/pi-packages/commit/1292cec60c24d8e657985c53b9b3413089c2a79d))
+* define AgentRunner interface in agent-runner.ts ([6a3c85a](https://github.com/gotgenes/pi-packages/commit/6a3c85a445daf0e4e8c01620eb6ae1a8237f1766))
+
+
+### Documentation
+
+* mark [#84](https://github.com/gotgenes/pi-packages/issues/84) as done in plan ([#72](https://github.com/gotgenes/pi-packages/issues/72)) ([5cfa1ec](https://github.com/gotgenes/pi-packages/commit/5cfa1ecf080f95fbd6b4aec05b27cc9672f60267))
+* **retro:** add retro notes for issue [#84](https://github.com/gotgenes/pi-packages/issues/84) ([99d9016](https://github.com/gotgenes/pi-packages/commit/99d90161df5fe9d302514e33c2d2d9fbfb248f25))
+
 ## [5.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.4.1...pi-subagents-v5.5.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/0072-inject-agent-manager-collaborators.md

@@ -35,7 +35,7 @@ Any test of `AgentManager` must mock entire modules via `vi.mock()`, coupling th
 | #71   | Extract pure agent-session assembler                | ✓ Done  |
 | #76   | Inject `cwd` into `AgentManager`                    | ✓ Done  |
 | #80   | Consolidate `getConfig`/`getAgentConfig`            | ✓ Done  |
-| #84   | Extract `GitWorktreeManager` class from worktree.ts | Pending |
+| #84   | Extract `GitWorktreeManager` class from worktree.ts | ✓ Done  |
 
 ### Prior art
 
@@ -201,7 +201,7 @@ expect(runner.run).toHaveBeenCalled();
 
 ### `src/worktree.ts` (no changes in this issue)
 
-`WorktreeManager` interface and `GitWorktreeManager` class are added by prerequisite #84.
+`WorktreeManager` interface and `GitWorktreeManager` class were added by #84.
 
 ### `src/agent-runner.ts` (modified)