@gotgenes/pi-subagents 13.2.1 → 13.2.2

package/docs/plans/0280-rename-agent-to-subagent.md

@@ -0,0 +1,197 @@
+---
+issue: 280
+issue_title: "Rename the internal Agent class to Subagent"
+---
+
+# Rename the internal `Agent` class to `Subagent`
+
+## Problem Statement
+
+The internal lifecycle class `Agent` (`src/lifecycle/agent.ts`) models a single spawned subagent, but the bare name `Agent` collides with two unrelated concepts in the same code: the parent Pi agent that invokes our tooling, and the SDK's `AgentSession` that each subagent wraps.
+The public API already standardized on the `Subagent*` family (`SubagentsService`, `SubagentRecord`, `SubagentStatus`, `SubagentType`, and — after [#265] — `SubagentSession` / `createSubagentSession`).
+The internal lifecycle layer is the lone holdout still using bare `Agent*`.
+Renaming the subagent-instance cluster closes that inconsistency and removes the parent/child/SDK ambiguity.
+
+## Goals
+
+- Rename the subagent-instance cluster in `src/lifecycle/` to the `Subagent*` family: `Agent` → `Subagent`, `AgentManager` → `SubagentManager`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentManagerObserver` → `SubagentManagerObserver`, `AgentManagerOptions` → `SubagentManagerOptions`, `AgentObserverOptions` → `SubagentObserverOptions`, `AgentManagerLike` → `SubagentManagerLike`.
+- Consolidate the duplicate `AgentStatus` union into the existing public `SubagentStatus`, deleting the duplicate and re-pointing `WorkspaceDisposeOutcome.status`.
+- Rename the lifecycle module files to match their primary export: `agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus the matching test files and the `make-agent.ts` test helper.
+- Extend the rename to adjacent identifiers in the same cluster for full consistency: the `subscribeAgentObserver` function → `subscribeSubagentObserver`, the `SubagentManagerObserver` methods `onAgent*` → `onSubagent*`, and the `createTestAgent` helper → `createTestSubagent`.
+- Update residual bare `Agent` / `AgentManager` references in lifecycle comments, JSDoc, and error strings — the acceptance grep matches these, not just symbols.
+- Update `docs/architecture/architecture.md` to the new names.
+- This is internal-only and non-breaking — the exported surface is unchanged apart from `WorkspaceDisposeOutcome.status` reading `SubagentStatus` (an identical union), so commits use `refactor:`, never `feat!:`.
+
+## Non-Goals
+
+- The agent-type/config axis stays untouched: `AgentConfig`, `AgentType`, `AgentTypeRegistry`, `AgentConfigLookup`, `AgentInvocation`, `AgentPromptConfig`, `AgentCategories`.
+- The UI/tool surface stays untouched: `AgentTool` (+ `AgentTool*` variants), `AgentSpawnConfig`, `AgentWidget`, `AgentsMenuHandler`, `AgentActivityTracker`, `AgentDetails`, `AgentCreationWizard`, `AgentConfigEditor`, `AgentFileOps`.
+- SDK types stay untouched: `AgentSession`, `AgentSessionEvent`.
+- Internal field/method names that do not contain the bare `Agent` word — `listAgents`, `getRecord`, the `agents` map, and `record:` parameters — are left as-is; they are not bare-`Agent` symbols and the acceptance grep does not flag them.
+- No behavior changes: this is a pure rename plus a structurally no-op type consolidation.
+
+## Background
+
+Relevant modules (Lifecycle domain unless noted):
+
+- `src/lifecycle/agent.ts` — defines `Agent`, `AgentInit`, `AgentLifecycleObserver`, and the duplicate `AgentStatus` union; owns the full execution lifecycle (`run`, `resume`, `abort`, `steer`, status transitions, workspace disposal).
+  Contains bare-`Agent` JSDoc and two error strings (`"Agent not configured for execution …"`, `"Agent not configured for resume …"`).
+- `src/lifecycle/agent-manager.ts` — defines `AgentManager`, `AgentManagerObserver` (methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated`), `AgentManagerOptions`, and `AgentSpawnConfig` (out of scope).
+- `src/lifecycle/workspace.ts` — `WorkspaceDisposeOutcome.status` is typed as the internal `AgentStatus`, imported from `#src/lifecycle/agent`.
+- `src/observation/record-observer.ts` — defines `AgentObserverOptions` and the `subscribeAgentObserver` function.
+- `src/service/service.ts` — defines the public `SubagentStatus` union (verbatim duplicate of `AgentStatus`) and re-exports `LifetimeUsage`, `Workspace`, and the four workspace collaborator types from the lifecycle layer.
+- `src/service/service-adapter.ts` — defines the `AgentManagerLike` test seam.
+- `src/types.ts` — barrel that re-exports `Agent` from `#src/lifecycle/agent`; most consumers import `Agent` via this barrel.
+- `test/helpers/make-agent.ts` — exports `createTestAgent`, imported by ~16 test files.
+
+Blast radius is mechanical but wide (~360 occurrences, dominated by the `Agent` class via the `types.ts` barrel).
+`typescript` + `tsserver` are available, so each rename is a scope-aware language-service pass verified by `pnpm run check`; the occurrence count does not drive scope.
+
+Constraints from AGENTS.md and skills that apply:
+
+- Within a package, import siblings via `#src/` / `#test/` aliases (eslint enforces this) — the file moves must preserve alias imports, not introduce relative paths.
+- After a barrel rename, verify at least one consumer still imports the renamed symbol from the barrel — many consumers import `Subagent` from `#src/types`, so this holds.
+- The public `dist/public.d.ts` bundle is rolled from `src/service/service.ts`; run `pnpm run verify:public-types` after touching the public surface or the status consolidation.
+- Load the `mermaid` skill before editing the architecture doc's class/sequence diagrams.
+
+## Design Overview
+
+### Status consolidation and the layering constraint
+
+`AgentStatus` (in `agent.ts`) and `SubagentStatus` (in `service.ts`) are identical seven-member unions (`queued | running | completed | steered | aborted | stopped | error`).
+The issue asks `WorkspaceDisposeOutcome.status` to point at the public `SubagentStatus`.
+
+A naive fix — importing `SubagentStatus` from `service.ts` into `workspace.ts` — would create a circular dependency: `service.ts` already imports the workspace collaborator types (`WorkspaceDisposeOutcome`, …) from `workspace.ts`, so `workspace.ts → service.ts` reverses an existing arrow.
+The correct single home is the lifecycle layer, mirroring how `service.ts` already re-exports `LifetimeUsage` from `#src/lifecycle/usage` and the workspace types from `#src/lifecycle/workspace`:
+
+- Keep the union defined in the lifecycle layer (in the renamed `subagent.ts`), renamed `AgentStatus` → `SubagentStatus`.
+- `service.ts` deletes its local definition and adds `export type { SubagentStatus } from "#src/lifecycle/subagent";` alongside its existing re-exports.
+- `workspace.ts` imports `SubagentStatus` from `#src/lifecycle/subagent` (it already imports `AgentStatus` from the same module today — only the symbol name and, after the file move, the path change).
+
+The `subagent ↔ workspace` relationship is type-only and already exists (`subagent.ts` imports `Workspace` / `WorkspaceProvider` from `workspace.ts`; `workspace.ts` imports the status union from `subagent.ts`), so no new runtime cycle is introduced — type-only imports are erased.
+
+`rollup-plugin-dts` inlines `#src/*` types, so `dist/public.d.ts` still emits the same `SubagentStatus` union literal — structurally a no-op for consumers, confirmed by `verify:public-types`.
+
+```typescript
+// src/lifecycle/subagent.ts (renamed from agent.ts)
+export type SubagentStatus =
+  | "queued" | "running" | "completed" | "steered"
+  | "aborted" | "stopped" | "error";
+
+// src/service/service.ts — delete local def, re-export instead
+export type { SubagentStatus } from "#src/lifecycle/subagent";
+
+// src/lifecycle/workspace.ts
+import type { SubagentStatus } from "#src/lifecycle/subagent";
+export interface WorkspaceDisposeOutcome {
+  status: SubagentStatus;
+  description: string;
+}
+```
+
+### Rename mechanics
+
+Each symbol rename is an atomic, scope-aware language-service operation (the API behind LSP "Rename Symbol"); after each, `pnpm run check` verifies the tree compiles.
+Because a rename updates every reference in one pass and leaves the build green, each logical rename is its own commit with the repository in a valid state — no lift-and-shift staging is required (a rename is not a type replacement; old and new names never coexist).
+
+Symbol renames do not touch comments, JSDoc, or string literals.
+There are 26 bare `Agent` and 4 bare `AgentManager` word-occurrences in `src/lifecycle/` comments/strings (e.g. the two `"Agent not configured …"` error messages and cross-file JSDoc in `turn-limits.ts`, `create-subagent-session.ts`, `subagent-session.ts`).
+The acceptance criterion greps `src/lifecycle/` for bare `Agent` / `AgentManager`, so each rename step must also sweep residual comment/string occurrences.
+Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`) are not bare-word matches and stay.
+
+### Full-consistency adjacent identifiers
+
+Per the scope decision, the rename extends to the rest of the cluster's naming so no `Agent`-as-subagent identifier survives:
+
+- `src/observation/record-observer.ts`: `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`.
+- `src/lifecycle/subagent-manager.ts`: `SubagentManagerObserver` methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated` → `onSubagentStarted` / `onSubagentCompleted` / `onSubagentCompacted` / `onSubagentCreated` (8 + 11 + 6 + 14 call sites across `src/` and `test/`, all updated by the language-service rename).
+- `test/helpers/make-agent.ts`: `createTestAgent` → `createTestSubagent`, file → `make-subagent.ts` (~16 importers, including `make-deps.ts` and `ui-stubs.ts`).
+
+## Module-Level Changes
+
+Renamed files (git move, preserving `#src/` / `#test/` alias imports):
+
+- `src/lifecycle/agent.ts` → `src/lifecycle/subagent.ts`
+- `src/lifecycle/agent-manager.ts` → `src/lifecycle/subagent-manager.ts`
+- `test/lifecycle/agent.test.ts` → `test/lifecycle/subagent.test.ts`
+- `test/lifecycle/agent-manager.test.ts` → `test/lifecycle/subagent-manager.test.ts`
+- `test/helpers/make-agent.ts` → `test/helpers/make-subagent.ts`
+- `test/helpers/make-agent.test.ts` → `test/helpers/make-subagent.test.ts`
+
+Changed (symbols, members, imports, comments/strings):
+
+- `src/lifecycle/subagent.ts` — `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentStatus` → `SubagentStatus` (kept here as the single home); update JSDoc and the two error strings.
+- `src/lifecycle/subagent-manager.ts` — `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; `AgentSpawnConfig` unchanged; update header comment.
+- `src/lifecycle/workspace.ts` — import `SubagentStatus` from `#src/lifecycle/subagent`; `WorkspaceDisposeOutcome.status` retyped.
+- `src/service/service.ts` — delete local `SubagentStatus` definition; add `export type { SubagentStatus } from "#src/lifecycle/subagent";`.
+- `src/service/service-adapter.ts` — `AgentManagerLike` → `SubagentManagerLike`; update header comment referencing `AgentManager`.
+- `src/observation/record-observer.ts` — `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`; update header comment.
+- `src/types.ts` — barrel re-export `export { Agent } from "#src/lifecycle/agent";` → `export { Subagent } from "#src/lifecycle/subagent";`.
+- All consumers of the renamed symbols across `src/` and `test/` (tools, UI, runtime, `index.ts`, session, observation, and their tests) — updated transitively by each language-service rename.
+  Out-of-scope `Agent*` symbols in these files are untouched.
+- `test/helpers/make-subagent.ts`, `make-deps.ts`, `ui-stubs.ts`, and ~16 test importers — `createTestAgent` → `createTestSubagent` and updated import paths.
+- `docs/architecture/architecture.md` — file-listing entries (`agent.ts`, `agent-manager.ts`), class/sequence Mermaid diagrams, the type-complexity table row (`AgentInit` → `SubagentInit`, module `agent` → `subagent`), and current-state prose naming the renamed cluster.
+  Out-of-scope `Agent*` names (`AgentTool`, `AgentSession`, `AgentTypeRegistry`, …) and historical phase narrative stay as written.
+
+No exports are removed from the public surface; the barrel rename swaps one name for another with many live consumers.
+Also swept for the `package-pi-subagents` SKILL.md, which documents internals (`AgentManager`, `Agent`, `make-agent`): update its dependency-flow sketch and module table to the new names.
+
+## Test Impact Analysis
+
+This is a pure rename plus a no-op type consolidation, so the extraction-style test questions resolve simply:
+
+1. New tests enabled: none — no new seams or behavior are introduced.
+2. Tests made redundant: none — no test is duplicated or subsumed.
+3. Tests that must stay as-is (renamed/retargeted only): all of them.
+   `test/lifecycle/subagent.test.ts`, `subagent-manager.test.ts`, `record-observer.test.ts`, `service-adapter.test.ts`, and every `createTestSubagent` consumer continue to exercise the same behavior under the new names.
+   The status consolidation leaves `WorkspaceDisposeOutcome` behavior identical, so workspace/service tests are unchanged beyond the symbol name.
+
+## TDD Order
+
+This is a refactor with no red phase; each step is a green checkpoint verified by `pnpm run check` && `pnpm -r run test` (and `verify:public-types` where the public surface is touched) before committing.
+Steps are independent renames ordered smallest-blast-first where practical; any order keeps the tree green.
+
+1. Consolidate the status union.
+   In `agent.ts` rename `AgentStatus` → `SubagentStatus` and keep the definition there; delete the duplicate in `service.ts` and re-export from the lifecycle module; retype `workspace.ts`.
+   Run `pnpm run check`, tests, and `pnpm run verify:public-types` to confirm the bundle is unchanged.
+   Commit: `refactor: consolidate AgentStatus into public SubagentStatus (#280)`.
+2. Rename the `Agent` class cluster.
+   `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`; git-move `agent.ts` → `subagent.ts` and `test/lifecycle/agent.test.ts` → `subagent.test.ts`; update the `types.ts` barrel re-export and the `workspace.ts` / `service.ts` import paths to `#src/lifecycle/subagent`; sweep residual bare-`Agent` JSDoc and the two error strings in `subagent.ts`.
+   Commit: `refactor: rename Agent class to Subagent (#280)`.
+3. Rename the manager cluster.
+   `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; git-move `agent-manager.ts` → `subagent-manager.ts` and its test file; sweep residual bare-`AgentManager` comments.
+   `AgentSpawnConfig` left untouched.
+   Commit: `refactor: rename AgentManager cluster to SubagentManager (#280)`.
+4. Rename the observation seam.
+   `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions` in `record-observer.ts`; update its test and header comment.
+   Commit: `refactor: rename subscribeAgentObserver to subscribeSubagentObserver (#280)`.
+5. Rename the adapter seam.
+   `AgentManagerLike` → `SubagentManagerLike` in `service-adapter.ts`; update its test and header comment.
+   Commit: `refactor: rename AgentManagerLike to SubagentManagerLike (#280)`.
+6. Rename the test helper.
+   `createTestAgent` → `createTestSubagent`; git-move `make-agent.ts` → `make-subagent.ts` and `make-agent.test.ts` → `make-subagent.test.ts`; update all importers and `#test/helpers/make-agent` paths.
+   Commit: `test: rename createTestAgent to createTestSubagent (#280)`.
+7. Update docs.
+   Architecture doc current-state references (file listing, Mermaid diagrams, complexity table, prose) and the `package-pi-subagents` SKILL.md internals; load the `mermaid` skill before editing diagrams.
+   Final verification: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code`, `pnpm run verify:public-types`, and `grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/` returns no bare in-scope matches.
+   Commit: `docs: update architecture and skill docs for Subagent rename (#280)`.
+
+## Risks and Mitigations
+
+- Risk: a symbol rename misses string literals or comments, leaving bare `Agent` that the acceptance grep flags.
+  Mitigation: each rename step explicitly sweeps comments/strings; the final grep gate in step 7 is the backstop.
+- Risk: pointing `workspace.ts` at the public `SubagentStatus` introduces a `lifecycle → service` cycle.
+  Mitigation: keep the union's home in the lifecycle layer (`subagent.ts`) and re-export from `service.ts`, mirroring the existing `LifetimeUsage` / workspace re-export pattern — no new arrow.
+- Risk: the public type bundle changes shape.
+  Mitigation: `verify:public-types` after step 1 and step 7; the union is identical, so the bundle differs only in provenance, not content.
+- Risk: a file move accidentally rewrites `#src/` alias imports to relative paths.
+  Mitigation: use `git mv` and rely on the language service for import updates; eslint's no-relative-sibling rule catches regressions during `pnpm run lint`.
+- Risk: over-reach into out-of-scope `Agent*` names.
+  Mitigation: the rename is symbol-scoped (not text find-replace); the Non-Goals list enumerates the protected names, and the acceptance grep targets only bare `Agent` / `AgentManager` / `AgentInit` / `Agent*Observer`.
+
+## Open Questions
+
+- Whether to later lowercase incidental prose uses of "Agent" (meaning subagent) in the architecture doc's event tables and history sections — deferred; this plan updates symbol/file names and current-state references, leaving historical narrative as written.
+- Whether `listAgents` / `getRecord` / the `agents` map deserve a follow-up naming pass — deferred; they are not bare-`Agent` symbols and fall outside the approved scope.
+
+[#265]: https://github.com/gotgenes/pi-packages/issues/265

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

@@ -3,13 +3,13 @@ issue: 51
 issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
 ---
 
-# Retro: #51 — docs: update ADR 0001 to reflect hard-fork decision
+# Retro: #51 — docs: update ADR-0001 to reflect hard-fork decision
 
 ## Final Retrospective (2026-05-16)
 
 ### Session summary
 
-Updated ADR 0001 (`docs/decisions/0001-deferred-patches.md`) to reflect the hard-fork decision documented in `docs/architecture/architecture.md`.
+Updated [ADR-0001] to reflect the hard-fork decision documented in `docs/architecture/architecture.md`.
 The change was planned, implemented, shipped, and released as `pi-subagents-v1.0.2` in a single clean pass with no rework.
 
 ### Observations
@@ -35,3 +35,5 @@ The change was planned, implemented, shipped, and released as `pi-subagents-v1.0
 - 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.
+
+[ADR-0001]: ../decisions/0001-deferred-patches.md

package/docs/retro/0257-extract-child-session-factory.md

@@ -5,7 +5,7 @@ issue_title: "Extract ChildSessionFactory from runner"
 
 # Retro: #257 — Extract ChildSessionFactory from runner
 
-> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" (ADR 0002, issues #261–#265).
+> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" ([ADR-0002], issues #261–#265).
 
 ## Stage: Planning (2026-05-29T00:32:12Z)
 
@@ -29,3 +29,5 @@ The plan is a lift-and-shift: `runAgent()` keeps its `(snapshot, type, prompt, o
 - `RunResult.sessionFile` shifts from a late `sessionManager.getSessionFile()` to the factory's `outputFile` — same value (stable after `newSession()`); the existing `/sessions/child.jsonl` assertion is the guard.
 - Did not invoke `ask_user`: the issue's "Proposed change" is prescriptive, and the two deviations are forced/justified rather than open-ended.
 - IO interfaces (`RunnerIO`, `RunnerDeps`, etc.) intentionally stay in `agent-runner.ts` for this step to minimize churn; their relocation to the factory module is flagged as an Open Question for Step 4 when the runner dissolves.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0262-add-workspace-provider-seam.md

@@ -9,7 +9,7 @@ issue_title: "Add WorkspaceProvider extension seam"
 
 ### Session summary
 
-Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam (ADR 0002).
+Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam ([ADR-0002]).
 The plan adds the seam additively — `WorkspaceProvider` / `Workspace` interfaces, `SubagentsService.registerWorkspaceProvider`, run-start consultation, and `dispose` with a verbatim `resultAddendum` — while leaving the existing `isolation: "worktree"` path untouched for #263 to evict.
 Three TDD steps (two `feat`, one `docs`).
 
@@ -85,3 +85,5 @@ Across all stages the plan's risk predictions held and TDD verification was incr
 
 1. `AGENTS.md` (Pre-completion reviewer subsection) — added a one-line guardrail: agent `model:` frontmatter must use the `provider/id` alias form the Pi CLI/UI accepts, because an ID absent from the model registry silently falls back to the parent session model.
 2. `packages/pi-subagents/docs/retro/0262-add-workspace-provider-seam.md` — this Final Retrospective stage entry.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0264-remove-extension-lifecycle-control.md

@@ -9,7 +9,7 @@ issue_title: "Remove isolated / extensions:false / noSkills from core"
 
 ### Session summary
 
-Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per ADR 0002.
+Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per [ADR-0002].
 Confirmed all three prerequisite Phase 16 steps (#261, #262, #263) are closed, so the explicit "deny-at-use" dependency is satisfied.
 Produced a four-cycle TDD plan (`isolated` → `extensions` → `skills`/`noSkills`/preload → docs) and committed it.
 
@@ -87,3 +87,5 @@ The run had zero rework and a PASS pre-completion review; test count moved 1016
 1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
 2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
    No prompt or `AGENTS.md` changes were made this retro.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0270-type-consumable-public-surface.md

@@ -34,7 +34,7 @@ The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts`
 
 ### Session summary
 
-Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded ADR 0003.
+Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded [ADR-0003].
 A fifth commit documented the new build step in the `package-pi-subagents` skill (reviewer WARN).
 Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
 
@@ -91,7 +91,7 @@ Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code`
 - The "pi-subagents-* extensions should use the released, npm-installed version, no workspace trickery" directive arrived mid-planning, after initial exploration.
   Surfacing the consumption-model constraint at kickoff would have framed the scope question earlier.
   Opportunity, not criticism — the same exchange produced the high-value chicken-and-egg catch (the registry version with the fix cannot exist until #270 publishes) that correctly deferred the worktrees flip to #263.
-- A brief "there is no ADR 0003" → "My mistake" exchange; no rework.
+- A brief "there is no [ADR-0003]" → "My mistake" exchange; no rework.
 
 ### Diagnostic details
 
@@ -104,3 +104,5 @@ Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code`
 
 1. `.pi/prompts/ship-issue.md` — renamed Step 2 to "Pre-push checks" and added `pnpm fallow dead-code` alongside `pnpm run lint`, with a one-line note that the gate is `main`-only and blocks pushes regardless of who introduced the failure.
 2. `AGENTS.md` (§ Code Style pnpm rules) — added a rule to run `pnpm install` and commit the updated `pnpm-lock.yaml` in the same commit when a `package.json` dependency changes, since CI installs with `--frozen-lockfile`.
+
+[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md

package/docs/retro/0280-rename-agent-to-subagent.md

@@ -0,0 +1,96 @@
+---
+issue: 280
+issue_title: "Rename the internal Agent class to Subagent"
+---
+
+# Retro: #280 — Rename the internal `Agent` class to `Subagent`
+
+## Stage: Planning (2026-05-31T00:09:51Z)
+
+### Session summary
+
+Produced a numbered implementation plan to rename the subagent-instance cluster in `src/lifecycle/` from the bare `Agent*` family to `Subagent*`, consolidate the duplicate `AgentStatus` union into the public `SubagentStatus`, and update the architecture doc.
+The plan is a 7-step refactor (no behavior change), each step an atomic language-service rename that leaves the tree green.
+
+### Observations
+
+- Scope decisions confirmed with the user via `ask_user`: (1) rename the module files too (`agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus test/helper files), and (2) full-consistency rename of adjacent identifiers — `subscribeAgentObserver`, the `SubagentManagerObserver` `onAgent*` methods, and the `createTestAgent` helper.
+- Layering catch: pointing `WorkspaceDisposeOutcome.status` directly at `service.ts`'s `SubagentStatus` would create a `lifecycle → service` cycle (`service.ts` already imports the workspace collaborator types).
+  Resolution: keep the union's single home in the lifecycle layer (`subagent.ts`) and have `service.ts` re-export it, mirroring the existing `LifetimeUsage` / workspace re-export pattern.
+- Acceptance-grep catch: the issue's `grep src/lifecycle/` for bare `Agent` matches comments and string literals (e.g. the two `"Agent not configured …"` error messages), not just symbols.
+  The language-service rename does not touch those, so each step must sweep residual comment/string occurrences; step 7 has a final grep gate.
+- Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`, `AgentTool`, `AgentSpawnConfig`) are not bare-word matches and are explicitly out of scope.
+- Non-breaking — `refactor:` commits throughout; `verify:public-types` runs after the status consolidation and the final step since the public bundle (`dist/public.d.ts`) is rolled from `src/service/service.ts`.
+- Also flagged the `package-pi-subagents` SKILL.md for an internals-naming update (it references `AgentManager`, `Agent`, `make-agent`).
+
+## Stage: Implementation — TDD (2026-05-31T00:38:55Z)
+
+### Session summary
+
+Completed 6 refactor commits (steps 1–6 from the plan, with step 5 folded into step 3) plus a `test:` commit for the helper rename and a `docs:` commit for the architecture doc update.
+All 973 tests pass across 59 test files with no test count delta.
+Pre-completion reviewer returned PASS with all 5 acceptance criteria verified.
+
+### Observations
+
+- Step 5 (`AgentManagerLike` → `SubagentManagerLike`) was automatically folded into step 3 because the bulk-rename Python script replaced all `AgentManager*` compounds at once — no separate commit was needed or appropriate.
+- The acceptance grep (`grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/`) also flags bare `Agent` in comments and error strings; each rename step swept those manually since the language-service rename does not touch non-symbol text.
+- `sed` with negative lookaheads failed on macOS for the `notification.ts` file; fell back to a two-pass approach (sed for the import, then `perl -i -0pe` with negative lookahead for the body).
+- `describe("Agent — ...)` test block names used em-dashes (Unicode U+2014); `sed` with `\u2014` escape did not match on macOS — required Python `re.sub` with the literal character.
+- The `SubagentStatus` type definition was kept in `src/lifecycle/subagent.ts` (single home) and re-exported from `src/service/service.ts`, matching the existing `LifetimeUsage` / workspace re-export pattern and avoiding a `lifecycle → service` cycle.
+- Docs: the architecture doc's session-encapsulation table had misaligned Markdown table columns after the rename (cell widths changed); `rumdl fmt` auto-fixed them.
+- Pre-completion reviewer: PASS — all deterministic checks, all 5 acceptance criteria, conventional commits, docs, Mermaid diagrams, and dead-code gate confirmed clean.
+
+## Stage: Final Retrospective (2026-05-31T01:05:57Z)
+
+### Session summary
+
+Shipped the full Planning → TDD → Ship lifecycle for the internal `Agent` → `Subagent` rename across `@gotgenes/pi-subagents`: 7 implementation commits (6 `refactor:`/`test:` + 1 `docs:`), 973 tests green throughout, CI passed on `27abb5aa`, and issue #280 closed.
+No release was triggered (all `refactor:`/`test:`/`docs:` commits), so no release-please PR appeared — expected.
+
+### Observations
+
+#### What went well
+
+- Two planning-stage catches prevented downstream rework: the `lifecycle → service` import cycle (resolved by keeping `SubagentStatus`'s single home in `subagent.ts` and re-exporting from `service.ts`) and the acceptance grep matching bare `Agent` in comments/strings (so each step swept non-symbol text).
+  Both were anticipated in the plan and held during execution.
+- Incremental verification carried the rename safely: `pnpm run check` plus the affected test files ran after every step, so the text-based substitution mistakes were caught instantly and never reached a commit.
+  The pre-completion reviewer then returned a clean PASS with nothing to fix.
+- The status re-export needed a follow-up `import type { SubagentStatus }` because `export type { … } from` does not create a local binding for `SubagentRecord` to reference — `pnpm run check` flagged it immediately, a one-edit fix.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan specified each rename as a "scope-aware language-service pass" (`findRenameLocations`), but the execution toolkit has no LSP-rename tool — only `Edit`, `Bash` (`sed`/`perl`/`python`), and `grep`.
+  Execution fell back to text substitution, which is exactly why the comment/string sweep was needed and why the regex gymnastics below happened.
+  Impact: added friction but no rework — `tsc` + tests caught every gap; no incorrect commit landed.
+- `other` (cross-platform tooling) — Repeated silent failures from BSD `sed` / `perl` one-liners: BSD `sed` lacks `\b` and lookahead; `perl -i ''` is malformed (the `-i ''` form is a `sed`-ism); neither interprets `\uXXXX` escapes, so em-dash `describe("Agent — …")` blocks and `notification.ts` body renames did not match.
+  Each failure forced a grep-verify-redo loop, ultimately resolved by switching to Python `re.sub`.
+  Impact: roughly 5–8 extra tool calls across the TDD stage; no rework beyond the redo cycles.
+
+#### What caused friction (user side)
+
+- None.
+  The user's two `ask_user` answers at planning time (file renames + full-consistency adjacent identifiers) front-loaded every scope decision, so the TDD and Ship stages ran without a single mid-course correction.
+
+### Diagnostic details
+
+- **Model-performance correlation** — One subagent dispatched (`pre-completion-reviewer`) on judgment-heavy review work (acceptance verification, Mermaid validation via `mmdc`, dead-code gate); appropriate match, no mismatch.
+- **Escalation-delay tracking** — The `notification.ts` body rename cycled ~4–5 consecutive `sed`/`perl`/`grep` calls on the same substitution before switching to `perl -i -0pe`; under the 5-call threshold but the closest the session came.
+  The general lesson (prefer Python `re.sub`) generalizes the fix.
+- **Unused-tool detection** — No Explore/`colgrep` gap: the codebase was already understood from planning, and an exact symbol rename is not a semantic-search task.
+  The only "missing capability" is a language-service rename tool, which is not in the toolkit — a genuine gap, not an unused option.
+- **Feedback-loop gap analysis** — No gap: `pnpm run check` and affected tests ran after each step (incremental); `pnpm run lint`, `pnpm fallow dead-code`, and `verify:public-types` ran as the final batch.
+  Verification cadence was correct.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0280-rename-agent-to-subagent.md`.
+2. Strengthened the global `APPEND_SYSTEM.md` "Shell Commands" rule to name the literal absolute-path `cd` form (e.g. `cd /Users/you/project &&`), not just `cd $CWD &&` — the existing rule failed to catch the literal-path form that agents actually emit.
+   This file is global (`~/.pi/agent/APPEND_SYSTEM.md`), outside the repo, so it is not committed here.
+3. Added a monorepo-specific line to `AGENTS.md` § Monorepo Structure: prefer `pnpm --filter @gotgenes/<pkg> run <script>` (or `pnpm -C packages/<pkg> run <script>`) from the root over `cd packages/<pkg> && pnpm run <script>`.
+   Prompted by excessive `cd` chaining observed across this session's Ship and Retro stages.
+
+### Follow-ups considered (not applied)
+
+1. Proposed adding a bulk-substitution tooling rule (prefer Python `re.sub` over `sed`/`perl` one-liners, since BSD `sed` lacks `\b`/lookahead and `\uXXXX` is uninterpreted) to the `code-design` skill's Tooling section.
+   The user opted to record the observation here only and skip the skill change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "13.2.1",
+  "version": "13.2.2",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -23,11 +23,11 @@ import {
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
-import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { SubagentManager, type SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { createSubagentRuntime } from "#src/runtime";
@@ -56,7 +56,7 @@ export default function (pi: ExtensionAPI) {
   const runtime = createSubagentRuntime();
 
   // ---- Notification system ----
-  // runtime.widget is assigned after AgentManager construction; arrow closures
+  // runtime.widget is assigned after SubagentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
@@ -76,8 +76,8 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer: AgentManagerObserver = {
-    onAgentStarted(record) {
+  const observer: SubagentManagerObserver = {
+    onSubagentStarted(record) {
       // Emit started event when agent transitions to running (including from queue).
       pi.events.emit("subagents:started", {
         id: record.id,
@@ -85,7 +85,7 @@ export default function (pi: ExtensionAPI) {
         description: record.description,
       });
     },
-    onAgentCompleted(record) {
+    onSubagentCompleted(record) {
       // Emit lifecycle event based on terminal status.
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
       const eventData = buildEventData(record);
@@ -110,7 +110,7 @@ export default function (pi: ExtensionAPI) {
 
       notifications.sendCompletion(record);
     },
-    onAgentCompacted(record, info) {
+    onSubagentCompacted(record, info) {
       // Emit compacted event when agent's session compacts (preserves count on record).
       pi.events.emit("subagents:compacted", {
         id: record.id,
@@ -121,7 +121,7 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
-    onAgentCreated(record) {
+    onSubagentCreated(record) {
       // Emit created event for background agents (before startAgent / queue drain).
       pi.events.emit("subagents:created", {
         id: record.id,
@@ -150,7 +150,7 @@ export default function (pi: ExtensionAPI) {
     lifecycle: createChildLifecyclePublisher((channel, data) => pi.events.emit(channel, data)),
   };
 
-  // ConcurrencyQueue: scheduling extracted from AgentManager.
+  // ConcurrencyQueue: scheduling extracted from SubagentManager.
   // startAgent callback forward-references manager via closure (safe — drain is never called during construction).
   const queue = new ConcurrencyQueue(
     () => settings.maxConcurrent,
@@ -161,7 +161,7 @@ export default function (pi: ExtensionAPI) {
     },
   );
 
-  const manager = new AgentManager({
+  const manager = new SubagentManager({
     createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
     baseCwd: process.cwd(),
     observer,

package/src/lifecycle/create-subagent-session.ts

@@ -5,7 +5,7 @@
  * `runAgent()` did up front: detect the environment, assemble the session config,
  * create the SDK session, publish `spawning`/`session-created`, bind extensions,
  * and apply the recursion guard. It returns a fully usable `SubagentSession` —
- * `Agent` then only coordinates (turn loop, steer, dispose).
+ * `Subagent` then only coordinates (turn loop, steer, dispose).
  *
  * The factory takes a resolved `cwd` value, never the WorkspaceProvider: `cwd`
  * is a value the factory consumes directly (detectEnv, assembleSessionConfig,