pi-subagents 0.81.0 → 0.82.1

package/bundle/control-channel.js

@@ -1,8 +1,8 @@
 import {
   requestAsyncStop
-} from "./chunk-BJN5LUQY.js";
+} from "./chunk-OYF6AFDY.js";
 import "./chunk-NIXWDZZV.js";
-import "./chunk-ZBC44JJ3.js";
+import "./chunk-CIZQXJ5Q.js";
 import "./chunk-5LFLVSTM.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";

package/bundle/index.js

@@ -17,7 +17,7 @@ function readInstalledPackageVersion() {
 var loadedPackageVersion = readInstalledPackageVersion();
 
 // index.ts
-var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-V6MR5TOQ.js")).default : process.env.PI_SUBAGENT_CHILD === "1" ? void 0 : (await import("./chunk-V3BIUPLU.js")).default;
+var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-JYUKW2SY.js")).default : process.env.PI_SUBAGENT_CHILD === "1" ? void 0 : (await import("./chunk-IVAE5Z6Q.js")).default;
 function registerSubagentExtension(pi) {
   const installedVersion = readInstalledPackageVersion();
   if (installedVersion !== loadedPackageVersion) {

package/bundle/intercom-bridge.js

@@ -1,8 +1,8 @@
 import {
   resolveIntercomSessionTarget
-} from "./chunk-ZP3HODFH.js";
+} from "./chunk-XSWOTIA3.js";
 import "./chunk-7F6RKT6W.js";
-import "./chunk-ZBC44JJ3.js";
+import "./chunk-CIZQXJ5Q.js";
 import "./chunk-5LFLVSTM.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";

package/bundle/preflight.js

@@ -2,22 +2,22 @@ import {
   buildEffectiveSystemPrompt,
   canPreferForkFromSnapshot,
   resolveSubagentLaunchContext
-} from "./chunk-ARRKBB2B.js";
-import "./chunk-EYNJ6VL6.js";
+} from "./chunk-GJECHSAR.js";
+import "./chunk-PLCCBLPY.js";
 import {
   loadConfig
-} from "./chunk-WSBNENFS.js";
+} from "./chunk-UCPP4GNU.js";
 import {
   nestedResultsPath,
   processTerminalCandidatePath,
   processTerminalPath,
   resultFilePath
-} from "./chunk-VJHOELQP.js";
+} from "./chunk-46XKCPJR.js";
 import {
   applyIntercomBridgeToAgent,
   resolveIntercomBridge,
   validateIntercomBridgeConfig
-} from "./chunk-ZP3HODFH.js";
+} from "./chunk-XSWOTIA3.js";
 import {
   AGENT_DEFINITION_PROJECTION_VERSION,
   resolveLaunchBinding,
@@ -26,7 +26,7 @@ import {
 import {
   applyThinkingSuffix,
   resolvePiLaunchToolPlan
-} from "./chunk-G5DKFLLI.js";
+} from "./chunk-4SDU2BZX.js";
 import {
   assertRequiredChildExtensionsAdmitted,
   resolveRequiredChildExtensions
@@ -34,7 +34,7 @@ import {
 import {
   getArtifactPaths,
   getArtifactsDir
-} from "./chunk-3DC5KBVP.js";
+} from "./chunk-5TYMSZX3.js";
 import {
   assertClaudeCodeModelScope,
   assertThinkingWithinCeiling,
@@ -61,7 +61,7 @@ import {
   resolveSkillsWithFallback,
   resolveStepBehavior,
   unknownAgentDiagnosticContext
-} from "./chunk-ZBC44JJ3.js";
+} from "./chunk-CIZQXJ5Q.js";
 import {
   DIRS,
   SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,

package/bundle/project-panes.js

@@ -8,10 +8,10 @@ import {
   openProjectPane,
   projectPaneBindingPath,
   readProjectPaneBinding
-} from "./chunk-V2JWDB5U.js";
+} from "./chunk-52UBALJL.js";
 import "./chunk-7J4ZXMY7.js";
-import "./chunk-3DC5KBVP.js";
-import "./chunk-ZBC44JJ3.js";
+import "./chunk-5TYMSZX3.js";
+import "./chunk-CIZQXJ5Q.js";
 import "./chunk-5LFLVSTM.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";

package/docs/agents.md

@@ -43,7 +43,7 @@ Builtins load at the lowest priority, so a user or project agent with the same n
 | `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
 | `evidence-auditor` | Independent evidence review of important claims in an existing research brief. |
 | `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
-| `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
+| `reviewer` | Read-only code review. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
 | `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
 | `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
 
@@ -282,6 +282,36 @@ Placed external profiles are one-shot and stop-only: they cannot steer, resume,
 
 pi-subagents never clones, pulls, or checks out on the machine. Generic `external-cli` commands and managed worktrees are rejected before launch; saved-machine placement accepts native Pi and only the six code-owned external profiles.
 
+## Running a Pi child in a Rex pane on this machine
+
+`machine: "local"` runs a native Pi child as a visible Pi in a new background tab of your own Rex session, labeled `subagent-<run id tail>`. It works wherever `machine` works: frontmatter, settings overrides, the `subagent` tool, workflow `runs.run`, chain, parallel, and dynamic-fanout steps. `local` is reserved and never looks in the Herdr catalog. The parent Pi must run inside Rex: with no `REX_SESSION`, or a session the Rex server does not confirm, the launch fails before anything starts.
+
+The parent drives the child through the same bridge as a Herdr-placed Pi: prompt, steer, follow-up, abort, `contact_supervisor`, and results. The child Pi loads pi-subagents from its own extensions, so it must be installed at the same version. `cwd` is a directory on this machine; a relative path joins the launch directory. pi-subagents finds `rex` in `$REX_BIN_DIR`, then on `PATH`, then in the Rex server app.
+
+A finished child keeps its tab open, with the idle Pi, until you close it; an aborted or stopped child's tab is closed. Limits: native Pi only (Claude Code, Codex, Cursor, and generic `external-cli` agents are rejected), fresh context only, and the same restrictions as a Herdr-placed Pi (no local extension paths, process environment, nested delegation, permission rules, or tool budgets).
+
+## Running a Pi child in a Rex pane on another Mac
+
+Name a Mac you reach over SSH in your user settings (`~/.pi/agent/settings.json`), with its repo root:
+
+```json
+{
+  "subagents": {
+    "machines": {
+      "workmac": { "rex": { "ssh": "100.82.67.118" }, "cwd": "~/dev/app" }
+    }
+  }
+}
+```
+
+`machine: "workmac"` then runs a native Pi child as a visible Pi in a new background tab of the Rex session labeled `subagents` on that Mac. pi-subagents creates the session the first time and reuses it after that; if two sessions there have that label, the launch fails until you close or rename one. Every `rex` command runs on that Mac over SSH, and the bridge socket comes back through an SSH forward, so SSH must work without a prompt (`ssh <target>` once to accept the host key). A name with a `rex` entry never looks in the Herdr catalog, so Herdr does not need to be installed.
+
+Only user settings may name a Rex host: a `rex` entry in a project's `.pi/settings.json` fails the launch, so a cloned repo cannot choose where a task runs. `cwd` can come from project or user settings, as for Herdr machines: a relative step `cwd` joins it, and an absolute or `~` path is used as given. The other Mac needs Rex, Pi on its login shell's `PATH`, and pi-subagents installed at the same version. The child edits that Mac's disk, so its changed files come from that Mac's Git state, as for a Herdr-placed child.
+
+Programs in a Rex tab run under the Rex app's macOS privacy permissions. If Pi on that Mac reads files in Desktop, Documents, or Downloads (for example a package path in its settings), allow Rex there first: open a Rex tab on that Mac, run `ls ~/Documents`, and accept the prompt. Until then Pi waits on the prompt and the launch times out.
+
+To watch the tab, open the `subagents` session in Rex on that Mac. To watch it from this Mac, add that Mac's Rex server to your hosts here once (`rex hosts add workmac <endpoint>`; after `rex server tailscale on` there, `rex whoami` on that Mac shows its Tailscale address). Tab lifecycle and limits are the same as for `machine: "local"`.
+
 ## Sandboxing background children with a launcher
 
 A launcher wraps an agent's background runner in a command you choose, so that agent can run in a different sandbox from the parent session. Define the command in the user config key [`runnerLaunchers`](configuration.md#runnerlaunchers), then name it in the agent file:
@@ -512,6 +542,7 @@ How `tools` behaves:
 - `tools` omitted: the child session gets Pi's normal builtin tools.
 - `tools` present: regular tool names become an explicit allowlist.
 - `tools:` empty: the child session gets no tools.
+- `tools: +codemode` or `tools: -write`: rejected. Pi's `--tools` and `defaultTools` accept `+name`/`-name` entries that edit the default tool set, but a child's `tools` list replaces that set, so name every tool the child needs, or omit `tools` and use `excludeTools` to drop one. A local agent with such an entry fails before launch. A Herdr- or Rex-placed child resolves its agent on that machine, so an entry only there fails when the pane bridge is configured, before the first prompt.
 - `allowNestedSubagents: true`: explicitly enables child-safe nested fanout without turning omitted `tools` into an allowlist. Depth and inherited capability ceilings still apply.
 - `allowedAgents: scout, reviewer`: if nesting is separately enabled, restricts this agent's descendant launches to those names. `allowedAgents:` denies all descendants and omission is unrestricted except for inherited/runtime policy.
 
@@ -619,11 +650,10 @@ The package bundles a `pi-subagents` skill that is automatically available to th
 
 What it covers:
 
-- **Delegation patterns**: how to select a bounded agent and single, parallel, scripted, or async shape after delegation is authorized, including fresh or forked context.
-- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup.
-- **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers.
-- **Safety boundaries**: child agents must not run subagents unless their resolved builtin tools explicitly include `subagent`, must not invent intercom targets, and must escalate unapproved decisions.
-- **Intercom conventions**: when to ask vs send, and how parent-side supervisor/result delivery works through the native channel.
-- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
+- **Calls**: the common `subagent` calls, workflow script and resume shapes, and async waiting rules.
+- **Delegation rules**: when to delegate at all, what every child brief contains, one writer per worktree, fresh or forked context, and what to do when a lane fails.
+- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command: parallel review, review loop, parallel research, gather-context-and-clarify, parallel cleanup, and oracle consultation.
+- **Orchestration**: splitting work into lanes, review loops, finding disposition, and gate-failure triage.
+- **Lookups**: which `guide` section answers each rarer question, so the skill does not copy this reference.
 
 If you are writing an agent that has been asked to orchestrate subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.

package/docs/configuration.md

@@ -244,6 +244,14 @@ Set `enabled` to `false` (or remove the block) as a kill switch. In that state,
 
 Workflow script calls use background execution when the request omits `async`. Set `asyncByDefault` to `false` to restore foreground-by-default behavior for tool launches that still use the internal single-run primitive. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
 
+## `autoResume`
+
+```json
+{ "autoResume": false }
+```
+
+Default `true`. When a session is reopened (`pi -c`, `pi --session`, `/resume`) or reloaded (`/reload`), its own async workflows that a Pi exit or a reload interrupted in the last 24 hours are resumed once, without delaying session start; set `autoResume` to `false` to resume them only by hand. A one-shot `pi -p` run does not auto-resume, so it does not wait on the workflow. See [Workflows](workflows.md).
+
 ## `runnerLaunchers`
 
 ```json
@@ -387,8 +395,8 @@ Adds a short `active_subagents` section to the parent's system prompt while this
 
 `defaultTimeoutMs` sets the blocking window used when a `bg_wait` call omits `timeoutMs`; explicit call values win, followed by this setting, then the 30-minute fallback. `bg_wait` is the only registered wait tool. When the window elapses, the tool returns a non-error `window_elapsed` result with the still-active work identities, and that work keeps running. Set `enabled` to `false` to make direct calls return immediately instead of blocking. The default is enabled. You can also set `"waitTool": false`; set `PI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. The effective enabled and default-timeout values are passed explicitly to child runtimes. Headless `agent_end` auto-drain retains its own strict deadline and fails if required work remains unresolved. Invalid config or environment values fail instead of being coerced.
 
-Blocking `bg_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention. Use `bg_wait({ stopOnAttention: false })` only for run-to-completion flows that should wait through idle or long-thinking attention; supervisor/contact requests still stop the wait. A steer or follow-up the operator sends while a blocking wait is open also ends it, with a non-error `user_input` result listing the still-active work, so the message reaches the model without waiting out the window. In a long-lived interactive parent session, `bg_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Use it for provider, detached, or other background work without a native completion notification; ordinary async subagent runs notify the parent natively and do not need a wait subscription. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work. Native completion notifications wake the session through the Pi process that launched the run, while that process is still running; a session reopened in a new process does not get that wake and should read the result with `subagent({ action: "status" })`. `nonBlocking` subscriptions need a host with a UI context, such as interactive or RPC mode; plain SDK embedding without a UI context rejects them.
 
+Blocking `bg_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention, even when the run is still working normally, for example a `bash` command open longer than `activeNoticeAfterMs`; the result then says the run is still running. Use `bg_wait({ stopOnAttention: false })` for run-to-completion flows: it waits through idle time, a tool held open, or repeated tool failures, and still ends for a supervisor/contact request, a finished run, the timeout, user input, or abort. A steer or follow-up the operator sends while a blocking wait is open also ends it, with a non-error `user_input` result listing the still-active work, so the message reaches the model without waiting out the window. In a long-lived interactive parent session, `bg_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Use it for provider, detached, or other background work without a native completion notification; ordinary async subagent runs notify the parent natively and do not need a wait subscription. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work. A native completion notification goes to the Pi process that launched the run while that process is running; once it has exited, the session gets the result the next time it is open in any Pi. `nonBlocking` subscriptions need a host with a UI context, such as interactive or RPC mode; plain SDK embedding without a UI context rejects them.
 This is different from `waitTool.enabled=false`, which returns immediately without registering any future wake. Provider items remain available only to blocking fleet-wide waits; non-blocking subscriptions require one async or remembered detached foreground run id.
 
 ## `resultScanLogging`

package/docs/tool-reference.md

@@ -82,7 +82,7 @@ The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `
 | `options.context` | `fresh \| fork \| profile` | global or per-agent default, else `fresh` | Explicit `fresh` or `fork` overrides every workflow child. `profile` requires the selected agent's declared `defaultContext` and ignores config `defaultSubagentContext`; missing agent defaults fail. When omitted, [`defaultSubagentContext`](configuration.md#defaultsubagentcontext) wins over each agent's `defaultContext`; implicit fork falls back to fresh without a persisted parent session and leaf. Explicit fork is strict. Packaged `worker` defaults to `fresh`; packaged `oracle` and `advisor` default to `fork`. |
 | `model` | string | agent default | An exact `provider/id`; bare ids resolve only if unique, and agent names are not model ids. An unknown or ambiguous model fails with up to 5 closest registry ids to copy; `{action:"models"}` lists them all. A suffix such as `provider/id:high` (`off/minimal/low/medium/high/xhigh/max`) overrides agent thinking. The `thinking` field is only for `watchdog.configure`, ignored on dispatch. On the `claude-code` and `claude-code-writer` adapters the model is Claude Code's own alias or id, and the same suffix becomes its `--effort`, bounded by `subagents.maxThinking` and by an enforced `subagents.modelScope`. |
 | `options.missionId` | string | - | Attach a workflow, including each fire of `schedule.create`, to an existing project mission. Scheduled attachment uses ordinary lifecycle and retention rules. |
-| `options.reuseFrom` | string | - | Exact id of an async workflow run stopped by a runtime replacement (`workflow.stopCause: "runtime-replaced"`). An async relaunch of the same script in the same cwd, from any session, reuses that run's finished children and waits for its running ones; see [Workflows](workflows.md). |
+| `options.reuseFrom` | string | - | Exact id of an async workflow run stopped by a runtime replacement or whose Pi process exited (`workflow.stopCause: "runtime-replaced"` or `"owner-exited"`). An async relaunch of the same script in the same cwd, from any session, reuses that run's finished children and waits for its running ones; see [Workflows](workflows.md). |
 | `options.mission` | object/false | auto-create | Override the default enclosing mission with `{ title \| summary, objective?, goal?, budget?, labels? }`. Set exactly one non-empty `title` or `summary`; `objective` and `labels` are optional. `goal` may only be `true`, requires `budget.tokens`, and enables continuation notices. Pass `false` for an intentionally ephemeral workflow with no mission for it or its children and no `state` global. Explicit mission persistence failures are strict. |
 | `options.handoffPath` | string | - | Aggregate handoff manifest for `action: "worktree.discard"` or lane evidence actions, or optional explicit metadata for `action: "worktree.cleanup"`. |
 | `options.repo` | string | runtime cwd | Repository path for `action: "worktree.cleanup"`; required explicitly for apply. The configured worktree base filters candidates by their per-project folder under it but never discovers them. |
@@ -329,6 +329,7 @@ subagent({ action: "stop", id: "<run-id>" })
 subagent({ action: "resume", id: "<run-id>", message: "follow-up question after it pauses or finishes" })
 subagent({ action: "resume", id: "<run-id>", message: "follow-up for child 2", options: { index: 1 } })
 subagent({ action: "resume", id: "<nested-run-id>", message: "follow-up for a nested child" })
+subagent({ action: "resume", id: "<stopped-workflow-run-id>" })
 subagent({ action: "steer", id: "<run-id>", message: "guidance for the running child" })
 subagent({ action: "steer", id: "<run-id>", message: "check this after the current turn", options: { mode: "follow_up" } })
 subagent({ action: "steer", id: "<run-id>", message: "guidance for child 2", options: { index: 1, mode: "auto" } })
@@ -379,6 +380,7 @@ Commands remain owned by the child session. Normal completion with unfinished co
 - Completed external-job runs, including nested runs, can use the same `resume` action as a provider follow-up when the registered provider exposes `followUp(input)`. Running external-job parents fail closed with guidance to wait for completion. Unsupported providers fail with an update/reload message.
 - Revive starts a new child session from the old session context; it does not resume the live session, and it requires the chosen child to have a persisted `.jsonl` session file.
 - Direct revival takes an exclusive cross-process lease on the canonical session file until the new child finishes. A concurrent attempt fails before Pi is spawned and identifies the owning revived run; dead-owner leases are reclaimed only when staleness can be proved.
+- Without `message` (and without `index` or `chain`), `resume` on a top-level async workflow run that stopped because its session was replaced or its Pi process exited (`workflow.stopCause: "runtime-replaced"` or `"owner-exited"`) relaunches it once from the launch it saved, reusing its finished children, and its receipt starts with `Resumed workflow '<id>' as <new id>.`; a run that cannot be resumed is refused as `Cannot resume workflow '<id>': <reason>.` The session that owns the run also resumes it on its own when reopened or reloaded, unless [`autoResume`](configuration.md#autoresume) is off; see [Workflows](workflows.md).
 
 ### stop
 

package/docs/workflows.md

@@ -14,6 +14,8 @@ Packaged `worker` defaults to fresh context so implementation starts from its as
 
 Launch children in the background (`async` follows `asyncByDefault`, normally true) and consume each result at the point a later step depends on it. Native completion wakes the parent session, so the parent returns control instead of sleeping or polling. Use `async: false` only when the parent must block, not for final reviews or gates. When an oracle or advisor reaches an unknown that needs a decision, it asks through supervisor dialogue; use a one-shot oracle call only when one was requested.
 
+A background child awaited by an `async: false` workflow cannot receive a supervisor decision while its parent is blocked in that call. Its native `contact_supervisor` decision or interview request returns a tool error promptly, asking it to report the blocker and partial results and stop. The transport error is not a supervisor reply or approval. Use `async: true` for workflows whose children may need a decision. Progress updates remain non-blocking, and an explicit child `async: true` still returns its launch receipt without being awaited.
+
 Child-safety boundaries are enforced at runtime:
 
 - Child sessions do not receive the bundled `pi-subagents` skill.
@@ -31,8 +33,22 @@ Failed workflow details and async `status.json` include `workflow.failureKind` a
 
 When `/reload`, a session resume, or a pi-web project switch replaces the extension runtime, a running async workflow stops with `workflow.stopCause: "runtime-replaced"` in `status.json`, and its awaited async children keep running. Its in-process foreground children are stopped, including ones that detached to ask their supervisor. When the same workflow script is launched again with the same `args` in that session, a `runs.run` with the same key and params returns a child that already finished successfully without launching it, and waits for a child that is still running instead of starting another. Those results carry `reused: true`, their step and trace entry are marked `reused`, and the new run records `workflow.reusedFrom`. Failed and stopped children, and children that ran in-process, launch again. Reuse applies only when the newest run of that script and args in the session was stopped this way; a user stop or a completed run ends it. From another session, such as one that took over after a handoff, relaunch the same script as an async workflow with `options: { reuseFrom: "<stopped run id>" }`; the run must have stopped this way in the same cwd, and `args` may differ, because each child is still reused only when its key and params match.
 
+When the Pi process that ran an async workflow exits before the workflow finishes (a crash, a kill, or a machine restart), the stale-run check that runs when its session reopens, or when `options.reuseFrom` names the run, marks it failed with `workflow.stopCause: "owner-exited"`, and a relaunch reuses its finished children the same way. On any relaunch, `runs.steer` and `runs.host` calls run again and only `runs.run` results are reused, so a replayed check such as "tests passed" can be stale.
+
+A stopped run is continued by one relaunch only. While that relaunch exists, another relaunch of the same stopped run, by the same script or by `options.reuseFrom`, is refused with `workflow run '<id>' was resumed as <new id>; wait on it or stop it.` If that relaunch stops the same way, relaunch it instead: it carries the children of every run before it. If the Pi process that started the relaunch exits before the relaunch begins, the stopped run can be relaunched again.
+
+To continue a stopped run without sending its script again, resume it by id from the session that owns it: `subagent({ action: "resume", id: "<stopped run id>" })` with no `message`. Every async top-level workflow saves its launch (the script or named resource, its `args` and options) when it starts, and the resume relaunches that launch with `options.reuseFrom` set to the stopped run, in the stopped run's cwd, with no more authority than it had. A named resource is resolved again and must still have the same script. The new run records `workflow.resumeOrigin: { sourceRunId, attempt }`, where `attempt` counts the resumes that followed a Pi exit. Another session cannot resume the run by id; reopen the session that started it, or relaunch the same script with `options.reuseFrom`. When the run cannot be resumed this way (it started before launches were saved, was launched from `tasks` or `chain`, or its resource changed), the refusal says so; relaunch the same script by hand with `options: { reuseFrom: "<stopped run id>" }`.
+
+When the session that owns such a run is reopened or reloaded, the run is resumed this way automatically, once, if it was interrupted in the last 24 hours: for a Pi exit, measured from the last time the dead Pi process updated the run. Session start does not wait for the relaunch. A run that cannot be relaunched is named in its notice (`Not auto-resumed: …`, with how to continue by hand); a launch that fails after session start also posts one `Workflow <id> was not auto-resumed: <reason>.` message. Either way the run is not tried again. `/new` and forks do not resume the runs of the session they replaced. The `autoResume` setting turns this off; see [Configuration](configuration.md#autoresume).
+
+Starting Pi in a folder where another session's subagent runs were cut off by its Pi dying in the last 24 hours shows one info line per such session, such as ``2 subagent runs were interrupted in another session. Reopen it to resume them: `pi --session <id>` ``; it only points to that session, changes nothing in it, and is not sent to the model.
+
+The completion notice of a workflow stopped by a Pi exit or a runtime replacement has one line right after `Workflow run: <id>` that says what happens next: `Auto-resumed as <new id>.`, `Resumed as <new id>.` (resumed by id), `Relaunched as <new id>.` (relaunched with the same script or `options.reuseFrom`), `Not auto-resumed: <reason>.` followed by the way to continue by hand, or, when nothing continues it, `Resume by hand: subagent({ action: "resume", id: "<id>" })` (or the `options.reuseFrom` form when its launch cannot be resumed by id).
+
 After `/new`, `/resume`, or a fork in the same Pi process, the new session owns the async runs of the session it replaced, and of the sessions that one replaced. It can list, `bg_wait` on, steer, stop, and resume them, receives their completion notices, and answers their children's pending supervisor requests. Over RPC, a host can steer, interrupt, stop, resume, and inspect them, and sees them in the fleet and `subagent-async` snapshots. Startup and other Pi processes inherit nothing; `/reload` adds nothing new but keeps what the session already inherited. To relaunch a stopped workflow instead of controlling its children one by one, use `options.reuseFrom`.
 
+Once the Pi process that started a background single, parallel, or chain run has exited, the run is reported once to a Pi window that has its session open, whether it finished while Pi was closed or finishes later. A workflow's children are reported through their workflow.
+
 Pi core may print a generic `pi -ne` extension-load hint; that out-of-repo hint is not protocol-approved fallback. A verified compaction abort may continue the retained child once on its already resolved model; it does not authorize an execution-mode or model switch.
 
 ## Prompt shortcuts

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "pi-subagents",
-  "version": "0.81.0",
+  "version": "0.82.1",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "@js-temporal/polyfill": "0.5.1",
     "acorn": "8.18.0",
     "jiti": "2.7.0",
-    "undici": "8.10.2",
+    "undici": "8.12.3",
     "yaml": "2.8.3"
   },
   "peerDependencies": {

package/skills/council-mode/SKILL.md

@@ -9,10 +9,7 @@ Council mode is parent-supervised advice for a material decision with real trade
 
 The parent selects the roster, relays only curated claims, decides validity, and writes the memo. Advisors stay read-only and do not see peer transcripts by default.
 
-Before launch, read:
-
-- `skills/pi-subagents/references/execution-controls.md`
-- `skills/council-mode/references/pass-contracts.md`
+Before launch, read `skills/council-mode/references/pass-contracts.md`.
 
 ## Roster
 

package/skills/pi-subagents/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pi-subagents
 description: |
-  Technical guidance for operator-requested delegation to builtin or custom
-  subagents: bounded handoffs, parallel review, scripted workflows, async work,
-  forked context, isolation, and coordinated execution.
+  Delegate work to Pi subagents after the operator asks for it: one child,
+  parallel or scripted workflows, async runs, resume/steer/stop, review fanout,
+  and multi-lane or worktree orchestration.
 ---
 
 # Pi Subagents
@@ -14,111 +14,134 @@ instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
 available specialist does not independently authorize delegation.
 
 Once authorized, choose the smallest bounded shape that earns its token and
-elapsed-time overhead through concrete evidence, independent review,
-specialization, useful parallelism, or needed isolation. A single child is
-valid; writer, challenge, and review stages must each earn their overhead rather
-than becoming default ceremony. The parent keeps user intent, constraints,
-routing, arbitration, decisions, final acceptance, and publication authority,
-and may perform the work directly where it is the most efficient owner.
+elapsed-time overhead through evidence, independent review, specialization,
+useful parallelism, or isolation. A single child is valid. The parent keeps
+intent, routing, decisions, final acceptance, and publication authority, and
+does the work itself where that is cheaper.
+
+## Calls
+
+```typescript
+subagent({ agent: "worker", task: "<brief>" })                    // one child; async by default
+subagent({ workflow: "parallel", args: { tasks: [{ agent, task, cwd?, model? }] } })  // independent children
+subagent({ workflow: true })              // runs the one ```js workflow block in this same reply
+subagent({ workflow: "./lane.js", args }) // script file, path relative to the request cwd
+subagent({ action: "validate", workflow: "./lane.js" })          // check a script without launching
+subagent({ action: "status", id })        // options: { view: "fleet" } or { view: "transcript", index: 0 }
+subagent({ action: "resume", id, message })   // completed or paused child; returns a new run id
+subagent({ action: "steer", id, message })    // live async child
+subagent({ action: "stop", id })              // ends the run; not resumable
+subagent({ action: "interrupt", id })         // pauses the child's current turn
+subagent({ action: "list" })  ·  subagent({ action: "models" })
+subagent({ action: "guide", options: { topic: "<section address>" } })
+```
+
+Launches are async by default. Set `async: false` only when the parent must
+block; final reviews and gates stay async. After launching, keep doing safe
+independent work, or yield: native completion wakes this session. Do not sleep,
+poll, or call `bg_wait` for ordinary children. Use `bg_wait` only for provider
+or detached work that has no native notification and whose result this turn
+needs.
+
+## Workflow scripts
+
+Use a script when later steps depend on earlier results, or for keyed,
+retried, aggregated, or resumed children. Write one ```` ```js workflow ````
+block in the reply and call `subagent({ workflow: true })` in the same reply.
+For a long script, or when a `workflow: true` call reports the block missing,
+write it to a file and pass `workflow: "./path.js"`. On Claude 5.x models (Opus
+5.5, Sonnet 5.5, Fable 5.1), use the file whenever the turn already made a tool
+call: text after one reaches the session as a summary without the block. Calls in one reply run at
+the same time, so write the file in one reply and `validate` or launch it in
+the next.
+
+```js workflow
+const scan = await runs.run("scan", { label: "Map auth flow", agent: "scout", task: "..." });
+const reviews = await runs.all([
+  { key: "correctness", label: "Review auth correctness", agent: "reviewer", task: "... " + scan.output },
+  { key: "tests", label: "Review auth tests", agent: "reviewer", task: "..." },
+]);
+return reviews.map((review) => review.output);
+```
+
+- Scripts are statement bodies with an explicit `return`, top-level `await`,
+  and plain helpers. Nested async functions, arrows, and methods are rejected.
+- Every `runs.run` / `runs.all` item needs a stable `key`. Add a short
+  verb + behavior `label` unless the user gave one.
+- Bind files with `output: "plans/x.md"` (relative paths land in run
+  artifacts) and return `outputReference` or `artifactPaths`. A filename in
+  task text does not route output. Never send reports to the repo root.
+- `runs.lanes([{ key, stages: [...] }])` runs a predeclared plan: first stages
+  together, later stages in order per lane.
+
+Resuming a retained child:
+
+```js workflow
+let child = await runs.run("fix-1", { agent: "worker", task: "..." });
+child = await runs.run("fix-2", { resume: child.runId, task: "Apply these accepted findings: ..." });
+return child.output;
+```
+
+- Always resume the latest returned run id; every resume returns a new one.
+- Use a new stable key for every resume pass.
+- `resume` excludes `agent` and `gate`; the child keeps its agent, model, and tools.
+- Resume a completed child; steer a live one. Top-level `{ action: "resume" }` is detached.
+
+## Briefs
+
+Every child starts cold. Its task states: goal; repo, explicit `cwd`, and
+ref; authority and edit boundary; relevant files, decisions, and evidence;
+success criteria; validation; expected output; and when to stop or ask.
+Make parallel briefs differ by seam, evidence, and decision, not just an item
+number.
+
+## Rules
+
+- One writer per cwd or worktree. Parallelize reading, review, and
+  validation. `worktree: true` needs a clean checkout (untracked files count;
+  `.pi/subagents/` does not). For Pi extension repos, put lane worktrees
+  outside `~/.pi/agent/extensions`, for example `~/.pi/agent/worktrees`.
+- Reviewers use fresh context. Use `context: "fork"` only when the child needs
+  the parent's history; it requires a persisted parent session.
+- Children do not spawn subagents unless the parent delegated fanout and their
+  resolved `tools` include `subagent`.
+- A failed workflow, launch, prompt runtime, extension load, or child tool
+  setup blocks the lane. Stop, report the exact failure and run/worktree state,
+  verify a clean worktree or capture the partial diff, then retry the same way
+  once. Switching to `interactive_shell`, `pi -ne`, or another CLI needs owner
+  approval.
+- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+- Route workers and scouts to a fast capable tier, serious reviews to a strong
+  tier, and top reasoning only to bounded read-only critique. Exact model names
+  belong in user or project settings, not here.
+- `subagent`, `subagents_enable`, `subagent_supervisor`, `contact_supervisor`, and `structured_output` are model-only: call them as ordinary model tool calls. Codemode scripts cannot reach them through `tools.*`, `ALL_TOOLS`, or `searchTools`.
+- Receipts, CI, and review bots are evidence, not authority. Backlog, release,
+  and merge policy belong to the user's or project's own skill.
 
-Children do not spawn subagents unless the parent explicitly delegated fanout
-and their resolved `tools` allow `subagent`.
+## Look up the rest
 
-## Launch shape
+If only `subagents_enable` is visible, call it first; `subagent` and `guide`
+work from the next request. Read one section, not a whole topic:
 
-| Need | Use |
-| --- | --- |
-| One bounded task for one child | direct `{ agent, task }` |
-| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | a workflow script with `runs.run(...)` / `runs.all(...)` |
-| A broad plan split into visible narrow stages per lane | a workflow script with `runs.lanes([{ key, stages: [...] }])` |
-| Independent worktree or repository lanes | `references/multi-lane-orchestration.md` |
-| Council of advisors | `../council-mode/SKILL.md` |
-| Management, status, steering, authoring, or inspection | `action` |
-
-To launch a workflow script, write it as one ```` ```js workflow ```` fenced
-block in your reply, then call `subagent({ workflow: true, ... })` in the same
-reply. Use `workflow: "./path/to/script.js"` for a script file and
-`workflow: "<name>"` for a named resource.
-
-A workflow script is code-driven: `runs.run(...)` for keyed steps,
-`runs.all([...])` for fanout, plain JavaScript for branching and aggregation.
-Keep scripts portable: use top-level `await`, plain helpers, or explicit Promise
-chains, not nested async helpers. Legacy top-level `chain` / `tasks` inputs and
-durable `.chain.md` execution are inspection or migration material only, except
-that `disabledFeatures: ["workflow-scripts"]` replaces scripts with top-level
-`chain` and `tasks` (see [configuration](../../docs/configuration.md#chain-and-tasks-without-workflow-scripts)).
-
-Use `runs.lanes(...)` only inside a workflow script, not as a top-level mode,
-when a broad, predeclared plan benefits from visible per-lane stages; otherwise
-use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
-example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
-bounded, but do not add stages or ceremony just to satisfy this skill.
-
-When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
-supply a short verb + behavior display `label` derived from the task, unless
-the user supplied an explicit label; preserve that label. Keep the stable
-machine `key` independent (for example, `issue2011-writer` with
-`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
-items, not lane objects. Use stage-appropriate labels for reviews and retained-child
-follow-ups too (for example, `Review workflow steering`). Generate labels in
-the orchestrator while composing the launch—no extra model call, runtime
-generator, or schema change. Native direct `{ agent, task }` calls have no
-top-level `label` parameter; do not invent one or wrap a tiny single task in
-a workflow just to label it.
-
-Use async/background by default. Set `async:false` only when the parent must
-block. Final reviews, validation gates, oracle checks, and publication checks
-stay async.
-
-In an ordinary interactive session, yield after launching or triaging useful
-async lanes and let Pi wake the parent on completion; ordinary async subagents
-already have native completion notifications, so do not call `bg_wait()` merely
-because a child is active. Use blocking `bg_wait()` only for provider,
-detached, or other background work without a native notification when a
-headless/run-to-completion contract or a required same-turn artifact makes the
-result necessary before this turn ends. For
-“continue/orchestrate/work until done,” keep the lane board moving while a safe
-immediate action remains; if only async lanes are running, record the revisit
-trigger and yield.
-
-Package agents appear in `subagent({ action: "list" })`. External CLI/job agents
-use their own runner contract. Do not pass native Pi child options to them unless
-that runner explicitly supports the option.
-
-## Read the reference for the branch
-
-For exact API fields and worked examples, call `subagent({action:"guide",options:{topic:"tool-reference"}})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
-
-| Branch | Read |
+| Need | Guide section |
 | --- | --- |
-| Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
-| Execute single, scripted, async, scheduled, mission, forked, watchdog, oracle, or intercom workflows | `references/execution-controls.md` |
-| Review, validate, triage gate failures, or prepare delivery | `references/review-and-validation.md` |
-| Coordinate lanes, worktrees, repositories, or writer waves | `references/multi-lane-orchestration.md` |
-| List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
-| Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
-
-For an authorized complex delegated workflow, read `prompting-and-roles.md` and
-`execution-controls.md`, then load `review-and-validation.md` and
-`constraints-and-recipes.md` before launch or review.
-
-## Operating rules
-
-- Avoid duplicate scouts, overlapping writers, and vague prompts without a concrete deliverable.
-- Call `subagent`, `subagents_enable`, `subagent_supervisor`, `contact_supervisor`, and `structured_output` as ordinary model tool calls. They are model-only, so codemode scripts cannot reach them through `tools.*`, `ALL_TOOLS`, or `searchTools`.
-- Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
-- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
-- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
-- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
-- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. `worktree: true` refuses to launch unless the source checkout is clean (untracked files count; `.pi/subagents/` does not), so commit your own changes first or plan the lane without managed isolation. See `references/multi-lane-orchestration.md` for lane mechanics.
-- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
-- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
-- For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
-- Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
-- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- For Pi extension repos under `~/.pi/agent/extensions`, put lane worktrees outside extension auto-discovery, such as `~/.pi/agent/worktrees`.
-- Preserve capability ceilings, including child tool limits and allowed-agent restrictions.
-- Preserve parent authority and escalate unresolved choices.
-- Treat receipts, CI, review bots, and external-run records as evidence, not authority.
-- For backlog maintenance, releases, merge queues, or other public-repo mutation policy, load the matching user/project skill. This package defines delegation primitives, not private policy.
-- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+| Script API: `runs.*`, `state`, limits | `workflows/scripted-workflows` |
+| Typed gates, host commands, rolling fanout | `workflows/typed-post-run-checks-and-typed-steps`, `workflows/host-command-steps`, `workflows/advanced-rolling-child-runs` |
+| Budgets, timeouts, `baseRef`, `gate`, `output` | `tool-reference/execution-parameters`, `tool-reference/output-mode-details` |
+| Fresh or forked context | `tool-reference/fork-context-details` |
+| Resume, steer modes, stop, status | `tool-reference/retained-children`, `tool-reference/resume`, `tool-reference/steer`, `tool-reference/stop`, `tool-reference/status` |
+| Acceptance and review gates | `tool-reference/acceptance-gates` |
+| Worktrees and handoffs | `workflows/worktree-isolation` |
+| Child asks the parent (`contact_supervisor`) | `workflows/supervisor-coordination-child-asks-parent` |
+| Agent create, update, eject, disable, refine | `tool-reference/management-actions`, `agents/frontmatter-reference` |
+| Missions and schedules | `missions/missions`, `missions/schedules` |
+| Watchdog | `watchdog/when-it-runs`, `watchdog/choosing-a-model` |
+| Model overrides and profiles | `models/setting-defaults-and-overrides` |
+| Other projects in panes | `tool-reference/herdr-project-panes` |
+| Setup looks wrong | `subagent({ action: "doctor" })` |
+
+## References
+
+- Choosing roles, writing prompts, review/research/cleanup techniques, oracle → [prompting-and-roles.md](references/prompting-and-roles.md)
+- Several lanes, worktrees, repositories, staged fixes, review loops, finding and gate triage → [orchestration.md](references/orchestration.md)
+- Advisor council → [../council-mode/SKILL.md](../council-mode/SKILL.md)