@selesai/code 0.8.3 → 0.8.4

package/dist/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md

@@ -16,7 +16,7 @@ Precedence is by parsed runtime name:
 2. user scope
 3. builtin agents
 
-Project settings resolve from the nearest parent directory containing a `.selesai` config dir or a legacy `.agents` agent dir by default. In monorepos or git worktrees where an incidental nested `.selesai` directory should not shadow the repository config, set `subagents.projectRootResolution: "git-root"` in the repository root `.selesai/settings.json`; a nested project can opt back with `"nearest"` in its own settings.
+Project settings resolve from the nearest parent directory containing `.pi` or `.agents` by default. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository config, set `subagents.projectRootResolution: "git-root"` in the repository root `.selesai/settings.json`; a nested project can opt back with `"nearest"` in its own settings.
 
 ## Running Subagents
 
@@ -30,8 +30,7 @@ External CLI profiles are async-only and one-shot. They support lifecycle artifa
 
 ```typescript
 subagent({
-  agent: "commentator",
-  task: "Review my current direction and challenge assumptions."
+  workflowScript: `return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction and challenge assumptions." })`
 })
 ```
 
@@ -39,9 +38,7 @@ subagent({
 
 ```typescript
 subagent({
-  agent: "commentator",
-  task: "Review my current direction and challenge assumptions.",
-  context: "fork"
+  workflowScript: `return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction and challenge assumptions.", context: "fork" })`
 })
 ```
 
@@ -56,28 +53,112 @@ its resolved launch context as `[fresh]` or `[fork]`. Aggregate headers show
 
 ### Scripted workflows
 
-`workflowScript` is the sole public orchestration surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, builder then monitor setup, or a fanout that the parent will consume together. Use a direct `{ agent, task }` call only for one isolated child with no sibling work or aggregate handoff.
+`workflowScript` is the scripted orchestration surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Scripts are ordinary JavaScript statement bodies, so use an explicit return such as `workflowScript: "return runs.run('main', { agent: 'worker', task: '...' })"` for a useful one-child result. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, worker then monitor setup, cross-repo prep lanes, or a fanout that the parent will consume together; use the declarative `chain` / `tasks` modes when the shape is known up front.
+
+**Workflow modes as `workflowScript` auto-loops.** The bundled `workflow` extension ships its four mode shapes (task, prototype, quicktype, loop) as `workflowScript` auto-loops launched via `/workflow-*`. Each mode runs its phases as `runs.run` steps and loops the build↔review round until the commentator reports clean. There are no checkpoints (one-shot-and-sleep); durable state is the auto-created mission per launch; recover via `mission.list`/`status`.
 
 ```js
 subagent({
   workflowScript: `
-    const scan = await runs.run("scan", { agent: "explorer", task: "Map the target" });
+    const scan = await runs.run("scan", { agent: "scout", task: "Map the target" });
     const reviews = await runs.all([
-      { key: "correctness", agent: "commentator", task: "Review correctness: " + scan.output },
-      { key: "tests", agent: "commentator", task: "Review tests: " + scan.output }
+      { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
+      { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
     ]);
     return reviews.map(result => result.output);
   `
 })
 ```
 
-Scripts run in a timed builder with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
+Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `prompts.render`, `emit`, captured `console`, and standard JavaScript. `await prompts.render("package:<name>" | "user:<name>" | "project:<name>", vars?)` reads a named Markdown fragment through the host resolver, applies simple scalar `{{name}}` interpolation, and returns plain task text. It does not give the script filesystem access. Pass the rendered text explicitly as `task` to `runs.run`. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
+
+For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`runs.all` item (or at the top level as a workflow default). It is shorthand for verified acceptance with that single command: the runtime executes it on the host, records the result as evidence, and memoizes it per tracked workspace state and effective environment. `gate` cannot be combined with `acceptance`; use explicit `acceptance.verify` for multiple commands or custom criteria.
+
+Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids, and a later workflow continues one with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. A follow-up loop can render each task with `await prompts.render(...)`. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
+
+### Chain execution
+
+```typescript
+subagent({
+  chain: [
+    { agent: "explorer", task: "Map the auth flow and summarize key files" },
+    { agent: "architect", task: "Create an implementation plan from {previous}" },
+    { agent: "builder", task: "Implement the approved plan based on {previous}" }
+  ]
+})
+```
+
+Chain steps can use templated variables such as `{task}`, `{previous}`,
+`{chain_dir}`, and `{outputs.name}`. Use `as: "name"` on a successful step or
+parallel task to make that output available to later steps. Prefer named outputs
+when a later step needs one specific result; keep `{previous}` for simple linear
+handoffs or full fan-in summaries. Use `phase` and `label` for status readability.
+Use `outputSchema` when later steps need reliable structured data; the child must
+call `structured_output` with schema-valid JSON, or the step fails.
+
+Use `agentContract: { version: 1 }` when a caller needs generic result projections
+instead of acceptance or mutation effects rewriting execution success. V1 adds
+`execution`, `acceptance`, `review`, and `effects`; omitted acceptance means no
+acceptance request. Chain steps advance on execution by default under v1. Set
+`gateOn: "acceptance"` only when a rejected explicit acceptance report should stop
+the chain.
+
+For planned human gates, add a checkpoint step: `{ checkpoint: "name", message?: "..." }` pauses the chain without launching a child until the parent calls `approve-checkpoint` / `reject-checkpoint` for the paused run. This is the first-class way to add an approval pause to a chain.
+
+### Parallel execution
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "explorer", task: "Explore the auth module" },
+    { agent: "commentator", task: "Review the API client" }
+  ]
+})
+```
+
+Top-level parallel tasks can override per-task behavior:
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "explorer", task: "Map auth", output: "auth-context.md", progress: true },
+    { agent: "researcher", task: "Research OAuth best practices", output: "oauth-research.md" },
+    { agent: "commentator", task: "Review auth tests", model: "anthropic/claude-sonnet-4" }
+  ],
+  concurrency: 3
+})
+```
+
+Repeat one parallel task N times with the same settings via `count` (useful for identical explorers or review angles without hand-duplicating entries):
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "explorer", task: "Map a distinct slice of the auth surface and return compressed context.", count: 3 }
+  ],
+  concurrency: 3,
+  context: "fresh"
+})
+```
+
+Parallel groups also work inside chain steps with `{ parallel: [...] }`, plus dynamic fanout via `{ expand: { from: { output, path }, item?, maxItems, parallel: {...}, collect: { as, outputSchema? } } }` when a producer step returns a structured target list. Avoid duplicate output paths in parallel tasks; concurrent children should not write to the same file. Delivery is reference-first by default: every child gets a durable saved output unless `output: false`, omitted `output` uses a generated per-run path, omitted `outputMode` resolves to `file-only`, and the parent result contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Inspect full output through the saved path, async status/transcript, or resume. Explicit `outputMode: "inline"` keeps the legacy full inline delivery; `output: false` disables durable result persistence (follow-up visibility falls back to bounded excerpts). Failed runs with a persisted result return the error/status plus the saved-output reference; persistence or read-back failures return only a bounded excerpt (first 80 lines / 4 KiB) together with the error, never raw unbounded output. Do not use `output: false` to get a file-only return; use file-only mode with an output path. In chains, relative `output` paths are chain-artifact paths under `{chain_dir}`, not project CWD paths; use an absolute `output` path or a persistent `chainDir` when a saved artifact must outlive the temp chain directory. Read-only children return the complete artifact in their final response and the runtime persists it, so missing write tools are not a supervisor blocker. Mutation-capable children still receive direct-write instructions.
+
+### Saved chains
+
+Saved `.chain.md` (simple sequential/static) and `.chain.json` (dynamic fanout, inline `outputSchema`) workflows live in user (`~/.selesai/agent/chains/`) and project (`.selesai/chains/`) chains dirs and are discovered recursively. Use them when the user wants a repeatable multi-agent flow without rewriting the chain each time:
+
+```text
+/run-chain review-chain -- review this branch
+/run-chain list
+```
+
+`/run-chain <name>` executes the saved chain through the normal chain executor; `agent`/`chain` management actions and `agentManagement` treat chains as first-class records alongside agents. Agents and chains can set optional frontmatter/package metadata; `name: explorer` plus `package: code-analysis` registers as runtime name `code-analysis.explorer` while serialization keeps `name` and `package` separate.
 
 ### Async/background
 
-Prefer async mode for every subagent launch. Set `async: true` no matter the task unless there is a specific reason to opt into a foreground/blocking run. This applies to explorers, researchers, builders, commentators, validators, commentator checks, one-off explorers, and scripted workflows. Keep the write path single-threaded even when the run is async.
+Prefer async mode for every subagent launch. Set `async: true` no matter the task unless there is a specific reason to opt into a foreground/blocking run. This applies to scouts, researchers, workers, reviewers, validators, oracle checks, one-off delegates, and scripted workflows. Keep the write path single-threaded even when the run is async.
 
-Async does not mean parallel writes. Do not edit the same active worktree while an async builder is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree.
+Async does not mean parallel writes. Do not edit the same active worktree while an async worker is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree.
 
 Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed.
 
@@ -87,20 +168,18 @@ In an interactive chat, normally return control when ready to yield and let Pi w
 
 ```typescript
 subagent({
-  agent: "builder",
-  task: "Run the full test suite",
+  workflowScript: `return runs.run("main", { agent: "worker", task: "Run the full test suite" })`,
   async: true
 })
 ```
 
-File-only output mode works for async single runs and workflowScript child launches. Use distinct absolute or durable output paths when later script steps need stable references.
+File-only output mode works for workflowScript child launches. Use distinct absolute or durable output paths when later script steps need stable references. For cross-codebase waves, include the repo slug or lane key in each output path so reports from different repositories cannot collide.
 
 For review fanout where the parent continues a local audit:
 
 ```typescript
 const run = subagent({
-  agent: "commentator",
-  task: "Review the current diff for correctness issues. Do not edit files.",
+  workflowScript: `return runs.run("correctness", { agent: "reviewer", task: "Review the current diff for correctness issues. Do not edit files." })`,
   async: true,
   context: "fresh"
 })
@@ -109,7 +188,7 @@ const run = subagent({
 
 While children run, the persistent FleetView and the collapsed foreground tool-result card show live per-child detail: resolved model and thinking level, `[fresh]`/`[fork]` context, tool/token/elapsed counters, and current activity. The collapsed running card also prints the configured expand-key hint ("Press … for live detail"); expanding it shows nested children, recent tools, and recent output. Model badges appear once the child's model resolves at first attempt start. `/subagents-fleet` opens the live fleet inspector, which also has per-child controls (`s` steer, `D` stop with confirmation). When optional Herdr 0.7.5+ is available, `H` opens a raw inspector dashboard for the selected active async child; this mirrors artifacts rather than attaching to the headless child. Use it for confusing or long-running active async work when the human wants a dedicated visual pane or FleetView is insufficient, not for routine headless runs.
 
-Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a explorerd fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
+Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
 
 Stop a current-session top-level async run with `stop` (or `/subagents-stop`). Stopped runs finish as `stopped`/cancelled and are not resumable. For an active foreground single-subagent run, `/subagents-detach [run-id]` leaves the child running without terminating it and returns the eventual result through status/wait. Append one more step to the tail of a still-running durable chain with `append-step` (`step` must contain exactly one step object). Use checkpoint steps for planned human gates; they pause without launching a child and are approved or rejected through current-session control actions:
 
@@ -124,13 +203,13 @@ subagent({ action: "approve-checkpoint", id: "run-id" })
 subagent({ action: "reject-checkpoint", id: "run-id" })
 ```
 
-Use `steer` for top-level live async guidance and `resume` after a explorerd run pauses or finishes. Routed nested runs retain their existing non-destructive live follow-up path:
+Use `steer` for top-level live async guidance and `resume` after a delegated run pauses or finishes. Routed nested runs retain their existing non-destructive live follow-up path:
 
 ```typescript
 subagent({ action: "steer", id: "run-id", message: "Focus on the failing test." })
 subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
-subagent({ action: "resume", id: "run-id", index: 1, message: "Continue commentator 2." })
-subagent({ action: "resume", id: "nested-run-id", message: "Continue this nested commentator." })
+subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." })
+subagent({ action: "resume", id: "nested-run-id", message: "Continue this nested reviewer." })
 ```
 
 Resume behavior:
@@ -162,8 +241,8 @@ A cooperating terminal runtime can register read-only external records through `
 Schedules are durable project records under `.pi-subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.selesai/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
 
 ```typescript
-// One-shot commentator
-subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m", agent: "commentator", task: "Review the diff." })
+// One-shot reviewer
+subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m", workflowScript: "return runs.run('main', { agent: 'reviewer', task: 'Review the diff.' })" })
 
 // Fixed recurring workflow
 subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "..." })
@@ -178,13 +257,13 @@ subagent({ action: "schedule.run-due" })
 subagent({ action: "schedule.delete", id: "backlog" })
 ```
 
-`schedule.create` accepts exactly one target (`workflowScript`, or `agent` with optional `task`) and exactly one trigger (`at`, or a fixed `every` interval using `m`, `h`, `d`, or `w`). Runs always launch async with fresh context and no automatic mission; mission attachment is deferred from this first slice. `overlap` is currently `skip`; `catchUp` supports `latest` and `none`. `schedule.run-due` is the headless external-launcher seam. Calendar recurrence, cron, and the schedule inspector are deferred from this first safe slice. Definitions, bounded history, append-only events, and per-run receipts remain project-scoped across Pi sessions.
+`schedule.create` accepts exactly one target, `workflowScript`, and exactly one trigger (`at`, or a fixed `every` interval using `m`, `h`, `d`, or `w`). Runs always launch async with fresh context and no automatic mission; mission attachment is deferred from this first slice. `overlap` is currently `skip`; `catchUp` supports `latest` and `none`. `schedule.run-due` is the headless external-launcher seam. Calendar recurrence, cron, and the schedule inspector are deferred from this first safe slice. Definitions, bounded history, append-only events, and per-run receipts remain project-scoped across Pi sessions.
 
 Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
 
 ### Subagent control
 
-Subagent control is the runtime visibility and intervention layer for explorerd runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, `stopped`, `failed`, or `rejected`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Manual top-level async cancellation uses `stop` / `/subagents-stop`; a live async chain can gain one more tail step via `append-step`, and a paused async chain checkpoint can be decided with `approve-checkpoint` or `reject-checkpoint`.
+Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, `stopped`, `failed`, or `rejected`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Manual top-level async cancellation uses `stop` / `/subagents-stop`; a live async chain can gain one more tail step via `append-step`, and a paused async chain checkpoint can be decided with `approve-checkpoint` or `reject-checkpoint`.
 
 Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
 
@@ -201,18 +280,20 @@ subagent({ action: "interrupt", id: "abc123" })
 subagent({ action: "interrupt", id: "nested-run-id" })
 ```
 
-A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the explorerd task succeeded or failed. Bare `interrupt` does not target hidden nested descendants; use the explicit nested id. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow.
+A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the delegated task succeeded or failed. Bare `interrupt` does not target hidden nested descendants; use the explicit nested id. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow.
 
 Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual:
 
 ```typescript
 subagent({
-  agent: "builder",
-  task: "Run the slow migration test suite",
-  control: {
-    needsAttentionAfterMs: 300000,
-    notifyOn: ["needs_attention"]
-  }
+  workflowScript: `return runs.run("slow-tests", {
+    agent: "worker",
+    task: "Run the slow migration test suite",
+    control: {
+      needsAttentionAfterMs: 300000,
+      notifyOn: ["needs_attention"]
+    }
+  })`
 })
 ```
 
@@ -228,9 +309,9 @@ The action waits up to three seconds for the child Pi session to accept the corr
 
 ## Watchdog
 
-The subagent watchdog is an **opt-in** adversarial change commentator. It is not the
-`commentator` subagent and is not configured by `subagents.defaultModel` or
-`agentOverrides.commentator`.
+The subagent watchdog is an **opt-in** adversarial change reviewer. It is not the
+`reviewer` subagent and is not configured by `subagents.defaultModel` or
+`agentOverrides.reviewer`.
 
 When enabled, it reviews actual repo edits at safe `agent_end` boundaries only if
 the final worktree state changed during that turn. Unchanged or reverted diffs and
@@ -242,7 +323,7 @@ They keep bounded current-scope context from real user prompts (`watchdog.scope.
 and can optionally run non-blocking Scopey-style cadence reviews every N tool results
 (`watchdog.cadence.everyNTools`). Cadence corrections and blocker auto-follow prompts
 are always transcript-visible; choose the watchdog model that matches the desired
-cheap-monitor vs strong-commentator policy.
+cheap-monitor vs strong-reviewer policy.
 
 Prefer a strong complementary model (for example Opus 4.8 high paired against a
 GPT 5.5 main session, or the reverse). Recommendation and configuration:
@@ -263,13 +344,13 @@ subagent({ action: "watchdog.check" })
 ```
 
 `session` scope is temporary. Persistent `user`/`project` scopes write settings only
-when the user asked. Use ordinary fresh-context `commentator` fanout for planned review
+when the user asked. Use ordinary fresh-context `reviewer` fanout for planned review
 waves; enable the watchdog when you want an automatic second pass on real edits.
 
 ## Clarify TUI
 
-Single and parallel runs support a clarification TUI when you want to preview or
-edit parameters before launch:
+Single, chain, and parallel runs support a clarification TUI when you want to preview
+or edit parameters before execution:
 
 ```typescript
 subagent({
@@ -279,34 +360,49 @@ subagent({
 })
 ```
 
-Ordinary tool calls launch in the background by default. Set `async: false` when the current turn needs a foreground result, or `clarify: true` when you want the clarify UI; clarify always stays foreground. Clarify edits affect only the next run; use management actions, settings, or markdown files for persistent changes.
+Tool calls launch directly by default. Set `clarify: true` on single, parallel, or
+chain runs when you want the clarify UI. Clarify edits affect only the next run;
+use management actions, settings, or markdown files for persistent changes.
+For programmatic background launches, use `async: true`; `clarify: true` keeps the
+run foreground for the clarify UI.
 
 ## Missions and cross-project routing
 
 Missions are the durable orchestration layer. Use this noun map:
 
 - **Project/codebase** — where work happens.
-- **Mission** — why explorerd work exists and how to recover it later.
+- **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 launches with a task create a mission by default, so substantial explorerd work has a persisted goal, status, run links, decisions, artifacts, and delivery receipts that survive compaction or a new parent chat. Automatic persistence failures leave the run intact and set `details.missionWarning`; explicit `missionId` or `mission` remains strict before launch. Human receipts end with a mission id/status line, while structured JSON text remains untouched and `details.missionId` is authoritative. Pass `missionId` to attach an existing mission, use `mission: { title, goal?, labels? }` to control the auto-created record, pass `mission: false` for intentionally ephemeral work, or set `missions.enabled: false` to opt out globally.
+Ordinary launches with a task create a mission by default, so substantial delegated work has a persisted objective, status, run links, decisions, artifacts, and delivery receipts that survive compaction or a new parent chat. Automatic persistence failures leave the run intact and set `details.missionWarning`; explicit `missionId` or `mission` remains strict before launch. Human receipts end with a mission id/status line, while structured JSON text remains untouched and `details.missionId` is authoritative. Pass `missionId` to attach an existing mission, use `mission: { title, objective?, goal?, budget?, labels? }` to control the auto-created record, pass `mission: false` for intentionally ephemeral work, or set `missions.enabled: false` to opt out globally. `objective` is the intent string; `goal: true` requires `budget.tokens` and turns the open mission into a continuation driver that sends one needs-attention notice after idle parent turns until the budget is exhausted, the goal is paused with `mission.update` `{ goal: { paused: true } }`, or the mission closes.
 
 Use `mission.update` while work runs to record decisions, artifacts, labels, summaries, or delivery receipts. A receipt records a pull request, CI, deployment, or release link with a concise status; it does not authorize or automate merge, CI polling, or deployment. Record open product, architecture, or safety decisions there and escalate them upward; do not let a child decide silently. Use `mission.attach-run` only for runs launched outside the normal mission-backed path, and use `mission.close` with a terminal status and concise summary when the mission is done.
 
+### Mission use policy
+
+- **Keep the default.** Every ordinary `workflowScript` launch with a task creates one enclosing mission automatically. All workflow children share it and never get their own. Do not add `mission: {...}` boilerplate. Pass it only to set the title, objective, labels, or to enable `goal` with `budget`.
+- **Use `mission: false` for noise.** Use it for trivial one-shot lookups, scouts, disposable probes, and quick validation where a recovery record is noise. It removes the mission and the `state` global for the whole workflow, so do not use it for monitors or multi-workflow loops that coordinate through `state`. Scheduled runs already launch without automatic missions.
+- **Use `missionId` for follow-up work.** Attach later work to an existing objective with `missionId`; attachment re-marks the mission active. `missionId` and `mission` are mutually exclusive. Explicit attachment fails before launch if the mission is missing, while automatic missions degrade to `details.missionWarning` without blocking the run.
+- **Keep `state` small.** Mission `state` is JSON coordination across workflows on the same mission. Keys use the same format as run keys, values must be JSON, and the whole state file is capped at 256 KiB. Each `set` merges one key under a file lock. Put large content in artifact files and store paths in state. In goal missions, write `state.set("nextReadyAction", "...")` so the next idle-turn notice names the exact ready step.
+- **Use artifacts and receipts as evidence.** Mission-backed launches already record run artifacts such as async `status.json`, `events.jsonl`, child output paths, and handoff manifests. Add `mission.update` artifacts only for extra durable outputs such as `patch`, `review`, or `note` files. Add receipts for external outcomes: `pull_request`, `ci`, `deployment`, or `release`; each receipt needs an absolute URL. Receipts are evidence, not authority to merge, deploy, or release.
+- **Treat decisions as append-only.** `mission.update` `decisions` can only add open decisions. No tool action resolves one. In a goal mission, an unresolved decision becomes the fallback next ready action in each notice. Use decisions sparingly there; record them for escalation and audit, steer goal continuation through `state.nextReadyAction`, and close the mission when the question is settled.
+- **Close missions when done.** `mission.close` takes `missionStatus` `completed`, `failed`, or `cancelled` plus a concise `summary`, and ends any goal loop. Goal notices go only to the owning session and stop silently at `budget-exhausted` without closing or claiming success, so close explicitly. Terminal missions are pruned beyond configured retention, so store durable outputs as artifacts, receipts, and summary before closing.
+
 After compaction, restart, or confusing history, recover from durable state first: `mission.list` in the project, `mission.list` with `missionScope: "global"` for the user-local cross-project pointer index, then `mission.show` for the relevant mission. `mission.show` refreshes linked async status when available and returns warnings instead of hiding the mission if a linked status file is temporarily unreadable. Use the linked run ids with normal `status`, `steer`, `resume`, or `stop` actions. Project mission JSON remains authoritative over chat history.
 
 Routing rule:
 - Same project: ordinary mission-backed subagents.
-- Different project, small/bounded task: ordinary subagent with explicit `cwd`.
-- Different project, substantial or long-running work: open a project-owned Herdr pane rooted there, then give that project Pi session a narrow mission/result contract. Do not model it as ordinary child nesting, and do not expect existing headless runs to move into the pane.
+- Different project, small/bounded task: ordinary async subagent with explicit `cwd`, an authority boundary, and durable output.
+- Several projects with independent work: one async `workflowScript` whose child keys include repo slugs and whose child calls set explicit `cwd`; keep publication and merge decisions serial per repo.
+- Different project, substantial or long-running work: open a project-owned Herdr pane rooted there when a separate visible project session is useful, then give that project Pi session a narrow mission/result contract. Do not model it as ordinary child nesting, and do not expect existing headless runs to move into the pane.
 
-Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi-subagents/project-panes/herdr.json`.
+Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi-subagents/project-panes/herdr.json`. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
 
 ```typescript
-subagent({ action: "mission.create", mission: { title: "Ship auth refresh", goal: "Implement and validate refresh handling" } })
-subagent({ agent: "builder", task: "Implement the approved plan", missionId: "<mission-id>" })
-subagent({ agent: "explorer", task: "Quickly answer whether this file exists", mission: false })
+subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
+subagent({ workflowScript: `return runs.run("main", { agent: "worker", task: "Implement the approved plan" })`, missionId: "<mission-id>" })
+subagent({ workflowScript: `return runs.run("main", { agent: "scout", task: "Quickly answer whether this file exists" })`, mission: false })
 subagent({ action: "mission.list", missionScope: "global" })
 subagent({ action: "project.open", cwd: "/path/to/other-repo", message: "Own this mission for the project and report back with receipts." })
 subagent({ action: "project.status", cwd: "/path/to/other-repo" })
@@ -323,8 +419,8 @@ them share one filesystem view.
 subagent({
   workflowScript: `
     const results = await runs.all([
-      { key: "feature-a", agent: "builder", task: "Implement feature A", worktree: true },
-      { key: "feature-b", agent: "builder", task: "Implement feature B", worktree: true }
+      { key: "feature-a", agent: "worker", task: "Implement feature A", worktree: true },
+      { key: "feature-b", agent: "worker", task: "Implement feature B", worktree: true }
     ]);
     return results.map(({ key, artifactPaths }) => ({ key, artifactPaths }));
   `
@@ -338,7 +434,7 @@ requires a clean git state and is mainly for intentionally parallel write
 workflows. On completion, use each child's handoff path from its
 `artifactPaths` instead of scraping combined text. Each manifest records child status and output references, full
 patch paths and stats, and whether each temporary worktree and branch was
-removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", handoffPath: "<child handoff path>" })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several commentatory agents, prefer a
+removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", handoffPath: "<child handoff path>" })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several advisory agents, prefer a
 single-writer pattern instead.
 
 Git worktrees start from tracked files, so ignored or untracked build state
@@ -351,39 +447,51 @@ running tests, typecheck, or builds. If module resolution fails in a fresh
 worktree, first confirm dependencies were linked, installed, or provisioned by
 `worktreeSetupHook` before treating it as a code failure.
 
-## The commentator Workflow
+## The Oracle and Commentator Workflows
 
-The intended commentator loop is:
-1. the main agent launches `commentator` (fresh context by default; pass `context: "fork"` only when a branched commentatory thread that inherits the parent session history is intended)
-2. `commentator` reviews direction, drift, assumptions, and risks
-3. `commentator` can coordinate back through `contact_supervisor` when the bridge injects it
+The intended advisory loop is:
+1. the main agent forks to `oracle` (or launches a fresh `commentator`)
+2. the advisor reviews direction, drift, assumptions, and risks
+3. it can coordinate back through `contact_supervisor` when the bridge injects it
 4. the main agent decides what direction to approve
-5. only then should `builder` implement
+5. only then should `worker` (or `builder`) implement
 
 ```typescript
-// Advisory review. commentator defaults to fresh context; fork explicitly when a branched commentatory thread is intended.
+// Advisory review in a branched thread. Oracle defaults to forked context.
+subagent({
+  workflowScript: `return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction, challenge assumptions, and propose the best next move." })`
+})
+
+// Selesai-native equivalent. Commentator defaults to fresh context; fork
+// explicitly when a branched advisory thread is intended.
 subagent({
   agent: "commentator",
-  task: "Review my current direction, challenge assumptions, and propose the best next move."
+  task: "Review my current direction, challenge assumptions, and propose the best next move.",
+  context: "fork"
 })
 
-// Implementation only after explicit approval. builder defaults to fresh context; pass context: "fork" when inherited parent context is intentionally required.
+// Implementation only after explicit approval. Worker defaults to forked context;
+// builder defaults to fresh context, so pass context: "fork" when inherited
+// parent context is intentionally required.
 subagent({
-  agent: "builder",
-  task: "Implement the approved approach: ..."
+  workflowScript: `return runs.run("implementation", { agent: "worker", task: "Implement the approved approach: ..." })`
 })
 ```
 
-`commentator` is not a fresh-context commentator in the Cognition article sense. It is
-an commentatory thread that reviews direction, drift, and risks against the task/plan.
-Pass `context: "fork"` when the review should inherit the parent session history and
-use that history as a baseline contract; otherwise fresh context is the default.
+`oracle` is not a fresh-context reviewer in the Cognition article sense. It is
+a forked advisory thread that inherits the parent session history and uses that
+history as a baseline contract. `commentator` is the Selesai-native equivalent:
+an advisory thread that reviews direction, drift, and risks against the task/plan;
+pass `context: "fork"` when the review should inherit the parent session history
+and use that history as a baseline contract, otherwise fresh context is the default.
 
-Use `commentator` as a smart-friend escalation when the parent needs help with trajectory rather than diff inspection: architectural boundaries, model capability routing, merge conflicts, commentator disagreement, context drift after long work, a builder about to invent a pattern, or fixes that require product/scope tradeoffs. Ask broad questions when the right concern is unclear, and let `commentator` point out missing context or files the parent should inspect before asking again. Keep `commentator` commentatory unless it has been explicitly assigned the single writer role.
+Use `oracle`/`commentator` as a smart-friend escalation when the parent needs help with trajectory rather than diff inspection: architectural boundaries, model capability routing, merge conflicts, reviewer disagreement, context drift after long work, a worker about to invent a pattern, or fixes that require product/scope tradeoffs. Ask broad questions when the right concern is unclear, and let the advisor point out missing context or files the parent should inspect before asking again. Keep `oracle`/`commentator` advisory unless it has been explicitly assigned the single writer role.
 
 ## Subagent + Intercom Coordination
 
-`pi-subagents` includes native supervisor coordination. Child agents can use `contact_supervisor` to ask the exact parent session that spawned them; messages are scoped by parent session id and should not appear in other Pi sessions.
+`pi-subagents` includes native supervisor coordination. Child agents can use `contact_supervisor` to ask the exact parent session that spawned them; messages are scoped by parent session id and should not appear in other Pi sessions. Parents inspect or reply with `subagent_supervisor`. This path does not require `pi-intercom`.
+
+This is separate from optional external completion delivery. Set `intercomBridge.resultDelivery: true` only when an external listener consumes and acknowledges `subagent:result-intercom` grouped results. It does not deliver results by itself, and it does not change native supervisor asks or progress updates.
 
 Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target. Prefer the tool from the injected bridge instructions.
 

package/dist/extensions/pi-subagents/skills/pi-subagents/references/management-authoring-rpc.md

@@ -12,6 +12,24 @@ The `subagent(...)` tool also supports management actions.
 subagent({ action: "list" })
 ```
 
+### List retained children
+
+```typescript
+subagent({ action: "children.list" })
+```
+
+Lists up to the last 10 completed retained workflow children from this parent session with their run ids. Continue one in a later workflow with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`; the revived child keeps its stored agent, model, and tool contract.
+
+### Refinement overlays
+
+```typescript
+subagent({ action: "refine", agent: "reviewer" })
+subagent({ action: "refine.show", agent: "reviewer" })
+subagent({ action: "refine.rollback", agent: "reviewer" })
+```
+
+`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi-subagents/refinements/<agent>.md` with revision snapshots and is injected into that agent's child system prompt for this project. `refine.show` prints the current overlay and history; `refine.rollback` restores the previous revision. Guidance that tries to override safety, policy, tool, output, acceptance, developer, or system instructions is rejected. `/subagents-refine <agent>` is the slash equivalent.
+
 ### Create an agent
 
 ```typescript
@@ -51,15 +69,15 @@ subagent({ action: "delete", agent: "code-analysis.my-agent" })
 
 ```typescript
 // Copy a bundled builtin/package agent to user scope as an editable custom file.
-subagent({ action: "eject", agent: "commentator" })
-subagent({ action: "eject", agent: "commentator", agentScope: "project" })
+subagent({ action: "eject", agent: "reviewer" })
+subagent({ action: "eject", agent: "reviewer", agentScope: "project" })
 
 // Hide an agent from runtime discovery without deleting it (reversible).
-subagent({ action: "disable", agent: "commentator" })
-subagent({ action: "enable", agent: "commentator", agentScope: "project" })
+subagent({ action: "disable", agent: "reviewer" })
+subagent({ action: "enable", agent: "reviewer", agentScope: "project" })
 
 // Delete the scope's custom agent file and/or settings override, restoring the bundled default.
-subagent({ action: "reset", agent: "commentator" })
+subagent({ action: "reset", agent: "reviewer" })
 ```
 
 `eject` copies a builtin or package agent verbatim into the user (default) or project agent dir so it can be customized without hunting package files; the copy shadows the original by runtime name. `disable` writes a reversible `agentOverrides.<name>.disabled: true` entry to the user or project settings file. `enable` removes that `disabled` field while keeping any other override fields. `reset` removes the scope's custom file and settings override to restore the bundled default, and refuses if no bundled default exists (use `delete` for purely custom agents). All four take optional `agentScope: "user" | "project"`; project overrides win over user ones, so target the project scope to undo a project-scope disable.
@@ -130,15 +148,17 @@ The package includes prompt shortcuts for common workflows: `/parallel-review`,
 `/parallel-cleanup`. Use them when the user wants repeatable review,
 review/fix loops, research, context handoff, implementation handoff,
 clarification, or cleanup-review patterns. `/parallel-review autofix` and
-`/parallel-cleanup autofix` synthesize commentator feedback and then apply only the
+`/parallel-cleanup autofix` synthesize reviewer feedback and then apply only the
 fixes worth doing now. Parent agents can also apply the same recipes directly
 with `subagent(...)` when the user describes the workflow in natural language
 instead of invoking a slash command.
 
-Additional user prompt templates can explorer into `pi-subagents` through the native `/prompt-workflow` command. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `fresh`, `fork`, or `inheritContext` for the native adapter.
+Additional user prompt templates can delegate into `pi-subagents` through the native `/prompt-workflow` and `/chain-prompts` commands. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `fresh`, `fork`, or `inheritContext` for the native adapter; a `chain:` frontmatter list (names separated by ` -> `) runs the templates as a sequence, and `/chain-prompts` runs that sequence as a native chain.
+
+Native chain and parallel steps are also launchable directly from the command line: `/chain <agent> <task> | <agent> <task> [--bg] [--fork] [--fresh]`, `/parallel <agent> <task> | <agent> <task> [--bg]`, and `/run-chain <name>` for saved `.chain.md` / `.chain.json` workflows (`/run-chain list` lists them). Saved chains are managed like agents through `{ action: "create" | "get" | "update" | "delete" }` with `chainName`, and discovered from user (`~/.selesai/agent/chains/`) and project (`.selesai/chains/`) chains dirs plus package `chains` metadata.
 
 ## Extension RPC
 
 Other Pi extensions can call `pi-subagents` through the in-process event bus. The RPC channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
 
-Methods: `ping`, `status`, `spawn`, `steer`, `interrupt`, `resume`, and `stop`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` is async-only and rejects management actions, `async: false`, or `clarify: true`; it reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and explorers to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.
+Methods: `ping`, `status`, `spawn`, `steer`, `interrupt`, `resume`, and `stop`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` requires `workflowScript`, is async-only, and rejects management actions, `async: false`, or `clarify: true`; it reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.