@gotgenes/pi-subagents 5.0.0 → 5.2.0

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

@@ -0,0 +1,345 @@
+---
+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/retro/0049-remove-group-join-output-file-rpc.md

@@ -23,15 +23,26 @@ A new issue (#61) was filed to port the output-file format to Pi's official JSON
 
 #### What caused friction (agent side)
 
-- `missing-context` — Included `output-file.ts` removal in the initial plan without questioning its debugging value, despite AGENTS.md's rule "Ask before removing functionality or changing defaults." The issue body explicitly listed it for removal so I followed the spec literally. Impact: required plan revision (amend commit), scope-narrowing comment on issue, and filing #61 — roughly 10 minutes of rework, but produced a better design.
+- `missing-context` — Included `output-file.ts` removal in the initial plan without questioning its debugging value, despite AGENTS.md's rule "Ask before removing functionality or changing defaults."
+  The issue body explicitly listed it for removal so I followed the spec literally.
+  Impact: required plan revision (amend commit), scope-narrowing comment on issue, and filing #61 — roughly 10 minutes of rework, but produced a better design.
 
-- `missing-context` — When asked whether output-file adheres to Pi's session format, searched the web (`web_search` for "Claude Code session JSONL format") instead of checking the local `~/development/pi/pi` monorepo. The user had to explicitly say "~/development/pi/pi has the code for Pi's JSONL format." Impact: one extra round-trip and less authoritative initial answer (Claude Code's format vs Pi's `SessionManager`). Self-identified after user redirect.
+- `missing-context` — When asked whether output-file adheres to Pi's session format, searched the web (`web_search` for "Claude Code session JSONL format") instead of checking the local `~/development/pi/pi` monorepo.
+  The user had to explicitly say "~/development/pi/pi has the code for Pi's JSONL format."
+  Impact: one extra round-trip and less authoritative initial answer (Claude Code's format vs Pi's `SessionManager`).
+  Self-identified after user redirect.
 
-- `instruction-violation` (self-identified) — Shell-escaped the `gh issue comment` body incorrectly; backtick-wrapped `src/output-file.ts` was interpreted by bash. Caught immediately via `gh issue view` and fixed with `--edit-last`. Impact: trivial — one extra command.
+- `instruction-violation` (self-identified) — Shell-escaped the `gh issue comment` body incorrectly; backtick-wrapped `src/output-file.ts` was interpreted by bash.
+  Caught immediately via `gh issue view` and fixed with `--edit-last`.
+  Impact: trivial — one extra command.
 
 #### What caused friction (user side)
 
-- The issue body listed output-file for removal without noting its debugging value. The user's "How confident are we in getting rid of the logging system?" intervention was the correction. If the issue had marked output-file removal as "tentative pending debugging value assessment," the plan would have surfaced it as a design decision from the start. Minor — the discussion was quick and productive.
+- The issue body listed output-file for removal without noting its debugging value.
+  The user's "How confident are we in getting rid of the logging system?"
+  intervention was the correction.
+  If the issue had marked output-file removal as "tentative pending debugging value assessment," the plan would have surfaced it as a design decision from the start.
+  Minor — the discussion was quick and productive.
 
 ### Changes made
 

package/docs/retro/0051-update-adr-0001-hard-fork.md

@@ -22,12 +22,16 @@ The change was planned, implemented, shipped, and released as `pi-subagents-v1.0
 
 #### What caused friction (agent side)
 
-- No friction observed. The task was unambiguous and the tooling well-suited.
+- No friction observed.
+  The task was unambiguous and the tooling well-suited.
 
 #### What caused friction (user side)
 
-- No friction observed. The session required no user input beyond invoking the three slash commands.
+- No friction observed.
+  The session required no user input beyond invoking the three slash commands.
 
 ### Follow-ups identified
 
-- The `package-pi-subagents` skill (`.pi/skills/package-pi-subagents/SKILL.md`) still frames the fork as "a friendly fork… carrying a small number of patches" with priorities like "stays as close to upstream as possible." This framing is now stale given the hard-fork commitment. A separate issue should update the skill to reflect the architecture document's posture.
+- The `package-pi-subagents` skill (`.pi/skills/package-pi-subagents/SKILL.md`) still frames the fork as "a friendly fork… carrying a small number of patches" with priorities like "stays as close to upstream as possible."
+  This framing is now stale given the hard-fork commitment.
+  A separate issue should update the skill to reflect the architecture document's posture.

package/docs/retro/0053-extract-model-resolution-from-execute.md

@@ -17,14 +17,24 @@ Also fixed a pre-existing `rumdl` glob-quoting bug in `package.json` discovered
 
 #### What went well
 
-- Pre-existing lint bug surfaced and fixed: the `rumdl check '*.md' 'docs/**/*.md'` command in `package.json` used single-quoted globs that prevented shell expansion. Verified as pre-existing (reproduced on prior commit via `git stash`), cleanly isolated into its own `fix:` commit. This was a genuine find — the lint had been silently broken.
+- Pre-existing lint bug surfaced and fixed: the `rumdl check '*.md' 'docs/**/*.md'` command in `package.json` used single-quoted globs that prevented shell expansion.
+  Verified as pre-existing (reproduced on prior commit via `git stash`), cleanly isolated into its own `fix:` commit.
+  This was a genuine find — the lint had been silently broken.
 
 #### What caused friction (agent side)
 
-- `missing-context` — In step 6 (refactoring `index.ts`), replaced the `resolveModel` import with `resolveInvocationModel` without first checking whether `resolveModel` was still used elsewhere in the file. Two other call sites (`createSubagentsService` at line 386 and `getModelLabel` at line 1043) still needed it. The plan explicitly listed `getModelLabel` as a non-goal that continues using `resolveModel`, so the information was available. Caught immediately via `grep` after the edit and fixed in the same commit. Impact: one extra edit + grep cycle, no rework.
+- `missing-context` — In step 6 (refactoring `index.ts`), replaced the `resolveModel` import with `resolveInvocationModel` without first checking whether `resolveModel` was still used elsewhere in the file.
+  Two other call sites (`createSubagentsService` at line 386 and `getModelLabel` at line 1043) still needed it.
+  The plan explicitly listed `getModelLabel` as a non-goal that continues using `resolveModel`, so the information was available.
+  Caught immediately via `grep` after the edit and fixed in the same commit.
+  Impact: one extra edit + grep cycle, no rework.
 
-- `missing-context` — The plan's type definitions specified `model: unknown` for `ModelResolutionResult`, but downstream code in `index.ts` accesses `.id` and `.name` on the model and passes it where `Model<any>` is expected. The plan's risk section flagged this ("reducing but not eliminating the `any`"), yet the implementation went with `unknown` first, requiring a correction after `pnpm run check` failed with 4 type errors. Changed to `model: any` to match the existing `resolveModel` return type. Impact: one extra edit cycle within the same commit, no rework.
+- `missing-context` — The plan's type definitions specified `model: unknown` for `ModelResolutionResult`, but downstream code in `index.ts` accesses `.id` and `.name` on the model and passes it where `Model<any>` is expected.
+  The plan's risk section flagged this ("reducing but not eliminating the `any`"), yet the implementation went with `unknown` first, requiring a correction after `pnpm run check` failed with 4 type errors.
+  Changed to `model: any` to match the existing `resolveModel` return type.
+  Impact: one extra edit cycle within the same commit, no rework.
 
 #### What caused friction (user side)
 
-- None observed. The issue was well-scoped with clear acceptance criteria, making planning and execution straightforward.
+- None observed.
+  The issue was well-scoped with clear acceptance criteria, making planning and execution straightforward.

package/docs/retro/0054-decompose-index-into-modules.md

@@ -18,20 +18,35 @@ Filed follow-up #66 (replace `as any` casts with proper SDK types) and #67 (flak
 
 #### What went well
 
-- Leaf-first extraction order worked cleanly — helpers, then renderer, then notification, then tools, then menu. Each step left the repo green with no cascading breakage.
+- Leaf-first extraction order worked cleanly — helpers, then renderer, then notification, then tools, then menu.
+  Each step left the repo green with no cascading breakage.
 - The `createNotificationSystem` factory pattern with arrow-closure capture of `widget` (assigned after `AgentManager` construction) preserved the existing deferred-reference semantics without restructuring initialization order.
 
 #### What caused friction (agent side)
 
-- `wrong-abstraction` — Applied the code-style skill's "keep Pi SDK imports out of business-logic modules" rule to tool/menu modules, which are SDK consumers, not business logic. Used `unknown` for `ExtensionContext`, `AgentSession`, `ModelRegistry` in factory dep interfaces, requiring 9 `as any` casts in `index.ts`. User caught this post-ship. Impact: filed #66 as a follow-up cleanup; the casts are cosmetic (no runtime effect) but degrade type safety. Fixed the code-style skill to clarify the boundary. (user-caught)
+- `wrong-abstraction` — Applied the code-style skill's "keep Pi SDK imports out of business-logic modules" rule to tool/menu modules, which are SDK consumers, not business logic.
+  Used `unknown` for `ExtensionContext`, `AgentSession`, `ModelRegistry` in factory dep interfaces, requiring 9 `as any` casts in `index.ts`.
+  User caught this post-ship.
+  Impact: filed #66 as a follow-up cleanup; the casts are cosmetic (no runtime effect) but degrade type safety.
+  Fixed the code-style skill to clarify the boundary. (user-caught)
 
-- `missing-context` — Four test files (`notification.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`, `agent-tool.test.ts`) omitted `compactionCount: 0` from `AgentRecord` factories. Caught at the final `pnpm run check` step, not during test writing. The testing skill already says "grep for ALL test files that construct a compatible mock." Impact: one extra fix cycle delegated to a subagent, no rework beyond that step. (self-identified)
+- `missing-context` — Four test files (`notification.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`, `agent-tool.test.ts`) omitted `compactionCount: 0` from `AgentRecord` factories.
+  Caught at the final `pnpm run check` step, not during test writing.
+  The testing skill already says "grep for ALL test files that construct a compatible mock."
+  Impact: one extra fix cycle delegated to a subagent, no rework beyond that step. (self-identified)
 
-- `other` — `Edit` tool failed 3 times matching the UTF-8 middle dot (`·`, U+00B7) in the steer tool's `stateParts.join(" · ")` line. The third attempt produced a partial match that left the file in a broken state (dangling orphan code after the replacement anchor). Required `git restore` and a fallback to `python3` line-range replacement. The same `python3` approach for the menu extraction lost the closing `}` of the default export function. Impact: ~5 minutes of rework across the two extraction steps, plus one `git restore`.
+- `other` — `Edit` tool failed 3 times matching the UTF-8 middle dot (`·`, U+00B7) in the steer tool's `stateParts.join(" · ")` line.
+  The third attempt produced a partial match that left the file in a broken state (dangling orphan code after the replacement anchor).
+  Required `git restore` and a fallback to `python3` line-range replacement.
+  The same `python3` approach for the menu extraction lost the closing `}` of the default export function.
+  Impact: ~5 minutes of rework across the two extraction steps, plus one `git restore`.
 
 #### What caused friction (user side)
 
-- The `as any` casts could have been caught earlier if the user had flagged the `unknown` types during the planning phase. However, the plan didn't prescribe exact interface types — that was an implementation decision. The user's post-ship review ("Why did we have to cast `as any`? Take a look at `packages/pi-permission-system/` as a model") was an efficient redirect that immediately scoped the investigation.
+- The `as any` casts could have been caught earlier if the user had flagged the `unknown` types during the planning phase.
+  However, the plan didn't prescribe exact interface types — that was an implementation decision.
+  The user's post-ship review ("Why did we have to cast `as any`?
+  Take a look at `packages/pi-permission-system/` as a model") was an efficient redirect that immediately scoped the investigation.
 
 ### Changes made
 

package/docs/retro/0057-structured-debug-logging.md

@@ -0,0 +1,77 @@
+---
+issue: 57
+issue_title: "feat: structured debug logging for silenced catch blocks"
+---
+
+# Retro: #57 — structured debug logging for silenced catch blocks
+
+## Final Retrospective (2026-05-19T10:30:00Z)
+
+### Session summary
+
+Added `src/debug.ts` with `debugLog` and `isDebug()`, then threaded `debugLog` into ~20 silent `catch` blocks across 9 files.
+All 7 TDD cycles went green on the first pass with no rework.
+Shipped as `pi-subagents-v5.1.0`, then followed up with a `refactor:` commit converting `DEBUG` (module-level constant) to `isDebug()` (function getter) during the retro.
+
+### Observations
+
+#### What went well
+
+- The plan's "Non-Goals" section correctly excluded `usage.ts` and `settings.ts` before implementation started, and a post-TDD `grep -rn 'catch\s*{'` confirmed only those two in-scope-excluded files remained.
+  Closing the loop with a verification query is worth repeating.
+- The scope of the change was so well-defined (the issue listed exact file names) that no `ask_user` call was needed during planning.
+
+#### What caused friction (agent side)
+
+- `missing-context` — When loading the `ask-user` skill I guessed `.pi/skills/ask-user/SKILL.md` before reading the actual `<location>` tag in `AGENTS.md`, triggering an ENOENT error and a follow-up `find` call.
+  Impact: 2 extra tool calls, no rework. (self-identified)
+
+- `other` — The plan's TDD Order step 1 stated *"the test skill documents this pattern"* for `vi.resetModules()` + dynamic import when testing module-level env constants — but the testing skill does not have that entry.
+  The aspiration was recorded rather than verified.
+  During the retro, the user's question ("should that be a function getter instead?") led to a better outcome: replace the module-level constant with `isDebug()` so `vi.stubEnv()` alone works, consistent with how every other `process.env` read in this codebase is structured.
+  Impact: one retro-phase `refactor:` commit; the approach shipped in `v5.1.0` was technically correct but unnecessarily complex to test.
+
+#### What caused friction (user side)
+
+- The initial issue proposal chose the module-level-constant pattern (common in Node.js tooling like the `debug` package).
+  A note in the issue or plan about preferring function-based env reads for testability would have caught this at design time rather than post-ship.
+  That said, the retro question was efficient — a single targeted redirect resolved it cleanly.
+
+### Changes made
+
+1. `packages/pi-subagents/src/debug.ts` — replaced `export const DEBUG` with `export function isDebug()`.
+2. `packages/pi-subagents/test/debug.test.ts` — simplified to static import + `vi.stubEnv()` only; removed all `vi.resetModules()` + dynamic `import()` calls.
+3. `.pi/skills/testing/SKILL.md` — added bullet: prefer reading `process.env` inside functions; `vi.stubEnv()` alone is insufficient for module-level constants.
+
+## Follow-up Retrospective (2026-05-19T11:15:00Z)
+
+### Session summary
+
+The user asked how many `process.*` reads exist in `pi-subagents`.
+Audit found 9 sites: 4 acceptable (wiring layer, detection functions, injectable defaults), 2 genuine injection gaps, and 1 mild case.
+Filed #76 (`AgentManager.dispose()` reads `process.cwd()` without a stored `cwd`) and #77 (`createAgentsMenuHandler` hardcodes `process.cwd()` when `AgentMenuDeps` already injects the personal-side equivalent).
+
+### Observations
+
+#### What went well
+
+- The `isDebug()` refactor naturally led the user to ask a broader design question about `process.*` access patterns, producing two well-scoped follow-up issues without manual triage.
+- The audit categorization (genuinely problematic vs. acceptable) was clean — presenting a table with verdicts per site let the user decide scope without re-reading source.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — The original plan accepted the module-level `DEBUG` constant without checking how the rest of the codebase reads `process.env`.
+  The code-style skill said "keep IO at the edges" but didn't name `process.*` specifically, so the rule wasn't applied.
+  Impact: one post-ship `refactor:` commit to replace `DEBUG` with `isDebug()`; the pattern was technically correct but inconsistent with codebase conventions. (user-caught)
+
+#### What caused friction (user side)
+
+- Nothing notable.
+  The user's two redirecting questions ("should that be a function?"
+  and "how many places access `process.*`?") were well-timed interventions that broadened scope productively.
+
+### Changes made
+
+1. `.pi/skills/code-style/SKILL.md` — added bullet: do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions; accept the value as a parameter.
+2. Filed #76 — inject `cwd` into `AgentManager` constructor.
+3. Filed #77 — add `projectAgentsDir` to `AgentMenuDeps`.

package/package.json

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

package/src/agent-manager.ts

@@ -10,6 +10,8 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { debugLog } from "./debug.js";
+import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
@@ -71,6 +73,7 @@ export class AgentManager {
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
   private maxConcurrent: number;
+  private getRunConfig?: () => RunConfig;
 
   /** Queue of background agents waiting to start. */
   private queue: { id: string; args: SpawnArgs }[] = [];
@@ -82,10 +85,12 @@ export class AgentManager {
     maxConcurrent = DEFAULT_MAX_CONCURRENT,
     onStart?: OnAgentStart,
     onCompact?: OnAgentCompact,
+    getRunConfig?: () => RunConfig,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
     this.onCompact = onCompact;
+    this.getRunConfig = getRunConfig;
     this.maxConcurrent = maxConcurrent;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
@@ -181,10 +186,13 @@ export class AgentManager {
     }
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
+    const runConfig = this.getRunConfig?.();
     const promise = runAgent(ctx, type, prompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
+      defaultMaxTurns: runConfig?.defaultMaxTurns,
+      graceTurns: runConfig?.graceTurns,
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
@@ -230,7 +238,7 @@ export class AgentManager {
 
         // Final flush of streaming output file
         if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
+          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup", err); }
           record.outputCleanup = undefined;
         }
 
@@ -246,7 +254,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+          try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
           this.drainQueue();
         }
         return responseText;
@@ -263,7 +271,7 @@ export class AgentManager {
 
         // Final flush of streaming output file on error
         if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
+          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup on error", err); }
           record.outputCleanup = undefined;
         }
 
@@ -272,7 +280,7 @@ export class AgentManager {
           try {
             const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
             record.worktreeResult = wtResult;
-          } catch { /* ignore cleanup errors */ }
+          } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
 
         if (options.isBackground) {
@@ -477,6 +485,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+    try { pruneWorktrees(process.cwd()); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }