@llblab/pi-kit 0.38.3 → 0.39.0

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

@@ -1,7 +1,16 @@
 /**
  * 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.
  */
 export declare const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
+/** Avoid acquiring the same lifecycle resource through a second path while its parent lock is held. */
+export declare function assertDistinctRunStateDirectories(parentStateDir: string, childStateDir: string): void;
 export declare function claimRunStateDirectory(stateDir: string, run: string): string;
+/** Read only the public marker identity, never its private ownership token. */
+export declare function readOwnedRunStateDirectory(stateDir: string, options?: {
+    maxBytes?: number;
+}): {
+    run: string;
+    stateDir: string;
+};
 export declare function assertOwnedRunStateDirectory(stateDir: string, run: string): string;

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

@@ -1,12 +1,13 @@
 /**
  * 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 { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { writeJsonAtomic } from "./file-state.js";
+import { readJsonFileResilient } from "./state-readers.js";
 export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
 function markerPath(stateDir) {
     return join(stateDir, RUN_STATE_OWNERSHIP_FILE);
@@ -39,10 +40,15 @@ function assertCanonicalDirectory(stateDir) {
     }
     return resolved;
 }
-function readMarker(stateDir) {
+function readMarker(stateDir, maxBytes) {
     try {
-        const value = JSON.parse(readFileSync(markerPath(stateDir), "utf8"));
-        if (value.version !== 1 ||
+        const path = markerPath(stateDir);
+        if (!lstatSync(path).isFile())
+            return undefined;
+        const value = maxBytes === undefined
+            ? JSON.parse(readFileSync(path, "utf8"))
+            : readJsonFileResilient(path, undefined, { maxBytes, strictUtf8: true }).value;
+        if (!value || value.version !== 1 ||
             typeof value.run !== "string" ||
             typeof value.state_dir !== "string" ||
             typeof value.ownership_token !== "string" ||
@@ -64,6 +70,22 @@ function assertMarkerMatches(marker, stateDir, run) {
     }
     return marker;
 }
+/** Avoid acquiring the same lifecycle resource through a second path while its parent lock is held. */
+export function assertDistinctRunStateDirectories(parentStateDir, childStateDir) {
+    const parent = realpathSync.native(resolve(parentStateDir));
+    let child;
+    try {
+        child = realpathSync.native(resolve(childStateDir));
+    }
+    catch (error) {
+        if (error.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, run) {
     const resolved = resolve(stateDir);
     if (existsSync(resolved) && lstatSync(resolved).isSymbolicLink()) {
@@ -89,6 +111,16 @@ export function claimRunStateDirectory(stateDir, run) {
     });
     return canonical;
 }
+/** Read only the public marker identity, never its private ownership token. */
+export function readOwnedRunStateDirectory(stateDir, options = {}) {
+    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, run) {
     const canonical = assertCanonicalDirectory(stateDir);
     assertMarkerMatches(readMarker(canonical), canonical, run);

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

@@ -0,0 +1,46 @@
+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 declare function queryArguments(profile: unknown, pids: unknown): string[] | undefined;
+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 declare function decodeProvenanceBinding(value: unknown): {
+    readonly kind: 'decoded_binding_unadmitted';
+    readonly binding: ProvenanceBinding;
+} | {
+    readonly kind: 'unusable';
+    readonly reason: 'invalid_binding';
+};
+export declare function decodeResponse(bytes: Uint8Array, profile: unknown, pids: unknown): DecodeOutcome;
+export {};

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

@@ -0,0 +1,114 @@
+// 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.
+export function queryArguments(profile, pids) {
+    if ((profile !== 'scalar' && profile !== 'shared') || !Array.isArray(pids) ||
+        pids.length < 1 || pids.length > 64 || (profile === 'scalar' && pids.length !== 1))
+        return undefined;
+    const selected = [];
+    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, keys) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) &&
+        Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+export function decodeProvenanceBinding(value) {
+    const invalid = { kind: 'unusable', reason: 'invalid_binding' };
+    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) {
+    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, profile, pids) {
+    const args = queryArguments(profile, pids);
+    if (!args)
+        return { kind: 'unusable', reason: 'invalid_query' };
+    const invalid = { 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;
+    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 = [];
+    const seen = new Set();
+    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/dist/lib/runs-process.d.ts

@@ -1,7 +1,9 @@
 /**
  * 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 { type ChildProcess } from "node:child_process";
 export interface RunProcessIdentity {
     command: string;
     cwd?: string;
@@ -14,9 +16,40 @@ export interface RunProcessIdentityResult {
     valid: boolean;
 }
 type ProcessIdentityReader = (pid: number, runtimePlatform: NodeJS.Platform) => RunProcessIdentity | undefined;
+export type ProcessLiveness = "alive" | "dead" | "unknown";
+type ProcessLivenessProbe = (pid: number, signal: 0) => boolean;
+export declare function readProcessLiveness(pid: number, probe?: ProcessLivenessProbe): ProcessLiveness;
+/** POSIX group presence only: neither ownership, membership completeness, nor whole-Run stop proof. */
+export declare function readProcessGroupLiveness(processGroupId: number, runtimePlatform?: NodeJS.Platform, probe?: ProcessLivenessProbe): ProcessLiveness;
+/** Unknown liveness must retain active-state guards, never authorize state reuse. */
 export declare function isAlive(pid: number): boolean;
+export declare const WINDOWS_IDENTITY_QUERY_PID_LIMIT = 64;
+/** One bounded, complete CIM observation; undefined means query failure, never process absence. */
+export declare function readWindowsProcessIdentities(pids: readonly number[]): Map<number, RunProcessIdentity> | undefined;
 export declare function readProcessIdentity(pid: number, runtimePlatform?: NodeJS.Platform): RunProcessIdentity | undefined;
+export declare function runProcessIdentityDigest(value: unknown): string | undefined;
 export declare function captureRunProcessIdentity(pid: number, cwd: string, stateDir: string, runnerPath: string, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader): RunProcessIdentity | undefined;
+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 declare function captureSpawnedRunProcessIdentity(child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">, cwd: string, stateDir: string, runnerPath: string, deps?: SpawnIdentityCaptureDeps): RunProcessIdentity | undefined;
+/** Immediate managed-native callback only; this observation is not complete membership or termination authority. */
+export declare function captureSpawnedNativeProcessIdentity(child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">, deps?: SpawnIdentityCaptureDeps): RunProcessIdentity | undefined;
 export declare function verifyRunProcessIdentity(pid: number, expected: RunProcessIdentity | undefined, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader, alive?: (pid: number) => boolean): RunProcessIdentityResult;
+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 declare function observeRunProcessExit(pid: number, expected: RunProcessIdentity | undefined, deps?: RunProcessExitDeps): RunProcessExitObservation;
 export declare function isWithinRunnerIdentityGrace(meta: Record<string, unknown>, graceMs: number): boolean;
 export {};

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

@@ -1,20 +1,33 @@
 /**
  * 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 { createHash } from "node:crypto";
 import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
 import { posix, win32 } from "node:path";
-export function isAlive(pid) {
+export function readProcessLiveness(pid, probe = process.kill.bind(process)) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return "unknown";
     try {
-        process.kill(pid, 0);
-        return true;
+        return probe(pid, 0) === true ? "alive" : "unknown";
     }
-    catch {
-        return false;
+    catch (error) {
+        return error?.code === "ESRCH" ? "dead" : "unknown";
     }
 }
+/** POSIX group presence only: neither ownership, membership completeness, nor whole-Run stop proof. */
+export function readProcessGroupLiveness(processGroupId, runtimePlatform = platform(), probe = process.kill.bind(process)) {
+    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) {
+    return readProcessLiveness(pid) !== "dead";
+}
 function readLinuxIdentity(pid) {
     if (!existsSync(`/proc/${pid}`))
         return undefined;
@@ -51,24 +64,67 @@ function readDarwinIdentity(pid) {
 }
 function readWindowsIdentity(pid) {
     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("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], { encoding: "utf8", windowsHide: true });
     if (result.status !== 0)
         return undefined;
     try {
-        const value = JSON.parse(result.stdout);
-        if (typeof value.CreationDate !== "string")
+        return decodeWindowsIdentity(JSON.parse(result.stdout));
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeWindowsIdentity(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const row = value;
+    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) {
+    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;
-        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,
-        };
+        // Parse the entire bounded output, not a clipped prefix. Every row must correlate exactly once.
+        const rows = JSON.parse(result.stdout);
+        if (!Array.isArray(rows) || rows.length > pids.length)
+            return undefined;
+        const selected = new Set(pids);
+        const identities = new Map();
+        for (const row of rows) {
+            if (!row || typeof row !== "object" || Array.isArray(row))
+                return undefined;
+            const pid = row.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;
@@ -83,26 +139,83 @@ export function readProcessIdentity(pid, runtimePlatform = platform()) {
         return readWindowsIdentity(pid);
     return undefined;
 }
-export function captureRunProcessIdentity(pid, cwd, stateDir, runnerPath, runtimePlatform = platform(), reader = readProcessIdentity) {
-    const identity = reader(pid, runtimePlatform);
-    if (!identity)
+export function runProcessIdentityDigest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
-    if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
+    const identity = value;
+    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, cwd, runtimePlatform) {
     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)
+    const actualCwd = runtimePlatform === "win32" && identity.cwd ? identity.cwd.toLowerCase() : identity.cwd;
+    return !actualCwd || actualCwd === expectedCwd;
+}
+export function captureRunProcessIdentity(pid, cwd, stateDir, runnerPath, runtimePlatform = platform(), reader = readProcessIdentity) {
+    const identity = reader(pid, runtimePlatform);
+    if (!identity || !identity.command.includes(runnerPath) || !identity.command.includes(stateDir) ||
+        !matchesRunCwd(identity, cwd, runtimePlatform))
         return undefined;
     return identity;
 }
+/** Fresh spawn only, while its lifecycle lock/child handle is retained and workload is not admitted. */
+export function captureSpawnedRunProcessIdentity(child, cwd, stateDir, runnerPath, deps = {}) {
+    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, deps = {}) {
+    const runtimePlatform = deps.runtimePlatform ?? platform();
+    if (!["linux", "darwin", "win32"].includes(runtimePlatform))
+        return undefined;
+    return captureFreshProcessIdentity(child, deps, (current) => current, () => true);
+}
+function captureFreshProcessIdentity(child, deps, accept, acceptEmpty) {
+    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;
+    // 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, expected, runtimePlatform = platform(), reader = readProcessIdentity, alive = isAlive) {
     if (!alive(pid))
         return { status: "dead_pid", valid: false };
@@ -117,6 +230,25 @@ export function verifyRunProcessIdentity(pid, expected, runtimePlatform = platfo
         current.cwd === expected.cwd;
     return { status: valid ? "valid" : "owner_mismatch", valid };
 }
+/** Observes one captured process only; signal dispatch and descendant cleanup are separate facts. */
+export function observeRunProcessExit(pid, expected, deps = {}) {
+    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, graceMs) {
     const createdAt = typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
     return (Number.isFinite(createdAt) &&