@gotgenes/pi-subagents 5.0.0 → 5.2.0

package/docs/architecture/architecture.md

@@ -1,32 +1,24 @@
 # Architecture
 
-This document describes the planned decomposition of the pi-subagents fork
-into a focused, composable core with a stable API boundary that other
-extensions can build on.
+This document describes the planned decomposition of the pi-subagents fork into a focused, composable core with a stable API boundary that other extensions can build on.
 
 ## Design principles
 
-1. **Narrow core** — the extension owns agent spawning, execution, and result
-   retrieval. Everything else is a consumer.
-2. **Composable by default** — other extensions can spawn agents, observe
-   their lifecycle, and display their state without importing this package
-   directly.
-3. **Typed API boundary** — this package exports a `SubagentsAPI` interface
-   and `Symbol.for()` accessors (`publishSubagentsAPI` /
-   `getSubagentsAPI`). Consumers declare this package as an optional peer
-   dependency and use dynamic import for compile-time types. The runtime
-   bridge is `Symbol.for()` on `globalThis` — no separate API package.
+1. **Narrow core** — the extension owns agent spawning, execution, and result retrieval.
+   Everything else is a consumer.
+2. **Composable by default** — other extensions can spawn agents, observe their lifecycle, and display their state without importing this package directly.
+3. **Typed API boundary** — this package exports a `SubagentsAPI` interface and `Symbol.for()` accessors (`publishSubagentsAPI` / `getSubagentsAPI`).
+   Consumers declare this package as an optional peer dependency and use dynamic import for compile-time types.
+   The runtime bridge is `Symbol.for()` on `globalThis` — no separate API package.
 4. **No scheduling** — in-process scheduling is removed from the core.
-   Scheduling is a separate concern that any extension can implement by
-   calling `spawn()` on the published API.
-5. **UI extraction is deferred** — the widget, conversation viewer, and
-   `/agents` command menu stay in the core for now. They are the first
-   candidate for extraction once the API boundary is proven stable.
+   Scheduling is a separate concern that any extension can implement by calling `spawn()` on the published API.
+5. **UI extraction is deferred** — the widget, conversation viewer, and `/agents` command menu stay in the core for now.
+   They are the first candidate for extraction once the API boundary is proven stable.
 
 ## Current state
 
-The extension is a 6,300 LOC monolith organized into well-factored internal
-modules but with no public API contract. The subsystems are:
+The extension is a 6,300 LOC monolith organized into well-factored internal modules but with no public API contract.
+The subsystems are:
 
 ```text
 index.ts (1,894 LOC) — entry point, tool registration, event wiring
@@ -57,18 +49,11 @@ ui/conversation-viewer.ts — scrollable session overlay
 
 ### Coupling today
 
-The widget reads agent state by holding a direct reference to
-`AgentManager` and polling a shared mutable `Map<string, AgentActivity>`
-every 80 ms. The conversation viewer subscribes directly to `AgentSession`
-objects.
+The widget reads agent state by holding a direct reference to `AgentManager` and polling a shared mutable `Map<string, AgentActivity>` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
 
-Cross-extension consumers use an ad-hoc RPC layer over `pi.events`
-(`subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:ping`) with
-per-request reply channels and untyped envelopes.
+Cross-extension consumers use an ad-hoc RPC layer over `pi.events` (`subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:ping`) with per-request reply channels and untyped envelopes.
 
-There is also a `Symbol.for("pi-subagents:manager")` export on
-`globalThis` that exposes `{ waitForAll, hasRunning, spawn, getRecord }`,
-but it is undocumented and untyped.
+There is also a `Symbol.for("pi-subagents:manager")` export on `globalThis` that exposes `{ waitForAll, hasRunning, spawn, getRecord }`, but it is undocumented and untyped.
 
 ## Target state
 
@@ -111,31 +96,26 @@ but it is undocumented and untyped.
 
 - The three tools: `Agent`, `get_subagent_result`, `steer_subagent`.
 - `AgentManager` — spawn, queue, abort, resume, concurrency control.
-- `agent-runner` — session creation, turn loop, tool filtering, extension
-  binding (Patches 2 and 3).
+- `agent-runner` — session creation, turn loop, tool filtering, extension binding (Patches 2 and 3).
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, memory, skills, environment.
 - Worktree isolation.
 - Token usage tracking.
 - Settings persistence.
-- Internal UI (widget, conversation viewer, `/agents` menu) — these stay
-  until the API boundary is proven, then move to a separate extension.
+- Internal UI (widget, conversation viewer, `/agents` menu) — these stay until the API boundary is proven, then move to a separate extension.
 
 ### What the core drops
 
-- **Scheduling** (`schedule.ts`, `schedule-store.ts`,
-  `ui/schedule-menu.ts`) — 612 LOC removed. The `schedule` parameter is
-  removed from the `Agent` tool schema. Any extension that wants scheduling
-  can implement it by calling `getSubagentsAPI()?.spawn(...)` on a timer.
-- **Ad-hoc RPC** (`cross-extension-rpc.ts`) — replaced by the typed
-  `SubagentsAPI` published via `Symbol.for()`. The untyped event-bus RPC
-  channels are removed.
-- **Group join** (`group-join.ts`) — 141 LOC removed. The grouped
-  notification batching adds complexity for a marginal UX improvement.
+- **Scheduling** (`schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`) — 612 LOC removed.
+  The `schedule` parameter is removed from the `Agent` tool schema.
+  Any extension that wants scheduling can implement it by calling `getSubagentsAPI()?.spawn(...)` on a timer.
+- **Ad-hoc RPC** (`cross-extension-rpc.ts`) — replaced by the typed `SubagentsAPI` published via `Symbol.for()`.
+  The untyped event-bus RPC channels are removed.
+- **Group join** (`group-join.ts`) — 141 LOC removed.
+  The grouped notification batching adds complexity for a marginal UX improvement.
   Individual completion notifications are sufficient.
-- **Output file** (`output-file.ts`) — 96 LOC removed. JSONL transcript
-  streaming is a consumer concern; a separate extension can subscribe to
-  lifecycle events and write transcripts.
+- **Output file** (`output-file.ts`) — 96 LOC removed.
+  JSONL transcript streaming is a consumer concern; a separate extension can subscribe to lifecycle events and write transcripts.
 
 ### Estimated impact
 
@@ -147,13 +127,11 @@ but it is undocumented and untyped.
 | Output file       | 83          | ~50                       |
 | **Total**         | **~916**    | **~400**                  |
 
-After removal and `index.ts` decomposition, the core shrinks from ~6,300
-to ~5,400 LOC, and `index.ts` shrinks from ~1,894 to ~1,300 LOC.
+After removal and `index.ts` decomposition, the core shrinks from ~6,300 to ~5,400 LOC, and `index.ts` shrinks from ~1,894 to ~1,300 LOC.
 
 ## 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 (`@earendil-works/pi-subagents`).
 No separate API package is needed.
 
 Consumers declare this package as an optional peer dependency:
@@ -169,8 +147,7 @@ Consumers declare this package as an optional peer dependency:
 }
 ```
 
-At runtime, consumers use dynamic import for type-safe access to the
-accessor functions:
+At runtime, consumers use dynamic import for type-safe access to the accessor functions:
 
 ```typescript
 const { getSubagentsAPI } = await import("@earendil-works/pi-subagents");
@@ -180,12 +157,9 @@ if (api) {
 }
 ```
 
-Pi's extension loader creates a fresh `jiti` instance per extension with
-`moduleCache: false`, so module-scoped singletons don't survive across
-extensions. The accessor functions use `Symbol.for()` on `globalThis`,
-which is process-global by spec, to bridge this gap. The dynamic import
-provides compile-time types; the `Symbol.for()` key is the actual
-runtime channel.
+Pi's extension loader creates a fresh `jiti` instance per extension with `moduleCache: false`, so module-scoped singletons don't survive across extensions.
+The accessor functions use `Symbol.for()` on `globalThis`, which is process-global by spec, to bridge this gap.
+The dynamic import provides compile-time types; the `Symbol.for()` key is the actual runtime channel.
 
 ### Interface
 
@@ -245,9 +219,7 @@ export function getSubagentsAPI(): SubagentsAPI | undefined {
 }
 ```
 
-If Pi gains a native service registry ([earendil-works/pi#4207]), these
-accessors can be updated to delegate to `pi.registerService()` /
-`pi.getService()` internally while keeping the same consumer API.
+If Pi gains a native service registry ([earendil-works/pi#4207]), these accessors can be updated to delegate to `pi.registerService()` / `pi.getService()` internally while keeping the same consumer API.
 
 ### Lifecycle events
 
@@ -259,8 +231,8 @@ The core emits events on `pi.events` that any extension can observe:
 | `subagents:completed` | `{ id, type, status, result?, error? }`     | Agent finishes       |
 | `subagents:activity`  | `{ id, toolName?, textDelta?, turnCount? }` | Streaming progress   |
 
-These replace the ad-hoc RPC channels. They are fire-and-forget broadcast
-events — no request IDs, no reply channels.
+These replace the ad-hoc RPC channels.
+They are fire-and-forget broadcast events — no request IDs, no reply channels.
 
 ### Consumer example: scheduling extension
 
@@ -327,60 +299,137 @@ src/
 └── (existing modules unchanged)
 ```
 
-Each extracted module receives narrow constructor-injected dependencies
-rather than closing over module-level state.
+Each extracted module receives narrow constructor-injected dependencies rather than closing over module-level state.
 
 ## Phase plan
 
 ### Phase 1: Export `SubagentsAPI` from this package
 
-Add the `SubagentsAPI` interface, serializable types, and `Symbol.for()`
-accessor functions as public exports of this package. No behavioral
-changes to the core yet.
+Add the `SubagentsAPI` interface, serializable types, and `Symbol.for()` accessor functions as public exports of this package.
+No behavioral changes to the core yet.
 
 ### Phase 2: Remove scheduling ✓ (done — issue #52)
 
-Deleted `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`. Removed
-the `schedule` parameter from the `Agent` tool schema. Removed scheduler
-setup and lifecycle hooks from `index.ts`.
+Deleted `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`.
+Removed the `schedule` parameter from the `Agent` tool schema.
+Removed scheduler setup and lifecycle hooks from `index.ts`.
 
 ### Phase 3: Remove group-join, output-file, ad-hoc RPC
 
 Delete `group-join.ts`, `output-file.ts`, `cross-extension-rpc.ts`.
-Simplify `index.ts` to use direct individual notifications. Emit
-lifecycle events on `pi.events` for external consumers.
+Simplify `index.ts` to use direct individual notifications.
+Emit lifecycle events on `pi.events` for external consumers.
 
 ### Phase 4: Implement and publish `SubagentsAPI`
 
-Wire `api-adapter.ts` to wrap `AgentManager` and call
-`publishSubagentsAPI()` at extension init. Resolve model strings inside
-the adapter (fixing upstream [tintinweb/pi-subagents#60]).
+Wire `api-adapter.ts` to wrap `AgentManager` and call `publishSubagentsAPI()` at extension init.
+Resolve model strings inside the adapter (fixing upstream [tintinweb/pi-subagents#60]).
 
-### Phase 5: Decompose `index.ts`
+### Phase 5: Decompose `index.ts` ✓ (done — issue #54)
 
-Extract tools, notifications, activity tracking, and the `/agents` command
-into separate modules per the decomposition above.
+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`
 
-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.
+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.
+
+## Structural refactoring roadmap (post-#54)
+
+The Issue #54 decomposition created focused modules but left several structural cleanup opportunities on the table.
+The following issues track the work needed to bring `pi-subagents` to the same level of testability and composability as `pi-permission-system`.
+
+### Phase 1: Foundation
+
+These three issues are independent of each other and can land in any order.
+Together they eliminate module-scope mutable state and create a testable functional core.
+
+1. **gotgenes/pi-packages#69** — Create `SubagentRuntime`
+   - Move `defaultMaxTurns`, `graceTurns`, `agentActivity`, `currentCtx`, and widget references out of closure/module scope into a single factory-constructed object.
+   - This unblocks handler extraction (Issue #70) by giving handlers a concrete deps bag instead of closure variables.
+
+2. **gotgenes/pi-packages#71** — Extract pure agent-session assembler from `agent-runner.ts`
+   - 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.
+
+### 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`.
+
+5. **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.
+   - 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
+   - 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`
+   - 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
+   - 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
+   - 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.
+
+### Dependency graph
+
+```text
+#69 (SubagentRuntime) ──┬──► #70 (handler extraction)
+                        │
+                        └──► #72 (AgentManager DI) ──(optional)──► #70
+
+#71 (pure assembler) ─────(independent)────► (can land any time)
+
+#76 (cwd injection) ──────► #72
+
+#66 (type casts) ◄────────(after structural changes settle)
+#77 (projectAgentsDir) ◄──(after #66 or parallel)
+
+#61 (transcript format) ◄─(after structural refactor)
+#22 (parent session) ◄────(cross-extension, independent)
+```
+
+### Recommended order
+
+The recommended sequence is:
+
+```text
+#69 → #71 → #76 → #72 → #70 → #66 → #77 → #61
+```
+
+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]. The decomposition diverges materially from
-upstream's direction.
+This fork ([earendil-works/pi-subagents]) 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. If they land, upstream
-gains the peer-dep fix and the two RepOne patches. This fork continues
-independently regardless.
+The three upstream PRs (#71, #72, #73) remain open.
+If they land, upstream gains the peer-dep fix and the two RepOne patches.
+This fork continues independently regardless.
 
-Upstream fixes and ideas are cherry-picked when they align with this
-fork's scope. The upstream test suite is run periodically as a regression
-canary for the agent-runner core.
+Upstream fixes and ideas are cherry-picked when they align with this fork's scope.
+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

package/docs/decisions/0001-deferred-patches.md

@@ -28,7 +28,8 @@ This ADR records why Patch 1 was deferred and the strategy for upstream PRs back
 
 ### Patch 1 is deferred
 
-The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`. The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
+The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`.
+The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
 
 During planning for this fork, two implementation constraints surfaced:
 
@@ -40,9 +41,12 @@ A working patch would have to either:
 - Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
 - Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
 
-Neither matches the production need. For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration. The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
+Neither matches the production need.
+For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration.
+The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
 
-We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream. A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
+We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream.
+A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
 
 ### Upstream PRs are open
 
@@ -65,10 +69,12 @@ However, the fork now diverges intentionally beyond those patches — see [`docs
 
 ### Negative
 
-- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands. We accept this because no consumer in scope uses that pattern.
+- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands.
+  We accept this because no consumer in scope uses that pattern.
 
 ### Operational
 
-- Upstream PRs are open and linked above. If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
+- Upstream PRs are open and linked above.
+  If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
 - The architecture document governs the fork's direction going forward; this ADR's original "thin-patch" framing no longer describes the fork's trajectory.
 - When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.

package/docs/plans/0048-implement-subagents-api.md

@@ -33,7 +33,8 @@ This issue implements that boundary, following the naming and structural convent
 
 ### Prerequisite issues
 
-- #49 (remove group-join and RPC) — **closed/merged**. The untyped RPC channels are already gone.
+- #49 (remove group-join and RPC) — **closed/merged**.
+  The untyped RPC channels are already gone.
 - #52 (remove scheduled subagents) — **closed/merged**.
 - #51 (update ADR for hard fork) — **closed/merged**.
 

package/docs/plans/0049-remove-group-join-output-file-rpc.md

@@ -128,23 +128,40 @@ Since this is a removal (not a feature), the order is deletion-first with valida
    Commit: `feat!: remove group-join and cross-extension-rpc source`
 
 2. **Remove RPC wiring from `index.ts`.**
-   Remove `registerRpcHandlers` import and call. Remove `currentCtx` state and RPC-related `session_start`/`session_shutdown` logic (keep `manager.clearCompleted()` call). Remove `unsubPing/Spawn/Stop` teardown. Remove `subagents:ready` emit.
+   Remove `registerRpcHandlers` import and call.
+   Remove `currentCtx` state and RPC-related `session_start`/`session_shutdown` logic (keep `manager.clearCompleted()` call).
+   Remove `unsubPing/Spawn/Stop` teardown.
+   Remove `subagents:ready` emit.
    Commit: `feat!: remove RPC wiring from index.ts`
 
 3. **Remove group-join wiring from `index.ts`.**
-   Remove `GroupJoinManager` import and instantiation (including the grouped-delivery callback). Remove batch tracking (`currentBatchAgents`, `batchFinalizeTimer`, `batchCounter`, `finalizeBatch`). Remove `defaultJoinMode` state, `getDefaultJoinMode`, `setDefaultJoinMode`. Remove join-mode resolution in background spawn path. Remove "Join mode" settings menu entry. Remove `defaultJoinMode` from `snapshotSettings()`. Simplify the `onComplete` callback: remove `currentBatchAgents` check and `groupJoin.onAgentComplete()` routing — always call `sendIndividualNudge(record)`. Remove `setDefaultJoinMode` from `applyAndEmitLoaded` appliers.
+   Remove `GroupJoinManager` import and instantiation (including the grouped-delivery callback).
+   Remove batch tracking (`currentBatchAgents`, `batchFinalizeTimer`, `batchCounter`, `finalizeBatch`).
+   Remove `defaultJoinMode` state, `getDefaultJoinMode`, `setDefaultJoinMode`.
+   Remove join-mode resolution in background spawn path.
+   Remove "Join mode" settings menu entry.
+   Remove `defaultJoinMode` from `snapshotSettings()`.
+   Simplify the `onComplete` callback: remove `currentBatchAgents` check and `groupJoin.onAgentComplete()` routing — always call `sendIndividualNudge(record)`.
+   Remove `setDefaultJoinMode` from `applyAndEmitLoaded` appliers.
    Commit: `feat!: remove group-join wiring from index.ts`
 
 4. **Clean up types, settings, and invocation-config.**
-   Remove `JoinMode` type from `types.ts`. Remove `groupId` and `joinMode` from `AgentRecord`. Remove `others` from `NotificationDetails`. Remove `defaultJoinMode` from `SubagentsSettings` and `SettingsAppliers` in `settings.ts`. Remove `VALID_JOIN_MODES` and sanitize/apply clauses. Remove `resolveJoinMode` and `JoinMode` import from `invocation-config.ts`.
+   Remove `JoinMode` type from `types.ts`.
+   Remove `groupId` and `joinMode` from `AgentRecord`.
+   Remove `others` from `NotificationDetails`.
+   Remove `defaultJoinMode` from `SubagentsSettings` and `SettingsAppliers` in `settings.ts`.
+   Remove `VALID_JOIN_MODES` and sanitize/apply clauses.
+   Remove `resolveJoinMode` and `JoinMode` import from `invocation-config.ts`.
    Commit: `feat!: remove join-mode types and settings`
 
 5. **Verify all tests pass and fix straggling references.**
-   Run `pnpm vitest run` and `pnpm run check`. Fix any test fixtures or assertions that reference removed fields (`joinMode`, `groupId`, `defaultJoinMode`, `resolveJoinMode`).
+   Run `pnpm vitest run` and `pnpm run check`.
+   Fix any test fixtures or assertions that reference removed fields (`joinMode`, `groupId`, `defaultJoinMode`, `resolveJoinMode`).
    Commit (if fixes needed): `test: remove references to deleted subsystems from test fixtures`
 
 6. **Update documentation.**
-   Update `README.md`: remove "Cross-extension RPC" section, join-mode documentation, `subagents:ready` event row. Update settings persistence paragraph.
+   Update `README.md`: remove "Cross-extension RPC" section, join-mode documentation, `subagents:ready` event row.
+   Update settings persistence paragraph.
    Update `.pi/skills/package-pi-subagents/SKILL.md`: remove `cross-extension-rpc.ts` and `group-join.ts` from architecture diagram and module tables, update `index.ts` description.
    Commit: `docs: remove group-join and RPC from README and AGENTS`
 

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

@@ -43,7 +43,8 @@ The update touches three areas of the ADR:
 
 1. **Frontmatter + Status section** — change `status: accepted` to `status: superseded` in frontmatter, and update the Status section body to read "Superseded" with a pointer to `docs/architecture/architecture.md`.
 2. **"Upstream PRs are open" subsection** — keep the PR list and factual statements intact; revise the final sentence ("Once these land upstream, the fork's divergence reduces to package naming and tooling.") to note that the fork now diverges intentionally beyond those patches, per the architecture document.
-3. **Consequences → Operational** — add a sentence noting that the fork diverges intentionally beyond patches, and that the architecture document governs the fork's direction going forward. Keep the existing bullet about upstream PRs.
+3. **Consequences → Operational** — add a sentence noting that the fork diverges intentionally beyond patches, and that the architecture document governs the fork's direction going forward.
+   Keep the existing bullet about upstream PRs.
 
 No structural changes (new sections, removed sections, reordered content).
 

package/docs/plans/0052-remove-scheduled-subagents.md

@@ -83,7 +83,8 @@ The `bypassQueue` option on `SpawnOptions` stays — its JSDoc comment mentionin
 
 1. No new unit tests are needed — this is pure deletion.
 2. All three scheduling test files (`schedule.test.ts`, `schedule-store.test.ts`, `schedule-e2e.test.ts`) become entirely redundant and are deleted.
-3. Existing tests for `agent-manager`, `agent-runner`, `settings`, and other modules stay as-is. The `settings.test.ts` file (if it exists) may need minor updates to remove `schedulingEnabled` from fixture data.
+3. Existing tests for `agent-manager`, `agent-runner`, `settings`, and other modules stay as-is.
+   The `settings.test.ts` file (if it exists) may need minor updates to remove `schedulingEnabled` from fixture data.
 
 ## TDD Order
 
@@ -109,7 +110,8 @@ Since this is a removal (not a feature), the order is deletion-first with a sing
    Commit: `build: remove croner dependency`
 
 5. **Verify all tests pass.**
-   Run `pnpm vitest run` in the package. Fix any test fixtures that reference `schedulingEnabled` or scheduling types.
+   Run `pnpm vitest run` in the package.
+   Fix any test fixtures that reference `schedulingEnabled` or scheduling types.
    Commit (if fixes needed): `test: remove scheduling references from test fixtures`
 
 6. **Update documentation.**

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

@@ -0,0 +1,154 @@
+---
+issue: 57
+issue_title: "feat: structured debug logging for silenced catch blocks"
+---
+
+# Structured debug logging for silenced catch blocks
+
+## Problem Statement
+
+The codebase contains ~20 `catch { /* ignore */ }` blocks spread across `agent-manager.ts`, `worktree.ts`, `output-file.ts`, `skill-loader.ts`, `custom-agents.ts`, `memory.ts`, `env.ts`, and `notification.ts`.
+Each block correctly suppresses a non-essential side-effect failure, but in development the silence makes it impossible to diagnose what is actually failing inside those paths.
+
+## Goals
+
+- Add a `debugLog(context, err)` utility in `src/debug.ts` gated on
+  `PI_SUBAGENTS_DEBUG=1`.
+- Thread `debugLog` into every silenced `catch` block listed in the issue scope.
+- Leave production behavior **completely unchanged** — no new log output unless
+  the env var is explicitly set.
+- Provide a `debug.test.ts` unit test covering the on/off branching.
+
+## Non-Goals
+
+- `usage.ts` catch blocks — they return `0`/`null` on failure and are already
+  recoverable, not truly "silent drops"; they are out of scope.
+- `settings.ts` catch block — it returns `false` on failure, already surfaced
+  to the caller; out of scope.
+- Log rotation, structured JSON output, or stderr vs. stdout routing.
+- Wiring debug output to the Pi UI; `console.warn` to stderr is sufficient.
+
+## Background
+
+The `AGENTS.md` rule "prefer explicit configuration over hidden behavior" aligns with gating noise behind an opt-in env var rather than always-on logging.
+The code-style skill notes that business logic should remain pure — `debug.ts` must not import the Pi SDK; it only reads `process.env`.
+
+The `DEBUG` constant is evaluated once at module import time (top-level `const`).
+That matches how similar opt-in env vars work in Node.js tooling and keeps the hot path to a single boolean branch.
+
+### Catch blocks in scope
+
+| File               | Line(s)                              | Context label(s)                                        |
+| ------------------ | ------------------------------------ | ------------------------------------------------------- |
+| `env.ts`           | 15, 23                               | `"git rev-parse"`, `"git branch"`                       |
+| `skill-loader.ts`  | 74                                   | `"readdirSync skill root"`                              |
+| `custom-agents.ts` | 37, 47                               | `"readdirSync agents dir"`, `"readFileSync agent file"` |
+| `memory.ts`        | 33, 47                               | `"lstatSync"`, `"readFileSync"`                         |
+| `output-file.ts`   | 83                                   | `"write JSONL chunk"`                                   |
+| `worktree.ts`      | 40, 56, 110, 130, 132, 147, 151, 161 | `"git rev-parse"`, `"git worktree add"`, etc.           |
+| `agent-manager.ts` | 233, 249, 266, 275, 480              | `"outputCleanup"`, `"onComplete callback"`, etc.        |
+| `notification.ts`  | 145                                  | `"notification render"`                                 |
+
+## Design Overview
+
+### `src/debug.ts`
+
+```typescript
+export const DEBUG = process.env.PI_SUBAGENTS_DEBUG === "1";
+
+export function debugLog(context: string, err: unknown): void {
+  if (DEBUG) console.warn(`[pi-subagents:debug] ${context}:`, err);
+}
+```
+
+The module-level `DEBUG` constant is the canonical source.
+`debugLog` is a pure side-effect function: no return value, no SDK dependency, no coupling to Pi types.
+
+### Threading pattern
+
+Every silenced `catch` block is updated from:
+
+```typescript
+} catch { /* ignore */ }
+```
+
+to:
+
+```typescript
+} catch (err) { debugLog("<context label>", err); }
+```
+
+When the block already had a named error (`catch (err)`), only the `debugLog` call is added; the existing comment, if descriptive, is removed in favour of the context string.
+
+### Context label convention
+
+Labels read as `"<verb> <noun>"`, lower-case, mirroring the surrounding function name when unambiguous (e.g., `"removeWorktree"`, `"outputCleanup"`).
+
+## Module-Level Changes
+
+| File                   | Change                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `src/debug.ts`         | **New.** Exports `DEBUG` constant and `debugLog` function.                   |
+| `test/debug.test.ts`   | **New.** Unit tests for `debugLog` on/off behaviour.                         |
+| `src/env.ts`           | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/skill-loader.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+| `src/custom-agents.ts` | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/memory.ts`        | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/output-file.ts`   | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+| `src/worktree.ts`      | Add `debugLog` import; name the eight bare `catch` errors; call `debugLog`.  |
+| `src/agent-manager.ts` | Add `debugLog` import; name/update the five `catch` blocks; call `debugLog`. |
+| `src/notification.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+
+## Test Impact Analysis
+
+1. **New tests enabled** — `debug.test.ts` can directly unit-test `debugLog` in isolation.
+   Asserting `console.warn` is/isn't called based on the env var is now trivial.
+   Previously this path was entirely untested.
+
+2. **Existing tests become redundant** — None.
+   The catch blocks were never exercised by existing tests (they were silent drops), so no existing test coverage needs to be removed.
+
+3. **Tests that must stay as-is** — All existing tests remain valid.
+   The threading adds a call inside each catch but does not change control flow, return values, or thrown exceptions; no test expectations change.
+
+## TDD Order
+
+1. **`src/debug.ts` + `test/debug.test.ts`** Test surface: `debugLog` calls `console.warn` when `PI_SUBAGENTS_DEBUG=1`; does nothing when unset or `"0"`.
+   Use `vi.spyOn(console, 'warn')` + `vi.stubEnv('PI_SUBAGENTS_DEBUG', '1')` + `vi.resetModules()` + dynamic import to exercise both branches.
+   Suggested commit: `feat: add debugLog utility gated on PI_SUBAGENTS_DEBUG (#57)`
+
+2. **Thread into `env.ts`** Test surface: `env.test.ts` — existing tests still pass (no new assertions required because the catch paths are tested implicitly by the non-git-dir test already covering the swallowed failures).
+   Suggested commit: `feat: thread debugLog into env catch blocks (#57)`
+
+3. **Thread into `skill-loader.ts`** Test surface: `skill-loader.test.ts` — existing tests still pass.
+   The readdirSync-error catch is exercised when the skill root does not exist (covered by existing "not found" test paths).
+   Suggested commit: `feat: thread debugLog into skill-loader catch block (#57)`
+
+4. **Thread into `custom-agents.ts` and `memory.ts`** These two files have structurally identical filesystem-error catch blocks and can land in a single step.
+   Test surface: `custom-agents.test.ts`, `memory.test.ts` — existing tests still pass.
+   Suggested commit: `feat: thread debugLog into custom-agents and memory catch blocks (#57)`
+
+5. **Thread into `output-file.ts`** Test surface: `output-file.test.ts` — existing tests still pass.
+   Suggested commit: `feat: thread debugLog into output-file catch block (#57)`
+
+6. **Thread into `worktree.ts`** Test surface: `worktree.test.ts` — existing tests still pass.
+   Eight catch sites; name each with its enclosing function for label clarity.
+   Suggested commit: `feat: thread debugLog into worktree catch blocks (#57)`
+
+7. **Thread into `agent-manager.ts` and `notification.ts`** Test surface: `agent-manager.test.ts`, `notification.test.ts` — existing tests still pass.
+   Suggested commit: `feat: thread debugLog into agent-manager and notification catch blocks (#57)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                          | Mitigation                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEBUG` is a module-level constant — `vi.stubEnv` alone won't flip it mid-test                                | Use `vi.resetModules()` + dynamic `import()` inside a test that sets the env var before re-importing; the test skill documents this pattern |
+| Adding `(err)` to a bare `catch` in TypeScript is type-safe (`unknown`) but a `noImplicitAny`-adjacent change | `tsconfig` already uses `"useUnknownInCatchVariables": true` (default in strict mode); no cast needed                                       |
+| Verbose worktree.ts threading (8 sites) could miss one                                                        | The TDD step runs `pnpm vitest run worktree` and `pnpm run check` before committing                                                         |
+
+## Open Questions
+
+- Should a future issue expose `debugLog` as part of the public `service.ts` API so consumer extensions can share the same debug flag?
+  Deferred — out of scope for this change; no consumer currently needs it.
+- Should `PI_SUBAGENTS_DEBUG` be documented in the package `README.md`?
+  Likely yes, but deferred to a follow-up doc PR.