pi-crew 0.9.67 → 0.10.1

package/src/state/stores/spec-store.ts

@@ -0,0 +1,189 @@
+/**
+ * spec-store.ts — SpecRecord store + provenance mint (ADR-6 §1/§4, WP-6 step 2;
+ * round-1 security fix: provenance v2).
+ *
+ * TWO stores, split by trust:
+ * - WORKSPACE store `<projectCrewRoot(cwd)>/state/specs/<id>.json` — the
+ *   generated/worker-influenced store. NEVER trusted by the strict gate.
+ * - USER store `~/.pi/agent/specs/<projectSlug>/<id>.json` — the ONLY store a
+ *   user action (CLI import / explicit command) mints into. Trust lives here
+ *   because `.crew/state/` is worker-writable runtime state: any prompt-injected
+ *   worker can write a workspace `*.json` + `*.trusted` pair (round-1 P1).
+ *   Raising the anchor out of the workspace makes workspace tampering
+ *   structurally insufficient — no documented worker path writes `~/.pi/agent/specs`.
+ *
+ * Digest-bound sidecar: the user-store `<id>.trusted` marker contains the
+ * sha-256 of the canonical record JSON. `isSpecTrusted` verifies the binding,
+ * so editing a legitimately-minted record while keeping its real sidecar
+ * (content-swap attack) degrades to untrusted. Residual (documented in ADR
+ * erratum): a fully malicious same-user process can forge both files in
+ * `~/.pi/agent/specs` — but such a process already has arbitrary exec as the
+ * user; the gate defends against prompt-injected WORKERS via documented paths.
+ *
+ * Trust is evaluated ONCE at freeze (dispatch): `freezeSpecSnapshot` records
+ * `trustedAtFreeze` into the snapshot, and the strict gate reads ONLY that
+ * frozen bit — post-freeze mint/delete cannot affect a running task (TOCTOU
+ * window closed, round-1 P1 variant c).
+ */
+
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
+import type { SpecRecord, SpecSnapshot } from "../types.ts";
+
+function specsDir(cwd: string): string {
+	return path.join(projectCrewRoot(cwd), "state", "specs");
+}
+
+function userSpecsDir(cwd: string): string {
+	const slugSource = (() => {
+		try {
+			return fs.realpathSync(path.resolve(cwd));
+		} catch {
+			return path.resolve(cwd);
+		}
+	})();
+	const slug = createHash("sha256").update(slugSource).digest("hex").slice(0, 16);
+	return path.join(os.homedir(), ".pi", "agent", "specs", slug);
+}
+
+function recordPath(dir: string, id: string): string {
+	assertSafeSpecId(id);
+	return path.join(dir, `${id}.json`);
+}
+
+function sidecarPath(dir: string, id: string): string {
+	assertSafeSpecId(id);
+	return path.join(dir, `${id}.trusted`);
+}
+
+const SPEC_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function assertSafeSpecId(id: string): void {
+	if (!SPEC_ID_PATTERN.test(id)) throw new Error(`Invalid spec id: ${id}`);
+}
+
+/** Stable canonical JSON (sorted keys, recursive) — the digest basis. */
+export function canonicalSpecJson(value: unknown): string {
+	const sort = (v: unknown): unknown => {
+		if (Array.isArray(v)) return v.map(sort);
+		if (v && typeof v === "object") {
+			return Object.fromEntries(
+				Object.entries(v as Record<string, unknown>)
+					.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+					.map(([k, val]) => [k, sort(val)]),
+			);
+		}
+		return v;
+	};
+	return JSON.stringify(sort(value));
+}
+
+export interface SaveSpecOptions {
+	/** Only USER-facing actions (CLI import / explicit user command) may mint. */
+	userAction?: boolean;
+}
+
+export function saveSpecRecord(cwd: string, record: SpecRecord, options: SaveSpecOptions = {}): SpecRecord {
+	assertSafeSpecId(record.id);
+	const userAction = options.userAction === true;
+	if (userAction && record.source.kind === "manual") {
+		// USER store mint — the only trusted path. persisted.trusted mirrors the
+		// digest sidecar (informational); the gate reads the sidecar digest.
+		const persisted: SpecRecord = { ...record, trusted: true };
+		const dir = userSpecsDir(cwd);
+		fs.mkdirSync(dir, { recursive: true });
+		atomicWriteJson(recordPath(dir, record.id), persisted);
+		const digest = createHash("sha256").update(canonicalSpecJson(persisted), "utf8").digest("hex");
+		fs.writeFileSync(sidecarPath(dir, record.id), `${digest}\n`, "utf-8");
+		return persisted;
+	}
+	// Workspace store — the worker/skill path AND user-imported generated
+	// records. ALWAYS persisted generated + untrusted regardless of payload.
+	const persisted: SpecRecord = {
+		...record,
+		source: { ...record.source, kind: "generated" },
+		trusted: false,
+	};
+	fs.mkdirSync(specsDir(cwd), { recursive: true });
+	atomicWriteJson(recordPath(specsDir(cwd), record.id), persisted);
+	// Teardown any stale workspace sidecar (defense in depth: a hand-forged
+	// workspace sidecar must never resurrect trust).
+	try {
+		fs.unlinkSync(sidecarPath(specsDir(cwd), record.id));
+	} catch {
+		/* absent — fine */
+	}
+	return persisted;
+}
+
+function readRecordAt(file: string, id: string): SpecRecord | undefined {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as SpecRecord;
+		if (parsed?.id !== id) return undefined;
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+/** User store first (authoritative for trusted specs), then workspace.
+ *  Invalid/unsafe ids degrade to undefined (read path never throws). */
+export function loadSpecRecord(cwd: string, id: string): SpecRecord | undefined {
+	if (!SPEC_ID_PATTERN.test(id)) return undefined;
+	const fromUser = readRecordAt(recordPath(userSpecsDir(cwd), id), id);
+	if (fromUser) return fromUser;
+	return readRecordAt(recordPath(specsDir(cwd), id), id);
+}
+
+/** Strict-gate trust check — USER-store sidecar exists AND its sha-256 digest
+ *  binds to the record content. When `record` is provided (freeze path) the
+ *  binding is checked against THAT record, killing the content-swap attack on
+ *  legitimately-minted specs. */
+export function isSpecTrusted(cwd: string, id: string, record?: SpecRecord): boolean {
+	if (!SPEC_ID_PATTERN.test(id)) return false;
+	const dir = userSpecsDir(cwd);
+	const candidate = record ?? readRecordAt(recordPath(dir, id), id);
+	if (!candidate) return false;
+	try {
+		const sidecar = fs.readFileSync(sidecarPath(dir, id), "utf-8").trim();
+		const digest = createHash("sha256").update(canonicalSpecJson(candidate), "utf8").digest("hex");
+		return sidecar === digest;
+	} catch {
+		return false;
+	}
+}
+
+export function listSpecIds(cwd: string): string[] {
+	const ids = new Set<string>();
+	for (const dir of [userSpecsDir(cwd), specsDir(cwd)]) {
+		try {
+			for (const f of fs.readdirSync(dir)) {
+				if (!f.endsWith(".json")) continue;
+				const id = f.slice(0, -".json".length);
+				if (SPEC_ID_PATTERN.test(id)) ids.add(id);
+			}
+		} catch {
+			/* absent dir — fine */
+		}
+	}
+	return [...ids];
+}
+
+/** Freeze the current record into an immutable SpecSnapshot (dispatch time).
+ *  `trustedAtFreeze` is decided HERE — the strict gate never re-reads the live
+ *  sidecar, so post-freeze mint/delete cannot change a running task's trust. */
+export function freezeSpecSnapshot(record: SpecRecord, cwd: string): SpecSnapshot {
+	return {
+		specId: record.id,
+		version: record.version,
+		frozenAt: new Date().toISOString(),
+		trustedAtFreeze: isSpecTrusted(cwd, record.id, record),
+		items: record.requirements.flatMap((requirement) =>
+			record.acceptance.filter((a) => a.requirementId === requirement.id).map((acceptance) => ({ requirement, acceptance })),
+		),
+	};
+}

package/src/state/stores/state-store.ts

@@ -17,13 +17,15 @@ import {
 	flushPendingAtomicWrites,
 	readJsonFile,
 } from "../atomic-write.ts";
-import { canTransitionRunStatus, isTeamTaskStatus } from "../contracts.ts";
+import { canTransitionRunStatus } from "../contracts.ts";
 import { withRunLock, withRunLockSync } from "../coordination/locks.ts";
 import { appendEvent } from "../event-log/event-log.ts";
-import { reconstructTasksFromEvents } from "../event-log/event-reconstructor.ts";
 import type { TeamRunManifest, TeamTaskState } from "../types.ts";
-import { CURRENT_SCHEMA_VERSION, CURRENT_TASKS_SCHEMA_VERSION } from "../types.ts";
+import { CURRENT_SCHEMA_VERSION } from "../types.ts";
 import { unregisterActiveRun } from "./active-run-registry.ts";
+import { extractTaskArray, loadTasksWithRecovery, loadTasksWithRecoveryAsync, quarantineCorruptFile } from "./manifest-io.ts";
+
+export { loadManifestWithRecovery, loadTasksWithRecovery } from "./manifest-io.ts";
 
 /**
  * stat() the manifest with a brief retry on Windows for the AV-scan window.
@@ -87,6 +89,10 @@ export interface ManifestCacheEntry {
 // (e.g., parent + child processes writing to the same run) relies on the
 // mtime/size checks in loadRunManifestById, not on this counter.
 const manifestCacheGeneration = new Map<string, number>();
+// R5-M1 (Round 5 MEDIUM-1): safety-net FIFO cap. stateRoots are few in
+// practice, but nothing else bounded this Map — it leaked ~1 entry per run
+// for the process lifetime (manifestCache itself has TTL + LRU eviction).
+const MANIFEST_CACHE_GENERATION_MAX = 64;
 function genOf(stateRoot: string): number {
 	return manifestCacheGeneration.get(stateRoot) ?? 0;
 }
@@ -151,7 +157,20 @@ function invalidateRunCache(stateRoot: string): void {
 	// F1: only bump the generation of THIS stateRoot — sibling runs keep their
 	// generation intact, so concurrent writes to run A no longer evict run B's
 	// hot cache.
-	manifestCacheGeneration.set(stateRoot, genOf(stateRoot) + 1);
+	// R5-M1: delete-then-set couples this generation entry to the cache entry it
+	// guards (same lifecycle point) and refreshes its insertion order, so the
+	// FIFO safety net below evicts the least-recently-invalidated stateRoot.
+	const nextGen = genOf(stateRoot) + 1;
+	manifestCacheGeneration.delete(stateRoot);
+	manifestCacheGeneration.set(stateRoot, nextGen);
+	while (manifestCacheGeneration.size > MANIFEST_CACHE_GENERATION_MAX) {
+		const oldest = manifestCacheGeneration.keys().next().value;
+		if (oldest === undefined) break;
+		// Dropping a generation entry makes genOf read 0 — also drop that root's
+		// manifest cache entry so a 0-stamped entry can never falsely match.
+		manifestCache.delete(oldest);
+		manifestCacheGeneration.delete(oldest);
+	}
 }
 
 function scopeBaseRoot(cwd: string): string {
@@ -444,8 +463,13 @@ function shouldPersistTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]):
 	if (tasks.length > 0) return true;
 	const existing = extractTaskArray(readJsonFile<unknown>(manifest.tasksPath));
 	if (existing.length > 0) {
-		console.warn(
-			`[state-store] refusing to persist empty tasks over ${existing.length} existing task(s) — possible corrupt-load cascade (runId=${manifest.runId})`,
+		logInternalError(
+			"state-store",
+			new Error(
+				`refusing to persist empty tasks over ${existing.length} existing task(s) — possible corrupt-load cascade (runId=${manifest.runId})`,
+			),
+			undefined,
+			"warn",
 		);
 		return false;
 	}
@@ -693,6 +717,7 @@ export function __test__manifestCacheSize(): number {
 
 export function __test__clearManifestCache(): void {
 	manifestCache.clear();
+	manifestCacheGeneration.clear();
 }
 
 /**
@@ -707,17 +732,18 @@ export function __test__clearManifestCache(): void {
  * `fs.statSync`-based invalidation. It is a safe exit hatch for callers that
  * want a guaranteed cache drop (e.g. cleanup paths, end-of-run shutdown).
  *
- * Scope note: `flushPendingAtomicWrites()` flushes ALL pending coalesced
- * writes process-wide, not just those under `stateRoot`. The coalescer has no
- * per-stateRoot filter; flushing the whole queue is the simplest correct
- * behavior and matches the existing `flushPendingAtomicWrites()` contract
- * used by cleanupRuntime / process exit handlers.
+ * Scope note (R10-2): the flush is scoped to the run's `tasks.json` — the only
+ * file that (a) feeds this cache and (b) can have a pending coalesced write
+ * (`manifest.json` is only ever written through immediate/durable paths, and
+ * `agents.json`/`status.json` coalesced writes live outside this cache).
+ * Unrelated coalesced writes for OTHER runs stay pending on their own timers;
+ * unloading one run must not block on them.
  */
 export async function unloadRun(stateRoot: string): Promise<void> {
 	// Flush first so any in-flight buffered write lands on disk before we drop
 	// the cache entry. Otherwise a coalesced write could fire AFTER unloadRun
 	// returns, re-populate the cache from disk, and re-stale it.
-	flushPendingAtomicWrites();
+	flushPendingAtomicWrites(path.join(stateRoot, "tasks.json"));
 	// invalidateRunCache bumps the per-stateRoot generation counter so even if
 	// some in-process reader has a stale reference, the next cache lookup
 	// misses (generation mismatch) and re-reads from disk.
@@ -769,215 +795,6 @@ async function readJsonFileAsync<T>(filePath: string): Promise<T | undefined> {
 	}
 }
 
-/**
- * ST-4: Rename a corrupt file to a quarantine path (`.corrupt-<ts>`) so it is
- * preserved for debugging but no longer read as the primary source of truth.
- */
-function quarantineCorruptFile(filePath: string): void {
-	try {
-		fs.renameSync(filePath, `${filePath}.corrupt-${Date.now()}`);
-	} catch {
-		// Best-effort — if rename fails (file already gone, permission, etc.),
-		// we still proceed with reconstruction from the event log.
-	}
-}
-
-/**
- * ST-4: Convert event-reconstructor output into TeamTaskState[].
- * Reconstructed tasks carry lifecycle data (id, status, timing) from the
- * event log; auxiliary fields (role, agent, title) are filled with defaults
- * since they are not present in lifecycle events.
- */
-function reconstructTasksFromEventLog(eventsPath: string, runId: string): TeamTaskState[] {
-	try {
-		const result = reconstructTasksFromEvents(eventsPath);
-		const tasks: TeamTaskState[] = [];
-		for (const [, rt] of result.tasks) {
-			tasks.push({
-				id: rt.id,
-				runId,
-				role: "unknown",
-				agent: "unknown",
-				title: "reconstructed from events",
-				status: isTeamTaskStatus(rt.status) ? rt.status : "queued",
-				dependsOn: [],
-				cwd: "",
-				startedAt: rt.startedAt,
-				finishedAt: rt.finishedAt,
-				error: rt.error,
-				segment: rt.segment,
-				diagnostics: rt.diagnostics,
-				metrics: rt.metrics,
-			});
-		}
-		return tasks;
-	} catch {
-		return [];
-	}
-}
-
-/**
- * ST-4: Load tasks.json with corruption recovery (sync path).
- *
- * Distinguishes:
- * - ENOENT / ENOTDIR → legitimate empty → [] (NOT quarantined).
- * - SyntaxError (parse failure) → corrupt → quarantine `.corrupt-<ts>` AND
- *   reconstruct from events.jsonl. If reconstruction yields tasks, persist
- *   them so subsequent loads see a valid file.
- * - Non-array JSON (e.g. `{}`) → corrupt → same as SyntaxError.
- * - Valid array → return as-is.
- */
-
-/**
- * ST-9: Extract the task array from a tasks.json payload.
- *
- * Accepts both the v0 legacy bare-array format and the v1+ envelope
- * `{ schemaVersion, tasks }`. Returns [] for unrecognized shapes.
- */
-function extractTaskArray(raw: unknown): TeamTaskState[] {
-	if (Array.isArray(raw)) return raw as TeamTaskState[];
-	if (raw !== null && typeof raw === "object" && "tasks" in raw) {
-		const envelope = raw as { tasks?: unknown };
-		if (Array.isArray(envelope.tasks)) return envelope.tasks as TeamTaskState[];
-	}
-	return [];
-}
-
-/**
- * ST-9: Whether `parsed` is a recognizable tasks.json shape (v0 bare array
- * or v1+ envelope). Used to distinguish legitimate formats from corruption.
- */
-function isRecognizableTasksPayload(parsed: unknown): boolean {
-	if (Array.isArray(parsed)) return true;
-	if (parsed !== null && typeof parsed === "object" && "tasks" in parsed) {
-		return Array.isArray((parsed as { tasks?: unknown }).tasks);
-	}
-	return false;
-}
-
-/**
- * ST-9: Version-check + migration hook for tasks.json.
- *
- * tasks.json has two on-disk shapes:
- * - v0 (current): bare JSON array `TeamTaskState[]` — what saveRunTasks*
- *   write today (backward-compatible; no schemaVersion envelope).
- * - v1+ (future): envelope `{ schemaVersion: number, tasks: TeamTaskState[] }`
- *   — read-supported defensively for a future write-side switch.
- *
- * This detects the shape and returns the task array. v0 needs NO migration
- * (it IS the current write format). For v1+ envelopes, a schemaVersion
- * mismatch warns (mirroring the manifest check). Future breaking changes
- * add real migration logic here.
- */
-function migrateTasksFile(parsed: unknown, runId: string): TeamTaskState[] {
-	// v0 current: bare array (no schemaVersion envelope) — what writers produce.
-	if (Array.isArray(parsed)) {
-		// v0 bare array is the CURRENT write format (saveRunTasks* write the
-		// array directly, by design — backward compat). Nothing to migrate:
-		// return as-is. (v1+ envelope read-support below is defensive, for a
-		// future write-side switch.) Do NOT warn here — it would fire for 100%
-		// of runs on every load and flood the UI on startup.
-		return parsed as TeamTaskState[];
-	}
-	// v1+ envelope: { schemaVersion, tasks }.
-	if (parsed !== null && typeof parsed === "object" && "tasks" in parsed) {
-		const envelope = parsed as { schemaVersion?: unknown; tasks?: unknown };
-		const detected = typeof envelope.schemaVersion === "number" ? envelope.schemaVersion : 0;
-		if (detected !== CURRENT_TASKS_SCHEMA_VERSION) {
-			console.warn(
-				`[state-store] tasks.json schemaVersion mismatch: expected ${CURRENT_TASKS_SCHEMA_VERSION}, got ${detected}. Run ${runId} may be incompatible.`,
-			);
-		}
-	}
-	return extractTaskArray(parsed);
-}
-export function loadTasksWithRecovery(tasksPath: string, eventsPath: string, runId: string): TeamTaskState[] {
-	let content: string;
-	try {
-		content = fs.readFileSync(tasksPath, "utf-8");
-	} catch {
-		// ENOENT / ENOTDIR / other read errors → empty (retry loop handles
-		// transient instability; ENOENT is a legitimate empty run).
-		return [];
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(content);
-	} catch {
-		// SyntaxError — corrupt file.
-		quarantineCorruptFile(tasksPath);
-		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
-		if (reconstructed.length > 0) atomicWriteJson(tasksPath, reconstructed, { compact: true });
-		return reconstructed;
-	}
-	if (!isRecognizableTasksPayload(parsed)) {
-		// Neither v0 bare array nor v1+ envelope (e.g. `{}`) — corrupt.
-		quarantineCorruptFile(tasksPath);
-		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
-		if (reconstructed.length > 0) atomicWriteJson(tasksPath, reconstructed, { compact: true });
-		return reconstructed;
-	}
-	return migrateTasksFile(parsed, runId);
-}
-
-/**
- * STATE-3: Load manifest.json with corruption quarantine (sync). Distinguishes:
- * - ENOENT / read error → undefined (legitimate missing run — NOT quarantined).
- * - SyntaxError (unparseable) → CORRUPT → quarantine `.corrupt-<ts>` + log + undefined.
- *   Manifest CANNOT be reconstructed from events.jsonl (run.created only carries
- *   {team, workflow}), so quarantine + visible log is the recovery — do NOT attempt
- *   reconstruction (unlike loadTasksWithRecovery). This prevents a corrupt manifest
- *   from silently making a run invisible (STATE-3).
- */
-export function loadManifestWithRecovery(manifestPath: string, runId: string): TeamRunManifest | undefined {
-	let content: string;
-	try {
-		content = fs.readFileSync(manifestPath, "utf-8");
-	} catch {
-		// ENOENT / ENOTDIR / other read error → legitimate missing run.
-		return undefined;
-	}
-	try {
-		return JSON.parse(content) as TeamRunManifest;
-	} catch {
-		// SyntaxError → corrupt manifest. Quarantine (preserve for diagnosis) + log,
-		// then treat as missing. Do NOT reconstruct (infeasible from events).
-		quarantineCorruptFile(manifestPath);
-		console.error(
-			`[state-store] STATE-3: manifest.json for run ${runId} is corrupt (unparseable) — quarantined to ${manifestPath}.corrupt-*. Run is now treated as missing. Preserve the .corrupt-* file for diagnosis.`,
-		);
-		return undefined;
-	}
-}
-
-/**
- * ST-4: async twin of {@link loadTasksWithRecovery}.
- */
-async function loadTasksWithRecoveryAsync(tasksPath: string, eventsPath: string, runId: string): Promise<TeamTaskState[]> {
-	let content: string;
-	try {
-		content = await fs.promises.readFile(tasksPath, "utf-8");
-	} catch {
-		return [];
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(content);
-	} catch {
-		quarantineCorruptFile(tasksPath);
-		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
-		if (reconstructed.length > 0) await atomicWriteJsonAsync(tasksPath, reconstructed, { compact: true });
-		return reconstructed;
-	}
-	if (!isRecognizableTasksPayload(parsed)) {
-		quarantineCorruptFile(tasksPath);
-		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
-		if (reconstructed.length > 0) await atomicWriteJsonAsync(tasksPath, reconstructed, { compact: true });
-		return reconstructed;
-	}
-	return migrateTasksFile(parsed, runId);
-}
-
 /**
  * Load a run manifest and its tasks by runId.
  * WARNING: This function provides best-effort consistency only. The sentinel-based
@@ -1094,8 +911,13 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 	// S-01: warn (do not throw) on schemaVersion mismatch — future version
 	// bumps will add migration logic here.
 	if (manifest && manifest.schemaVersion !== CURRENT_SCHEMA_VERSION) {
-		console.warn(
-			`[state-store] Manifest schemaVersion mismatch: expected ${CURRENT_SCHEMA_VERSION}, got ${manifest.schemaVersion}. Run ${runId} may be incompatible.`,
+		logInternalError(
+			"state-store",
+			new Error(
+				`Manifest schemaVersion mismatch: expected ${CURRENT_SCHEMA_VERSION}, got ${manifest.schemaVersion}. Run ${runId} may be incompatible.`,
+			),
+			undefined,
+			"warn",
 		);
 	}
 	// STATE-3: readJsonFile returns undefined for BOTH missing (ENOENT) and corrupt
@@ -1105,8 +927,13 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 	// infeasible (run.created lacks manifest fields), so quarantine+log is the recovery.
 	if (!manifest && fs.existsSync(manifestPath)) {
 		quarantineCorruptFile(manifestPath);
-		console.error(
-			`[state-store] STATE-3: manifest.json for run ${runId} exists but is unparseable — quarantined. Run treated as missing; preserve the .corrupt-* file for diagnosis.`,
+		logInternalError(
+			"state-store",
+			new Error(
+				`STATE-3: manifest.json for run ${runId} exists but is unparseable — quarantined. Run treated as missing; preserve the .corrupt-* file for diagnosis.`,
+			),
+			undefined,
+			"error",
 		);
 		return undefined;
 	}
@@ -1231,8 +1058,13 @@ export async function loadRunManifestByIdAsync(
 	// S-01: warn (do not throw) on schemaVersion mismatch — future version
 	// bumps will add migration logic here.
 	if (manifest && manifest.schemaVersion !== CURRENT_SCHEMA_VERSION) {
-		console.warn(
-			`[state-store] Manifest schemaVersion mismatch: expected ${CURRENT_SCHEMA_VERSION}, got ${manifest.schemaVersion}. Run ${runId} may be incompatible.`,
+		logInternalError(
+			"state-store",
+			new Error(
+				`Manifest schemaVersion mismatch: expected ${CURRENT_SCHEMA_VERSION}, got ${manifest.schemaVersion}. Run ${runId} may be incompatible.`,
+			),
+			undefined,
+			"warn",
 		);
 	}
 	// STATE-3 (async twin): readJsonFileAsync returns undefined for BOTH missing (ENOENT)
@@ -1242,8 +1074,13 @@ export async function loadRunManifestByIdAsync(
 	// lacks manifest fields), so quarantine+log is the recovery.
 	if (!manifest && fs.existsSync(manifestPath)) {
 		quarantineCorruptFile(manifestPath);
-		console.error(
-			`[state-store] STATE-3 async: manifest.json for run ${runId} exists but is unparseable — quarantined. Run treated as missing; preserve the .corrupt-* file for diagnosis.`,
+		logInternalError(
+			"state-store",
+			new Error(
+				`STATE-3 async: manifest.json for run ${runId} exists but is unparseable — quarantined. Run treated as missing; preserve the .corrupt-* file for diagnosis.`,
+			),
+			undefined,
+			"error",
 		);
 		return undefined;
 	}