@gotgenes/pi-subagents 11.4.0 → 11.6.0

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

@@ -0,0 +1,202 @@
+---
+issue: 270
+issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
+---
+
+# Publish a bundled `.d.ts` for the pi-subagents public surface
+
+## Problem Statement
+
+`@gotgenes/pi-subagents` cannot be imported by another TypeScript package in this workspace.
+A sibling that writes `import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"` fails its `tsc` run.
+This blocks Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`), the first package that needs to import the subagents service and the `WorkspaceProvider` seam by name.
+
+Two compounding causes were confirmed empirically with `tsc --traceResolution`:
+
+1. `package.json` `exports["."]` points at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   This is a latent bug; nothing in-repo imports the package by name today.
+2. Once the path is corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via `#src/*`.
+   When a sibling's `tsc` follows the symlink and resolves those specifiers, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and point into the *consumer's* `src/` (a global-`paths` collision — both packages even define `#src/*`).
+   The fallback to the publisher's `package.json` `imports` field then fails too: tsc cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is also deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) pulls in `AgentStatus` from 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.
+
+## Goals
+
+- A consumer using the **published/packaged** `@gotgenes/pi-subagents` can `import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"` and have `tsc` pass.
+- Fix the stale `exports["."]` path so it resolves to a real file.
+- Emit a self-contained (alias-free) `.d.ts` for the public surface via `rollup-plugin-dts`, generated at pack/publish time and shipped in the npm tarball.
+- Add a verification harness that proves external consumability via `pnpm pack` → throwaway consumer → `tsc`, with no publish round-trip.
+- No regression to how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+- `feat:` — adds a publishable capability (a typed public API surface) to `pi-subagents`.
+
+## Non-Goals
+
+- No source restructuring to make the entry alias-free (the rejected alternative — see Background).
+  `src/` modules and `#src/*` internal imports are left exactly as they are.
+- No removal of worktree code from the core (`worktree.ts`, `worktree-isolation.ts`, `IsolationMode`, `isolation` spawn mode) — that is Issue #263.
+- No change to `pi-subagents-worktrees`' dependency wiring: it stays on `workspace:*` and does not yet import `@gotgenes/pi-subagents`.
+  Flipping it to registry consumption (drop `workspace:*`, set `link-workspace-packages: false`, point at the fixed version, wire the real import) is deferred to Issue #263, because the registry version carrying this fix does not exist until #270 is published.
+- No registration of `pi-subagents-worktrees` into `release-please-config.json` — that belongs to Issue #263 when it is ready to publish.
+
+## Background
+
+Relevant modules and facts:
+
+- `packages/pi-subagents/src/service/service.ts` — the real public entry.
+  Locally declares the public service contract (`SubagentsService`, `SubagentRecord`, `SpawnOptions`, `SubagentStatus`, `SUBAGENT_EVENTS`) and the `Symbol.for()` accessor functions (`publishSubagentsService`, `getSubagentsService`, `unpublishSubagentsService`).
+  Its only internal imports are `import type { LifetimeUsage }` and `import type { WorkspaceProvider }` — both type-only, so they erase at runtime.
+- `src/lifecycle/workspace.ts` — defines `WorkspaceProvider`, `Workspace`, and the prepare/dispose context types.
+  Imports `AgentStatus` from `#src/lifecycle/agent` and `AgentInvocation`/`SubagentType` from `#src/types`.
+- `src/lifecycle/usage.ts` — defines `LifetimeUsage` plus internal runtime helpers.
+- `src/lifecycle/agent.ts` (510 LOC) — defines `AgentStatus` near the top, alongside the `Agent` class and a wide `#src/*` import graph.
+- `src/index.ts` — the Pi extension entry; imports `publishSubagentsService`/`unpublishSubagentsService` from `#src/service/service` (internal use, unaffected).
+
+Constraints from `AGENTS.md` and the package skill:
+
+- Ship-source model: every package ships raw `.ts` executed directly by Pi; there is no build step today.
+  ADR 0002 frames pi-subagents as a minimal core.
+  Introducing the repo's **first build step** is a deliberate decision and warrants an ADR.
+- `eslint`'s `no-parent-relative-imports` rule forbids `../` imports inside `packages/*/src`; same-directory `./` is allowed.
+  This (plus the deep type entanglement above) is why the alias-free-entry alternative was rejected.
+- New packages and internal docs subdirectories must be added to `release-please-config.json` `exclude-paths` where appropriate.
+
+Rejected alternative (recorded for the ADR): restructure the source so the entry's full type closure is alias-free (leaf types module imported via `./`).
+It is mechanically possible but requires moving `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and reworking the `agent.ts`/`types.ts` entanglement, with care around dependency direction (inner layers must not import the outer service layer).
+Larger blast radius than emitting a `.d.ts`.
+
+Release/CI mechanics relevant to sequencing:
+
+- CI publishes only when the `release-please` PR is merged (`publish` job gated on `releases_created == true`), not on every push to `main`.
+- `release-please` batches all releasable commits per component.
+  The `#263` scaffold commits on `main` touch only the `pi-subagents-worktrees` component (which is **not** registered in `release-please-config.json`), so they neither trigger a release nor batch into `pi-subagents`.
+
+## Design Overview
+
+### Conditional exports
+
+Point the `types` condition at the bundled declaration and the runtime condition at the real source module:
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime `await import("@gotgenes/pi-subagents")` (the accessor functions; its `import type` lines erase, so no runtime `#src/*` resolution is needed).
+- `types` → `./dist/public.d.ts` gives a consumer's `tsc` a self-contained declaration that never references `#src/*`, sidestepping both the `paths` collision and the `imports`-field resolution failure.
+
+### Bundled declaration emit
+
+`rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into a single `dist/public.d.ts`.
+It tree-shakes to only the types reachable from the entry's exports — `SubagentsService`, `SubagentRecord`, `SpawnOptions`, `SubagentStatus`, `SUBAGENT_EVENTS`, the accessor signatures, plus the seam closure (`WorkspaceProvider`, `Workspace`, the context types, `AgentStatus`, `AgentInvocation`, `SubagentType`) and `LifetimeUsage`, all inlined.
+Imports from `@earendil-works/*` and `@sinclair/typebox` remain **external** in the output (the consumer has them as peers), so they are not inlined.
+
+We ship `.ts` source, so we want **only** the `.d.ts` — no JS bundle.
+`rollup-plugin-dts` does exactly that.
+
+Resolution note (primary feasibility risk): the roll-up must resolve the publisher's `#src/*` specifiers while parsing the type graph.
+`rollup-plugin-dts` drives the TypeScript compiler, which reads `compilerOptions.paths`; the build config references a tsconfig carrying the existing `#src/*` → `./src/*` paths.
+If `#src/*` does not resolve out of the box, add a tsconfig-paths/alias resolver to the rollup config.
+The first build step (below) is the checkpoint that proves this.
+
+### Generation timing and packaging
+
+- `prepack` runs `build:types` before both `pnpm pack` and `pnpm publish` (publish packs internally), so the tarball always contains a freshly generated `dist/public.d.ts`.
+- `dist/` is gitignored, so the artifact is **never committed**.
+- A `files` allowlist is added so the gitignored `dist/` is included in the published tarball.
+  The allowlist must preserve everything currently published (the whole `src/` tree, `docs/`, `README.md`, `LICENSE`, `CHANGELOG.md`, `AGENTS.md`, `.prettierignore`) plus `dist/`.
+  Validate parity with `pnpm pack --dry-run` before/after.
+
+### Verification harness (the proof)
+
+A script (run locally and in CI) proves external consumability without a publish:
+
+```bash
+# pseudocode — scripts/verify-public-types.sh
+pnpm --filter @gotgenes/pi-subagents pack --pack-destination "$TMP"   # triggers prepack → build:types
+cd "$TMP/consumer"                                                     # minimal package.json + tsconfig
+pnpm add "$TMP/gotgenes-pi-subagents-*.tgz" \
+  @earendil-works/pi-ai @earendil-works/pi-coding-agent @earendil-works/pi-tui typescript
+# probe.ts: import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"
+pnpm exec tsc --noEmit                                                 # must pass
+```
+
+Plus a cheap self-containment guard: assert `dist/public.d.ts` exists, exports the expected symbols, and contains no `#src/` substring (proving it is alias-free).
+
+## Module-Level Changes
+
+- `packages/pi-subagents/package.json`
+  - `exports["."]` → `{ "types": "./dist/public.d.ts", "default": "./src/service/service.ts" }`.
+  - Add `devDependencies`: `rollup`, `rollup-plugin-dts` (package-specific, not catalog — only this package builds types).
+  - Add scripts: `"build:types"` (runs rollup with the dts config) and `"prepack": "pnpm run build:types"`; add `"verify:public-types"` invoking the harness script.
+  - Add a `files` allowlist including `src`, `dist`, `docs`, `README.md`, `LICENSE`, `CHANGELOG.md`, `AGENTS.md`, `.prettierignore` (validated against `pnpm pack --dry-run`).
+- `packages/pi-subagents/rollup.dts.config.mjs` — **new**.
+  Entry `src/service/service.ts` → output `dist/public.d.ts`; `rollup-plugin-dts` with the package tsconfig (for `#src/*` paths); externals = peer deps + `@sinclair/typebox`.
+- `packages/pi-subagents/scripts/verify-public-types.sh` (or repo-level `scripts/`) — **new**.
+  Pack → throwaway consumer → `tsc`, plus the self-containment grep guard.
+- `.github/workflows/ci.yml`
+  - Add a "Verify public types" step in the `check` job (runs on PR and `main`) invoking `pnpm --filter @gotgenes/pi-subagents run verify:public-types`.
+- `packages/pi-subagents/docs/decisions/0003-publish-bundled-type-declarations.md` — **new** ADR.
+  Records the first-build-step decision, the rejected alias-free alternative, and the ship-source tradeoff (docs path; `exclude-paths` already covers `docs/decisions`, so it does not trigger a release).
+
+No `src/` module is added, renamed, or removed; no exported symbol is removed.
+No `docs/architecture/` layout/complexity tables reference `dist/` or the build config, so no architecture-doc edits are required beyond the ADR (optionally cross-link a one-line "build step" note — defer to build stage).
+
+## Test Impact Analysis
+
+This is a build/packaging change; `src/` is untouched, so the existing vitest suite (362 tests) is unaffected and stays as-is.
+
+1. New verification this enables: a packaged-artifact consumability check (`pnpm pack` → consumer `tsc`) that did not exist and was previously impossible (the package was not consumable at all).
+2. No existing tests become redundant — none currently exercise packaging or the public `exports`.
+3. No existing tests must change; the public service contract types in `service.ts` are unchanged.
+
+## Build Order
+
+This is a tooling/config change with a verification harness (not red→green→refactor), so it proceeds as build steps that each leave the repo valid.
+
+1. **Emit checkpoint.**
+   Add `rollup` + `rollup-plugin-dts` devDeps, write `rollup.dts.config.mjs`, add the `build:types` script.
+   Run `build:types`; confirm `dist/public.d.ts` is generated, exports the expected symbols, and contains no `#src/` substring (resolve the `#src/*` resolution risk here — add a paths/alias resolver if needed).
+   Commit: `build(pi-subagents): bundle public .d.ts with rollup-plugin-dts`.
+2. **Wire exports + packaging.**
+   Set the conditional `exports` (`types` + `default`, fixing the stale path), add `prepack`, add the `files` allowlist; validate `pnpm pack --dry-run` parity (no currently-shipped file dropped; `dist/public.d.ts` present).
+   Commit: `feat(pi-subagents): publish bundled type declarations and fix stale exports path`.
+3. **Verification harness + CI.**
+   Add `scripts/verify-public-types.sh` (pack → throwaway consumer → `tsc`, plus self-containment guard), the `verify:public-types` script, and the CI step.
+   Commit: `test(pi-subagents): verify the public surface is type-consumable from the packaged tarball`.
+4. **ADR.**
+   Add `docs/decisions/0003-publish-bundled-type-declarations.md`.
+   Commit: `docs(pi-subagents): record decision to publish bundled type declarations (ADR 0003)`.
+
+## Risks and Mitigations
+
+- **`rollup-plugin-dts` cannot resolve `#src/*`** (primary risk).
+  Mitigation: drive it with the package tsconfig (which carries `#src/*` paths); if needed, add a tsconfig-paths/alias resolver.
+  Step 1 is the explicit checkpoint — if it cannot produce an alias-free `dist/public.d.ts`, stop and reassess before wiring exports.
+- **Deep type graph via `agent.ts`.**
+  The seam closure reaches the 510-LOC `agent.ts`.
+  Mitigation: `rollup-plugin-dts` tree-shakes to only reachable types; the self-containment guard asserts the output is minimal and alias-free.
+- **`files` allowlist drops currently-published files.**
+  Mitigation: diff `pnpm pack --dry-run` before/after; the allowlist must reproduce the existing tarball plus `dist/`.
+- **`types` condition points at a gitignored, build-time artifact.**
+  An in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  Mitigation: tight scope — `pi-subagents-worktrees` does not import the package yet; #263 consumes the built artifact from the published tarball.
+- **Release batching / ordering with #263.**
+  Once #263 resumes and edits `pi-subagents` core, its commits batch into the same `pi-subagents` release.
+  Mitigation: publish #270 first (merge its release-please PR → `pi-subagents` publishes), then resume #263 against the published version.
+  The current `#263` scaffold commits touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` today.
+- **`prepack` must fire under the publish path.**
+  `scripts/publish-released.sh` runs `pnpm --filter @gotgenes/pi-subagents publish`, which packs and therefore runs `prepack`.
+  Mitigation: the verification harness exercises the same `pnpm pack` path that publish uses.
+
+## Open Questions
+
+- Whether to add a fast vitest self-containment assertion in addition to the shell harness, or keep the guard inside the script only — defer to the build stage.
+- Whether the ADR should add a short "build process" subsection to `docs/architecture/architecture.md` — defer; the ADR is sufficient.
+- Exact `files` allowlist entries — finalize against `pnpm pack --dry-run` in Step 2.

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

@@ -0,0 +1,87 @@
+---
+issue: 262
+issue_title: "Add WorkspaceProvider extension seam"
+---
+
+# Retro: #262 — Add WorkspaceProvider extension seam
+
+## Stage: Planning (2026-05-29T14:51:15Z)
+
+### Session summary
+
+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`).
+
+### Observations
+
+- Two ambiguous choices were surfaced via `ask_user` and resolved: **scope = additive seam only** (Option A — leave the legacy worktree path; #263 evicts it), and **duplicate registration = throw** (loud misconfiguration surface, disposer clears only the active provider).
+- The package's public surface is `./src/service.ts` (per `package.json` `exports`), so the seam types are defined in a new core `src/lifecycle/workspace.ts` and re-exported from `service.ts` — avoiding a `service ↔ lifecycle` import cycle while still exposing them to the worktrees consumer.
+- Diverged from the issue's literal `Disposable` return type: the repo convention for unsubscribe/unregister is a plain `() => void` (matching `SubscribableSession.subscribe` and `pi.events.on`); no `Symbol.dispose` usage exists anywhere in the codebase.
+- Provider-first precedence was chosen so the new seam and the legacy worktree collaborator never silently conflict during the transient dual-path window (#263 collapses the branch).
+- Headline risk is the ADR "no vacant hooks" rule: within #262 the seam is exercised only by test fakes, so it must land **alongside** #263 (`@gotgenes/pi-subagents-worktrees`) and not ship in a release on its own.
+- Step 1 bundles the entire registration surface (types, `SubagentsService` method, adapter impl, `AgentManagerLike`, required `baseCwd`) into one commit because the interface method forces the adapter and the required field forces both construction sites — splitting would not type-check.
+- Verified `test/service/service.test.ts` casts its mock `as unknown as SubagentsService`, so adding an interface method does not break it; flagged the `createManager` and `AgentManagerLike` mock updates for the `baseCwd` and registration additions.
+
+## Stage: Implementation — TDD (2026-05-29T15:09:49Z)
+
+### Session summary
+
+Implemented the `WorkspaceProvider` seam across three TDD cycles (two `feat`, one `docs`): the registration surface (`AgentManager.registerWorkspaceProvider` + service/adapter delegation + `workspace.ts` types), run-start consumption in `Agent.run()` with provider-first precedence and `dispose`/`resultAddendum`, and an architecture-doc update.
+Test count went from 1049 to 1061 (+12 new tests; +6 in `agent.test.ts`, +4 registration in `agent-manager.test.ts`, +1 adapter delegation, plus existing-helper additions).
+All deterministic gates green: `check`, `lint`, `test`, and `fallow dead-code` (run from repo root).
+
+### Observations
+
+- Deviation from plan (Module-Level Changes): the plan said `service.ts` would re-export "the five seam types and `AgentStatus`", but `fallow dead-code` flagged those five re-exports as unused (no consumer until #263), and AGENTS.md forbids speculative re-exports.
+  Resolved by re-exporting only `WorkspaceProvider` — a consumer assigning to it gets `Workspace` and the context types via inference; #263 adds named re-exports when it imports them.
+  This is the concrete manifestation of the plan's headline "vacant hook" risk surfacing in the dead-code gate.
+- Lint surprise: `WorkspaceDisposeResult | void` tripped eslint `no-invalid-void-type`.
+  Changed the `dispose` return type to `WorkspaceDisposeResult | undefined` (equivalent — a side-effecting `dispose` that falls off the end returns `undefined`); minor divergence from the issue's literal `| void`.
+- Three test mock factories implement `AgentManagerLike` in `service-adapter.test.ts` (`createMockManager`, `defaultManager`, `createTestManager`) — all three needed the new `registerWorkspaceProvider` stub; `tsc` caught the third after the first two were updated.
+- Used `git commit --fixup` + `--autosquash` rebase twice (unpushed history) to fold the fallow trim into the Step 1 `feat` commit and the reviewer's doc-wording fix into the Step 3 `docs` commit, keeping each commit self-consistent.
+- Pre-completion reviewer: WARN — all blocking checks pass; one non-blocking doc finding (architecture.md overstated that `Workspace` is re-exported).
+  Addressed before finishing.
+
+## Stage: Final Retrospective (2026-05-29T15:40:54Z)
+
+### Session summary
+
+Shipped #262: pushed, CI green, closed the issue, and merged release-please PR #269 → `pi-subagents-v11.5.0`.
+Mid-session the user asked what `model: claude-sonnet-4-6-20260526` in `.pi/agents/pre-completion-reviewer.md` resolved to; investigation found it had no entry in Pi's model registry and was silently falling back to the parent session model, and the fix (`anthropic/claude-sonnet-4-6`) landed in `1e46c5f4`.
+Across all stages the plan's risk predictions held and TDD verification was incremental.
+
+### Observations
+
+#### What went well
+
+- The planning-stage "vacant hook" risk prediction manifested exactly as predicted at the `fallow dead-code` gate: the plan named the failure (speculative re-exports flagged dead) before it happened, and the fix (re-export only `WorkspaceProvider`) was already reasoned out — a clean closed loop from planning risk to implementation gate.
+- Incremental verification during TDD: `check` / `test` / `lint` ran after each step plus per-file vitest red→green, not just at the end.
+- The model-spec question surfaced and fixed a latent silent bug — the reviewer's configured `model:` had no registry entry and was inheriting the parent model, so the misconfiguration produced no error.
+- Cost discipline: the session model was switched to `opencode-go/deepseek-v4-flash` for the mechanical shipping stage — appropriate model-to-task matching.
+
+#### What caused friction (agent side)
+
+- `rabbit-hole` — the model-resolution investigation (≈30 tool calls, turns 119–160) grepped the Pi core monorepo (`~/development/pi/pi/packages/coding-agent`) for `.pi/agents/` frontmatter handling that does not live there, before landing on `pi-prompt-template-model/model-selection.ts` (a `pi-packages` dependency) plus the `models.generated.ts` registry.
+  Impact: long detour on a user tangent; no rework, but the answer was reachable far sooner.
+- `other` (minor, recurring) — the pre-commit `trim trailing whitespace` hook reformatted files on the first `git commit`, failing it; the immediate retry succeeded (turns 55→56 and 95→96).
+  Impact: one wasted commit attempt per occurrence, no rework.
+
+#### What caused friction (user side)
+
+- The broken model spec was pre-existing config; because the failure mode is a silent fallback, such typos never surface on their own.
+  Opportunity (not criticism): a short convention note so future `.pi/agents/*.md` authoring uses the registry-resolvable `provider/id` form.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the `pre-completion-reviewer` subagent was dispatched (turn 90) while the parent model was `anthropic/claude-opus-4-8`; because its `model:` frontmatter did not resolve, it ran on opus-4-8 (strong reasoning, appropriate for judgment-heavy review) rather than the configured Sonnet.
+  No quality mismatch in outcome, but the risk was latent: a weaker parent model would have silently degraded the reviewer.
+  The shipping stage ran on `deepseek-v4-flash` (mechanical git/CI/release ops) — appropriate.
+- **Escalation-delay tracking** — the model-resolution `rabbit-hole` ran ≈30 consecutive search calls on the same goal, far past the 5-call threshold; consulting the `prompt-template-authoring` skill or reading `model-selection.ts` first would have shortcut it.
+- **Unused-tool detection** — for that investigation the `prompt-template-authoring` skill (documents template/agent `model:` format) and `code_search` were available but not used; grep over two monorepos was used instead.
+- **Feedback-loop gap analysis** — none; verification ran incrementally after each TDD step, not only at the end.
+
+### Changes made
+
+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.

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

@@ -0,0 +1,56 @@
+---
+issue: 270
+issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
+---
+
+# Retro: #270 — Make @gotgenes/pi-subagents type-consumable by sibling workspace packages
+
+## Stage: Planning (2026-05-29T00:00:00Z)
+
+### Session summary
+
+Diagnosed the consumability failure empirically with `tsc --traceResolution` and planned a `.d.ts`-emit fix.
+The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`, wires conditional `exports` (`types` → the bundle, `default` → the real source), generates the artifact at `prepack` time, ships it via a `files` allowlist, and proves external consumability with a `pnpm pack` → throwaway-consumer → `tsc` harness.
+
+### Observations
+
+- Root cause is two compounding failures: the stale `exports["."]` path (`./src/service.ts` does not exist) and, once fixed, an unresolvable `#src/*` cascade.
+  The trace showed the consumer's own `paths` (`#src/*` → `./src/*`) intercept first (both packages define `#src/*`), and the publisher's `imports`-field fallback cannot resolve the extensionless `.ts` target.
+- The public type closure is entangled: `WorkspaceProvider` → `AgentStatus` (in the 510-LOC `agent.ts`) → `types.ts` (which re-exports the `Agent` class).
+  This made the alias-free-entry alternative (Option 2) a substantial source restructure, so it was rejected.
+- Decisions taken via `ask_user`:
+  1. Approach — emit a bundled `.d.ts` (the repo's first build step), over alias-free restructure or type re-declaration.
+  2. Bundler — `rollup-plugin-dts` (purpose-built for flattening declarations; no JS bundle, which suits ship-source), over `tsdown`/`api-extractor`.
+  3. Artifact — not committed; generated at `prepack` and shipped in the tarball, consumed via the package interface.
+  4. Scope — tight: packaging + a `pnpm pack`-based verification harness in #270; defer the `pi-subagents-worktrees` registry-consumption flip (drop `workspace:*`, `link-workspace-packages: false`, wire the real import) to #263.
+- Scope was deliberately narrowed after a chicken-and-egg surfaced: the registry version carrying the fix does not exist until #270 publishes, so the meaningful consumer flip belongs to #263.
+- Sequencing constraint for #263 (captured in the plan): publish #270 first — merge its release-please PR so `pi-subagents` publishes — *before* resuming #263, otherwise #263's `pi-subagents` core edits batch into the same release.
+  The current `#263` scaffold commits on `main` touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` and #270 ships cleanly.
+- Primary feasibility risk flagged: whether `rollup-plugin-dts` resolves `#src/*` while rolling up the type graph.
+  Build Step 1 is the explicit checkpoint (emit + assert the output is alias-free and exports the expected symbols).
+- `dist/` is gitignored and already excluded by eslint/biome; the new wrinkle is that a `files` allowlist is required so the gitignored `dist/public.d.ts` is included in the npm tarball — validate `pnpm pack --dry-run` parity so no currently-shipped file is dropped.
+
+## Stage: Implementation — Build (2026-05-29T00:00:00Z)
+
+### 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.
+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.
+
+### Observations
+
+- The primary feasibility risk (`rollup-plugin-dts` resolving `#src/*`) resolved cleanly out of the box: driving it with the package `tsconfig` (which carries the `#src/*` paths) produced a 178-line `dist/public.d.ts` with zero `#src/` residue and only `ThinkingLevel` kept external from `@earendil-works/pi-ai`.
+  No alias/path resolver plugin was needed.
+- Harness deviation (fixed in the same step): `pnpm add` in the isolated (`--ignore-workspace`) throwaway consumer exited non-zero with `ERR_PNPM_IGNORED_BUILDS` because it does not inherit the workspace `allowBuilds` approvals (`@google/genai`, `protobufjs`).
+  Fixed by adding `--ignore-scripts` — a type-check needs no dependency build scripts.
+  Worth remembering for any future packaged-consumer harness.
+- A subtle gotcha while debugging: `pnpm ... | tail; echo $?` reports `tail`'s exit, not pnpm's, which masked the real failure.
+  Use `set -o pipefail` or check the command directly.
+- `files` allowlist parity was validated with a before/after `pnpm pack --dry-run` diff: nothing dropped, only `dist/public.d.ts` added.
+  The allowlist reproduces the current contents (`src`, `docs`, `vitest.config.ts`, `AGENTS.md`, `CHANGELOG.md`, `.prettierignore`) plus `dist`.
+  Did not take the opportunity to slim the tarball (docs/test-config still ship) — that would be a separate deliberate change.
+- Runtime `default` → `./src/service/service.ts` is safe because that module's only internal imports are `import type`, which erase; no runtime `#src/*` resolution occurs.
+- No `src/`/`test/` `.ts` files were touched, so the vitest suite and `tsc` were unaffected (confirmed via root check).
+- Pre-completion reviewer: WARN — no findings attributable to this session.
+  Reviewer warnings: (1) the `package-pi-subagents` skill lacked a build-step note — addressed in commit `2ff5a375`; (2) `pnpm fallow dead-code` exits non-zero on a pre-existing finding in `packages/pi-subagents-worktrees/package.json` from the #263 scaffold (commit `9a7dcfc5`), out of scope for #270 and left for #263.

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.4.0",
+  "version": "11.6.0",
   "type": "module",
   "exports": {
-    ".": "./src/service.ts"
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service/service.ts"
+    }
   },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "vitest.config.ts",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    ".prettierignore"
+  ],
   "imports": {
     "#src/*": "./src/*",
     "#test/*": "./test/*"
@@ -51,6 +63,8 @@
     "@earendil-works/pi-coding-agent": "0.75.4",
     "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
@@ -64,6 +78,8 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",

package/src/index.ts

@@ -167,6 +167,7 @@ export default function (pi: ExtensionAPI) {
   const manager = new AgentManager({
     runner: new ConcreteAgentRunner(runnerDeps),
     worktrees: new GitWorktreeManager(process.cwd()),
+    baseCwd: process.cwd(),
     observer,
     queue,
     getRunConfig: () => settings,

package/src/lifecycle/agent-manager.ts

@@ -13,6 +13,7 @@ import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 import { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 
@@ -33,6 +34,8 @@ export interface AgentManagerOptions {
   worktrees: WorktreeManager;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
+  /** Base working directory handed to a workspace provider (the parent cwd). */
+  baseCwd: string;
   getRunConfig?: () => RunConfig;
   observer?: AgentManagerObserver;
 }
@@ -70,12 +73,20 @@ export class AgentManager {
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
   private readonly queue: ConcurrencyQueue;
+  private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
+  private _workspaceProvider?: WorkspaceProvider;
+
+  /** The registered workspace provider, or undefined when none is registered. */
+  get workspaceProvider(): WorkspaceProvider | undefined {
+    return this._workspaceProvider;
+  }
 
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
     this.queue = options.queue;
+    this.baseCwd = options.baseCwd;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
@@ -83,6 +94,23 @@ export class AgentManager {
     this.cleanupInterval.unref();
   }
 
+  /**
+   * Register the single workspace provider. Throws if one is already
+   * registered (chaining is out of scope — see ADR 0002). Returns a disposer
+   * that clears the slot only if this provider is still the active one.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    if (this._workspaceProvider) {
+      throw new Error(
+        "A WorkspaceProvider is already registered; only one is supported.",
+      );
+    }
+    this._workspaceProvider = provider;
+    return () => {
+      if (this._workspaceProvider === provider) this._workspaceProvider = undefined;
+    };
+  }
+
   /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
   private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
     return {
@@ -140,6 +168,8 @@ export class AgentManager {
           : undefined,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
+      baseCwd: this.baseCwd,
+      getWorkspaceProvider: () => this._workspaceProvider,
     });
     this.agents.set(id, record);
 

package/src/lifecycle/agent.ts

@@ -26,6 +26,7 @@ import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
+import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
@@ -72,6 +73,10 @@ export interface AgentInit {
 	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
+	/** Resolves the registered workspace provider (if any) at run-start. */
+	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	/** Parent working directory handed to a workspace provider's prepare(). */
+	baseCwd?: string;
 
 	// Run config (required for run(), optional for tests)
 	snapshot?: ParentSnapshot;
@@ -129,6 +134,10 @@ export class Agent {
 	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
+	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	private readonly _baseCwd: string;
+	/** Workspace prepared at run-start by a provider — undefined when none is registered. */
+	private _workspace?: Workspace;
 
 	// Run config — optional (required for run())
 	private readonly _snapshot?: ParentSnapshot;
@@ -186,6 +195,8 @@ export class Agent {
 		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
+		this._getWorkspaceProvider = init.getWorkspaceProvider;
+		this._baseCwd = init.baseCwd ?? "";
 
 		// Run config
 		this._snapshot = init.snapshot;
@@ -223,8 +234,23 @@ export class Agent {
 		this.observer?.onStarted?.(this);
 		this.wireSignal(this._signal, () => this.abort());
 
+		let cwd: string | undefined;
 		try {
-			this.worktree?.setup();
+			// Provider-first: a registered workspace provider supplies the cwd and
+			// owns teardown; otherwise fall back to the legacy worktree collaborator.
+			const provider = this._getWorkspaceProvider?.();
+			if (provider) {
+				this._workspace = await provider.prepare({
+					agentId: this.id,
+					agentType: this.type,
+					baseCwd: this._baseCwd,
+					invocation: this.invocation,
+				});
+				cwd = this._workspace?.cwd;
+			} else {
+				this.worktree?.setup();
+				cwd = this.worktree?.path;
+			}
 		} catch (err) {
 			this.markError(err);
 			this.releaseListeners();
@@ -236,7 +262,7 @@ export class Agent {
 		try {
 			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
 				context: {
-					cwd: this.worktree?.path,
+					cwd,
 					parentSession: this._parentSession,
 				},
 				model: this._model,
@@ -442,9 +468,19 @@ export class Agent {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		const wtResult = this.worktree?.cleanup(this.description);
-		if (wtResult?.hasChanges && wtResult.branch) {
-			finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+		if (this._workspace) {
+			const finalStatus: AgentStatus = result.aborted
+				? "aborted"
+				: result.steered
+					? "steered"
+					: "completed";
+			const disposeResult = this._workspace.dispose({ status: finalStatus, description: this.description });
+			if (disposeResult?.resultAddendum) finalResult += disposeResult.resultAddendum;
+		} else {
+			const wtResult = this.worktree?.cleanup(this.description);
+			if (wtResult?.hasChanges && wtResult.branch) {
+				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+			}
 		}
 
 		if (result.aborted) this.markAborted(finalResult);
@@ -465,8 +501,9 @@ export class Agent {
 		this.releaseListeners();
 
 		try {
-			this.worktree?.cleanup(this.description);
-		} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
+			else this.worktree?.cleanup(this.description);
+		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
 		this.observer?.onRunFinished?.(this);
 	}

package/src/lifecycle/workspace.ts

@@ -0,0 +1,47 @@
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+import type { AgentStatus } from "#src/lifecycle/agent";
+import type { AgentInvocation, SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+  invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  status: AgentStatus;
+  description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+  /** Appended verbatim to the child's result text — the provider owns the wording. */
+  resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+  /** The working directory — already exists when the workspace is handed back. */
+  readonly cwd: string;
+  dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+  prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}