@agwab/pi-workflow 0.3.0 → 0.4.0

package/dist/workflow-web-source-extension.js

@@ -608,8 +608,8 @@ async function cachedFetchFailureResult(config, cache, key, failure) {
     }
     return errorToolResult(failure.code, failure.message, failure.extra);
 }
-const FETCH_LOCK_STALE_MS = 60_000;
-const FETCH_LOCK_WAIT_MS = 75_000;
+const FETCH_LOCK_STALE_MS = 4 * 60_000;
+const FETCH_LOCK_WAIT_MS = 5 * 60_000;
 async function withWorkflowWebFetchLock(config, key, signal, fn) {
     const release = await acquireWorkflowWebFetchLock(config, key, signal);
     try {
@@ -627,10 +627,11 @@ async function acquireWorkflowWebFetchLock(config, key, signal) {
         if (signal?.aborted)
             throw new Error("aborted");
         try {
+            const ownerId = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
             await mkdir(lockDir);
-            await writeFile(resolve(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), key }, null, 2)}\n`, "utf8");
+            await writeFile(resolve(lockDir, "owner.json"), `${JSON.stringify({ ownerId, pid: process.pid, createdAt: new Date().toISOString(), key }, null, 2)}\n`, "utf8");
             return async () => {
-                await rm(lockDir, { recursive: true, force: true });
+                await releaseWorkflowWebFetchLock(lockDir, ownerId);
             };
         }
         catch (error) {
@@ -644,6 +645,17 @@ async function acquireWorkflowWebFetchLock(config, key, signal) {
         }
     }
 }
+async function releaseWorkflowWebFetchLock(lockDir, ownerId) {
+    try {
+        const current = await readFetchLockOwner(lockDir);
+        if (current?.ownerId !== ownerId)
+            return;
+        await rm(lockDir, { recursive: true, force: true });
+    }
+    catch {
+        // Missing or unreadable lock will be retried by the caller.
+    }
+}
 async function removeStaleFetchLock(lockDir) {
     try {
         const current = await stat(lockDir);
@@ -655,6 +667,17 @@ async function removeStaleFetchLock(lockDir) {
         // Missing or unreadable lock will be retried by the caller.
     }
 }
+async function readFetchLockOwner(lockDir) {
+    try {
+        const parsed = JSON.parse(await readFile(resolve(lockDir, "owner.json"), "utf8"));
+        return isRecord(parsed) && typeof parsed.ownerId === "string"
+            ? { ownerId: parsed.ownerId }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function readDurableFetchFailure(config, key) {
     try {
         const parsed = JSON.parse(await readFile(fetchFailurePath(config, key), "utf8"));

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 } : {}),
@@ -702,9 +700,15 @@ function consumeAnchoredSnippet(options) {
     }
     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,
+        status: anchorTruncated ? "truncated" : status,
         quote: consumed.text,
         visibleChars: consumed.text.length,
         sourceStart,
@@ -737,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);
@@ -834,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 } : {}),
@@ -972,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-subagent",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Minimal subagent runtime for Pi.",
   "type": "module",
   "private": false,

package/node_modules/@agwab/pi-subagent/src/index.ts

@@ -210,6 +210,52 @@ function getExecuteParams(first: unknown, second: unknown): unknown {
 	return second === undefined ? first : second;
 }
 
+function isAbortSignalLike(value: unknown): value is AbortSignal {
+	return isRecord(value) && typeof value.aborted === "boolean";
+}
+
+function normalizeExecuteArgs(args: unknown[]): {
+	params: unknown;
+	signal?: AbortSignal;
+	onUpdate?: ToolUpdateCallback;
+	ctx?: unknown;
+} {
+	const [first, second, third, fourth, fifth] = args;
+	const params = getExecuteParams(first, second);
+
+	// Pi has shipped both execute(toolCallId, params, signal, onUpdate, ctx)
+	// and execute(toolCallId, params, onUpdate, ctx, signal) call orders. Support
+	// both so context-scoped metadata (cwd/session) and cancellation survive either
+	// host version.
+	if (typeof third === "function") {
+		return {
+			params,
+			onUpdate: third as ToolUpdateCallback,
+			ctx: fourth,
+			...(isAbortSignalLike(fifth) ? { signal: fifth } : {}),
+		};
+	}
+
+	if (isAbortSignalLike(fifth) && !isAbortSignalLike(third)) {
+		return {
+			params,
+			signal: fifth,
+			...(typeof fourth === "function"
+				? { onUpdate: fourth as ToolUpdateCallback }
+				: { ctx: fourth }),
+		};
+	}
+
+	return {
+		params,
+		...(isAbortSignalLike(third) ? { signal: third } : {}),
+		...(typeof fourth === "function"
+			? { onUpdate: fourth as ToolUpdateCallback }
+			: {}),
+		ctx: fifth,
+	};
+}
+
 function getCwd(ctx: unknown): string {
 	if (isRecord(ctx) && typeof ctx.cwd === "string" && ctx.cwd.length > 0)
 		return ctx.cwd;
@@ -595,9 +641,10 @@ async function writeUnsupportedResult(
 	});
 }
 
-interface ToolUpdateCallback {
-	(update: { content: ToolTextContent[]; details: unknown }): void;
-}
+type ToolUpdateCallback = (update: {
+	content: ToolTextContent[];
+	details: unknown;
+}) => void;
 
 interface NotificationContext {
 	ui?: {
@@ -957,8 +1004,9 @@ export default function registerSubagentEngine(pi: ExtensionAPI) {
 				: summary;
 			return new SingleLineComponent(`${title} ${theme.fg("muted", rest)}`);
 		},
-		async execute(toolCallIdOrArgs, maybeParams, signal, onUpdate, ctx) {
-			const params = getExecuteParams(toolCallIdOrArgs, maybeParams);
+		async execute(...executeArgs: unknown[]) {
+			const { params, signal, onUpdate, ctx } =
+				normalizeExecuteArgs(executeArgs);
 			const cwd = getCwd(ctx);
 
 			try {

package/node_modules/@agwab/pi-subagent/src/panel.ts

@@ -512,12 +512,14 @@ async function readTask(
 	mtimeMs: number,
 	loadTails: boolean,
 	currentSessionId?: string,
+	options: { staleOverride?: boolean } = {},
 ): Promise<TaskRow | null> {
 	const parsed = await readJson(resultPath);
 	if (!isResultEnvelope(parsed)) return null;
 	const log = await readLogTail(cwd, parsed, loadTails, currentSessionId);
 	const stale =
-		isActive(parsed.status) && Date.now() - mtimeMs > STALE_RUN_AFTER_MS;
+		isActive(parsed.status) &&
+		(options.staleOverride ?? Date.now() - mtimeMs > STALE_RUN_AFTER_MS);
 	return {
 		attemptId: parsed.attemptId ?? parsed.taskId ?? "unknown",
 		status: stale ? "failed" : parsed.status,
@@ -571,6 +573,7 @@ async function readTaskFromRegistry(
 	loadTails: boolean,
 	currentSessionId?: string,
 ): Promise<TaskRow> {
+	const registryStale = registryTaskStale(task);
 	if (
 		task.artifactCwd !== undefined &&
 		task.resultPath !== undefined &&
@@ -590,13 +593,14 @@ async function readTaskFromRegistry(
 					statInfo.mtimeMs,
 					loadTails,
 					currentSessionId,
+					isActive(task.status) ? { staleOverride: registryStale } : undefined,
 				);
 				if (parsed !== null) return parsed;
 			}
 		}
 	}
 	const log = await readTailFromRegistryPath(task, loadTails, currentSessionId);
-	const stale = registryTaskStale(task);
+	const stale = registryStale;
 	return {
 		attemptId: task.attemptId ?? task.taskId ?? "unknown",
 		status: stale ? "failed" : task.status,
@@ -1087,7 +1091,7 @@ export class SubagentPanel implements Component {
 	}
 
 	render(width: number): string[] {
-		const safeWidth = Math.max(48, width);
+		const safeWidth = Math.max(1, width);
 		const maxLines = panelLineBudget();
 		const lines: string[] = [];
 		const active = this.snapshot.runs.filter((run) =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-workflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Workflow orchestration for Pi subagents.",
   "private": false,
   "type": "module",
@@ -76,7 +76,7 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "@agwab/pi-subagent": "^0.4.0",
+    "@agwab/pi-subagent": "^0.4.2",
     "pi-web-access": "^0.10.7",
     "typebox": "^1.1.39"
   },

package/skills/workflow-guide/SKILL.md

@@ -29,6 +29,7 @@ Resolve paths relative to this skill directory. Treat those docs as the source o
 - For deterministic local post-processing, declare a `support` object with `support.uses` pointing to a bundle-local `./*.mjs` helper; support is trusted local code, not sandboxed subagent work and does not use a separate `type` value.
 - For bounded iteration, use `loop` with fixed child stages, `maxRounds`, and deterministic `until`.
 - Agent-declared tools are the authority ceiling; workflow `tools` can only narrow them.
+- To reuse agent knowledge across stages, declare top-level `roles` (`fromAgent` extracts safe agent sections; `prompt` appends literal text). Compiled role text is injected as a `# Role Context` block; check the result with `/workflow roles <workflow>`. See "Roles" in `docs/usage.md`.
 - Keep review/research workflows read-only unless the workflow explicitly documents managed-worktree mutation.
 - Write-capable workflows need explicit worktree policy, validation/check stages, and protected-path awareness.
 - In non-git workspaces with `worktreePolicy: "off"`, writes mutate the live directory.

package/src/artifact-graph-runtime.ts

@@ -2,6 +2,8 @@ import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { stringifyPromptJson } from "./prompt-json.js";
+import { compactStrings } from "./strings.js";
 import { loadWorkflowHelper } from "./workflow-helpers.js";
 import {
 	WORKFLOW_ARTIFACT_TOOL_NAME,
@@ -13,7 +15,7 @@ import {
 	type WorkflowSourceManifestSource,
 } from "./workflow-artifact-tool.js";
 import { writeWorkflowTaskArtifactBundle } from "./workflow-output-artifacts.js";
-import { type JsonSchema } from "./json-schema.js";
+import type { JsonSchema } from "./json-schema.js";
 import {
 	buildRunSourceContext,
 	readOutputText,
@@ -29,11 +31,11 @@ import {
 	writeJsonAtomic,
 	writeRunRecord,
 } from "./store.js";
-import {
-	type CompiledTask,
-	type CompiledWorkflow,
-	type WorkflowRunRecord,
-	type WorkflowTaskRunRecord,
+import type {
+	CompiledTask,
+	CompiledWorkflow,
+	WorkflowRunRecord,
+	WorkflowTaskRunRecord,
 } from "./types.js";
 
 export async function executeSupportTask(
@@ -372,7 +374,9 @@ export function normalizeDynamicControllerOutput(value: unknown): {
 		refs: [],
 	};
 }
-export function normalizeSupportControl(value: unknown): Record<string, unknown> {
+export function normalizeSupportControl(
+	value: unknown,
+): Record<string, unknown> {
 	if (value && typeof value === "object" && !Array.isArray(value)) {
 		const record = value as Record<string, unknown>;
 		return {
@@ -474,7 +478,7 @@ export async function prepareDagTask(
 			compiledTask.compiledPrompt,
 			"# Source Stage Context",
 			"Use this deterministic source context packet. Prefer structuredOutput over outputPreview. Do not assume dependencies beyond this explicit packet.",
-			JSON.stringify({ ...context, missingDependencies: missing }, null, 2),
+			stringifyPromptJson({ ...context, missingDependencies: missing }),
 		].join("\n\n"),
 	};
 }
@@ -486,6 +490,10 @@ async function prepareArtifactGraphTask(
 	task: WorkflowTaskRunRecord,
 	contextDependsOn: readonly string[],
 ): Promise<CompiledTask> {
+	if (compiledTask.artifactGraph?.artifactAccess === "none") {
+		return { ...compiledTask, cwd: task.cwd };
+	}
+
 	const taskDir = dirname(fromProjectPath(cwd, task.files.result));
 	const manifestPath = join(taskDir, "source-manifest.json");
 	const ledgerPath = join(taskDir, "read-ledger.jsonl");
@@ -880,7 +888,7 @@ export function formatArtifactGraphSourceContext(
 	return [
 		"# Workflow Artifact Inputs",
 		"Use workflow_artifact to list/read upstream workflow artifacts. Inline controlProjection fields are authoritative for the projected data they contain; use artifact reads for declared requiredReads, missing fields, or debug detail.",
-		"Projected reads must include a JSON path when using maxItems or maxChars, for example {\"action\":\"read\",\"source\":\"plan\",\"artifact\":\"control\",\"path\":\"$.factSlots\",\"maxItems\":8,\"maxChars\":2000}. For a whole artifact read, omit maxItems/maxChars.",
+		'Projected reads must include a JSON path when using maxItems or maxChars, for example {"action":"read","source":"plan","artifact":"control","path":"$.factSlots","maxItems":8,"maxChars":2000}. For a whole artifact read, omit maxItems/maxChars.',
 		requiredReads.length > 0
 			? [
 					"Required reads before final output:",
@@ -888,7 +896,7 @@ export function formatArtifactGraphSourceContext(
 				].join("\n")
 			: "No hard requiredReads are declared for this stage.",
 		"Available sources:",
-		JSON.stringify(
+		stringifyPromptJson(
 			sources.map((source) => ({
 				source: source.source,
 				taskId: source.taskId,
@@ -904,13 +912,11 @@ export function formatArtifactGraphSourceContext(
 				projectionTruncated: source.projectionTruncated,
 				availableArtifacts: Object.keys(source.artifacts),
 			})),
-			null,
-			2,
 		),
 	].join("\n\n");
 }
 function uniqueStrings(values: readonly string[]): string[] {
-	return [...new Set(values.filter((value) => value.trim().length > 0))];
+	return compactStrings(values, { trim: false, dropWhitespaceOnly: true });
 }
 
 export async function readArtifactGraphControl(