@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/lib/runs-descendant-launches.ts

@@ -0,0 +1,338 @@
+/**
+ * Descendant Run launch-intent evidence.
+ * Owns: declared/prepared parent-child generation facts, strict persistence, and unresolved-scope mutation fences.
+ * Excludes: authenticating child birth/membership, work/control authority, exhaustive scope, and termination.
+ */
+
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export const RUN_DESCENDANT_LAUNCH_FILE = "descendant-launches.json";
+export const RUN_DESCENDANT_PREPARATION_FILE = "descendant-preparation.json";
+export const RUN_DESCENDANT_PREPARED_META_FILE = "prepared-run.json";
+const SCHEMA = "run-descendant-launches-v1";
+const PREPARATION_SCHEMA = "run-descendant-preparation-v1";
+
+export interface RunDescendantLaunchOwner {
+  readonly run: string;
+  readonly runInstanceId: string;
+  readonly ownerId?: string;
+  readonly pid: number;
+  readonly processIdentityDigest?: string;
+}
+
+export interface RunDescendantLaunchRequest {
+  readonly run: string;
+  readonly runInstanceId: string;
+  readonly ownerId?: string;
+  readonly stateDir: string;
+}
+
+export interface RunDescendantLaunchTarget {
+  readonly run: string;
+  readonly run_instance_id: string;
+  readonly ownerId?: string;
+  readonly state_dir: string;
+}
+
+export interface RunDescendantPreparedFact {
+  readonly preparation_id: string;
+  readonly prepared_at: string;
+}
+
+/** Persisted reference to the original producer, never a reconstructed runtime capability or native membership proof. */
+export interface RunDescendantProducerBinding {
+  readonly pid: number;
+  readonly process_identity_digest: string | null;
+}
+
+export interface RunDescendantPreparation extends RunDescendantPreparedFact {
+  readonly schema: typeof PREPARATION_SCHEMA;
+  readonly parent: Readonly<RunDescendantLaunchTarget>;
+  readonly child: Readonly<RunDescendantLaunchTarget>;
+  // Absent only in retained unbound metadata; new prepared facts require the original binding.
+  readonly parent_producer?: Readonly<RunDescendantProducerBinding>;
+}
+
+export interface RunDescendantLaunchIntent {
+  readonly intent_id: string;
+  readonly admitted_at: string;
+  readonly child: Readonly<RunDescendantLaunchTarget>;
+  readonly preparation?: Readonly<RunDescendantPreparedFact>;
+}
+
+export interface RunDescendantLaunchLedger {
+  readonly schema: typeof SCHEMA;
+  readonly run: string;
+  readonly run_instance_id: string;
+  readonly ownerId?: string;
+  readonly runner_pid: number;
+  readonly runner_identity_digest: string | null;
+  readonly intents: readonly Readonly<RunDescendantLaunchIntent>[];
+}
+
+export type RunDescendantLaunchReading =
+  | { state: "absent" | "invalid" }
+  | { state: "available"; ledger: Readonly<RunDescendantLaunchLedger> };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function required(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return keys.every((key) => Object.hasOwn(value, key));
+}
+
+function text(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function optionalText(value: Record<string, unknown>, key: string): boolean {
+  return !(key in value) || (Object.hasOwn(value, key) && (value[key] === undefined || text(value[key])));
+}
+
+function validOwner(value: unknown): value is RunDescendantLaunchOwner {
+  if (!record(value) || !required(value, ["run", "runInstanceId", "pid"]) ||
+    !text(value.run) || !text(value.runInstanceId) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 ||
+    !optionalText(value, "ownerId")) return false;
+  return !("processIdentityDigest" in value) || (Object.hasOwn(value, "processIdentityDigest") &&
+    (value.processIdentityDigest === undefined || (typeof value.processIdentityDigest === "string" &&
+      /^[a-f0-9]{64}$/.exec(value.processIdentityDigest)?.[0] === value.processIdentityDigest)));
+}
+
+function intentId(value: unknown): value is string {
+  return typeof value === "string" &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.exec(value)?.[0] === value;
+}
+
+function timestamp(value: unknown): value is string {
+  if (!text(value)) return false;
+  try { return new Date(value).toISOString() === value; } catch { return false; }
+}
+
+function decodeReference(value: unknown): Readonly<RunDescendantLaunchTarget> | undefined {
+  if (!record(value) || !onlyKeys(value, ["run", "run_instance_id", "ownerId", "state_dir"]) ||
+    !required(value, ["run", "run_instance_id", "state_dir"]) || typeof value.run !== "string" ||
+    /^[A-Za-z0-9_.-]+$/.exec(value.run)?.[0] !== value.run || !text(value.run_instance_id) ||
+    !optionalText(value, "ownerId") || !text(value.state_dir) || !isAbsolute(value.state_dir) ||
+    resolve(value.state_dir) !== value.state_dir) return undefined;
+  // A normalized declaration is not filesystem identity, existence, or child ownership proof.
+  return Object.freeze({ run: value.run, run_instance_id: value.run_instance_id,
+    ...(value.ownerId === undefined ? {} : { ownerId: String(value.ownerId) }), state_dir: value.state_dir });
+}
+
+function decodeTarget(value: unknown, owner: RunDescendantLaunchOwner, stateDir: string): Readonly<RunDescendantLaunchTarget> | undefined {
+  const target = decodeReference(value);
+  return target && target.run_instance_id !== owner.runInstanceId && target.state_dir !== stateDir ? target : undefined;
+}
+
+function decodePreparedFact(value: unknown): Readonly<RunDescendantPreparedFact> | undefined {
+  if (!record(value) || !onlyKeys(value, ["preparation_id", "prepared_at"]) ||
+    !intentId(value.preparation_id) || !timestamp(value.prepared_at)) return undefined;
+  return Object.freeze({ preparation_id: value.preparation_id, prepared_at: value.prepared_at });
+}
+
+function decodeProducerBinding(value: unknown): Readonly<RunDescendantProducerBinding> | undefined {
+  if (!record(value) || !onlyKeys(value, ["pid", "process_identity_digest"]) ||
+    !required(value, ["pid", "process_identity_digest"]) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 ||
+    (value.process_identity_digest !== null && (typeof value.process_identity_digest !== "string" ||
+      /^[a-f0-9]{64}$/.exec(value.process_identity_digest)?.[0] !== value.process_identity_digest))) return undefined;
+  return Object.freeze({ pid: Number(value.pid), process_identity_digest: value.process_identity_digest as string | null });
+}
+
+function decodePreparation(value: unknown): Readonly<RunDescendantPreparation> | undefined {
+  if (!record(value) || !onlyKeys(value, ["schema", "preparation_id", "prepared_at", "parent", "child", "parent_producer"]) ||
+    value.schema !== PREPARATION_SCHEMA || !intentId(value.preparation_id) || !timestamp(value.prepared_at)) return undefined;
+  const parent = decodeReference(value.parent);
+  const child = decodeReference(value.child);
+  const producer = Object.hasOwn(value, "parent_producer") ? decodeProducerBinding(value.parent_producer) : undefined;
+  if (!parent || !child || parent.run_instance_id === child.run_instance_id || parent.state_dir === child.state_dir ||
+    ("parent_producer" in value && (!Object.hasOwn(value, "parent_producer") || !producer))) return undefined;
+  return Object.freeze({ schema: PREPARATION_SCHEMA, preparation_id: value.preparation_id, prepared_at: value.prepared_at, parent, child,
+    ...(producer ? { parent_producer: producer } : {}) });
+}
+
+function sameReference(a: RunDescendantLaunchTarget, b: RunDescendantLaunchTarget): boolean {
+  return a.run === b.run && a.run_instance_id === b.run_instance_id && a.ownerId === b.ownerId && a.state_dir === b.state_dir;
+}
+
+/** Validated reference data only; resolving a target never grants work or membership authority. */
+export function resolveRunDescendantLaunchTarget(value: unknown, owner: RunDescendantLaunchOwner, stateDir: string): Readonly<RunDescendantLaunchTarget> | undefined {
+  if (!record(value) || !onlyKeys(value, ["run", "runInstanceId", "ownerId", "stateDir"]) ||
+    !required(value, ["run", "runInstanceId", "stateDir"]) || !optionalText(value, "ownerId")) return undefined;
+  return decodeTarget({ run: value.run, run_instance_id: value.runInstanceId,
+    ...(value.ownerId === undefined ? {} : { ownerId: value.ownerId }), state_dir: value.stateDir }, owner, stateDir);
+}
+
+function decode(value: unknown, owner: RunDescendantLaunchOwner, stateDir: string): Readonly<RunDescendantLaunchLedger> | undefined {
+  if (!record(value) || !onlyKeys(value, ["schema", "run", "run_instance_id", "ownerId", "runner_pid", "runner_identity_digest", "intents"]) ||
+    value.schema !== SCHEMA || value.run !== owner.run || value.run_instance_id !== owner.runInstanceId ||
+    value.ownerId !== owner.ownerId || value.runner_pid !== owner.pid ||
+    value.runner_identity_digest !== (owner.processIdentityDigest ?? null) || !Array.isArray(value.intents)) return undefined;
+  const ids = new Set<string>();
+  const generations = new Set<string>();
+  const preparations = new Set<string>();
+  const intents: Readonly<RunDescendantLaunchIntent>[] = [];
+  for (const item of value.intents) {
+    if (!record(item) || !onlyKeys(item, ["intent_id", "admitted_at", "child", "preparation"]) || !intentId(item.intent_id) ||
+      ids.has(item.intent_id) || !timestamp(item.admitted_at)) return undefined;
+    const child = decodeTarget(item.child, owner, stateDir);
+    const preparation = item.preparation === undefined ? undefined : decodePreparedFact(item.preparation);
+    if (!child || generations.has(child.run_instance_id) || (item.preparation !== undefined && !preparation) ||
+      (preparation && preparations.has(preparation.preparation_id))) return undefined;
+    ids.add(item.intent_id);
+    generations.add(child.run_instance_id);
+    if (preparation) preparations.add(preparation.preparation_id);
+    intents.push(Object.freeze({ intent_id: item.intent_id, admitted_at: item.admitted_at, child,
+      ...(preparation ? { preparation } : {}) }));
+  }
+  return Object.freeze({ schema: SCHEMA, run: owner.run, run_instance_id: owner.runInstanceId,
+    ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }), runner_pid: owner.pid,
+    runner_identity_digest: owner.processIdentityDigest ?? null, intents: Object.freeze(intents) });
+}
+
+/** Only ENOENT permits mutation; an empty or invalid journal is not closure proof. */
+export function assertNoRetainedDescendantLaunchScope(stateDir: string): void {
+  assertNoRetainedDescendantFiles(stateDir, [RUN_DESCENDANT_LAUNCH_FILE, RUN_DESCENDANT_PREPARATION_FILE, RUN_DESCENDANT_PREPARED_META_FILE]);
+}
+
+function assertNoRetainedDescendantFiles(stateDir: string, files: readonly string[]): void {
+  for (const file of files) {
+    try { lstatSync(join(stateDir, file)); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; }
+    throw new Error("Run descendant launch scope is unproven; confirm the complete owned scope before replacing or retiring its state.");
+  }
+}
+
+/** Declared generations and paths confer no child work/control authority or exhaustive membership. */
+export function readRunDescendantLaunchLedger(stateDir: string, owner: RunDescendantLaunchOwner): RunDescendantLaunchReading {
+  if (!validOwner(owner)) return { state: "invalid" };
+  let canonical: string;
+  try { canonical = assertOwnedRunStateDirectory(stateDir, owner.run); }
+  catch { return { state: "invalid" }; }
+  const path = join(canonical, RUN_DESCENDANT_LAUNCH_FILE);
+  try { if (!lstatSync(path).isFile()) return { state: "invalid" }; }
+  catch (error) { return { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "absent" : "invalid" }; }
+  const read = readJsonFileResilient<unknown>(path, undefined);
+  if (read.diagnostics.length) return { state: "invalid" };
+  const ledger = decode(read.value, owner, canonical);
+  return ledger ? { state: "available", ledger } : { state: "invalid" };
+}
+
+/** Retained preparation data is evidence, never a native-start or membership capability. */
+export function readRunDescendantPreparation(
+  stateDir: string,
+  child: RunDescendantLaunchTarget,
+  parent: RunDescendantLaunchTarget,
+): Readonly<RunDescendantPreparation> | undefined {
+  try {
+    const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+    const path = join(canonical, RUN_DESCENDANT_PREPARATION_FILE);
+    if (!lstatSync(path).isFile()) return undefined;
+    const value = decodePreparation(JSON.parse(readFileSync(path, "utf8")));
+    return value && child.state_dir === canonical && sameReference(value.child, child) && sameReference(value.parent, parent) ? value : undefined;
+  } catch { return undefined; }
+}
+
+/** Fresh evidence checks only, not a capability reconstructed from staged metadata. */
+export function assertRunDescendantPreparedMetadata(stateDir: string, child: RunDescendantLaunchTarget): void {
+  const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+  let unpublished = false;
+  try { lstatSync(join(canonical, "run.json")); }
+  catch (error) { unpublished = (error as NodeJS.ErrnoException).code === "ENOENT"; }
+  if (!unpublished) throw new Error("Run descendant preparation is published or unavailable.");
+  const path = join(canonical, RUN_DESCENDANT_PREPARED_META_FILE);
+  if (!lstatSync(path).isFile()) throw new Error("Run descendant prepared metadata is unavailable or invalid.");
+  const meta: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!record(meta) || meta.run !== child.run || meta.run_instance_id !== child.run_instance_id ||
+    meta.ownerId !== child.ownerId || meta.state_dir !== canonical || child.state_dir !== canonical ||
+    meta.pid !== 0 || meta.process_identity !== undefined) {
+    throw new Error("Run descendant prepared metadata is unavailable or invalid.");
+  }
+}
+
+/** Storage only: the kernel prepare-only branch owns child creation and holds parent then child lifecycle locks. */
+export function recordRunDescendantPreparationUnderLock(
+  stateDir: string,
+  child: RunDescendantLaunchTarget,
+  parent: RunDescendantLaunchTarget,
+  producer: RunDescendantLaunchOwner,
+): Readonly<RunDescendantPreparation> {
+  const parentReference = decodeReference(parent);
+  if (!validOwner(producer) || !parentReference || parentReference.run !== producer.run ||
+    parentReference.run_instance_id !== producer.runInstanceId || parentReference.ownerId !== producer.ownerId) {
+    throw new Error("Run descendant preparation producer binding is invalid.");
+  }
+  const canonical = assertOwnedRunStateDirectory(stateDir, child.run);
+  assertNoRetainedDescendantFiles(canonical, [RUN_DESCENDANT_LAUNCH_FILE, RUN_DESCENDANT_PREPARATION_FILE]);
+  assertRunDescendantPreparedMetadata(canonical, child);
+  const preparation = decodePreparation({ schema: PREPARATION_SCHEMA, preparation_id: randomUUID(),
+    prepared_at: new Date().toISOString(), child, parent: parentReference,
+    parent_producer: { pid: producer.pid, process_identity_digest: producer.processIdentityDigest ?? null } });
+  if (!preparation || preparation.child.state_dir !== canonical) throw new Error("Run descendant preparation binding is invalid.");
+  writeJsonAtomic(join(canonical, RUN_DESCENDANT_PREPARATION_FILE), preparation);
+  return preparation;
+}
+
+/** Storage only: bare intents require work admission; prepared facts may use evidence admission. Validate child evidence under its lock. */
+export function recordRunDescendantLaunchIntentUnderLock(
+  stateDir: string,
+  owner: RunDescendantLaunchOwner,
+  request: RunDescendantLaunchRequest,
+  preparation?: RunDescendantPreparation,
+): Readonly<RunDescendantLaunchIntent> {
+  if (!validOwner(owner)) throw new Error("Run descendant launch identity or request is invalid.");
+  const canonical = assertOwnedRunStateDirectory(stateDir, owner.run);
+  const child = resolveRunDescendantLaunchTarget(request, owner, canonical);
+  if (!child) throw new Error("Run descendant launch identity or request is invalid.");
+  const current = readRunDescendantLaunchLedger(canonical, owner);
+  if (current.state === "invalid") throw new Error("Run descendant launch evidence is unavailable or invalid.");
+  const prior = current.state === "available" ? current.ledger.intents : [];
+  const index = prior.findIndex((item) => item.child.run_instance_id === child.run_instance_id);
+  const existing = prior[index];
+  if (existing && preparation === undefined) throw new Error("Run descendant launch generation is already retained.");
+  if (existing && !sameReference(existing.child, child)) throw new Error("Run descendant preparation target changed.");
+  let prepared: Readonly<RunDescendantPreparedFact> | undefined;
+  if (preparation !== undefined) {
+    const parent = { run: owner.run, run_instance_id: owner.runInstanceId,
+      ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }), state_dir: canonical };
+    const claimed = decodePreparation(preparation);
+    if (!claimed || !sameReference(claimed.parent, parent) || !sameReference(claimed.child, child)) {
+      throw new Error("Run descendant preparation binding changed or is unavailable.");
+    }
+    if (existing?.preparation && (existing.preparation.preparation_id !== claimed.preparation_id ||
+      existing.preparation.prepared_at !== claimed.prepared_at)) {
+      throw new Error("Run descendant preparation binding changed or is unavailable.");
+    }
+    const retained = readRunDescendantPreparation(child.state_dir, child, parent);
+    if (!retained || JSON.stringify(claimed) !== JSON.stringify(retained)) {
+      throw new Error("Run descendant preparation binding changed or is unavailable.");
+    }
+    assertRunDescendantPreparedMetadata(child.state_dir, child);
+    if (existing?.preparation) return existing;
+    if (!retained.parent_producer || retained.parent_producer.pid !== owner.pid ||
+      retained.parent_producer.process_identity_digest !== (owner.processIdentityDigest ?? null)) {
+      throw new Error("Run descendant preparation producer binding changed or is unavailable.");
+    }
+    prepared = Object.freeze({ preparation_id: retained.preparation_id, prepared_at: retained.prepared_at });
+  }
+  const intent = existing ? Object.freeze({ ...existing, preparation: prepared! })
+    : Object.freeze({ intent_id: randomUUID(), admitted_at: new Date().toISOString(), child,
+        ...(prepared ? { preparation: prepared } : {}) });
+  const intents = existing ? prior.map((item, i) => i === index ? intent : item) : [...prior, intent];
+  const updated = decode({ schema: SCHEMA, run: owner.run, run_instance_id: owner.runInstanceId,
+    ...(owner.ownerId === undefined ? {} : { ownerId: owner.ownerId }), runner_pid: owner.pid,
+    runner_identity_digest: owner.processIdentityDigest ?? null, intents }, owner, canonical);
+  if (!updated) throw new Error("Run descendant launch evidence is unavailable or invalid.");
+  writeJsonAtomic(join(canonical, RUN_DESCENDANT_LAUNCH_FILE), updated);
+  return updated.intents[existing ? index : updated.intents.length - 1]!;
+}

package/node_modules/@llblab/pi-actors/lib/runs-execution-evidence.ts

@@ -0,0 +1,302 @@
+/**
+ * Owned-generation execution evidence and explicit kernel source selection.
+ * Owns: data-only manifest projection, recorded capture/session reference admission and checked canonical runner stream input.
+ * Excludes: raw-body exposure permission, session discovery, primary-source completeness, producer/work authority and native closure.
+ */
+import { lstatSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { observeExecutionFileReference, readExecutionRunnerStreamText } from "./execution-files.ts";
+import { createRunRecipeEvidenceRedactor } from "./recipe-projection.ts";
+import { readRunContextIdentity, RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, type RunContextIndexIdentity } from "./runs-context-index.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+// --- Manifest projection ---
+
+export interface ExecutionCaptureView {
+  readonly reported_saved_bytes: number | null;
+  readonly persistence: "incomplete" | "reported_complete" | "unproven";
+  readonly reported_observed_bytes?: number;
+  readonly error?: "capture_write_failed";
+}
+export interface ExecutionAttemptView {
+  readonly attempt: number;
+  readonly code: number;
+  readonly native_exit_code?: number | null;
+  readonly native_signal?: string;
+  readonly reported_killed?: boolean;
+  readonly stdout: Readonly<ExecutionCaptureView>;
+  readonly stderr: Readonly<ExecutionCaptureView>;
+}
+export interface ExecutionCommandView {
+  readonly id: string;
+  readonly reported_status: string;
+  readonly attempts: readonly Readonly<ExecutionAttemptView>[];
+  readonly stage?: string;
+  readonly command?: string;
+  readonly label?: string;
+  readonly occurrence?: number;
+  readonly branch_index?: number;
+  readonly prompt_bytes?: number;
+  readonly started_at?: string;
+  readonly completed_at?: string;
+  readonly semantic_acceptance?: string;
+  readonly exit_code?: number;
+  readonly effective_exit_code?: number;
+  readonly native_exit_code?: number | null;
+  readonly reported_killed?: boolean;
+  readonly interruption?: string;
+  readonly reported_session_file_count?: number;
+}
+export interface RunExecutionView {
+  readonly reported_status: string;
+  readonly updated_at: string;
+  readonly reported_active_subagents: number;
+  readonly commands_total: number;
+  readonly settled_attempts_reported: number;
+  readonly commands: readonly Readonly<ExecutionCommandView>[];
+}
+export type RunExecutionProjection = { readonly state: "available"; readonly view: Readonly<RunExecutionView> }
+  | { readonly state: "unavailable"; readonly reason: "manifest_invalid" | "identity_mismatch" };
+
+function manifestField(value: Record<string, unknown>, key: string): unknown { return Object.hasOwn(value, key) ? value[key] : undefined; }
+function count(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; }
+function code(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value); }
+function timestamp(value: unknown): value is string {
+  const time = typeof value === "string" ? Date.parse(value) : NaN;
+  return Number.isSafeInteger(time) && new Date(time).toISOString() === value;
+}
+function capture(value: unknown): Readonly<ExecutionCaptureView> | undefined {
+  const source = record(value);
+  if (!source) return undefined;
+  const saved = manifestField(source, "bytes");
+  const observed = manifestField(source, "bytes_observed");
+  const complete = manifestField(source, "complete");
+  const error = manifestField(source, "error");
+  if ((saved !== null && !count(saved)) || (observed !== undefined && !count(observed)) ||
+    (complete !== undefined && typeof complete !== "boolean") || (error !== undefined && error !== "capture_write_failed") ||
+    (typeof saved === "number" && typeof observed === "number" && saved > observed) || (error !== undefined && complete !== false)) return undefined;
+  return Object.freeze({ reported_saved_bytes: saved,
+    persistence: complete === false ? "incomplete" : saved === null ? "unproven" : "reported_complete",
+    ...(typeof observed === "number" ? { reported_observed_bytes: observed } : {}), ...(error ? { error } : {}) });
+}
+function attempt(value: unknown, ordinal: number): Readonly<ExecutionAttemptView> | undefined {
+  const source = record(value);
+  if (!source || manifestField(source, "attempt") !== ordinal || !code(manifestField(source, "code"))) return undefined;
+  const nativeCode = manifestField(source, "native_exit_code");
+  const signal = manifestField(source, "native_signal");
+  const killed = manifestField(source, "killed");
+  if ((nativeCode !== undefined && nativeCode !== null && !code(nativeCode)) ||
+    (signal !== undefined && (typeof signal !== "string" || !/^SIG[A-Z0-9]{1,31}$/u.test(signal))) ||
+    (killed !== undefined && typeof killed !== "boolean")) return undefined;
+  const stdout = capture(manifestField(source, "stdout"));
+  const stderr = capture(manifestField(source, "stderr"));
+  if (!stdout || !stderr) return undefined;
+  return Object.freeze({ attempt: ordinal, code: source.code as number, stdout, stderr,
+    ...(nativeCode !== undefined ? { native_exit_code: nativeCode as number | null } : {}),
+    ...(typeof signal === "string" ? { native_signal: signal } : {}),
+    ...(typeof killed === "boolean" ? { reported_killed: killed } : {}) });
+}
+
+/** Already-captured metadata is data, never a reconstructed producer/work/close capability. */
+export function projectRunExecutionManifest(
+  expected: { readonly run: string; readonly run_instance_id: string },
+  value: unknown,
+  recipe: Record<string, unknown> = {},
+  redactEvidence?: (value: unknown) => unknown,
+): Readonly<RunExecutionProjection> {
+  const invalid = (): Readonly<RunExecutionProjection> => Object.freeze({ state: "unavailable", reason: "manifest_invalid" });
+  const identity = record(expected);
+  const source = record(value);
+  if (!identity || typeof manifestField(identity, "run") !== "string" || !identity.run ||
+    typeof manifestField(identity, "run_instance_id") !== "string" || !identity.run_instance_id || !source || manifestField(source, "version") !== 1) return invalid();
+  if (manifestField(source, "run") !== expected.run || manifestField(source, "run_instance_id") !== expected.run_instance_id) {
+    return Object.freeze({ state: "unavailable", reason: "identity_mismatch" });
+  }
+  const status = manifestField(source, "status");
+  const updated = manifestField(source, "updated_at");
+  const active = manifestField(source, "active_subagents");
+  const records = manifestField(source, "commands");
+  if (typeof status !== "string" || !["running", "stopping", "done", "failed"].includes(status) || !timestamp(updated) ||
+    !count(active) || !Array.isArray(records)) return invalid();
+  const redact = redactEvidence ?? createRunRecipeEvidenceRedactor(recipe);
+  const commands: Readonly<ExecutionCommandView>[] = [];
+  const ids = new Set<string>();
+  let attemptsReported = 0;
+  for (const value of records) {
+    const command = record(value);
+    if (!command) return invalid();
+    const id = manifestField(command, "id");
+    const state = manifestField(command, "status");
+    const rows = manifestField(command, "attempts");
+    if (typeof id !== "string" || !/^command-[0-9]{3,}$/u.test(id) || !count(Number(id.slice(8))) || Number(id.slice(8)) === 0 || ids.has(id) ||
+      typeof state !== "string" || !["running", "done", "failed", "interrupted"].includes(state) || !Array.isArray(rows)) return invalid();
+    ids.add(id);
+    const attempts: Readonly<ExecutionAttemptView>[] = [];
+    for (const [index, row] of rows.entries()) { const item = attempt(row, index + 1); if (!item) return invalid(); attempts.push(item); }
+    const details: Record<string, unknown> = {};
+    for (const key of ["stage", "command", "label"]) {
+      const item = manifestField(command, key);
+      if (item !== undefined) { if (typeof item !== "string") return invalid(); details[key] = redact(item); }
+    }
+    for (const key of ["occurrence", "branch_index", "prompt_bytes"]) {
+      const item = manifestField(command, key);
+      if (item !== undefined) { if (!count(item) || (key === "occurrence" && item === 0)) return invalid(); details[key] = item; }
+    }
+    for (const key of ["started_at", "completed_at"]) {
+      const item = manifestField(command, key);
+      if (item !== undefined) { if (!timestamp(item)) return invalid(); details[key] = item; }
+    }
+    for (const key of ["exit_code", "effective_exit_code", "native_exit_code"]) {
+      const item = manifestField(command, key);
+      if (item !== undefined) { if (!(key === "native_exit_code" && item === null) && !code(item)) return invalid(); details[key] = item; }
+    }
+    const semantic = manifestField(command, "semantic_acceptance");
+    if (semantic !== undefined) {
+      if (typeof semantic !== "string" || !["pending", "accepted", "rejected", "not_required", "unavailable"].includes(semantic)) return invalid();
+      details.semantic_acceptance = semantic;
+    }
+    const killed = manifestField(command, "killed");
+    if (killed !== undefined) { if (typeof killed !== "boolean") return invalid(); details.reported_killed = killed; }
+    const sessions = manifestField(command, "session_files");
+    if (sessions !== undefined) {
+      if (!Array.isArray(sessions) || sessions.some(file => typeof file !== "string")) return invalid();
+      details.reported_session_file_count = sessions.length;
+    }
+    const interruption = record(manifestField(command, "interruption"));
+    const message = interruption ? manifestField(interruption, "message") : undefined;
+    if (typeof message === "string") details.interruption = redact(message);
+    commands.push(Object.freeze({ id, reported_status: state, attempts: Object.freeze(attempts), ...details }));
+    attemptsReported += attempts.length;
+  }
+  return Object.freeze({ state: "available", view: Object.freeze({ reported_status: status, updated_at: updated,
+    reported_active_subagents: active, commands_total: commands.length, settled_attempts_reported: attemptsReported,
+    commands: Object.freeze(commands) }) });
+}
+
+// --- Canonical kernel stream input ---
+
+export type KernelRunStreamSourceReading =
+  | { readonly state: "available"; readonly identity: Readonly<RunContextIndexIdentity>; readonly stream: "stdout" | "stderr";
+      readonly source_scope: "canonical_runner_stream"; readonly visibility: "kernel_only"; readonly capture_completeness: "not_asserted";
+      readonly bytes_total: number; readonly text: string; readonly unchanged: () => boolean }
+  | { readonly state: "unavailable"; readonly reason: "stream_invalid" | "identity_unavailable" | "identity_mismatch" | "observation_changed" |
+      "stream_missing" | "stream_unavailable" | "stream_too_large" | "stream_invalid_text" };
+type StreamUnavailable = Extract<KernelRunStreamSourceReading, { state: "unavailable" }>;
+function streamUnavailable(reason: StreamUnavailable["reason"]): Readonly<StreamUnavailable> { return Object.freeze({ state: "unavailable", reason }); }
+
+/** Never serialize this raw source as tool/model evidence: an export owner still owes a fixed privacy projection. */
+export function readRunStreamSource(stateDir: string, expected: unknown, stream: unknown): Readonly<KernelRunStreamSourceReading> {
+  if (stream !== "stdout" && stream !== "stderr") return streamUnavailable("stream_invalid");
+  const owner = readRunContextIdentity(stateDir, expected);
+  if (owner.state === "unavailable") return owner;
+  const source = readExecutionRunnerStreamText(owner.local_path, stream);
+  if (!owner.unchanged()) return streamUnavailable("observation_changed");
+  if (source.availability === "unavailable") return streamUnavailable(source.reason === "reference_changed" ? "observation_changed"
+    : source.reason === "reference_missing" ? "stream_missing" : source.reason === "reference_too_large" ? "stream_too_large"
+    : source.reason === "reference_invalid_text" ? "stream_invalid_text" : "stream_unavailable");
+  const { reference, text } = source;
+  const unchanged = (): boolean => owner.unchanged() && reference.unchanged();
+  if (!unchanged()) return streamUnavailable("observation_changed");
+  return Object.freeze({ state: "available", identity: owner.identity, stream, source_scope: "canonical_runner_stream",
+    visibility: "kernel_only", capture_completeness: "not_asserted", bytes_total: reference.bytes_total, text, unchanged });
+}
+
+// --- Recorded reference admission ---
+
+export type RunExecutionReferenceRequest =
+  | { readonly kind: "capture"; readonly command_id: string; readonly attempt: number; readonly stream: "stdout" | "stderr" }
+  | { readonly kind: "session"; readonly command_id: string; readonly path: string };
+interface ExecutionReferenceMetadata {
+  readonly command_id: string;
+  readonly path: string;
+  readonly local_path: string;
+  readonly bytes_total: number;
+  readonly mutable: true;
+}
+export type RunExecutionReference = ExecutionReferenceMetadata & (
+  | { readonly kind: "capture"; readonly attempt: number; readonly stream: "stdout" | "stderr"; readonly capture: Readonly<ExecutionCaptureView> }
+  | { readonly kind: "session" }
+);
+export type RunExecutionReferenceReading =
+  | { readonly state: "available"; readonly identity: Readonly<RunContextIndexIdentity>;
+      readonly source_updated_at: string; readonly reference: Readonly<RunExecutionReference>; readonly unchanged: () => boolean }
+  | { readonly state: "unavailable"; readonly reason: "request_invalid" | "identity_unavailable" | "identity_mismatch" |
+      "observation_changed" | "manifest_absent" | "manifest_unavailable" | "manifest_invalid" | "manifest_identity_mismatch" |
+      "reference_not_recorded" | "reference_invalid" | "reference_missing" | "reference_unavailable" | "reference_changed" |
+      "reference_size_unrepresentable" | "capture_size_mismatch" };
+type Unavailable = Extract<RunExecutionReferenceReading, { state: "unavailable" }>;
+function unavailable(reason: Unavailable["reason"]): Readonly<Unavailable> { return Object.freeze({ state: "unavailable", reason }); }
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function own(value: Record<string, unknown>, key: string): unknown { return Object.getOwnPropertyDescriptor(value, key)?.value; }
+function request(value: unknown): Readonly<RunExecutionReferenceRequest> | undefined {
+  const source = record(value);
+  if (!source) return undefined;
+  const kind = own(source, "kind");
+  const command = own(source, "command_id");
+  if (typeof command !== "string" || !/^command-[0-9]{3,}$/u.test(command) || !Number.isSafeInteger(Number(command.slice(8))) || Number(command.slice(8)) < 1) return undefined;
+  if (kind === "capture") {
+    const attempt = own(source, "attempt"); const stream = own(source, "stream");
+    return typeof attempt === "number" && Number.isSafeInteger(attempt) && attempt > 0 && (stream === "stdout" || stream === "stderr") &&
+      Object.keys(source).every(key => ["kind", "command_id", "attempt", "stream"].includes(key))
+      ? Object.freeze({ kind, command_id: command, attempt, stream }) : undefined;
+  }
+  const path = own(source, "path");
+  return kind === "session" && typeof path === "string" && path.length > 0 && Object.keys(source).every(key => ["kind", "command_id", "path"].includes(key))
+    ? Object.freeze({ kind, command_id: command, path }) : undefined;
+}
+function sameFile(left: BigIntStats, right: BigIntStats): boolean {
+  return right.isFile() && left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+/** Local paths and unchanged callbacks describe data only, never readable-body exposure or native capabilities. */
+export function readRunExecutionReference(stateDir: string, expected: unknown, query: unknown): Readonly<RunExecutionReferenceReading> {
+  const selected = request(query);
+  if (!selected) return unavailable("request_invalid");
+  const owner = readRunContextIdentity(stateDir, expected);
+  if (owner.state === "unavailable") return unavailable(owner.reason);
+  const sourcePath = join(owner.local_path, "execution.json");
+  try {
+    let before: BigIntStats;
+    try { before = lstatSync(sourcePath, { bigint: true }); }
+    catch (error) { return unavailable((error as NodeJS.ErrnoException).code === "ENOENT" ? "manifest_absent" : "manifest_unavailable"); }
+    if (!before.isFile() || before.size > BigInt(RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES)) return unavailable("manifest_unavailable");
+    const captured = readJsonFileResilient<unknown>(sourcePath, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+    const sourceUnchanged = (): boolean => {
+      try { return owner.unchanged() && sameFile(before, lstatSync(sourcePath, { bigint: true })); } catch { return false; }
+    };
+    if (!sourceUnchanged()) return unavailable("observation_changed");
+    if (captured.diagnostics.length) return unavailable("manifest_invalid");
+    const projected = projectRunExecutionManifest(owner.identity, captured.value);
+    if (projected.state === "unavailable") return unavailable(projected.reason === "identity_mismatch" ? "manifest_identity_mismatch" : "manifest_invalid");
+    const index = projected.view.commands.findIndex(command => command.id === selected.command_id);
+    if (index < 0) return unavailable("reference_not_recorded");
+    const command = (record(captured.value)!.commands as Record<string, unknown>[])[index];
+    const view = projected.view.commands[index];
+    let relative: string;
+    let capture: Readonly<ExecutionCaptureView> | undefined;
+    if (selected.kind === "capture") {
+      const attempt = (command.attempts as Record<string, unknown>[])[selected.attempt - 1];
+      const reported = record(attempt?.[selected.stream]);
+      if (!reported || !Object.hasOwn(reported, "path")) return unavailable("reference_not_recorded");
+      relative = `captures/${selected.command_id}/attempt-${String(selected.attempt).padStart(3, "0")}/${selected.stream}.log`;
+      if (reported.path !== relative) return unavailable("reference_invalid");
+      capture = view.attempts[selected.attempt - 1][selected.stream];
+    } else {
+      if (!Array.isArray(command.session_files) || !command.session_files.includes(selected.path)) return unavailable("reference_not_recorded");
+      relative = selected.path;
+    }
+    const observed = observeExecutionFileReference(owner.local_path, { kind: selected.kind, path: relative });
+    if (!sourceUnchanged()) return unavailable("observation_changed");
+    if (observed.availability === "unavailable") return unavailable(observed.reason === "invalid_reference" ? "reference_invalid" : observed.reason);
+    if (!observed.unchanged()) return unavailable("reference_changed");
+    if (capture && capture.reported_saved_bytes !== null && capture.reported_saved_bytes !== observed.bytes_total) return unavailable("capture_size_mismatch");
+    const base = { command_id: selected.command_id, path: observed.path, local_path: observed.local_path, bytes_total: observed.bytes_total, mutable: true as const };
+    const reference: Readonly<RunExecutionReference> = selected.kind === "capture"
+      ? Object.freeze({ ...base, kind: "capture", attempt: selected.attempt, stream: selected.stream, capture: capture! })
+      : Object.freeze({ ...base, kind: "session" });
+    return Object.freeze({ state: "available", identity: owner.identity, source_updated_at: projected.view.updated_at,
+      reference, unchanged: () => sourceUnchanged() && observed.unchanged() });
+  } catch { return unavailable("manifest_unavailable"); }
+}