pi-crew 0.9.68 → 0.10.1

package/src/runtime/stale-reconciler.ts

@@ -3,8 +3,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { errors } from "../errors.ts";
 import { atomicWriteFile, atomicWriteJson } from "../state/atomic-write.ts";
+import { getCurrentPlanRecord } from "../state/stores/plan-store.ts";
 import { loadManifestWithRecovery, loadTasksWithRecovery, saveRunManifest } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { checkProcessLiveness } from "./process-status.ts";
 
@@ -23,7 +25,7 @@ const ORPHAN_TEMP_SCAN_BATCH_SIZE = 50;
 export interface ReconcileResult {
 	runId: string;
 	/** What was found and what action was taken */
-	verdict: "healthy" | "blocked_awaiting_approval" | "result_exists" | "pid_dead" | "pid_alive_stale" | "no_status";
+	verdict: "healthy" | "blocked_awaiting_approval" | "waiting_answer" | "result_exists" | "pid_dead" | "pid_alive_stale" | "no_status";
 	/** Whether repair was applied */
 	repaired: boolean;
 	/** Human-readable detail */
@@ -45,6 +47,50 @@ export function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
 	return manifest.status === "blocked" && manifest.planApproval?.required === true && manifest.planApproval.status === "pending";
 }
 
+/** T2/R4 (ADR-4 §2 reader migration): plan-record-first variant — the current
+ *  PlanRecord's approval (when present) is authoritative; pre-v2 runs fall
+ *  back to the manifest gate above. The `blocked + pending → protected`
+ *  invariant is preserved on BOTH paths. */
+export function isPlanApprovalPendingEffective(manifest: TeamRunManifest): boolean {
+	if (isPlanApprovalPending(manifest)) return true;
+	if (manifest.status !== "blocked") return false;
+	return getCurrentPlanRecord(manifest)?.approval?.status === "pending";
+}
+
+/** WP-2/R2 (ADR-0 item 9, docs/decisions/2026-08-17-waiting-producer-ask.md):
+ * waiting TTL — a manifest.waitState.askedAt younger than this marks an
+ * intentional ask-wait; older marks a leaked park marker (worker died without
+ * resolving the ask) and the run loses reconciler protection. Leak guard. */
+const WAITING_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Is this run parked in the ask tool awaiting a human answer (WP-2/R2)?
+ *
+ * True when waitState is set and its askedAt is within waitingTtl. The parked
+ * worker is blocked polling the mailbox for a response — not crashed — and it
+ * typically stops heartbeating while parked, so the run must be protected at
+ * run level (before the no-PID/heartbeat staleness phases) exactly like
+ * plan-approval runs. askedAt exactly at the TTL boundary still counts as
+ * pending (<=, fail-safe toward preservation); a future askedAt (clock skew)
+ * also passes. TTL-EXPIRED waitState returns false — the marker leaked and the
+ * normal staleness repair paths apply (leak guard).
+ */
+export function isWaitAnswerPending(manifest: TeamRunManifest, now = Date.now()): boolean {
+	const askedAtMs = manifest.waitState?.askedAt ? new Date(manifest.waitState.askedAt).getTime() : Number.NaN;
+	return Number.isFinite(askedAtMs) && now - askedAtMs <= WAITING_TTL_MS;
+}
+
+/**
+ * Generalized intentional-wait predicate (ADR-0 item 9, extended by ADR-4 §2):
+ * the run is blocked on a human decision — plan approval (record-first with
+ * manifest fallback — pre-v2 semantics preserved on the fallback path) or a
+ * pending ask answer within waitingTtl. Such runs are not crashes and must not
+ * be stale-repaired or cancelled by reconciliation.
+ */
+export function isIntentionalWait(manifest: TeamRunManifest, now = Date.now()): boolean {
+	return isPlanApprovalPendingEffective(manifest) || isWaitAnswerPending(manifest, now);
+}
+
 const STALE_ALIVE_PID_MS = 24 * 60 * 60 * 1000; // 24 hours
 const ACTIVE_EVIDENCE_TTL_MS = 5 * 60 * 1000;
 /** For no-PID runs, repair when ALL running tasks have heartbeat stale beyond this threshold. */
@@ -315,7 +361,9 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 	// Preserve runs intentionally blocked on human plan approval. These are not
 	// crashes even if the owning PID is gone — they are waiting for a decision.
 	// Must short-circuit before Phase 1 (result check) and Phase 2 (PID liveness).
-	if (isPlanApprovalPending(manifest)) {
+	// ADR-4 §2: record-first predicate — a PlanRecord approval is authoritative,
+	// the manifest field remains the pre-v2 fallback (never dropped).
+	if (isPlanApprovalPendingEffective(manifest)) {
 		return {
 			runId,
 			verdict: "blocked_awaiting_approval",
@@ -324,6 +372,22 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 		};
 	}
 
+	// WP-2/R2 (ADR-0 item 9): a run parked in the ask tool with a fresh
+	// waitState.askedAt is intentionally waiting on a human answer — not stale.
+	// Short-circuits before Phase 1/2 like plan-approval above: a parked worker
+	// does not heartbeat, so the no-PID/heartbeat staleness phases would
+	// otherwise cancel it long before its (server-clamped <=1h) ask deadline.
+	// TTL-expired waitState (>24h) falls through — the park marker leaked
+	// (worker died without resolving) and normal staleness repair applies.
+	if (isWaitAnswerPending(manifest, now)) {
+		return {
+			runId,
+			verdict: "waiting_answer",
+			repaired: false,
+			detail: "Ask answer pending (manifest.waitState.askedAt within waiting TTL); run is intentionally waiting and must not be stale-repaired",
+		};
+	}
+
 	// Phase 1: Check if results already exist
 	const phase1 = checkResultFile(manifest, tasks);
 	if (phase1.found) {
@@ -538,7 +602,14 @@ export function reconcileOrphanedTempWorkspaces(
 							}
 						}
 						// If still running after reconciliation attempt, mark for dir-preserving
-						if (result.verdict === "healthy" || (result.verdict === "no_status" && !result.repaired)) {
+						if (
+							result.verdict === "healthy" ||
+							// WP-2/R2: a run intentionally waiting on an ask answer keeps the
+							// temp workspace alive (its stateRoot + mailbox must survive for
+							// the parked worker to receive the answer).
+							result.verdict === "waiting_answer" ||
+							(result.verdict === "no_status" && !result.repaired)
+						) {
 							hasRunning = true;
 						}
 					} catch (err) {
@@ -546,14 +617,19 @@ export function reconcileOrphanedTempWorkspaces(
 						// Note: manifestPath here refers to the variable defined in the
 						// for loop at line 442 (outer scope of this catch block).
 						const scanManifestPath = manifestPath;
-						console.warn(`[stale-reconciler] Skipping manifest due to parse error: ${scanManifestPath}: ${err}`);
+						logInternalError(
+							"stale-reconciler",
+							new Error(`Skipping manifest due to parse error: ${scanManifestPath}: ${err}`),
+							undefined,
+							"warn",
+						);
 					}
 				}
 			} catch (err) {
 				// Cannot determine running state — treat as if running to prevent
 				// premature cleanup of a potentially active workspace.
 				hasRunning = true;
-				console.warn(`[stale-reconciler] Skipping unreadable runs dir: ${stateRunsDir}: ${err}`);
+				logInternalError("stale-reconciler", new Error(`Skipping unreadable runs dir: ${stateRunsDir}: ${err}`), undefined, "warn");
 			}
 
 			// Post-loop: check if this workspace dir can be cleaned up.
@@ -617,7 +693,12 @@ export function reconcileOrphanedTempWorkspaces(
 							}
 						}
 					} catch (err) {
-						console.warn(`[stale-reconciler] Skipping unreadable runs dir: ${stateRunsDir}: ${err}`);
+						logInternalError(
+							"stale-reconciler",
+							new Error(`Skipping unreadable runs dir: ${stateRunsDir}: ${err}`),
+							undefined,
+							"warn",
+						);
 					}
 				}
 			}

package/src/runtime/subagent-manager.ts

@@ -25,11 +25,26 @@ export interface SubagentSpawnOptions {
 	/** Optional batch grouping id (Rule 1). Agents sharing a batchId coalesce
 	 * completion notifications into one. undefined => individual (default). */
 	batchId?: string;
+	/** WP-1/R1 (H6): owning team-run task id. Set by the one-shot Agent-tool
+	 * route once the run manifest resolves (taskId is only knowable after the
+	 * run is dispatched). undefined for unlinked/legacy spawns. */
+	taskId?: string;
+	/** WP-1/R1 (H6): ownership depth in the task tree (0 for a root one-shot).
+	 * Optional for back-compat; defaults to 0 at spawn. WP-5 owns depth
+	 * semantics for nested runs. */
+	depth?: number;
 }
 
 export interface SubagentRecord {
 	id: string;
 	runId?: string;
+	/** WP-1/R1 (H6): owning team-run task id (task ⇄ subagentId link).
+	 * Optional for back-compat — records without it render as today and steer
+	 * returns the existing "not linked" message (no throw). */
+	taskId?: string;
+	/** WP-1/R1 (H6): ownership depth (0 for root one-shot). Optional for
+	 * back-compat — legacy records without it render as today. */
+	depth?: number;
 	type: string;
 	description: string;
 	prompt: string;
@@ -144,6 +159,7 @@ const ALLOWED_RECORD_FIELDS = new Set([
 	"runId",
 	"cwd",
 	"taskId",
+	"depth",
 	"result",
 	"error",
 	"resultConsumed",
@@ -185,7 +201,13 @@ export function readPersistedSubagentRecord(cwd: string, id: string): SubagentRe
 	try {
 		const raw = JSON.parse(fs.readFileSync(persistedSubagentPath(cwd, id), "utf-8"));
 		return sanitizePersistedRecord(raw);
-	} catch {
+	} catch (error) {
+		// R17-B5: parse/read failures were fully silent, hiding lost records
+		// (see NEW-R3 note in savePersistedSubagentRecord). ENOENT stays quiet —
+		// a legitimately removed record (cancel) is not an error.
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			logInternalError("subagent-manager.read-persisted", error, `id=${id}`, "warn");
+		}
 		return undefined;
 	}
 }
@@ -254,6 +276,8 @@ export class SubagentManager {
 			ownerSessionGeneration: options.ownerSessionGeneration,
 			ownerSessionId: options.ownerSessionId,
 			batchId: options.batchId,
+			taskId: options.taskId,
+			depth: options.depth ?? 0,
 		};
 		this.records.set(record.id, record);
 		this.cwdByRecord.set(record.id, options.cwd);

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_OUTPUT_CONTEXT } from "../config/defaults.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
 import { writeArtifact } from "../state/stores/artifact-store.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
@@ -124,6 +125,13 @@ export interface ReadIfSmallTeeResult {
 	content: string;
 	/** Set only when tee was actually written (file size > 2× threshold + write succeeded). */
 	fullOutputPath?: string;
+	/** R10-1 (dep-context cache tee-safety): character length of the RAW file
+	 *  content BEFORE the truncation pipeline ran. Populated on every
+	 *  successful read; lets callers tell whether a cached no-tee read
+	 *  (`readIfSmall`) would have teed
+	 *  (length > TEE_THRESHOLD_MULTIPLIER × MAX_RESULT_INLINE_BYTES) without
+	 *  re-reading the file — no heuristics on the truncated body. */
+	originalLength?: number;
 }
 
 /**
@@ -211,9 +219,11 @@ export function readIfSmallWithTee(
 					},
 				}),
 			]);
-			return fullOutputPath ? { content: result.text, fullOutputPath } : { content: result.text };
+			return fullOutputPath
+				? { content: result.text, fullOutputPath, originalLength: content.length }
+				: { content: result.text, originalLength: content.length };
 		}
-		return { content };
+		return { content, originalLength: content.length };
 	} catch {
 		return undefined;
 	}
@@ -401,6 +411,12 @@ export function collectDependencyOutputContext(
 	tasks: TeamTaskState[],
 	task: TeamTaskState,
 	step: WorkflowStep,
+	/** R10-1 residual: per-run result-artifact read cache (same instance the
+	 *  closeout aggregation uses — created once in executeTeamRunCore, threaded
+	 *  SchedulerContext → baseInput → TaskRunnerInput). Optional: undefined
+	 *  keeps the previous uncached per-dep readIfSmallWithTee behavior
+	 *  byte-for-byte. NEVER pass a per-call cache instance. */
+	cache?: ResultArtifactReadCache,
 ): DependencyOutputContext {
 	const byStep = new Map(tasks.map((item) => [item.stepId, item]).filter((entry): entry is [string, TeamTaskState] => Boolean(entry[0])));
 	const byId = new Map(tasks.map((item) => [item.id, item]));
@@ -424,11 +440,19 @@ export function collectDependencyOutputContext(
 		.filter((item): item is TeamTaskState => Boolean(item))
 		.map((item) => {
 			const fullOutputPath = item.resultArtifact ? teePathForArtifact(manifest.artifactsRoot, task.id, item.id) : undefined;
+			// R10-1 residual: route the dep result read through the same per-run
+			// cache the closeout aggregation populated (readTaskResultArtifactWithTee).
+			// Without a cache this issues the identical readIfSmallWithTee call as
+			// before (byte-identical output); with one, a non-tee-band hit returns
+			// the memoized body while tee-band truncations still do the real read
+			// (tee file + fullOutputPath preserved per consumer).
 			const teeResult = item.resultArtifact
-				? readIfSmallWithTee(item.resultArtifact.path, {
-						baseDir: manifest.artifactsRoot,
-						...(fullOutputPath ? { tee: { fullOutputPath } } : {}),
-					})
+				? readTaskResultArtifactWithTee(
+						item.resultArtifact,
+						manifest.artifactsRoot,
+						fullOutputPath ? { fullOutputPath } : undefined,
+						cache,
+					)
 				: undefined;
 			const resultText = teeResult?.content;
 			const inlineBytes = resultText?.length ?? 0;
@@ -570,12 +594,209 @@ export function writeTaskInputsArtifact(
 	});
 }
 
-export function aggregateTaskOutputs(tasks: TeamTaskState[], manifest?: TeamRunManifest): string {
+/**
+ * R10-1: outcome of one aggregated result-artifact read (the pair of disk
+ * ops {@link aggregateTaskOutputs} performs per task: readIfSmall +
+ * containedExists). Cached as a unit so a cache hit replaces BOTH ops.
+ */
+export interface ResultArtifactReadOutcome {
+	/** Truncated body from readIfSmall; undefined when the read failed/missing. */
+	body: string | undefined;
+	/** containedExists() result for the same artifact path. */
+	exists: boolean;
+	/** R10-1 (dep-context tee-safety): character length of the raw file content
+	 *  at miss time. Present whenever the read succeeded; used by the
+	 *  dependency-context seam to decide whether a cache hit is byte-identical
+	 *  (no tee would have been written) or must fall through to a real
+	 *  readIfSmallWithTee. Undefined when the read failed. */
+	originalLength?: number;
+}
+
+/**
+ * R10-1: per-run memoization for result-artifact reads inside
+ * {@link aggregateTaskOutputs} (batch summary + group-join both aggregate the
+ * SAME settled batch every closeout — the second aggregation re-reads each
+ * `results/<taskId>.txt` from disk for no benefit).
+ *
+ * Cache key = artifact path + descriptor identity (`sizeBytes|contentHash`).
+ * writeArtifact computes both on every write (STATE-9: in-memory,
+ * post-redaction), so a retry that rewrites `results/<taskId>.txt` produces a
+ * NEW descriptor → new key → automatic miss. Descriptors missing BOTH fields
+ * bypass the cache entirely (cannot distinguish a rewrite from unchanged
+ * content). "Missing" outcomes are cached too (result artifacts use the
+ * default `retention: "run"` and are not pruned mid-run, so a miss is stable
+ * within a run). Path is used as-is (producer/taskId-keyed, stable absolute
+ * path from the manifest — no per-lookup realpath needed).
+ *
+ * Lifetime: one run (closure-level in executeTeamRunCore) — no cross-run
+ * leakage, no invalidation beyond the descriptor-identity key.
+ *
+ * Env bypass: `PI_CREW_DISABLE_RESULT_READ_CACHE=1` (read ONCE at creation)
+ * returns a cache whose lookups always miss — control mode for benches/tests
+ * that need the uncached behavior while still routing through the counting
+ * wrapper below.
+ */
+export interface ResultArtifactReadCache {
+	/** Cached outcome for the artifact identity, or undefined on miss/bypass. */
+	lookup(descriptor: ArtifactDescriptor): ResultArtifactReadOutcome | undefined;
+	/** Store an outcome. No-op when the descriptor lacks identity fields. */
+	store(descriptor: ArtifactDescriptor, outcome: ResultArtifactReadOutcome): void;
+}
+
+/**
+ * R10-1 test/bench counters for the result-artifact read path. Track disk ops
+ * ACTUALLY ISSUED through {@link readTaskResultArtifact} (incremented in the
+ * miss branch right before the real readIfSmall/containedExists calls) plus
+ * cache hits/misses. The disabled-control mode still routes through the
+ * counting wrapper (map simply not consulted) so cached-vs-uncached
+ * comparisons are honest.
+ */
+export interface ResultArtifactReadStats {
+	readFile: number;
+	exists: number;
+	hits: number;
+	misses: number;
+	reset(): void;
+}
+
+export const __test__resultReadStats: ResultArtifactReadStats = {
+	readFile: 0,
+	exists: 0,
+	hits: 0,
+	misses: 0,
+	reset() {
+		this.readFile = 0;
+		this.exists = 0;
+		this.hits = 0;
+		this.misses = 0;
+	},
+};
+
+function resultArtifactCacheKey(descriptor: ArtifactDescriptor): string | undefined {
+	if (descriptor.sizeBytes === undefined && descriptor.contentHash === undefined) return undefined;
+	return `${descriptor.path}|${descriptor.sizeBytes ?? ""}|${descriptor.contentHash ?? ""}`;
+}
+
+export function createResultArtifactReadCache(): ResultArtifactReadCache {
+	// Read once at creation — the bypass decision is fixed for the cache's
+	// (per-run) lifetime, matching PI_CREW_USE_BUNDLE-style one-shot env reads.
+	if (getCrewEnv("PI_CREW_DISABLE_RESULT_READ_CACHE") === "1") {
+		return {
+			lookup: () => undefined,
+			store: () => undefined,
+		};
+	}
+	const entries = new Map<string, ResultArtifactReadOutcome>();
+	return {
+		lookup(descriptor) {
+			const key = resultArtifactCacheKey(descriptor);
+			if (key === undefined) return undefined;
+			const hit = entries.get(key);
+			if (hit === undefined) {
+				__test__resultReadStats.misses += 1;
+				return undefined;
+			}
+			__test__resultReadStats.hits += 1;
+			return hit;
+		},
+		store(descriptor, outcome) {
+			const key = resultArtifactCacheKey(descriptor);
+			if (key !== undefined) entries.set(key, outcome);
+		},
+	};
+}
+
+/**
+ * Single read seam for {@link aggregateTaskOutputs}. Without a cache this is
+ * byte-for-byte the old behavior: readIfSmall + containedExists issued in the
+ * same order. With a cache, a hit returns the memoized pair (zero disk ops);
+ * a miss issues the same disk ops as the uncached path, counts them, and
+ * memoizes the outcome.
+ */
+function readTaskResultArtifact(
+	descriptor: ArtifactDescriptor,
+	baseDir: string | undefined,
+	cache: ResultArtifactReadCache | undefined,
+): ResultArtifactReadOutcome {
+	const cached = cache?.lookup(descriptor);
+	if (cached !== undefined) return cached;
+	__test__resultReadStats.readFile += 1;
+	__test__resultReadStats.exists += 1;
+	// readIfSmall is a thin wrapper over readIfSmallWithTee(...).content — the
+	// direct call is byte-identical and also captures originalLength (R10-1
+	// tee-safety metadata consumed by readTaskResultArtifactWithTee).
+	const raw = readIfSmallWithTee(descriptor.path, { baseDir });
+	const outcome: ResultArtifactReadOutcome = {
+		body: raw?.content,
+		exists: containedExists(descriptor.path, baseDir),
+		...(raw?.originalLength !== undefined ? { originalLength: raw.originalLength } : {}),
+	};
+	cache?.store(descriptor, outcome);
+	return outcome;
+}
+
+/**
+ * R10-1 residual: cached read seam for the dependency-context path
+ * ({@link collectDependencyOutputContext}). Mirrors {@link readTaskResultArtifact}
+ * while preserving the tee-recovery semantics of the direct
+ * `readIfSmallWithTee(path, { tee })` call it replaces:
+ *
+ * - A cache hit is reusable ONLY when the memoized read proves the uncached
+ *   call would NOT have teed: `originalLength` is known AND
+ *   `originalLength <= TEE_THRESHOLD_MULTIPLIER × MAX_RESULT_INLINE_BYTES`.
+ *   In that band readIfSmallWithTee().content is byte-identical to the
+ *   memoized body (same file, same truncation pipeline) and fullOutputPath is
+ *   unset, so returning the memoized body cannot change the rendered prompt.
+ * - A memoized read that FAILED (body undefined) is also returned as-is: the
+ *   direct readIfSmallWithTee would have thrown and returned undefined for
+ *   the same descriptor identity.
+ * - Otherwise (miss, bypass, or tee-band truncation) the real
+ *   readIfSmallWithTee runs — WITH tee, so the per-consumer
+ *   `tee/<taskId>-<depId>.full.txt` write and `fullOutputPath` survive — and
+ *   the disk ops are counted in `__test__resultReadStats` exactly like
+ *   readTaskResultArtifact's miss branch (honest cached-vs-bypass benches).
+ *   When a cache is provided the miss ALSO populates it with the SAME
+ *   outcome readTaskResultArtifact would have stored (body = teeResult.content
+ *   — byte-identical to readIfSmall's output since tee never alters content —
+ *   exists via containedExists, originalLength), so the next dep collect /
+ *   closeout aggregation hits. Truncation checks in later consumers use
+ *   originalLength, never heuristics on the truncated body.
+ */
+function readTaskResultArtifactWithTee(
+	descriptor: ArtifactDescriptor,
+	baseDir: string | undefined,
+	tee: TeeRecoveryOptions | undefined,
+	cache: ResultArtifactReadCache | undefined,
+): ReadIfSmallTeeResult | undefined {
+	const cached = cache?.lookup(descriptor);
+	if (cached !== undefined) {
+		if (cached.body === undefined) return undefined;
+		if (cached.originalLength !== undefined && cached.originalLength <= MAX_RESULT_INLINE_BYTES * TEE_THRESHOLD_MULTIPLIER) {
+			return { content: cached.body };
+		}
+	}
+	__test__resultReadStats.readFile += 1;
+	const result = readIfSmallWithTee(descriptor.path, { baseDir, ...(tee ? { tee } : {}) });
+	if (cache) {
+		// Populate with the outcome the closeout seam would have stored. The op
+		// order (read → existsSync) matches readTaskResultArtifact's miss branch.
+		__test__resultReadStats.exists += 1;
+		cache.store(descriptor, {
+			body: result?.content,
+			exists: containedExists(descriptor.path, baseDir),
+			...(result?.originalLength !== undefined ? { originalLength: result.originalLength } : {}),
+		});
+	}
+	return result;
+}
+
+export function aggregateTaskOutputs(tasks: TeamTaskState[], manifest?: TeamRunManifest, cache?: ResultArtifactReadCache): string {
 	return tasks
 		.map((task, index) => {
-			const body = task.resultArtifact ? readIfSmall(task.resultArtifact.path, manifest?.artifactsRoot) : undefined;
+			const read = task.resultArtifact ? readTaskResultArtifact(task.resultArtifact, manifest?.artifactsRoot, cache) : undefined;
+			const body = read?.body;
 			const hasBody = Boolean(body?.trim());
-			const expectedMissing = task.resultArtifact && !containedExists(task.resultArtifact.path, manifest?.artifactsRoot);
+			const expectedMissing = read ? !read.exists : undefined;
 			const status =
 				task.status === "skipped"
 					? "SKIPPED"

package/src/runtime/task-packet.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
-import type { TaskPacket, TaskScope, TeamRunManifest, VerificationContract } from "../state/types.ts";
+import { freezeSpecSnapshot, loadSpecRecord } from "../state/stores/spec-store.ts";
+import type { SpecRecord, TaskPacket, TaskScope, TeamRunManifest, VerificationContract } from "../state/types.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { generateTaskHashId } from "./task-id.ts";
 
@@ -70,6 +71,10 @@ export function sanitizeTaskText(task: string): string {
 }
 
 export interface BuildTaskPacketInput {
+	/** T4/R6 (ADR-6 §2): workspace spec ids — loaded + FROZEN into the packet. */
+	specRefs?: string[];
+	/** T4/R6 (ADR-6 §7): strict mode — coverage AND machine-check (§4). */
+	specStrict?: boolean;
 	manifest: TeamRunManifest;
 	step: WorkflowStep;
 	taskId: string;
@@ -98,6 +103,20 @@ export function defaultVerificationContract(step: WorkflowStep): VerificationCon
 }
 
 export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
+	// T4/R6 (ADR-6 §1/§2): the ONLY packet-creation path is also the freeze
+	// point — specRefs load from the workspace store and freeze into immutable
+	// snapshots embedded in the packet (later spec edits never rewrite them).
+	// Round-1 review (fail-closed freeze): declared-but-unresolvable ids are
+	// kept on the packet as unresolvedSpecRefs instead of being dropped — the
+	// gate surfaces them (badge non-strict / failure strict), never a silent
+	// no-op. Snapshots freeze trust via the store at THIS moment.
+	const declaredSpecRefs = input.specRefs ?? [];
+	const resolvedRecords = declaredSpecRefs
+		.map((id) => loadSpecRecord(input.manifest.cwd, id))
+		.filter((r): r is SpecRecord => r !== undefined);
+	const specSnapshots = resolvedRecords.map((r) => freezeSpecSnapshot(r, input.manifest.cwd));
+	const unresolvedSpecRefs = declaredSpecRefs.filter((id) => !specSnapshots.some((s) => s.specId === id));
+
 	const scope = inferTaskScope(input.step);
 	const reads = input.step.reads === false ? [] : (input.step.reads ?? []);
 	const scopePath = reads.length === 1 ? reads[0] : reads.length > 1 ? reads.join(", ") : undefined;
@@ -112,6 +131,9 @@ export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
 
 	return {
 		objective: sanitizedTask.replaceAll("{goal}", sanitizedGoal),
+		...(declaredSpecRefs.length > 0 ? { specRefs: declaredSpecRefs, specSnapshots } : {}),
+		...(unresolvedSpecRefs.length > 0 ? { unresolvedSpecRefs } : {}),
+		...(input.specStrict === true ? { specStrict: true } : {}),
 		scope,
 		scopePath,
 		repo: path.basename(input.manifest.cwd) || input.manifest.cwd,