@agwab/pi-workflow 0.2.1 → 0.4.0

package/dist/workflow-web-source.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { appendFile, mkdir, readFile, readdir, rename, writeFile, } from "node:fs/promises";
 import { isIP } from "node:net";
 import { dirname, resolve } from "node:path";
+import { compactStrings } from "./strings.js";
 export const WORKFLOW_WEB_SOURCE_CACHE_SCHEMA = "workflow-web-source-cache-v1";
 export const WORKFLOW_WEB_SOURCE_INDEX_SCHEMA = "workflow-web-source-index-v1";
 export const WORKFLOW_WEB_SOURCE_INDEX_EVENT_SCHEMA = "workflow-web-source-index-event-v1";
@@ -22,7 +23,7 @@ export const DEFAULT_WORKFLOW_WEB_SECURITY_POLICY = {
     allowPrivateHosts: false,
     cacheRawProviderPayloads: false,
 };
-const SENSITIVE_QUERY_PARAM_PATTERN = /(^|[-_])(access[-_]?token|auth|code|credential|key|password|secret|session|signature|sig|token)([-_]|$)/i;
+const SENSITIVE_QUERY_PARAM_PATTERN = /(^|[-_])(access[-_]?token|auth|code|credential|key|password|secret|session|session[-_]?id|sessionid|signature|sig|sid|jwt|token)([-_]|$)/i;
 const PRIVATE_HOST_PATTERNS = [
     /^localhost$/i,
     /^127\./,
@@ -165,7 +166,7 @@ export function createWorkflowWebSource(options) {
         redactedUrl,
         urlKey: sourceUrlCacheKey(options.url),
         domain,
-        ...(options.title ? { title: options.title } : {}),
+        ...(options.title ? { title: redactInlineSecrets(options.title) } : {}),
         ...(options.provider ? { provider: options.provider } : {}),
         contentHash,
         text: options.text,
@@ -355,15 +356,12 @@ export function extractTextFromToolResult(result) {
     const content = result.content;
     if (!Array.isArray(content))
         return "";
-    return content
-        .map((entry) => {
+    return compactStrings(content.map((entry) => {
         if (!isRecord(entry))
             return "";
         const text = entry.text;
         return typeof text === "string" ? text : "";
-    })
-        .filter(Boolean)
-        .join("\n\n");
+    }), { trim: false, unique: false }).join("\n\n");
 }
 export function extractTitleFromToolResult(result) {
     if (!isRecord(result))
@@ -446,7 +444,7 @@ function sourceToIndexEntry(source) {
         redactedUrl: source.redactedUrl,
         ...(source.urlKey ? { urlKey: source.urlKey } : {}),
         domain: source.domain,
-        ...(source.title ? { title: source.title } : {}),
+        ...(source.title ? { title: redactInlineSecrets(source.title) } : {}),
         contentHash: source.contentHash,
         textChars: source.textChars,
         ...(source.provider ? { provider: source.provider } : {}),
@@ -526,19 +524,32 @@ function snippetForTerms(options) {
             return right.score - left.score;
         return right.matchedTerms.length - left.matchedTerms.length;
     })[0];
-    const raw = redactInlineSecrets(options.text.slice(best.start, best.end));
-    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, options.maxChars);
+    const consumed = consumeAnchoredSnippet({
+        text: options.text,
+        anchorStart: best.anchorStart,
+        anchorEnd: best.anchorEnd,
+        maxChars: options.maxChars,
+        budget: options.budget,
+    });
+    const returnedWindowNorm = normalizeForSearch(options.text.slice(consumed.sourceStart, consumed.sourceEnd)).normalized;
+    const matchedTerms = needles
+        .filter((term) => returnedWindowNorm.includes(term.normalized))
+        .map((term) => term.raw);
+    const missingTerms = needles
+        .filter((term) => !returnedWindowNorm.includes(term.normalized))
+        .map((term) => term.raw);
     return {
-        status: "matched",
+        status: consumed.status,
         matchType: "terms",
-        quote: consumed.text,
-        startOffset: best.start,
-        endOffset: best.end,
-        visibleChars: consumed.text.length,
-        matchedTerms: best.matchedTerms,
-        missingTerms: best.missingTerms,
-        coverageRatio: best.matchedTerms.length / Math.max(1, needles.length),
+        quote: consumed.quote || undefined,
+        startOffset: consumed.sourceStart,
+        endOffset: consumed.sourceEnd,
+        visibleChars: consumed.visibleChars,
+        matchedTerms,
+        missingTerms,
+        coverageRatio: matchedTerms.length / Math.max(1, needles.length),
         candidateOnly: true,
+        truncated: consumed.truncated || undefined,
     };
 }
 function scoreTermWindow(text, matchStart, matchEnd, maxChars, terms) {
@@ -559,6 +570,8 @@ function scoreTermWindow(text, matchStart, matchEnd, maxChars, terms) {
     return {
         start,
         end,
+        anchorStart: matchStart,
+        anchorEnd: matchEnd,
         matchedTerms,
         missingTerms,
         score: matchedTerms.length * 1_000 + occurrenceScore,
@@ -631,20 +644,76 @@ const SOURCE_READ_STOPWORDS = new Set([
     "without",
 ]);
 function snippetForMatch(options) {
-    const matchLength = Math.max(0, options.end - options.start);
-    const slack = Math.max(0, options.maxChars - matchLength);
-    const before = Math.floor(slack / 2);
-    const snippetStart = Math.max(0, options.start - before);
-    const snippetEnd = Math.min(options.text.length, snippetStart + options.maxChars);
-    const raw = redactInlineSecrets(options.text.slice(snippetStart, snippetEnd));
-    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, options.maxChars);
+    const consumed = consumeAnchoredSnippet({
+        text: options.text,
+        anchorStart: options.start,
+        anchorEnd: options.end,
+        maxChars: options.maxChars,
+        budget: options.budget,
+    });
     return {
-        status: "matched",
+        status: consumed.status,
         matchType: options.matchType,
-        quote: consumed.text,
+        quote: consumed.quote || undefined,
         startOffset: options.start,
         endOffset: options.end,
+        visibleChars: consumed.visibleChars,
+        truncated: consumed.truncated || undefined,
+    };
+}
+function consumeAnchoredSnippet(options) {
+    const maxChars = Math.max(0, Math.floor(options.maxChars));
+    const remainingBefore = Math.max(0, options.budget.limit - options.budget.used);
+    const visibleLimit = Math.max(0, Math.min(maxChars, remainingBefore));
+    const anchorStart = Math.max(0, Math.min(options.text.length, Math.floor(options.anchorStart)));
+    const anchorEnd = Math.max(anchorStart, Math.min(options.text.length, Math.floor(options.anchorEnd)));
+    const anchorLength = Math.max(0, anchorEnd - anchorStart);
+    if (visibleLimit <= 0) {
+        return {
+            status: "truncated",
+            quote: "",
+            visibleChars: 0,
+            sourceStart: anchorStart,
+            sourceEnd: anchorStart,
+            truncated: true,
+        };
+    }
+    let sourceStart;
+    let sourceEnd;
+    let status = "matched";
+    if (anchorLength > visibleLimit) {
+        sourceStart = anchorStart;
+        sourceEnd = Math.min(options.text.length, sourceStart + visibleLimit);
+        status = "truncated";
+    }
+    else {
+        const slack = Math.max(0, visibleLimit - anchorLength);
+        sourceStart = Math.max(0, anchorStart - Math.floor(slack / 2));
+        sourceEnd = Math.min(options.text.length, sourceStart + visibleLimit);
+        if (sourceEnd < anchorEnd) {
+            sourceEnd = anchorEnd;
+            sourceStart = Math.max(0, sourceEnd - visibleLimit);
+        }
+        else if (sourceEnd === options.text.length) {
+            sourceStart = Math.max(0, sourceEnd - visibleLimit);
+        }
+    }
+    const raw = redactInlineSecrets(options.text.slice(sourceStart, sourceEnd));
+    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, visibleLimit);
+    // Redaction can expand secrets. Promote only when the redacted anchor
+    // itself no longer fits; clipping trailing context can remain a match.
+    const redactedThroughAnchorLength = consumed.truncated
+        ? redactInlineSecrets(options.text.slice(sourceStart, Math.min(sourceEnd, anchorEnd))).length
+        : 0;
+    const anchorTruncated = status === "truncated" || redactedThroughAnchorLength > visibleLimit;
+    const truncated = status === "truncated" || consumed.truncated;
+    return {
+        status: anchorTruncated ? "truncated" : status,
+        quote: consumed.text,
         visibleChars: consumed.text.length,
+        sourceStart,
+        sourceEnd,
+        truncated,
     };
 }
 function normalizeForSearch(text) {
@@ -672,7 +741,15 @@ function normalizeForSearch(text) {
             map.push(index);
         }
     }
-    return { normalized: normalized.trim(), map };
+    while (normalized.startsWith(" ")) {
+        normalized = normalized.slice(1);
+        map.shift();
+    }
+    while (normalized.endsWith(" ")) {
+        normalized = normalized.slice(0, -1);
+        map.pop();
+    }
+    return { normalized, map };
 }
 function nearbySnippet(text, needle, maxChars) {
     const index = text.indexOf(needle);
@@ -769,7 +846,9 @@ function sourceIndexEntryFromUnknown(value) {
         redactedUrl: value.redactedUrl,
         ...(typeof value.urlKey === "string" ? { urlKey: value.urlKey } : {}),
         domain: value.domain,
-        ...(typeof value.title === "string" ? { title: value.title } : {}),
+        ...(typeof value.title === "string"
+            ? { title: redactInlineSecrets(value.title) }
+            : {}),
         contentHash: value.contentHash,
         textChars: Number(value.textChars),
         ...(typeof value.provider === "string" ? { provider: value.provider } : {}),
@@ -907,7 +986,7 @@ function redactInlineSecrets(value) {
 function redactInlineSecretsNoUrls(value) {
     return value
         .replace(/(authorization|cookie|set-cookie):\s*[^\n\r]+/gi, "$1: REDACTED")
-        .replace(/(token|secret|password|api[-_]?key)=([^\s&]+)/gi, "$1=REDACTED")
+        .replace(/(token|secret|password|api[-_]?key|jwt|sid|sessionid|session[-_]?id)=([^\s&]+)/gi, "$1=REDACTED")
         .replace(/\/Users\/[^\s:'")]+/g, "/Users/REDACTED");
 }
 function isRecord(value) {

package/docs/usage.md

@@ -114,9 +114,11 @@ For reusable workflow authoring, `workflow-guide` includes validated scaffold bu
 | `/workflow show <run-id-or-workflow-name>` | If the ref starts with `workflow_`, show run details; otherwise show the raw workflow spec. |
 | `/workflow logs <run-id> [task-id] [lines]` | Print captured logs for a workflow task. Defaults to `task-1`. |
 | `/workflow wait <run-id> [timeout-ms]` | Poll until the run finishes or the optional timeout elapses. |
+| `/workflow stop <run-id>` | Interrupt a non-terminal run, best-effort interrupt active subagents, mark unfinished tasks interrupted, and stop the local supervisor watch. Use `/workflow resume <run-id>` if you want to restart unfinished work later. |
 | `/workflow resume <run-id>` | Resume a failed, interrupted, or resumable blocked run (including dynamic approval blocked in headless mode): completed tasks are preserved; failed/interrupted/skipped or resumable blocked tasks reset to pending and reschedule. Loop workflows are not supported yet. |
+| `/workflow stop <run-id>` | Stop a non-terminal run: best-effort interrupt of active subagent workers, then mark unfinished tasks `interrupted`. Completed task artifacts are preserved, and the stopped run can be restarted later with `/workflow resume` (resumed tasks start fresh sessions). |
 
-Not implemented: `/workflow continue` and `/workflow delegate`. Use `status`, `show`, `logs`, `wait`, `resume`, and `pi-workflow inspect` for text/CLI inspection. The standalone CLI also offers `pi-workflow supervise <run-id>|--all` to drive scheduling from outside a Pi session (unfinished failed/interrupted or resumable blocked runs within the last 7 days are announced at session start with resume hints).
+Not implemented: `/workflow continue` and `/workflow delegate`. Use `status`, `show`, `logs`, `wait`, `stop`, `resume`, and `pi-workflow inspect` for text/CLI inspection. The standalone CLI also offers `pi-workflow supervise <run-id>|--all` to drive scheduling from outside a Pi session (unfinished failed/interrupted or resumable blocked runs within the last 7 days are announced at session start with resume hints).
 
 ### Workflow board controls
 
@@ -198,13 +200,30 @@ For lower-latency runs, pass `--thinking low` explicitly:
 
 This is an opt-in fast mode. Package defaults remain conservative until a separate holdout evaluation provides enough evidence to change them. Current evidence is limited but encouraging for explicit fast runs: the 2026-07-02 `deep-research` combined gate on P1/P2/P3-style prompts resolved non-support tasks to `low`, completed selected valid runs in about 15-17 minutes, passed the strict gate 9/9, and had zero source-ref join failures across those 9 runs. Treat this as a speed option, not proof that every workflow should default to `low`.
 
+### Opt-in batched verification for deep-research
+
+`deep-research` still verifies one claim per verifier task by default. For controlled runs where verifier batching is acceptable, use the explicit path-ref variant:
+
+```text
+/workflow validate ./workflows/deep-research/batched-verification.spec.json
+/workflow run ./workflows/deep-research/batched-verification.spec.json "Research this repository and verify the key claims."
+```
+
+This path-ref variant keeps the same planner/research/normalization/audit/final stages, but feeds `verify-claims` from `verification-batches` and requires each verifier task to return one `results[]` row per claim id. It is not registered as an official bundled workflow name and does not change package defaults. Treat speed/cost results as task-specific: claim a win only when the run's audit reports zero missing/duplicate/invalid verifier rows, zero sourceRef join failures, and no verified-floor regression.
+
+### Verification outcome ontology
+
+The package exports a small verification outcome vocabulary for workflows that verify source-backed claims: `verified`, `partially_supported`, `unsupported`, `conflicting`, and `verification_blocked`. Bundled workflow helpers must use bundle-local shims that stay in parity with the package export, because helper imports are bundled from the workflow spec directory. `verification_blocked` means the verifier could not evaluate the claim because required evidence, source access, tool execution, or policy constraints blocked verification. It is not a weaker form of `verified`, never counts toward verified floors, and should remain visible in audit summaries so operators can decide whether to rerun, change source access, or treat the claim as unresolved.
+
+Adopt this vocabulary only for evidence-verification outcomes. Do not force it onto workflow-control, finding-disposition, or ship-readiness verdicts such as `KEEP`, `DROP`, `READY`, or `NEEDS_WORK`. Deep-diff-review revival is not part of this ontology change.
+
 ### Run-scoped web-source cache
 
 Prefer normalized workflow web tools in new workflows:
 
 - `workflow_web_search` returns compact candidate cards.
 - `workflow_web_fetch_source` caches one or more URLs and returns compact source cards with `sourceRef` values; pass `urls: [...]` or `sources: [{ url, title }]` to batch several fetches in one tool call.
-- `workflow_web_source_read` reads narrow exact/fuzzy/term-matched evidence snippets by `sourceRef`; pass `queries: [...]` or `reads: [...]` to batch several snippets from the same source in one tool call, or `claim` + distinctive `terms` when the exact quote is unknown. Term/claim reads return candidate metadata (`matchedTerms`, `missingTerms`, `coverageRatio`) rather than a proof verdict.
+- `workflow_web_source_read` reads narrow exact/fuzzy/term-matched evidence snippets by `sourceRef`; pass `queries: [...]` or `reads: [...]` to batch several snippets from the same source in one tool call, or `claim` + distinctive `terms` when the exact quote is unknown. Term/claim reads return candidate metadata (`matchedTerms`, `missingTerms`, `coverageRatio`) rather than a proof verdict. Snippet windows are anchored to the match: a result may report `status: "truncated"` when the per-task visible budget or `maxChars` clips the window (the returned quote still starts at the match), and `status: "budget_exhausted"` when no visible budget remains; both include a `next` hint suggesting smaller queries or a fresh task.
 
 The normalized cache is stored under the workflow run directory:
 
@@ -214,7 +233,11 @@ The normalized cache is stored under the workflow run directory:
 
 Do not instruct agents to read that directory directly; source cards intentionally expose only opaque refs and short previews. The cache also writes an append-only index ledger plus same-URL fetch locks/negative-cache files so duplicate lookup and deterministic terminal failures can recover across parallel worker processes. Custom extension `fetch_content` providers are treated as trusted fetchers and are disabled under the default private-host policy; use the default safe fetch path or opt into trusted private-host behavior only for controlled providers. Legacy workflow tasks that still use `fetch_content` keep the older run-scoped file cache under `.pi/workflows/<run-id>/source-cache/fetch-content/`. Set `PI_WORKFLOW_FETCH_CONTENT_CACHE=0` to disable that legacy fetch cache for a run.
 
-Benchmark note: cache-enabled runs are a distinct cohort from older uncached runs. Do not compare wall-clock numbers directly unless the task set, model, and cache policy are controlled and recorded.
+To reduce worker context pressure for legacy `fetch_content` tasks, the bundled
+workflow fetch wrapper caps inline response text while preserving full stored
+source content. Override with `PI_WORKFLOW_FETCH_CONTENT_INLINE_CHARS=<n>` or
+disable the inline cap with `PI_WORKFLOW_FETCH_CONTENT_INLINE_CHARS=0` when you
+intentionally need the provider's full inline response.
 
 ## Bundled workflows
 
@@ -284,7 +307,15 @@ Dynamic workflows keep JSON as the source of truth while allowing trusted bundle
 }
 ```
 
-Controller/helper/nested workflow refs must be bundle-local `./...` paths. Nested workflow specs are intentionally self-contained at their own directory level: refs inside a nested spec may point to files in that nested spec's subtree, but not to parent-level shared files via `../`. Put shared helpers/schemas under each nested workflow subtree or expose them through the parent controller/helper layer. Controller/helper code is trusted Node.js code for orchestration and timeout isolation, not a security sandbox. Generated agents are real workflow tasks: `ctx.agent({ id, agent, prompt, tools })` inserts a deterministic `stageId.id` task into `compiled.json` and `run.json`, persists a request hash in `dynamic/events.jsonl`, and replays fail-closed if the same id later changes request shape. On resume, controllers must re-issue previously recorded `ctx.agent`, `ctx.helper`, and `ctx.workflow` operations in the same order before issuing new operations; omitted or out-of-order replay fails closed with an explicit replay-invariant error. Use `ctx.parallel([() => ctx.agent(...), ...])` for dynamic fan-out; the runtime records queued sibling generation ops before the controller suspends, and non-suspension operation failures make the controller fail closed. Generated dependency cycles are rejected. `ctx.helper(name, input)` can call only helpers declared in `dynamic.helpers`; pure/retry-safe helpers may set `idempotent: true` so a crash after `helper.started` but before `helper.completed` can retry the helper instead of permanently failing closed. `ctx.workflow(name, input)` can call only nested specs declared in `dynamic.workflows`.
+Controller/helper/nested workflow refs must be bundle-local `./...` paths. Nested workflow specs are intentionally self-contained at their own directory level: refs inside a nested spec may point to files in that nested spec's subtree, but not to parent-level shared files via `../` — put shared helpers/schemas under each nested workflow subtree or expose them through the parent controller/helper layer. Controller/helper code is trusted Node.js code for orchestration and timeout isolation, not a security sandbox.
+
+Controller context rules:
+
+- Generated agents are real workflow tasks: `ctx.agent({ id, agent, prompt, tools })` inserts a deterministic `stageId.id` task into `compiled.json` and `run.json`, persists a request hash in `dynamic/events.jsonl`, and replays fail-closed if the same id later changes request shape.
+- On resume, controllers must re-issue previously recorded `ctx.agent`, `ctx.helper`, and `ctx.workflow` operations in the same order before issuing new operations; omitted or out-of-order replay fails closed with an explicit replay-invariant error.
+- Use `ctx.parallel([() => ctx.agent(...), ...])` for dynamic fan-out; the runtime records queued sibling generation ops before the controller suspends, and non-suspension operation failures make the controller fail closed. Generated dependency cycles are rejected.
+- `ctx.helper(name, input)` can call only helpers declared in `dynamic.helpers`; pure/retry-safe helpers may set `idempotent: true` so a crash after `helper.started` but before `helper.completed` can retry the helper instead of permanently failing closed.
+- `ctx.workflow(name, input)` can call only nested specs declared in `dynamic.workflows`.
 
 Dynamic outputs should be compact typed artifacts. The controller returns normal workflow sections through `{ control, analysis, refs }`; generated child agents must return the same `<control>`, `<analysis>`, `<refs>` protocol as other artifact-graph tasks. When a controller result includes `outputTasks`/`outputTaskIds` (the built-in decision loop sets this from accepted `synthesize` actions), downstream `from: "<dynamic-stage>"` reducers also receive those exported task artifacts as stable sources such as `<dynamic-stage>.output`. Runtime state is stored under `.pi/workflows/<run-id>/dynamic/`:
 
@@ -301,13 +332,7 @@ Budgets bound controller behavior (`maxAgents`, `maxConcurrency`, `maxRuntimeMs`
 
 ### DAG authoring
 
-Top-level `artifactGraph.stages` is DAG-capable by default. A nested `type: "dag"` is a workflow/control container, not a leaf subagent task: it must contain child `stages` and should not have its own prompt. The runtime lowers public graph relationships onto the internal dependency scheduler while preserving artifact/data boundaries.
-
-Keep these layers distinct:
-
-- **Workflow layer**: graph/control/data-dependency semantics such as `id`, `from`, `after`, `sourcePolicy`, `sourceProjection`, scheduling, and artifacts.
-- **Subagent layer**: model-backed execution patterns such as `single`, `foreach`, `reduce`, and loop child stages.
-- **Support layer**: deterministic local helper execution through `support: { uses, options }`.
+Top-level `artifactGraph.stages` is DAG-capable by default. A nested `type: "dag"` is a workflow/control container, not a leaf subagent task: it must contain child `stages` and should not have its own prompt. The runtime lowers public graph relationships onto the internal dependency scheduler while preserving artifact/data boundaries. Keep the authoring layers described under "Stage model" distinct when composing DAGs.
 
 DAG rules:
 
@@ -405,6 +430,28 @@ Use workflow-local JSON Schema files when the control plane needs stronger valid
 
 The built-in validator supports the subset used by bundled workflows: `type`, `required`, `properties`, `items`, `enum`, `const`, length/item/number bounds, `additionalProperties`, and simple `allOf`/`anyOf`/`oneOf`. Unsupported keywords such as `$ref`, `$defs`, `definitions`, and `pattern` are rejected when the workflow is loaded.
 
+### Opt-in partial output for streaming foreach
+
+A producer stage can declare stable array paths that may be published before terminal completion:
+
+```json
+"output": {
+  "partial": { "paths": ["$.items"] }
+}
+```
+
+A downstream `foreach` may then opt in on the matching `from` edge:
+
+```json
+"from": {
+  "source": "plan",
+  "path": "$.items",
+  "streaming": { "enabled": true, "minChunk": 2 }
+}
+```
+
+The runtime accepts only partial items for declared paths. Published partial items must be final/stable JSON objects with a non-empty string `id`; the producer may emit them as `<partial-control>{"schema":"workflow-partial-output-v1","path":"$.items","items":[...]}</partial-control>` before the final workflow output. If the final `control.json` later changes a published item with the same id, the streaming foreach placeholder blocks fail-closed. Downstream reducers still wait for the foreach placeholder plus all generated item tasks, so partial output overlaps item work without relaxing final fan-in gates.
+
 ## Support helpers
 
 A support node runs local helper code inline instead of launching a subagent. It is declared by adding a `support` object; it does not use a separate `type` value:
@@ -542,6 +589,15 @@ Authoring checklist:
 7. Add JSON output contracts for model-produced data that later stages depend on.
 8. Run `/workflow validate <workflow-or-file>` before using the workflow.
 
+### Roles
+
+A workflow can declare reusable role context under top-level `roles`. Compiled role text is injected into subagent task prompts as a `# Role Context` block, and `/workflow roles <workflow>` shows the compiled result per role. Role fields:
+
+- `fromAgent`: extract sections from a discoverable Pi agent's markdown body. By default only safe knowledge sections are included (`Core Principles`, `Domain Expertise`, `Safety Review`, `Rules`, `Research Manifest`); orchestration and output-format sections are always excluded.
+- `includeSections` / `excludeSections`: override which agent sections are extracted.
+- `prompt`: literal role text, appended after any extracted agent sections.
+- `maxChars`: compiled role budget (default 12000). Longer content is truncated and flagged in `/workflow roles` output.
+
 ### Tool allowlists
 
 Workflow `tools` are still the child-worker allowlist. Entries can be strings:
@@ -578,26 +634,17 @@ Scope order is agent frontmatter fallback < `defaults.tools` < stage `tools`: th
 - Write-capable workflows should use managed worktrees in git repositories.
 - In non-git workspaces with `worktreePolicy: "off"`, writes mutate the live directory.
 - No backend fallback exists. The compiled backend/strategy is fixed for the run.
+- Subagent process launches are gated per Pi process to avoid boot storms: at most `max(2, floor(cpu cores / 2))` concurrent launches, overridable with the `PI_WORKFLOW_MAX_CONCURRENT_LAUNCHES` environment variable. Queued tasks report a waiting message in their status. Deterministic boot failures (extension load or configuration errors) fail fast instead of consuming transient-failure retries.
 - External content, source files, and web pages used by workflow workers are untrusted data, not instructions.
 
 ## Web tools
 
 New workflows should use `workflow_web_search`, `workflow_web_fetch_source`, and
-`workflow_web_source_read`. These tools route through a workflow web-source
-adapter, return compact model-visible cards/snippets, and preserve full source
-text in a run-scoped cache when safe. Fetch accepts `urls: [...]` and
-`sources: [{ url, title }]` so agents can cache several source cards in one call.
-Source-read accepts `queries: [...]` and `reads: [...]` so agents can retrieve
-several snippets from one `sourceRef` in a single call, and accepts `claim` +
-distinctive `terms` for deterministic quote
-candidate harvesting when the exact quote is unknown. Term/claim matches are
-candidate evidence and include matched/missing term metadata; they are not a
-verdict by themselves. The bundled `pi-web-access` adapter remains
-available as the default compatibility provider for this release scope.
-
-Legacy workflows that use `web_search`, `fetch_content`, `get_search_content`, or
-`code_search` still use the bundled `pi-web-access` dependency packaged with
-pi-workflow. Object-form custom tool `extensions` are merged with built-in
-mappings and deduplicated for the subagent launch. Web calls can still fail when
-network access, provider credentials, browser state, or quota are unavailable;
-research workflows should report those limits instead of guessing.
+`workflow_web_source_read` — tool semantics, batching forms, and the run-scoped
+cache are documented under "Run-scoped web-source cache" above. The bundled
+`pi-web-access` adapter remains the default compatibility provider for this
+release scope.
+
+- Legacy workflows that use `web_search`, `fetch_content`, `get_search_content`, or `code_search` still use the bundled `pi-web-access` dependency packaged with pi-workflow.
+- Object-form custom tool `extensions` are merged with built-in mappings and deduplicated for the subagent launch.
+- Web calls can still fail when network access, provider credentials, browser state, or quota are unavailable; research workflows should report those limits instead of guessing.

package/node_modules/@agwab/pi-subagent/README.md

@@ -38,7 +38,6 @@ Run this check in a sandboxed worker and report the artifact paths.
 Start a background audit and let me inspect it in /subagent panel.
 ```
 
-
 ## What it does
 
 Tool: `subagent`
@@ -121,9 +120,11 @@ Existing run:
 { "action": "status", "runId": "run_..." }
 ```
 
+Recent runs can be addressed by `runId` even when they were launched from another cwd; legacy records still resolve from the explicit or current cwd.
+
 ### Panel
 
-Inspect runs, attempts, artifacts, and log tails in a live TUI.
+Inspect runs, attempts, artifacts, and log tails in a live TUI. The panel defaults to the current Pi session, can switch to current cwd or all indexed runs, and includes status filters plus a scrollable detail pane. It shows active and recent terminal runs by default, with in-panel `m` to show more, and counts stale/malformed run pointers without exposing raw session ids.
 
 Open the run monitor:
 
@@ -147,4 +148,3 @@ const status = await getSubagentStatus({ runId: run.runId });
 ## Detailed docs
 
 - [`docs/usage.md`](./docs/usage.md) — full argument reference, code API, `action` behavior, backend selection, sandbox/worktree behavior, artifacts, and validation notes.
-

package/node_modules/@agwab/pi-subagent/api.mjs

@@ -9,4 +9,5 @@ export const getSubagentLogs = api.getSubagentLogs;
 export const waitForSubagent = api.waitForSubagent;
 export const interruptSubagent = api.interruptSubagent;
 export const reconcileSubagentRun = api.reconcileSubagentRun;
+export const recordSubagentChildEvent = api.recordSubagentChildEvent;
 export const SubagentValidationError = api.SubagentValidationError;

package/node_modules/@agwab/pi-subagent/docs/usage.md

@@ -33,20 +33,23 @@ Every call has an `action`. The default is `run`, so omitting `action` starts a
 | `action` | Purpose | Key parameters |
 |---|---|---|
 | `run` (default) | Start a new subagent run, or launch independent runs in parallel. | `agent`/`task` or `tasks`; plus `sandbox`, `worktree`, `model`, `async`, etc. |
-| `status` | Read a run's current state. | `runId`, optional `attemptId` |
-| `logs` | Read a run's captured logs. | `runId`, optional `attemptId` |
-| `wait` | Block until a run finishes. | `runId`, optional `timeoutMs`, `pollIntervalMs` |
-| `interrupt` | Signal a process-backed run. | `runId`, optional `attemptId`, `signal`, `escalateAfterMs`, `killAfterMs`, `reason` |
-| `mark-background` | Mark a run as not needed before the final answer. | `runId` |
-| `reconcile` | Re-read durable artifacts and repair stale/orphaned state when possible. | `runId` |
+| `status` | Read a run's current state. | `runId`, optional `cwd`, `attemptId` |
+| `logs` | Read a run's captured logs. | `runId`, optional `cwd`, `attemptId` |
+| `wait` | Block until a run finishes. | `runId`, optional `cwd`, `timeoutMs`, `pollIntervalMs` |
+| `interrupt` | Signal a process-backed run. | `runId`, optional `cwd`, `attemptId`, `signal`, `escalateAfterMs`, `killAfterMs`, `reason` |
+| `mark-background` | Mark a run as not needed before the final answer. | `runId`, optional `cwd` |
+| `reconcile` | Re-read durable artifacts and repair stale/orphaned state when possible. | `runId`, optional `cwd` |
 
-State is file-based under `.pi/agent/runs/<run-id>/`. `status`/`logs`/`wait` read those files; `interrupt` sends a real OS signal; `mark-background` updates run metadata; `reconcile` repairs local metadata from durable attempt artifacts without relaunching work.
+State is file-based under `.pi/agent/runs/<run-id>/`. `status`/`logs`/`wait` read those files; `interrupt` sends a real OS signal; `mark-background` updates run metadata; `reconcile` repairs local metadata from durable attempt artifacts without relaunching work. Recent runs also write a global locator pointer, so existing-run actions can often resolve a `runId` even when `cwd` is omitted or the run was launched from another cwd.
+
+Parent orchestrators may record descendant state with `recordSubagentChildEvent`, which appends `child.*` events to the parent run's `events.jsonl` (`child.started`, `child.failed`, `child.completed`, or `child.cancelled`). `status` and `/subagent panel` aggregate those into `childSummary`, including failure counts, active child run IDs, and the latest child failure. This keeps parent status distinct from descendant failures and makes retry attempts distinguishable from newly-started child work.
 
 Model:
 
 ```text
 run = one subagent execution
 attempt = one launch attempt
+child = descendant work reported by an orchestrator through child.* events
 correlationId = optional external trace label
 ```
 
@@ -68,6 +71,7 @@ import {
   waitForSubagent,
   interruptSubagent,
   reconcileSubagentRun,
+  recordSubagentChildEvent,
 } from "@agwab/pi-subagent/api";
 
 const run = await runSubagent({
@@ -83,9 +87,17 @@ const logs = await getSubagentLogs({ cwd: process.cwd(), runId: run.runId });
 await waitForSubagent({ cwd: process.cwd(), runId: run.runId, timeoutMs: 300000 });
 await interruptSubagent({ cwd: process.cwd(), runId: run.runId, reason: "caller cancelled" });
 await reconcileSubagentRun({ cwd: process.cwd(), runId: run.runId });
+await recordSubagentChildEvent({
+  cwd: process.cwd(),
+  runId: run.runId,
+  event: "failed",
+  childRunId: "run_child_123",
+  childTaskId: "task-4",
+  failureKind: "model",
+});
 ```
 
-`runSubagent` accepts the same run options as the tool, plus an optional `signal`. Existing-run helpers accept `cwd`, `runId`, optional `attemptId`, and optional `runsDir`. The API is intentionally object-only and does not expose the lower-level runner internals.
+`runSubagent` accepts the same run options as the tool, plus an optional `signal`. Existing-run helpers accept `runId`, optional `cwd`, optional `attemptId`, and optional `runsDir`; when `cwd` is omitted they use the global locator index first and fall back to the current cwd for legacy records. The API is intentionally object-only and does not expose the lower-level runner internals.
 
 The code API is ESM-only. Import `@agwab/pi-subagent/api`; do not deep-import internal files such as `src/orchestrate/*` because only documented package subpaths are public.
 
@@ -128,6 +140,21 @@ Use `concurrency` to cap parallel fan-out:
 }
 ```
 
+For synchronous parallel fan-out, `failFast:true` stops scheduling additional siblings after the first failed result. Add `cancelSiblingsOnFailure:true` to also abort siblings that are already running:
+
+```json
+{
+  "failFast": true,
+  "cancelSiblingsOnFailure": true,
+  "tasks": [
+    { "task": "Run check A." },
+    { "task": "Run check B." }
+  ]
+}
+```
+
+The parallel response includes `totalTasks`, `startedCount`, `skippedCount`, and `failFastTriggered` so callers can distinguish skipped siblings from completed/failed runs. Async parallel launches return once children are started, so fail-fast decisions for later runtime failures must be handled by the parent/workflow layer.
+
 Chain/sequential execution is intentionally not supported by this engine. If step B needs output from step A, keep that sequencing in the parent agent or a workflow layer.
 
 ## Async and existing runs
@@ -177,14 +204,26 @@ Interrupt a process-backed run:
 
 `interrupt` is conservative. It can signal runs with registered process metadata. Unsupported or already-terminal runs return explicit status rather than pretending cancellation succeeded.
 
+### Existing-run resolution
+
+For `status`, `logs`, `wait`, `interrupt`, `mark-background`, and `reconcile`, the lookup order is:
+
+1. Use the explicit `cwd`/`runsDir` when provided.
+2. Otherwise, check the current cwd's `.pi/agent/runs` for legacy/local records.
+3. Otherwise, resolve `runId` through the global locator index and read the pointed-to run directory.
+
+The locator index is only a pointer for finding runs across cwd boundaries. `run.json`, `events.jsonl`, and attempt `result.json` files remain the source of truth.
+
 ## Common run options
 
 | Option | Use |
 |---|---|
-| `cwd` | Run from a specific project directory. Existing-run actions also accept `cwd` to find that run registry. |
+| `cwd` | Run from a specific project directory. Existing-run actions accept `cwd` to force a registry location; if omitted, recent runs can be found by global locator and older runs fall back to the current cwd. |
 | `timeoutMs` | Limit worker execution time for `run`; limit polling duration for `action: "wait"`. Omit it for no runtime kill deadline; `wait` alone defaults to 60s polling. |
 | `visible` | Use a visible tmux-backed worker (`visible: true`). |
 | `concurrency` | Cap parallel run fan-out. |
+| `failFast` | For synchronous parallel runs, stop scheduling new siblings after the first failed result. |
+| `cancelSiblingsOnFailure` | For synchronous parallel runs, abort already-running siblings after the first failed result; implies fail-fast scheduling. |
 | `model` | Select a Pi model/provider for model-backed workers. |
 | `thinking` / `thinkingLevel` / `reasoningLevel` | Set the reasoning level. |
 | `tools` | Tool allowlist. With a named agent this may only narrow agent-declared tools; it cannot expand authority. For agentless runs it sets the full tool allowlist. |
@@ -247,8 +286,8 @@ There are three inputs for worktree isolation, in order of preference:
 | Input | When to use |
 |---|---|
 | `worktree` | Primary switch. `true` to isolate; or a string path for an explicit worktree location. |
-| `workspace` | Advanced. `"shared" | "worktree" | "auto"`, or `{ mode, path }` for an explicit path. |
-| `worktreePolicy` | Advanced. `"auto" | "required" | "never"` to force or forbid isolation. |
+| `workspace` | Advanced. `"shared" \| "worktree" \| "auto"`, or `{ mode, path }` for an explicit path. |
+| `worktreePolicy` | Advanced. `"auto" \| "required" \| "never"` to force or forbid isolation. |
 
 Most calls only need `worktree`:
 
@@ -389,6 +428,8 @@ Runs write durable evidence under:
 
 `run.json` records a `parentSessionId` field: the Pi session id of the session that launched the run, injected from the tool context (not a model-settable argument). Consumers (e.g. status panels) can use it to scope a shared per-`cwd` runs directory to the session that owns each run. The field is omitted when no session id is available, and older records simply lack it.
 
+Recent runs also write a small locator file under Pi's global subagent-run index. A locator contains the `runId`, absolute `cwd`, optional `runsDir`, optional `parentSessionId`, optional `correlationId`, and `updatedAt`. It is not authoritative evidence and can become stale if the pointed-to run directory is moved or deleted; use `run.json`, `events.jsonl`, and attempt `result.json` as the source of truth.
+
 Older `schemaVersion: 1` artifacts under `<run-id>/<task-id>/` are still readable for compatibility.
 
 Tool responses return compact status and artifact references rather than raw logs.
@@ -399,7 +440,17 @@ Tool responses return compact status and artifact references rather than raw log
 /subagent panel
 ```
 
-The panel shows all/completed/failed filters, run/attempt details, workspace/artifact paths, dependency metadata, event tail, and log tail. The panel is for human inspection; existing-run tool actions remain the programmatic interface.
+The panel shows run/attempt details, workspace/artifact paths, dependency metadata, event tail, and log tail. It has three scopes:
+
+- `session`: runs whose `run.json.parentSessionId` matches the current Pi session. This is the default when a session id is available.
+- `cwd`: runs under the current workspace's `.pi/agent/runs`, including legacy records that lack `parentSessionId`.
+- `all`: the global locator index plus current-cwd legacy records.
+
+Status filters are `all`, `running`, `completed`, and `failed`. In the `all` status view, the default list shows all active runs plus recent terminal runs only: 20 for `session`/`cwd`, 50 for `all`. The `completed` and `failed` filters use the same recent terminal cap; `running` is uncapped. The header reports `shown/total`, and when older matching runs are hidden, press `m` in the panel to show more; no separate command is needed. The panel keeps a fixed-height layout, uses an internally scrollable detail pane, and never renders raw `parentSessionId` values.
+
+Stale or malformed locators are counted in the header and skipped. Active runs whose process metadata is dead and whose heartbeat/update timestamp is stale are rendered read-only as `failed` with failure `stale`; the panel does not mutate or delete records. Use `action:"reconcile"` to repair local registry state from durable artifacts when possible.
+
+The panel is for human inspection; existing-run tool actions remain the programmatic interface.
 
 ## Development validation
 

package/node_modules/@agwab/pi-subagent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-subagent",
-  "version": "0.3.6",
+  "version": "0.4.2",
   "description": "Minimal subagent runtime for Pi.",
   "type": "module",
   "private": false,
@@ -37,7 +37,7 @@
     "image": "https://raw.githubusercontent.com/AgwaB/pi-subagent/main/assets/subagent-panel.png"
   },
   "scripts": {
-    "check:scripts": "for d in scripts test internal/scripts; do [ -d \"$d\" ] && find \"$d\" -name '*.mjs' -print; done | xargs -n1 node --check",
+    "check:scripts": "for d in scripts test; do [ -d \"$d\" ] && find \"$d\" -name '*.mjs' -print; done | xargs -n1 node --check",
     "check:resolver": "node ./test/checks/resolver.mjs",
     "check:api": "node ./test/checks/api.mjs",
     "check:artifacts": "node ./test/checks/artifacts.mjs",