@gotgenes/pi-subagents 13.2.0 → 13.2.2

package/docs/architecture/history/phase-16-invert-dependencies.md

@@ -0,0 +1,144 @@
+# Phase 16: Invert dependencies — extensions on a minimal core
+
+## Summary
+
+Phase 16 reclaimed its original intent — invert the core's outbound dependencies — and extended it: worktree isolation joined permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+The decision and the full reasoning chain are recorded in [ADR-0002]; the two-surface extension model is described under [Target architecture](../architecture.md#target-architecture).
+
+All five steps are closed: [#261], [#262], [#263], [#264], [#265].
+
+## Two extension surfaces
+
+Extensions attach through exactly two surfaces, distinguished by the direction of information flow.
+
+1. **Lifecycle events (observational) — unlimited.**
+   The core emits awaited, ordered events for the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`).
+   Any number of extensions subscribe; handlers return nothing.
+   Reactive concerns live here: permission detection, telemetry, UI, notifications.
+   Adding a reactive concern never modifies the core.
+2. **Provider seams (generative) — rationed.**
+   The rare concern that must *inject* a value the core consumes synchronously registers a provider the core consults.
+   Today there is exactly one: the **workspace provider** (returns the child's working directory plus bracketed setup/teardown).
+   A provider seam is the only place the core is "open," so the list is kept as small as possible.
+
+The discriminator when deciding how a concern attaches:
+
+- It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
+- It must **return a value the core consumes** → register a provider (generative, rationed).
+
+The governing rule — **no vacant hooks**: the architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
+Latent extensibility is the deliverable; a vacant hook is not.
+
+## Abandoned exploration: agent collaborator architecture
+
+An earlier Phase 16 plan ("agent collaborator architecture") proposed giving `Agent` three collaborators — a session factory, a `WorktreeIsolation`, and a lifecycle observer — and dissolving the runner.
+That framing was abandoned.
+Pulling on a single late-bound `create(cwd?)` parameter on the planned `ChildSessionFactory` exposed deeper problems:
+
+- `WorktreeIsolation.setup()` is a two-phase `construct-then-setup()` that violates "Construct complete" (principle 8) — the worktree is only *ready* at dequeue.
+- The worktree and the child session share one lifespan, so they are one run-scoped resource, not sibling collaborators that `Agent` must sequence; the `cwd` parameter only existed because the worktree was split out and `Agent` relayed its output back in.
+- Worktrees are not intrinsic to subagents — they are one *workspace strategy* and belong outside the core, exactly as Phase 14 evicted tool/extension policy.
+
+Issue #256 (`WorktreeIsolation` as a collaborator) shipped under the abandoned plan and was superseded by #263; issue #257 (`ChildSessionFactory` extraction) was parked.
+Issues #258 (Agent owns session lifecycle via factory) and #259 (dissolve runner concept) belonged to the same abandoned plan — both depended on #256/#257 and were closed as not planned; their structural goals were recovered by Step 5 (#265) via a cleaner route.
+The structural win the collaborator plan chased — a born-complete child execution and the dissolution of the runner — is recovered once the workspace seam exists (Step 5).
+
+## Steps
+
+### Step 1: Child-execution lifecycle events; retire permission-bridge — [#261]
+
+Emit ordered child-execution events (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) carrying child identity (session directory, agent name, parent session id).
+Migrated `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disposed` for registration instead of being looked up by the core; deleted `permission-bridge.ts`.
+
+- Cross-package: pi-subagents (emit + remove bridge) and pi-permission-system (subscribe).
+- Investigation (resolved): `pi.events` is a Node `EventEmitter`, so `emit()` dispatches listeners synchronously on the same call stack — a synchronous subscriber completes before `emit()` returns.
+  Emitting `session-created` immediately before `bindExtensions()` therefore guarantees the registry entry lands pre-bind, with no new SDK hook.
+  The synchronous-handler constraint is encoded as a real-bus test in pi-permission-system.
+- Outcome: the core stops reaching out to a named consumer; permission detection rides events.
+- Deferred: removing the now-caller-less `registerSubagentSession`/`unregisterSubagentSession` from `PermissionsService` → #267; registry-detected resume ("executing now" → "exists" semantics) → #265.
+
+### Step 2: Define the `WorkspaceProvider` seam — [#262]
+
+Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
+All five workspace types are named-re-exported from `service.ts`: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` (added in #272).
+At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd.
+On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
+
+- The seam is additive and non-breaking.
+- Landed alongside its first consumer (Step 3) to avoid a vacant hook — the "no vacant hooks" rule.
+- Outcome: a single generative seam; the core no longer knows what an "isolation strategy" is.
+
+### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263]
+
+New package implementing `WorkspaceProvider`: prepares a git worktree at run-start (born complete), tears it down after (saving the branch), and owns the "changes saved to branch" result.
+Worktree isolation is opt-in per agent type via the package's own `worktreeAgents` config; creation failure for an opted-in agent throws (strict, no silent fallback).
+Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; dropped `isolation` from the spawn API and `SubagentsService`, and `worktreeResult` from `SubagentRecord`.
+
+- Supersedes #256.
+  New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`).
+- Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
+
+### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]
+
+Children always load the parent's extensions and skills; the recursion guard is now unconditional.
+Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
+The `skills` curation axis collapsed symmetrically with `extensions`: `AgentConfig.skills`, the skill-preload path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`), `SessionConfig.{extensions,noSkills,extras}`, and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are all gone.
+
+- Depended on: Step 1 (deny-at-use over events).
+- Outcome: the `isolated`/`extensions`/`noSkills`/`skills` axis is gone; the guard is unconditional.
+
+### Step 5: Born-complete child execution; dissolve the runner — [#265]
+
+`createSubagentSession()` is an assembly factory that returns a born-complete `SubagentSession` (session created, extensions bound, recursion guard applied).
+`SubagentSession` owns turn driving (`runTurnLoop`/`resumeTurnLoop`), steering, and disposal.
+`Agent.run()` is coordination, not assembly; `runAgent` / `resumeAgent` / `ConcreteAgentRunner` / `AgentRunner` / `RunOptions` / `RunResult` / `ExecutionState` dissolved.
+`getAgentConversation()` relocated to `session/conversation.ts`; `normalizeMaxTurns()` to `lifecycle/turn-limits.ts`.
+`disposed` now fires at true session disposal (cleanup), so resume executions are registry-detected (closing the gap deferred from #261).
+
+- Depends on: Steps 2–4.
+- Outcome: the "runner" concept is gone; `Agent.run()` is coordination, not assembly — the structural goal of the abandoned collaborator plan, reached cleanly.
+
+## Step dependency diagram
+
+```mermaid
+flowchart LR
+    S1["Step 1<br/>Lifecycle events<br/>(retire bridge)"]
+    S2["Step 2<br/>WorkspaceProvider seam"]
+    S3["Step 3<br/>Extract worktrees pkg"]
+    S4["Step 4<br/>Remove isolated"]
+    S5["Step 5<br/>Born-complete execution"]
+
+    S2 --> S3
+    S1 --> S4
+    S2 --> S5
+    S3 --> S5
+    S4 --> S5
+```
+
+## Tracks
+
+1. **Track A — Inversion seams** (Steps 1, 2): lifecycle events and the workspace seam.
+   Independent of each other — proceeded in parallel.
+2. **Track B — Eviction** (Steps 3, 4): worktrees and `isolated` leave the core.
+   Step 3 depends on Step 2.
+3. **Track C — Consolidation** (Step 5): dissolve the runner around the new seam.
+   Depends on Tracks A and B.
+
+## Composition model
+
+In the post-Phase-16 state, pi-subagents publishes events and a provider seam; other packages hook in:
+
+- **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
+- **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
+- **pi-subagents-ui** (future, Phase 17) subscribes to the service API, renders the widget, conversation viewer, and `/agents` menu.
+- **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
+
+Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
+
+[#261]: https://github.com/gotgenes/pi-packages/issues/261
+[#262]: https://github.com/gotgenes/pi-packages/issues/262
+[#263]: https://github.com/gotgenes/pi-packages/issues/263
+[#264]: https://github.com/gotgenes/pi-packages/issues/264
+[#265]: https://github.com/gotgenes/pi-packages/issues/265
+[ADR-0002]: ../../decisions/0002-extensions-on-a-minimal-core.md

package/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -27,7 +27,7 @@ A `tsc --traceResolution` of a sibling consuming the package surfaced two compou
 The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
 A shallow alias-free entry is therefore not achievable without a substantial source restructure.
 
-This collides with the ship-source model (ADR 0002): every package ships raw `.ts` executed directly by Pi, with no build step.
+This collides with the ship-source model ([ADR-0002]): every package ships raw `.ts` executed directly by Pi, with no build step.
 
 ## Decision
 
@@ -67,3 +67,5 @@ It is deliberately narrow: it produces type declarations only and changes nothin
 - The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
   This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
 - Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.
+
+[ADR-0002]: ./0002-extensions-on-a-minimal-core.md

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

@@ -3,14 +3,14 @@ issue: 51
 issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
 ---
 
-# Update ADR 0001 to reflect hard-fork decision
+# Update ADR-0001 to reflect hard-fork decision
 
 ## Problem Statement
 
-ADR 0001 (`docs/decisions/0001-deferred-patches.md`) was written when the fork was a thin-patch layer over `tintinweb/pi-subagents`.
+[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:
+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.
@@ -18,7 +18,7 @@ Several claims in ADR 0001 are now outdated:
 
 ## Goals
 
-- Add a supersession note to ADR 0001 pointing to `docs/architecture/architecture.md`.
+- 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.
@@ -31,7 +31,7 @@ Several claims in ADR 0001 are now outdated:
 
 ## Background
 
-ADR 0001 has YAML frontmatter (`status: accepted`, `date: 2026-05-11`) and follows a standard ADR structure: Status, Context, Decision, Consequences.
+[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.
 
@@ -60,7 +60,7 @@ No tests are affected — this is a docs-only change.
 
 ## TDD Order
 
-1. Update ADR 0001 with all four edits described above.
+1. Update [ADR-0001] with all four edits described above.
    Commit: `docs: update ADR 0001 to reflect hard-fork decision (#51)`
 
 ## Risks and Mitigations
@@ -73,3 +73,5 @@ No tests are affected — this is a docs-only change.
 ## Open Questions
 
 None — the issue's acceptance criteria are unambiguous.
+
+[ADR-0001]: ../decisions/0001-deferred-patches.md

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

@@ -6,7 +6,7 @@ issue_title: "Extract ChildSessionFactory from runner"
 # Extract ChildSessionFactory from runner
 
 > Superseded — issue #257 was closed `not_planned`.
-> Planning this extraction exposed that worktree isolation does not belong in the core; see [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md) and the reclaimed Phase 16 roadmap in [`docs/architecture/architecture.md`](../architecture/architecture.md).
+> Planning this extraction exposed that worktree isolation does not belong in the core; see [ADR-0002] and the reclaimed Phase 16 roadmap in [`docs/architecture/architecture.md`](../architecture/architecture.md).
 > The structural goal is recovered by #265.
 > This plan is retained for historical context only.
 
@@ -281,3 +281,5 @@ After all steps: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fa
   Deferred to Step 4, when the runner dissolves and the natural home for these creation contracts is the factory module.
 - Whether `ConcreteAgentRunner.createFactory()` lands in Step 3 (when `AgentManager` consumes it) exactly as the issue describes.
   Deferred to Step 3 per the Design Overview rationale.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

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

@@ -7,50 +7,50 @@ issue_title: "Add WorkspaceProvider extension seam"
 
 ## Problem Statement
 
-Phase 16, Step 2 of ADR 0002 (`packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md`).
-The core needs only a working directory and a disposal hook for a child run; the default — the parent's cwd, with no setup or teardown — is always correct.
+Phase 16, Step 2 of [ADR-0002].
+The core needs only a working directory and a disposal hook for a child run; the default - the parent's cwd, with no setup or teardown - is always correct.
 "Where does a child run, and what brackets the run?"
 is a *strategy* (git worktree, container, tmpdir, remote sandbox), not core behavior.
-ADR 0002 classifies this as the single *generative* extension surface: a concern that must return a value the core consumes synchronously attaches through a rationed provider seam, not an observational event.
-This issue adds that seam — `WorkspaceProvider` / `Workspace` plus `SubagentsService.registerWorkspaceProvider` — without the core gaining any knowledge of what an "isolation strategy" is.
+[ADR-0002] classifies this as the single *generative* extension surface: a concern that must return a value the core consumes synchronously attaches through a rationed provider seam, not an observational event.
+This issue adds that seam -`WorkspaceProvider` / `Workspace` plus `SubagentsService.registerWorkspaceProvider` - without the core gaining any knowledge of what an "isolation strategy" is.
 
 ## Goals
 
 - Define the `WorkspaceProvider` and `Workspace` interfaces in the core, with zero git or worktree knowledge.
-- Add `SubagentsService.registerWorkspaceProvider(provider): () => void` — a single-provider seam (chaining is out of scope) that throws if a provider is already registered and returns an unregister disposer.
-- At run-start, consult the registered provider for the child's cwd and a disposal handle; with no provider, the child runs in `baseCwd` (parent cwd — default behavior unchanged).
+- Add `SubagentsService.registerWorkspaceProvider(provider): () => void` - a single-provider seam (chaining is out of scope) that throws if a provider is already registered and returns an unregister disposer.
+- At run-start, consult the registered provider for the child's cwd and a disposal handle; with no provider, the child runs in `baseCwd` (parent cwd - default behavior unchanged).
 - Call `dispose()` after the run and append the returned `resultAddendum` to the child's result.
-- This change is **additive and non-breaking** — the existing `isolation: "worktree"` path is left intact (its eviction is #263).
+- This change is **additive and non-breaking** - the existing `isolation: "worktree"` path is left intact (its eviction is #263).
 
 ## Non-Goals
 
-- Removing `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, or the `isolation: "worktree"` spawn mode — deferred to #263.
-- Removing `isolated` / `extensions: false` / `noSkills` — deferred to #264.
-- Born-complete child execution / dissolving the runner — deferred to #265.
-- Multiple/chained providers — out of scope per the issue; one provider only.
-- Shipping a concrete provider implementation — the worktrees package (#263) is the seam's first real consumer.
+- Removing `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, or the `isolation: "worktree"` spawn mode - deferred to #263.
+- Removing `isolated` / `extensions: false` / `noSkills` - deferred to #264.
+- Born-complete child execution / dissolving the runner - deferred to #265.
+- Multiple/chained providers - out of scope per the issue; one provider only.
+- Shipping a concrete provider implementation - the worktrees package (#263) is the seam's first real consumer.
   Within this issue the seam is exercised only by test fakes; see Risks for the "no vacant hooks" release-coordination constraint.
 
 ## Background
 
 Relevant existing modules:
 
-- `src/lifecycle/agent.ts` — `Agent.run()` calls `this.worktree?.setup()` at run-start to obtain a cwd, threads it into `runner.run({ context: { cwd } })`, and on completion calls `this.worktree?.cleanup(description)`, appending a "Changes saved to branch …" addendum.
+- `src/lifecycle/agent.ts` - `Agent.run()` calls `this.worktree?.setup()` at run-start to obtain a cwd, threads it into `runner.run({ context: { cwd } })`, and on completion calls `this.worktree?.cleanup(description)`, appending a "Changes saved to branch ..." addendum.
   This is exactly the prepare/dispose shape the seam generalizes.
-- `src/lifecycle/worktree-isolation.ts` — `WorktreeIsolation` is the current run-scoped collaborator: `setup()` returns a path, `cleanup(description)` returns a `WorktreeCleanupResult`.
+- `src/lifecycle/worktree-isolation.ts` - `WorktreeIsolation` is the current run-scoped collaborator: `setup()` returns a path, `cleanup(description)` returns a `WorktreeCleanupResult`.
   The seam is its abstraction; #263 will reimplement it as a `WorkspaceProvider` in a separate package.
-- `src/lifecycle/agent-manager.ts` — constructs each `Agent`, owns the injected `WorktreeManager`, and threads `getRunConfig` as a getter.
+- `src/lifecycle/agent-manager.ts` - constructs each `Agent`, owns the injected `WorktreeManager`, and threads `getRunConfig` as a getter.
   The same getter pattern is reused for the workspace provider.
-- `src/service/service.ts` — the package's public API surface (`package.json` `exports` points at `./src/service.ts`).
+- `src/service/service.ts` - the package's public API surface (`package.json` `exports` points at `./src/service.ts`).
   `SubagentsService`, `SpawnOptions`, and `SubagentRecord` all live here; the seam types are re-exported here so the worktrees package can implement them.
-- `src/service/service-adapter.ts` — `SubagentsServiceAdapter implements SubagentsService`, wrapping the `AgentManagerLike` narrow interface.
-- `src/lifecycle/child-lifecycle.ts` — the *observational* lifecycle events from #261 (`spawning`, `session-created`, `completed`, `disposed`).
+- `src/service/service-adapter.ts` - `SubagentsServiceAdapter implements SubagentsService`, wrapping the `AgentManagerLike` narrow interface.
+- `src/lifecycle/child-lifecycle.ts` - the *observational* lifecycle events from #261 (`spawning`, `session-created`, `completed`, `disposed`).
   The provider seam is orthogonal: events tell consumers what happened; the provider returns a value the core consumes.
 
 AGENTS.md constraints that apply:
 
-- Pi SDK imports stay out of library modules — the seam interfaces and `AgentManager` accept the provider as a parameter; `index.ts` (the SDK edge) supplies `baseCwd: process.cwd()`.
-- Do not read `process.cwd()` inside library functions — `baseCwd` is injected into `AgentManager` from `index.ts`.
+- Pi SDK imports stay out of library modules - the seam interfaces and `AgentManager` accept the provider as a parameter; `index.ts` (the SDK edge) supplies `baseCwd: process.cwd()`.
+- Do not read `process.cwd()` inside library functions - `baseCwd` is injected into `AgentManager` from `index.ts`.
 - When adding a public API pattern, follow the established convention: the repo's registration/subscription convention is an unsubscribe **function** (`() => void`, as in `SubscribableSession.subscribe` and `pi.events.on`), not a `Symbol.dispose` `Disposable`.
   The seam therefore returns `() => void`; this is a deliberate divergence from the issue's literal `Disposable` to match the codebase convention.
 
@@ -97,10 +97,10 @@ export interface WorkspaceProvider {
 ```
 
 Note the addendum-formatting boundary: the core appends `resultAddendum` *verbatim*.
-The provider owns its own separator and wording (the worktrees package owns the "Changes saved to branch …" string in #263).
+The provider owns its own separator and wording (the worktrees package owns the "Changes saved to branch ..." string in #263).
 The core never formats branch text.
 
-### Registration — single provider, throw on duplicate
+### Registration - single provider, throw on duplicate
 
 `AgentManager` holds an optional provider and exposes registration:
 
@@ -130,7 +130,7 @@ The disposer clears the slot only if the same provider is still active, so a sta
 Provider-first precedence: when a provider supplies a workspace, the core routes cwd and dispose through it and skips the legacy worktree collaborator; with no provider it falls back to the existing worktree path; with neither it runs in `baseCwd` (cwd undefined → SDK uses the parent cwd).
 
 ```typescript
-// run() — replacing the worktree?.setup() block
+// run() - replacing the worktree?.setup() block
 let cwd: string | undefined;
 try {
   const provider = this._getWorkspaceProvider?.();
@@ -152,7 +152,7 @@ try {
   this.observer?.onRunFinished?.(this);
   return;
 }
-// … runner.run({ context: { cwd, parentSession }, … })
+// ... runner.run({ context: { cwd, parentSession }, ... })
 ```
 
 On completion (`completeRun`) the core computes the final status, then disposes:
@@ -165,7 +165,7 @@ if (this._workspace) {
   if (out?.resultAddendum) finalResult += out.resultAddendum;
 } else {
   const wt = this.worktree?.cleanup(this.description);
-  if (wt?.hasChanges && wt.branch) finalResult += `\n\n---\nChanges saved to branch \`${wt.branch}\`…`;
+  if (wt?.hasChanges && wt.branch) finalResult += `\n\n---\nChanges saved to branch \`${wt.branch}\`...`;
 }
 ```
 
@@ -197,7 +197,7 @@ Provider-first precedence means the two never silently conflict, and #263 collap
 | `src/lifecycle/agent-manager.ts`    | `AgentManagerOptions` gains required `baseCwd: string`. New `workspaceProvider` field, `registerWorkspaceProvider()` (throw on dup, unregister disposer). `spawn()` passes `baseCwd` and the `getWorkspaceProvider` getter into each `Agent`.                                                                                           |
 | `src/service/service.ts`            | Re-export the five seam types and `AgentStatus`. Add `registerWorkspaceProvider(provider: WorkspaceProvider): () => void` to the `SubagentsService` interface.                                                                                                                                                                          |
 | `src/service/service-adapter.ts`    | `AgentManagerLike` gains `registerWorkspaceProvider(provider): () => void`. `SubagentsServiceAdapter` implements the method, delegating to the manager.                                                                                                                                                                                 |
-| `src/index.ts`                      | Pass `baseCwd: process.cwd()` to the `new AgentManager({…})` construction (alongside the existing `GitWorktreeManager(process.cwd())`).                                                                                                                                                                                                 |
+| `src/index.ts`                      | Pass `baseCwd: process.cwd()` to the `new AgentManager({...})` construction (alongside the existing `GitWorktreeManager(process.cwd())`).                                                                                                                                                                                               |
 | `docs/architecture/architecture.md` | Mark Phase 16 Step 2 (#262) as landed in the roadmap; note the seam exists and `workspace.ts` is added to the lifecycle domain listing.                                                                                                                                                                                                 |
 
 No exports are removed or renamed, so no `src/`/`test/` removed-symbol grep is required.
@@ -206,8 +206,8 @@ No file in Module-Level Changes is also claimed as unchanged in Non-Goals (the w
 ### Grep checklist before finalizing
 
 - Objects typed as `SubagentsService` in tests: `test/service/service.test.ts` casts `{ spawn: () => "id" } as unknown as SubagentsService`, so adding an interface method does **not** break it (verified).
-- `new AgentManager(` call sites: `src/index.ts` (one) and `test/lifecycle/agent-manager.test.ts` `createManager` (one) — both updated for required `baseCwd` in the same step.
-- `AgentManagerLike` mocks in `test/service/service-adapter.test.ts` (`defaultManager`, inline `spawn:` stubs) — add `registerWorkspaceProvider` stub in the same step.
+- `new AgentManager(` call sites: `src/index.ts` (one) and `test/lifecycle/agent-manager.test.ts` `createManager` (one) - both updated for required `baseCwd` in the same step.
+- `AgentManagerLike` mocks in `test/service/service-adapter.test.ts` (`defaultManager`, inline `spawn:` stubs) - add `registerWorkspaceProvider` stub in the same step.
 
 ## Test Impact Analysis
 
@@ -216,36 +216,36 @@ This is an additive seam, so the work is dominated by *new* tests; little existi
 1. New unit tests the seam enables: provider registration (throw-on-duplicate, disposer-unregisters), run-start consultation (cwd from `prepare`, `resultAddendum` appended on dispose), `prepare` returns undefined → `baseCwd`, `prepare` rejects → `markError`, and adapter delegation.
    These were impossible before because there was no provider abstraction to substitute.
 2. Redundant existing tests: none.
-   The seam does not subsume worktree tests — they exercise the legacy path, which is preserved.
-3. Existing tests that must stay as-is: all `worktree.test.ts`, `worktree-isolation.test.ts`, and the AgentManager worktree-isolation tests (`calls worktrees.create` / `cleanup`) — they genuinely exercise the fallback path that remains in #262.
+   The seam does not subsume worktree tests - they exercise the legacy path, which is preserved.
+3. Existing tests that must stay as-is: all `worktree.test.ts`, `worktree-isolation.test.ts`, and the AgentManager worktree-isolation tests (`calls worktrees.create` / `cleanup`) - they genuinely exercise the fallback path that remains in #262.
    The Agent no-provider tests assert unchanged worktree behavior.
 
 ## TDD Order
 
-1. **Seam types + registration surface** — `feat`.
+1. **Seam types + registration surface** - `feat`.
    New `src/lifecycle/workspace.ts`; re-export seam types + `AgentStatus` from `service.ts`; add `registerWorkspaceProvider` to `SubagentsService`, `AgentManagerLike`, and `SubagentsServiceAdapter` (delegating); add required `baseCwd` + provider field + `registerWorkspaceProvider` (throw on dup, disposer) to `AgentManager`; update `index.ts` and the `createManager` test factory for `baseCwd`.
    Tests: `agent-manager.test.ts` registration (throws on second register; disposer clears only the active provider; getter returns the registered provider) and `service-adapter.test.ts` delegation.
-   This whole surface lands in one commit because the `SubagentsService` interface method forces the adapter to implement it and the required `baseCwd` forces both construction sites — splitting would not type-check.
+   This whole surface lands in one commit because the `SubagentsService` interface method forces the adapter to implement it and the required `baseCwd` forces both construction sites - splitting would not type-check.
    Suggested message: `feat: add WorkspaceProvider registration seam to subagents service`.
    Run `pnpm run check` immediately after (shared-interface change).
 
-2. **Run-start consumption + dispose** — `feat`.
+2. **Run-start consumption + dispose** - `feat`.
    `Agent`: `AgentInit` gains `baseCwd`/`getWorkspaceProvider`; new private fields; `run()` provider-first prepare; `completeRun`/`failRun` dispose + verbatim `resultAddendum`.
    `AgentManager.spawn` passes `baseCwd` and the `getWorkspaceProvider` getter (sole extra construction site, folded in).
-   Tests: `agent.test.ts` — provider `prepare` supplies cwd to the runner; `dispose` `resultAddendum` appended to the result; `prepare` undefined → cwd falls back to `baseCwd`; `prepare` rejects → `markError` + `onRunFinished`; no-provider path still uses the worktree collaborator (regression guard).
+   Tests: `agent.test.ts` - provider `prepare` supplies cwd to the runner; `dispose` `resultAddendum` appended to the result; `prepare` undefined → cwd falls back to `baseCwd`; `prepare` rejects → `markError` + `onRunFinished`; no-provider path still uses the worktree collaborator (regression guard).
    Suggested message: `feat: consult workspace provider for child cwd and disposal`.
    Run `pnpm run check` after (AgentInit change).
 
-3. **Architecture doc update** — `docs`.
+3. **Architecture doc update** - `docs`.
    Mark Phase 16 Step 2 (#262) landed in the roadmap; add `workspace.ts` to the lifecycle domain listing; cross-link the seam.
    Suggested message: `docs: record WorkspaceProvider seam in phase 16 roadmap`.
 
 ## Risks and Mitigations
 
 - **Vacant hook (the headline risk).**
-  ADR 0002's "no vacant hooks" rule says a provider seam with no consumer is a speculative abstraction that `fallow` flags as dead.
+  [ADR-0002]’s “no vacant hooks” rule says a provider seam with no consumer is a speculative abstraction that `fallow` flags as dead.
   Within #262 the seam is exercised only by test fakes.
-  Mitigation: land #262 **alongside** #263 (its first real consumer, `@gotgenes/pi-subagents-worktrees`) — do not cut a release that contains the seam without the worktrees package.
+  Mitigation: land #262 **alongside** #263 (its first real consumer, `@gotgenes/pi-subagents-worktrees`) - do not cut a release that contains the seam without the worktrees package.
   Track this as a release-coordination constraint; the architecture roadmap already pairs Steps 2 and 3.
 - **Dual cwd path confusion.**
   Provider-first precedence keeps worktree and provider from silently conflicting; the branch is documented and removed in #263.
@@ -257,6 +257,8 @@ This is an additive seam, so the work is dominated by *new* tests; little existi
 ## Open Questions
 
 - Should `baseCwd` eventually come from the parent `SessionContext.cwd` rather than `process.cwd()`?
-  Deferred — `process.cwd()` preserves current worktree behavior; revisit during the born-complete work (#265).
+  Deferred -`process.cwd()` preserves current worktree behavior; revisit during the born-complete work (#265).
 - Should the `disposed` lifecycle event (#261) and `Workspace.dispose` be reconciled into one teardown notion?
-  Deferred — they serve different surfaces (observational vs generative); revisit if #265 dissolves the runner.
+  Deferred - they serve different surfaces (observational vs generative); revisit if #265 dissolves the runner.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md