@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -1,6 +1,6 @@
 /**
  * Async run state-directory ownership.
- * Owns: the marker proof required before launch and destructive retention.
+ * Owns: marker proof for lifecycle/retention and optional bounded readonly identity admission.
  */
 
 import {
@@ -16,6 +16,7 @@ import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 import { writeJsonAtomic } from "./file-state.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
 
 export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
 
@@ -66,11 +67,15 @@ function assertCanonicalDirectory(stateDir: string): string {
   return resolved;
 }
 
-function readMarker(stateDir: string): RunStateOwnershipMarker | undefined {
+function readMarker(stateDir: string, maxBytes?: number): RunStateOwnershipMarker | undefined {
   try {
-    const value = JSON.parse(readFileSync(markerPath(stateDir), "utf8")) as Partial<RunStateOwnershipMarker>;
+    const path = markerPath(stateDir);
+    if (!lstatSync(path).isFile()) return undefined;
+    const value = maxBytes === undefined
+      ? JSON.parse(readFileSync(path, "utf8")) as Partial<RunStateOwnershipMarker>
+      : readJsonFileResilient<Partial<RunStateOwnershipMarker> | undefined>(path, undefined, { maxBytes, strictUtf8: true }).value;
     if (
-      value.version !== 1 ||
+      !value || value.version !== 1 ||
       typeof value.run !== "string" ||
       typeof value.state_dir !== "string" ||
       typeof value.ownership_token !== "string" ||
@@ -98,6 +103,20 @@ function assertMarkerMatches(
   return marker;
 }
 
+/** Avoid acquiring the same lifecycle resource through a second path while its parent lock is held. */
+export function assertDistinctRunStateDirectories(parentStateDir: string, childStateDir: string): void {
+  const parent = realpathSync.native(resolve(parentStateDir));
+  let child: string;
+  try { child = realpathSync.native(resolve(childStateDir)); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  if (comparablePath(parent) === comparablePath(child)) {
+    throw new Error("Run descendant preparation cannot target its parent state directory.");
+  }
+}
+
 export function claimRunStateDirectory(stateDir: string, run: string): string {
   const resolved = resolve(stateDir);
   if (existsSync(resolved) && lstatSync(resolved).isSymbolicLink()) {
@@ -126,6 +145,20 @@ export function claimRunStateDirectory(stateDir: string, run: string): string {
   return canonical;
 }
 
+/** Read only the public marker identity, never its private ownership token. */
+export function readOwnedRunStateDirectory(
+  stateDir: string,
+  options: { maxBytes?: number } = {},
+): { run: string; stateDir: string } {
+  if (options.maxBytes !== undefined && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
+    throw new Error("Run state ownership read budget must be a nonnegative safe integer.");
+  }
+  const canonical = assertCanonicalDirectory(stateDir);
+  const marker = readMarker(canonical, options.maxBytes);
+  const checked = assertMarkerMatches(marker, canonical, marker?.run ?? "");
+  return { run: checked.run, stateDir: canonical };
+}
+
 export function assertOwnedRunStateDirectory(
   stateDir: string,
   run: string,

package/node_modules/@llblab/pi-actors/lib/runs-process-windows-mi.ts

@@ -0,0 +1,113 @@
+// Owns: Bounded raw MI wire decoding, query inputs and unadmitted provenance fragments, subordinate to process acquisition.
+// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission,
+// fallback, native invocation and asset loading. Decoded data never admits a representation profile.
+
+type NativeStage = 'application' | 'session' | 'input' | 'retrieval' | 'operation' | 'representation' | 'cleanup';
+type RawTimestamp = {
+  readonly profile: 'mi-timestamp-v1';
+  readonly year: number; readonly month: number; readonly day: number;
+  readonly hour: number; readonly minute: number; readonly second: number;
+  readonly microseconds: number; readonly utc: number;
+};
+type RawRow = { readonly pid: number; readonly date: RawTimestamp; readonly exe: string; readonly cmd: string };
+type DecodeOutcome =
+  | { readonly kind: 'decoded_unadmitted'; readonly rows: readonly RawRow[] }
+  | { readonly kind: 'unusable'; readonly reason: 'invalid_query' | 'invalid_wire' | 'unsupported_optional_fields' }
+  | { readonly kind: 'unusable'; readonly reason: 'native_stage'; readonly stage: NativeStage };
+
+export function queryArguments(profile: unknown, pids: unknown): string[] | undefined {
+  if ((profile !== 'scalar' && profile !== 'shared') || !Array.isArray(pids) ||
+    pids.length < 1 || pids.length > 64 || (profile === 'scalar' && pids.length !== 1)) return undefined;
+  const selected: number[] = [];
+  for (const pid of pids) {
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0 || selected.includes(pid)) return undefined;
+    selected.push(pid);
+  }
+  const query = `SELECT ${profile === 'shared' ? 'ProcessId,' : ''}CreationDate,ExecutablePath,CommandLine FROM Win32_Process WHERE ${selected.map(pid => `ProcessId = ${pid}`).join(' OR ')}`;
+  if (query.length > 4096 || !/^[\x00-\x7f]+$/.test(query)) return undefined;
+  return [profile, ...selected.map(String)];
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) &&
+    Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+type ProvenanceBinding = {
+  readonly source_sha256: string;
+  readonly executable_sha256: string;
+  readonly executable_bytes: number;
+  readonly originating_source_commit: string;
+  readonly originating_build_job: string;
+};
+
+export function decodeProvenanceBinding(value: unknown):
+  | { readonly kind: 'decoded_binding_unadmitted'; readonly binding: ProvenanceBinding }
+  | { readonly kind: 'unusable'; readonly reason: 'invalid_binding' } {
+  const invalid = { kind: 'unusable', reason: 'invalid_binding' } as const;
+  if (!exactKeys(value, ['source_sha256', 'executable_sha256', 'executable_bytes', 'originating_source_commit', 'originating_build_job'])) return invalid;
+  const { source_sha256, executable_sha256, executable_bytes, originating_source_commit, originating_build_job } = value;
+  if (typeof source_sha256 !== 'string' || !/^[0-9a-f]{64}$(?![\s\S])/.test(source_sha256) ||
+    typeof executable_sha256 !== 'string' || !/^[0-9a-f]{64}$(?![\s\S])/.test(executable_sha256) ||
+    typeof originating_source_commit !== 'string' || !/^[0-9a-f]{40}$(?![\s\S])/.test(originating_source_commit) ||
+    typeof originating_build_job !== 'string' || !/^[1-9][0-9]*$(?![\s\S])/.test(originating_build_job) ||
+    typeof executable_bytes !== 'number' || !Number.isSafeInteger(executable_bytes) || executable_bytes <= 0) return invalid;
+  // These data claims verify neither the asset, its origin nor a representation profile.
+  return { kind: 'decoded_binding_unadmitted', binding: { source_sha256, executable_sha256, executable_bytes, originating_source_commit, originating_build_job } };
+}
+
+function timestamp(value: unknown): RawTimestamp | undefined {
+  if (!exactKeys(value, ['profile', 'year', 'month', 'day', 'hour', 'minute', 'second', 'microseconds', 'utc']) || value.profile !== 'mi-timestamp-v1') return undefined;
+  const { year, month, day, hour, minute, second, microseconds, utc } = value;
+  if (typeof year !== 'number' || typeof month !== 'number' || typeof day !== 'number' ||
+    typeof hour !== 'number' || typeof minute !== 'number' || typeof second !== 'number' ||
+    typeof microseconds !== 'number' || typeof utc !== 'number' ||
+    ![year, month, day, hour, minute, second, microseconds, utc].every(Number.isInteger)) return undefined;
+  if (year < 1601 || year > 9999 || month < 1 || month > 12 || day < 1 ||
+    hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59 ||
+    microseconds < 0 || microseconds > 999999 || utc < -720 || utc > 840) return undefined;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (day > days[month - 1]!) return undefined;
+  return { profile: 'mi-timestamp-v1', year, month, day, hour, minute, second, microseconds, utc };
+}
+
+export function decodeResponse(bytes: Uint8Array, profile: unknown, pids: unknown): DecodeOutcome {
+  const args = queryArguments(profile, pids);
+  if (!args) return { kind: 'unusable', reason: 'invalid_query' };
+  const invalid: DecodeOutcome = { kind: 'unusable', reason: 'invalid_wire' };
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > 1024 * 1024 ||
+    (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)) return invalid;
+  let value: unknown;
+  try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { return invalid; }
+  if (exactKeys(value, ['schema', 'status']) && value.schema === 'native-mi-v1') {
+    switch (value.status) {
+      case 'application': case 'session': case 'input': case 'retrieval': case 'operation': case 'representation': case 'cleanup':
+        return { kind: 'unusable', reason: 'native_stage', stage: value.status };
+      default: return invalid;
+    }
+  }
+  const selected = args.slice(1).map(Number);
+  if (!exactKeys(value, ['schema', 'status', 'profile', 'complete', 'rows']) || value.schema !== 'native-mi-v1' ||
+    value.status !== 'ok' || value.profile !== profile || value.complete !== true || !Array.isArray(value.rows) ||
+    value.rows.length > selected.length) return invalid;
+  const rows: RawRow[] = [];
+  const seen = new Set<number>();
+  let optionalNull = false;
+  for (const row of value.rows) {
+    if (!exactKeys(row, profile === 'shared' ? ['pid', 'date', 'exe', 'cmd'] : ['date', 'exe', 'cmd'])) return invalid;
+    const pid = profile === 'shared' ? row.pid : selected[0];
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || !selected.includes(pid) || seen.has(pid)) return invalid;
+    seen.add(pid);
+    // Preserve the raw optional-field distinction; no normalization or profile admission occurs here.
+    if (row.exe === null || row.cmd === null) optionalNull = true;
+    if ((row.exe !== null && typeof row.exe !== 'string') || (row.cmd !== null && typeof row.cmd !== 'string')) return invalid;
+    const date = timestamp(row.date);
+    if (!date) return invalid;
+    // Null rows are never returned, even if the other rows are well formed.
+    if (typeof row.exe === 'string' && typeof row.cmd === 'string') rows.push({ pid, date, exe: row.exe, cmd: row.cmd });
+  }
+  if (optionalNull) return { kind: 'unusable', reason: 'unsupported_optional_fields' };
+  return { kind: 'decoded_unadmitted', rows };
+}

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

@@ -1,9 +1,11 @@
 /**
  * Async run process identity helpers.
- * Owns: cross-platform liveness and stable runner process identity proofs.
+ * Owns: cross-platform liveness, stable runner identity, and single-process exit observations.
+ * Excludes: stop claims, signal dispatch, descendant/group cleanup, and lifecycle finalization.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawnSync, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
 import { posix, win32 } from "node:path";
@@ -31,15 +33,37 @@ type ProcessIdentityReader = (
   runtimePlatform: NodeJS.Platform,
 ) => RunProcessIdentity | undefined;
 
-export function isAlive(pid: number): boolean {
+export type ProcessLiveness = "alive" | "dead" | "unknown";
+
+type ProcessLivenessProbe = (pid: number, signal: 0) => boolean;
+
+export function readProcessLiveness(
+  pid: number,
+  probe: ProcessLivenessProbe = process.kill.bind(process),
+): ProcessLiveness {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return "unknown";
   try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
+    return probe(pid, 0) === true ? "alive" : "unknown";
+  } catch (error) {
+    return (error as NodeJS.ErrnoException | undefined)?.code === "ESRCH" ? "dead" : "unknown";
   }
 }
 
+/** POSIX group presence only: neither ownership, membership completeness, nor whole-Run stop proof. */
+export function readProcessGroupLiveness(
+  processGroupId: number,
+  runtimePlatform: NodeJS.Platform = platform(),
+  probe: ProcessLivenessProbe = process.kill.bind(process),
+): ProcessLiveness {
+  if (runtimePlatform !== "linux" && runtimePlatform !== "darwin") return "unknown";
+  return readProcessLiveness(processGroupId, (validatedId, signal) => probe(-validatedId, signal));
+}
+
+/** Unknown liveness must retain active-state guards, never authorize state reuse. */
+export function isAlive(pid: number): boolean {
+  return readProcessLiveness(pid) !== "dead";
+}
+
 function readLinuxIdentity(pid: number): RunProcessIdentity | undefined {
   if (!existsSync(`/proc/${pid}`)) return undefined;
   try {
@@ -77,8 +101,8 @@ function readDarwinIdentity(pid: number): RunProcessIdentity | undefined {
 
 function readWindowsIdentity(pid: number): RunProcessIdentity | undefined {
   const command = [
-    `$p = Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\";`,
-    "if ($null -eq $p) { exit 3 };",
+    `$p = Get-CimInstance Win32_Process -Property CreationDate,ExecutablePath,CommandLine -Filter \"ProcessId = ${pid}\";`,
+    "if ($null -eq $p) { exit 3 }; [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false, $true);",
     "$p | Select-Object CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress",
   ].join(" ");
   const result = spawnSync(
@@ -88,20 +112,55 @@ function readWindowsIdentity(pid: number): RunProcessIdentity | undefined {
   );
   if (result.status !== 0) return undefined;
   try {
-    const value = JSON.parse(result.stdout) as Record<string, unknown>;
-    if (typeof value.CreationDate !== "string") return undefined;
-    const executable = typeof value.ExecutablePath === "string" ? value.ExecutablePath : "";
-    const commandLine = typeof value.CommandLine === "string" ? value.CommandLine : "";
-    return {
-      command: `${executable}\n${commandLine}`.trim(),
-      platform: "win32",
-      start_time: value.CreationDate,
-    };
+    return decodeWindowsIdentity(JSON.parse(result.stdout));
   } catch {
     return undefined;
   }
 }
 
+function decodeWindowsIdentity(value: unknown): RunProcessIdentity | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const row = value as Record<string, unknown>;
+  if (typeof row.CreationDate !== "string") return undefined;
+  const executable = typeof row.ExecutablePath === "string" ? row.ExecutablePath : "";
+  const commandLine = typeof row.CommandLine === "string" ? row.CommandLine : "";
+  return { command: `${executable}\n${commandLine}`.trim(), platform: "win32", start_time: row.CreationDate };
+}
+
+export const WINDOWS_IDENTITY_QUERY_PID_LIMIT = 64;
+const WINDOWS_IDENTITY_QUERY_MAX_BYTES = 1024 * 1024;
+
+/** One bounded, complete CIM observation; undefined means query failure, never process absence. */
+export function readWindowsProcessIdentities(pids: readonly number[]): Map<number, RunProcessIdentity> | undefined {
+  if (!pids.length || pids.length > WINDOWS_IDENTITY_QUERY_PID_LIMIT || new Set(pids).size !== pids.length ||
+    pids.some(pid => !Number.isSafeInteger(pid) || pid <= 0)) return undefined;
+  // 64 safe integers (at most 16 digits) keep this ASCII command below 4096 characters,
+  // independently of native output. No shell, encoded command, or widened process scan.
+  const command = ['$ErrorActionPreference = "Stop";',
+    `$p = Get-CimInstance Win32_Process -Property ProcessId,CreationDate,ExecutablePath,CommandLine -Filter "${pids.map(pid => `ProcessId = ${pid}`).join(" OR ")}";`,
+    "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false, $true); ConvertTo-Json -InputObject @($p | Select-Object ProcessId,CreationDate,ExecutablePath,CommandLine) -Compress"].join(" ");
+  if (command.length > 4096) return undefined;
+  try {
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command],
+      { encoding: "utf8", windowsHide: true, maxBuffer: WINDOWS_IDENTITY_QUERY_MAX_BYTES });
+    if (result.error || result.signal || result.status !== 0 || typeof result.stdout !== "string" ||
+      result.stdout.length > WINDOWS_IDENTITY_QUERY_MAX_BYTES || Buffer.byteLength(result.stdout) > WINDOWS_IDENTITY_QUERY_MAX_BYTES) return undefined;
+    // Parse the entire bounded output, not a clipped prefix. Every row must correlate exactly once.
+    const rows: unknown = JSON.parse(result.stdout);
+    if (!Array.isArray(rows) || rows.length > pids.length) return undefined;
+    const selected = new Set(pids); const identities = new Map<number, RunProcessIdentity>();
+    for (const row of rows) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) return undefined;
+      const pid = (row as Record<string, unknown>).ProcessId;
+      if (typeof pid !== "number" || !selected.has(pid) || identities.has(pid)) return undefined;
+      const identity = decodeWindowsIdentity(row);
+      if (!identity) return undefined;
+      identities.set(pid, identity);
+    }
+    return identities;
+  } catch { return undefined; }
+}
+
 export function readProcessIdentity(
   pid: number,
   runtimePlatform: NodeJS.Platform = platform(),
@@ -112,6 +171,29 @@ export function readProcessIdentity(
   return undefined;
 }
 
+export function runProcessIdentityDigest(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const identity = value as Record<string, unknown>;
+  if (typeof identity.platform !== "string" || !["linux", "darwin", "win32"].includes(identity.platform) ||
+    typeof identity.start_time !== "string" || !identity.start_time ||
+    typeof identity.command !== "string" || !identity.command ||
+    (identity.cwd !== undefined && typeof identity.cwd !== "string")) return undefined;
+  return createHash("sha256").update(JSON.stringify([
+    identity.platform, identity.start_time, identity.command, identity.cwd ?? null,
+  ])).digest("hex");
+}
+
+function matchesRunCwd(identity: RunProcessIdentity, cwd: string, runtimePlatform: NodeJS.Platform): boolean {
+  const pathApi = runtimePlatform === "win32" ? win32 : posix;
+  const resolvedCwd = pathApi.resolve(cwd);
+  const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
+    ? realpathSync.native(resolvedCwd)
+    : resolvedCwd;
+  const expectedCwd = runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
+  const actualCwd = runtimePlatform === "win32" && identity.cwd ? identity.cwd.toLowerCase() : identity.cwd;
+  return !actualCwd || actualCwd === expectedCwd;
+}
+
 export function captureRunProcessIdentity(
   pid: number,
   cwd: string,
@@ -121,25 +203,78 @@ export function captureRunProcessIdentity(
   reader: ProcessIdentityReader = readProcessIdentity,
 ): RunProcessIdentity | undefined {
   const identity = reader(pid, runtimePlatform);
-  if (!identity) return undefined;
-  if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
-    return undefined;
-  }
-  const pathApi = runtimePlatform === "win32" ? win32 : posix;
-  const resolvedCwd = pathApi.resolve(cwd);
-  const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
-    ? realpathSync.native(resolvedCwd)
-    : resolvedCwd;
-  const expectedCwd =
-    runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
-  const actualCwd =
-    runtimePlatform === "win32" && identity.cwd
-      ? identity.cwd.toLowerCase()
-      : identity.cwd;
-  if (actualCwd && actualCwd !== expectedCwd) return undefined;
+  if (!identity || !identity.command.includes(runnerPath) || !identity.command.includes(stateDir) ||
+    !matchesRunCwd(identity, cwd, runtimePlatform)) return undefined;
   return identity;
 }
 
+export interface SpawnIdentityCaptureDeps {
+  runtimePlatform?: NodeJS.Platform;
+  readIdentity?: ProcessIdentityReader;
+  now?: () => number;
+  wait?: (milliseconds: number) => void;
+}
+
+/** Fresh spawn only, while its lifecycle lock/child handle is retained and workload is not admitted. */
+export function captureSpawnedRunProcessIdentity(
+  child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">,
+  cwd: string,
+  stateDir: string,
+  runnerPath: string,
+  deps: SpawnIdentityCaptureDeps = {},
+): RunProcessIdentity | undefined {
+  return captureFreshProcessIdentity(child, deps,
+    (current, runtimePlatform) => captureRunProcessIdentity(child.pid!, cwd, stateDir, runnerPath, runtimePlatform, () => current),
+    (current, runtimePlatform) => matchesRunCwd(current, cwd, runtimePlatform),
+  );
+}
+
+/** Immediate managed-native callback only; this observation is not complete membership or termination authority. */
+export function captureSpawnedNativeProcessIdentity(
+  child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">,
+  deps: SpawnIdentityCaptureDeps = {},
+): RunProcessIdentity | undefined {
+  const runtimePlatform = deps.runtimePlatform ?? platform();
+  if (!["linux", "darwin", "win32"].includes(runtimePlatform)) return undefined;
+  return captureFreshProcessIdentity(child, deps, (current) => current, () => true);
+}
+
+function captureFreshProcessIdentity(
+  child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">,
+  deps: SpawnIdentityCaptureDeps,
+  accept: (current: RunProcessIdentity, runtimePlatform: NodeJS.Platform) => RunProcessIdentity | undefined,
+  acceptEmpty: (current: RunProcessIdentity, runtimePlatform: NodeJS.Platform) => boolean,
+): RunProcessIdentity | undefined {
+  const pid = child.pid;
+  if (!Number.isSafeInteger(pid) || !pid || pid <= 0) return undefined;
+  const runtimePlatform = deps.runtimePlatform ?? platform();
+  const read = deps.readIdentity ?? readProcessIdentity;
+  const now = deps.now ?? (() => performance.now());
+  const wait = deps.wait ?? ((ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); });
+  const started = now();
+  let birth: string | undefined;
+  // Bound startup retries, not OS probe latency; never retry an observed contradiction.
+  for (let attempt = 0; attempt <= 100; attempt++) {
+    if (child.pid !== pid || child.exitCode !== null || child.signalCode !== null) return undefined;
+    const current = read(pid, runtimePlatform);
+    if (child.pid !== pid || child.exitCode !== null || child.signalCode !== null) return undefined;
+    if (current) {
+      if (current.platform !== runtimePlatform || typeof current.start_time !== "string" || !current.start_time ||
+        typeof current.command !== "string" || (current.cwd !== undefined && (typeof current.cwd !== "string" || !current.cwd)) ||
+        (birth !== undefined && current.start_time !== birth)) return undefined;
+      birth = current.start_time;
+      if (current.command) {
+        return accept({ ...current }, runtimePlatform);
+      }
+      if (!acceptEmpty(current, runtimePlatform)) return undefined;
+    }
+    const elapsed = now() - started;
+    if (!Number.isFinite(elapsed) || elapsed < 0 || elapsed >= 500) return undefined;
+    wait(Math.min(5, 500 - elapsed));
+  }
+  return undefined;
+}
+
 export function verifyRunProcessIdentity(
   pid: number,
   expected: RunProcessIdentity | undefined,
@@ -160,6 +295,47 @@ export function verifyRunProcessIdentity(
   return { status: valid ? "valid" : "owner_mismatch", valid };
 }
 
+export interface RunProcessExitObservation {
+  status: "exited" | "running" | "unproven";
+  process_identity_status: RunProcessIdentityStatus;
+}
+
+export interface RunProcessExitDeps {
+  probe?: ProcessLivenessProbe;
+  readIdentity?: ProcessIdentityReader;
+  runtimePlatform?: NodeJS.Platform;
+}
+
+/** Observes one captured process only; signal dispatch and descendant cleanup are separate facts. */
+export function observeRunProcessExit(
+  pid: number,
+  expected: RunProcessIdentity | undefined,
+  deps: RunProcessExitDeps = {},
+): RunProcessExitObservation {
+  const runtimePlatform = deps.runtimePlatform ?? platform();
+  if (!expected || expected.platform !== runtimePlatform ||
+    typeof expected.command !== "string" || !expected.command ||
+    typeof expected.start_time !== "string" || !expected.start_time ||
+    (expected.cwd !== undefined && typeof expected.cwd !== "string")) {
+    return { status: "unproven", process_identity_status: "unsupported_proof" };
+  }
+  const liveness = readProcessLiveness(pid, deps.probe);
+  if (liveness === "unknown") {
+    return { status: "unproven", process_identity_status: "unsupported_proof" };
+  }
+  const identity = verifyRunProcessIdentity(
+    pid,
+    expected,
+    runtimePlatform,
+    deps.readIdentity ?? readProcessIdentity,
+    () => liveness === "alive",
+  );
+  return {
+    status: identity.status === "dead_pid" ? "exited" : identity.valid ? "running" : "unproven",
+    process_identity_status: identity.status,
+  };
+}
+
 export function isWithinRunnerIdentityGrace(
   meta: Record<string, unknown>,
   graceMs: number,