pi-crew 0.9.9 → 0.9.10

package/src/runtime/important-line-classifier.ts

@@ -0,0 +1,130 @@
+/**
+ * Important-Line Classifier (P0-B) — scan middle slice of a truncated value
+ * for diagnostic lines worth preserving between head and tail.
+ *
+ * Ported from Hypa's `ImportantLineClassifier.cs` (5 regexes) and the
+ * middle-scanning portion of `Stages/TruncationStage.cs:24-46`, adapted to TS
+ * (no `[GeneratedRegex]` AOT) and to pi-crew's head(75%)/tail(25%) split.
+ *
+ * Design rationale:
+ * - Patterns are intentionally OVER-INCLUSIVE. False positives preserve
+ *   harmless lines; false negatives drop critical diagnostics, which is
+ *   unacceptable (the whole point of this module). Hypa uses the same
+ *   over-inclusive design.
+ * - Patterns are evaluated against a WHOLE line, not against the raw
+ *   truncated slice, so a match at a line boundary is reliable.
+ * - The `splitWithImportantLines` helper performs the head/tail split AND
+ *   greedily picks whole important lines from the middle that fit inside
+ *   `slackFactor * maxChars` (default 15% slack). Callers compose their own
+ *   marker using the returned parts — keeping `compactString` (marker
+ *   "compacted ... chars, head+tail preserved") and `readIfSmall` (marker
+ *   "truncated ... bytes, head+tail preserved") backward-compatible when no
+ *   important lines are present.
+ */
+
+/** Diagnostic patterns. Anchored where safe to avoid matching noise. */
+export const IMPORTANT_LINE_PATTERNS: readonly RegExp[] = [
+	// error keywords — NOTE: "warning" is intentionally excluded here; it has
+	// its own case-sensitive pattern below so that the common prose word
+	// "warning" does not over-match. (Hypa does the same split.)
+	/\b(error|failed|exception|fatal|panic)\b/i,
+	// file:line diagnostic — `child-pi.ts:383:`, `App.tsx:42:`
+	/\w+\.\w+:\d+:/,
+	// HTTP 4xx / 5xx — bounded so it does not match phone numbers etc.
+	/\b[45]\d{2}\b/,
+	// k8s / linter "Warning" event (case-sensitive so prose is not matched)
+	/\bWarning\b/,
+	// compiler / linter diagnostic id — `TS2304`, `CS0246`, `ES1234`
+	/\b[A-Z]{2,4}\d{3,5}\b/,
+];
+
+/** True iff `line` matches at least one important-line pattern. */
+export function isImportantLine(line: string): boolean {
+	if (!line) return false;
+	for (const pattern of IMPORTANT_LINE_PATTERNS) {
+		if (pattern.test(line)) return true;
+	}
+	return false;
+}
+
+/**
+ * Extract up to `maxLines` important lines from `text`. Lines are split on
+ * `\n` (also handles `\r\n`). Order preserved; duplicates kept (callers may
+ * want to see the same diagnostic twice if it appears twice — that often
+ * signals a recurring failure).
+ */
+export function extractImportantLines(text: string, maxLines = 30): string[] {
+	if (!text || maxLines <= 0) return [];
+	const out: string[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		if (out.length >= maxLines) break;
+		if (isImportantLine(line)) out.push(line);
+	}
+	return out;
+}
+
+export interface TruncationSplit {
+	/** The first 75% of the value (by char count), verbatim. */
+	head: string;
+	/** The last 25% of the value (by char count), verbatim. */
+	tail: string;
+	/**
+	 * Important lines from the middle slice, greedily picked (whole lines) so
+	 * the joined length fits inside `slackFactor * maxChars`. Empty when
+	 * `preserveImportant` is false OR no important lines are present OR none
+	 * fit the slack budget.
+	 */
+	importantLines: string[];
+	/** `value.length - maxChars` — chars dropped if no important lines preserved. */
+	baseDropped: number;
+}
+
+export interface SplitOptions {
+	/** When false, important-line scanning is skipped (assistant-text mode). */
+	preserveImportant?: boolean;
+	/** Hard cap on candidate lines before slack-budget selection. Default 30. */
+	maxImportantLines?: number;
+	/** Fraction of `maxChars` available for important-line content. Default 0.15. */
+	slackFactor?: number;
+}
+
+/**
+ * Split `value` into head + important-middle + tail, returning the parts.
+ * The caller is responsible for composing the final result (marker + glue)
+ * because the marker wording differs between `compactString` and
+ * `readIfSmall`.
+ *
+ * When no important lines are picked, the returned `importantLines` is `[]`
+ * and the marker wording stays bit-identical to the pre-P0-B format.
+ */
+export function splitWithImportantLines(value: string, maxChars: number, opts: SplitOptions = {}): TruncationSplit {
+	if (value.length <= maxChars) {
+		return { head: value, tail: "", importantLines: [], baseDropped: 0 };
+	}
+	const headLen = Math.floor(maxChars * 0.75);
+	const tailLen = maxChars - headLen;
+	const head = value.slice(0, headLen);
+	const tail = value.slice(value.length - tailLen);
+
+	if (opts.preserveImportant === false) {
+		return { head, tail, importantLines: [], baseDropped: value.length - maxChars };
+	}
+
+	const slackFactor = opts.slackFactor ?? 0.15;
+	const slackChars = Math.max(0, Math.floor(maxChars * slackFactor));
+	const maxCandidates = opts.maxImportantLines ?? 30;
+	const middle = value.slice(headLen, value.length - tailLen);
+	const candidates = extractImportantLines(middle, maxCandidates);
+
+	// Greedily pick whole lines that fit in the slack budget.
+	const chosen: string[] = [];
+	let used = 0;
+	for (const line of candidates) {
+		const addLen = (chosen.length > 0 ? 1 : 0) + line.length; // '\n' separator
+		if (used + addLen > slackChars) break;
+		chosen.push(line);
+		used += addLen;
+	}
+
+	return { head, tail, importantLines: chosen, baseDropped: value.length - maxChars };
+}

package/src/runtime/iteration-hooks.ts

@@ -8,6 +8,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
+import { HeadSnapStage } from "./compact-stages/index.ts";
 import { resolveShellForScript } from "../utils/resolve-shell.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { DENIED_METRIC_NAMES } from "./metric-parser.ts";
@@ -98,23 +99,6 @@ function notFiredResult(): HookResult {
 	};
 }
 
-/**
- * Truncate a buffer to the given byte limit, snapping to the last newline
- * boundary for UTF-8 safety.
- */
-function truncateToLimit(buf: Buffer, limit: number): Buffer {
-	if (buf.byteLength <= limit) return buf;
-
-	const slice = buf.subarray(0, limit);
-	// Find the last newline within the truncated region
-	const lastNewline = slice.lastIndexOf("\n");
-	if (lastNewline >= 0) {
-		return slice.subarray(0, lastNewline);
-	}
-	// No newline found — return the full slice
-	return slice;
-}
-
 /**
  * Check if a script path exists and is executable.
  */
@@ -196,13 +180,17 @@ export async function runIterationHook(
 			const durationMs = Date.now() - startTime;
 
 			const rawStdout = Buffer.concat(stdoutChunks);
-			const truncatedStdout = truncateToLimit(rawStdout, MAX_STDOUT_BYTES);
+			// Sprint 5: refactored onto HeadSnapStage. Convert to UTF-8 string once,
+			// then apply the byte-cap stage with newline-snap so partial lines
+			// never appear in the captured preview. HeadSnapStage is byte-cap-safe
+			// (walks back partial UTF-8 sequences at the cut boundary).
+			const stdoutText = new HeadSnapStage({ maxBytes: MAX_STDOUT_BYTES }).apply(rawStdout.toString("utf-8"));
 
 			const rawStderr = Buffer.concat(stderrChunks);
 
 			resolve({
 				fired: true,
-				stdout: truncatedStdout.toString("utf-8"),
+				stdout: stdoutText,
 				stderr: rawStderr.toString("utf-8"),
 				exitCode: code,
 				timedOut: killed,

package/src/runtime/live-session-runtime.ts

@@ -241,6 +241,54 @@ function modelFromRegistry(modelRegistry: unknown, modelId: string | undefined):
 	}
 }
 
+/**
+ * Round 18: when agent declares `model: false`, the inherited `parentModel`
+ * (= `ctx.model` from Pi runtime, set via `team-tool.ts:541/655`) is the
+ * session's SAVED model. That saved model can be stale (e.g. a previous
+ * session used claude-sonnet-4-5 and saved it as session.model; the new
+ * session actually runs on minimax-M3 displayed in the footer). If the
+ * saved model has no auth in `modelRegistry`, the worker fails immediately
+ * with "No API key found" before reaching any fallback candidate.
+ *
+ * This helper prefers the saved model when it is in the auth-available
+ * registry; otherwise falls back to the first auth-available registry
+ * model (e.g. minimax/MiniMax-M3, zai/glm-5.2); otherwise returns the
+ * raw `parentModel` unchanged so the caller surfaces E008.
+ */
+export function resolveParentModelFromRegistry(
+	modelRegistry: unknown,
+	rawParentModel: unknown,
+): string | undefined {
+	const raw = typeof rawParentModel === "string" ? rawParentModel.trim() : undefined;
+	if (raw) {
+		const candidate = raw.includes("/")
+			? raw
+			: (() => {
+				const m = modelFromRegistry(modelRegistry, raw);
+				if (m && typeof m === "object" && "fullId" in m) {
+					return String((m as { fullId?: unknown }).fullId ?? raw);
+				}
+				return undefined;
+			})();
+		if (candidate && modelFromRegistry(modelRegistry, candidate)) return candidate;
+	}
+	const registry = modelRegistry as { getAvailable?: () => unknown[] } | undefined;
+	if (registry && typeof registry.getAvailable === "function") {
+		try {
+			const available = registry.getAvailable();
+			if (Array.isArray(available) && available.length > 0) {
+				const first = available[0] as { provider?: unknown; id?: unknown } | undefined;
+				if (first && typeof first.provider === "string" && typeof first.id === "string") {
+					return `${first.provider}/${first.id}`;
+				}
+			}
+		} catch {
+			// ignore — fall through to raw
+		}
+	}
+	return raw;
+}
+
 /** Communication intensity by role (caveman-inspired token optimization) */
 const ROLE_INTENSITY: Record<string, "lite" | "full" | "ultra"> = {
 	explorer: "ultra",
@@ -473,7 +521,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			});
 			await (resourceLoader as { reload?: () => Promise<void> }).reload?.();
 		}
-		const modelRouting = buildConfiguredModelRouting({ overrideModel: input.modelOverride, stepModel: input.step.model, teamRoleModel: input.teamRoleModel, agentModel: input.agent.model, fallbackModels: input.agent.fallbackModels, parentModel: input.parentModel, modelRegistry: input.modelRegistry, cwd: input.manifest.cwd, scopeModelsPatterns: await resolveScopeModelsPatterns(input.manifest.cwd) });
+		const effectiveParentModel = resolveParentModelFromRegistry(input.modelRegistry, input.parentModel);
+		const modelRouting = buildConfiguredModelRouting({ overrideModel: input.modelOverride, stepModel: input.step.model, teamRoleModel: input.teamRoleModel, agentModel: input.agent.model, fallbackModels: input.agent.fallbackModels, parentModel: effectiveParentModel, modelRegistry: input.modelRegistry, cwd: input.manifest.cwd, scopeModelsPatterns: await resolveScopeModelsPatterns(input.manifest.cwd) });
 		const resolvedModel = modelFromRegistry(input.modelRegistry, modelRouting.candidates[0] ?? modelRouting.requested) ?? input.parentModel;
 		// Phase 4: MCP proxy — will be determined after session creation
 		// (we check parent's MCP tools and share connections when available)

package/src/runtime/model-fallback.ts

@@ -209,6 +209,25 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/internal(?:_server)?[ _]error/i,
 	/server error/i,
 	/bad gateway/i,
+	//
+	// Broader retryable patterns (added 2026-06-25, FIX 2):
+	// - `/provider[_ ]?error/i`: OpenAI-compatible "Provider error" generic fault.
+	// - `/context[_ ]?length[_ ]?exceeded/i`: "context_length_exceeded" from
+	//   OpenAI/Anthropic — when the configured model is the bottleneck, a
+	//   different model in the fallback chain may have a larger window.
+	// - `/safety/i`: Anthropic safety blocks — typically retryable on a
+	//   different model in the fallback chain.
+	// - `/is[_ ]?overloaded/i`: alias to the existing `/overloaded/i` pattern
+	//   to catch phrasings like "upstream is overloaded".
+	// - `/\b408\b/`: HTTP 408 Request Timeout — transient, provider-side.
+	//
+	// Intentionally NOT added: `/bad_request/` — can mean bad input (e.g.
+	// invalid schema), which is non-retryable.
+	/provider[_ ]?error/i,
+	/context[_ ]?length[_ ]?exceeded/i,
+	/safety/i,
+	/is[_ ]?overloaded/i,
+	/\b408\b/,
 ];
 
 // These patterns indicate auth/key/billing issues that will never succeed on retry.
@@ -313,9 +332,18 @@ export function buildConfiguredModelRouting(input: {
 	const rawModels = availableModels
 		? [input.overrideModel, input.stepModel, input.teamRoleModel, effectiveAgentModel, ...(input.fallbackModels ?? []), ...availableModels.map((model) => model.fullId)]
 		: [input.overrideModel, input.stepModel, input.teamRoleModel, effectiveAgentModel, ...(input.fallbackModels ?? []), parentModel];
+	// Fix (Round 18): when an agent has `model: false` (frontmatter) the
+	// inherited `parentModel` (= session chính's model, e.g. minimax-M3) IS the
+	// desired primary. It must NOT be filtered out by isAvailableModel — which
+	// only knows about models from models.json / registry, NOT builtin Pi models.
+	// Pin the inherited parentModel at index 0 regardless of availability.
+	const parentModelRaw = effectiveAgentModel?.trim() || undefined;
 	const configuredModels = rawModels
 		.filter((model): model is string => Boolean(model?.trim()))
-		.filter((model) => isAvailableModel(model.trim(), availableModels));
+		.filter((model, idx) => {
+			if (parentModelRaw && idx === 0 && model.trim() === parentModelRaw) return true;
+			return isAvailableModel(model.trim(), availableModels);
+		});
 	const candidates = buildModelCandidates(configuredModels[0], configuredModels.slice(1), availableModels, preferredProvider);
 	const reason = requested && candidates[0] && resolveModelCandidate(requested, availableModels, preferredProvider) !== candidates[0]
 		? "requested model unavailable; selected configured Pi fallback"

package/src/runtime/role-permission.ts

@@ -2,8 +2,8 @@ import { isSensitivePath } from "./sensitive-paths.ts";
 
 export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
 
-const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner", "writer"]);
-const WRITE_ROLES = new Set(["executor", "test-engineer"]);
+const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner"]);
+const WRITE_ROLES = new Set(["executor", "test-engineer", "writer"]);
 const READ_ONLY_COMMANDS = new Set(["cat", "head", "tail", "less", "more", "wc", "ls", "find", "grep", "rg", "awk", "sed", "echo", "printf", "which", "where", "whoami", "pwd", "env", "printenv", "date", "df", "du", "uname", "file", "stat", "diff", "sort", "uniq", "tr", "cut", "paste", "test", "true", "false", "type", "readlink", "realpath", "basename", "dirname", "sha256sum", "md5sum", "xxd", "hexdump", "od", "strings", "tree", "jq", "git", "gh"]);
 
 export interface PermissionCheckResult {

package/src/runtime/stream-preview.ts

@@ -3,6 +3,7 @@
 // Used by the UI layer to show partial results before task completion.
 
 import type { ParsedPiUsage } from "./pi-json-output.ts";
+import { TAIL_CAPTURE_STREAM_STAGE } from "./compact-stages/index.ts";
 
 export interface ToolCallPreview {
 	toolName: string;
@@ -111,7 +112,13 @@ export function feedJsonEvent(preview: StreamPreview, event: unknown): boolean {
 		const text = extractTextFromContent(message?.content ?? obj.content);
 		if (text) {
 			const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + text : text;
-			preview.textBuffer = appended.length > MAX_TEXT_BUFFER ? appended.slice(appended.length - MAX_TEXT_BUFFER) : appended;
+			// Sprint 5: refactored onto the stage-chain. TAIL_CAPTURE_STREAM_STAGE
+			// is a 16_384-char tail-capture stage with no marker (the UI shows
+			// raw text without a prefix). It is bit-equivalent to the inline
+			// `appended.slice(appended.length - MAX_TEXT_BUFFER)` for inputs at
+			// or below the cap (returns verbatim) and equivalent for over-cap
+			// inputs (returns last MAX_TEXT_BUFFER chars).
+			preview.textBuffer = TAIL_CAPTURE_STREAM_STAGE.apply(appended);
 		}
 		modified = true;
 	}
@@ -119,7 +126,7 @@ export function feedJsonEvent(preview: StreamPreview, event: unknown): boolean {
 	// Detect direct text/final output
 	if (typeof obj.text === "string" && obj.text.trim()) {
 		const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + obj.text : obj.text;
-		preview.textBuffer = appended.length > MAX_TEXT_BUFFER ? appended.slice(appended.length - MAX_TEXT_BUFFER) : appended;
+		preview.textBuffer = TAIL_CAPTURE_STREAM_STAGE.apply(appended);
 		modified = true;
 	}
 

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

@@ -5,6 +5,8 @@ import { writeArtifact } from "../state/artifact-store.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { pruneToolOutputs, type ToolResultEntry, type FileEditEvent, DEFAULT_PRUNE_CONFIG } from "./tool-output-pruner.ts";
+import { applyCompactPipeline } from "./compact-pipeline.ts";
+import { ANSI_STRIP_STAGE, BLANK_COLLAPSE_STAGE, TruncationStage } from "./compact-stages/index.ts";
 
 export interface DependencyContextEntry {
 	taskId: string;
@@ -19,7 +21,14 @@ export interface DependencyContextEntry {
 
 export interface DependencyOutputContext {
 	dependencies: DependencyContextEntry[];
-	sharedReads: Array<{ name: string; path: string; content: string }>;
+	/**
+	 * Each shared artifact read, truncated for inline injection. When truncation
+	 * is materially lossy (file size > 2× MAX_RESULT_INLINE_BYTES) the FULL
+	 * content is also teed to `${artifactsRoot}/tee/${taskId}-${name}.full.txt`
+	 * and the path is exposed via `fullOutputPath` so the downstream worker
+	 * can `read` it back if it needs the dropped middle.
+	 */
+	sharedReads: Array<{ name: string; path: string; content: string; fullOutputPath?: string }>;
 }
 
 function containedExists(filePath: string, baseDir?: string): boolean {
@@ -39,35 +48,127 @@ function containedExists(filePath: string, baseDir?: string): boolean {
  * (24K/40K/80K) which truncated the same artifact differently depending on
  * which code path read it.
  */
-const MAX_RESULT_INLINE_BYTES = 32_000;
+export const MAX_RESULT_INLINE_BYTES = 32_000;
 
-function readIfSmall(filePath: string, baseDir?: string): string | undefined {
-	const maxBytes = MAX_RESULT_INLINE_BYTES;
+/**
+ * Read a file and return its content, truncating to a head+tail slice if it
+ * exceeds {@link MAX_RESULT_INLINE_BYTES} characters. Multi-byte UTF-8
+ * sequences are preserved by reading the full file as a UTF-8 string and
+ * slicing by character count (not raw bytes).
+ */
+export interface TeeRecoveryOptions {
+	/** Absolute path to write the full (non-truncated) content to. */
+	fullOutputPath: string;
+}
+
+export interface ReadIfSmallTeeResult {
+	/** Truncated content (or full content when no truncation). */
+	content: string;
+	/** Set only when tee was actually written (file size > 2× threshold + write succeeded). */
+	fullOutputPath?: string;
+}
+
+/**
+ * Sanitize a taskId / artifactName into a flat tee filename. Any character
+ * outside [A-Za-z0-9._-] is replaced with underscore so the resulting path
+ * is always single-segment and cannot escape the tee directory.
+ */
+function safeTeeName(taskId: string, artifactName: string): string {
+	const safe = (s: string): string => s.replace(/[^A-Za-z0-9._-]/g, "_");
+	return `${safe(taskId)}-${safe(artifactName)}.full.txt`;
+}
+
+/**
+ * Canonical tee path for a shared artifact read.
+ *
+ * Format: `${artifactsRoot}/tee/${taskId}-${artifactName}.full.txt`
+ *
+ * The downstream worker prompt includes this path so the worker can `read`
+ * the full content when it needs the dropped middle.
+ */
+export function teePathForArtifact(artifactsRoot: string, taskId: string, artifactName: string): string {
+	return path.join(artifactsRoot, "tee", safeTeeName(taskId, artifactName));
+}
+
+/**
+ * Best-effort tee write. Returns true on success, false on any error (write
+ * failures are silent — tee is enhancement, never a hard dependency). The
+ * truncated inline content is still returned by the caller either way.
+ */
+function writeTeeFile(fullOutputPath: string, content: string): boolean {
 	try {
-		const safePath = baseDir ? resolveRealContainedPath(baseDir, filePath) : filePath;
-		const stat = fs.statSync(safePath);
-		if (stat.size > maxBytes) {
-			// L4: head + tail instead of head-only. Keeps closing markdown
-			// structure (code fences, headings) instead of leaving them truncated.
-			const head = Math.floor(maxBytes * 0.75);
-			const tail = maxBytes - head;
-			const headBuf = Buffer.alloc(head);
-			const tailBuf = Buffer.alloc(tail);
-			const fd = fs.openSync(safePath, "r");
-			try {
-				fs.readSync(fd, headBuf, 0, head, 0);
-				fs.readSync(fd, tailBuf, 0, tail, stat.size - tail);
-			} finally {
-				fs.closeSync(fd);
+		fs.mkdirSync(path.dirname(fullOutputPath), { recursive: true });
+		fs.writeFileSync(fullOutputPath, content, "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Read a file with optional tee-recovery (P1-A). Returns the truncated
+ * content AND (when tee was actually written) the absolute path to the full
+ * file. Returns undefined if the file cannot be read at all.
+ *
+ * Tee threshold: only when content.length > 2 * MAX_RESULT_INLINE_BYTES
+ * (the head+tail is materially lossy — small over-threshold files are not
+ * teed because the inline content is mostly intact and the worker can live
+ * with the 75/25 split). File content is read once and reused for both the
+ * pipeline (truncation) and the tee write (full file).
+ *
+ * Truncation behavior is unchanged from the P0-A pipeline: ANSI strip +
+ * blank collapse BEFORE truncation, important-line preservation (P0-B)
+ * inside TruncationStage, marker wording matches the pre-P1-A `readIfSmall`
+ * output exactly (L4 backward-compat).
+ */
+export function readIfSmallWithTee(
+	filePath: string,
+	opts: { baseDir?: string; tee?: TeeRecoveryOptions } = {},
+): ReadIfSmallTeeResult | undefined {
+	const maxChars = MAX_RESULT_INLINE_BYTES;
+	try {
+		const safePath = opts.baseDir ? resolveRealContainedPath(opts.baseDir, filePath) : filePath;
+		const content = fs.readFileSync(safePath, "utf-8");
+		if (content.length > maxChars) {
+			let fullOutputPath: string | undefined;
+			// Tee only when truncation is materially lossy (>2× threshold).
+			if (opts.tee && content.length > maxChars * 2) {
+				if (writeTeeFile(opts.tee.fullOutputPath, content)) {
+					fullOutputPath = opts.tee.fullOutputPath;
+				}
 			}
-			return `${headBuf.toString("utf-8")}\n\n...[pi-crew truncated ${stat.size - maxBytes} bytes, head+tail preserved]...\n${tailBuf.toString("utf-8")}`;
+			const result = applyCompactPipeline(content, [
+				ANSI_STRIP_STAGE,
+				BLANK_COLLAPSE_STAGE,
+				new TruncationStage(maxChars, {
+					preserveImportant: true,
+					marker: { verb: "truncated", unit: "chars", headSeparator: "\n\n", tailSeparator: "\n" },
+				}),
+			]);
+			return fullOutputPath ? { content: result.text, fullOutputPath } : { content: result.text };
 		}
-		return fs.readFileSync(safePath, "utf-8");
+		return { content };
 	} catch {
 		return undefined;
 	}
 }
 
+/**
+ * Read a file and return its content, truncating to a head+tail slice if it
+ * exceeds {@link MAX_RESULT_INLINE_BYTES} characters. Multi-byte UTF-8
+ * sequences are preserved by reading the full file as a UTF-8 string and
+ * slicing by character count (not raw bytes).
+ *
+ * Thin wrapper around {@link readIfSmallWithTee} for backward compatibility
+ * — callers that do not need tee-recovery metadata get just the content
+ * string. New tee-recovery call sites should use {@link readIfSmallWithTee}
+ * directly so they can include the full output path in the worker prompt.
+ */
+export function readIfSmall(filePath: string, baseDir?: string): string | undefined {
+	const result = readIfSmallWithTee(filePath, { baseDir });
+	return result?.content;
+}
+
 function safeSharedName(name: string): string {
 	const normalized = name.replaceAll("\\", "/").replace(/^\.\/+/, "");
 	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid shared artifact name: ${name}`);
@@ -127,6 +228,7 @@ function aggregateUsage(task: TeamTaskState): DependencyContextEntry["usage"] {
 function pruneSharedReads(
 	reads: Array<{ name: string; path: string; content: string }>,
 	dependencies: DependencyContextEntry[],
+	artifactsRoot: string,
 ): Array<{ name: string; path: string; content: string }> {
 	if (reads.length === 0) return reads;
 	// Convert shared reads to tool result entries (ordered oldest → newest
@@ -140,15 +242,19 @@ function pruneSharedReads(
 	// Collect file edit events from dependency artifacts produced to shared/.
 	// A dependency that wrote a shared file after an earlier read invalidates
 	// that read (the content is now stale relative to the latest version).
-	const sharedRoot = path.resolve("shared");
+	// Artifact entries from listTaskArtifacts() are already relative to
+	// artifactsRoot (e.g. "shared/foo.md"), so resolve directly against
+	// artifactsRoot — NOT against a "shared" subdirectory (which would
+	// double-prefix to <artifactsRoot>/shared/shared/foo.md).
 	const fileEdits: FileEditEvent[] = [];
 	for (let depIndex = 0; depIndex < dependencies.length; depIndex++) {
 		const dep = dependencies[depIndex]!;
 		const produced = dep.artifactsProduced ?? [];
 		for (const artifact of produced) {
 			if (typeof artifact !== "string") continue;
-			// Map artifact path to shared-relative and check against read targets.
-			fileEdits.push({ target: path.resolve(sharedRoot, artifact), index: reads.length + depIndex });
+			// Map artifact path (relative to artifactsRoot) to absolute and
+			// check against read targets.
+			fileEdits.push({ target: path.resolve(artifactsRoot, artifact), index: reads.length + depIndex });
 		}
 	}
 	const pruned = pruneToolOutputs(entries, DEFAULT_PRUNE_CONFIG);
@@ -175,13 +281,33 @@ export function collectDependencyOutputContext(manifest: TeamRunManifest, tasks:
 	});
 	const rawSharedReads = (step.reads === false ? [] : step.reads ?? []).map((name) => {
 		const filePath = sharedPath(manifest, name);
-		return { name, path: filePath, content: readIfSmall(filePath, path.resolve(manifest.artifactsRoot, "shared")) ?? "" };
+		// P1-A tee-recovery: when the shared artifact is large enough that the
+		// 75/25 head+tail split is materially lossy (>2× MAX_RESULT_INLINE_BYTES),
+		// tee the full content to ${artifactsRoot}/tee/${taskId}-${name}.full.txt
+		// and expose the path so the downstream worker can `read` the full file
+		// if it needs the dropped middle. The truncated content is still
+		// included inline; tee is an enhancement, not a hard dependency. Tee
+		// write is best-effort (writeTeeFile swallows I/O errors and the result
+		// simply omits fullOutputPath in that case).
+		const teePath = teePathForArtifact(manifest.artifactsRoot, task.id, name);
+		const teeResult = readIfSmallWithTee(filePath, {
+			baseDir: path.resolve(manifest.artifactsRoot, "shared"),
+			tee: { fullOutputPath: teePath },
+		});
+		if (teeResult === undefined) return { name, path: filePath, content: "" };
+		const entry: { name: string; path: string; content: string; fullOutputPath?: string } = {
+			name,
+			path: filePath,
+			content: teeResult.content,
+		};
+		if (teeResult.fullOutputPath) entry.fullOutputPath = teeResult.fullOutputPath;
+		return entry;
 	}).filter((item) => item.content.trim().length > 0);
 	// Apply staleness-aware pruning to shared reads: drops superseded reads
 	// (same file re-read with different selectors) and replaces stale large
 	// outputs with compact digest notices before injecting into the worker
 	// prompt. OPT-IN: default config protects recent results.
-	const sharedReads = pruneSharedReads(rawSharedReads, dependencies);
+	const sharedReads = pruneSharedReads(rawSharedReads, dependencies, manifest.artifactsRoot);
 	return { dependencies, sharedReads };
 }
 
@@ -198,7 +324,15 @@ export function renderDependencyOutputContext(context: DependencyOutputContext):
 	}
 	if (context.sharedReads.length) {
 		parts.push("# Shared Run Context Reads", "");
-		for (const read of context.sharedReads) parts.push(`## shared/${read.name}`, `Path: ${read.path}`, "", read.content.trim(), "");
+		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(), "");
+		}
 	}
 	return parts.join("\n").trim();
 }