@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -3,15 +3,32 @@
  * Owns: active-run reuse checks, start lock acquisition, and safe state-dir
  * preparation before a new runner process is spawned.
  */
-import { rmSync } from "node:fs";
-import { join } from "node:path";
-import { acquireFileMutationLock, } from "./file-state.js";
+import { readdirSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { acquireFileMutationLock, mutationLockPath, } from "./file-state.js";
+import { assertNoRetainedDescendantLaunchScope } from "./runs-descendant-launches.js";
+import { assertNoRetainedNativeLaunchScope } from "./runs-native-launches.js";
+import { isRunStopResultCapture, readRunStopClaim, RUN_STOP_CLAIM_FILE } from "./runs-outcomes.js";
+import { RUN_STATE_OWNERSHIP_FILE } from "./runs-ownership.js";
 import { isAlive, verifyRunProcessIdentity, } from "./runs-process.js";
+function assertNoPendingStop(stateDir, meta) {
+    const stop = readRunStopClaim(stateDir, meta);
+    if (stop.state === "pending" || stop.state === "invalid") {
+        throw new Error("Run stop is pending or unproven; confirm the complete owned scope before restarting.");
+    }
+}
+function assertNoUnresolvedCapture(result) {
+    if (isRunStopResultCapture(result)) {
+        throw new Error("Run stop result capture is not confirmed terminal evidence.");
+    }
+}
 export function readActiveOwnedRunState(stateDir, readJson, _runnerPath) {
     const meta = readJson(join(stateDir, "run.json"));
     if (!meta)
         return undefined;
+    assertNoPendingStop(stateDir, meta);
     const result = readJson(join(stateDir, "result.json"));
+    assertNoUnresolvedCapture(result);
     if (typeof result?.completedAt === "string")
         return undefined;
     const pid = Number(meta.pid || 0);
@@ -27,16 +44,39 @@ export function readActiveOwnedRunState(stateDir, readJson, _runnerPath) {
     return identity.valid ? meta : undefined;
 }
 export function assertNoActiveRunState(stateDir, readJson, runnerPath) {
+    assertNoRetainedDescendantLaunchScope(stateDir);
+    assertNoRetainedNativeLaunchScope(stateDir);
     const meta = readActiveOwnedRunState(stateDir, readJson, runnerPath);
     if (meta) {
         throw new Error(`Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`);
     }
 }
+/** Prepare-only metadata must neither replace an earlier Run nor erase unrelated retained evidence. */
+export function assertFreshRunPreparationState(stateDir) {
+    assertNoRetainedDescendantLaunchScope(stateDir);
+    let entries;
+    try {
+        entries = readdirSync(stateDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const lock = basename(mutationLockPath(join(stateDir, ".lifecycle")));
+    if (entries.some((name) => name !== RUN_STATE_OWNERSHIP_FILE && name !== lock && !name.startsWith(`${lock}.`))) {
+        throw new Error("Run descendant preparation requires fresh state without published Run metadata or retained evidence.");
+    }
+}
 export function acquireStateStartLock(stateDir, options = {}) {
     return acquireFileMutationLock(join(stateDir, ".lifecycle"), options);
 }
 export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
+    assertNoRetainedDescendantLaunchScope(stateDir);
+    assertNoRetainedNativeLaunchScope(stateDir);
     const existing = readJson(join(stateDir, "run.json"));
+    assertNoPendingStop(stateDir, existing ?? {});
+    assertNoUnresolvedCapture(readJson(join(stateDir, "result.json")));
     const existingPid = Number(existing?.pid || 0);
     if (existingPid && isAlive(existingPid)) {
         const identity = verifyRunProcessIdentity(existingPid, existing?.process_identity);
@@ -57,6 +97,7 @@ export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
         "execution.json",
         "progress.json",
         "result.json",
+        RUN_STOP_CLAIM_FILE,
         "stderr.log",
         "stdout.log",
         "terminal-delivery-failure.json",

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

@@ -1,10 +1,24 @@
 /**
  * Async run status and log readers.
- * Owns: status derivation from run state files plus bounded log/event tails.
+ * Owns: status derivation, readonly canonical snapshot-fact admission and bounded log/event tails.
+ * Excludes: snapshot timing/visibility authority, export publication, scheduling and native scope closure.
  */
+import type { RunSnapshotFacts } from "./runs-snapshot.ts";
 export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
 type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 export declare function buildRunStatus(stateDir: string, runOrDir: string, meta: Record<string, unknown>, readJson: RunJsonReader, _runnerPath: string, _runnerIdentityGraceMs: number): Record<string, unknown>;
+/** Fixed kernel inventory path. Native frames are synchronous locals, never capabilities returned to consumers. */
+export declare function readRunInventoryStatuses(stateDirs: readonly string[], readJson: RunJsonReader, scalarStatus: (stateDir: string) => Record<string, unknown>): (Record<string, unknown> | undefined)[];
+export type RunSnapshotFactsReading = {
+    readonly state: "available";
+    readonly facts: Readonly<RunSnapshotFacts>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "identity_unavailable" | "identity_mismatch" | "observation_changed" | "observation_unavailable" | "references_unavailable" | "snapshot_too_large";
+};
+/** Kernel-local facts only. Opt-in timing must be the original retained owner's method, never actor data or a cached DTO. */
+export declare function readRunSnapshotFacts(stateDir: string, expected: unknown, capturedAt: unknown, observeTime?: (expected: unknown, stateDir?: string) => unknown, observeFrozenNaturalTime?: (expected: unknown, stateDir?: string) => unknown): Readonly<RunSnapshotFactsReading>;
 export declare function tailFile(path: string, lines: number): string;
 export declare function tailLines(path: string, lines: number): string[];
 export {};

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

@@ -1,11 +1,18 @@
 /**
  * Async run status and log readers.
- * Owns: status derivation from run state files plus bounded log/event tails.
+ * Owns: status derivation, readonly canonical snapshot-fact admission and bounded log/event tails.
+ * Excludes: snapshot timing/visibility authority, export publication, scheduling and native scope closure.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { verifyRunProcessIdentity, } from "./runs-process.js";
-import { readJsonlFileResilient } from "./state-readers.js";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { platform } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { types as UtilTypes } from "node:util";
+import { RUN_DELIVERY_MODEL_MAX_BYTES } from "./limits.js";
+import { readRunContextIdentity, readRunContextIndex, RUN_CONTEXT_INDEX_FILE, RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES } from "./runs-context-index.js";
+import { RUN_OUTCOME_PROTOCOL, RUN_STOP_CLAIM_FILE, isRunStopResultCapture, readRunNaturalOutcomeSnapshot, readRunStopClaim } from "./runs-outcomes.js";
+import { RUN_STATE_OWNERSHIP_FILE } from "./runs-ownership.js";
+import { isAlive, observeRunProcessExit, readWindowsProcessIdentities, WINDOWS_IDENTITY_QUERY_PID_LIMIT, verifyRunProcessIdentity, } from "./runs-process.js";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
 function getInterruptedRunStatus(stateDir) {
     const trace = readJsonlFileResilient(join(stateDir, "trace.jsonl")).records.slice(-200);
     for (const event of trace.reverse()) {
@@ -24,18 +31,32 @@ function getInterruptedRunStatus(stateDir) {
     return undefined;
 }
 export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath, _runnerIdentityGraceMs) {
-    const result = readJson(join(stateDir, "result.json"));
+    return deriveRunStatus(stateDir, meta, readJson, (pid, expected) => verifyRunProcessIdentity(pid, expected));
+}
+function deriveRunStatus(stateDir, meta, readJson, observeIdentity) {
+    const snapshot = readRunNaturalOutcomeSnapshot(stateDir, meta, readJson);
+    const rawResult = snapshot.result;
+    const staleResult = rawResult?.run_instance_id !== undefined && rawResult.run_instance_id !== meta.run_instance_id;
+    const result = staleResult ? undefined : rawResult;
+    const stop = readRunStopClaim(stateDir, meta);
+    const unresolvedCapture = isRunStopResultCapture(result);
+    const natural = snapshot.outcome;
+    const stopping = natural.state !== "accepted" && (stop.state === "pending" || stop.state === "invalid" || unresolvedCapture);
     const pid = Number(meta.pid || 0);
-    const processIdentity = verifyRunProcessIdentity(pid, meta.process_identity);
+    const processIdentity = observeIdentity(pid, meta.process_identity);
     const aliveOwnedRunner = Boolean(pid &&
         (processIdentity.valid || processIdentity.status === "unsupported_proof"));
-    const status = result
-        ? Number(result.code ?? 0) === 0
-            ? "done"
-            : "failed"
-        : aliveOwnedRunner
+    const status = natural.state === "accepted"
+        ? natural.status
+        : stopping
             ? "running"
-            : (getInterruptedRunStatus(stateDir) ?? "exited");
+            : result
+                ? Number(result.code ?? 0) === 0
+                    ? "done"
+                    : "failed"
+                : aliveOwnedRunner
+                    ? "running"
+                    : (getInterruptedRunStatus(stateDir) ?? "exited");
     const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
     const terminalDeliveryFailure = readJson(join(stateDir, "terminal-delivery-failure.json"));
     return {
@@ -43,6 +64,11 @@ export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath,
         traceFile: join(stateDir, "trace.jsonl"),
         executionFile: join(stateDir, "execution.json"),
         process_identity_status: processIdentity.status,
+        ...(stopping ? { phase: "stopping", stopped: false } : {}),
+        ...(stopping && stop.state === "pending" ? { stop_reason: stop.claim.reason, stop_claim_id: stop.claim.claim_id } : {}),
+        ...(stop.state === "invalid" || (unresolvedCapture && stop.state !== "pending")
+            ? { stop_error: "claim_unavailable" } : {}),
+        ...(staleResult ? { result_error: "generation_mismatch" } : {}),
         progress: readJson(join(stateDir, "progress.json")) || null,
         result: result || null,
         ...(terminalDeliveryFailure
@@ -54,6 +80,304 @@ export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath,
         status,
     };
 }
+function readInventorySource(path) {
+    let fd;
+    try {
+        const stamp = snapshotStamp(path);
+        if (!stamp?.isFile() || stamp.size > BigInt(RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES))
+            return undefined;
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const opened = fstatSync(fd, { bigint: true });
+        if (opened.dev !== stamp.dev || opened.ino !== stamp.ino || !opened.isFile() || opened.size !== stamp.size ||
+            opened.mtimeNs !== stamp.mtimeNs || opened.ctimeNs !== stamp.ctimeNs)
+            return undefined;
+        const bytes = Buffer.alloc(Number(stamp.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (!count)
+                return undefined;
+            offset += count;
+        }
+        if (readSync(fd, Buffer.alloc(1), 0, 1, offset) !== 0 ||
+            !sameSnapshotStamp(stamp, path))
+            return undefined;
+        const after = fstatSync(fd, { bigint: true });
+        return after.size === stamp.size && after.mtimeNs === stamp.mtimeNs && after.ctimeNs === stamp.ctimeNs ? { stamp, bytes } : undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function admitInventoryRow(stateDir) {
+    const path = join(stateDir, "run.json");
+    const markerPath = join(stateDir, RUN_STATE_OWNERSHIP_FILE);
+    const source = readInventorySource(path);
+    if (!source)
+        return undefined;
+    let meta;
+    try {
+        meta = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(source.bytes));
+    }
+    catch {
+        return undefined;
+    }
+    if (!meta || typeof meta !== "object" || Array.isArray(meta) || meta.state_dir !== stateDir ||
+        typeof meta.pid !== "number" || !Number.isSafeInteger(meta.pid) || meta.pid <= 0)
+        return undefined;
+    const expected = meta.process_identity;
+    if (!expected || expected.platform !== "win32" || typeof expected.command !== "string" ||
+        typeof expected.start_time !== "string" || (expected.cwd !== undefined && typeof expected.cwd !== "string"))
+        return undefined;
+    const owner = readRunContextIdentity(stateDir, meta);
+    if (owner.state !== "available" || owner.local_path !== stateDir)
+        return undefined;
+    const marker = readInventorySource(markerPath);
+    if (!marker)
+        return undefined;
+    const unchanged = () => {
+        if (!owner.unchanged() || !sameSnapshotStamp(source.stamp, path) || !sameSnapshotStamp(marker.stamp, markerPath))
+            return false;
+        const current = readInventorySource(path);
+        const currentMarker = readInventorySource(markerPath);
+        return !!current && !!currentMarker && source.bytes.equals(current.bytes) && marker.bytes.equals(currentMarker.bytes) && owner.unchanged();
+    };
+    // Once admitted, a changed row can only be discarded, never reread through the scalar facade.
+    return { meta, pid: meta.pid, expected, unchanged };
+}
+/** Fixed kernel inventory path. Native frames are synchronous locals, never capabilities returned to consumers. */
+export function readRunInventoryStatuses(stateDirs, readJson, scalarStatus) {
+    const scalar = (stateDir) => { try {
+        return scalarStatus(stateDir);
+    }
+    catch {
+        return undefined;
+    } };
+    if (platform() !== "win32")
+        return stateDirs.map(scalar);
+    const rows = stateDirs.map(stateDir => { try {
+        return admitInventoryRow(stateDir);
+    }
+    catch {
+        return undefined;
+    } });
+    // This selects optional acquisition only; assembly still verifies freshly and excluded rows retain scalar fallback.
+    const pids = [...new Set(rows.flatMap(row => row ? [row.pid] : []))].filter(isAlive);
+    const observations = new Map();
+    for (let offset = 0; offset < pids.length; offset += WINDOWS_IDENTITY_QUERY_PID_LIMIT) {
+        const chunk = pids.slice(offset, offset + WINDOWS_IDENTITY_QUERY_PID_LIMIT);
+        const identities = readWindowsProcessIdentities(chunk);
+        for (const pid of chunk)
+            observations.set(pid, identities);
+    }
+    const statuses = stateDirs.map((stateDir, index) => {
+        const row = rows[index];
+        if (!row)
+            return scalar(stateDir);
+        try {
+            if (!row.unchanged())
+                return undefined;
+            const identities = observations.get(row.pid);
+            const status = deriveRunStatus(stateDir, row.meta, readJson, () => {
+                if (!row.unchanged())
+                    throw new Error("Inventory frame changed");
+                const identity = identities === undefined ? verifyRunProcessIdentity(row.pid, row.expected)
+                    : verifyRunProcessIdentity(row.pid, row.expected, "win32", pid => identities.get(pid));
+                if (!row.unchanged())
+                    throw new Error("Inventory frame changed");
+                return identity;
+            });
+            return row.unchanged() ? status : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // Later row assembly can reenter file readers and invalidate an earlier assembled row.
+    return statuses.map((status, index) => {
+        const row = rows[index];
+        if (!status || !row)
+            return status;
+        try {
+            return row.unchanged() ? status : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+function snapshotStamp(path) {
+    try {
+        return lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function sameSnapshotStamp(before, path) {
+    const after = snapshotStamp(path);
+    return before === undefined ? after === undefined : after !== undefined && before.dev === after.dev && before.ino === after.ino &&
+        before.mode === after.mode && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs;
+}
+function snapshotDeferred(value) {
+    if (!UtilTypes.isPromise(value))
+        return false;
+    void Promise.prototype.then.call(value, undefined, () => { });
+    return true;
+}
+function snapshotData(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    for (let target = value; target; target = Object.getPrototypeOf(target)) {
+        const then = Object.getOwnPropertyDescriptor(target, "then");
+        if (then && (!Object.hasOwn(then, "value") || typeof then.value === "function"))
+            return undefined;
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return Object.values(descriptors).every(field => Object.hasOwn(field, "value"))
+        ? Object.fromEntries(Object.entries(descriptors).map(([key, field]) => [key, field.value])) : undefined;
+}
+/** Kernel-local facts only. Opt-in timing must be the original retained owner's method, never actor data or a cached DTO. */
+export function readRunSnapshotFacts(stateDir, expected, capturedAt, observeTime, observeFrozenNaturalTime) {
+    const unavailable = (reason) => Object.freeze({ state: "unavailable", reason });
+    if ((observeTime !== undefined && typeof observeTime !== "function") ||
+        (observeFrozenNaturalTime !== undefined && typeof observeFrozenNaturalTime !== "function") || typeof capturedAt !== "string" || capturedAt.length > 32)
+        return unavailable("observation_unavailable");
+    const capturedMs = Date.parse(capturedAt);
+    if (!Number.isSafeInteger(capturedMs) || new Date(capturedMs).toISOString() !== capturedAt)
+        return unavailable("observation_unavailable");
+    const owner = readRunContextIdentity(stateDir, expected);
+    if (owner.state !== "available")
+        return unavailable(owner.reason);
+    try {
+        const root = owner.local_path;
+        const metadataPath = join(root, "run.json");
+        const resultPath = join(root, "result.json");
+        const indexPath = join(root, RUN_CONTEXT_INDEX_FILE);
+        const metadata = snapshotStamp(metadataPath);
+        if (!metadata?.isFile() || metadata.size > BigInt(RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES))
+            return unavailable("observation_unavailable");
+        const read = readJsonFileResilient(metadataPath, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+        if (!owner.unchanged() || !sameSnapshotStamp(metadata, metadataPath))
+            return unavailable("observation_changed");
+        if (read.diagnostics.length || !read.value || typeof read.value !== "object" || Array.isArray(read.value))
+            return unavailable("observation_unavailable");
+        const meta = read.value;
+        if (meta.run !== owner.identity.run || meta.run_instance_id !== owner.identity.run_instance_id || meta.ownerId !== owner.identity.ownerId || meta.state_dir !== root)
+            return unavailable("identity_mismatch");
+        if (typeof meta.cwd !== "string" || !isAbsolute(meta.cwd) || /[\u0000-\u001f\u007f]/u.test(meta.cwd))
+            return unavailable("references_unavailable");
+        if (meta.cwd.length > RUN_DELIVERY_MODEL_MAX_BYTES)
+            return unavailable("snapshot_too_large");
+        const result = snapshotStamp(resultPath);
+        const index = snapshotStamp(indexPath);
+        if (result && !result.isFile())
+            return unavailable("observation_unavailable");
+        const outcome = readRunNaturalOutcomeSnapshot(root, meta, path => {
+            const canonical = readJsonFileResilient(path, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+            return canonical.diagnostics.length ? undefined : canonical.value;
+        });
+        const natural = outcome.outcome;
+        const context = readRunContextIndex(root, owner.identity);
+        const stopPath = join(root, RUN_STOP_CLAIM_FILE);
+        let stopObserved = false;
+        let stopStamp;
+        let timingUnchanged;
+        const frameUnchanged = () => owner.unchanged() && sameSnapshotStamp(metadata, metadataPath) &&
+            sameSnapshotStamp(result, resultPath) && sameSnapshotStamp(index, indexPath) && (!stopObserved || sameSnapshotStamp(stopStamp, stopPath));
+        const unchanged = () => {
+            try {
+                if (!frameUnchanged())
+                    return false;
+                if (!timingUnchanged)
+                    return true;
+                const stable = timingUnchanged();
+                return !snapshotDeferred(stable) && stable === true && frameUnchanged();
+            }
+            catch {
+                return false;
+            }
+        };
+        if (!unchanged())
+            return unavailable("observation_changed");
+        let lifecycle = meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && natural.state === "accepted"
+            ? Object.freeze({ status: natural.status }) : Object.freeze({ status: "unproven" });
+        let timing = Object.freeze({ basis: "unproven" });
+        if (observeFrozenNaturalTime && meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && natural.state === "accepted") {
+            const retained = observeFrozenNaturalTime(owner.identity, root);
+            if (snapshotDeferred(retained))
+                return unavailable("observation_unavailable");
+            const frozen = snapshotData(retained);
+            if (!frozen)
+                return unavailable("observation_unavailable");
+            if (frozen.state === "available") {
+                const identity = snapshotData(frozen.identity);
+                const accepted = snapshotData(frozen.natural_acceptance);
+                if (!identity || identity.run !== owner.identity.run || identity.run_instance_id !== owner.identity.run_instance_id || identity.ownerId !== owner.identity.ownerId)
+                    return unavailable("identity_mismatch");
+                if (frozen.basis !== "first_natural_acceptance" || !accepted || accepted.recorded_status !== natural.status || accepted.code !== outcome.result?.code ||
+                    accepted.completed_at !== outcome.result?.completedAt || typeof frozen.elapsed_ms !== "number" || !Number.isSafeInteger(frozen.elapsed_ms) || frozen.elapsed_ms < 0 ||
+                    typeof frozen.unchanged !== "function")
+                    return unavailable("observation_unavailable");
+                timingUnchanged = frozen.unchanged;
+                timing = Object.freeze({ basis: "terminal", elapsed_ms: frozen.elapsed_ms });
+            }
+            else if (frozen.state !== "unavailable")
+                return unavailable("observation_unavailable");
+            if (!unchanged())
+                return unavailable("observation_changed");
+        }
+        if (observeTime && meta.outcome_protocol === RUN_OUTCOME_PROTOCOL && (natural.state === "absent" || natural.state === "captured") &&
+            typeof meta.pid === "number" && Number.isSafeInteger(meta.pid) && meta.pid > 0) {
+            stopObserved = true;
+            stopStamp = snapshotStamp(stopPath);
+            const stop = readRunStopClaim(root, meta);
+            const eligible = (natural.state === "absent" && (stop.state === "absent" || stop.state === "stale" || stop.state === "pending")) ||
+                (natural.state === "captured" && stop.state === "pending" && outcome.result?.stop_claim_id === stop.claim.claim_id);
+            if (eligible && observeRunProcessExit(meta.pid, meta.process_identity).status === "running") {
+                if (!unchanged())
+                    return unavailable("observation_changed");
+                const sampled = observeTime(owner.identity, root);
+                if (snapshotDeferred(sampled))
+                    return unavailable("observation_unavailable");
+                const observed = snapshotData(sampled);
+                if (!observed)
+                    return unavailable("observation_unavailable");
+                if (observed.state === "available") {
+                    const identity = snapshotData(observed.identity);
+                    const measured = snapshotData(observed.timing);
+                    if (!identity || identity.run !== owner.identity.run || identity.run_instance_id !== owner.identity.run_instance_id || identity.ownerId !== owner.identity.ownerId)
+                        return unavailable("identity_mismatch");
+                    if (observed.basis !== "since_admission" || !measured || typeof observed.unchanged !== "function")
+                        return unavailable("observation_unavailable");
+                    timingUnchanged = observed.unchanged;
+                    lifecycle = Object.freeze({ status: "running", ...(stop.state === "pending" ? { phase: "stopping" } : {}) });
+                    if (measured.state === "available" && typeof measured.elapsed_ms === "number" && Number.isSafeInteger(measured.elapsed_ms) && measured.elapsed_ms >= 0) {
+                        timing = Object.freeze({ basis: "live", elapsed_ms: measured.elapsed_ms });
+                    }
+                    else if (measured.state !== "unproven" || measured.elapsed_ms !== null)
+                        return unavailable("observation_unavailable");
+                }
+                else if (observed.state !== "unavailable")
+                    return unavailable("observation_unavailable");
+                if (!unchanged() || observeRunProcessExit(meta.pid, meta.process_identity).status !== "running" || !unchanged())
+                    return unavailable("observation_changed");
+            }
+        }
+        const facts = Object.freeze({ identity: owner.identity, captured_at: capturedAt,
+            lifecycle, timing, cwd: meta.cwd,
+            ...(context.state === "available" ? { context_index: Object.freeze({ identity: context.identity, path: context.local_path }) } : {}) });
+        if (Buffer.byteLength(JSON.stringify(facts)) > RUN_DELIVERY_MODEL_MAX_BYTES)
+            return unavailable("snapshot_too_large");
+        return unchanged() ? Object.freeze({ state: "available", facts, unchanged }) : unavailable("observation_changed");
+    }
+    catch {
+        return unavailable("observation_unavailable");
+    }
+}
 export function tailFile(path, lines) {
     if (!existsSync(path))
         return "";

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

@@ -0,0 +1,105 @@
+import { type RunSupervisionClock, type RunSupervisionController, type RunSupervisionControllerPorts, type RunSupervisionControllerSnapshot, type RunSupervisionTimebaseReading, type RunSupervisionTimeObservation } from "./run-supervision.ts";
+import { type RunContextIndexIdentity } from "./runs-context-index.ts";
+import { type RunSnapshotReferencesReading } from "./runs-context-exports.ts";
+import { type RunSnapshotFactsReading } from "./runs-status.ts";
+import { type RunSnapshot, type RunSnapshotProjection } from "./runs-snapshot.ts";
+import { type RunNaturalResultTimingAdmission, type RunResultProducer } from "./runs-results.ts";
+export type RunSupervisionBindingReading = {
+    readonly state: "available";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly clock: Readonly<RunSupervisionClock>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "identity_unavailable" | "identity_mismatch" | "observation_changed" | "clock_metadata_unavailable" | "clock_unconfigured" | "clock_invalid";
+};
+type Unavailable = Extract<RunSupervisionBindingReading, {
+    state: "unavailable";
+}>;
+export type BoundRunSupervisionControllerReading = {
+    readonly state: "available";
+    readonly controller: Readonly<RunSupervisionController>;
+} | Unavailable | Extract<RunSupervisionTimebaseReading, {
+    state: "unavailable";
+}>;
+/** Curated metadata only; no current-time read, clock repair, lifecycle/native observation or role body. */
+export declare function readRunSupervisionBinding(stateDir: string, expected: unknown): Readonly<RunSupervisionBindingReading>;
+/** Does not start automatically; origin must be the genuine reference retained from generation admission. */
+export declare function createRunSupervisionControllerFromState(stateDir: string, expected: unknown, origin: unknown, ports: Omit<RunSupervisionControllerPorts, "readCurrent">): Readonly<BoundRunSupervisionControllerReading>;
+export type RunSupervisionOwnerReading = {
+    readonly state: "retained" | "stopped" | "released";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly controller?: Readonly<RunSupervisionControllerSnapshot>;
+} | {
+    readonly state: "controlled";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly controller: Readonly<RunSupervisionControllerSnapshot>;
+} | {
+    readonly state: "unavailable";
+    readonly reason: Extract<BoundRunSupervisionControllerReading, {
+        state: "unavailable";
+    }>["reason"] | "identity_invalid" | "origin_not_retained" | "owner_closed" | "controller_claimed";
+};
+type OwnerUnavailable = Extract<RunSupervisionOwnerReading, {
+    state: "unavailable";
+}>;
+export type RunSupervisionOwnerTimeReading = {
+    readonly state: "available";
+    readonly basis: "since_admission";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly timing: Readonly<RunSupervisionTimeObservation>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: OwnerUnavailable["reason"] | "owner_stopped";
+};
+export type RunSupervisionOwnerReferencesReading = RunSnapshotReferencesReading | OwnerUnavailable | {
+    readonly state: "unavailable";
+    readonly reason: "owner_stopped" | "references_not_retained";
+};
+export type RunSupervisionOwnerSnapshotReading = {
+    readonly state: "available";
+    readonly snapshot: Readonly<RunSnapshot>;
+    readonly unchanged: () => boolean;
+} | Extract<RunSnapshotProjection | RunSnapshotFactsReading | RunSupervisionOwnerReferencesReading, {
+    state: "unavailable";
+}>;
+export type RunSupervisionOwnerNaturalTimeReading = {
+    readonly state: "available";
+    readonly basis: "first_natural_acceptance";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly elapsed_ms: number;
+    readonly natural_acceptance: Readonly<{
+        code: number;
+        recorded_status: "done" | "failed";
+        completed_at: string;
+    }>;
+    readonly unchanged: () => boolean;
+} | Extract<RunSupervisionOwnerTimeReading, {
+    state: "unavailable";
+}> | {
+    readonly state: "unavailable";
+    readonly reason: "natural_time_not_captured" | "natural_time_capturing" | "natural_time_unproven" | "natural_acceptance_mismatch";
+};
+export interface RunSupervisionOwnerClose {
+    readonly state: "closed";
+    readonly timer_cleanup?: "unproven";
+}
+export interface RunSupervisionOwner {
+    readonly onSupervisionClockCaptured: (capture: unknown) => void;
+    readonly start: (expected: unknown) => Readonly<RunSupervisionOwnerReading>;
+    readonly stop: (expected: unknown) => Readonly<RunSupervisionOwnerReading>;
+    readonly release: (expected: unknown) => Readonly<RunSupervisionOwnerReading>;
+    readonly snapshot: (expected: unknown) => Readonly<RunSupervisionOwnerReading>;
+    readonly observeTime: (expected: unknown, stateDir?: string) => Readonly<RunSupervisionOwnerTimeReading>;
+    readonly observeReferences: (expected: unknown, stateDir?: string) => Readonly<RunSupervisionOwnerReferencesReading>;
+    /** Active postcommit admission only; the first authorized attempt is final across original-origin owners. */
+    readonly captureNaturalTime: (expected: unknown, producer: RunResultProducer, admission: RunNaturalResultTimingAdmission, stateDir?: string) => Readonly<RunSupervisionOwnerNaturalTimeReading>;
+    /** Historical elapsed plus current owner/clock/frame, not current result/lifecycle or a new sample. */
+    readonly observeFrozenNaturalTime: (expected: unknown, stateDir?: string) => Readonly<RunSupervisionOwnerNaturalTimeReading>;
+    readonly observeSnapshot: (expected: unknown, capturedAt: unknown, stateDir?: string) => Readonly<RunSupervisionOwnerSnapshotReading>;
+    readonly close: () => Readonly<RunSupervisionOwnerClose>;
+}
+/** Explicit retention with cooperative same-origin claims; no default watcher, cross-process lease or independent supervisor. */
+export declare function createRunSupervisionOwner(ports: Omit<RunSupervisionControllerPorts, "readCurrent">): Readonly<RunSupervisionOwner>;
+export {};