pi-crew 0.11.6 → 0.11.7

package/src/runtime/task-runner/child-executor.ts

@@ -38,6 +38,7 @@ import { type FatalFsCause, failureCauseForAttempt } from "../../utils/fs-errno.
 import { logInternalError } from "../../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import type { ChildPiLifecycleEvent, ChildPiRunResult } from "../child-pi/child-pi.ts";
+import type { SessionRecoveryInfo } from "../child-pi/session-recovery.ts";
 import {
 	appendCrewAgentEventBuffered,
 	appendCrewAgentOutputBuffered,
@@ -398,7 +399,11 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 	const manifest: TeamRunManifest = ctx.manifest;
 	let task = ctx.task;
 	let tasks = ctx.tasks;
-	const prompt = ctx.prompt;
+	// R3-1: the child-pi worker's USER message is the dynamic suffix — the
+	// run-static header rides --append-system-prompt (compaction-safe).
+	// Fallback to the full prompt keeps hand-built contexts (tests, custom
+	// callers that skip pre-execution) on the old single-channel behavior.
+	const userPrompt = ctx.userPrompt ?? ctx.prompt;
 	const skillPaths = ctx.skillPaths;
 	const collectedJsonEvents = ctx.collectedJsonEvents;
 	const streamBridge: StreamBridgeHandle | undefined = ctx.streamBridge;
@@ -409,6 +414,9 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 	let modelAttempts: ModelAttemptSummary[] | undefined;
 	let parsedOutput: ParsedPiJsonOutput | undefined;
 	let rawFinalText: string | undefined;
+	// W2 (P1-1): last attempt's session-recovery provenance (thread-level,
+	// mirrors rawFinalText — escapes the attempt loop's block scope).
+	let recoveredFromSession: SessionRecoveryInfo | undefined;
 	let intermediateFindings: string | undefined;
 	let finalStdout = "";
 	let transcriptPath: string | undefined;
@@ -652,7 +660,12 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 		try {
 			childResult = await runWorker({
 				cwd: task.cwd,
-				task: prompt,
+				task: userPrompt,
+				systemPromptAppend: ctx.systemPromptAppend,
+				// R3-19/D5: thread the runtime.hermeticWorkers config gate to the
+				// worker argv (--no-extensions). Env PI_CREW_HERMETIC_WORKERS still
+				// overrides either way (resolveHermeticWorkers).
+				hermeticWorkers: input.runtimeConfig?.hermeticWorkers,
 				agent: input.agent,
 				model,
 				signal: timeoutController.signal,
@@ -665,6 +678,10 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 				parentContext: input.parentContext,
 				excludeContextBash: input.runtimeConfig?.excludeContextBash,
 				sessionId: manifest.sessionId,
+				// W2 (P1-1): thread the runtime.sessionRecovery flag so the config
+				// gate reaches the crash-path tail-replay (env/default still work
+				// without this — resolveSessionRecoveryEnabled precedence).
+				sessionRecovery: input.runtimeConfig?.sessionRecovery,
 				role: task.role,
 				thinkingOverride: input.teamRoleThinking,
 				runId: manifest.runId,
@@ -997,6 +1014,9 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 		const transcriptText = tailReadWithLineSnap(transcriptPath, MAX_TRANSCRIPT_PARSE_BYTES, childResult.stdout);
 		parsedOutput = parsePiJsonOutput(transcriptText);
 		rawFinalText = childResult.rawFinalText;
+		// W2 (P1-1): keep the most recent recovery info (crash-path only —
+		// undefined on clean exits, so this stays dormant in the happy path).
+		recoveredFromSession = childResult.recoveredFromSession ?? recoveredFromSession;
 		intermediateFindings = childResult.intermediateFindings;
 		error = attemptErrorFor(childResult, parsedOutput, task.id);
 		// bug-026 sub-issue B: classify fatal fs errnos (ENOSPC/EDQUOT/EMFILE/
@@ -1121,6 +1141,12 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 	const resultCandidates: ReadonlyArray<{ source: ResultSource; text: string | undefined }> = [
 		{ source: "rawFinalText", text: cleanResultText(rawFinalText) },
 		{ source: "finalText", text: cleanResultText(parsedOutput?.finalText) },
+		// W2 (P1-1): crash-path session tail-recovery. Ranks BELOW live captures
+		// (raw/finalText — the stream is authoritative when it survived) but
+		// ABOVE stdout/stderr noise: on signal death (exitCode null) the live
+		// captures are empty and this is the recovered last complete assistant
+		// message from the worker's session JSONL.
+		{ source: "session", text: cleanResultText(recoveredFromSession?.text) },
 		{ source: "stdout", text: cleanResultText(finalStdout) },
 		{ source: "stderr", text: cleanResultText(finalStderr) },
 		{ source: "findings", text: cleanResultText(intermediateFindings) },
@@ -1142,6 +1168,18 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 			"(no output)",
 		producer: task.id,
 	});
+	// W2 (P1-1): serialize the recovery provenance as a result sidecar — the
+	// recovered text itself flows through the "session" candidate above; this
+	// records WHERE it came from (session id/file, timestamp, stopReason) so
+	// crash-path recovery is auditable after the fact.
+	if (recoveredFromSession) {
+		writeArtifact(manifest.artifactsRoot, {
+			kind: "result",
+			relativePath: `results/${task.id}.session-recovery.json`,
+			content: JSON.stringify(recoveredFromSession, null, "\t"),
+			producer: task.id,
+		});
+	}
 	const logArtifact = writeArtifact(manifest.artifactsRoot, {
 		kind: "log",
 		relativePath: `logs/${task.id}.log`,

package/src/runtime/task-runner/post-execution.ts

@@ -86,16 +86,18 @@ export interface TaskExecutionResult {
 	terminalEvidence: OperationTerminalEvidence[];
 	startupEvidence: import("../heartbeat/worker-startup.ts").WorkerStartupEvidence;
 	/** Which child-executor fallback branch produced the result artifact
-	 *  content (rawFinalText → finalText → stdout → stderr → findings →
+	 *  content (rawFinalText → finalText → session → stdout → stderr → findings →
 	 *  "(no output)"). Finding #2 (2026-09-29 battery): "stderr"/"none" mean
 	 *  every authoritative worker output source was empty — finalizeTaskResult
 	 *  fails those DETERMINISTICALLY; the stderr-noise classifier stays a
-	 *  defense layer, never the verdict oracle. */
+	 *  defense layer, never the verdict oracle. "session" (W2/P1-1) = the text
+	 *  was tail-recovered from the worker's session JSONL on a signal-death
+	 *  crash path — authoritative recovered output, not a failure source. */
 	resultSource?: ResultSource;
 }
 
 /** Result-artifact provenance tags (see {@link TaskExecutionResult.resultSource}). */
-export type ResultSource = "rawFinalText" | "finalText" | "stdout" | "stderr" | "findings" | "none";
+export type ResultSource = "rawFinalText" | "finalText" | "session" | "stdout" | "stderr" | "findings" | "none";
 
 /** Final persisted task state returned by finalizeTaskResult. */
 export interface FinalTaskResult {

package/src/runtime/task-runner/pre-execution.ts

@@ -69,6 +69,17 @@ export interface TaskExecutionContext {
 	skillNames: string[] | undefined;
 	skillPaths: string[] | undefined;
 	prompt: string;
+	/** R3-1: the USER-message half of the rendered prompt (dynamicSuffix) —
+	 *  what the worker's task.md actually carries when the run-static header
+	 *  moves to the --append-system-prompt channel. `prompt` stays the FULL
+	 *  rendered prompt (stablePrefix + dynamicSuffix) for artifacts and the
+	 *  live-session path. Optional so hand-built contexts (tests, custom
+	 *  callers) keep the old single-channel behavior via the ?? fallback. */
+	userPrompt?: string;
+	/** R3-1: run-static worker header (stablePrefix) for the append-system-prompt
+	 *  channel — threaded to buildPiWorkerArgs via ChildPiRunInput. Undefined on
+	 *  hand-built contexts → single-channel legacy behavior. */
+	systemPromptAppend?: string;
 	promptArtifact: ArtifactDescriptor;
 	/** G18: prompt-breakdown artifact descriptor (undefined when PI_CREW_PROMPT_BREAKDOWN off). */
 	breakdownArtifact?: ArtifactDescriptor;
@@ -141,7 +152,14 @@ export async function prepareTaskExecutionContext(
 	// caller provided one) into the dep-context collection — cache hits reuse
 	// the closeout's reads byte-identically; undefined keeps uncached behavior.
 	const dependencyContext = collectDependencyOutputContext(manifest, input.tasks, input.task, input.step, input.resultReadCache);
-	const dependencyContextText = input.dependencyContextText ?? renderDependencyOutputContext(dependencyContext);
+	// Handoff budget: caps the dynamic.dependencyContext layer at an est-token
+	// (chars/4) budget (env PI_CREW_HANDOFF_BUDGET_TOKENS > runtime config >
+	// default 1800). IMPORTANT: only the RENDER path is budgeted — an explicit
+	// input.dependencyContextText override (leader-provided text) passes through
+	// UNCHANGED.
+	const dependencyContextText =
+		input.dependencyContextText ??
+		renderDependencyOutputContext(dependencyContext, { budgetTokens: input.runtimeConfig?.handoffBudgetTokens });
 	let task: TeamTaskState = {
 		...input.task,
 		cwd: workspace.cwd,
@@ -435,6 +453,11 @@ export async function prepareTaskExecutionContext(
 			collectedJsonEvents,
 			streamBridge,
 			startupEvidence,
+			// R3-1: channel split for child-pi workers — user message = dynamic
+			// suffix; run-static header = system-prompt append channel (compaction
+			// summarizes the user-message span, compaction.md:150-160).
+			userPrompt: promptResult.dynamicSuffix,
+			systemPromptAppend: promptResult.stablePrefix,
 		},
 	};
 }

package/src/runtime/task-runner/prompt-builder.ts

@@ -275,11 +275,14 @@ export interface RenderedTaskPrompt {
 	/** Full rendered prompt (stablePrefix + dynamicSuffix). */
 	full: string;
 	/**
-	 * SR-02 phase 1 (2026-09-23): per-section char counts of the USER prompt,
+	 * SR-02 phase 1 (2026-09-23): per-section char counts of the worker prompt,
 	 * keyed by section name — the token-breakdown instrumentation. Populated
 	 * only when PI_CREW_PROMPT_BREAKDOWN=1 (off by default; zero cost when off:
 	 * the sections object is built lazily). Pre-execution adds the SYSTEM-side
 	 * pieces (agent definition, skills) and writes the JSON artifact.
+	 * R3-1 note: stable.* sections ride the --append-system-prompt channel;
+	 * total.userPrompt counts the user message (dynamic suffix) only, while
+	 * total.systemAppend counts the system-channel header.
 	 */
 	sections?: Record<string, number>;
 }
@@ -424,6 +427,8 @@ export async function renderTaskPrompt(
 	const full = [stablePrefix, "", dynamicSuffix].join("\n");
 	const sections: Record<string, number> | undefined = promptBreakdownEnabled()
 		? {
+				// R3-1: the stable.* sections now ride the --append-system-prompt
+				// channel; the worker's user message is the dynamic suffix only.
 				"stable.runtimeHeader": headerBlock.length,
 				"stable.protocol": protocolBlock.length,
 				"stable.roleInstructions": roleInstructions.length,
@@ -440,7 +445,10 @@ export async function renderTaskPrompt(
 				"dynamic.memory": memoryBlock.length,
 				"dynamic.outputSchema": outputSchemaBlock.length,
 				"dynamic.taskAndHandoff": taskAndHandoff.length,
-				"total.userPrompt": full.length,
+				// R3-1: channel split — the user message carries ONLY the dynamic
+				// suffix; the stable prefix went to the system-prompt append channel.
+				"total.systemAppend": stablePrefix.length,
+				"total.userPrompt": dynamicSuffix.length,
 			}
 		: undefined;
 	return { stablePrefix, dynamicSuffix, full, sections };

package/src/schema/config-schema.ts

@@ -75,6 +75,18 @@ export const PiTeamsRuntimeConfigSchema = Type.Object(
 		graceTurns: Type.Optional(Type.Integer({ minimum: 1 })),
 		taskTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
 		inheritContext: Type.Optional(Type.Boolean({ sensitive: true })),
+		// W2 (session-file recovery): when a worker dies without a final assistant
+		// event (exitCode null / killed), tail-replay its session JSONL and attach
+		// the last complete assistant record to the run result. Default ON; env
+		// PI_CREW_SESSION_RECOVERY overrides. Kill switch, not a secret — no
+		// sensitive mark (same policy as surface: picks behavior, not authority).
+		sessionRecovery: Type.Optional(Type.Boolean()),
+		// R3-19/D5 reversal: hermetic worker spawns (--no-extensions on worker
+		// argv; explicit -e prompt-runtime + --skill flags unaffected). Default
+		// TRUE — off-switch for operators who want the old ambient-stack parity.
+		// Env PI_CREW_HERMETIC_WORKERS overrides either way. Behavior pick, not
+		// authority — no sensitive mark.
+		hermeticWorkers: Type.Optional(Type.Boolean()),
 		promptMode: Type.Optional(Type.Union([Type.Literal("replace"), Type.Literal("append")])),
 		groupJoin: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("group"), Type.Literal("smart")])),
 		groupJoinAckTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
@@ -94,6 +106,10 @@ export const PiTeamsRuntimeConfigSchema = Type.Object(
 			),
 		),
 		excludeContextBash: Type.Optional(Type.Boolean()),
+		// Handoff budget: est-token (chars/4) cap on the dynamic.dependencyContext
+		// prompt layer. Matches parseHandoffBudgetTokens in config-validation.ts
+		// (out-of-range values are dropped → render default 1800).
+		handoffBudgetTokens: Type.Optional(Type.Integer({ minimum: 1, maximum: 1_000_000 })),
 		agentExtensions: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { sensitive: true })),
 		// Mux-surface policy (spec v0.7 §8.2.4): no sensitive marks — surface
 		// picks where worker processes live, not what they may do.
@@ -118,6 +134,15 @@ export const PiTeamsRuntimeConfigSchema = Type.Object(
 			),
 		),
 		modelFallback: Type.Optional(PiTeamsModelFallbackConfigSchema),
+		// W7 (P2-3) EXPERIMENTAL: worker transport selector. Absent = "stdio"
+		// (production child-pi path, behavior unchanged). "rpc" selects the
+		// prototype RPC frame-client transport (src/runtime/rpc/) — currently
+		// the run-worker seam returns a structured not-implemented result
+		// instead of spawning. Live gate is env PI_CREW_WORKER_TRANSPORT;
+		// config→seam plumbing is the integration-phase follow-up (needs a
+		// parseRuntimeConfig line in config-validation.ts). Not sensitive —
+		// picks a transport, not authority.
+		workerTransport: Type.Optional(Type.Union([Type.Literal("stdio"), Type.Literal("rpc")])),
 	},
 	{ additionalProperties: false },
 );

package/src/schema/team-tool-schema.ts

@@ -280,6 +280,14 @@ const sharedFields = {
 			description: "Mark certain bash commands as excludeFromContext to reduce context tokens (default: false).",
 		}),
 	),
+	handoffBudgetTokens: Type.Optional(
+		Type.Integer({
+			minimum: 1,
+			maximum: 1_000_000,
+			description:
+				"Est-token (chars/4) budget cap on the dependency-context layer of worker prompts (default 1800). When exceeded, later dependencies are trimmed to summary head + artifact pointer. Out-of-range values are ignored.",
+		}),
+	),
 	budgetTotal: Type.Optional(
 		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
 		// 0 accepted as "unset/disabled" (models emit 0 for off); still rejects 1-999
@@ -596,6 +604,8 @@ export interface TeamToolParamsValue {
 	b?: number;
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens (default: false). */
 	excludeContextBash?: boolean;
+	/** Est-token (chars/4) budget cap on the dependency-context layer of worker prompts (default 1800). Later dependencies get trimmed to summary head + artifact pointer when exceeded. */
+	handoffBudgetTokens?: number;
 	/** Total token budget for the run. When set, enables budget tracking (minimum 1000). */
 	budgetTotal?: number;
 	/** When true, skip budget enforcement entirely (explicit opt-out). */

package/src/ui/pi-ui-compat.ts

@@ -1,5 +1,21 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+/**
+ * Host-compatibility shims for the `ExtensionContext["ui"]` surface.
+ *
+ * RETENTION POLICY (W4 2026-10-03): these typeof-based capability guards are
+ * deliberate no-ops, NOT version guards, and must be kept. pi-crew declares
+ * `"@earendil-works/pi-coding-agent": "*"` and `"@earendil-works/pi-tui": "*"`
+ * as optional peerDependencies with no minimum-version floor
+ * (package.json peerDependencies/peerDependenciesMeta), so host installs older
+ * than any SDK floor we verify against must keep working — retiring these
+ * shims would crash hosts whose UI predates
+ * `setWidget`/`setFooter`/`custom`/`setStatus`/`setWorkingIndicator`.
+ * Verified live: each guard is a pure feature check; there is no version
+ * constant or gate in this file. New host UI APIs should be added here
+ * (feature-detected), not called directly from src/.
+ */
+
 export interface WorkingIndicatorOptions {
 	frames?: string[];
 	intervalMs?: number;
@@ -9,7 +25,6 @@ type UiContext = Pick<ExtensionContext, "ui">;
 type ExtensionUi = ExtensionContext["ui"];
 type WidgetContent = string[] | ((tui: unknown, theme: unknown) => unknown);
 type WidgetOptions = Parameters<ExtensionUi["setWidget"]>[2];
-type WidgetOptionsWithPersist = WidgetOptions & { persist?: boolean };
 
 type CustomOptions = Parameters<ExtensionUi["custom"]>[1];
 
@@ -38,16 +53,10 @@ export function setWorkingIndicator(ctx: UiContext, options?: WorkingIndicatorOp
 
 /** Install or update an extension widget slot.
  * No-op when the host UI predates the `setWidget` API. */
-export function setExtensionWidget(
-	ctx: UiContext,
-	key: string,
-	content: WidgetContent | undefined,
-	options?: WidgetOptionsWithPersist,
-): void {
-	const { persist: _persist, ...widgetOptions } = options ?? {};
+export function setExtensionWidget(ctx: UiContext, key: string, content: WidgetContent | undefined, options?: WidgetOptions): void {
 	const record = maybeRecord(ctx.ui);
 	const fn = record?.setWidget;
-	if (typeof fn === "function") fn.call(ctx.ui, key, content as never, widgetOptions as WidgetOptions);
+	if (typeof fn === "function") fn.call(ctx.ui, key, content as never, options);
 }
 
 /**

package/src/ui/widget/index.ts

@@ -522,7 +522,6 @@ export function updateCrewWidget(
 		const model = state.model;
 		setExtensionWidget(ctx, WIDGET_KEY, ((_tui: unknown, theme: unknown) => new CrewWidgetComponent(model, theme, _tui)) as never, {
 			placement: piPlacement,
-			persist: true,
 		});
 		state.lastVisibility = "visible";
 		state.lastPlacement = placement;