harnery 0.45.1 → 0.46.0

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/governor/index.ts

@@ -63,13 +63,12 @@ export {
   type RunGovernorServiceDaemonInput,
   type RunGovernorServiceSweepInput,
   readGovernorServiceConfig,
-  readGovernorServiceRuntime,
-  readGovernorServiceStatus,
   requestGovernorServiceStop,
   runGovernorServiceDaemon,
   runGovernorServiceSweep,
   spawnGovernorService,
 } from "./service.ts";
+export { readGovernorServiceRuntime, readGovernorServiceStatus } from "./service-read.ts";
 export {
   assertGovernorId,
   type CreateGovernorInput,

package/src/core/governor/service-read.ts

@@ -1,21 +1,20 @@
 import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
-import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { gunzipSync } from "node:zlib";
 import { coordEnv } from "../../lib/env.ts";
+import type { ProcessGenerationVerdict } from "../agents/state/proc-start.ts";
 import {
-  type ProcessGenerationVerdict,
-  verifyProcessGeneration,
-} from "../agents/state/proc-start.ts";
-import { currentHarneryRuntimeBuild } from "../events/v3/runtime-build.ts";
+  observeServiceProcess,
+  type ServiceLiveness,
+  type ServiceProcessDependencies,
+} from "../agents/state/service-process.ts";
+import { serviceBuildStatus } from "../events/v3/runtime-build.ts";
 import { createStorageCatalog } from "../storage/catalog.ts";
 import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
 import { parseLogRecord } from "../storage/jsonl.ts";
 import { familyLogDirectory, readSegmentManifest } from "../storage/segments.ts";
 import type {
-  GovernorServiceBuild,
   GovernorServiceConfig,
-  GovernorServiceProcessDependencies,
   GovernorServiceRuntime,
   GovernorServiceStatus,
   GovernorServiceStatusRecord,
@@ -25,106 +24,6 @@ const MAX_FILE_BYTES = 512 * 1024;
 const MAX_LOG_RECORDS = 10_000;
 const MAX_GOALS = 100;
 
-export function currentGovernorServiceBuild(): GovernorServiceBuild {
-  let version = "unknown";
-  let revision = "unknown";
-  try {
-    const manifest = JSON.parse(
-      readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),
-    ) as {
-      version?: unknown;
-    };
-    if (typeof manifest.version === "string" && manifest.version.length <= 100) {
-      version = manifest.version;
-    }
-  } catch {
-    // Missing package metadata cannot establish that the running build is current.
-  }
-  try {
-    revision = currentHarneryRuntimeBuild();
-  } catch {
-    // Status still reports the unavailable build instead of guessing a match.
-  }
-  return { version, revision };
-}
-
-export function governorServiceBuildStatus(
-  record: GovernorServiceStatusRecord | undefined,
-): Pick<
-  GovernorServiceStatus,
-  "running_build" | "installed_build" | "restart_needed" | "build_status"
-> {
-  const installed_build = currentGovernorServiceBuild();
-  const candidate = record?.running_build;
-  const running_build =
-    candidate &&
-    typeof candidate.version === "string" &&
-    candidate.version.length > 0 &&
-    candidate.version.length <= 100 &&
-    typeof candidate.revision === "string" &&
-    candidate.revision.length > 0 &&
-    candidate.revision.length <= 100 &&
-    candidate.version !== "unknown" &&
-    candidate.revision !== "unknown"
-      ? candidate
-      : null;
-  const restart_needed =
-    running_build === null ||
-    installed_build.version === "unknown" ||
-    installed_build.revision === "unknown" ||
-    running_build.version !== installed_build.version ||
-    running_build.revision !== installed_build.revision;
-  return {
-    running_build,
-    installed_build,
-    restart_needed,
-    build_status:
-      running_build === null
-        ? "running build unknown; restart needed"
-        : restart_needed
-          ? "restart needed"
-          : "current",
-  };
-}
-
-/** An unknown token or process probe cannot establish a running or stopped owner. */
-export function observeGovernorServiceProcess(
-  record: Pick<GovernorServiceStatusRecord, "pid" | "host" | "state" | "start_token"> | undefined,
-  dependencies: GovernorServiceProcessDependencies = {},
-): { generation: ProcessGenerationVerdict; liveness: GovernorServiceStatus["liveness"] } {
-  if (!record) return { generation: "unknown", liveness: "stopped" };
-  const generation =
-    record.host === hostname()
-      ? verifyProcessGeneration(record.pid, record.start_token, dependencies.readToken)
-      : "unknown";
-  if (record.host !== hostname()) return { generation, liveness: "unknown" };
-  try {
-    const present = (dependencies.probePid ?? probePid)(record.pid);
-    if (!present) return { generation, liveness: "stopped" };
-  } catch (error) {
-    return {
-      generation,
-      liveness: (error as NodeJS.ErrnoException).code === "ESRCH" ? "stopped" : "unknown",
-    };
-  }
-  return {
-    generation,
-    liveness:
-      generation === "same"
-        ? record.state === "stopped"
-          ? "stopped"
-          : "running"
-        : generation === "different"
-          ? "stopped"
-          : "unknown",
-  };
-}
-
-function probePid(pid: number): boolean {
-  process.kill(pid, 0);
-  return true;
-}
-
 export function readGovernorServiceConfig(coordRootRaw: string): GovernorServiceConfig {
   const coordRoot = resolve(coordRootRaw);
   const config = readBoundedJson<GovernorServiceConfig>(
@@ -175,7 +74,7 @@ export function readGovernorServiceRuntime(
 
 export function readGovernorServiceStatus(
   coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): GovernorServiceStatus {
   const coordRoot = resolve(coordRootRaw);
   const record = readStatusRecord(coordRoot);
@@ -191,15 +90,17 @@ export function readGovernorServiceStatus(
   } catch {
     // Runtime is recoverable and must not make the dashboard unreadable.
   }
-  const observation = observeGovernorServiceProcess(record, dependencies);
-  if (!record && existsSync(join(serviceDir(coordRoot), "status.json"))) {
-    observation.liveness = "unknown";
-  }
+  const observation: { generation: ProcessGenerationVerdict; liveness: ServiceLiveness } = record
+    ? observeServiceProcess(record, dependencies)
+    : {
+        generation: "unknown",
+        liveness: existsSync(join(serviceDir(coordRoot), "status.json")) ? "unknown" : "stopped",
+      };
   return {
-    running: observation.liveness === "running" && record?.state !== "stopped",
+    running: observation.liveness === "running",
     stale: observation.liveness === "stopped" && record !== undefined && record.state !== "stopped",
     ...observation,
-    ...governorServiceBuildStatus(record),
+    ...serviceBuildStatus(record?.running_build),
     record,
     config,
     runtime,

package/src/core/governor/service.ts

@@ -10,30 +10,28 @@ import {
   renameSync,
   rmSync,
   statSync,
-  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
+import { type ProcessGenerationVerdict, processStartToken } from "../agents/state/proc-start.ts";
 import {
-  type ProcessGenerationSignalDependencies,
-  type ProcessGenerationVerdict,
-  processStartToken,
-  signalIfSameGeneration,
-} from "../agents/state/proc-start.ts";
+  acquireServiceLease,
+  requestServiceStop,
+  type ServiceLiveness,
+  type ServiceProcessDependencies,
+  serviceStartRefusal,
+} from "../agents/state/service-process.ts";
 import { resolveBinName } from "../config.ts";
+import { installedHarneryBuild } from "../events/v3/runtime-build.ts";
 import { type NormalizedPolicy, normalizePolicy, type PolicyIsolation } from "../policy/index.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
 import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import { RotatingTextSink } from "../storage/process-log.ts";
 import type { RunWorkItemInput } from "../work/index.ts";
 import { type GovernorRunReport, type GovernorStopReason, runGovernor } from "./runner.ts";
-import {
-  currentGovernorServiceBuild,
-  governorServiceBuildStatus,
-  observeGovernorServiceProcess,
-} from "./service-read.ts";
+import { readGovernorServiceRuntime, readGovernorServiceStatus } from "./service-read.ts";
 import { type GovernorRecord, readGovernor } from "./state.ts";
 
 export const GOVERNOR_SERVICE_CONFIG_SCHEMA_VERSION = 1 as const;
@@ -101,10 +99,6 @@ export interface GovernorServiceBuild {
   revision: string;
 }
 
-export interface GovernorServiceProcessDependencies extends ProcessGenerationSignalDependencies {
-  probePid?: (pid: number) => boolean;
-}
-
 export interface GovernorServiceStatusRecord {
   schema_version: typeof GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION;
   pid: number;
@@ -173,27 +167,13 @@ export interface RunGovernorServiceDaemonInput {
   onLog?: (line: string) => void;
 }
 
-interface ServiceLease {
-  pid: number;
-  start_token?: string;
-  running_build?: GovernorServiceBuild;
-  host: string;
-  nonce: string;
-  created_at: string;
-}
-
 export function configureGovernorService(
   input: ConfigureGovernorServiceInput,
 ): GovernorServiceConfig {
   const coordRoot = resolve(input.coordRoot);
-  const active = readStatusRecord(coordRoot);
-  if (!active && existsSync(serviceStatusPath(coordRoot))) {
-    throw serviceStartRefusal(coordRoot, undefined, "unknown");
-  }
-  if (active) {
-    const liveness = statusOwnerIsLive(active);
-    if (liveness !== "stopped") throw serviceStartRefusal(coordRoot, active.pid, liveness);
-  }
+  const current = readGovernorServiceStatus(coordRoot);
+  if (current.liveness !== "stopped")
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
   const goalIds = unique(input.goalIds.map((value) => value.trim()).filter(Boolean));
   if (goalIds.length < 1 || goalIds.length > MAX_GOALS) {
     throw new Error(`governor service requires from 1 to ${MAX_GOALS} unique goal ids`);
@@ -249,65 +229,12 @@ export function readGovernorServiceConfig(coordRootRaw: string): GovernorService
   return config;
 }
 
-export function readGovernorServiceRuntime(
-  coordRootRaw: string,
-): GovernorServiceRuntime | undefined {
-  const coordRoot = resolve(coordRootRaw);
-  if (!existsSync(serviceRuntimePath(coordRoot))) return undefined;
-  const runtime = readBoundedJson<GovernorServiceRuntime>(
-    serviceRuntimePath(coordRoot),
-    "governor service runtime",
-  );
-  if (
-    runtime.schema_version !== GOVERNOR_SERVICE_RUNTIME_SCHEMA_VERSION ||
-    !validTimestamp(runtime.config_created_at) ||
-    !validTimestamp(runtime.updated_at) ||
-    !runtime.goals ||
-    typeof runtime.goals !== "object" ||
-    Array.isArray(runtime.goals)
-  ) {
-    throw new Error("governor service runtime has an unsupported schema");
-  }
-  return runtime;
-}
-
-export function readGovernorServiceStatus(
-  coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
-): GovernorServiceStatus {
-  const coordRoot = resolve(coordRootRaw);
-  const record = readStatusRecord(coordRoot);
-  let config: GovernorServiceConfig | undefined;
-  let runtime: GovernorServiceRuntime | undefined;
-  try {
-    config = readGovernorServiceConfig(coordRoot);
-  } catch {
-    // A service has no usable configuration until explicitly configured.
-  }
-  try {
-    runtime = readGovernorServiceRuntime(coordRoot);
-  } catch {
-    // Status remains readable when recoverable runtime state is corrupt.
-  }
-  const observation = observeGovernorServiceProcess(record, dependencies);
-  if (!record && existsSync(serviceStatusPath(coordRoot))) observation.liveness = "unknown";
-  return {
-    running: observation.liveness === "running" && record?.state !== "stopped",
-    stale: observation.liveness === "stopped" && record !== undefined && record.state !== "stopped",
-    ...observation,
-    ...governorServiceBuildStatus(record),
-    record,
-    config,
-    runtime,
-  };
-}
-
 export async function spawnGovernorService(coordRootRaw: string): Promise<GovernorServiceStatus> {
   const coordRoot = resolve(coordRootRaw);
   readGovernorServiceConfig(coordRoot);
   const current = readGovernorServiceStatus(coordRoot);
   if (current.liveness !== "stopped") {
-    throw serviceStartRefusal(coordRoot, current.record?.pid, current.liveness);
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
   }
   mkdirSync(serviceDir(coordRoot), { recursive: true, mode: stateDirMode() });
   const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
@@ -347,31 +274,19 @@ export async function spawnGovernorService(coordRootRaw: string): Promise<Govern
 
 export function requestGovernorServiceStop(
   coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): GovernorServiceStatus {
   const coordRoot = resolve(coordRootRaw);
   const status = readGovernorServiceStatus(coordRoot, dependencies);
   if ((status.record?.state === "stopped" || !status.record) && status.liveness === "stopped") {
     return { ...status, signal_sent: false, signal_verdict: status.generation };
   }
-  writePrivateJsonAtomic(serviceStopPath(coordRoot), {
-    requested_at: new Date().toISOString(),
-    requested_by_pid: process.pid,
-  });
-  const signal =
-    status.record?.host === hostname() && status.record.state !== "stopped"
-      ? signalIfSameGeneration(
-          status.record.pid,
-          status.record.start_token,
-          "SIGTERM",
-          dependencies,
-        )
-      : { sent: false, verdict: status.generation };
-  return {
-    ...readGovernorServiceStatus(coordRoot, dependencies),
-    signal_sent: signal.sent,
-    signal_verdict: signal.verdict,
-  };
+  return requestServiceStop(
+    status,
+    () => readGovernorServiceStatus(coordRoot, dependencies),
+    serviceStopPath(coordRoot),
+    dependencies,
+  );
 }
 
 export async function runGovernorServiceSweep(
@@ -519,22 +434,21 @@ export async function runGovernorServiceDaemon(
 ): Promise<GovernorServiceStatusRecord> {
   const coordRoot = resolve(input.coordRoot);
   const config = readGovernorServiceConfig(coordRoot);
-  const existing = readStatusRecord(coordRoot);
-  if (!existing && existsSync(serviceStatusPath(coordRoot))) {
-    throw serviceStartRefusal(coordRoot, undefined, "unknown");
-  }
-  if (existing) {
-    const liveness = statusOwnerIsLive(existing);
-    if (liveness !== "stopped") throw serviceStartRefusal(coordRoot, existing.pid, liveness);
-  }
-  const release = acquireServiceLease(coordRoot);
+  const current = readGovernorServiceStatus(coordRoot);
+  if (current.liveness !== "stopped")
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
+  const { release } = acquireServiceLease(
+    serviceLeasePath(coordRoot),
+    (pid, liveness) => startRefusal(coordRoot, pid, liveness),
+    { running_build: installedHarneryBuild() },
+  );
   rmSync(serviceStopPath(coordRoot), { force: true });
   const now = new Date().toISOString();
   const status: GovernorServiceStatusRecord = {
     schema_version: GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION,
     pid: process.pid,
     start_token: processStartToken(process.pid) ?? undefined,
-    running_build: currentGovernorServiceBuild(),
+    running_build: installedHarneryBuild(),
     host: hostname(),
     nonce: randomUUID(),
     state: "starting",
@@ -781,114 +695,16 @@ function normalizeIsolation(value: unknown): PolicyIsolation | undefined {
   throw new Error("service isolation must be shared, worktree, sandbox, or remote");
 }
 
-function acquireServiceLease(coordRoot: string): () => void {
-  const path = serviceLeasePath(coordRoot);
-  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
-  const owner: ServiceLease = {
-    pid: process.pid,
-    start_token: processStartToken(process.pid) ?? undefined,
-    running_build: currentGovernorServiceBuild(),
-    host: hostname(),
-    nonce: randomUUID(),
-    created_at: new Date().toISOString(),
-  };
-  const acquire = (): boolean => {
-    try {
-      const fd = openSync(path, "wx", stateFileMode());
-      try {
-        writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
-      } finally {
-        closeSync(fd);
-      }
-      return true;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      return false;
-    }
-  };
-  if (!acquire()) {
-    const existing = readLease(path);
-    const liveness = existing ? leaseOwnerIsLive(existing) : "unknown";
-    if (liveness !== "stopped") {
-      throw serviceStartRefusal(coordRoot, existing?.pid, liveness);
-    }
-    unlinkSync(path);
-    if (!acquire()) throw new Error("governor service lease raced with another process");
-  }
-  return () => {
-    try {
-      const existing = readLease(path);
-      if (existing?.nonce === owner.nonce) unlinkSync(path);
-    } catch {
-      // A stale lease is recoverable by the next explicit service start.
-    }
-  };
-}
-
-function readLease(path: string): ServiceLease | null {
-  try {
-    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<ServiceLease>;
-    return Number.isSafeInteger(value.pid) &&
-      (value.pid ?? 0) > 0 &&
-      typeof value.host === "string" &&
-      typeof value.nonce === "string" &&
-      typeof value.created_at === "string"
-      ? ({
-          ...value,
-          start_token: typeof value.start_token === "string" ? value.start_token : undefined,
-        } as ServiceLease)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function leaseOwnerIsLive(lease: ServiceLease): GovernorServiceStatus["liveness"] {
-  return observeGovernorServiceProcess({ ...lease, state: "running" }).liveness;
-}
-
-function readStatusRecord(coordRoot: string): GovernorServiceStatusRecord | undefined {
-  if (!existsSync(serviceStatusPath(coordRoot))) return undefined;
-  try {
-    const value = readBoundedJson<GovernorServiceStatusRecord>(
-      serviceStatusPath(coordRoot),
-      "governor service status",
-    );
-    if (
-      value.schema_version !== GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION ||
-      !Number.isSafeInteger(value.pid) ||
-      value.pid < 1 ||
-      typeof value.host !== "string" ||
-      typeof value.nonce !== "string" ||
-      !validTimestamp(value.started_at) ||
-      !validTimestamp(value.heartbeat_at)
-    ) {
-      return undefined;
-    }
-    return {
-      ...value,
-      start_token: typeof value.start_token === "string" ? value.start_token : undefined,
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-function statusOwnerIsLive(record: GovernorServiceStatusRecord): GovernorServiceStatus["liveness"] {
-  return observeGovernorServiceProcess(record).liveness;
-}
-
-function serviceStartRefusal(
+function startRefusal(
   coordRoot: string,
   pid: number | undefined,
-  liveness: GovernorServiceStatus["liveness"],
+  liveness: ServiceLiveness,
 ): Error {
-  const reason =
-    liveness === "unknown"
-      ? `governor service process generation is unknown${pid ? ` for pid ${pid}` : ""}`
-      : `governor service process is still running under pid ${pid}`;
-  return new Error(
-    `${reason}; run \`${resolveBinName(coordRoot)} governor service stop\` to write a durable stop request before starting or reconfiguring it`,
+  return serviceStartRefusal(
+    "governor service",
+    `${resolveBinName(coordRoot)} governor service stop`,
+    pid,
+    liveness,
   );
 }
 

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 };
+}