pi-crew 0.11.6 → 0.11.7

package/src/runtime/rpc/rpc-worker.ts

@@ -0,0 +1,151 @@
+/**
+ * rpc-worker.ts — W7 (P2-3): EXPERIMENTAL RPC worker transport (prototype).
+ *
+ * STATUS — NOT WIRED INTO LIVE DISPATCH (honest prototype):
+ * `runWorker` (run-worker.ts) consults {@link resolveWorkerTransport}; when it
+ * resolves "rpc" the seam currently returns a structured not-implemented
+ * result instead of calling {@link runRpcWorker}. Reason: this lane is
+ * forbidden from live-spawning pi (Round-2 evidence already covers the live
+ * probes; unit tests use fake streams only), so the live path would ship
+ * completely unvalidated. Flipping the seam to call runRpcWorker is the
+ * integration-phase follow-up AFTER a live-fire probe (see README.md).
+ *
+ * runRpcWorker itself is complete and fake-stream tested:
+ *   prompt → collect session events until `agent_settled` → orderly stop →
+ *   map to ChildPiRunResult. Abort/steer signals send the RPC `abort` command
+ *   before stopping.
+ */
+
+import { getCrewEnv } from "../../config/env-vars.ts";
+import type { ChildPiRunResult } from "../child-pi/child-pi.ts";
+import { createRpcFrameClient, type RpcFrameClientOptions } from "./frame-client.ts";
+import type { DialogAnswerPolicy } from "./ui-request-policy.ts";
+
+/** Env knob selecting the transport at the run-worker seam. */
+export const WORKER_TRANSPORT_ENV = "PI_CREW_WORKER_TRANSPORT";
+/** Env knob for the dialog auto-answer policy (GATE 2). */
+export const RPC_DIALOG_ANSWER_ENV = "PI_CREW_RPC_DIALOG_ANSWER";
+
+export type WorkerTransport = "stdio" | "rpc";
+
+/** Minimal surface of runWorker's input the RPC path consumes. */
+export interface RpcWorkerInput {
+	cwd?: string;
+	task: string;
+	model?: string;
+	signal?: AbortSignal;
+	/** Optional client overrides (tests inject a fake spawner + tiny timeouts). */
+	rpc?: Pick<RpcFrameClientOptions, "spawnFn" | "argv" | "commandTimeoutMs" | "stopTimeoutMs" | "dialogPolicy">;
+}
+
+/**
+ * Resolve the worker transport. The env var is the live prototype gate
+ * (runWorker has no config access — packet §A); the `runtime.workerTransport`
+ * config key is declared in config-schema.ts/types.ts and reaches this seam
+ * in the integration phase. FAILSAFE: anything other than exactly "rpc"
+ * (after trim) resolves to the default stdio transport.
+ */
+export function resolveWorkerTransport(read: (name: string) => string | undefined = getCrewEnv): WorkerTransport {
+	const raw = read(WORKER_TRANSPORT_ENV);
+	return raw?.trim() === "rpc" ? "rpc" : "stdio";
+}
+
+/**
+ * Resolve the dialog auto-answer policy (GATE 2). "cancel" (default) is the
+ * universal safe answer; "block" leaves the server promise pending on purpose
+ * (debugging). Auto-confirm is deliberately NOT a policy (security gate — see
+ * ui-request-policy.ts). Invalid values fail safe to "cancel".
+ */
+export function resolveDialogAnswerPolicy(read: (name: string) => string | undefined = getCrewEnv): DialogAnswerPolicy {
+	return read(RPC_DIALOG_ANSWER_ENV)?.trim() === "block" ? "block" : "cancel";
+}
+
+interface SettleTracking {
+	lastAssistantText: string | undefined;
+	settled: boolean;
+}
+
+function extractAssistantText(message: unknown): string | undefined {
+	if (typeof message !== "object" || message === null) return undefined;
+	const role = (message as { role?: unknown }).role;
+	if (role !== "assistant") return undefined;
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return undefined;
+	const parts: string[] = [];
+	for (const part of content) {
+		if (typeof part === "object" && part !== null && (part as { type?: unknown }).type === "text") {
+			const text = (part as { text?: unknown }).text;
+			if (typeof text === "string") parts.push(text);
+		}
+	}
+	return parts.length > 0 ? parts.join("\n") : undefined;
+}
+
+/**
+ * Run one worker turn over the RPC frame transport (EXPERIMENTAL prototype —
+ * see module header). Never spawned by production dispatch in this lane.
+ */
+export async function runRpcWorker(input: RpcWorkerInput): Promise<ChildPiRunResult> {
+	const tracking: SettleTracking = { lastAssistantText: undefined, settled: false };
+	let settleResolve: (() => void) | undefined;
+	const settledPromise = new Promise<void>((resolve) => {
+		settleResolve = resolve;
+	});
+	let abortError: Error | undefined;
+
+	const overrides = input.rpc ?? {};
+	const client = createRpcFrameClient({
+		...overrides,
+		dialogPolicy: overrides.dialogPolicy ?? resolveDialogAnswerPolicy(),
+		onEvent: (event) => {
+			const record = event as { type?: unknown; message?: unknown };
+			if (record?.type === "message_end") {
+				const text = extractAssistantText(record.message);
+				if (text !== undefined) tracking.lastAssistantText = text;
+			} else if (record?.type === "agent_settled") {
+				tracking.settled = true;
+				settleResolve?.();
+			}
+		},
+	});
+
+	const onAbort = () => {
+		// Ask the server to abort the current run, then stop orderly. The
+		// command may race the shutdown — a rejection is expected and logged.
+		client
+			.sendCommand({ type: "abort" })
+			.catch((error: Error) => {
+				abortError = error;
+			})
+			.finally(() => {
+				// biome-ignore lint/suspicious/noEmptyBlockStatements: stop() never rejects by design — void-append .catch per lane rules.
+				void client.stop().catch(() => {});
+				settleResolve?.();
+			});
+	};
+	input.signal?.addEventListener("abort", onAbort, { once: true });
+
+	let runError: string | undefined;
+	try {
+		await client.sendCommand({ type: "prompt", message: input.task });
+		await settledPromise;
+	} catch (error) {
+		runError = error instanceof Error ? error.message : String(error);
+	} finally {
+		input.signal?.removeEventListener("abort", onAbort);
+		// biome-ignore lint/suspicious/noEmptyBlockStatements: stop() never rejects by design — void-append .catch per lane rules.
+		await client.stop().catch(() => {});
+	}
+
+	const exitCode = await client.exited();
+	const result: ChildPiRunResult = {
+		exitCode,
+		stdout: client.stdoutText(),
+		stderr: client.stderrText(),
+	};
+	if (runError) result.error = runError;
+	else if (abortError && !tracking.settled) result.error = `rpc abort failed: ${abortError.message}`;
+	if (tracking.lastAssistantText !== undefined) result.rawFinalText = tracking.lastAssistantText;
+	if (input.signal?.aborted) result.aborted = true;
+	return result;
+}

package/src/runtime/rpc/ui-request-policy.ts

@@ -0,0 +1,112 @@
+/**
+ * ui-request-policy.ts — W7 (P2-3) RPC transport: the two Round-2 design gates.
+ *
+ * Evidence base (read directly from the SDK's rpc-mode.js during W7 recon):
+ *
+ *  GATE 1 — extension_ui_request DRAIN (fire-and-forget methods):
+ *    `notify` (rpc-mode.js:87-96), `setStatus` (:101-110), `setWidget`
+ *    (:123+), `setTitle`, `set_editor_text` are emitted WITHOUT being
+ *    registered in `pendingExtensionRequests` — the server never waits for
+ *    a response. Round-2 live evidence: 15 of the first 16 records a worker
+ *    emits are these. Drain policy = COUNT + DROP (a response would be
+ *    harmlessly ignored by the server, but sending one is pure waste).
+ *
+ *  GATE 2 — DIALOG auto-answer (ask-over-RPC otherwise blocks forever):
+ *    `select` / `confirm` / `input` (:84-86) and `editor` (:191) register a
+ *    promise in `pendingExtensionRequests` (:70-76). If the client never
+ *    answers and the request has no `timeout`, the server-side promise NEVER
+ *    resolves — the worker deadlocks (R2.5 ask-tool deadlock caveat).
+ *    Universal safe answer: `{type:"extension_ui_response", id, cancelled:true}`
+ *    → server resolves select/input to undefined and confirm to false.
+ *
+ *  SECURITY GATE (deliberate, review-mandated): there is NO auto-approve /
+ *  auto-confirm mode. An unattended transport must never answer "yes" on the
+ *  user's behalf. If a confirm-approval mode is ever needed it must be an
+ *  explicit opt-in with its own security review — do not add it here.
+ */
+
+import type { RpcExtensionUIRequest, RpcExtensionUIResponse } from "@earendil-works/pi-coding-agent";
+
+/** Dialog answer policy. See module header GATE 2 + SECURITY GATE. */
+export type DialogAnswerPolicy = "cancel" | "block";
+
+/** UI-request methods the server emits fire-and-forget (never pending). */
+export const FIRE_AND_FORGET_UI_METHODS: ReadonlySet<string> = new Set(["notify", "setStatus", "setWidget", "setTitle", "set_editor_text"]);
+
+/** UI-request methods that register a pending server-side promise (block until answered). */
+export const DIALOG_UI_METHODS: ReadonlySet<string> = new Set(["select", "confirm", "input", "editor"]);
+
+/** Counters surfaced for diagnostics + tests (packet §E instrumentation set). */
+export interface UiRequestCounters {
+	/** Fire-and-forget records drained (counted, then dropped). */
+	uiRequestsDrained: number;
+	/** Drain breakdown by method (e.g. setStatus / setWidget). */
+	drainedByMethod: Record<string, number>;
+	/** Dialogs answered with the universal safe answer (`cancelled:true`). */
+	dialogsCancelled: number;
+	/** Dialogs left unanswered on purpose (policy "block" — server promise stays pending). */
+	dialogsBlocked: number;
+}
+
+export interface UiRequestPolicy {
+	/** Apply the drain/answer policy to one incoming ui-request record. */
+	handle(request: RpcExtensionUIRequest): void;
+	/** Snapshot of the counters (fresh object each call). */
+	counters(): UiRequestCounters;
+}
+
+export interface UiRequestPolicyOptions {
+	/** GATE 2 policy. "cancel" (default): answer `cancelled:true`. "block": leave pending (debug). */
+	dialogPolicy: DialogAnswerPolicy;
+	/** Sink for ui-responses the policy decides to send (the client's stdin writer). */
+	writeResponse: (response: RpcExtensionUIResponse) => void;
+	/** Optional warn sink (policy decisions worth surfacing). */
+	onWarn?: (message: string) => void;
+}
+
+/**
+ * Build the drain/answer policy for one RPC frame client.
+ *
+ * Unknown methods (future SDK additions) are treated as fire-and-forget:
+ * counted into `uiRequestsDrained` and dropped — never answered, because we
+ * cannot know whether the server put them in the pending map. A stray answer
+ * is harmless to the server, but staying silent is the conservative default
+ * for anything we have not classified.
+ */
+export function createUiRequestPolicy(options: UiRequestPolicyOptions): UiRequestPolicy {
+	const dialogPolicy = options.dialogPolicy === "block" ? "block" : "cancel";
+	const drainedByMethod: Record<string, number> = {};
+	let uiRequestsDrained = 0;
+	let dialogsCancelled = 0;
+	let dialogsBlocked = 0;
+
+	return {
+		handle(request: RpcExtensionUIRequest): void {
+			const method: string = request.method;
+			if (DIALOG_UI_METHODS.has(method)) {
+				if (dialogPolicy === "block") {
+					dialogsBlocked++;
+					options.onWarn?.(
+						`rpc dialog ${method} (${request.id}) left unanswered by policy "block" — server promise stays pending`,
+					);
+					return;
+				}
+				dialogsCancelled++;
+				// Universal safe answer: select/input → undefined, confirm → false.
+				options.writeResponse({ type: "extension_ui_response", id: request.id, cancelled: true });
+				return;
+			}
+			// GATE 1: fire-and-forget (or unknown) — count + drop.
+			uiRequestsDrained++;
+			drainedByMethod[method] = (drainedByMethod[method] ?? 0) + 1;
+		},
+		counters(): UiRequestCounters {
+			return {
+				uiRequestsDrained,
+				drainedByMethod: { ...drainedByMethod },
+				dialogsCancelled,
+				dialogsBlocked,
+			};
+		},
+	};
+}

package/src/runtime/run-worker.ts

@@ -28,6 +28,7 @@
 
 import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi/child-pi.ts";
 import { runChildPi } from "./child-pi/child-pi.ts";
+import { resolveWorkerTransport } from "./rpc/rpc-worker.ts";
 import { withWorkerSlot } from "./scheduling/global-worker-cap.ts";
 
 /**
@@ -71,6 +72,19 @@ export interface WorkerSpawnInput extends ChildPiRunInput {
  */
 export async function runWorker(input: WorkerSpawnInput): Promise<ChildPiRunResult> {
 	const { cap = true, ...childPiInput } = input;
+	// W7 (P2-3) EXPERIMENTAL transport seam: PI_CREW_WORKER_TRANSPORT=rpc
+	// selects the prototype RPC transport. NOT wired live yet — the module
+	// (src/runtime/rpc/, fake-stream tested only) stands beside production and
+	// the seam returns a structured not-implemented result so nobody can
+	// mistake the prototype for an active transport. Default/invalid env →
+	// stdio path below, byte-identical to the pre-W7 behavior. No worker-cap
+	// slot is taken for the not-implemented return (nothing spawns).
+	if (resolveWorkerTransport() === "rpc") {
+		const message =
+			"rpc worker transport requested (PI_CREW_WORKER_TRANSPORT=rpc) but live wiring is not implemented yet — W7 prototype module src/runtime/rpc/ is fake-stream tested only; unset PI_CREW_WORKER_TRANSPORT to use the default stdio transport";
+		console.error(`[pi-crew:run-worker.rpc-transport] ${message}`);
+		return { exitCode: null, stdout: "", stderr: "", error: message };
+	}
 	if (cap) {
 		// RR-014 / F15: thread the caller's signal into the slot WAIT itself.
 		// Previously the signal lived only inside childPiInput and was read by

package/src/runtime/surface/surface-spawn.ts

@@ -270,7 +270,14 @@ export async function prepareSurfaceSpawn(input: PrepareSurfaceSpawnInput): Prom
 			throw new Error("provider does not implement sendCommand — cannot boot a commandless pane");
 		}
 		const tuiArgs = stripHeadlessModeArgs(input.piArgs);
-		const spawnSpec = (input.deps?.resolveCommand ?? getPiSpawnCommand)(tuiArgs);
+		// P0-1 (pi 1.0.0 — review R2.1 2026-10-03): pin TUI mode `regular`.
+		// 1.0.0 đổi default sang fullscreen; alt-screen làm rỗng scrollback mà
+		// readScreen (tmux capture-pane -S) đang scrape → mất history pane.
+		// Flag có từ pi 0.84.0, dưới tested floor 0.99.2 của pi-crew → thêm vô
+		// điều kiện (pi strict parser REJECT flag lạ — note buildPiWorkerArgs,
+		// pi-args.ts). Caller đã set --tui-mode thì tôn trọng, không nhân đôi.
+		const tuiSpawnArgs = tuiArgs.includes("--tui-mode") ? tuiArgs : [...tuiArgs, "--tui-mode", "regular"];
+		const spawnSpec = (input.deps?.resolveCommand ?? getPiSpawnCommand)(tuiSpawnArgs);
 		// Env export = worker env đầy đủ (parity headless) + các biến surface.
 		// Không stateRoot (spawn ngoài run) → không có event log để ghi — bỏ key
 		// thay vì đường dẫn tương đối sai layout agents/{taskId}/events.jsonl.

package/src/runtime/task-output-context.ts

@@ -41,6 +41,12 @@ export interface DependencyContextEntry {
 	 *  the workflow (earlier deps = higher relevance because they were
 	 *  explicitly listed first). Defaults to 0.5 (neutral) when unknown. */
 	relevance?: number;
+	/** Handoff-budget marker: set by {@link applyHandoffBudget} when this
+	 *  entry was downgraded to the compact form (taskId/role/status + summary
+	 *  head ≤240 chars + artifact pointer). The render path emits the compact
+	 *  block for marked entries; `writeTaskInputsArtifact` still serializes the
+	 * ORIGINAL (untrimmed) context — the trim is render-only, never persisted. */
+	budgetTrimmed?: boolean;
 }
 
 export interface DependencyOutputContext {
@@ -58,6 +64,12 @@ export interface DependencyOutputContext {
 		content: string;
 		fullOutputPath?: string;
 	}>;
+	/** Run id (from the team manifest). Populated by
+	 *  `collectDependencyOutputContext` so the handoff-budget trim can build
+	 *  artifact pointers (`artifacts/<runId>/results/<taskId>.txt`). Optional
+	 *  for backward-compat with hand-built fixtures; without it trimmed deps
+	 *  simply omit the pointer line. */
+	runId?: string;
 }
 
 function containedExists(filePath: string, baseDir?: string): boolean {
@@ -523,7 +535,7 @@ export function collectDependencyOutputContext(
 	// outputs with compact digest notices before injecting into the worker
 	// prompt. OPT-IN: default config protects recent results.
 	const sharedReads = pruneSharedReads(rawSharedReads, trimmedDependencies, manifest.artifactsRoot);
-	return { dependencies: trimmedDependencies, sharedReads };
+	return { dependencies: trimmedDependencies, sharedReads, runId: manifest.runId };
 }
 
 // ADR-5 §trust-fence: dependency output is DATA, never instructions. Mirror the
@@ -536,46 +548,193 @@ function sanitizeFencedBody(body: string): string {
 	return body.replace(DEPENDENCY_CONTROL_CHAR_PATTERN, "").replace(/<\/dependency-context/g, "&lt;/dependency-context");
 }
 
-export function renderDependencyOutputContext(context: DependencyOutputContext): string {
+// ── Handoff budget (est-token cap on this layer) ─────────────────────────────
+
+/** Default est-token budget for the dynamic.dependencyContext layer. */
+export const DEFAULT_HANDOFF_BUDGET_TOKENS = 1800;
+/** Budget ceiling: a resolved budget above this is treated as the off-switch
+ *  (same semantics as ≤0 — clearly not a real handoff cap, so render
+ *  untrimmed instead of guessing). */
+export const HANDOFF_BUDGET_CEILING_TOKENS = 1_000_000;
+/** Summary head kept per dependency when the budget trims it. */
+export const HANDOFF_SUMMARY_HEAD_CHARS = 240;
+
+/** Strict integer env syntax — "12abc" must NOT parse as 12. */
+const HANDOFF_BUDGET_ENV_RE = /^[+-]?\d+$/;
+
+/** Est tokens = chars/4 — the same heuristic as `estimateTokens` in
+ *  src/runtime/task-runner/prompt-builder.ts (SR-02 breakdown). Duplicated
+ *  here instead of imported: importing prompt-builder would pull its
+ *  retrieval/workspace-tree graph into every task-output-context consumer
+ *  (post-execution, aggregate outputs) for a one-line heuristic. Keep the
+ *  two in sync if either changes. */
+function estimateHandoffTokens(chars: number): number {
+	return Math.round(chars / 4);
+}
+
+/** Budget active iff it is a positive finite number at or below the ceiling;
+ *  ≤0 or >ceiling = off-switch (render untrimmed). */
+function handoffBudgetActive(budgetTokens: number): boolean {
+	return Number.isFinite(budgetTokens) && budgetTokens > 0 && budgetTokens <= HANDOFF_BUDGET_CEILING_TOKENS;
+}
+
+/** Resolve the handoff budget: env PI_CREW_HANDOFF_BUDGET_TOKENS beats the
+ *  configured value, which beats the default (1800). A non-numeric/invalid
+ *  env string NEVER throws — it falls through to config/default. The resolved
+ *  number may still be ≤0 or >1_000_000 (off-switch at the render site). */
+export function resolveHandoffBudgetTokens(configured: number | undefined): number {
+	const raw = getCrewEnv("PI_CREW_HANDOFF_BUDGET_TOKENS");
+	if (raw !== undefined) {
+		const trimmed = raw.trim();
+		if (HANDOFF_BUDGET_ENV_RE.test(trimmed)) {
+			const parsed = Number.parseInt(trimmed, 10);
+			if (Number.isFinite(parsed)) return parsed;
+		}
+	}
+	return configured ?? DEFAULT_HANDOFF_BUDGET_TOKENS;
+}
+
+/** Full-form render lines for one dependency (pre-sanitize). */
+function dependencyEntryLines(dep: DependencyContextEntry): string[] {
+	const lines: string[] = [
+		`## ${dep.taskId} (${dep.role})`,
+		`Status: ${dep.status}`,
+		dep.resultPath ? `Result artifact: ${dep.resultPath}` : "",
+		"",
+		dep.resultSummary?.trim() || "(no result output)",
+		"",
+	];
+	// P1-A dependency tee-recovery hint: when the dependency's result was
+	// materially truncated (>1.25× MAX_RESULT_INLINE_BYTES) the full RAW
+	// content was teed to fullOutputPath. Mirrors the sharedReads hint so the
+	// downstream worker can read the dropped middle instead of re-deriving.
+	if (dep.fullOutputPath) lines.push(`Full output (if you need the missing middle): ${dep.fullOutputPath}`, "");
+	if (dep.structuredResults) lines.push("Structured results:", JSON.stringify(dep.structuredResults, null, 2), "");
+	if (dep.artifactsProduced?.length) lines.push(`Artifacts produced: ${dep.artifactsProduced.join(", ")}`, "");
+	if (dep.usage)
+		lines.push(`Usage: ${dep.usage.inputTokens} input tokens, ${dep.usage.outputTokens} output tokens, ${dep.usage.durationMs}ms`, "");
+	return lines;
+}
+
+/** Compact handoff-budget form for one dependency (pre-sanitize): keeps the
+ *  taskId/role/status lines + a ≤240-char summary head (with a truncation
+ *  marker when the summary was longer) + a relative artifact pointer the
+ *  worker can `read`. Drops structuredResults, usage, artifactsProduced and
+ *  the absolute-path lines — all recoverable via the pointer. The pointer is
+ *  built ONLY from manifest-derived runId/taskId (same trust level as the
+ *  existing `## <taskId>` headers and the results/<taskId>.txt artifact
+ *  naming); dep-controlled content never reaches it. */
+function budgetTrimmedDependencyEntryLines(dep: DependencyContextEntry, runId: string | undefined): string[] {
+	const summary = dep.resultSummary?.trim() ?? "";
+	const head = summary.slice(0, HANDOFF_SUMMARY_HEAD_CHARS);
+	const body =
+		summary.length > HANDOFF_SUMMARY_HEAD_CHARS ? `${head}\n[trimmed, ${summary.length} chars total]` : summary || "(no result output)";
+	return [
+		`## ${dep.taskId} (${dep.role})`,
+		`Status: ${dep.status}`,
+		body,
+		...(runId ? [`full output: artifacts/${runId}/results/${dep.taskId}.txt`] : []),
+		"",
+	];
+}
+
+/** Full-form render lines for one shared read (pre-sanitize). */
+function sharedReadLines(read: { name: string; path: string; content: string; fullOutputPath?: string }): string[] {
+	const lines = [`## shared/${read.name}`, `Path: ${read.path}`];
+	// P1-A tee-recovery hint: when the file was materially truncated
+	// (>2× threshold) the full content was teed to fullOutputPath so the
+	// worker can read the dropped middle if needed. The path is inside
+	// artifactsRoot/tee/ and goes through the normal permission gate.
+	if (read.fullOutputPath) lines.push(`Full output (if you need the missing middle): ${read.fullOutputPath}`);
+	lines.push("", read.content.trim(), "");
+	return lines;
+}
+
+/** Build the unsanitized body parts for a (possibly budget-trimmed) context.
+ *  Shared by the renderer (sanitize path) and the budget estimator so the
+ *  estimate can never drift from what is actually rendered. */
+function buildDependencyOutputBodyParts(context: DependencyOutputContext): string[] {
 	const parts: string[] = [];
 	if (context.dependencies.length) {
 		parts.push("# Dependency Outputs", "");
 		for (const dep of context.dependencies) {
-			parts.push(
-				`## ${dep.taskId} (${dep.role})`,
-				`Status: ${dep.status}`,
-				dep.resultPath ? `Result artifact: ${dep.resultPath}` : "",
-				"",
-				dep.resultSummary?.trim() || "(no result output)",
-				"",
-			);
-			// P1-A dependency tee-recovery hint: when the dependency's result was
-			// materially truncated (>1.25× MAX_RESULT_INLINE_BYTES) the full RAW
-			// content was teed to fullOutputPath. Mirrors the sharedReads hint so the
-			// downstream worker can read the dropped middle instead of re-deriving.
-			if (dep.fullOutputPath) parts.push(`Full output (if you need the missing middle): ${dep.fullOutputPath}`, "");
-			if (dep.structuredResults) parts.push("Structured results:", JSON.stringify(dep.structuredResults, null, 2), "");
-			if (dep.artifactsProduced?.length) parts.push(`Artifacts produced: ${dep.artifactsProduced.join(", ")}`, "");
-			if (dep.usage)
-				parts.push(
-					`Usage: ${dep.usage.inputTokens} input tokens, ${dep.usage.outputTokens} output tokens, ${dep.usage.durationMs}ms`,
-					"",
-				);
+			parts.push(...(dep.budgetTrimmed ? budgetTrimmedDependencyEntryLines(dep, context.runId) : dependencyEntryLines(dep)));
 		}
 	}
 	if (context.sharedReads.length) {
 		parts.push("# Shared Run Context Reads", "");
-		for (const read of context.sharedReads) {
-			parts.push(`## shared/${read.name}`, `Path: ${read.path}`);
-			// P1-A tee-recovery hint: when the file was materially truncated
-			// (>2× threshold) the full content was teed to fullOutputPath so the
-			// worker can read the dropped middle if needed. The path is inside
-			// artifactsRoot/tee/ and goes through the normal permission gate.
-			if (read.fullOutputPath) parts.push(`Full output (if you need the missing middle): ${read.fullOutputPath}`);
-			parts.push("", read.content.trim(), "");
-		}
+		for (const read of context.sharedReads) parts.push(...sharedReadLines(read));
 	}
-	return sanitizeFencedBody(parts.join("\n").trim());
+	return parts;
+}
+
+/** Measure a candidate context in est tokens (chars/4), mirroring the render
+ *  byte-for-byte (same parts builder; `.trim()` matches the render join). */
+function measureHandoffTokens(context: DependencyOutputContext): number {
+	return estimateHandoffTokens(buildDependencyOutputBodyParts(context).join("\n").trim().length);
+}
+
+/**
+ * Handoff budget: trim the dependency-output context to an est-token
+ * (chars/4) budget. PURE — no I/O, no env reads (callers pass the resolved
+ * budget from {@link resolveHandoffBudgetTokens}); returns the input
+ * reference unchanged when the budget is off (≤0 or >1_000_000) or the
+ * context already fits.
+ *
+ * Trim policy (declaration order): dependencies are probed from ALL-full
+ * downward — the largest prefix of dependencies that still fits keeps its
+ * FULL output; every dependency after the cutoff is downgraded to the
+ * compact form (taskId/role/status + ≤240-char summary head + truncation
+ * marker + `artifacts/<runId>/results/<taskId>.txt` pointer). Earlier deps
+ * therefore always keep ≥ as much as later ones. Long (>240 chars) sharedRead
+ * bodies are replaced by a trim marker (the Path pointer is already
+ * rendered); short shared reads pass through.
+ *
+ * When even the fully-trimmed form exceeds the budget (extreme dependency
+ * count), the fully-trimmed context is returned as the bounded best effort —
+ * every entry is then ≤ ~240 chars + pointer, so the layer stays small and
+ * deterministic.
+ *
+ * Composes AFTER the L4 byte trim (`enforceDependencyInlineBudget`, 96KB,
+ * priority-ordered path-only downgrade) which runs at collect time and is
+ * untouched by this function.
+ */
+export function applyHandoffBudget(context: DependencyOutputContext, budgetTokens: number, runId?: string): DependencyOutputContext {
+	if (!handoffBudgetActive(budgetTokens)) return context;
+	const effectiveRunId = runId ?? context.runId;
+	const base: DependencyOutputContext =
+		effectiveRunId !== undefined && context.runId !== effectiveRunId ? { ...context, runId: effectiveRunId } : context;
+	if (measureHandoffTokens(base) <= budgetTokens) return base;
+	const trimmedRead = (read: { name: string; path: string; content: string; fullOutputPath?: string }) => {
+		const content = read.content.trim();
+		return content.length > HANDOFF_SUMMARY_HEAD_CHARS
+			? { ...read, content: `[content trimmed, ${content.length} chars total — read Path above for the full file]` }
+			: read;
+	};
+	const candidateAt = (fullCount: number): DependencyOutputContext => ({
+		...base,
+		dependencies: base.dependencies.map((dep, index) => (index < fullCount ? dep : { ...dep, budgetTrimmed: true })),
+		sharedReads: base.sharedReads.map(trimmedRead),
+	});
+	for (let fullCount = base.dependencies.length; fullCount >= 0; fullCount--) {
+		const candidate = candidateAt(fullCount);
+		if (measureHandoffTokens(candidate) <= budgetTokens) return candidate;
+	}
+	return candidateAt(0);
+}
+
+export interface RenderDependencyOutputContextOptions {
+	/** Configured budget (runtime.handoffBudgetTokens). Env
+	 *  PI_CREW_HANDOFF_BUDGET_TOKENS beats this value; when neither is set the
+	 *  default is 1800. A resolved value ≤0 or >1_000_000 disables the trim
+	 *  (off-switch). */
+	budgetTokens?: number;
+}
+
+export function renderDependencyOutputContext(context: DependencyOutputContext, opts: RenderDependencyOutputContextOptions = {}): string {
+	const budgetTokens = resolveHandoffBudgetTokens(opts.budgetTokens);
+	const effective = applyHandoffBudget(context, budgetTokens);
+	return sanitizeFencedBody(buildDependencyOutputBodyParts(effective).join("\n").trim());
 }
 
 export function writeTaskSharedOutput(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState): ArtifactDescriptor | undefined {

package/src/runtime/task-packet.ts

@@ -203,6 +203,9 @@ export const HANDOFF_TEMPLATE = [
 	"",
 	"### Follow-ups",
 	"<!-- Any remaining issues or next steps -->",
+	"",
+	"### Provenance",
+	"<!-- Self-report your runtime identity (pre-set in your bash tool env, one line): PI_SESSION_ID, PI_SESSION_FILE, PI_MODEL, PI_PROVIDER, PI_REASONING_LEVEL — e.g. `session=<id> model=<provider>/<model> reasoning=<level>` -->",
 ].join("\n");
 
 export interface ParsedHandoff {