oh-my-super-agent 0.1.0

package/dist/src/runs/controller.js

@@ -0,0 +1,1182 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { createAuditRunTerminalWriter, createLiveRunLedger, } from "../audit/run-ledger.js";
+import { assertFileInside, openStableDirectory, readImmutableFile, writeImmutableFile, } from "../evidence/immutable-file.js";
+import { createEnduranceAuthorities } from "../runtime/endurance-authorities.js";
+import { acquireDirectoryLock, readLockOwner, recoverDirectoryLock } from "../runtime/lock.js";
+import { currentProcessInstanceId, processIsAlive } from "../runtime/process-identity.js";
+import { assertSchema, loadJsonSchema } from "../runtime/schema.js";
+import { createStableId } from "../runtime/stable-id.js";
+import { systemBootId, systemClockSample } from "../runtime/system-clock.js";
+import { generateServicePlan, persistServicePlan, verifyPersistedServicePlan, } from "../schedule/service-plan.js";
+import { loadTrackedRolePolicyGate } from "../domain/role-policy.js";
+import { isRecord, validateExistingDirectory } from "../utils/fs.js";
+import { freezeTrackedVerificationPlan } from "../verification/plan.js";
+const MAX_CONTROL_BYTES = 1024 * 1024;
+const RUN_TICKET_ADMISSION = Symbol("OMS run ticket admission");
+const RUN_TICKET_ADMISSIONS = new WeakSet();
+const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+export function startAuditRun(options) {
+    const packageRoot = validateExistingDirectory(options.packageRoot, "package root");
+    const configRoot = validateExistingDirectory(options.configRoot, "configuration root");
+    const stateRoot = validateExistingDirectory(options.stateRoot, "runtime state root");
+    const workspaceRoot = validateExistingDirectory(options.workspaceRoot, "workspace root");
+    if (options.runKind !== "12h" && options.runKind !== "24h" && options.runKind !== "until-empty") {
+        throw new Error("unsupported audit run kind");
+    }
+    return withRunControllerAuthority(stateRoot, () => {
+        const runtime = createEnduranceAuthorities({ packageRoot, configRoot, stateRoot });
+        try {
+            const intents = listStartIntents(packageRoot, stateRoot);
+            const outstanding = outstandingStartIntents(runtime.auditLedger, intents);
+            if (outstanding.length > 1)
+                throw new Error("multiple outstanding run intents require operator repair");
+            const activeWithoutIntent = runtime.auditLedger.listRunIds().filter((runId) => {
+                const head = runtime.auditLedger.head(runId);
+                if (!head || runtime.auditLedger.deriveMetrics(head).status !== "running")
+                    return false;
+                return !intents.some((intent) => intent.expected_run_id === runId);
+            });
+            if (activeWithoutIntent.length > 0)
+                throw new Error(`unbound active audit run requires operator repair: ${activeWithoutIntent[0]}`);
+            const intent = outstanding[0]
+                ? assertStartRequestMatches(outstanding[0], options, runtime.policyGate.digest, configRoot)
+                : createStartIntent({
+                    packageRoot,
+                    configRoot,
+                    stateRoot,
+                    workspaceRoot,
+                    executablePath: options.executablePath,
+                    manager: options.manager,
+                    runKind: options.runKind,
+                    policyDigest: runtime.policyGate.digest,
+                    tickets: runtime.tickets.queue.list(),
+                });
+            const started = runtime.auditLedger.start({
+                operationId: intent.operation_id,
+                runKind: intent.run_kind,
+                policyDigest: intent.policy_digest,
+                ticketSetDigest: intent.ticket_set_digest,
+                servicePlanDigest: intent.service_plan_digest,
+            });
+            if (started.entry.run_id !== intent.expected_run_id)
+                throw new Error("run start intent derived a different run id");
+            const manifest = persistManifest(manifestFromIntent(intent, started.entry.recorded_at), packageRoot, stateRoot);
+            return Object.freeze({ status: started.status, manifest });
+        }
+        finally {
+            runtime.close();
+        }
+    });
+}
+export function conductorNext(options) {
+    return withRunControllerAuthority(options.stateRoot, () => {
+        const runtime = createEnduranceAuthorities(options);
+        try {
+            const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+            assertRunCurrentAuthority(manifest, options.configRoot);
+            assertActiveManifestRun(runtime.auditLedger, manifest);
+            return persistDecision(buildConductorRoute(runtime.tickets.queue.list(), manifest), options.packageRoot, options.stateRoot);
+        }
+        finally {
+            runtime.close();
+        }
+    });
+}
+export function tickAuditRun(options) {
+    return withRunControllerAuthority(options.stateRoot, () => {
+        const runtime = createEnduranceAuthorities(options);
+        try {
+            const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+            assertRunCurrentAuthority(manifest, options.configRoot);
+            let metrics = currentMetrics(runtime.auditLedger, manifest);
+            if (metrics.status !== "running") {
+                validateTerminal(runtime, manifest, metrics, options.packageRoot);
+                return Object.freeze({ status: buildStatus(runtime.tickets.queue.list(), manifest, metrics), route: null });
+            }
+            recordControllerObservation(runtime.auditLedger, manifest, "tick");
+            metrics = currentMetrics(runtime.auditLedger, manifest);
+            projectTicketStates(runtime.auditLedger, manifest, runtime.tickets.queue.list());
+            const route = buildConductorRoute(runtime.tickets.queue.list(), manifest);
+            persistDecision(route, options.packageRoot, options.stateRoot);
+            if (manifest.run_kind === "until-empty" && route.action === "queue-empty") {
+                completeAuditRun(runtime, manifest, "until-empty", 0, options.packageRoot);
+            }
+            const latest = currentMetrics(runtime.auditLedger, manifest);
+            validateTerminal(runtime, manifest, latest, options.packageRoot);
+            return Object.freeze({ status: buildStatus(runtime.tickets.queue.list(), manifest, latest), route });
+        }
+        finally {
+            runtime.close();
+        }
+    });
+}
+export function closeTimedAuditRun(options) {
+    return withRunControllerAuthority(options.stateRoot, () => {
+        const runtime = createEnduranceAuthorities(options);
+        try {
+            const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+            assertRunCurrentAuthority(manifest, options.configRoot);
+            if (manifest.run_kind === "until-empty")
+                throw new Error("until-empty runs close through run tick");
+            let metrics = currentMetrics(runtime.auditLedger, manifest);
+            if (metrics.status !== "running") {
+                validateTerminal(runtime, manifest, metrics, options.packageRoot);
+                if (metrics.status === "aborted")
+                    throw new Error(`aborted audit run cannot be closed: ${manifest.run_id}`);
+                return buildStatus(runtime.tickets.queue.list(), manifest, metrics);
+            }
+            recordControllerObservation(runtime.auditLedger, manifest, "close");
+            metrics = currentMetrics(runtime.auditLedger, manifest);
+            const minimum = manifest.run_kind === "12h" ? TWELVE_HOURS_MS : TWENTY_FOUR_HOURS_MS;
+            if (!metrics.restart_continuity_valid || metrics.monotonic_elapsed_ms < minimum || metrics.elapsed_ms < minimum) {
+                throw new Error(`${manifest.run_kind} audit duration has not elapsed with valid continuity`);
+            }
+            projectTicketStates(runtime.auditLedger, manifest, runtime.tickets.queue.list());
+            if (buildConductorRoute(runtime.tickets.queue.list(), manifest).action !== "queue-empty") {
+                throw new Error("timed audit run cannot close with unresolved or unadmitted tickets");
+            }
+            completeAuditRun(runtime, manifest, "elapsed", minimum, options.packageRoot);
+            const latest = currentMetrics(runtime.auditLedger, manifest);
+            validateTerminal(runtime, manifest, latest, options.packageRoot);
+            return buildStatus(runtime.tickets.queue.list(), manifest, latest);
+        }
+        finally {
+            runtime.close();
+        }
+    });
+}
+export function abortAuditRun(options) {
+    return withRunControllerAuthority(options.stateRoot, () => {
+        const runtime = createEnduranceAuthorities(options);
+        try {
+            const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+            const metrics = currentMetrics(runtime.auditLedger, manifest);
+            const reason = boundedReason(options.reason);
+            if (metrics.status === "running") {
+                const reasonSha256 = sha256(reason);
+                const reasonFile = `${manifest.run_id}-${reasonSha256}.txt`;
+                writeControlFile(join(options.stateRoot, "run-aborts"), reasonFile, Buffer.from(reason, "utf8"), "run aborts root");
+                appendRunTerminalEvent(runtime.auditLedger, createAuditRunTerminalWriter(runtime.auditLedger), {
+                    runId: manifest.run_id,
+                    operationId: createStableId("run-abort", manifest.run_id, reasonSha256),
+                    entryKind: "run-aborted",
+                    payload: {
+                        manifest_id: manifest.manifest_id,
+                        reason_sha256: reasonSha256,
+                        reason_file: reasonFile,
+                        certifying: false,
+                    },
+                });
+            }
+            else if (metrics.status === "completed") {
+                throw new Error(`completed audit run cannot be aborted: ${manifest.run_id}`);
+            }
+            else {
+                const terminal = runtime.auditLedger.list(manifest.run_id).at(-1);
+                if (terminal?.entry_kind !== "run-aborted" || terminal.payload.reason_sha256 !== sha256(reason)) {
+                    throw new Error(`audit run was already aborted with a different reason: ${manifest.run_id}`);
+                }
+            }
+            const latest = currentMetrics(runtime.auditLedger, manifest);
+            validateTerminal(runtime, manifest, latest, options.packageRoot);
+            return buildStatus(runtime.tickets.queue.list(), manifest, latest);
+        }
+        finally {
+            runtime.close();
+        }
+    });
+}
+export function recoverRunControllerAuthority(options) {
+    const packageRoot = validateExistingDirectory(options.packageRoot, "package root");
+    const stateRoot = validateExistingDirectory(options.stateRoot, "runtime state root");
+    const reason = boundedRecoveryReason(options.reason);
+    const locksRoot = join(stateRoot, "locks");
+    const lockPath = join(locksRoot, "run-controller");
+    const owner = readLockOwner(lockPath);
+    if (owner) {
+        if (owner.created_nonce !== options.expectedGenerationId) {
+            throw new Error("expected run controller generation is not active");
+        }
+        if (owner.boot_id === systemBootId() && processIsAlive(owner.process_id)) {
+            throw new Error("refusing to recover a run controller lock whose owner process is alive");
+        }
+    }
+    const recovered = recoverDirectoryLock({
+        locksRoot,
+        lockId: "run-controller",
+        recoveredBy: "oms-run-controller",
+        reason,
+        expectedGenerationId: options.expectedGenerationId,
+    });
+    withRunControllerAuthority(stateRoot, () => {
+        const ledger = createLiveRunLedger({
+            ledgerRoot: join(stateRoot, "audit"),
+            locksRoot,
+            packageRoot,
+        });
+        const intents = listStartIntents(packageRoot, stateRoot);
+        const activeRunIds = ledger.listRunIds().filter((runId) => {
+            const head = ledger.head(runId);
+            if (head === undefined || ledger.deriveMetrics(head).status !== "running")
+                return false;
+            try {
+                const manifest = readRunManifest(packageRoot, stateRoot, runId);
+                assertRunManifestLedgerBinding(ledger, manifest);
+            }
+            catch (error) {
+                const intent = intents.find((candidate) => candidate.expected_run_id === runId);
+                if (!intent)
+                    throw error;
+                assertRunLedgerMatchesStartIntent(ledger, intent);
+            }
+            return true;
+        });
+        if (activeRunIds.length > 1)
+            throw new Error("multiple active runs block controller recovery audit projection");
+        const runId = activeRunIds[0];
+        if (runId) {
+            appendRunAuditEvent(ledger, {
+                runId,
+                operationId: createStableId("run-ctl-recov", runId, recovered.generation_id),
+                entryKind: "controller-lock-recovered",
+                payload: {
+                    lock_id: recovered.lock_id,
+                    generation_id: recovered.generation_id,
+                    recovered_by: recovered.recovered_by,
+                    recovery_evidence_path: recovered.recoveryEvidencePath,
+                },
+            });
+        }
+    });
+    return Object.freeze({
+        recovered: true,
+        lock_id: "run-controller",
+        generation_id: recovered.generation_id,
+        recovered_by: recovered.recovered_by,
+        previous_process_id: recovered.previousOwner.process_id,
+        recovery_evidence_path: recovered.recoveryEvidencePath,
+    });
+}
+function assertRunLedgerMatchesStartIntent(ledger, intent) {
+    const first = ledger.list(intent.expected_run_id)[0];
+    if (!first
+        || first.entry_kind !== "run-started"
+        || first.run_id !== intent.expected_run_id
+        || first.operation_id !== intent.operation_id
+        || first.run_kind !== intent.run_kind
+        || first.policy_sha256 !== intent.policy_digest
+        || first.payload.ticket_set_digest !== intent.ticket_set_digest
+        || first.payload.service_plan_digest !== intent.service_plan_digest) {
+        throw new Error(`active run ledger does not match its outstanding start intent: ${intent.expected_run_id}`);
+    }
+}
+export function readRunStatus(options) {
+    const runtime = createEnduranceAuthorities(options);
+    try {
+        const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+        assertRunCurrentAuthority(manifest, options.configRoot);
+        const metrics = currentMetrics(runtime.auditLedger, manifest);
+        validateTerminal(runtime, manifest, metrics, options.packageRoot);
+        return buildStatus(runtime.tickets.queue.list(), manifest, metrics);
+    }
+    finally {
+        runtime.close();
+    }
+}
+export function listRunStatuses(options) {
+    const root = openStableDirectory(join(options.stateRoot, "run-manifests"), "run manifests root");
+    try {
+        const runIds = readdirSync(root.path, { withFileTypes: true }).map((entry) => {
+            if (!entry.isFile() || !/^run-[a-f0-9]{48}\.json$/.test(entry.name))
+                throw new Error(`unsafe run manifest entry: ${entry.name}`);
+            return entry.name.slice(0, -5);
+        }).sort(compareText);
+        root.assertUnchanged();
+        return Object.freeze(runIds.map((runId) => readRunStatus({ ...options, runId })));
+    }
+    finally {
+        root.close();
+    }
+}
+export function assertRunTicketAdmission(options) {
+    const manifest = readRunManifest(options.packageRoot, options.stateRoot, options.runId);
+    assertRunCurrentAuthority(manifest, options.configRoot);
+    const ledger = createLiveRunLedger({
+        ledgerRoot: join(options.stateRoot, "audit"),
+        locksRoot: join(options.stateRoot, "locks"),
+        packageRoot: options.packageRoot,
+    });
+    assertActiveManifestRun(ledger, manifest);
+    const snapshot = snapshotFor(manifest, options.ticket.record_id);
+    assertTicketMatchesAdmission(options.ticket, snapshot, manifest);
+    const gate = Object.freeze({
+        [RUN_TICKET_ADMISSION]: true,
+        run_id: manifest.run_id,
+        ticket_id: options.ticket.record_id,
+        manifest_id: manifest.manifest_id,
+    });
+    RUN_TICKET_ADMISSIONS.add(gate);
+    return gate;
+}
+export function findActiveRunTicketAdmission(options) {
+    const root = openStableDirectory(join(options.stateRoot, "run-manifests"), "run manifests root");
+    let runIds;
+    try {
+        runIds = Object.freeze(readdirSync(root.path, { withFileTypes: true }).map((entry) => {
+            if (!entry.isFile() || !/^run-[a-f0-9]{48}\.json$/.test(entry.name)) {
+                throw new Error(`unsafe run manifest entry: ${entry.name}`);
+            }
+            return entry.name.slice(0, -5);
+        }).sort(compareText));
+        root.assertUnchanged();
+    }
+    finally {
+        root.close();
+    }
+    const ledger = createLiveRunLedger({
+        ledgerRoot: join(options.stateRoot, "audit"),
+        locksRoot: join(options.stateRoot, "locks"),
+        packageRoot: options.packageRoot,
+    });
+    const active = runIds.filter((runId) => {
+        const manifest = readRunManifest(options.packageRoot, options.stateRoot, runId);
+        if (!manifest.selected_ticket_ids.includes(options.ticket.record_id))
+            return false;
+        const head = ledger.head(runId);
+        if (!head)
+            throw new Error(`run manifest has no audit ledger: ${runId}`);
+        return ledger.deriveMetrics(head).status === "running";
+    });
+    if (active.length > 1)
+        throw new Error(`ticket belongs to multiple active audit runs: ${options.ticket.record_id}`);
+    const runId = active[0];
+    return runId === undefined ? null : assertRunTicketAdmission({ ...options, runId });
+}
+export function assertRunCurrentAuthority(manifest, configRoot) {
+    const policyDigest = loadTrackedRolePolicyGate(configRoot).digest;
+    const verificationGateDigest = freezeTrackedVerificationPlan(configRoot).digest;
+    if (manifest.policy_digest !== policyDigest || manifest.verification_gate_digest !== verificationGateDigest) {
+        throw new Error(`audit run authority is stale under the current policy or verification gate: ${manifest.run_id}`);
+    }
+}
+export function assertRunTicketAdmissionGate(value) {
+    if (typeof value !== "object" || value === null || !RUN_TICKET_ADMISSIONS.has(value)) {
+        throw new Error("run-bound ticket work requires a real OMS admission gate");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("run ticket admission gate lost its boundary");
+}
+/**
+ * Appends one audit-only event while preserving process continuity across
+ * short-lived CLI invocations. The head compare-and-swap keeps a restart
+ * marker adjacent to the first event from its process.
+ */
+export function appendRunAuditEvent(ledger, input) {
+    const rawEntryKind = input.entryKind;
+    if (rawEntryKind === "process-restarted" || rawEntryKind === "run-completed" || rawEntryKind === "run-aborted") {
+        throw new Error("run process continuity and terminal entries are controller-managed");
+    }
+    const processInstanceId = currentProcessInstanceId();
+    for (let attempt = 0; attempt < 64; attempt += 1) {
+        let head = ledger.head(input.runId);
+        if (!head)
+            throw new Error(`audit run does not exist: ${input.runId}`);
+        let entry = ledger.read(head);
+        if (entry.process_instance_id !== processInstanceId) {
+            try {
+                ledger.appendAtHead({
+                    runId: input.runId,
+                    operationId: createStableId("run-process", input.runId, processInstanceId, head.sha256, input.operationId),
+                    entryKind: "process-restarted",
+                    payload: {
+                        previous_process_instance_id: entry.process_instance_id,
+                        next_operation_id: input.operationId,
+                    },
+                    expectedHeadSha256: head.sha256,
+                });
+            }
+            catch (error) {
+                if (isHeadRace(error))
+                    continue;
+                throw error;
+            }
+        }
+        head = ledger.head(input.runId);
+        if (!head)
+            throw new Error(`audit run does not exist: ${input.runId}`);
+        entry = ledger.read(head);
+        if (entry.process_instance_id !== processInstanceId)
+            continue;
+        try {
+            return ledger.appendAtHead({ ...input, expectedHeadSha256: head.sha256 });
+        }
+        catch (error) {
+            if (isHeadRace(error))
+                continue;
+            throw error;
+        }
+    }
+    throw new Error(`run audit head remained contended: ${input.runId}`);
+}
+function appendRunTerminalEvent(ledger, writer, input) {
+    const processInstanceId = currentProcessInstanceId();
+    for (let attempt = 0; attempt < 64; attempt += 1) {
+        let head = ledger.head(input.runId);
+        if (!head)
+            throw new Error(`audit run does not exist: ${input.runId}`);
+        let entry = ledger.read(head);
+        if (entry.process_instance_id !== processInstanceId) {
+            appendRunAuditEvent(ledger, {
+                runId: input.runId,
+                operationId: createStableId("run-term-bound", input.operationId, String(attempt)),
+                entryKind: "heartbeat",
+                payload: { terminal_operation_id: input.operationId },
+            });
+        }
+        head = ledger.head(input.runId);
+        if (!head)
+            throw new Error(`audit run does not exist: ${input.runId}`);
+        entry = ledger.read(head);
+        if (entry.process_instance_id !== processInstanceId)
+            continue;
+        try {
+            return writer.appendAtHead({ ...input, expectedHeadSha256: head.sha256 });
+        }
+        catch (error) {
+            if (isHeadRace(error))
+                continue;
+            throw error;
+        }
+    }
+    throw new Error(`run terminal head remained contended: ${input.runId}`);
+}
+export function readRunManifest(packageRoot, stateRoot, runId) {
+    if (!/^run-[a-f0-9]{48}$/.test(runId))
+        throw new Error("invalid audit run id");
+    const manifest = readControlJson(join(stateRoot, "run-manifests"), `${runId}.json`, "run manifests root", (value) => parseManifest(value, packageRoot));
+    if (manifest.run_id !== runId || manifest.state_root !== stateRoot)
+        throw new Error("run manifest identity mismatch");
+    const intent = readStartIntent(packageRoot, stateRoot, manifest.start_intent_id);
+    if (!manifestMatchesIntent(manifest, intent))
+        throw new Error("run manifest does not match its immutable start intent");
+    verifyPersistedServicePlan({
+        packageRoot,
+        directory: manifest.service_plan_directory,
+        expectedDigest: manifest.service_plan_digest,
+        stateRoot: manifest.state_root,
+        workspaceRoot: manifest.workspace_root,
+        executablePath: intent.executable_path,
+        manager: intent.manager,
+    });
+    return manifest;
+}
+function createStartIntent(options) {
+    const generated = generateServicePlan({
+        manager: options.manager,
+        executablePath: options.executablePath,
+        stateRoot: options.stateRoot,
+        workspaceRoot: options.workspaceRoot,
+        packageRoot: options.packageRoot,
+    });
+    const persisted = persistServicePlan({ generated, outputRoot: join(options.stateRoot, "service-plans") });
+    const ticketSnapshot = captureTicketSnapshot(options.tickets);
+    const ticketSetDigest = sha256(JSON.stringify(ticketSnapshot));
+    const verificationGateDigest = freezeTrackedVerificationPlan(options.configRoot).digest;
+    const startNonce = randomUUID().toLowerCase();
+    const operationId = createStableId("run-start", startNonce, options.runKind, options.policyDigest, verificationGateDigest, ticketSetDigest, generated.digest);
+    const intent = parseStartIntent({
+        schema_version: 1,
+        intent_id: createStableId("run-intent", operationId),
+        operation_id: operationId,
+        start_nonce: startNonce,
+        expected_run_id: createStableId("run", operationId),
+        run_kind: options.runKind,
+        manager: options.manager,
+        executable_path: options.executablePath,
+        created_at: systemClockSample().wallTime,
+        policy_digest: options.policyDigest,
+        verification_gate_digest: verificationGateDigest,
+        ticket_set_digest: ticketSetDigest,
+        service_plan_digest: generated.digest,
+        service_plan_directory: persisted.directory,
+        state_root: options.stateRoot,
+        workspace_root: options.workspaceRoot,
+        ticket_snapshot: ticketSnapshot,
+    }, options.packageRoot);
+    writeControlFile(join(options.stateRoot, "run-start-intents"), `${intent.intent_id}.json`, canonicalBytes(intent), "run start intents root");
+    return readStartIntent(options.packageRoot, options.stateRoot, intent.intent_id);
+}
+function assertStartRequestMatches(intent, request, policyDigest, configRoot) {
+    if (intent.run_kind !== request.runKind
+        || intent.manager !== request.manager
+        || intent.executable_path !== request.executablePath
+        || intent.state_root !== request.stateRoot
+        || intent.workspace_root !== request.workspaceRoot) {
+        throw new Error(`another audit run is already active or has an outstanding start: ${intent.expected_run_id}`);
+    }
+    if (intent.policy_digest !== policyDigest || intent.verification_gate_digest !== freezeTrackedVerificationPlan(configRoot).digest) {
+        throw new Error("outstanding audit run intent belongs to stale policy");
+    }
+    return intent;
+}
+function listStartIntents(packageRoot, stateRoot) {
+    const root = openStableDirectory(join(stateRoot, "run-start-intents"), "run start intents root");
+    try {
+        const intents = readdirSync(root.path, { withFileTypes: true }).map((entry) => {
+            if (!entry.isFile() || !/^run-intent-[a-f0-9]{48}\.json$/.test(entry.name))
+                throw new Error(`unsafe run start intent entry: ${entry.name}`);
+            return parseStartIntent(JSON.parse(readImmutableFile(join(root.path, entry.name), MAX_CONTROL_BYTES).toString("utf8")), packageRoot);
+        }).sort((left, right) => compareText(left.intent_id, right.intent_id));
+        root.assertUnchanged();
+        return Object.freeze(intents);
+    }
+    finally {
+        root.close();
+    }
+}
+function outstandingStartIntents(ledger, intents) {
+    return intents.filter((intent) => {
+        const head = ledger.head(intent.expected_run_id);
+        return !head || ledger.deriveMetrics(head).status === "running";
+    });
+}
+function readStartIntent(packageRoot, stateRoot, intentId) {
+    if (!/^run-intent-[a-f0-9]{48}$/.test(intentId))
+        throw new Error("invalid run start intent id");
+    return readControlJson(join(stateRoot, "run-start-intents"), `${intentId}.json`, "run start intents root", (value) => parseStartIntent(value, packageRoot));
+}
+function parseStartIntent(value, packageRoot) {
+    assertSchema(value, loadJsonSchema(join(packageRoot, "schemas", "run-start-intent.schema.json")), "run start intent");
+    const intent = structuredClone(value);
+    validateTicketSnapshot(intent.ticket_snapshot, intent.ticket_set_digest);
+    const expectedOperationId = createStableId("run-start", intent.start_nonce, intent.run_kind, intent.policy_digest, intent.verification_gate_digest, intent.ticket_set_digest, intent.service_plan_digest);
+    if (intent.operation_id !== expectedOperationId
+        || intent.intent_id !== createStableId("run-intent", intent.operation_id)
+        || intent.expected_run_id !== createStableId("run", intent.operation_id))
+        throw new Error("run start intent identity is invalid");
+    if (basename(intent.service_plan_directory) !== intent.service_plan_digest)
+        throw new Error("run start intent service directory is invalid");
+    return deepFreeze(intent);
+}
+function manifestFromIntent(intent, createdAt) {
+    return deepFreeze({
+        schema_version: 1,
+        manifest_id: createStableId("manifest", intent.expected_run_id),
+        run_id: intent.expected_run_id,
+        run_kind: intent.run_kind,
+        start_intent_id: intent.intent_id,
+        created_at: createdAt,
+        policy_digest: intent.policy_digest,
+        verification_gate_digest: intent.verification_gate_digest,
+        ticket_set_digest: intent.ticket_set_digest,
+        service_plan_digest: intent.service_plan_digest,
+        service_plan_directory: intent.service_plan_directory,
+        state_root: intent.state_root,
+        workspace_root: intent.workspace_root,
+        selected_ticket_ids: intent.ticket_snapshot.map((ticket) => ticket.ticket_id),
+        ticket_snapshot: intent.ticket_snapshot,
+        provider_started: false,
+        manual_conductor_start_required: true,
+        certifying: false,
+        release: "not_stable",
+        merge_disposition: "human_hold",
+    });
+}
+function persistManifest(value, packageRoot, stateRoot) {
+    const manifest = parseManifest(value, packageRoot);
+    writeControlFile(join(stateRoot, "run-manifests"), `${manifest.run_id}.json`, canonicalBytes(manifest), "run manifests root");
+    return readRunManifest(packageRoot, stateRoot, manifest.run_id);
+}
+function parseManifest(value, packageRoot) {
+    assertSchema(value, loadJsonSchema(join(packageRoot, "schemas", "run-manifest.schema.json")), "run manifest");
+    const manifest = structuredClone(value);
+    if (manifest.manifest_id !== createStableId("manifest", manifest.run_id))
+        throw new Error("run manifest id is invalid");
+    validateTicketSnapshot(manifest.ticket_snapshot, manifest.ticket_set_digest);
+    if (manifest.selected_ticket_ids.join("\0") !== manifest.ticket_snapshot.map((ticket) => ticket.ticket_id).join("\0")) {
+        throw new Error("run manifest selected tickets do not match its admission snapshot");
+    }
+    if (basename(manifest.service_plan_directory) !== manifest.service_plan_digest)
+        throw new Error("run manifest service directory is invalid");
+    return deepFreeze(manifest);
+}
+function manifestMatchesIntent(manifest, intent) {
+    return manifest.run_id === intent.expected_run_id
+        && manifest.run_kind === intent.run_kind
+        && manifest.start_intent_id === intent.intent_id
+        && manifest.policy_digest === intent.policy_digest
+        && manifest.verification_gate_digest === intent.verification_gate_digest
+        && manifest.ticket_set_digest === intent.ticket_set_digest
+        && manifest.service_plan_digest === intent.service_plan_digest
+        && manifest.service_plan_directory === intent.service_plan_directory
+        && manifest.state_root === intent.state_root
+        && manifest.workspace_root === intent.workspace_root
+        && JSON.stringify(manifest.ticket_snapshot) === JSON.stringify(intent.ticket_snapshot);
+}
+function captureTicketSnapshot(tickets) {
+    return Object.freeze(tickets.filter((ticket) => ticket.state !== "completed").sort((left, right) => compareText(left.record_id, right.record_id)).map((ticket) => {
+        if (ticket.state === "completed")
+            throw new Error("completed ticket escaped run admission filtering");
+        return Object.freeze({
+            ticket_id: ticket.record_id,
+            initial_version: ticket.version,
+            initial_attempt: ticket.attempt,
+            initial_state: ticket.state,
+            source_ref_sha256: ticket.payload.source_ref_sha256,
+            content_sha256: ticket.payload.content_sha256,
+            policy_version: ticket.payload.policy_version,
+            policy_digest: ticket.payload.policy_digest,
+            gate_digest: ticket.payload.gate_digest,
+        });
+    }));
+}
+function validateTicketSnapshot(snapshot, expectedDigest) {
+    const ids = snapshot.map((ticket) => ticket.ticket_id);
+    if (ids.join("\0") !== [...ids].sort(compareText).join("\0") || new Set(ids).size !== ids.length) {
+        throw new Error("run ticket admissions must be sorted and unique");
+    }
+    if (sha256(JSON.stringify(snapshot)) !== expectedDigest)
+        throw new Error("run ticket admission digest is invalid");
+}
+function buildConductorRoute(tickets, manifest) {
+    const admitted = new Set(manifest.selected_ticket_ids);
+    const outside = tickets.filter((ticket) => ticket.state !== "completed" && !admitted.has(ticket.record_id))
+        .sort((left, right) => compareText(left.record_id, right.record_id))[0];
+    if (outside)
+        return routeForTicket(manifest, outside, "human-hold", "canonical queue contains an unresolved ticket outside the frozen run admission", false);
+    const unresolved = manifest.selected_ticket_ids.map((ticketId) => requiredTicket(tickets, ticketId))
+        .filter((ticket) => ticket.state !== "completed")
+        .sort((left, right) => compareText(left.record_id, right.record_id));
+    const ticket = unresolved[0];
+    if (!ticket)
+        return routeForEmpty(manifest);
+    const snapshot = snapshotFor(manifest, ticket.record_id);
+    try {
+        assertTicketMatchesAdmission(ticket, snapshot, manifest);
+    }
+    catch {
+        return routeForTicket(manifest, ticket, "human-hold", "ticket identity drifted from the frozen run admission", false);
+    }
+    const action = ticket.state === "blocked"
+        ? "human-hold"
+        : ticket.state === "parked"
+            ? "wait-resume"
+            : ticket.state === "pending" || ticket.state === "retryable"
+                ? "human-start-required"
+                : "await-native-hook";
+    const reason = action === "human-hold"
+        ? "ticket is blocked and requires operator review"
+        : action === "wait-resume"
+            ? "ticket is parked until its durable resume gate opens"
+            : action === "human-start-required"
+                ? "shipped provider roles require an explicit human start"
+                : "ticket is active; wait for its native hook or deterministic evidence";
+    return routeForTicket(manifest, ticket, action, reason, true);
+}
+function routeForTicket(manifest, ticket, action, reason, admitted) {
+    if (ticket.state === "completed")
+        throw new Error("completed ticket cannot produce a conductor route");
+    const decisionId = createStableId("decision", manifest.run_id, ticket.record_id, String(ticket.version), String(ticket.attempt), ticket.state, action, ticket.payload.content_sha256, ticket.payload.policy_digest, ticket.payload.gate_digest ?? "gate:null");
+    return deepFreeze({
+        schema_version: 1,
+        decision_id: decisionId,
+        operation_nonce: createStableId("route", decisionId),
+        run_id: manifest.run_id,
+        ticket_id: ticket.record_id,
+        ticket_version: ticket.version,
+        ticket_attempt: ticket.attempt,
+        ticket_state: ticket.state,
+        policy_digest: ticket.payload.policy_digest,
+        gate_digest: ticket.payload.gate_digest,
+        action,
+        eligible_role_ids: action === "human-start-required" ? ["oms.ticket-executor", "oms.goal-long-executor"] : [],
+        evidence_paths: admitted ? evidencePaths(manifest.state_root, ticket) : [],
+        manual_start_required: action === "human-start-required",
+        provider_started: false,
+        reason,
+    });
+}
+function routeForEmpty(manifest) {
+    const decisionId = createStableId("decision", manifest.run_id, "queue-empty", manifest.ticket_set_digest);
+    return deepFreeze({
+        schema_version: 1,
+        decision_id: decisionId,
+        operation_nonce: createStableId("route", decisionId),
+        run_id: manifest.run_id,
+        ticket_id: null,
+        ticket_version: null,
+        ticket_attempt: null,
+        ticket_state: null,
+        policy_digest: manifest.policy_digest,
+        gate_digest: null,
+        action: "queue-empty",
+        eligible_role_ids: [],
+        evidence_paths: [],
+        manual_start_required: false,
+        provider_started: false,
+        reason: "the canonical queue is empty for this run admission watermark",
+    });
+}
+function assertTicketMatchesAdmission(ticket, snapshot, manifest) {
+    const allowedGate = ticket.payload.gate_digest === snapshot.gate_digest
+        || (snapshot.gate_digest === null && ticket.payload.gate_digest === manifest.verification_gate_digest);
+    if (ticket.record_id !== snapshot.ticket_id
+        || ticket.version < snapshot.initial_version
+        || ticket.attempt < snapshot.initial_attempt
+        || ticket.payload.source_ref_sha256 !== snapshot.source_ref_sha256
+        || ticket.payload.content_sha256 !== snapshot.content_sha256
+        || ticket.payload.policy_version !== snapshot.policy_version
+        || ticket.payload.policy_digest !== snapshot.policy_digest
+        || ticket.payload.policy_digest !== manifest.policy_digest
+        || !allowedGate)
+        throw new Error("ticket no longer matches its run admission snapshot");
+}
+function projectTicketStates(ledger, manifest, tickets) {
+    for (const snapshot of manifest.ticket_snapshot) {
+        const ticket = requiredTicket(tickets, snapshot.ticket_id);
+        try {
+            assertTicketMatchesAdmission(ticket, snapshot, manifest);
+        }
+        catch {
+            continue;
+        }
+        appendRunAuditEvent(ledger, {
+            runId: manifest.run_id,
+            operationId: createStableId("run-ticket", ticket.record_id, String(ticket.version)),
+            entryKind: "ticket-transition",
+            payload: {
+                ticket_id: ticket.record_id,
+                version: ticket.version,
+                attempt: ticket.attempt,
+                state: ticket.state,
+                actor: ticket.actor,
+                lease_token: ticket.lease_token,
+                executor_evidence: ticket.payload.executor_evidence,
+                verification_evidence: ticket.payload.verification_evidence,
+                grade_evidence: ticket.payload.grade_evidence,
+            },
+        });
+    }
+}
+function recordControllerObservation(ledger, manifest, purpose) {
+    const sample = systemClockSample();
+    appendRunAuditEvent(ledger, {
+        runId: manifest.run_id,
+        operationId: createStableId("run-observe", manifest.run_id, purpose, currentProcessInstanceId(), sample.monotonicNs.toString()),
+        entryKind: "heartbeat",
+        payload: { manifest_id: manifest.manifest_id, purpose },
+    });
+}
+function completeAuditRun(runtime, manifest, mode, minimumDurationMs, packageRoot) {
+    const tickets = runtime.tickets.queue.list();
+    if (buildConductorRoute(tickets, manifest).action !== "queue-empty")
+        throw new Error("run cannot complete while the canonical queue is unresolved");
+    const proof = persistCompletionProof(buildCompletionProof(manifest, tickets), runtime.tickets.evidenceStore, manifest, packageRoot, tickets);
+    appendRunTerminalEvent(runtime.auditLedger, createAuditRunTerminalWriter(runtime.auditLedger), {
+        runId: manifest.run_id,
+        operationId: createStableId("run-complete", manifest.run_id, mode),
+        entryKind: "run-completed",
+        payload: {
+            manifest_id: manifest.manifest_id,
+            ticket_set_digest: manifest.ticket_set_digest,
+            completion_mode: mode,
+            minimum_duration_ms: minimumDurationMs,
+            completion_proof: proof,
+            queue_empty: true,
+            certifying: false,
+        },
+    });
+}
+function buildCompletionProof(manifest, queue) {
+    const selected = manifest.selected_ticket_ids.map((ticketId) => requiredTicket(queue, ticketId));
+    for (const ticket of selected) {
+        const snapshot = snapshotFor(manifest, ticket.record_id);
+        assertTicketMatchesAdmission(ticket, snapshot, manifest);
+        if (ticket.state !== "completed" || ticket.payload.verification_evidence === null || ticket.payload.grade_evidence === null) {
+            throw new Error(`run completion requires terminal deterministic and grader evidence: ${ticket.record_id}`);
+        }
+    }
+    const queueWatermark = queue.map((ticket) => ({
+        ticket_id: ticket.record_id,
+        version: ticket.version,
+        state: ticket.state,
+        content_sha256: ticket.payload.content_sha256,
+    })).sort((left, right) => compareText(left.ticket_id, right.ticket_id));
+    const tickets = selected.map((ticket) => ({
+        ticket_id: ticket.record_id,
+        version: ticket.version,
+        attempt: ticket.attempt,
+        verification_evidence: ticket.payload.verification_evidence,
+        grade_evidence: ticket.payload.grade_evidence,
+    }));
+    const completedAt = systemClockSample().wallTime;
+    const queueWatermarkSha256 = sha256(JSON.stringify(queueWatermark));
+    return deepFreeze({
+        schema_version: 1,
+        proof_id: createStableId("run-proof", manifest.run_id, manifest.ticket_set_digest, queueWatermarkSha256, JSON.stringify(tickets), completedAt),
+        run_id: manifest.run_id,
+        manifest_id: manifest.manifest_id,
+        completed_at: completedAt,
+        ticket_set_digest: manifest.ticket_set_digest,
+        queue_watermark_sha256: queueWatermarkSha256,
+        tickets,
+        certifying: false,
+    });
+}
+function persistCompletionProof(proofValue, evidenceStore, manifest, packageRoot, queue) {
+    const proof = parseCompletionProof(proofValue, manifest, evidenceStore, packageRoot, queue);
+    const bytes = canonicalBytes(proof);
+    const ref = Object.freeze({
+        proof_id: proof.proof_id,
+        sha256: sha256(bytes),
+        file_name: `${proof.proof_id}.json`,
+    });
+    writeControlFile(join(manifest.state_root, "run-completion-proofs"), ref.file_name, bytes, "run completion proofs root");
+    readCompletionProof(ref, manifest, evidenceStore, packageRoot, queue);
+    return ref;
+}
+function readCompletionProof(referenceValue, manifest, evidenceStore, packageRoot, queue) {
+    const reference = parseCompletionProofReference(referenceValue);
+    const bytes = readControlBytes(join(manifest.state_root, "run-completion-proofs"), reference.file_name, "run completion proofs root");
+    if (sha256(bytes) !== reference.sha256)
+        throw new Error("run completion proof digest mismatch");
+    const proof = parseCompletionProof(JSON.parse(bytes.toString("utf8")), manifest, evidenceStore, packageRoot, queue);
+    if (proof.proof_id !== reference.proof_id)
+        throw new Error("run completion proof identity mismatch");
+    return proof;
+}
+function parseCompletionProofReference(value) {
+    if (!isRecord(value))
+        throw new Error("run completion proof reference must be an object");
+    assertExactKeys(value, ["proof_id", "sha256", "file_name"], "run completion proof reference");
+    if (typeof value.proof_id !== "string"
+        || !/^run-proof-[a-f0-9]{48}$/.test(value.proof_id)
+        || typeof value.sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(value.sha256)
+        || value.file_name !== `${value.proof_id}.json`) {
+        throw new Error("run completion proof reference identity is invalid");
+    }
+    return Object.freeze({
+        proof_id: value.proof_id,
+        sha256: value.sha256,
+        file_name: value.file_name,
+    });
+}
+function parseCompletionProof(value, manifest, evidenceStore, packageRoot, queue) {
+    assertSchema(value, loadJsonSchema(join(packageRoot, "schemas", "run-completion-proof.schema.json")), "run completion proof");
+    const proof = structuredClone(value);
+    if (proof.run_id !== manifest.run_id || proof.manifest_id !== manifest.manifest_id || proof.ticket_set_digest !== manifest.ticket_set_digest) {
+        throw new Error("run completion proof belongs to a different manifest");
+    }
+    if (proof.tickets.map((ticket) => ticket.ticket_id).join("\0") !== manifest.selected_ticket_ids.join("\0")) {
+        throw new Error("run completion proof ticket set is invalid");
+    }
+    const expectedId = createStableId("run-proof", manifest.run_id, manifest.ticket_set_digest, proof.queue_watermark_sha256, JSON.stringify(proof.tickets), proof.completed_at);
+    if (proof.proof_id !== expectedId)
+        throw new Error("run completion proof id is invalid");
+    assertCompletionProofMatchesQueue(proof, manifest, queue, evidenceStore);
+    return deepFreeze(proof);
+}
+function assertCompletionProofMatchesQueue(proof, manifest, queue, evidenceStore) {
+    const queueWatermark = queue.map((ticket) => ({
+        ticket_id: ticket.record_id,
+        version: ticket.version,
+        state: ticket.state,
+        content_sha256: ticket.payload.content_sha256,
+    })).sort((left, right) => compareText(left.ticket_id, right.ticket_id));
+    if (proof.queue_watermark_sha256 !== sha256(JSON.stringify(queueWatermark))) {
+        throw new Error("run completion proof queue watermark is stale");
+    }
+    for (const proofTicket of proof.tickets) {
+        const ticket = requiredTicket(queue, proofTicket.ticket_id);
+        if (ticket.state !== "completed"
+            || ticket.version !== proofTicket.version
+            || ticket.attempt !== proofTicket.attempt
+            || ticket.payload.verification_evidence === null
+            || ticket.payload.grade_evidence === null
+            || !sameEvidenceReference(ticket.payload.verification_evidence, proofTicket.verification_evidence)
+            || !sameEvidenceReference(ticket.payload.grade_evidence, proofTicket.grade_evidence)) {
+            throw new Error(`run completion proof ticket is not the canonical completed record: ${ticket.record_id}`);
+        }
+        const verification = evidenceStore.read(ticket.payload.verification_evidence);
+        const grade = evidenceStore.read(ticket.payload.grade_evidence);
+        const attemptLease = [...ticket.transition_outcomes].reverse()
+            .find((outcome) => outcome.attempt === ticket.attempt && outcome.lease_token !== null)?.lease_token;
+        if (attemptLease === undefined
+            || verification.evidence_kind !== "deterministic-check"
+            || verification.ticket_id !== ticket.record_id
+            || verification.producer_role !== "oms.verifier"
+            || verification.payload.certification !== "non-certifying"
+            || verification.payload.passed !== true
+            || verification.payload.attempt !== ticket.attempt
+            || verification.payload.lease_token !== attemptLease
+            || verification.payload.policy_version !== ticket.payload.policy_version
+            || verification.payload.policy_digest !== ticket.payload.policy_digest
+            || verification.payload.plan_digest !== ticket.payload.gate_digest) {
+            throw new Error(`run completion proof deterministic verdict is invalid: ${ticket.record_id}`);
+        }
+        const executor = ticket.payload.executor_evidence === null
+            ? null
+            : evidenceStore.read(ticket.payload.executor_evidence);
+        const expectedGrader = executor?.evidence_kind === "goal-executor-result"
+            ? "oms.grader.claude"
+            : "oms.grader.codex";
+        if (executor === null
+            || grade.evidence_kind !== "grader-output"
+            || grade.ticket_id !== ticket.record_id
+            || grade.producer_role !== expectedGrader
+            || grade.payload.verdict !== "pass"
+            || !sameEvidenceReference(grade.payload.deterministic_evidence, ticket.payload.verification_evidence)) {
+            throw new Error(`run completion proof grader verdict is invalid: ${ticket.record_id}`);
+        }
+    }
+    if (proof.tickets.map((ticket) => ticket.ticket_id).join("\0") !== manifest.selected_ticket_ids.join("\0")) {
+        throw new Error("run completion proof no longer matches the admitted ticket set");
+    }
+}
+function sameEvidenceReference(left, right) {
+    return left !== null
+        && right !== null
+        && left.evidence_id === right.evidence_id
+        && left.sha256 === right.sha256
+        && left.file_name === right.file_name;
+}
+function validateTerminal(runtime, manifest, metrics, packageRoot) {
+    if (metrics.status === "running")
+        return;
+    const terminal = runtime.auditLedger.list(manifest.run_id).at(-1);
+    if (!terminal)
+        throw new Error("terminal audit run has no terminal entry");
+    if (terminal.entry_kind === "run-completed") {
+        assertExactKeys(terminal.payload, [
+            "manifest_id",
+            "ticket_set_digest",
+            "completion_mode",
+            "minimum_duration_ms",
+            "completion_proof",
+            "queue_empty",
+            "certifying",
+        ], "run completion payload");
+        if (terminal.payload.manifest_id !== manifest.manifest_id
+            || terminal.payload.ticket_set_digest !== manifest.ticket_set_digest
+            || terminal.payload.queue_empty !== true
+            || terminal.payload.certifying !== false)
+            throw new Error("run completion payload is not controller-authorized");
+        const mode = terminal.payload.completion_mode;
+        const minimum = terminal.payload.minimum_duration_ms;
+        if (typeof minimum !== "number" || !Number.isSafeInteger(minimum) || minimum < 0) {
+            throw new Error("run completion minimum duration is invalid");
+        }
+        if ((mode === "until-empty" && (manifest.run_kind !== "until-empty" || minimum !== 0))
+            || (mode === "elapsed" && (manifest.run_kind === "until-empty" || minimum !== (manifest.run_kind === "12h" ? TWELVE_HOURS_MS : TWENTY_FOUR_HOURS_MS))))
+            throw new Error("run completion mode does not match the manifest");
+        if (mode === "until-empty" && buildConductorRoute(runtime.tickets.queue.list(), manifest).action !== "queue-empty") {
+            throw new Error("terminal until-empty run no longer has an empty canonical queue");
+        }
+        if (mode === "elapsed"
+            && (metrics.elapsed_ms < minimum || metrics.monotonic_elapsed_ms < minimum)) {
+            throw new Error("terminal elapsed run does not satisfy its minimum duration");
+        }
+        readCompletionProof(terminal.payload.completion_proof, manifest, runtime.tickets.evidenceStore, packageRoot, runtime.tickets.queue.list());
+        return;
+    }
+    if (terminal.entry_kind !== "run-aborted")
+        throw new Error("run terminal entry is not controller-authorized");
+    assertExactKeys(terminal.payload, ["manifest_id", "reason_sha256", "reason_file", "certifying"], "run abort payload");
+    if (terminal.payload.manifest_id !== manifest.manifest_id || terminal.payload.certifying !== false) {
+        throw new Error("run abort payload is not controller-authorized");
+    }
+    const bytes = readControlBytes(join(manifest.state_root, "run-aborts"), String(terminal.payload.reason_file), "run aborts root");
+    if (sha256(bytes) !== terminal.payload.reason_sha256)
+        throw new Error("run abort reason digest mismatch");
+}
+function buildStatus(tickets, manifest, metrics) {
+    const selected = manifest.selected_ticket_ids.map((ticketId) => requiredTicket(tickets, ticketId));
+    const counts = {};
+    for (const ticket of selected)
+        counts[ticket.state] = (counts[ticket.state] ?? 0) + 1;
+    return deepFreeze({
+        manifest,
+        audit: metrics,
+        ticket_counts: Object.fromEntries(Object.entries(counts).sort(([left], [right]) => compareText(left, right))),
+        provider_started: false,
+        certifying: false,
+        release: "not_stable",
+        human_hold: true,
+        next_action: nextAction(tickets, manifest, metrics),
+    });
+}
+function nextAction(tickets, manifest, metrics) {
+    if (metrics.status !== "running")
+        return "none";
+    const action = buildConductorRoute(tickets, manifest).action;
+    if (action === "human-hold")
+        return "human-hold";
+    if (action === "wait-resume")
+        return "wait-resume";
+    if (action === "await-native-hook")
+        return "await-native-hook";
+    if (action === "human-start-required")
+        return "manual-conductor";
+    return manifest.run_kind === "until-empty" ? "run-tick" : "observe";
+}
+function currentMetrics(ledger, manifest) {
+    const head = ledger.head(manifest.run_id);
+    if (!head)
+        throw new Error(`audit run does not exist: ${manifest.run_id}`);
+    assertRunManifestLedgerBinding(ledger, manifest);
+    return ledger.deriveMetrics(head);
+}
+function assertActiveManifestRun(ledger, manifest) {
+    if (currentMetrics(ledger, manifest).status !== "running")
+        throw new Error(`conductor cannot route a terminal run: ${manifest.run_id}`);
+}
+export function assertRunManifestLedgerBinding(ledger, manifest) {
+    const first = ledger.list(manifest.run_id)[0];
+    if (!first
+        || first.entry_kind !== "run-started"
+        || first.provenance_class !== "audit"
+        || first.run_kind !== manifest.run_kind
+        || first.policy_sha256 !== manifest.policy_digest
+        || first.payload.ticket_set_digest !== manifest.ticket_set_digest
+        || first.payload.service_plan_digest !== manifest.service_plan_digest)
+        throw new Error("run manifest does not match its audit ledger authority");
+}
+function persistDecision(value, packageRoot, stateRoot) {
+    const decision = parseDecision(value, packageRoot);
+    const bytes = canonicalBytes(decision);
+    const fileName = `${decision.decision_id}.json`;
+    const status = writeControlFile(join(stateRoot, "run-decisions"), fileName, bytes, "run decisions root");
+    const stored = readControlJson(join(stateRoot, "run-decisions"), fileName, "run decisions root", (input) => parseDecision(input, packageRoot));
+    return Object.freeze({ status, decision: stored, absolute_path: join(stateRoot, "run-decisions", fileName) });
+}
+function parseDecision(value, packageRoot) {
+    assertSchema(value, loadJsonSchema(join(packageRoot, "schemas", "conductor-route.schema.json")), "conductor route");
+    const decision = structuredClone(value);
+    if (decision.operation_nonce !== createStableId("route", decision.decision_id))
+        throw new Error("conductor route nonce is invalid");
+    const empty = decision.action === "queue-empty";
+    if (empty !== (decision.ticket_id === null && decision.ticket_version === null && decision.ticket_attempt === null && decision.ticket_state === null)) {
+        throw new Error("conductor route ticket identity is inconsistent");
+    }
+    if (decision.manual_start_required !== (decision.action === "human-start-required"))
+        throw new Error("conductor route manual-start flag is inconsistent");
+    if (new Set(decision.eligible_role_ids).size !== decision.eligible_role_ids.length || new Set(decision.evidence_paths).size !== decision.evidence_paths.length) {
+        throw new Error("conductor route arrays must be unique");
+    }
+    return deepFreeze(decision);
+}
+function evidencePaths(stateRoot, ticket) {
+    const paths = [join(stateRoot, "tickets", ticket.payload.content_file)];
+    for (const reference of [ticket.payload.verification_plan_ref, ticket.payload.executor_evidence, ticket.payload.verification_evidence, ticket.payload.grade_evidence]) {
+        if (reference)
+            paths.push(join(stateRoot, "evidence", reference.file_name));
+    }
+    return Object.freeze([...new Set(paths)].sort(compareText));
+}
+function snapshotFor(manifest, ticketId) {
+    const snapshot = manifest.ticket_snapshot.find((ticket) => ticket.ticket_id === ticketId);
+    if (!snapshot)
+        throw new Error(`ticket is not admitted to run: ${ticketId}`);
+    return snapshot;
+}
+function requiredTicket(tickets, ticketId) {
+    const ticket = tickets.find((candidate) => candidate.record_id === ticketId);
+    if (!ticket)
+        throw new Error(`run admission ticket is missing: ${ticketId}`);
+    return ticket;
+}
+function readControlJson(rootPath, fileName, label, parse) {
+    return parse(JSON.parse(readControlBytes(rootPath, fileName, label).toString("utf8")));
+}
+function readControlBytes(rootPath, fileName, label) {
+    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(fileName))
+        throw new Error(`unsafe ${label} file name`);
+    const root = openStableDirectory(rootPath, label);
+    try {
+        const path = join(root.path, fileName);
+        assertFileInside(root, path);
+        const bytes = readImmutableFile(path, MAX_CONTROL_BYTES);
+        root.assertUnchanged();
+        return bytes;
+    }
+    finally {
+        root.close();
+    }
+}
+function writeControlFile(rootPath, fileName, bytes, label) {
+    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(fileName))
+        throw new Error(`unsafe ${label} file name`);
+    const root = openStableDirectory(rootPath, label);
+    try {
+        const path = join(root.path, fileName);
+        assertFileInside(root, path);
+        const status = writeImmutableFile(path, bytes);
+        root.assertUnchanged();
+        return status;
+    }
+    finally {
+        root.close();
+    }
+}
+export function withRunControllerAuthority(stateRoot, operation) {
+    if (typeof operation !== "function")
+        throw new Error("run controller operation must be a function");
+    const runtimeStateRoot = validateExistingDirectory(stateRoot, "runtime state root");
+    const lock = acquireDirectoryLock({
+        locksRoot: join(runtimeStateRoot, "locks"),
+        lockId: "run-controller",
+        ownerId: "oms-run-controller",
+        note: "serialize run start, terminal proof, and abort authority",
+    });
+    try {
+        return operation();
+    }
+    finally {
+        lock.release();
+    }
+}
+function boundedReason(value) {
+    if (typeof value !== "string")
+        throw new Error("run abort reason must be text");
+    const normalized = value.trim();
+    if (normalized.length < 1 || normalized.length > 4096)
+        throw new Error("run abort reason must contain 1 to 4096 characters");
+    return normalized;
+}
+function boundedRecoveryReason(value) {
+    const reason = boundedReason(value);
+    if (reason.length > 512)
+        throw new Error("run controller recovery reason must contain 1 to 512 characters");
+    return reason;
+}
+function assertExactKeys(value, keys, label) {
+    const expected = [...keys].sort(compareText);
+    const actual = Object.keys(value).sort(compareText);
+    if (actual.join("\0") !== expected.join("\0"))
+        throw new Error(`${label} fields are invalid`);
+}
+function isHeadRace(error) {
+    return error instanceof Error && error.message === "run ledger trusted head advanced concurrently";
+}
+function canonicalBytes(value) {
+    return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function deepFreeze(value, seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=controller.js.map