@gotgenes/pi-subagents 18.0.1 → 18.0.3

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

@@ -1,304 +0,0 @@
----
-issue: 48
-issue_title: "feat: implement and publish SubagentsAPI at extension init"
----
-
-# Implement and publish SubagentsService
-
-## Problem Statement
-
-The package currently exposes an untyped, undocumented manager via `Symbol.for("pi-subagents:manager")` on `globalThis`.
-This forces consumers to guess the API shape, lacks model resolution at the boundary (causing "No API key found for undefined" crashes when consumers pass string model names), and leaks non-serializable internals (`AgentSession`, `AbortController`) in returned records.
-
-The architecture doc specifies a typed interface with `Symbol.for()` accessor functions that other extensions import as an optional peer dependency.
-This issue implements that boundary, following the naming and structural conventions established by `pi-permission-system`.
-
-## Goals
-
-- Export `SubagentsService` interface, `SubagentRecord`, `SubagentStatus`, `SpawnOptions`, `LifetimeUsage`, accessor functions (`publishSubagentsService`, `getSubagentsService`), and event constants from the package's public entry point.
-- Create `src/service-adapter.ts` — an adapter wrapping `AgentManager` to satisfy `SubagentsService`, handling string model resolution and record serialization.
-- Call `publishSubagentsService()` at extension init; clean up on `session_shutdown`.
-- Remove the old `Symbol.for("pi-subagents:manager")` global key.
-- This is a **breaking change** (`feat!:`) — the old untyped global key is removed and replaced with the typed service under a new key.
-- Follow the naming and structural conventions established by `pi-permission-system` (`service.ts`, `@gotgenes/<pkg>:service` key, `Record<symbol, unknown>` cast).
-
-## Non-Goals
-
-- Consumer extensions (scheduling, transcript) — these are separate packages.
-- Native Pi service registry integration (`pi.registerService()`) — deferred to a future Pi SDK release.
-- `SubagentsService.resume()` — not part of the initial interface per the architecture doc.
-- Output-file JSONL format migration (#61).
-
-## Background
-
-### Prerequisite issues
-
-- #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**.
-
-### Relevant modules
-
-| Module                  | Role in this change                                                                                  |
-| ----------------------- | ---------------------------------------------------------------------------------------------------- |
-| `src/index.ts`          | Wiring layer. Currently publishes the untyped global; will call `publishSubagentsService()` instead. |
-| `src/agent-manager.ts`  | Core lifecycle manager. The adapter wraps its public methods.                                        |
-| `src/model-resolver.ts` | `resolveModel()` converts string → `Model`. The adapter calls this at the API boundary.              |
-| `src/types.ts`          | Defines `AgentRecord` (internal, non-serializable).                                                  |
-| `src/usage.ts`          | Exports `LifetimeUsage` (already serializable).                                                      |
-
-### Constraints from AGENTS.md
-
-- One concern per file — types/accessors in `src/service.ts`, adapter logic in `src/service-adapter.ts`.
-- Avoid `any` unless absolutely necessary — the accessor functions use `Record<symbol, unknown>` on `globalThis`.
-- Pi SDK imports stay out of business-logic modules — `service-adapter.ts` accepts `pi` and `ctx` as narrow interface parameters.
-- Narrow interface types for collaborators — the adapter takes a minimal `AgentManagerLike` interface, not the concrete `AgentManager` class.
-
-### Alignment with pi-permission-system
-
-This plan deliberately follows the pattern established by `@gotgenes/pi-permission-system`:
-
-| Aspect          | pi-permission-system                       | pi-subagents (this plan)                |
-| --------------- | ------------------------------------------ | --------------------------------------- |
-| Public file     | `src/service.ts`                           | `src/service.ts`                        |
-| Interface name  | `PermissionsService`                       | `SubagentsService`                      |
-| Symbol.for key  | `"@gotgenes/pi-permission-system:service"` | `"@gotgenes/pi-subagents:service"`      |
-| globalThis cast | `Record<symbol, unknown>`                  | `Record<symbol, unknown>`               |
-| Accessors       | `publish/get/unpublishPermissionsService`  | `publish/get/unpublishSubagentsService` |
-| exports →       | `./src/service.ts`                         | `./src/service.ts`                      |
-
-The architecture doc uses `SubagentsAPI` naming and `pi:service:subagents` key; it should be updated during implementation to reflect the final naming.
-
-## Design Overview
-
-### Module decomposition
-
-```text
-src/service.ts          ← SubagentsService interface, SubagentRecord, SpawnOptions,
-                          SubagentStatus, accessor functions, event constants
-src/service-adapter.ts  ← createSubagentsService() factory, record serialization,
-                          model resolution at the boundary
-src/index.ts            ← wire: publishSubagentsService(createSubagentsService(...))
-```
-
-### Types (in `src/service.ts`)
-
-```typescript
-export type SubagentStatus =
-  | "queued" | "running" | "completed" | "steered"
-  | "aborted" | "stopped" | "error";
-
-export interface SubagentRecord {
-  id: string;
-  type: string;
-  description: string;
-  status: SubagentStatus;
-  result?: string;
-  error?: string;
-  toolUses: number;
-  startedAt: number;
-  completedAt?: number;
-  lifetimeUsage: LifetimeUsage;
-  compactionCount: number;
-  worktreeResult?: { hasChanges: boolean; branch?: string };
-}
-
-export interface SpawnOptions {
-  description?: string;
-  model?: string;
-  maxTurns?: number;
-  thinkingLevel?: string;
-  isolated?: boolean;
-  inheritContext?: boolean;
-  foreground?: boolean;
-  bypassQueue?: boolean;
-  isolation?: "worktree";
-}
-
-export interface SubagentsService {
-  spawn(type: string, prompt: string, options?: SpawnOptions): string;
-  getRecord(id: string): SubagentRecord | undefined;
-  listAgents(): SubagentRecord[];
-  abort(id: string): boolean;
-  steer(id: string, message: string): Promise<boolean>;
-  waitForAll(): Promise<void>;
-  hasRunning(): boolean;
-}
-
-export const SUBAGENT_EVENTS = {
-  STARTED: "subagents:started",
-  COMPLETED: "subagents:completed",
-  ACTIVITY: "subagents:activity",
-} as const;
-```
-
-### Accessor pattern
-
-```typescript
-const SERVICE_KEY = Symbol.for("@gotgenes/pi-subagents:service");
-
-export function publishSubagentsService(service: SubagentsService): void {
-  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
-}
-
-export function getSubagentsService(): SubagentsService | undefined {
-  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
-    | SubagentsService
-    | undefined;
-}
-
-export function unpublishSubagentsService(): void {
-  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
-}
-```
-
-### Adapter (`src/service-adapter.ts`)
-
-The adapter accepts narrow interfaces rather than concrete classes:
-
-```typescript
-interface AgentManagerLike {
-  spawn(pi: any, ctx: any, type: string, prompt: string, options: any): string;
-  getRecord(id: string): AgentRecord | undefined;
-  listAgents(): AgentRecord[];
-  abort(id: string): boolean;
-  waitForAll(): Promise<void>;
-  hasRunning(): boolean;
-}
-
-interface AdapterDeps {
-  manager: AgentManagerLike;
-  resolveModel: (input: string, registry: ModelRegistry) => any;
-  getCtx: () => { pi: any; ctx: any } | undefined;
-  getModelRegistry: () => ModelRegistry | undefined;
-}
-```
-
-Key behaviors:
-
-1. **String model resolution** — `spawn()` calls `resolveModel(options.model, registry)` before delegating to the manager.
-   If resolution fails, throws with the error string (list of available models).
-2. **Session gating** — throws if `getCtx()` returns `undefined` (no active session).
-3. **Record serialization** — `toSubagentRecord()` strips `session`, `abortController`, `promise`, `pendingSteers`, `outputCleanup` from `AgentRecord`.
-4. **Steer delegation** — uses the same pattern as the `steer_subagent` tool: checks status, queues if session not ready, delegates to `session.steer()`.
-
-This mirrors the `pi-permission-system` pattern: a slim `service.ts` defines the contract and accessors; a separate adapter file contains the implementation wiring.
-
-### Public entry point
-
-The package currently has no explicit `exports` field in `package.json`.
-Since Pi loads the extension via `pi.extensions` (pointing at `./src/index.ts`), the service types and accessors need a separate public entry point.
-Add an `exports` map:
-
-```json
-{
-  "exports": {
-    ".": "./src/service.ts"
-  }
-}
-```
-
-This exposes the types and accessor functions to consumers who `import("@gotgenes/pi-subagents")`.
-The extension entry point (`./src/index.ts`) remains declared in `pi.extensions`.
-This matches the pattern established by `pi-permission-system` (`exports` → `service.ts`, `pi.extensions` → `index.ts`).
-
-### Edge cases
-
-- **No active session**: `spawn()` throws `"No active session — cannot spawn agents outside a session."`.
-- **Model resolution failure**: `spawn()` throws with the error string from `resolveModel()`.
-- **Missing description**: default to a truncated prompt (`prompt.slice(0, 80)`).
-- **Steer on non-running agent**: returns `false`.
-- **Steer before session ready**: queues the message (returns `true`).
-
-### Naming conventions
-
-Following `pi-permission-system`'s established pattern:
-
-- Public file: `service.ts` (not `api.ts`)
-- Interface: `SubagentsService` (not `SubagentsAPI`)
-- Symbol key: `"@gotgenes/pi-subagents:service"` (scoped package name, not generic `pi:service:*`)
-- globalThis cast: `Record<symbol, unknown>` (not `any`)
-- Accessor names: `publish/get/unpublishSubagentsService`
-
-## Module-Level Changes
-
-### New files
-
-| File                           | Contents                                                                                                                                                                       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `src/service.ts`               | `SubagentsService` interface, `SubagentRecord`, `SubagentStatus`, `SpawnOptions`, `LifetimeUsage` re-export, accessor functions, event constants, `unpublishSubagentsService`. |
-| `src/service-adapter.ts`       | `createSubagentsService()` factory. `toSubagentRecord()` serializer. Narrow `AgentManagerLike` and `AdapterDeps` interfaces.                                                   |
-| `test/service-adapter.test.ts` | Unit tests for the adapter (model resolution, serialization, session gating, steer delegation).                                                                                |
-| `test/service.test.ts`         | Unit tests for accessor functions (publish/get/unpublish round-trip, isolation between keys).                                                                                  |
-
-### Modified files
-
-| File           | Change                                                                                                                                                                                                                                                                                                                                                                      |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/index.ts` | Import `publishSubagentsService`, `unpublishSubagentsService` from `./service.js` and `createSubagentsService` from `./service-adapter.js`. Replace `Symbol.for("pi-subagents:manager")` block with `publishSubagentsService(createSubagentsService(...))`. In `session_shutdown`, call `unpublishSubagentsService()` instead of `delete (globalThis as any)[MANAGER_KEY]`. |
-| `package.json` | Add `"exports": { ".": "./src/service.ts" }`.                                                                                                                                                                                                                                                                                                                               |
-| `src/usage.ts` | No change needed — `LifetimeUsage` is already exported. Re-exported from `src/service.ts`.                                                                                                                                                                                                                                                                                  |
-
-## Test Impact Analysis
-
-1. **New unit tests enabled**: `test/service-adapter.test.ts` tests the adapter in isolation against a mock `AgentManagerLike` — model resolution, record stripping, session gating, steer semantics.
-   `test/service.test.ts` tests the accessor functions (publish/get/unpublish lifecycle, `undefined` before publish).
-2. **Existing tests that become redundant**: None — the old `Symbol.for("pi-subagents:manager")` global was not unit-tested.
-3. **Existing tests that must stay**: All `agent-manager.test.ts` and `agent-runner.test.ts` tests remain — they test the internal engine, not the public service boundary.
-   Any test referencing `MANAGER_KEY` or `"pi-subagents:manager"` in string assertions must be updated.
-
-## TDD Order
-
-1. **`src/service.ts` — types, accessors, and event constants.**
-   Test: `test/service.test.ts` — `publishSubagentsService` stores on globalThis, `getSubagentsService` retrieves it, `unpublishSubagentsService` removes it, `getSubagentsService` returns `undefined` when not published.
-   Commit: `feat!: add SubagentsService types and accessor functions`
-
-2. **`src/service-adapter.ts` — `toSubagentRecord()` serializer.**
-   Test: `test/service-adapter.test.ts` — given an `AgentRecord` with `session`, `abortController`, `promise`, `pendingSteers`, `outputCleanup`, verify the returned `SubagentRecord` contains only serializable fields.
-   Commit: `feat: add SubagentRecord serializer`
-
-3. **`src/service-adapter.ts` — `createSubagentsService().getRecord()` and `listAgents()`.**
-   Test: verify `getRecord` delegates to manager and serializes; `listAgents` returns serialized records sorted by `startedAt` descending.
-   Commit: `feat: implement getRecord and listAgents on SubagentsService adapter`
-
-4. **`src/service-adapter.ts` — `spawn()` with model resolution and session gating.**
-   Test: (a) throws when `getCtx()` returns `undefined`; (b) resolves string model names via `resolveModel`; (c) throws on model resolution failure; (d) delegates to manager with resolved model; (e) uses truncated prompt as default description.
-   Commit: `feat: implement spawn with model resolution on SubagentsService adapter`
-
-5. **`src/service-adapter.ts` — `steer()`, `abort()`, `waitForAll()`, `hasRunning()`.**
-   Test: `steer` returns `false` for non-running agent, `true` when session queues or delivers; `abort`/`waitForAll`/`hasRunning` delegate to manager.
-   Commit: `feat: implement steer, abort, waitForAll, hasRunning on adapter`
-
-6. **Wire into `src/index.ts` — replace old global with typed service.**
-   Replace `Symbol.for("pi-subagents:manager")` block with `publishSubagentsService(createSubagentsService(...))`.
-   Update `session_shutdown` to call `unpublishSubagentsService()`.
-   Commit: `feat!: publish SubagentsService at extension init, remove old untyped global`
-
-7. **Add `exports` to `package.json`.**
-   Add `"exports": { ".": "./src/service.ts" }` so consumers can `import("@gotgenes/pi-subagents")`.
-   Commit: `feat: expose public service entry point via package exports`
-
-8. **Run full suite and type check.**
-   `pnpm vitest run && pnpm run check`.
-   Fix any straggling references to `MANAGER_KEY` or `"pi-subagents:manager"` in tests.
-   Commit (if fixes needed): `test: update references to old Symbol.for key`
-
-## Risks and Mitigations
-
-| Risk                                                                            | Mitigation                                                                                                                                                                                                         |
-| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Consumers relying on the old `pi-subagents:manager` key break silently          | This is a `feat!:` (major bump). No other package in this monorepo references the old key. Document migration in CHANGELOG via release-please.                                                                     |
-| `exports` field breaks Pi's extension loader                                    | Pi loads via `pi.extensions` (`./src/index.ts`), which is separate from `exports`. The `exports` field only affects `import("@gotgenes/pi-subagents")` from consumer code. Same pattern as `pi-permission-system`. |
-| Adapter leaks internal state if `AgentRecord` gains new non-serializable fields | `toSubagentRecord()` uses an explicit allowlist (pick pattern), not a denylist. New fields must be opted in.                                                                                                       |
-| `steer()` race condition — session created between status check and queue push  | The existing tool handler has the same race window and handles it acceptably. The adapter uses the same pattern (check session → queue if absent → delegate if present).                                           |
-| `resolveModel` returns `any` — type unsafety at boundary                        | The adapter's `AgentManagerLike.spawn` already accepts `Model<any>` for the `options.model` field. The `any` is confined to the model-resolution seam, matching existing code.                                     |
-| Architecture doc uses different naming (`SubagentsAPI`, `pi:service:subagents`) | Open question documented below. Update the architecture doc during implementation to reflect final naming.                                                                                                         |
-
-## Open Questions
-
-- Should `SubagentsService` be augmented with an `onEvent(channel, callback)` subscription method, or is `pi.events.on(SUBAGENT_EVENTS.COMPLETED, ...)` sufficient for consumers?
-  Deferred — consumers already have access to `pi.events` and the event constants are exported.
-- The architecture doc uses `SubagentsAPI` naming and `pi:service:subagents` key.
-  This plan intentionally diverges to align with the established `pi-permission-system` pattern (`*Service` naming, `@gotgenes/<pkg>:service` key, `Record<symbol, unknown>` cast).
-  The architecture doc should be updated during implementation to reflect the final naming.

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

@@ -1,180 +0,0 @@
----
-issue: 49
-issue_title: "feat: remove group-join, output-file, and ad-hoc RPC"
----
-
-# Remove group-join and ad-hoc RPC
-
-## Problem Statement
-
-Two optional subsystems remain in the core that are either consumer concerns or replaced by the typed `SubagentsAPI` (#48):
-
-1. **Group join** — grouped completion notifications add batching complexity for marginal UX benefit when individual notifications are sufficient.
-2. **Ad-hoc RPC** — untyped RPC over `pi.events` with per-request reply channels is replaced by the typed `SubagentsAPI` published via `Symbol.for()`.
-
-Removing these two subsystems reduces the core's surface area by ~220 source LOC, eliminates the join-mode settings system, and simplifies the completion callback path in `index.ts`.
-
-The **output file** subsystem (`src/output-file.ts`) is retained — it provides valuable post-hoc debugging transcripts for subagent sessions.
-A separate issue (#61) tracks porting it to Pi's official JSONL session format.
-
-## Goals
-
-- Delete `src/group-join.ts` (141 LOC) and `src/cross-extension-rpc.ts` (80 LOC).
-- Delete `test/cross-extension-rpc.test.ts`.
-- Remove all group-join wiring from `index.ts`: `GroupJoinManager` instantiation, batch tracking (`currentBatchAgents`, `finalizeBatch`, `batchFinalizeTimer`, `batchCounter`), join-mode configuration state, and settings menu entry.
-- Remove all RPC wiring from `index.ts`: `registerRpcHandlers` import, `currentCtx` capture for RPC, `unsubPing/Spawn/Stop` teardown, and the `subagents:ready` broadcast.
-- Remove `JoinMode` type and `joinMode`/`groupId` fields from `types.ts`.
-- Remove `NotificationDetails.others` field (no longer needed without grouping).
-- Remove `defaultJoinMode` from `SubagentsSettings` and `SettingsAppliers` in `settings.ts`.
-- Remove `resolveJoinMode` from `invocation-config.ts`.
-- Simplify the completion callback in `index.ts` to always send an individual notification.
-- Preserve existing lifecycle events (`subagents:started`, `subagents:completed`, `subagents:failed`) — they are already emitted.
-- This is a **breaking change** (`feat!:`) — the join-mode setting is removed and RPC channels are no longer registered.
-
-## Non-Goals
-
-- Removing the `Symbol.for("pi-subagents:manager")` global accessor — that belongs to #48 (implement SubagentsAPI), which replaces it with the typed `publishSubagentsAPI()`.
-- Removing `bypassQueue` from `SpawnOptions` — it remains useful for the typed API.
-- Providing migration shims for RPC consumers — none known.
-- Removing or modifying `src/output-file.ts` — retained for debugging value; porting to Pi's JSONL format is tracked in #61.
-
-## Background
-
-The architecture doc marks these modules as "removing."
-Issue #52 (remove scheduled subagents) is already implemented and merged.
-Issue #48 (implement SubagentsAPI) depends on RPC removal here since the typed API replaces the untyped RPC.
-
-The `index.ts` file is the primary wiring layer affected.
-The completion callback currently routes through `groupJoin.onAgentComplete()` and only falls through to `sendIndividualNudge()` on `'pass'`.
-After this change, the callback always calls `sendIndividualNudge()` directly, which simplifies the control flow from ~90 lines of group/batch logic down to a single function call.
-
-The `currentCtx` variable captured in `session_start` exists solely for the RPC spawn handler.
-After RPC removal, session lifecycle hooks simplify: `session_start` only needs `manager.clearCompleted()`.
-
-## Design Overview
-
-This is a pure deletion change with minor simplification of the remaining completion path.
-
-After removal, the background-agent completion flow becomes:
-
-1. `AgentManager` calls `onComplete(record)`.
-2. `onComplete` emits `subagents:completed` or `subagents:failed` on `pi.events`.
-3. `onComplete` persists the record via `pi.appendEntry`.
-4. If `record.resultConsumed`, clean up widget and return.
-5. Otherwise, call `sendIndividualNudge(record)` — which schedules the notification with a 200ms debounce window (retained for `get_subagent_result` cancellation).
-
-The `NotificationDetails` interface stays (individual notifications still use it) but loses the `others` field.
-The `outputFile` field on `NotificationDetails` stays since output-file is retained.
-
-### Settings changes
-
-`SubagentsSettings` loses `defaultJoinMode`.
-The settings menu loses the "Join mode" entry.
-`snapshotSettings()` and `persistToastFor()` patterns are unchanged — they just carry one fewer field.
-
-### Types changes
-
-```typescript
-// Remove from types.ts:
-export type JoinMode = 'async' | 'group' | 'smart';
-
-// Remove from AgentRecord:
-groupId?: string;
-joinMode?: JoinMode;
-
-// Remove from NotificationDetails:
-others?: NotificationDetails[];
-```
-
-`AgentRecord.outputFile`, `outputCleanup`, and `toolCallId` are retained — they support the output-file subsystem which remains in scope.
-
-## Module-Level Changes
-
-### Delete
-
-| File                               | Lines |
-| ---------------------------------- | ----- |
-| `src/group-join.ts`                | 141   |
-| `src/cross-extension-rpc.ts`       | 80    |
-| `test/cross-extension-rpc.test.ts` | ~220  |
-
-### Modify
-
-| File                                       | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/index.ts`                             | Remove imports for group-join and RPC modules. Remove `GroupJoinManager` instantiation and the grouped-delivery callback (~30 lines). Remove batch tracking state and `finalizeBatch()` (~40 lines). Remove join-mode state (`defaultJoinMode`, `getDefaultJoinMode`, `setDefaultJoinMode`). Remove RPC registration, `currentCtx` capture, `unsubPing/Spawn/Stop` teardown. Remove `subagents:ready` emit. Remove "Join mode" settings menu entry and `snapshotSettings` join-mode field. Simplify `onComplete` callback to always call `sendIndividualNudge`. Remove the `currentBatchAgents` deferred-notification check. Remove join-mode resolution in background spawn path. |
-| `src/types.ts`                             | Remove `JoinMode` type. Remove `groupId` and `joinMode` from `AgentRecord`. Remove `others` from `NotificationDetails`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `src/settings.ts`                          | Remove `JoinMode` import. Remove `defaultJoinMode` from `SubagentsSettings`. Remove `setDefaultJoinMode` from `SettingsAppliers`. Remove `VALID_JOIN_MODES`. Remove sanitize clause and `applySettings` clause for `defaultJoinMode`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `src/invocation-config.ts`                 | Remove `JoinMode` import. Remove `resolveJoinMode` export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `README.md`                                | Remove "Cross-extension RPC" section. Remove join-mode documentation. Remove `subagents:ready` from events table. Update settings persistence paragraph to drop join-mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `.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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-
-## Test Impact Analysis
-
-1. No new unit tests are needed — this is pure deletion.
-2. `test/cross-extension-rpc.test.ts` becomes entirely redundant and is deleted.
-3. `test/output-file.test.ts` is retained (output-file stays).
-4. There is no dedicated `group-join.test.ts` — the group-join logic was only tested indirectly through integration.
-5. Existing tests for `agent-manager`, `agent-runner`, `settings`, and `invocation-config` must be checked for references to `joinMode`, `groupId`, `defaultJoinMode`, or `resolveJoinMode` — any such references need updating.
-6. The notification renderer test (if any) may reference `others` on `NotificationDetails` — check and remove.
-
-## TDD Order
-
-Since this is a removal (not a feature), the order is deletion-first with validation passes.
-
-1. **Delete source files for both subsystems.**
-   Delete `src/group-join.ts`, `src/cross-extension-rpc.ts`.
-   Delete `test/cross-extension-rpc.test.ts`.
-   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.
-   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.
-   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`.
-   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`).
-   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 `.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`
-
-## Risks and Mitigations
-
-| Risk                                                      | Mitigation                                                                                                                                                             |
-| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Missed references cause compile errors                    | `grep -rn 'group.join\|GroupJoin\|registerRpcHandlers\|resolveJoinMode\|JoinMode' src/` after each step. `pnpm run check` catches import errors.                       |
-| Test fixtures reference removed fields                    | Step 5 explicitly scans for and fixes these. TypeScript `noEmit` check catches type mismatches.                                                                        |
-| `Symbol.for("pi-subagents:manager")` accidentally removed | Explicitly out of scope — this belongs to #48. The global accessor stays until the typed API replaces it.                                                              |
-| Breaking change not communicated                          | `feat!:` commit prefix triggers a major version bump via release-please.                                                                                               |
-| Settings file with `defaultJoinMode` on disk              | `sanitize()` already drops unknown fields silently — once the field is removed from the interface, existing files just have an inert JSON key that is ignored on load. |
-
-## Open Questions
-
-None — the issue scope is fully specified and the architecture doc ratified these removals.

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

@@ -1,77 +0,0 @@
----
-issue: 51
-issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
----
-
-# Update ADR-0001 to reflect hard-fork decision
-
-## Problem Statement
-
-[ADR-0001] was written when the fork was a thin-patch layer over `tintinweb/pi-subagents`.
-The new architecture document (`docs/architecture/architecture.md`) commits to a hard fork with material scope reduction — scheduling removal, a `SubagentsAPI` boundary, `index.ts` decomposition, and more.
-
-Several claims in [ADR-0001] are now outdated:
-
-1. The status is "accepted" but the decision has been superseded by the architecture doc.
-2. The Upstream PRs section states "the fork's divergence reduces to package naming and tooling," which is no longer true.
-3. The Consequences → Operational section implies that merging the upstream PRs eliminates behavioral divergence, which no longer holds.
-
-## Goals
-
-- Add a supersession note to [ADR-0001] pointing to `docs/architecture/architecture.md`.
-- Update the "Upstream PRs are open" subsection so the "divergence reduces to…" claim reflects reality.
-- Update the Consequences → Operational section to note intentional divergence per the architecture document.
-- Preserve all existing rationale — no information is removed.
-
-## Non-Goals
-
-- Rewriting the ADR from scratch — the original context is still useful.
-- Updating the architecture document itself.
-- Any code changes.
-
-## Background
-
-[ADR-0001] has YAML frontmatter (`status: accepted`, `date: 2026-05-11`) and follows a standard ADR structure: Status, Context, Decision, Consequences.
-
-The architecture document (`docs/architecture/architecture.md`) describes a six-phase plan that materially diverges from upstream: scheduling removal, ad-hoc RPC replacement, group-join and output-file removal, a typed `SubagentsAPI` boundary, and `index.ts` decomposition.
-
-The three upstream PRs (#71, #72, #73) are still open and factually accurate — that section just needs the concluding sentence revised.
-
-## Design Overview
-
-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.
-
-No structural changes (new sections, removed sections, reordered content).
-
-## Module-Level Changes
-
-| File                                      | Change                                                                                                                                                                                    |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `docs/decisions/0001-deferred-patches.md` | Update frontmatter `status` from `accepted` to `superseded`; revise Status section; revise closing sentence in "Upstream PRs are open"; add divergence note to Consequences → Operational |
-
-## Test Impact Analysis
-
-No tests are affected — this is a docs-only change.
-
-## TDD Order
-
-1. Update [ADR-0001] with all four edits described above.
-   Commit: `docs: update ADR 0001 to reflect hard-fork decision (#51)`
-
-## Risks and Mitigations
-
-| Risk                                           | Mitigation                                                                                                           |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| Supersession note makes the ADR look stale     | Keep all original rationale intact; the note clarifies evolution, not obsolescence                                   |
-| Wording drift between ADR and architecture doc | Use a direct pointer (`docs/architecture/architecture.md`) rather than paraphrasing the architecture doc's decisions |
-
-## Open Questions
-
-None — the issue's acceptance criteria are unambiguous.
-
-[ADR-0001]: ../decisions/0001-deferred-patches.md