harnery 0.45.2 → 0.46.1

package/src/core/events/v3/producers/recorder.ts

@@ -465,7 +465,18 @@ function sessionHashForSignal(
   // single live producer authority instead of hashing the instance into a
   // second state path. Ambiguous or absent matches keep the fail-closed fallback.
   if (adapterBehavior(input.adapter).sessionIdentityOnStartOnly) {
-    const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(
+    const scan = scanHookProducerStateRecordsV3(input.coordRoot);
+    // This instance's own state is unreadable: fail closed rather than hash
+    // the instance into a second state path beside it.
+    if (
+      scan.invalid.some(
+        (file) => file.adapter === input.adapter && file.instance_id === input.instance_id,
+      )
+    ) {
+      throw new Error("V3 producer state is invalid");
+    }
+    for (const file of scan.invalid) recordInvalidProducerStateDiagnostic(input.coordRoot, file);
+    const matches = scan.records.filter(
       ({ state }) => state.adapter === input.adapter && state.instance_id === input.instance_id,
     );
     if (matches.length === 1) {
@@ -3476,15 +3487,44 @@ export function salvageOpenSpansV3(input: SalvageOpenSpansV3Input): SalvageOpenS
   }
 }
 
-export function listHookProducerStateRecordsV3(
+/** One producer-state file the validator refused during a listing scan. */
+export interface InvalidHookProducerStateFileV3 {
+  path: string;
+  adapter: EventAdapterIdV3;
+  session_hash: `hid_${string}`;
+  reason: string;
+  /**
+   * The file's raw `instance_id` when it parses as JSON and carries a
+   * well-formed one. Readers that target one instance use it to keep failing
+   * closed on that instance's own invalid state.
+   */
+  instance_id?: `inst_${string}`;
+}
+
+export interface HookProducerStateScanV3 {
+  records: HookProducerStateRecordV3[];
+  invalid: InvalidHookProducerStateFileV3[];
+}
+
+/**
+ * Scan every producer-state file of the active epoch. A file the validator
+ * refuses is reported in `invalid` instead of failing the scan, so one
+ * session's bad state cannot take coordination away from every other session
+ * in the checkout. An unsafe adapter directory still throws.
+ */
+export function scanHookProducerStateRecordsV3(
   coordRoot: string,
   options: { includeTerminal?: boolean } = {},
-): HookProducerStateRecordV3[] {
+): HookProducerStateScanV3 {
   const control = readEventV3ControlState(coordRoot);
-  if (control.state !== "candidate" && control.state !== "active") return [];
+  if (control.state !== "candidate" && control.state !== "active") {
+    return { records: [], invalid: [] };
+  }
+  const genesisId = control.genesis.event.payload.genesis_id;
   const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
-  if (!existsSync(producerRoot)) return [];
+  if (!existsSync(producerRoot)) return { records: [], invalid: [] };
   const records: HookProducerStateRecordV3[] = [];
+  const invalid: InvalidHookProducerStateFileV3[] = [];
   for (const adapter of EVENT_ADAPTER_IDS_V3) {
     const directory = join(producerRoot, adapter);
     if (!existsSync(directory)) continue;
@@ -3496,19 +3536,86 @@ export function listHookProducerStateRecordsV3(
       /^hid_[a-f0-9]{64}\.json$/.test(entry),
     )) {
       const path = join(directory, name);
-      const state = readProducerState(path);
+      let state: HookProducerStateV3;
+      try {
+        state = readProducerState(path);
+      } catch (error) {
+        const raw = rawProducerStateIdentity(path);
+        // A refused file from a replaced epoch would have been skipped anyway.
+        if (raw.epoch_genesis_id !== undefined && raw.epoch_genesis_id !== genesisId) continue;
+        invalid.push({
+          path,
+          adapter,
+          session_hash: name.slice(0, -".json".length) as `hid_${string}`,
+          reason: error instanceof Error ? error.message : String(error),
+          ...(raw.instance_id ? { instance_id: raw.instance_id } : {}),
+        });
+        continue;
+      }
       // Skip authorities left behind by a replaced epoch: their sequences and
       // causal links belong to the archived ledger, not this one.
-      if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) continue;
+      if (state.epoch_genesis_id !== genesisId) continue;
       if (!options.includeTerminal && state.terminal) continue;
       records.push({ path, modified_at_ms: lstatSync(path).mtimeMs, state });
     }
   }
-  return records.sort(
+  records.sort(
     (left, right) =>
       left.state.generation_id.localeCompare(right.state.generation_id) ||
       left.path.localeCompare(right.path),
   );
+  invalid.sort((left, right) => left.path.localeCompare(right.path));
+  return { records, invalid };
+}
+
+/**
+ * List the valid producer states of the active epoch. An invalid file is
+ * skipped and recorded as a `producer_state_invalid_skipped` diagnostic that
+ * names its adapter and session hash; readers of that one session's state
+ * still fail closed through `readHookProducerStateV3`.
+ */
+export function listHookProducerStateRecordsV3(
+  coordRoot: string,
+  options: { includeTerminal?: boolean } = {},
+): HookProducerStateRecordV3[] {
+  const scan = scanHookProducerStateRecordsV3(coordRoot, options);
+  for (const file of scan.invalid) recordInvalidProducerStateDiagnostic(coordRoot, file);
+  return scan.records;
+}
+
+function recordInvalidProducerStateDiagnostic(
+  coordRoot: string,
+  file: InvalidHookProducerStateFileV3,
+): void {
+  writeProducerDiagnosticV3(coordRoot, "producer_state_invalid_skipped", {
+    adapter: file.adapter,
+    session_hash: file.session_hash,
+    reason: file.reason,
+    ...(file.instance_id ? { instance_id: file.instance_id } : {}),
+  });
+}
+
+function rawProducerStateIdentity(path: string): {
+  instance_id?: `inst_${string}`;
+  epoch_genesis_id?: string;
+} {
+  try {
+    const metadata = lstatSync(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return {
+      ...(typeof parsed.instance_id === "string" &&
+      /^inst_[a-zA-Z0-9._-]{1,128}$/.test(parsed.instance_id)
+        ? { instance_id: parsed.instance_id as `inst_${string}` }
+        : {}),
+      ...(typeof parsed.epoch_genesis_id === "string"
+        ? { epoch_genesis_id: parsed.epoch_genesis_id }
+        : {}),
+    };
+  } catch {
+    return {};
+  }
 }
 
 export interface ReanchorArchivedHookProducersV3Input {
@@ -4277,6 +4384,15 @@ function acquireStateLease(coordRoot: string, statePath: string) {
   };
 }
 
+/** Test seam: publish a producer state through the real write-side validator. */
+export function publishHookProducerStateForTestV3(
+  coordRoot: string,
+  path: string,
+  state: HookProducerStateV3,
+): void {
+  publishProducerState(coordRoot, path, state);
+}
+
 function publishProducerState(coordRoot: string, path: string, state: HookProducerStateV3): void {
   const control = readEventV3ControlState(coordRoot);
   if (
@@ -4285,11 +4401,19 @@ function publishProducerState(coordRoot: string, path: string, state: HookProduc
   ) {
     return;
   }
+  const serialized = JSON.stringify(state);
+  // Validate the exact bytes about to land with the reader's own validator.
+  // The previous file stays in place when this refuses.
+  try {
+    validateProducerStateDocument(JSON.parse(serialized));
+  } catch {
+    throw new Error("V3 producer state is invalid; refusing to publish");
+  }
   const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
   let fd: number | undefined;
   try {
     fd = openSync(temporary, "wx", stateFileMode());
-    writeFileSync(fd, `${JSON.stringify(state)}\n`, "utf8");
+    writeFileSync(fd, `${serialized}\n`, "utf8");
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
@@ -4314,6 +4438,16 @@ function readProducerState(path: string): HookProducerStateV3 {
   } catch {
     throw new Error("V3 producer state is unreadable");
   }
+  return validateProducerStateDocument(parsed);
+}
+
+/**
+ * The single producer-state validator. Readers run it on every file they
+ * load, and `publishProducerState` runs it on the serialized document before
+ * the rename, so a state no reader would accept fails in the producing hook
+ * instead of in every later reader of the checkout.
+ */
+function validateProducerStateDocument(parsed: unknown): HookProducerStateV3 {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("V3 producer state is invalid");
   }
@@ -4589,8 +4723,10 @@ function validPendingRuntimeContext(value: unknown): value is PendingRuntimeCont
     Number.isFinite(Date.parse(pending.terminal_observed_at)) &&
     typeof pending.turn_id === "string" &&
     /^tid_[a-f0-9]{64}$/.test(pending.turn_id) &&
-    (pending.run_id === undefined || /^run_[0-9a-f-]{36}$/.test(pending.run_id)) &&
-    (pending.workflow_id === undefined || /^wf_[0-9a-f-]{36}$/.test(pending.workflow_id)) &&
+    // Same shapes the event contract accepts: workflow children carry
+    // stableScopeId hashes (run_<64 hex>), not UUIDs.
+    (pending.run_id === undefined || /^run_[a-zA-Z0-9._-]{1,128}$/.test(pending.run_id)) &&
+    (pending.workflow_id === undefined || /^wf_[a-zA-Z0-9._-]{1,128}$/.test(pending.workflow_id)) &&
     (pending.workflow_agent_id === undefined ||
       /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.workflow_agent_id)) &&
     typeof pending.native_session_id === "string" &&
@@ -4606,9 +4742,11 @@ function validPendingRuntimeContext(value: unknown): value is PendingRuntimeCont
     (pending.runtime_version === undefined ||
       (typeof pending.runtime_version === "string" &&
         /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.runtime_version))) &&
+    // Externally driven reconciles (`deferRetryLimit`) keep counting past
+    // RUNTIME_CONTEXT_RETRY_LIMIT until their own final attempt, and publish
+    // those counts, so the reader must accept them.
     Number.isSafeInteger(pending.attempts) &&
-    pending.attempts >= 0 &&
-    pending.attempts < RUNTIME_CONTEXT_RETRY_LIMIT
+    pending.attempts >= 0
   );
 }
 

package/src/core/events/v3/reader.ts

@@ -19,6 +19,7 @@ import {
   readEventV3SegmentManifest,
 } from "./catalog.ts";
 import type { EventV3 } from "./contract.ts";
+import { readAdvanceableControlWitnessV3 } from "./control-witness.ts";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
 import {
   type EventV3RecoveryFailure,
@@ -442,7 +443,9 @@ export function readLedgerV3(
   }
 
   const discovered = discoverLedgerFramesV3(coordRoot);
-  const validated = validateLedgerFramesV3(discovered.frames, options);
+  const validated =
+    validateWitnessedFramesV3(coordRoot, storage, discovered, options) ??
+    validateLedgerFramesV3(discovered.frames, options);
   const recovery = discoverRecoveryReceiptsV3(coordRoot);
   const diagnostics = [
     ...discovered.diagnostics,
@@ -514,9 +517,40 @@ export function readLedgerFramesV3(
   return validateLedgerFramesV3(frames, options).result;
 }
 
+/**
+ * Cold-process fast path. Writers advance an authenticated validation
+ * checkpoint under the append lease after every drain, so when the witness
+ * names exactly the storage this read observed, each frame already passed the
+ * contract and canonical-byte checks that dominate a full read. Those two
+ * checks are skipped; every ledger-level rule still runs and rebuilds the
+ * validator state. The result is used only if that state reproduces the
+ * witnessed checkpoint byte for byte with no diagnostics and storage did not
+ * move during the read; anything else returns undefined and the caller runs
+ * the canonical full validation.
+ */
+function validateWitnessedFramesV3(
+  coordRoot: string,
+  storage: LedgerStorageVersionV3,
+  discovered: DiscoveredFramesV3,
+  options: ReadLedgerV3Options,
+): { result: ReadLedgerV3Result; state: LedgerValidationStateV3 } | undefined {
+  if (!discovered.active || discovered.diagnostics.length > 0) return undefined;
+  const witness = readAdvanceableControlWitnessV3(coordRoot);
+  if (!witness || witness.payload.storage.fingerprint !== sha256V3(storage.fingerprint)) {
+    return undefined;
+  }
+  const trusted = validateLedgerFramesV3(discovered.frames, options, true);
+  if (trusted.state.diagnostics.length > 0) return undefined;
+  const reproduced = checkpointFromValidationStateV3(trusted.state, discovered.active);
+  if (canonicalJsonV3(reproduced) !== canonicalJsonV3(witness.checkpoint)) return undefined;
+  if (ledgerStorageVersionV3(coordRoot).fingerprint !== storage.fingerprint) return undefined;
+  return trusted;
+}
+
 function validateLedgerFramesV3(
   frames: readonly LedgerFrameV3[],
   options: ReadLedgerV3Options,
+  witnessed = false,
 ): { result: ReadLedgerV3Result; state: LedgerValidationStateV3 } {
   const state: LedgerValidationStateV3 = {
     diagnostics: [],
@@ -530,13 +564,18 @@ function validateLedgerFramesV3(
     clocks: new Map(),
     event_count: 0,
   };
-  validateLedgerFramesIntoStateV3(frames, state);
+  validateLedgerFramesIntoStateV3(frames, state, witnessed);
   return { result: finishLedgerValidationV3(state, options, ledgerFramesBytesV3(frames)), state };
 }
 
+/**
+ * `witnessed` skips only the per-frame contract and canonical-byte checks, and
+ * only validateWitnessedFramesV3 may pass it, after authenticating the frames.
+ */
 function validateLedgerFramesIntoStateV3(
   frames: readonly LedgerFrameV3[],
   state: LedgerValidationStateV3,
+  witnessed = false,
 ): void {
   state.first_position ??= frames[0]?.position;
   const {
@@ -576,17 +615,22 @@ function validateLedgerFramesIntoStateV3(
       diagnostics.push(diagnostic("unsupported_major", frame));
       continue;
     }
-    const validation = validateEventV3(parsed);
-    if (!validation.ok || !validation.event) {
-      diagnostics.push(diagnostic("invalid_contract", frame));
-      continue;
+    let event: EventV3;
+    if (witnessed) {
+      event = parsed as EventV3;
+    } else {
+      const validation = validateEventV3(parsed);
+      if (!validation.ok || !validation.event) {
+        diagnostics.push(diagnostic("invalid_contract", frame));
+        continue;
+      }
+      event = validation.event;
+      if (canonicalJsonV3(event) !== frame.raw) {
+        diagnostics.push(diagnostic("noncanonical_frame", frame, event.event_id));
+        continue;
+      }
     }
-    const event = validation.event;
     const shape = event as unknown as EventShape;
-    if (canonicalJsonV3(event) !== frame.raw) {
-      diagnostics.push(diagnostic("noncanonical_frame", frame, shape.event_id));
-      continue;
-    }
     const priorFrame = seenIds.get(shape.event_id);
     if (priorFrame !== undefined) {
       if (priorFrame !== frame.raw) {

package/src/core/events/v3/validate.ts

@@ -45,8 +45,49 @@ interface RecoveryShape {
   elapsed_upper_bound_ms?: ObservationShape;
 }
 
+type EventVariantSchema = (typeof EventV3Schema.anyOf)[number];
+
+/**
+ * Every union member requires its own literal `event_type`, so only the member
+ * named by a value's `event_type` can accept it. Checking that one member gives
+ * the union's verdict without trying the other variants, which more than halves
+ * a full-ledger read. Returns null, falling back to the whole union, if a member
+ * ever stops carrying a required unique literal.
+ */
+let eventVariantsByType: Map<string, EventVariantSchema> | null | undefined;
+
+function eventVariantsByTypeV3(): Map<string, EventVariantSchema> | null {
+  if (eventVariantsByType !== undefined) return eventVariantsByType;
+  const variants = new Map<string, EventVariantSchema>();
+  for (const variant of EventV3Schema.anyOf) {
+    const literal = (variant.properties as Record<string, { const?: unknown }>).event_type?.const;
+    if (
+      typeof literal !== "string" ||
+      !(variant.required as readonly string[] | undefined)?.includes("event_type") ||
+      variants.has(literal)
+    ) {
+      eventVariantsByType = null;
+      return null;
+    }
+    variants.set(literal, variant);
+  }
+  eventVariantsByType = variants;
+  return variants;
+}
+
+function checkEventSchemaV3(value: unknown): boolean {
+  const variants = eventVariantsByTypeV3();
+  if (!variants) return Value.Check(EventV3Schema, value);
+  const eventType =
+    typeof value === "object" && value !== null
+      ? (value as { event_type?: unknown }).event_type
+      : undefined;
+  const variant = typeof eventType === "string" ? variants.get(eventType) : undefined;
+  return variant !== undefined && Value.Check(variant, value);
+}
+
 export function validateEventV3(value: unknown): EventV3ValidationResult {
-  if (!Value.Check(EventV3Schema, value)) {
+  if (!checkEventSchemaV3(value)) {
     return {
       ok: false,
       issues: [...Value.Errors(EventV3Schema, value)]

package/src/core/hooks/adapter/native-parent.ts

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { discoverCodexSessionTranscript } from "./runtime-telemetry.ts";
+
+export type NativeParentObservation =
+  | { state: "observed"; parent_session_id: string; source_witness: string }
+  | { state: "none"; reason: string; source_witness: string }
+  | { state: "unknown"; reason: string };
+
+export interface NativeParentRequest {
+  adapter: string;
+  native_session_id?: string;
+  transcript_path?: string;
+}
+
+export interface NativeParentReaderOptions {
+  discoverTranscript?: (sessionId: string, transcriptPath?: string) => string | undefined;
+}
+
+const HEADER_LIMIT = 1024 * 1024;
+const NATIVE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ORDINARY_SOURCES = new Set(["cli", "exec", "vscode", "app-server"]);
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Native relationship evidence only; no prompt bodies, state writes or recipient authority. */
+export function readNativeParentReference(
+  request: NativeParentRequest,
+  options: NativeParentReaderOptions = {},
+): NativeParentObservation {
+  if (request.adapter !== "codex") return unknown("native_parent_adapter_unsupported");
+  const child = request.native_session_id;
+  if (!child || !NATIVE_ID.test(child)) return unknown("native_child_identity_unavailable");
+  let fd: number | undefined;
+  try {
+    const path = (options.discoverTranscript ?? discoverCodexSessionTranscript)(
+      child,
+      request.transcript_path,
+    );
+    if (!path) return unknown("native_parent_transcript_unavailable");
+    const entry = lstatSync(path);
+    if (!entry.isFile() || entry.isSymbolicLink()) return unknown("native_parent_not_regular");
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.dev !== entry.dev || before.ino !== entry.ino) {
+      return unknown("native_parent_file_changed");
+    }
+    const header = readHeader(fd);
+    if (!header) return unknown("native_parent_header_incomplete");
+    // Appending later rows is normal. The same header must remain unchanged.
+    const checked = readHeader(fd);
+    const after = lstatSync(path);
+    if (
+      !checked?.equals(header) ||
+      !after.isFile() ||
+      after.isSymbolicLink() ||
+      before.dev !== after.dev ||
+      before.ino !== after.ino
+    ) {
+      return unknown("native_parent_file_changed");
+    }
+    const row = object(JSON.parse(header.toString("utf8")));
+    const payload = object(row?.payload);
+    if (row?.type !== "session_meta" || payload?.id !== child) {
+      return unknown("native_parent_child_mismatch");
+    }
+    const source_witness = createHash("sha256").update(header).digest("hex");
+    if (typeof payload.source === "string" && ORDINARY_SOURCES.has(payload.source)) {
+      return { state: "none", reason: "native_ordinary_session", source_witness };
+    }
+    const source = object(payload.source);
+    const spawn = object(object(source?.subagent)?.thread_spawn);
+    const parent = spawn?.parent_thread_id;
+    if (typeof parent !== "string" || !NATIVE_ID.test(parent)) {
+      return unknown("native_parent_not_reported");
+    }
+    if (parent.toLowerCase() === child.toLowerCase())
+      return unknown("native_parent_self_reference");
+    return { state: "observed", parent_session_id: parent, source_witness };
+  } catch {
+    return unknown("native_parent_metadata_unreadable");
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function readHeader(fd: number): Buffer | undefined {
+  const chunks: Buffer[] = [];
+  let offset = 0;
+  while (offset < HEADER_LIMIT) {
+    const buffer = Buffer.alloc(Math.min(16 * 1024, HEADER_LIMIT - offset));
+    const bytes = readSync(fd, buffer, 0, buffer.length, offset);
+    if (bytes === 0) return undefined;
+    const data = buffer.subarray(0, bytes);
+    const newline = data.indexOf(10);
+    if (newline >= 0) return Buffer.concat([...chunks, data.subarray(0, newline)]);
+    chunks.push(data);
+    offset += bytes;
+  }
+  return undefined;
+}
+
+function unknown(reason: string): NativeParentObservation {
+  return { state: "unknown", reason };
+}