@agwab/pi-workflow 0.3.0 → 0.4.0

package/src/workflow-partial-output.ts

@@ -0,0 +1,299 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { hashDynamicRequest } from "./dynamic-events.js";
+import { readJson, writeJsonAtomic } from "./store.js";
+
+export const WORKFLOW_PARTIAL_OUTPUT_PROTOCOL =
+	"workflow-partial-output-v1" as const;
+export const WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA =
+	"workflow-partial-output-ledger-v1" as const;
+export const WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE = "partial-control.json";
+
+export type WorkflowPartialOutputIssueCode =
+	| "invalid_json"
+	| "invalid_type"
+	| "invalid_schema"
+	| "invalid_path"
+	| "disallowed_path"
+	| "missing_items"
+	| "missing_item_id"
+	| "duplicate_item_id";
+
+export interface WorkflowPartialOutputIssue {
+	code: WorkflowPartialOutputIssueCode;
+	message: string;
+	sectionIndex?: number;
+	path?: string;
+	itemId?: string;
+}
+
+export interface WorkflowPartialOutputItem {
+	path: string;
+	itemId: string;
+	itemHash: string;
+	item: unknown;
+	ordinal: number;
+	sectionIndex: number;
+	sectionItemIndex: number;
+	itemRef: string;
+}
+
+export interface WorkflowPartialOutputLedger {
+	schema: typeof WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA;
+	protocol: typeof WORKFLOW_PARTIAL_OUTPUT_PROTOCOL;
+	items: WorkflowPartialOutputItem[];
+	issues: WorkflowPartialOutputIssue[];
+}
+
+export interface ParseWorkflowPartialOutputOptions {
+	allowedPaths?: readonly string[];
+}
+
+interface PartialSectionMatch {
+	content: string;
+	start: number;
+	end: number;
+	index: number;
+}
+
+const PARTIAL_CONTROL_OPEN = "partial-control";
+
+export function partialOutputLedgerPath(taskDir: string): string {
+	return join(taskDir, WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE);
+}
+
+export async function readWorkflowPartialOutputLedger(
+	taskDir: string,
+): Promise<WorkflowPartialOutputLedger | undefined> {
+	return await readJson<WorkflowPartialOutputLedger>(
+		partialOutputLedgerPath(taskDir),
+	);
+}
+
+export async function writeWorkflowPartialOutputLedger(options: {
+	taskDir: string;
+	rawOutput: string;
+	allowedPaths?: readonly string[];
+}): Promise<WorkflowPartialOutputLedger> {
+	const ledger = parseWorkflowPartialOutput(options.rawOutput, {
+		allowedPaths: options.allowedPaths,
+	});
+	await writeJsonAtomic(partialOutputLedgerPath(options.taskDir), ledger);
+	return ledger;
+}
+
+export async function writeWorkflowPartialOutputLedgerFromFile(options: {
+	taskDir: string;
+	outputFile: string;
+	allowedPaths?: readonly string[];
+}): Promise<WorkflowPartialOutputLedger | undefined> {
+	const rawOutput = await readFile(options.outputFile, "utf8").catch(
+		() => undefined,
+	);
+	if (rawOutput === undefined) return undefined;
+	return await writeWorkflowPartialOutputLedger({
+		taskDir: options.taskDir,
+		rawOutput,
+		allowedPaths: options.allowedPaths,
+	});
+}
+
+export function stripWorkflowPartialOutputSections(raw: string): string {
+	if (!raw.includes(PARTIAL_CONTROL_OPEN)) return raw;
+	return raw.replace(partialControlSectionRegExp(), "");
+}
+
+export function parseWorkflowPartialOutput(
+	raw: string,
+	options: ParseWorkflowPartialOutputOptions = {},
+): WorkflowPartialOutputLedger {
+	const allowedPaths = options.allowedPaths
+		? new Set(options.allowedPaths)
+		: undefined;
+	const items: WorkflowPartialOutputItem[] = [];
+	const issues: WorkflowPartialOutputIssue[] = [];
+	const byPathAndId = new Map<string, WorkflowPartialOutputItem>();
+
+	for (const section of collectPartialControlSections(raw)) {
+		const parsed = parsePartialSectionJson(section, issues);
+		if (!parsed) continue;
+		const path = parsePartialSectionPath(parsed, section, allowedPaths, issues);
+		if (!path) continue;
+		const rawItems = parsePartialSectionItems(parsed, section, path, issues);
+		if (!rawItems) continue;
+		for (const [sectionItemIndex, item] of rawItems.entries()) {
+			const itemId = stablePartialItemId(item);
+			if (!itemId) {
+				issues.push({
+					code: "missing_item_id",
+					sectionIndex: section.index,
+					path,
+					message:
+						"partial output items must be objects with a stable non-empty string id",
+				});
+				continue;
+			}
+			const itemHash = hashDynamicRequest(item);
+			const key = `${path}\0${itemId}`;
+			const existing = byPathAndId.get(key);
+			if (existing) {
+				if (existing.itemHash !== itemHash) {
+					issues.push({
+						code: "duplicate_item_id",
+						sectionIndex: section.index,
+						path,
+						itemId,
+						message: `partial output item ${itemId} at ${path} changed after it was published`,
+					});
+				}
+				continue;
+			}
+			const ordinal = items.length;
+			const partialItem: WorkflowPartialOutputItem = {
+				path,
+				itemId,
+				itemHash,
+				item,
+				ordinal,
+				sectionIndex: section.index,
+				sectionItemIndex,
+				itemRef: `${WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE}#/items/${ordinal}`,
+			};
+			items.push(partialItem);
+			byPathAndId.set(key, partialItem);
+		}
+	}
+
+	return {
+		schema: WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA,
+		protocol: WORKFLOW_PARTIAL_OUTPUT_PROTOCOL,
+		items,
+		issues,
+	};
+}
+
+export function hasFatalPartialOutputIssue(
+	ledger: Pick<WorkflowPartialOutputLedger, "issues"> | undefined,
+): WorkflowPartialOutputIssue | undefined {
+	return ledger?.issues.find((issue) => issue.code === "duplicate_item_id");
+}
+
+function collectPartialControlSections(raw: string): PartialSectionMatch[] {
+	if (!raw.includes(PARTIAL_CONTROL_OPEN)) return [];
+	const matches: PartialSectionMatch[] = [];
+	const re = partialControlSectionRegExp();
+	let match: RegExpExecArray | null;
+	while ((match = re.exec(raw)) !== null) {
+		matches.push({
+			content: match[1] ?? "",
+			start: match.index,
+			end: re.lastIndex,
+			index: matches.length,
+		});
+	}
+	return matches;
+}
+
+function partialControlSectionRegExp(): RegExp {
+	return /[ \t]*<partial-control\s*>([\s\S]*?)<\/partial-control>[ \t]*(?:\r?\n)?/gi;
+}
+
+function parsePartialSectionJson(
+	section: PartialSectionMatch,
+	issues: WorkflowPartialOutputIssue[],
+): Record<string, unknown> | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(section.content.trim());
+	} catch (error) {
+		issues.push({
+			code: "invalid_json",
+			sectionIndex: section.index,
+			message: error instanceof Error ? error.message : String(error),
+		});
+		return undefined;
+	}
+	if (!isRecord(parsed)) {
+		issues.push({
+			code: "invalid_type",
+			sectionIndex: section.index,
+			message: "partial-control section must contain a JSON object",
+		});
+		return undefined;
+	}
+	if (parsed.schema !== WORKFLOW_PARTIAL_OUTPUT_PROTOCOL) {
+		issues.push({
+			code: "invalid_schema",
+			sectionIndex: section.index,
+			message: `partial-control schema must be ${WORKFLOW_PARTIAL_OUTPUT_PROTOCOL}`,
+		});
+		return undefined;
+	}
+	return parsed;
+}
+
+function parsePartialSectionPath(
+	section: Record<string, unknown>,
+	match: PartialSectionMatch,
+	allowedPaths: Set<string> | undefined,
+	issues: WorkflowPartialOutputIssue[],
+): string | undefined {
+	const path = section.path;
+	if (typeof path !== "string" || !path.startsWith("$.")) {
+		issues.push({
+			code: "invalid_path",
+			sectionIndex: match.index,
+			message: "partial-control path must be a control JSONPath starting with $.",
+		});
+		return undefined;
+	}
+	if (allowedPaths && !allowedPaths.has(path)) {
+		issues.push({
+			code: "disallowed_path",
+			sectionIndex: match.index,
+			path,
+			message: `partial-control path ${path} is not declared for this stage`,
+		});
+		return undefined;
+	}
+	return path;
+}
+
+function parsePartialSectionItems(
+	section: Record<string, unknown>,
+	match: PartialSectionMatch,
+	path: string,
+	issues: WorkflowPartialOutputIssue[],
+): unknown[] | undefined {
+	const items = section.items;
+	if (!Array.isArray(items)) {
+		issues.push({
+			code: "missing_items",
+			sectionIndex: match.index,
+			path,
+			message: "partial-control items must be an array",
+		});
+		return undefined;
+	}
+	return items;
+}
+
+function stablePartialItemId(item: unknown): string | undefined {
+	if (!isRecord(item) || typeof item.id !== "string") return undefined;
+	const sanitized = sanitizePartialItemId(item.id);
+	return sanitized || undefined;
+}
+
+function sanitizePartialItemId(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9_.-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 64);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/workflow-progress-health.ts

@@ -104,16 +104,16 @@ export function diagnoseWorkflowRunHealth(
 	options: WorkflowHealthOptions = {},
 ): WorkflowProgressHealth {
 	const nowMs = options.nowMs ?? Date.now();
-	const runningTask = currentRunningTask(run.tasks ?? []);
-	if (runningTask)
-		return diagnoseWorkflowTaskHealth(runningTask, run, { nowMs });
-
 	const problem = (run.tasks ?? []).find((task) =>
 		isProblemStatus(task.status),
 	);
 	if (problem) return problemRunHealth(problem, nowMs);
 	if (isProblemStatus(run.status)) return problemWorkflowHealth(run.status);
 	if (run.status === "completed") return completedWorkflowHealth();
+
+	const runningTask = currentRunningTask(run.tasks ?? []);
+	if (runningTask)
+		return diagnoseWorkflowTaskHealth(runningTask, run, { nowMs });
 	return waitingWorkflowHealth(run, nowMs);
 }
 
@@ -143,19 +143,20 @@ export function classifyWorkflowTaskDuration(
 		.filter(Boolean)
 		.join(" ")
 		.toLowerCase();
-	if (/\b(render|helper|support|schema|partition|gate)\b/.test(text))
-		return "short";
-	if (
-		/\b(research|audit|synthesis|review|verify|verifier|normalize|plan|impact|spec)\b/.test(
-			text,
-		)
-	)
-		return "long";
 	const maxRuntimeMs = task.runtime?.maxRuntimeMs;
 	if (maxRuntimeMs !== undefined && Number.isFinite(maxRuntimeMs)) {
 		if (maxRuntimeMs <= 5 * 60_000) return "short";
 		if (maxRuntimeMs >= 60 * 60_000) return "long";
 	}
+	if (task.kind === "support") return "short";
+	if (
+		/\b(research|audit|synthesi[sz]e?r?|review(?:er|ers|ing|s)?|verif(?:y|ier|iers|ication)|normaliz(?:e|er|ing|ation)?|plan(?:ning)?|impact|spec)\b/.test(
+			text,
+		)
+	)
+		return "long";
+	if (/\b(render|helper|support|schema|partition|gate)\b/.test(text))
+		return "short";
 	return "medium";
 }
 
@@ -215,6 +216,33 @@ function waitingWorkflowHealth(
 	nowMs: number,
 ): WorkflowProgressHealth {
 	const hasPending = run.taskSummary.pending > 0;
+	const lastActivityAgeMs = ageMs(run.updatedAt, nowMs);
+	if (hasPending && lastActivityAgeMs !== undefined) {
+		if (lastActivityAgeMs >= STUCK_BY_DURATION.medium) {
+			return {
+				state: "likely-stuck",
+				label: "scheduler stuck",
+				summary: "pending tasks have not scheduled",
+				tone: "error",
+				suggestion: "resume",
+				reason: "no task is running and run activity is stale",
+				lastActivityAt: run.updatedAt,
+				lastActivityAgeMs,
+			};
+		}
+		if (lastActivityAgeMs >= STALL_BY_DURATION.medium) {
+			return {
+				state: "stalled",
+				label: "scheduler quiet",
+				summary: "pending tasks are waiting without recent activity",
+				tone: "warning",
+				suggestion: "inspect",
+				reason: "no task is running and run activity is stale",
+				lastActivityAt: run.updatedAt,
+				lastActivityAgeMs,
+			};
+		}
+	}
 	return {
 		state: hasPending ? "pending" : "active",
 		label: hasPending ? "pending" : "active",
@@ -227,7 +255,7 @@ function waitingWorkflowHealth(
 			? "no task is currently running"
 			: "workflow is still in progress",
 		lastActivityAt: run.updatedAt,
-		lastActivityAgeMs: ageMs(run.updatedAt, nowMs),
+		lastActivityAgeMs,
 	};
 }
 
@@ -335,8 +363,12 @@ function runningContext(
 	const durationClass = classifyWorkflowTaskDuration(task);
 	const startedAtMs = parseTime(task.startedAt);
 	const heartbeatAt = parseHeartbeatAt(task.lastMessage);
+	const heartbeatAgeMs = ageMs(heartbeatAt, nowMs);
 	const activityAt = latestIso([heartbeatAt, run?.updatedAt, task.startedAt]);
 	const lastActivityAgeMs = ageMs(activityAt, nowMs);
+	const hasFreshHeartbeat =
+		heartbeatAgeMs !== undefined &&
+		heartbeatAgeMs <= STALL_BY_DURATION[durationClass];
 	return {
 		task,
 		nowMs,
@@ -346,8 +378,8 @@ function runningContext(
 		activityAt,
 		lastActivityAgeMs,
 		heartbeatAt,
-		heartbeatAgeMs: ageMs(heartbeatAt, nowMs),
-		hasBackendSignal: Boolean(task.backendHandle || task.pid || heartbeatAt),
+		heartbeatAgeMs,
+		hasBackendSignal: Boolean(task.pid || hasFreshHeartbeat),
 		staleMs: lastActivityAgeMs ?? Number.POSITIVE_INFINITY,
 	};
 }

package/src/workflow-web-source-extension.ts

@@ -942,8 +942,8 @@ async function cachedFetchFailureResult(
 	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<T>(
 	config: WorkflowWebSourceCacheConfig,
@@ -970,14 +970,15 @@ async function acquireWorkflowWebFetchLock(
 	for (;;) {
 		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`,
+				`${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) {
 			if (!isFileExistsError(error)) throw error;
@@ -990,6 +991,19 @@ async function acquireWorkflowWebFetchLock(
 	}
 }
 
+async function releaseWorkflowWebFetchLock(
+	lockDir: string,
+	ownerId: string,
+): Promise<void> {
+	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: string): Promise<void> {
 	try {
 		const current = await stat(lockDir);
@@ -1001,6 +1015,21 @@ async function removeStaleFetchLock(lockDir: string): Promise<void> {
 	}
 }
 
+async function readFetchLockOwner(
+	lockDir: string,
+): Promise<{ ownerId?: string } | undefined> {
+	try {
+		const parsed = JSON.parse(
+			await readFile(resolve(lockDir, "owner.json"), "utf8"),
+		) as unknown;
+		return isRecord(parsed) && typeof parsed.ownerId === "string"
+			? { ownerId: parsed.ownerId }
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 async function readDurableFetchFailure(
 	config: WorkflowWebSourceCacheConfig,
 	key: string,

package/src/workflow-web-source.ts

@@ -10,6 +10,8 @@ import {
 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" as const;
 export const WORKFLOW_WEB_SOURCE_INDEX_SCHEMA =
@@ -150,7 +152,7 @@ export const DEFAULT_WORKFLOW_WEB_SECURITY_POLICY: WorkflowWebSecurityPolicy = {
 };
 
 const SENSITIVE_QUERY_PARAM_PATTERN =
-	/(^|[-_])(access[-_]?token|auth|code|credential|key|password|secret|session|signature|sig|token)([-_]|$)/i;
+	/(^|[-_])(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\./,
@@ -331,7 +333,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,
@@ -602,14 +604,14 @@ export function extractTextFromToolResult(result: unknown): string {
 	if (!isRecord(result)) return "";
 	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(
@@ -712,7 +714,7 @@ function sourceToIndexEntry(
 		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 } : {}),
@@ -1066,9 +1068,18 @@ function consumeAnchoredSnippet(options: {
 		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,
@@ -1105,7 +1116,15 @@ function normalizeForSearch(text: string): {
 			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: string, needle: string, maxChars: number): string {
@@ -1216,7 +1235,9 @@ function sourceIndexEntryFromUnknown(
 		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 } : {}),
@@ -1375,7 +1396,10 @@ function redactInlineSecrets(value: string): string {
 function redactInlineSecretsNoUrls(value: string): string {
 	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");
 }
 

package/workflows/README.md

@@ -22,7 +22,9 @@ For spec-less direct dynamic execution, use `/workflow dynamic "<task>"`; it doe
 | `spec-review` | `scout` | Use when you want to check whether requirements, an API spec, or a contract are reflected in the implementation and tests. |
 | `impact-review` | `scout` | Use before merging or releasing a change to check affected areas, risks, missing tests, and missing docs. |
 
-More official workflows are planned. Experimental or candidate workflows should live outside the bundled `workflows/` directory until their task fit is validated.
+Experimental or candidate workflows should live outside the bundled `workflows/` directory until their task fit is validated. `deep-research` also ships a path-ref-only batched verification variant at `workflows/deep-research/batched-verification.spec.json`; it is intentionally not registered as an official workflow name and must be invoked by explicit path after validation.
+
+Bundled workflows that verify source-backed claims can share the verification outcome ontology exported by the package: `verified`, `partially_supported`, `unsupported`, `conflicting`, and `verification_blocked`. Workflow helpers should keep dependency-free bundle-local shims in parity with that package export, because helper imports are bundled from the workflow spec directory. `verification_blocked` means verification could not complete because evidence, tool, source-access, or policy conditions blocked evaluation; it is never counted as verified. Deep-research adopts this ontology now. Workflows with different verdict models, such as finding disposition or ship readiness, should not be forced into it. Deep-diff-review revival is intentionally out of scope for this ontology update.
 
 ## Bundle layout
 
@@ -45,30 +47,10 @@ Bundle names resolve from the directory name (`/workflow run name ...`). If two
 
 Artifact-graph workflows use `from` for data edges, `after` for order-only edges, and `type: "dag"` containers for nested sibling-scoped graphs. A downstream stage consumes a container with `from: "analysis"`, which resolves to the container's `outputFrom` child. See `docs/usage.md` for the full DAG example, artifact bundle rules, and validation rules.
 
-## Support helpers
-
-A support node runs local helper code inline instead of launching a subagent. Declare it with a `support` object, not a separate `type` value:
-
-```json
-{
-  "id": "audit-claims",
-  "from": "verify-claims",
-  "sourcePolicy": "partial",
-  "support": {
-    "uses": "./helpers/claim-evidence-gate.mjs",
-    "options": { "downgradeExactQuantitativeWithoutSource": true }
-  }
-}
-```
-
-Helper API:
+## Support helpers and web tools
 
-```js
-export default async function helper({ sources, options, context }) {
-  return { schema: "helper-output-v1", digest: "...", value: { /* control data */ } };
-}
-```
+Support nodes run bundle-local `.mjs` helper code inline instead of launching a subagent (deep-research uses them to compact normalize inputs and preserve audited verdict/sourceRef ledgers). Bundled workflows prefer the normalized web-source tools (`workflow_web_search`, `workflow_web_fetch_source`, `workflow_web_source_read`) over legacy web tools.
 
-Helper refs are intentionally directory-local only. Allowed refs start with `./` and point to `.mjs` files inside the workflow bundle directory. Parent-directory refs, absolute paths, home-relative paths, protocol refs (`file://`, `https://`), and `npm:` refs are rejected. This is containment and reproducibility, not a sandbox: helper code still runs inside the workflow process and is not constrained by subagent tool allowlists.
+Legacy `fetch_content` workflow tasks use a run-scoped cache and a configurable inline text cap to reduce worker context pressure.
 
-Workflow runs now prefer normalized web-source tools: `workflow_web_search`, `workflow_web_fetch_source`, and `workflow_web_source_read`. Normalized web sources are stored inside `.pi/workflows/<run-id>/web-source-cache/`, model-visible tool results expose only compact cards/source refs/snippets, and agents should use `workflow_web_source_read` instead of reading cache files directly. Batch several source fetches with `urls: [...]` or `sources: [...]`, and batch several snippets from one sourceRef with `queries: [...]` or `reads: [...]` to reduce repeated tool turns; use `claim` plus distinctive `terms` for candidate quote windows with match metadata when the exact quote is unknown. Deep-research also uses support helpers to compact normalize inputs and preserve audited verdict/sourceRef ledgers before final synthesis. Custom extension `fetch_content` providers are disabled by default for normalized source fetches unless the workflow security policy explicitly trusts private-host behavior; this avoids accepting opaque provider network fetches as SSRF-safe. Legacy `fetch_content` tasks still use `.pi/workflows/<run-id>/source-cache/fetch-content/`; set `PI_WORKFLOW_FETCH_CONTENT_CACHE=0` to opt out for a run. Treat cache-enabled benchmark runs as a separate cohort from older uncached measurements.
+See `docs/usage.md` for the support helper API and path-containment rules ("Support helpers") and for web tool semantics, batching, cache layout, and the `fetch_content` security policy ("Run-scoped web-source cache" and "Web tools").