pi-subagents 0.81.0 → 0.82.1

package/src/workflows/workflow-resume.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { normalizePublicSubagentExecution } from "../extension/public-execution.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
+import { ownsRun } from "../runs/shared/run-ownership.js";
+import { readStatus } from "../shared/utils.js";
+import { readWorkflowLaunchRecord } from "./workflow-launch-record.js";
+import { claimWorkflowResume, refusalSentence, relaunchByHandText, resumeByHandText } from "./workflow-resume-claim.js";
+import { workflowScriptDigest } from "./workflow-reuse.js";
+import { isRunId } from "./workflow-revival.js";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_OWNER_EXITED } from "./workflow-stop-cause.js";
+/** A run may be resumed again after at most this many resumes that followed Pi exits (auto-resume only). */
+const MAX_WORKFLOW_RESUME_ATTEMPTS = 3;
+export function workflowResumeRefusal(code, reason, runId) {
+    const byHand = code === "launch-missing" || code === "launch-invalid" || code === "structured" || code === "digest" || code === "authority"
+        ? relaunchByHandText(runId)
+        : code === "capacity" || code === "attempts" || code === "launch-failed" ? resumeByHandText(runId) : "";
+    return { code, reason, byHand };
+}
+/** The tool error for a resume by id; the resume form is not repeated to a caller that just tried it. */
+export function manualWorkflowResumeRefusalText(runId, refusal) {
+    return `Cannot resume workflow '${runId}': ${refusalSentence(refusal.reason, refusal.byHand === relaunchByHandText(runId) ? refusal.byHand : "")}`;
+}
+/**
+ * The run id a resume action relaunches: no message, task, chain or index, and an id naming a
+ * top-level workflow run. Anything else is a child resume.
+ */
+export function workflowResumeTargetId(asyncDirRoot, params) {
+    if (params.message !== undefined || params.task !== undefined || params.index !== undefined)
+        return undefined;
+    if (Array.isArray(params.chain) && params.chain.length > 0)
+        return undefined;
+    const id = params.id ?? params.runId;
+    if (!isRunId(id))
+        return undefined;
+    let status;
+    try {
+        status = readStatus(path.join(asyncDirRoot, id));
+    }
+    catch {
+        return undefined;
+    }
+    return status?.mode === "workflow" && status.parentWorkflowRunId === undefined ? id : undefined;
+}
+/**
+ * Checks a stopped workflow run can be resumed and claims it for a new run id. Synchronous and
+ * cheap: the launch itself happens in the executor.
+ * `newRunId` presets the new run's id: a reload claims a run again under the id of the launch it cancelled.
+ */
+export function prepareWorkflowResume(input) {
+    const { asyncDirRoot, sourceRunId, trigger } = input;
+    const refuse = (code, reason) => ({ ok: false, ...workflowResumeRefusal(code, reason, sourceRunId) });
+    const sourceAsyncDir = path.join(asyncDirRoot, sourceRunId);
+    // Only the session that owns the run (itself or one it replaced) may resume it, and nothing is
+    // written into another session's run, so this comes before the reconcile.
+    const stored = readStatus(sourceAsyncDir);
+    if (stored && !ownsRun(input.currentSessionId, stored.sessionId))
+        return refuse("not-owned", "it was started in another session; reopen that session to resume it");
+    // Session start has already reconciled this session's runs; a resume by id may come later.
+    if (trigger === "manual")
+        reconcileAsyncRun(sourceAsyncDir);
+    const status = readStatus(sourceAsyncDir);
+    if (!status || status.mode !== "workflow" || !isReusableWorkflowStopCause(status.workflow?.stopCause))
+        return refuse("not-interrupted", "not interrupted; pass message to revive one of its children");
+    // The attempt the resumed run records: only resumes that follow a Pi exit count.
+    const attempt = (status.workflow?.resumeOrigin?.attempt ?? 0) + (status.workflow?.stopCause === WORKFLOW_STOP_CAUSE_OWNER_EXITED ? 1 : 0);
+    if (trigger === "auto" && attempt > MAX_WORKFLOW_RESUME_ATTEMPTS)
+        return refuse("attempts", `${MAX_WORKFLOW_RESUME_ATTEMPTS} resumes already followed Pi exits`);
+    const read = readWorkflowLaunchRecord(sourceAsyncDir);
+    if (!read.ok)
+        return read.missing ? refuse("launch-missing", "launch.json is missing (the run started before launches were saved)") : refuse("launch-invalid", `launch.json is invalid: ${read.error}`);
+    const record = read.record;
+    if (record.source === "structured")
+        return refuse("structured", "launched from tasks/chain");
+    if (record.source === "script" && (typeof record.params.workflowScript !== "string" || workflowScriptDigest(record.params.workflowScript) !== record.scriptDigest)) {
+        return refuse("launch-invalid", "launch.json is invalid: its script does not match its scriptDigest");
+    }
+    const normalized = normalizePublicSubagentExecution(record.params);
+    if (!normalized.ok)
+        return refuse("launch-invalid", `launch.json is invalid: ${normalized.error}`);
+    const newRunId = input.newRunId ?? randomUUID();
+    const claim = claimWorkflowResume(sourceAsyncDir, { newRunId, trigger, now: input.now });
+    if (claim.kind === "resumed")
+        return refuse("claim-resumed", `resumed as ${claim.newRunId}; wait on it or stop it`);
+    if (claim.kind === "busy")
+        return refuse("claim-busy", `being resumed by pid ${claim.pid}`);
+    if (claim.kind === "unreadable")
+        return refuse("claim-busy", "its resume claim cannot be read; wait or remove it");
+    return {
+        ok: true,
+        prepared: {
+            sourceRunId,
+            sourceAsyncDir,
+            newRunId,
+            trigger,
+            params: {
+                ...record.params,
+                async: true,
+                reuseFrom: sourceRunId,
+                ...(status.admissionCapabilityCeiling ? { capabilityCeiling: status.admissionCapabilityCeiling } : {}),
+            },
+            expectedScriptDigest: record.scriptDigest,
+            resumeOrigin: { sourceRunId, attempt },
+        },
+    };
+}

package/src/workflows/workflow-reuse.d.ts

@@ -1,11 +1,11 @@
+import { type WorkflowResumeClaimOutcome } from "./workflow-resume-claim.ts";
 import { type WorkflowScriptChildResult } from "./scripted-workflow.ts";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-declare const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
-type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED;
-export declare function workflowRuntimeReplacedRelaunchNotice(runId: string): string;
+import { WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.ts";
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export declare const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export declare function runtimeReplacedAbortReason(): Error;
-export declare function workflowStopCause(reason: unknown): WorkflowStopCause | undefined;
+export declare function workflowStopCause(reason: unknown): typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED | undefined;
 export declare function workflowScriptDigest(script: string): string;
 /** Hash of the canonical launch params the script host uses to detect duplicate keys. */
 export declare function workflowChildFingerprint(params: Record<string, unknown>): string;
@@ -40,16 +40,22 @@ type WorkflowReuseMatch = {
     kind: "started";
     runId: string;
 };
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export declare function claimedWorkflowRunRefusal(runId: string, claim: Exclude<WorkflowResumeClaimOutcome, {
+    kind: "owner";
+}>, named: boolean): string;
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export declare function findWorkflowReuseSource(asyncDirRoot: string, sessionId: string, scriptDigest: string, argsDigest: string | undefined): WorkflowReuseSource | undefined;
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string): WorkflowReuseSource;
+export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string, claimOwnerRunId?: string): WorkflowReuseSource;
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export declare function matchWorkflowReuse(source: WorkflowReuseSource, key: string, fingerprint: string): WorkflowReuseMatch | undefined;
 export {};

package/src/workflows/workflow-reuse.js

@@ -2,14 +2,15 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
 import { readStatus } from "../shared/utils.js";
+import { workflowResumeClaimState } from "./workflow-resume-claim.js";
+import { isRunId } from "./workflow-revival.js";
 import { workflowRunParamsFingerprint } from "./scripted-workflow.js";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.js";
 const WORKFLOW_CHILD_JOURNAL_FILE = "workflow-children.jsonl";
-export function workflowRuntimeReplacedRelaunchNotice(runId) {
-    return `Async children that were still running keep running. Relaunching the same workflow script with the same args from this session reuses finished children and re-attaches to running ones; from another session, add options: { reuseFrom: "${runId}" }.`;
-}
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export function runtimeReplacedAbortReason() {
     return Object.assign(new Error("Workflow stopped because the extension session was replaced or reloaded."), { workflowStopCause: WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED });
@@ -67,9 +68,63 @@ function readWorkflowChildJournal(runId, workflowAsyncDir) {
     }
     return source;
 }
+const WORKFLOW_REUSE_CHAIN_MAX_LINKS = 16;
+/**
+ * The head run's journal plus the journals of the runs it was relaunched from (`workflow.reusedFrom`).
+ * A child's start record is written only once it gets a concurrency slot, so a key the head never
+ * reached is still in an earlier run's journal. For each key the newest run that recorded it wins. A
+ * status file is parsed, not validated, so a corrupt `reusedFrom` may be any JSON value.
+ */
+function readWorkflowReuseChain(asyncDirRoot, headRunId, headStatus) {
+    const source = readWorkflowChildJournal(headRunId, path.join(asyncDirRoot, headRunId));
+    const visited = new Set([headRunId]);
+    let next = headStatus.workflow?.reusedFrom;
+    for (let links = 0; isRunId(next) && links < WORKFLOW_REUSE_CHAIN_MAX_LINKS && !visited.has(next); links++) {
+        visited.add(next);
+        const asyncDir = path.join(asyncDirRoot, next);
+        let status;
+        try {
+            status = readStatus(asyncDir);
+        }
+        catch {
+            break;
+        }
+        if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== headStatus.workflow?.scriptDigest)
+            break;
+        const link = readWorkflowChildJournal(next, asyncDir);
+        for (const key of new Set([...link.started.keys(), ...link.settled.keys()])) {
+            if (source.started.has(key) || source.settled.has(key))
+                continue;
+            const started = link.started.get(key);
+            const settled = link.settled.get(key);
+            if (started)
+                source.started.set(key, started);
+            if (settled)
+                source.settled.set(key, settled);
+        }
+        next = status.workflow?.reusedFrom;
+    }
+    return source;
+}
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export function claimedWorkflowRunRefusal(runId, claim, named) {
+    const run = `${named ? "options.reuseFrom: workflow" : "Workflow"} run '${runId}'`;
+    if (claim.kind === "resumed")
+        return `${run} was resumed as ${claim.newRunId}; wait on it or stop it.`;
+    if (claim.kind === "busy")
+        return `${run} is being resumed by pid ${claim.pid}; wait for it.`;
+    return `${run} has a resume claim that cannot be read; wait or remove it.`;
+}
+function assertWorkflowRunNotClaimed(asyncDir, runId, named, claimOwnerRunId) {
+    const claim = workflowResumeClaimState(asyncDir);
+    if (claim.kind === "none" || (claim.kind !== "unreadable" && claim.newRunId === claimOwnerRunId))
+        return;
+    throw new Error(claimedWorkflowRunRefusal(runId, claim, named));
+}
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, argsDigest) {
     let runIds;
@@ -90,28 +145,36 @@ export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, a
         }
         if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== scriptDigest || status.workflow.argsDigest !== argsDigest)
             continue;
-        return status.workflow.stopCause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED ? readWorkflowChildJournal(runId, asyncDir) : undefined;
+        if (!isReusableWorkflowStopCause(status.workflow.stopCause))
+            return undefined;
+        assertWorkflowRunNotClaimed(asyncDir, runId, false);
+        return readWorkflowReuseChain(asyncDirRoot, runId, status);
     }
     return undefined;
 }
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd) {
+export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd, claimOwnerRunId) {
     // A user-supplied id: it must name one run directory, never a path.
-    const status = runId === path.basename(runId) && runId !== "." && runId !== ".." ? readStatus(path.join(asyncDirRoot, runId)) : null;
+    const runName = isRunId(runId);
+    if (runName)
+        reconcileAsyncRun(path.join(asyncDirRoot, runId));
+    const status = runName ? readStatus(path.join(asyncDirRoot, runId)) : null;
     if (!status)
         throw new Error(`options.reuseFrom: workflow run '${runId}' was not found.`);
     if (status.mode !== "workflow")
         throw new Error(`options.reuseFrom: run '${runId}' is not a workflow run.`);
-    if (status.workflow?.stopCause !== WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED)
-        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced, so its children cannot be reused.`);
+    if (!isReusableWorkflowStopCause(status.workflow?.stopCause))
+        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced or its Pi process exited, so its children cannot be reused.`);
     if (status.workflow.scriptDigest !== scriptDigest)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran a different workflow script.`);
     if (status.cwd !== cwd)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran in '${status.cwd}', not '${cwd}'.`);
-    return readWorkflowChildJournal(runId, path.join(asyncDirRoot, runId));
+    assertWorkflowRunNotClaimed(path.join(asyncDirRoot, runId), runId, true, claimOwnerRunId);
+    return readWorkflowReuseChain(asyncDirRoot, runId, status);
 }
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export function matchWorkflowReuse(source, key, fingerprint) {

package/src/workflows/workflow-revival.d.ts

@@ -9,6 +9,8 @@ export interface WorkflowKeyRevival {
     /** State of the latest revived run; undefined when its status is unreadable. */
     state?: AsyncStatus["state"];
 }
+/** A run directory name, never a path. */
+export declare function isRunId(value: unknown): value is string;
 /**
  * Links a detached revival to the workflow key of its source run when the source failed and is
  * an async workflow child or an earlier revival of one. Throws when the source status cannot be

package/src/workflows/workflow-revival.js

@@ -13,7 +13,8 @@ export const REVIVAL_ORIGIN_FILE = "workflow-revival-origin.json";
 /** Recording refuses a deeper link, so readers bounded by this always reach the chain's end. */
 const MAX_REVIVAL_DEPTH = 16;
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-function isRunId(value) {
+/** A run directory name, never a path. */
+export function isRunId(value) {
     return typeof value === "string" && value.length > 0 && value.length <= 255 && path.basename(value) === value && value !== "." && value !== "..";
 }
 function readLink(file) {

package/src/workflows/workflow-stop-cause.d.ts

@@ -0,0 +1,6 @@
+/** The extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
+export declare const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+/** Stale-run reconciliation found the Pi process that ran the workflow dead (crash, kill, reboot). */
+export declare const WORKFLOW_STOP_CAUSE_OWNER_EXITED = "owner-exited";
+export type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED | typeof WORKFLOW_STOP_CAUSE_OWNER_EXITED;
+export declare function isReusableWorkflowStopCause(cause: unknown): cause is WorkflowStopCause;

package/src/workflows/workflow-stop-cause.js

@@ -0,0 +1,8 @@
+// Leaf module with no imports, so any module can use it without an import cycle.
+/** The extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
+export const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+/** Stale-run reconciliation found the Pi process that ran the workflow dead (crash, kill, reboot). */
+export const WORKFLOW_STOP_CAUSE_OWNER_EXITED = "owner-exited";
+export function isReusableWorkflowStopCause(cause) {
+    return cause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED || cause === WORKFLOW_STOP_CAUSE_OWNER_EXITED;
+}

package/skills/pi-subagents/references/constraints-and-recipes.md

@@ -1,74 +0,0 @@
-# Pi Subagents: Constraints And Recipes
-
-This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
-
-## Important Constraints
-
-- **Explicit forking requires a persisted parent session.** If the current session
-  does not have a persisted session file or current leaf, explicit `context: "fork"`
-  fails. An agent-level `defaultContext: fork` is a preference: packaged `oracle`
-  and `advisor` fall back to `fresh` when those fork preconditions are not
-  met yet. Use `context: "fresh"` when you do not want a fork even after the parent
-  session exists.
-- **Packaged workers start fresh.** `worker` defaults to fresh context so its brief,
-  not the parent's unfinished agenda, controls the implementation. Pass explicit
-  `context: "fork"` when inherited conversation history is required.
-- **Forked runs inherit parent history.** They are branched threads, not fresh
-  filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
-- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
-  unless configured otherwise.
-- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
-- **Intercom asks are blocking.** A session can only maintain one pending outbound
-  ask wait state at a time.
-- **Keep conversational authority clear.** Advisory subagents should not silently
-  become second decision-makers.
-- **Respect the fixed authority policy.** `authorityPolicy` is a small `auto` / `confirm` / `forbid` map for supported operational actions. Worktree discard, destructive cleanup, and spawn-budget grants default to confirmation; stop, steer, and schedule creation remain automatic. Use `worktree.discard` with the durable `handoffPath`; confirm-required actions refuse safely without an interactive UI and retained paths include manual Git recovery commands.
-
-Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `bg_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `session` (default), `project`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Per-run `artifacts: false` disables artifact capture for that launch. Async status and result artifacts include `lifecycleArtifactVersion` and fields such as `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Prefer these artifacts and `status` views over scraping terminal output.
-
-### Keep report artifacts out of the repository root
-
-Treat lane reports, review notes, council pass reports, and gate logs as scratch unless the user explicitly asks to keep them. Prefer `output: false` and the aggregate workflow result for short reports. When a later step needs a file, use the runtime-managed output artifact by setting a stable child key plus a relative `output` path such as `plans/deploy.md`; relative child outputs are saved under the run artifact directory, not the project root. Do not put `reports/...`, `*-report.json`, or similar repo-root paths in child task text.
-
-For durable evidence, copy only the final summary to session memory, a PR body/comment, a mission artifact, or a user-approved docs path outside the repo. After the PR, issue, or gate reaches a terminal state, delete or move scratch reports from the active worktree before reporting completion. Keep a project `.gitignore` entry for ad-hoc report patterns only as a safety net; it is not the cleanup mechanism.
-
-## Best Practices
-
-- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) is the composition surface for JavaScript control flow and data-dependent branching. Use `async: false` only when the parent must block. See `references/execution-controls.md` → Async/background for wait semantics.
-- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside a workflow script; use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling flows. See [`execution-controls.md`](execution-controls.md#parallel-sequential-lanes).
-- Keep one writer per cwd/worktree. Parallelize reading, review, and validation; concurrent writers need isolated worktrees. Give every child a cold-start packet with its goal, target/ref, authority, context, success criteria, validation, output, and stop rules.
-- Keep tasks narrow and standalone; do not rely on issue numbers, broad globs, or supervisor round-trips to supply missing context.
-- Keep authority with the parent. Escalate unapproved product, scope, architecture, merge, credential, or release decisions; checks, receipts, and review bots are evidence, not authority.
-- Use `fresh` context for adversarial review. `fork` is a persisted, history-inheriting branch; see `references/execution-controls.md` for its preconditions.
-- Use a same-session oracle follow-up only when its first answer leaves a material tradeoff. Treat `needs_attention` as a control signal, not failure, and do not interrupt a child merely because it is quiet during tools, tests, or reasoning.
-- Use `/name` when intercom targeting needs a stable session name.
-
-## Workflow selection
-
-This reference keeps cross-cutting policy and failure handling. Load the matching domain reference for detail:
-
-| Need | Read |
-| --- | --- |
-| Execution syntax, lifecycle, async/wait, missions, controls, watchdog, or worktrees | [`references/execution-controls.md`](execution-controls.md) |
-| Role choice, prompt contracts, review/research/cleanup techniques, or model tiering | [`references/prompting-and-roles.md`](prompting-and-roles.md) |
-| Fresh review, validation, gate failures, finding disposition, and final delivery checks | [`references/review-and-validation.md`](review-and-validation.md) |
-| Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
-| Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
-
-After delegation is operator-authorized, choose the smallest recipe that earns
-its overhead. Recipes select a shape; they do not authorize delegation:
-
-- **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
-- **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
-- **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
-
-## Error Handling
-
-- **Unknown agent:** the error lists the available agents and the directories searched; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
-- **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
-- **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
-- **Missing session file for a fork:** persist the parent session before using `context: "fork"`.
-- **Intercom already waiting for a reply:** resolve the pending ask before starting another.
-- **Parallel output-path conflict:** give each task a distinct output path, or disable output where no artifact is needed.
-- **Worktree launch failure:** ensure the git tree is clean and task cwd overrides match the shared cwd.
-- **Child fails before starting:** inspect `subagent({ action: "status", id: "..." })`, artifact metadata, output logs, and `doctor`; loader errors usually appear in child logs.