@gotgenes/pi-subagents 11.5.0 → 12.0.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [12.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.6.0...pi-subagents-v12.0.0) (2026-05-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* SubagentRecord no longer carries worktreeResult, and the core no longer creates git worktrees. Worktree isolation moves to @gotgenes/pi-subagents-worktrees.
+* the Agent tool no longer accepts isolation: "worktree", and SubagentsService.SpawnOptions no longer has an isolation field. Install @gotgenes/pi-subagents-worktrees and list the agent in worktreeAgents instead.
+
+### Features
+
+* drop the isolation spawn axis from the subagents API ([2ff8970](https://github.com/gotgenes/pi-packages/commit/2ff897059feec67a49af7e3f54e0e4828faa2521))
+* remove git worktree isolation from the subagents core ([2e81044](https://github.com/gotgenes/pi-packages/commit/2e81044221562c528d1fb296f356f60d81af0661))
+
+## [11.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.5.0...pi-subagents-v11.6.0) (2026-05-29)
+
+
+### Features
+
+* **pi-subagents:** publish bundled type declarations and fix stale exports path ([8eda6f6](https://github.com/gotgenes/pi-packages/commit/8eda6f6611a12c60d99a5069f352abd634997e67))
+
 ## [11.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.4.0...pi-subagents-v11.5.0) (2026-05-29)
 
 

package/dist/public.d.ts

@@ -0,0 +1,170 @@
+import { ThinkingLevel } from '@earendil-works/pi-ai';
+
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
+
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+type SubagentType = string;
+interface AgentInvocation {
+    /** Short display name, e.g. "haiku" — only set when different from parent. */
+    modelName?: string;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    runInBackground?: boolean;
+}
+
+/**
+ * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Behavior (abort, steer buffering) lives on the agent rather than on
+ * AgentManager — each agent manages its own lifecycle concerns.
+ *
+ * The child's working directory is supplied by a registered WorkspaceProvider
+ * (the workspace seam); with no provider the child runs in the parent cwd.
+ *
+ * Phase-specific collaborators (execution, notification) are attached
+ * after construction as lifecycle information becomes available.
+ */
+
+type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+/**
+ * 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.
+ */
+
+/** Context the core hands a provider when a child run starts. */
+interface WorkspacePrepareContext {
+    agentId: string;
+    agentType: SubagentType;
+    baseCwd: string;
+    invocation?: AgentInvocation;
+}
+/** Outcome the core reports to a workspace when the run ends. */
+interface WorkspaceDisposeOutcome {
+    status: AgentStatus;
+    description: string;
+}
+/** What dispose may hand back for the core to fold into the child result. */
+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. */
+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. */
+interface WorkspaceProvider {
+    prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+/** Serializable snapshot of an agent's state — no live session objects. */
+interface SubagentRecord {
+    id: string;
+    type: string;
+    description: string;
+    status: SubagentStatus;
+    result?: string;
+    error?: string;
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    lifetimeUsage: LifetimeUsage;
+    compactionCount: number;
+}
+/** Options for spawning an agent via the service. */
+interface SpawnOptions {
+    description?: string;
+    model?: string;
+    maxTurns?: number;
+    thinkingLevel?: string;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    foreground?: boolean;
+    bypassQueue?: boolean;
+}
+/** The public service contract for cross-extension subagent access. */
+interface SubagentsService {
+    /** Spawn an agent. Returns the agent ID immediately. */
+    spawn(type: string, prompt: string, options?: SpawnOptions): string;
+    /** Get a snapshot of an agent's current state. */
+    getRecord(id: string): SubagentRecord | undefined;
+    /** List all tracked agents, most recent first. */
+    listAgents(): SubagentRecord[];
+    /** Abort a running or queued agent. Returns false if not found. */
+    abort(id: string): boolean;
+    /** Send a steering message to a running agent. */
+    steer(id: string, message: string): Promise<boolean>;
+    /** Wait for all running and queued agents to complete. */
+    waitForAll(): Promise<void>;
+    /** Whether any agents are running or queued. */
+    hasRunning(): boolean;
+    /**
+     * Register the single workspace provider that supplies a child's working
+     * directory plus bracketed setup/teardown. Throws if one is already
+     * registered. Returns a disposer that unregisters the provider.
+     */
+    registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+/** Event channel constants for pi.events subscriptions. */
+declare const SUBAGENT_EVENTS: {
+    readonly STARTED: "subagents:started";
+    readonly COMPLETED: "subagents:completed";
+    readonly ACTIVITY: "subagents:activity";
+};
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+declare function publishSubagentsService(service: SubagentsService): void;
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+declare function getSubagentsService(): SubagentsService | undefined;
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+declare function unpublishSubagentsService(): void;
+
+export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
+export type { LifetimeUsage, SpawnOptions, SubagentRecord, SubagentStatus, SubagentsService, WorkspaceProvider };

package/docs/architecture/architecture.md

@@ -56,9 +56,9 @@ flowchart TB
         AgentManager["AgentManager<br/>(spawn, abort, collection)"]
         ConcurrencyQueue["ConcurrencyQueue<br/>(scheduling, drain)"]
         AgentRunner["agent-runner<br/>(session, turns, results)"]
-        Agent["Agent<br/>(status, behavior: abort/steer/worktree/run lifecycle)"]
+        Agent["Agent<br/>(status, behavior: abort/steer/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
-        Worktree["worktree<br/>(git isolation)"]
+        Workspace["workspace<br/>(provider seam: child cwd + teardown)"]
     end
 
     subgraph observation["Observation domain"]
@@ -112,7 +112,6 @@ classDiagram
         +toolUses: number
         +lifetimeUsage: LifetimeUsage
         +execution?: ExecutionState
-        +worktree?: WorktreeIsolation
         +notification?: NotificationState
         +markRunning()
         +markCompleted()
@@ -270,14 +269,12 @@ src/
 ├── lifecycle/                      agent execution and state tracking
 │   ├── agent-manager.ts            collection manager + observer wiring
 │   ├── agent-runner.ts             session creation, turn loop, tool filtering
-│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, worktree)
+│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, workspace)
 │   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
 │   ├── workspace.ts                workspace provider seam (generative extension surface)
-│   ├── worktree.ts                 git worktree isolation
-│   ├── worktree-isolation.ts       worktree lifecycle collaborator
 │   └── usage.ts                    token usage tracking
 │
 ├── observation/                    progress tracking and notification
@@ -357,14 +354,14 @@ They declare this package as an optional peer dependency and use dynamic import
   Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
   This replaced the former outbound `permission-bridge` (#261, ADR 0002) — the core no longer looks up a named consumer.
 - `workspace` — the single generative seam (#262, ADR 0002): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
-  With no provider, children run in the parent cwd (default unchanged); the git worktree strategy moves behind this seam in #263.
+  With no provider, children run in the parent cwd (default unchanged); the git worktree strategy lives behind this seam in `@gotgenes/pi-subagents-worktrees` (#263, the seam's first consumer).
 - `session-config` — pure configuration assembler (extracted from `agent-runner`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation — moving to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (ADR 0002).
+- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, ADR 0002); `git` no longer appears in the core.
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
@@ -418,7 +415,7 @@ Key types:
 
 - `SubagentsService` — `spawn`, `getRecord`, `listAgents`, `abort`, `steer`, `waitForAll`, `hasRunning`.
 - `SubagentRecord` — serializable agent snapshot (no live session objects).
-- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `isolated`, `inheritContext`, `foreground`, `bypassQueue`, `isolation`.
+- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `isolated`, `inheritContext`, `foreground`, `bypassQueue`.
 - `SUBAGENT_EVENTS` — channel constants for `pi.events` subscriptions.
 
 ### Accessor pattern
@@ -501,7 +498,7 @@ Latent extensibility is the deliverable; a vacant hook is not.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
   Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
-  These move to `@gotgenes/pi-subagents-worktrees`, the first consumer of the workspace provider seam.
+  Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
 - **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
   Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
 
@@ -608,7 +605,6 @@ interface SpawnExecution {
   inheritContext: boolean;
   runInBackground: boolean;
   isolated: boolean;
-  isolation: IsolationMode | undefined;
   agentInvocation: AgentInvocation;
 }
 
@@ -765,8 +761,8 @@ Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disp
 #### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
 
 Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
-Only `WorkspaceProvider` is named-re-exported from `service.ts`; `Workspace` and the context types resolve via inference when a consumer assigns to `WorkspaceProvider` (the worktrees package adds named re-exports in #263 when it imports them by name).
-At run-start `Agent.run()` consults the registered provider (provider-first precedence) for the child's cwd and a disposal handle; with no provider it falls back to the legacy worktree collaborator, and with neither the child runs in the parent's cwd.
+Only `WorkspaceProvider` is named-re-exported from `service.ts`; `Workspace` and the context types resolve via inference when a consumer assigns to `WorkspaceProvider` (named re-exports of the collaborator types are tracked 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 (the legacy worktree-collaborator fallback was removed when worktrees left the core in #263).
 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: the existing `isolation: "worktree"` path is untouched (its eviction is Step 3).
@@ -774,13 +770,15 @@ On completion the core calls `Workspace.dispose({ status, description })` and ap
   Within #262 the seam is exercised only by test fakes; do not cut a release containing the seam without `@gotgenes/pi-subagents-worktrees`.
 - 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]
+#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263] ✅ Delivered
 
 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.
-Remove `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; drop `isolation` from the spawn API and `SubagentsService`.
+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`; peer-depends on `@gotgenes/pi-subagents`.
+  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`), since `exports.types` resolves to the shipped declaration bundle.
+  Only `WorkspaceProvider` is importable by name from 11.6.0; the collaborator types are recovered via inference until #272 adds named re-exports.
 - Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
 
 #### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]

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

@@ -0,0 +1,69 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0003 — Publish a bundled `.d.ts` for the public surface
+
+## Status
+
+Accepted.
+Introduces the repository's first build step, scoped to type declarations only.
+
+## Context
+
+`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
+Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
+
+A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
+
+1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   A latent bug, unnoticed because nothing in-repo imported the package by name.
+2. Once corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
+   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
+   The fallback to the publisher's `package.json` `imports` field also fails: `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 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.
+
+## Decision
+
+Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
+  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
+- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
+- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
+
+This is the repository's first build step.
+It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+
+## Alternatives considered
+
+- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
+  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
+  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
+  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
+- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
+  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+
+## Consequences
+
+- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
+- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
+- 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.

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

@@ -42,3 +42,46 @@ All deterministic gates green: `check`, `lint`, `test`, and `fallow dead-code` (
 - 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.