@selesai/code 0.8.2 → 0.8.4

package/dist/extensions/pi-subagents/docs/extension-api.md

@@ -0,0 +1,308 @@
+# Extension and integration APIs
+
+Public seams for other Selesai extensions and host integrations: the in-process RPC, the structured delegation API, launch preflight, capability ceilings, the background-work provider contract, and the Herdr integration.
+
+## In-process event-bus RPC
+
+Other Selesai extensions can use the in-process event-bus RPC instead of scraping slash output or calling internal modules. Listen for `subagents:rpc:v1:ready`, send requests on `subagents:rpc:v1:request`, and read replies from `subagents:rpc:v1:reply:<requestId>`.
+
+```typescript
+const requestId = crypto.randomUUID();
+pi.events.on(`subagents:rpc:v1:reply:${requestId}`, (reply) => {
+  // { version: 1, requestId, success: true, data } or
+  // { version: 1, requestId, success: false, error: { code, message } }
+});
+pi.events.emit("subagents:rpc:v1:request", {
+  version: 1,
+  requestId,
+  method: "spawn",
+  params: {
+    workflowScript: `return runs.run("main", { agent: "reviewer", task: "Review the current diff" })`,
+    context: "fresh"
+  }
+});
+```
+
+The RPC methods are `ping`, `status`, `spawn`, `steer`, `interrupt`, `stop`, and `resume`. `status`, `steer`, `interrupt`, and `resume` reuse the normal package-owned actions.
+
+Method notes:
+
+- `spawn` requires `workflowScript` and is async-only: omit `async` or set `async: true`, omit `clarify`, and do not pass management `action` values. It goes through the same executor as the `subagent` tool, so agent discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status all behave the same.
+- `steer` requires an async run `id` (plus optional child `index`) and a non-empty `message`; its reply preserves the normal acknowledged-delivery result. Optional `mode` values are `steer` (default), `follow_up`, and `auto`, and receipts include `deliveryStatus: "delivered" | "queued"`. RPC steering disables the direct tool's pause-and-revive recovery in every mode so an extension keeps authority over the exact child it spawned; `ping.capabilities.nonRecoveringSteer` advertises this guarantee.
+- `resume` requires a run target and non-empty `message`. It delegates to the existing revival path, which validates current-session ownership, persisted session/recovery metadata, stopped/live state, capability ceilings, and the exclusive session lease before returning the new async run details. Callers may request a `file-only` output path for the revived result without overriding its model, tools, or budgets. `ping.capabilities.resume` advertises this seam.
+- `stop` targets current-session top-level async runs through the stop control channel and records a `stopped` lifecycle instead of reporting a timeout.
+
+Capability advertisements on `ping`:
+
+- `events.asyncComplete` — exact process-local completion correlation after RPC `spawn`.
+- `launchResolvedExtensions` — the optional launch-resolved extension projection in status details.
+- `runtimeAcknowledgedExtensions` — the optional child-runtime acknowledgement projection and event name.
+- `processTerminalProof` — the process-terminal proof status (see [observability.md](observability.md#process-terminal-proof)).
+- `nonRecoveringSteer` — RPC steering never pauses-and-revives.
+- `resume` — the revival seam described above.
+- `fleetStatus: { version: 1 }` — successful `status` replies additionally include `data.fleet`.
+
+Structured delegation progress updates carry `runId` as soon as foreground execution allocates it, so a caller can retain the package-owned revival target even if its own tool turn is interrupted before the terminal response. Foreground `details.results[]` rows also include a numeric `index` that is unique within the run and stable across partial progress snapshots and the final result; use `(runId, index)` instead of row position to correlate single, counted parallel, and chain children.
+
+### Fleet status DTO
+
+When `ping.capabilities.fleetStatus` is `{ version: 1 }`, successful `status` replies include `data.fleet`: `{ version: 1, entries, totalActive, omitted }`.
+
+Entries are bounded, current-session public display records with an opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, safe `startedAt`, and `{ input, output, total }` tokens. `totalActive` and `omitted` preserve overflow information beyond the bounded entry window.
+
+The DTO intentionally never exposes run, async, or tool IDs. Clients must ignore unknown fields and fall back to status text when the capability is absent.
+
+### Scope
+
+`pi.events` is in-process only. It does not reach separate Selesai processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
+
+## Launch contract preflight
+
+Use `pi-subagents/preflight` when an extension needs to inspect the resolved child launch contract before deciding whether to run anything:
+
+```ts
+import { resolveSubagentLaunchContract } from "pi-subagents/preflight";
+
+const result = await resolveSubagentLaunchContract({
+  agent: "reviewer",
+  task: "Review the current diff.",
+  context: "fresh",
+  cwd: ctx.cwd,
+  sessionRoot: "/tmp/my-extension-preflight-session-root",
+  availableModels: ctx.modelRegistry.getAvailable(),
+});
+
+if (!result.ok) {
+  // missing_agent, ambiguous_agent, missing_skill, denied_required_tool,
+  // invalid_artifact_dir, invalid_cwd, or unsupported_mode
+  throw new Error(result.message);
+}
+
+console.log(result.contract.digest, result.contract.tools.effectiveAllowlist);
+```
+
+Preflight covers ordinary single-agent launch resolution:
+
+- Selected agent identity and shadowed candidates.
+- A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields.
+- Fresh/fork context, effective model and thinking, skill and tool resolution, direct MCP selections, runtime/configured extensions.
+- Artifact/session paths, async lifecycle/status/result/event/process-terminal paths, package/lifecycle versions, capability-ceiling audit data, and stable digests.
+
+`launchContractDigest` is the canonical digest of the caller task, effective system prompt (including the resolved `turnBudget` prompt augmentation when supplied), model candidates, effective tools/extensions/MCP (including inherited capability ceilings), output binding, and structured-output schema that ordinary foreground and async execution report in results/status/events and metadata.
+
+Boundaries:
+
+- Runtime acceptance prose and output-task annotations are intentionally excluded because side-effect-free preflight does not resolve those host/runtime augmentations; the launch and task digests make that boundary explicit.
+- Raw prompts are not exposed in public contract output.
+- It is side-effect-free for launch state: it does not create child sessions, temp prompt files, structured-output runtimes, tool-diagnostic files, or run artifacts.
+- Some host-owned facts, such as exact fork snapshots, nested async roots, and live model registries, can only be proven by the Selesai host; those appear as `host_required` diagnostics instead of silently pretending to be exact.
+
+## Structured delegation API
+
+Other Selesai extensions can ask `pi-subagents` to run one configured foreground leaf agent through the structured delegation API. It uses the established `prompt-template:subagent:*` event family and the same executor as the `subagent` tool; it does not add another launcher.
+
+```ts
+import {
+  SUBAGENT_DELEGATION_REQUEST_EVENT,
+  SUBAGENT_DELEGATION_RESPONSE_EVENT,
+  type SubagentDelegationRequest,
+  type SubagentDelegationResponse,
+} from "pi-subagents/delegation";
+
+const request: SubagentDelegationRequest = {
+  requestId: crypto.randomUUID(),
+  ownerRunId: workflowRunId,
+  nodeId: "review-accuracy",
+  agent: "reviewer",
+  task: "Review the supplied evidence.",
+  context: "fresh",
+  cwd: ctx.cwd,
+  thinking: "high",
+  result: {
+    kind: "structured",
+    schema: {
+      type: "object",
+      properties: { verdict: { type: "string" } },
+      required: ["verdict"],
+      additionalProperties: false,
+    },
+  },
+};
+
+const unsubscribe = pi.events.on(SUBAGENT_DELEGATION_RESPONSE_EVENT, (payload) => {
+  const response = payload as SubagentDelegationResponse;
+  if (response.requestId !== request.requestId) return;
+  if (response.ownerRunId !== request.ownerRunId || response.nodeId !== request.nodeId) return;
+  unsubscribe();
+  // Inspect response.status, response.result, response.usage, model, and thinking.
+});
+pi.events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
+```
+
+Identity:
+
+- `ownerRunId` plus `nodeId` is the active logical identity; `requestId` identifies one attempt.
+- A second active attempt for the same logical node receives `duplicate_node` without disturbing the original.
+- Started, update, response, and cancellation payloads carry the full tuple. Cancellation affects only an exact tuple, including cancel-before-start races.
+- Each attempt emits at most one terminal response.
+
+Results:
+
+- Result mode is explicit. Text remains literal even when it looks like JSON. Structured mode returns the separately captured, schema-validated JSON value.
+- Terminal usage reports input, output, cache-read, cache-write, cost, turns, tool calls, and duration alongside the effective model and thinking level when known.
+
+Bounds:
+
+- Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.
+- Structured delegation accepts `toolBudget: { hard: 0, block: "*" }` to block the first tool call and run a zero-tool leaf; ordinary model-facing/configured budgets keep their existing minimum of one.
+- The foreground bridge retains up to 8,192 exact pending-cancellation and settled-attempt identities per extension context. If either history fills, it fails closed with `unavailable_context` for later starts rather than evicting identity facts; lifecycle reset clears the bounded history.
+
+Constraints:
+
+- Delegation requires an active extension context. Emit requests from a supported event callback or queued application step, not by recursively invoking the `subagent` tool inside another tool's `tool_call` hook.
+- The caller selects a configured agent, but agent discovery and effective tools remain package-owned. A request cannot grant arbitrary tools, and tool restrictions are not an operating-system sandbox.
+- The detached RPC remains async-only; this API is foreground-only.
+
+Unversioned prompt-template payloads with `requestId`, `agent`, `task`, `context`, `model`, and `cwd` are rejected as legacy direct delegation. New integrations must use the structured owned-leaf request above. `pi-subagents/delegation` is the canonical contract for extension integrations.
+
+## Capability ceilings
+
+Parent extensions can enforce an out-of-band, session-scoped capability ceiling without adding a model-visible field to `subagent`:
+
+```ts
+import { registerSubagentCapabilityCeiling } from "pi-subagents/capability-ceiling";
+
+const restriction = registerSubagentCapabilityCeiling({
+  sessionId: ctx.sessionManager.getSessionId(),
+  source: "plan-mode",
+  ceiling: {
+    allowedAgents: ["plan-scout", "plan-researcher", "plan-reviewer"],
+    allowedTools: ["read", "grep", "find", "ls"],
+    denyExtensions: true,
+  },
+});
+// restriction.update(...) replaces this provider's policy atomically.
+// restriction.dispose() removes only this provider's registration.
+```
+
+Semantics:
+
+- Active registrations intersect their `allowedTools` and `allowedAgents` sets and OR `denyExtensions`.
+- An explicit empty list means no caller-facing tools or launchable agents for that field; an omitted list does not restrict names.
+- `allowedAgents` entries are canonical agent names and are case-sensitive.
+- Launching a non-allowlisted agent fails before spawn, and `{ action: "list" }` keeps restricted agents visible in a separate non-executable section instead of silently hiding them.
+- The resolved snapshot is propagated monotonically to nested and async children and is retained for recovery.
+- `structured_output` may remain as a package-owned internal protocol tool when an output schema requires it; it is not a caller capability.
+- A denied lazy-skill `read` requirement fails before spawn rather than widening the ceiling.
+
+`denyExtensions` suppresses ambient, configured, and MCP provider extensions while retaining the package runtime needed for child protocol enforcement. This is a same-process policy boundary, not a sandbox against malicious code already running in the parent process.
+
+Schedules created while a ceiling is active are rejected until durable schedule persistence is available; unrestricted schedules remain subject to any policy active when they fire. Public status exposes bounded audit counts and sources, never full extension paths.
+
+## Background-work provider API
+
+Other Selesai extensions can make their current-session jobs visible to `subagent_wait` through the process-local provider contract:
+
+```ts
+import { registerBackgroundWorkProvider } from "pi-subagents/background-work";
+
+const dispose = registerBackgroundWorkProvider({
+  name: "my-background-extension",
+  wakeChannels: ["my-extension:job-finished"],
+  listActiveWork: () => jobs
+    .filter((job) => job.status === "running")
+    .map((job) => ({ id: job.id, sessionId: job.ownerSessionId })),
+  reconcile: ({ sessionId, nowMs }) => reconcileJobs(sessionId, nowMs),
+});
+```
+
+Semantics:
+
+- Each item needs a stable provider-local ID and the exact Selesai session ID that owns it. `subagent_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
+- It filters snapshots to the active session, fails closed if a provider disappears while its work is tracked, and surfaces malformed snapshots or provider errors with provider context.
+- Wake channels only shorten polling; validated snapshots remain authoritative.
+- Providers share a registry through `Symbol.for("pi-subagents.background-work.v1")`, allowing independently loaded extension modules to meet in one Selesai process.
+- Registration is reload-safe: a new provider with the same name replaces the old callback, and the old disposer cannot remove the replacement. Call the disposer during extension shutdown when possible.
+
+Child processes do not gain provider tools or extensions automatically. Add `subagent_wait` to the child agent's `tools` allowlist and load each provider through `extensions` or `subagentOnlyExtensions`. The parent's effective `waitTool` setting is serialized through foreground, async, resume, chain, parallel, and fanout launch paths; `SELESAI_SUBAGENT_WAIT_TOOL_ENABLED` keeps precedence.
+
+## Herdr integration
+
+When Selesai runs inside [Herdr](https://herdr.dev), pi-subagents automatically reports active async-run counts through Herdr pane metadata.
+
+- The bridge is enabled only when Herdr supplies `HERDR_ENV=1` and `HERDR_PANE_ID`; outside Herdr it registers no listeners or timers.
+- It restores current-session active runs after `/reload` or `/resume`, refreshes metadata while work is active, and clears it on completion or shutdown.
+- The bridge uses Herdr's existing `herdr:blocked` sibling event when an async child needs attention, and emits `herdr:busy` while async work remains. Herdr versions that support the sibling event keep the pane's semantic state `working`; older versions ignore it safely and still display the metadata label while the Selesai integration remains the lifecycle authority.
+
+To show the reported label in the expanded Agent sidebar, include `state_text` or `$summary` in its row layout:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "workspace", "tab"],
+  ["agent", "state_text"],
+]
+```
+
+### Inspector panes
+
+Herdr 0.7.5+ can open an on-demand inspector for an existing async run:
+
+```ts
+subagent({ action: "inspector.open", id: "<run-id>", index: 0, focus: true })
+subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
+subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
+```
+
+The inspector is a raw dashboard pane, not the child process and not a literal attach. It reads lifecycle/status/output/mission artifacts and sends `steer` or `stop` through pi-subagents' existing control inbox. Closing it never stops the run.
+
+Herdr remains optional. Ordinary launches stay headless, and missing/older Herdr versions affect only Herdr-specific inspector and project-pane actions. FleetView opens the selected active async child with `H`. Use `focus` only with `inspector.open`; Herdr 0.7.5 cannot focus an arbitrary existing raw pane id.
+
+### Project panes
+
+For substantial work in another codebase, Herdr 0.7.5+ can open a project-owned Selesai pane rooted in that repository:
+
+```ts
+subagent({ action: "project.open", cwd: "/path/to/repo", message: "Own the auth refresh mission for this project." })
+subagent({ action: "project.status", cwd: "/path/to/repo" })
+subagent({ action: "project.close", cwd: "/path/to/repo" })
+```
+
+A project pane runs its own Selesai session in the target directory, so subagents launched from that pane use that project's config, agents, skills, files, git state, and missions. The parent session keeps coordination authority; existing headless runs are not moved into the pane. Pane bindings live under `<projectRoot>/.pi-subagents/project-panes/herdr.json` and are only a local pointer to the Herdr pane.
+
+Other Selesai extensions should use the versioned public TypeScript surface instead of invoking the model-facing tool or importing inspector internals:
+
+```ts
+import {
+  PROJECT_PANES_API_VERSION,
+  openProjectPane,
+  getProjectPaneStatus,
+  closeProjectPane,
+} from "pi-subagents/project-panes";
+
+const opened = await openProjectPane({ cwd: "/path/to/repo", focus: false });
+const status = await getProjectPaneStatus({ cwd: "/path/to/repo" });
+const closed = await closeProjectPane({ cwd: "/path/to/repo", requireIdle: true });
+```
+
+The API returns discriminated structured results with canonical project root, binding path, pane identity, bounded Herdr runtime fields, and stable error codes. `requireIdle: true` fails closed unless Herdr explicitly reports `agent_status: "idle"`; use it when an owning extension must not close a working or blocked pane. The API deliberately reports `trust: "human-verification-required"`: it never bypasses or claims to attest Selesai's project-trust prompt. `PROJECT_PANES_API_VERSION` is currently `1`.
+
+## Runtime files
+
+The main runtime files in this repository:
+
+| File | Purpose |
+|------|---------|
+| `src/extension/index.ts` | Extension registration, tool registration, message/render wiring. |
+| `src/agents/agents.ts` | Agent and chain discovery, frontmatter parsing. |
+| `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, chain, management, status, interrupt, and doctor actions. |
+| `src/runs/foreground/execution.ts` | Core foreground `runSync` handling. |
+| `src/runs/background/subagent-runner.ts` | Detached async runner. |
+| `src/runs/background/async-execution.ts` | Background launch support. |
+| `src/runs/background/async-status.ts` | Status discovery and formatting for async runs. |
+| `src/runs/foreground/chain-execution.ts` / `src/agents/chain-serializer.ts` | Chain orchestration and `.chain.md` parsing. |
+| `src/shared/settings.ts` | Chain behavior, instructions, and config helpers. |
+| `src/runs/shared/worktree.ts` | Git worktree isolation. |
+| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
+| `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
+| `test/unit/` / `test/integration/` / `test/e2e/` | Unit, loader-based integration, and real-session E2E tests. |

package/dist/extensions/pi-subagents/docs/missions.md

@@ -0,0 +1,119 @@
+# Missions and schedules
+
+Durable records for delegated work: missions wrap runs so you can recover them later, and schedules launch work on a timer.
+
+## Missions
+
+Missions are durable wrappers around runs. The noun map:
+
+- **Project/codebase** — where work happens.
+- **Mission** — why delegated work exists and how to recover it later.
+- **Run** — one actual subagent execution.
+- **Receipt** — proof or a link for an external outcome, such as a PR, CI check, deployment, or release.
+
+Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under `<cwd>/.pi-subagents/missions/` linking objectives, run ids, lifecycle status, decisions, artifact paths, and delivery receipts. Workflow children do not create separate missions. Each workflow child attempt is stored in the enclosing mission with its stable workflow key, run id when known, agent, task metadata, timestamps, session and artifact paths, and latest status heartbeat.
+
+Behavior:
+
+- Automatic persistence failures do not block the run and are reported as `details.missionWarning`. Explicit `missionId` and `mission` requests remain strict before launch.
+- Human receipts end with `Mission: <id> (<status>)`, while JSON/structured output text stays unchanged and `details.missionId` is authoritative.
+- Pass `mission: false` for an intentionally ephemeral workflow. It creates no mission for the workflow or its children and has no `state` global.
+- Set `missions.enabled: false` to disable automatic mission creation; explicit mission fields and actions still work.
+- A workflow with a mission can use `await state.get(key)` and `await state.set(key, value)` for durable JSON state. Missing keys return `undefined`. Keys use the same format as `runs.run` keys. Each set takes the state-file lock, reads the latest file, merges the key, and atomically writes `<cwd>/.pi-subagents/missions/<mission-id>/state.json`. The complete file cannot exceed 256 KiB. Each workflow caches the file on its first `get`. A `mission:false` workflow has no `state` global.
+
+An explicit `mission` object must have exactly one non-empty `title` or `summary`. `objective` and `labels` are optional. When supplied, `goal` must be `true` and requires `budget: { tokens: <positive integer> }`.
+
+```ts
+const created = subagent({
+  action: "mission.create",
+  mission: { title: "Ship auth refresh", objective: "Implement and validate token refresh" }
+})
+subagent({
+  workflowScript: `return runs.run("main", { agent: "worker", task: "Implement the approved auth refresh plan" })`,
+  missionId: "<mission-id>"
+})
+
+// Or create and attach in one launch
+subagent({
+  workflowScript: `return runs.run("main", { agent: "worker", task: "Implement the approved plan" })`,
+  mission: { title: "Ship auth refresh" }
+})
+```
+
+### Goal missions
+
+Set `goal: true` with a token budget to make an open mission an active continuation driver:
+
+```ts
+subagent({
+  action: "mission.create",
+  mission: {
+    title: "Ship auth refresh",
+    objective: "Implement and validate token refresh",
+    goal: true,
+    budget: { tokens: 400000 }
+  }
+})
+```
+
+After each parent turn, an idle goal mission sends one needs-attention notice with its title, remaining token budget, and next ready action. The action comes from `state.nextReadyAction`, `state.nextAction`, a state item with `status: "ready"`, an open decision, or linked-run state. A workflow can write `state.nextReadyAction` to tell the next notice exactly what work is ready. When the latest linked workflow has a completed retained child, the notice names that child as the `resume` target. The extension never launches or replans goal work by itself.
+
+Linked-run token totals are stored on each run and folded into mission `usage`. An active linked run suppresses notices. Reaching the token budget changes the goal status to `budget-exhausted` and stops notices without closing the mission or reporting success.
+
+Pause and resume notices with `mission.update` and `{ goal: { paused: true } }` or `{ goal: { paused: false } }`. Set `{ goal: false }` to disable goal mode. `mission.close` also ends the loop.
+
+### Managing missions
+
+Use `mission.list`, `mission.show`, `mission.update`, `mission.resolve-decision`, `mission.attach-run`, and `mission.close`.
+
+- Use `mission.update` to record decisions, artifacts, labels, summaries, and delivery receipts while work runs. Adding a decision gates active or completed missions as `needs_decision`; planned and waiting missions keep their lifecycle status while the decision stays visible. Resolve it with `mission.resolve-decision`, `missionId`, the decision `id`, and a resolution in `summary`. A gated mission returns to `active` after its last open decision is resolved.
+- `mission.show` includes each workflow child's latest status, phase, update time, session path metadata, and heartbeat. The ledger is a recovery record only. It does not schedule or restart children.
+- Receipts are durable links for pull requests, CI, deployments, or releases, each with `kind`, `status`, `title`, `url`, and optional `description`. They record delivery state only; pi-subagents does not merge, poll CI, or deploy.
+- Use `mission.close` with a terminal status and summary when a mission is done.
+- After compaction or restart, resume from `mission.list`/`mission.show` first: `mission.show` refreshes linked async status where available, then use the linked run ids with normal `status`, `steer`, `resume`, or `stop` actions.
+- `mission.list` with `missionScope: "global"` reads the user-local pointer index under the Selesai agent directory. Project records remain the source of truth, and missing records are reported as stale rather than hiding other projects.
+
+### Cross-project work
+
+Keep same-project tasks on ordinary subagents. Use an explicit `cwd` for small bounded work in another project.
+
+For substantial or long-running work in another project, open a project-owned Herdr pane with `project.open` and give that project Selesai session a narrow mission/result contract (see [extension-api.md](extension-api.md#herdr-integration)). The project pane owns its own subagents; do not model it as ordinary child nesting or expect existing headless runs to move into the pane.
+
+Mission storage configuration (`missions.directory`, `retainTerminal`, `globalIndex`) is in [configuration.md](configuration.md#missions).
+
+## Schedules
+
+Durable schedules are enabled by default and stored per project under `.pi-subagents/schedules/<id>/`.
+
+Create a one-shot schedule:
+
+```ts
+subagent({
+  action: "schedule.create",
+  id: "evening-review",
+  name: "Evening review",
+  at: "+30m",
+  workflowScript: `return runs.run("main", { agent: "reviewer", task: "Review the current diff." })`
+})
+```
+
+Create a fixed recurring workflow:
+
+```ts
+subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "..." })
+```
+
+Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift.
+
+Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, `schedule.run-due`, and `schedule.delete`.
+
+Behavior:
+
+- Runs always launch async with fresh context and disable automatic mission creation; mission attachment is deferred from this first slice.
+- Definitions, bounded history, append-only events, and per-run receipts are stored with mode `0600`.
+- `overlap` is currently fixed to `skip`; `catchUp` supports `latest` (default) and `none`.
+- `schedule.run-due` lets an external launcher start due project work without making `pi-subagents` a daemon.
+- Calendar recurrence, cron, queue/replace overlap, and the schedule TUI inspector are intentionally deferred to the next slice.
+- The old `schedule`, `schedule-list`, `schedule-status`, and `schedule-cancel` actions were removed in a hard cutover.
+
+Disable or bound schedules with the `scheduledRuns` config key in [configuration.md](configuration.md#scheduledruns).

package/dist/extensions/pi-subagents/docs/models.md

@@ -0,0 +1,192 @@
+# Models
+
+How subagents pick models, and how to change that.
+
+Builtin agents inherit your current Selesai default model. This keeps new installs from depending on a provider you may not have configured. From there you can layer defaults and overrides:
+
+- `subagents.defaultModel` — a default for every subagent that does not set its own model.
+- `subagents.agentOverrides.<name>.model` — pin one role.
+- Per-run overrides — for one launch only.
+
+Precedence, strongest first: per-run override → agent frontmatter `model` → `agentOverrides.<name>.model` → `subagents.defaultModel` → the parent session model.
+
+## Setting defaults and overrides
+
+In `~/.selesai/agent/settings.json` (user) or the project config settings file (`.selesai/settings.json` in standard Selesai; project wins):
+
+```json
+{
+  "defaultModel": "deepseek-v4-pro",
+  "subagents": {
+    "defaultModel": "deepseek-v4-flash",
+    "agentOverrides": {
+      "oracle": {
+        "model": "deepseek-v4-pro"
+      }
+    }
+  }
+}
+```
+
+For one run, put the override in the command:
+
+```text
+/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
+```
+
+For a persistent role override with a backup model for provider failures:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "model": "anthropic/claude-sonnet-4",
+        "thinking": "high",
+        "fallbackModels": ["openai/gpt-5-mini"]
+      }
+    }
+  }
+}
+```
+
+`subagents.defaultModel` applies to builtin, package, user, and project agents that do not set `model` in frontmatter. Per-run model overrides and `agentOverrides.<name>.model` still win, and explicit agent frontmatter still wins over the global default. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable a builtin (see [agents.md](agents.md)). Matching user and project agents also receive override fields that their frontmatter leaves unset, so a shared project config agent can keep the persona while local settings choose the model.
+
+## Recommended model tiering (optional)
+
+A setup that works well in practice: route agents by task shape instead of running everything on one model. Four tiers:
+
+1. **Fast workhorse** — the cheapest capable model at low thinking, for recon, lookups, and mechanical edits. Example: `openai-codex/gpt-5.6-luna:low` on `scout`.
+2. **Standard well-scoped** — a mid-tier model at medium thinking, for most delegations: routine multi-file edits, focused reviews, straightforward implementation. Example: `openai-codex/gpt-5.6-terra:medium` on `worker`, `reviewer`, and a lightweight `delegate` agent.
+3. **Deep but bounded** — a top reasoning model at high thinking, only for hard tasks that arrive with explicit goals and completion criteria. These models tend to loop on vague goals, so keep them off open-ended work. Example: `openai-codex/gpt-5.6-sol:high` on oracle-style agents.
+4. **Taste and intent** — a model that reads human intent well and makes judgment calls without looping, for ambiguous work: UX and design decisions, product tradeoffs, planning from vague requirements, writing quality. Example: `anthropic/claude-fable-5` at `low` for lighter passes and `medium` for harder ones.
+
+The routing rule: use the capability tiers (1–3) when the task is well-scoped, and the intent tier (4) when scoping or judging is the task itself.
+
+Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully instead of failing the run. Fallback triggers on rate-limit and overload errors automatically:
+
+```yaml
+---
+name: shaper
+description: Open-ended design/UX/product/planning agent for ambiguous tasks
+model: anthropic/claude-fable-5
+thinking: medium
+fallbackModels: openai-codex/gpt-5.5:high
+---
+```
+
+One interaction worth knowing for tier 4: forked context over an Anthropic parent transcript with signed thinking blocks forces the child's thinking off, so intent-tier agents work best with fresh context.
+
+## Thinking level defaults
+
+Set `subagents.defaultThinking` to give builtin, package, user, and project agents without a `thinking` value a shared thinking level, independent of the parent session's default. Project settings win over user settings. Explicit frontmatter, `agentOverrides.<name>.thinking`, and per-run thinking overrides still win. `thinking: false` remains an explicit opt-out:
+
+```json
+{
+  "subagents": {
+    "defaultThinking": "medium",
+    "agentOverrides": {
+      "reviewer": { "thinking": "high" }
+    }
+  }
+}
+```
+
+If your provider rejects model IDs with thinking suffixes, set `subagents.disableThinking: true` in user or project settings. That clears bundled builtin thinking defaults in one place. An explicit higher-precedence `agentOverrides.<name>.thinking` value can opt a role back in. Existing custom-agent frontmatter remains authoritative.
+
+## Extension defaults
+
+Set `subagents.defaultExtensions` to give builtin, package, user, and project agents without an `extensions` field a shared extension allowlist:
+
+- Absent: preserves Selesai's normal ambient extension discovery.
+- Empty array: sets `extensions: []` for agents that do not explicitly define it, disabling ambient extension loading.
+- Non-empty array: supplies that allowlist to agents that do not explicitly define one.
+
+Project settings win over user settings. Use `agentOverrides.<name>.extensions` for per-agent settings; explicit custom-agent frontmatter remains authoritative.
+
+```json
+{
+  "subagents": {
+    "defaultExtensions": [],
+    "agentOverrides": {
+      "researcher": {
+        "extensions": ["./tools/research.ts"]
+      }
+    }
+  }
+}
+```
+
+A non-array value, an array containing a non-string entry, or an empty/whitespace-only string raises a settings error naming `defaultExtensions` and the offending settings file, matching the validation pattern used by `defaultModel` and `defaultThinking`.
+
+## Inspecting the live mapping
+
+To see what `pi-subagents` has actually loaded right now:
+
+```text
+/subagents-models
+/subagents-models reviewer
+```
+
+That reports the live runtime mapping, which can differ from settings on disk until you reload Selesai.
+
+## Fuzzy model matching
+
+You do not have to spell a model exactly. Model ids are matched fuzzily against the registry, so these all resolve to the same model:
+
+- Provider separator variations: `anthropic/claude-sonnet-4`, `anthropic:claude-sonnet-4`, `anthropic.claude-sonnet-4`
+- Id separator variations: `claude-haiku-4.5` vs `claude-haiku-4-5`
+- Case differences: `Claude-Sonnet-4` vs `claude-sonnet-4`
+- Optional trailing date stamps: `claude-haiku-4-5-20251001` or `claude-haiku-4-5-2025-10-01` vs `claude-haiku-4-5`
+
+Exact `provider/id` matches still win, and a qualified provider query never silently switches providers — it only matches within the named provider. Ambiguous bare ids that exist under multiple providers still require a provider prefix or the current session's provider to disambiguate.
+
+## Model scope enforcement
+
+To keep subagents inside a budget or compliance profile, enforce a model scope. Put `subagents.modelScope` in user or project settings (project overrides user):
+
+```json
+{
+  "subagents": {
+    "modelScope": {
+      "enforce": true,
+      "strict": true,
+      "allow": ["anthropic/*", "openai/gpt-5-*"]
+    }
+  }
+}
+```
+
+- `allow` is a list of glob patterns matched against the resolved `provider/id` (only `*` is special, case-insensitive). A resolved model that matches none of the patterns is rejected.
+- Models you pass explicitly — the tool-call `model`, `--model`, or a clarify pick — error and abort the run.
+- By default, models from agent frontmatter, `subagents.defaultModel`, the inherited parent session model, or fallback chains only warn and remain available, so existing configurations keep working while you tighten the scope.
+- Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model. This includes inherited models and fallback candidates. An invalid fallback fails the run instead of being removed from the candidate chain.
+- `enforce: true` requires a non-empty `allow` list; otherwise the config is rejected at load time.
+
+## Profiles and provider model catalogs
+
+Profiles let you generate and save role-to-model assignments from a provider's live catalog.
+
+Profiles are stored under:
+
+```text
+~/.selesai/agent/profiles/pi-subagents/
+```
+
+Provider model catalogs are cached under:
+
+```text
+~/.selesai/agent/profiles/pi-subagents/providers/
+```
+
+The workflow:
+
+```text
+/subagents-refresh-provider-models openai-codex
+/subagents-generate-profiles openai-codex
+/subagents-load-profile openai-codex.quota
+```
+
+- `/subagents-refresh-provider-models` writes a serialized provider model catalog with observed registry data, simple role-oriented classification, and live probe results from tiny one-shot `pi -p --model ... --no-tools` checks. The cache refreshes when missing or stale; use `--force` to ignore freshness and probe again immediately.
+- `/subagents-generate-profiles` uses the provider catalog to produce quota and quality profiles.
+- `/subagents-check-profile` re-checks each assigned model in a saved profile against the current registry and a live probe, so you can detect model removals, auth problems, or stale assignments.