@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/lib/runner/job.js

@@ -0,0 +1,463 @@
+/**
+ * One served-phase job, claim to outcome (ruling 34.12; Doors W-L13, W3.11 and W4.4).
+ *
+ * attest → claim (needs_key retry) → register the spawn → hello → heartbeats → served bundle
+ * (verified, bound to this claim) → job read (contract bytes bound to the claim's seal) → repo →
+ * phases through the runner's own proxy → PR → release. Every Mnemom error maps to one of S1's
+ * refused reasons and fails closed; under --fail-mode open, only bundle_unavailable,
+ * job_unavailable and api_unavailable are ridden through, and only once a verified bundle is held
+ * (34.12 (2)). A bundle that fails verification stops the job in every mode.
+ *
+ * Every side effect is in `JobDeps`, so each arm is tested; `liveJobDeps` (commands/agent-run.ts)
+ * is the thin driver.
+ */
+import { RUNNER_OPEN_MODE_TOLERATED, claimNeedsKeyRetry, } from "../../vendor/durable-contract/index.js";
+import { canonicalJson } from "../canonical-json.js";
+import { verifyServedPhaseBundle } from "./bundle.js";
+import { sealedContractHeader } from "./contract-header.js";
+import { errorCode, errorDetails } from "./executor-client.js";
+import { doneOutcome, failedOutcome, phaseReason, refusedOutcome, } from "./outcome.js";
+import { planPhase } from "./phases.js";
+import { resolveMergeStrategy } from "./settings.js";
+const TOLERATED = RUNNER_OPEN_MODE_TOLERATED;
+const OPEN_MODE_RETRIES = 3;
+const POOL_SKIP_INELIGIBLE = new Set(["waiting", "not_pool_member"]);
+/** A3's executor auth rejections, on whichever executor route comes first (34.12 (8), (10)). */
+export function authRefusal(r) {
+    if (r.status === 401 && r.code === "durable_key_revoked")
+        return "executor_revoked";
+    if (r.status === 401 && r.code === "unauthorized")
+        return "executor_unauthorized";
+    if (r.status === 403 && r.code === "executor_key_required")
+        return "executor_unauthorized";
+    return null;
+}
+/** Any other executor route failing: auth first, then api_unavailable. */
+function routeRefusal(r) {
+    return (authRefusal(r) ??
+        (r.status === 409 && r.code === "durable_lease_fenced" ? "lease_lost" : "api_unavailable"));
+}
+/** A post-claim read: the bundle fetch with the lease key, the job read with the executor key. */
+function leaseReadRefusal(r, unavailable) {
+    if (r.status === 200)
+        return null;
+    if (r.status === 401 || r.status === 403)
+        return "lease_lost";
+    return unavailable;
+}
+const ok2xx = (r) => r.status >= 200 && r.status < 300;
+const num = (v) => (Number.isSafeInteger(v) ? v : null);
+const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+async function claimSession(deps, sessionId) {
+    const at = await deps.api.attest(sessionId, deps.nonce);
+    const atRefusal = authRefusal(at);
+    if (atRefusal)
+        return { kind: "refused", reason: atRefusal, detail: `attest: ${at.code}` };
+    if (at.status === 0 || at.status >= 500) {
+        return {
+            kind: "refused",
+            reason: "api_unavailable",
+            detail: `attest: ${at.networkError ?? at.status}`,
+        };
+    }
+    // A 404 attest is a session this executor cannot see (taken, or not its org's): try the next.
+    if (at.status === 404)
+        return { kind: "next" };
+    const body = { nonce: deps.nonce };
+    let r = await deps.api.claim(sessionId, body);
+    const retry = claimNeedsKeyRetry(body, r.code, false);
+    if (retry)
+        r = await deps.api.claim(sessionId, retry);
+    const auth = authRefusal(r);
+    if (auth)
+        return { kind: "refused", reason: auth, detail: `claim: ${r.code}` };
+    if (r.status === 0)
+        return { kind: "refused", reason: "api_unavailable", detail: `claim: ${r.networkError}` };
+    if (r.status === 503 && r.code === "executor_lookup_unavailable") {
+        return {
+            kind: "refused",
+            reason: "api_unavailable",
+            detail: "claim: executor lookup unavailable",
+        };
+    }
+    const outcome = r.body?.outcome;
+    if (r.status === 409 && (outcome === "lost_race" || r.code === "durable_claim_lost_race"))
+        return { kind: "next" };
+    if (r.status === 403 && (outcome === "ineligible" || r.code === "durable_claim_ineligible")) {
+        const reason = String(errorDetails(r.body).reason ?? "");
+        if (POOL_SKIP_INELIGIBLE.has(reason))
+            return { kind: "next" };
+        return {
+            kind: "refused",
+            reason: "claim_ineligible",
+            detail: `claim ineligible: ${reason || "?"}`,
+        };
+    }
+    if (r.status === 409 && r.code === "durable_claim_needs_key") {
+        return {
+            kind: "refused",
+            reason: "claim_needs_key",
+            detail: "claim still needs a key after new_key",
+        };
+    }
+    if (r.status !== 200) {
+        const cause = errorDetails(r.body).cause;
+        return {
+            kind: "refused",
+            reason: "claim_unavailable",
+            detail: `claim: ${r.code ?? r.status} ${cause ?? ""}`.trim(),
+        };
+    }
+    const b = (r.body ?? {});
+    const epoch = num(b.epoch);
+    const leaseKey = str(b.lease_key);
+    const sha = str(b.contract_sha256);
+    const version = num(b.contract_version);
+    if (epoch === null || leaseKey === null || sha === null || version === null) {
+        // A pool claim always answers its contract; a homed one, or one with no lease key, is not a job.
+        return {
+            kind: "refused",
+            reason: "claim_unavailable",
+            detail: "claim answer has no lease key or contract",
+        };
+    }
+    return {
+        kind: "claimed",
+        claim: {
+            epoch,
+            leaseKey,
+            leaseSeconds: num(b.lease_seconds) ?? 60,
+            contractSha256: sha,
+            contractVersion: version,
+            executorId: str(b.executor_id),
+        },
+    };
+}
+function parseJob(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const b = body;
+    const repo = str(b.repo);
+    const sha = str(b.contract_sha256);
+    const version = num(b.version);
+    if (repo === null || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo))
+        return null;
+    // owner/name only: a dot-only segment ("..") would walk out of the workspace root.
+    if (repo.split("/").some((seg) => /^\.+$/.test(seg)))
+        return null;
+    if (sha === null || version === null || typeof b.contract !== "string")
+        return null;
+    return { repo, contract_sha256: sha, version, contract: b.contract };
+}
+/**
+ * Run one candidate session to an outcome. Never throws for a Mnemom error: every one is an
+ * outcome. Throws only on a runner bug.
+ */
+export async function runJob(sessionId, opts, deps) {
+    const facts = {};
+    const claimed = await claimSession(deps, sessionId);
+    if (claimed.kind === "next")
+        return claimed;
+    if (claimed.kind === "refused") {
+        deps.log(`refused: ${claimed.detail}`);
+        return { kind: "outcome", outcome: refusedOutcome(facts, claimed.reason) };
+    }
+    const claim = claimed.claim;
+    Object.assign(facts, {
+        session_id: sessionId,
+        lease_epoch: claim.epoch,
+        contract_sha256: claim.contractSha256,
+        contract_version: claim.contractVersion,
+    });
+    let bundleHeld = false;
+    let leaseLost = false;
+    let ws = null;
+    let proxy = null;
+    let heartbeat = null;
+    const phaseAbort = new AbortController();
+    const onStop = () => phaseAbort.abort();
+    opts.stop.addEventListener("abort", onStop);
+    const spawnId = deps.newSpawnId();
+    const tolerated = (reason) => opts.failMode === "open" && bundleHeld && TOLERATED.includes(reason);
+    // A stop or a fenced lease is honoured between every step, not only between phases.
+    const interrupted = async () => {
+        if (opts.stop.aborted)
+            return await stopJob(deps, sessionId, claim.epoch);
+        if (leaseLost)
+            return await refuse("lease_lost", "the lease was fenced mid-job");
+        return null;
+    };
+    const refuse = async (reason, detail) => {
+        deps.log(`refused (${reason}): ${detail}`);
+        await reportFail(deps, sessionId, claim.epoch, "runner_refused", reason);
+        return { kind: "outcome", outcome: refusedOutcome(facts, reason) };
+    };
+    try {
+        // Register the spawn, then hello: the session moves to running and the lease is ours.
+        const ap = await deps.api.append(sessionId, {
+            kind: "executor.spawned",
+            detail: { spawn_id: spawnId },
+            expected_epoch: claim.epoch,
+        });
+        if (!ok2xx(ap))
+            return await refuse(routeRefusal(ap), `register spawn: ${ap.code ?? ap.status}`);
+        const hello = await deps.api.hello(sessionId, {
+            epoch: claim.epoch,
+            nonce: deps.nonce,
+            spawn_id: spawnId,
+        });
+        if (!ok2xx(hello))
+            return await refuse(routeRefusal(hello), `hello: ${hello.code ?? hello.status}`);
+        const periodMs = Math.max(1, Math.floor(claim.leaseSeconds / 3)) * 1000;
+        heartbeat = setInterval(() => {
+            void deps.api
+                .heartbeat({
+                nonce: deps.nonce,
+                entries: [{ session_id: sessionId, epoch: claim.epoch, spawn_id: spawnId }],
+            })
+                .then((r) => {
+                const res = r.body
+                    ?.results?.[0];
+                if (r.status === 200 && res && res.extended === false) {
+                    leaseLost = true;
+                    deps.log(`heartbeat: lease not extended (${String(res.reason)})`);
+                    phaseAbort.abort();
+                }
+                else if (r.status !== 200 && !tolerated("api_unavailable")) {
+                    leaseLost = true;
+                    deps.log(`heartbeat failed: ${r.code ?? r.networkError ?? r.status}`);
+                    phaseAbort.abort();
+                }
+            });
+        }, periodMs);
+        // The served bundle: fetched per claim with the lease key, verified, bound to this claim.
+        const fetched = await fetchBundle(deps, sessionId, claim);
+        if (fetched.kind === "refused")
+            return await refuse(fetched.reason, fetched.detail);
+        const bundle = fetched.bundle;
+        bundleHeld = true;
+        facts.merge_strategy = resolveMergeStrategy(bundle);
+        const afterBundle = await interrupted();
+        if (afterBundle)
+            return afterBundle;
+        // The job and its contract bytes, bound to the claim's seal.
+        let job = null;
+        for (let attempt = 0;; attempt++) {
+            const jr = await deps.api.job(sessionId);
+            // The executor key's own rejection first; any other 401/403 is the lease.
+            const refusal = authRefusal(jr) ?? leaseReadRefusal(jr, "job_unavailable");
+            if (!refusal) {
+                job = parseJob(jr.body);
+                if (!job)
+                    return await refuse("job_unavailable", "job read answered an unreadable job");
+                break;
+            }
+            if (!tolerated(refusal) || attempt >= OPEN_MODE_RETRIES) {
+                return await refuse(refusal, `job read: ${jr.code ?? jr.networkError ?? jr.status}`);
+            }
+            deps.log(`job read: ${refusal}, retrying (fail mode open)`);
+            await deps.sleep(1000 * 2 ** attempt);
+            const afterSleep = await interrupted();
+            if (afterSleep)
+                return afterSleep;
+        }
+        if (job.contract_sha256 !== claim.contractSha256 || job.version !== claim.contractVersion) {
+            return await refuse("contract_sha_mismatch", "the job's contract is not the claim's seal");
+        }
+        const header = sealedContractHeader(Buffer.from(job.contract, "utf8"), claim.contractSha256);
+        if (!header.ok)
+            return await refuse(`contract_${header.reason}`, header.detail);
+        // The working copy, the proxy, then each phase in the bundle's order.
+        const phases = [...bundle.phases].sort((a, b) => a.order - b.order);
+        try {
+            ws = await deps.prepareWorkspace(job.repo, sessionId);
+        }
+        catch (e) {
+            // No working copy: the first phase could not start, as when its process cannot.
+            const reason = phaseReason(phases[0].order, phases[0].name);
+            deps.log(`preparing the working copy of ${job.repo} failed: ${e.message}`);
+            await reportFail(deps, sessionId, claim.epoch, "runner_failed", reason);
+            return { kind: "outcome", outcome: failedOutcome(facts, reason) };
+        }
+        const state = { contractValue: header.value, leaseKey: claim.leaseKey };
+        proxy = await deps.startProxy(state);
+        let opensPr = false;
+        for (const phase of phases) {
+            const planned = planPhase(phase);
+            if (!planned.ok) {
+                deps.log(`phase ${phase.order} ${phase.name}: ${planned.detail}`);
+                await reportFail(deps, sessionId, claim.epoch, "runner_failed", phaseReason(phase.order, phase.name));
+                return {
+                    kind: "outcome",
+                    outcome: failedOutcome(facts, phaseReason(phase.order, phase.name)),
+                };
+            }
+            opensPr ||= planned.opensPr;
+            let amended = false;
+            for (;;) {
+                let code;
+                try {
+                    code = await deps.runPhase(planned.invocation, ws, proxy.url, phaseAbort.signal);
+                }
+                catch (e) {
+                    deps.log(`phase ${phase.order} ${phase.name} did not start: ${e.message}`);
+                    code = -1;
+                }
+                const afterPhase = await interrupted();
+                if (afterPhase)
+                    return afterPhase;
+                if (proxy.contractMismatch && !amended) {
+                    // 34.11: the charter moved. Continue only on a higher sealed version with both the job
+                    // and a fresh bundle bound to it; then the phase runs again under the new seal.
+                    const next = await amendedSeal(deps, sessionId, claim, bundle);
+                    if (!next)
+                        return await refuse("contract_mismatch_unrecoverable", "the amended seal did not check out");
+                    state.contractValue = next.value;
+                    Object.assign(claim, { contractSha256: next.sha, contractVersion: next.version });
+                    Object.assign(facts, { contract_sha256: next.sha, contract_version: next.version });
+                    proxy.contractMismatch = null;
+                    amended = true;
+                    continue;
+                }
+                if (proxy.contractMismatch) {
+                    return await refuse("contract_mismatch_unrecoverable", "the gateway refused the amended seal too");
+                }
+                if (code !== 0) {
+                    const reason = phaseReason(phase.order, phase.name);
+                    deps.log(`phase ${phase.order} ${phase.name} exited ${code}`);
+                    await reportFail(deps, sessionId, claim.epoch, "runner_failed", reason);
+                    return { kind: "outcome", outcome: failedOutcome(facts, reason) };
+                }
+                break;
+            }
+        }
+        if (opensPr) {
+            try {
+                facts.pr_url = await deps.openPr(job.repo, ws, `mnemom: ${bundle.workflow.id} job ${sessionId.slice(0, 8)}`);
+            }
+            catch (e) {
+                deps.log(`opening the PR failed: ${e.message}`);
+                await reportFail(deps, sessionId, claim.epoch, "runner_failed", "pr_open_failed");
+                return { kind: "outcome", outcome: failedOutcome(facts, "pr_open_failed") };
+            }
+            if (facts.merge_strategy === "merge_on_green") {
+                try {
+                    await deps.enableAutoMerge(facts.pr_url);
+                }
+                catch (e) {
+                    deps.log(`enabling auto-merge failed (the PR stays open): ${e.message}`);
+                }
+            }
+        }
+        await release(deps, sessionId, claim.epoch);
+        return { kind: "outcome", outcome: doneOutcome(facts) };
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        opts.stop.removeEventListener("abort", onStop);
+        await proxy?.close();
+        // A workspace left behind never changes the outcome; it is logged for the operator.
+        if (ws)
+            await deps.cleanup(ws).catch((e) => deps.log(`cleanup failed: ${e.message}`));
+    }
+}
+async function fetchBundle(deps, sessionId, claim) {
+    const [jwksRes, res] = await Promise.all([
+        deps.api.jwks(),
+        deps.api.bundle(sessionId, claim.leaseKey),
+    ]);
+    const refusal = leaseReadRefusal(res, "bundle_unavailable");
+    if (refusal)
+        return {
+            kind: "refused",
+            reason: refusal,
+            detail: `bundle fetch: ${res.code ?? res.networkError ?? res.status}`,
+        };
+    if (jwksRes.status !== 200) {
+        return {
+            kind: "refused",
+            reason: "bundle_unavailable",
+            detail: `jwks: ${jwksRes.networkError ?? jwksRes.status}`,
+        };
+    }
+    if (claim.executorId === null) {
+        // No answer named this runner's executor id, so the bundle cannot be bound to the claim.
+        return {
+            kind: "refused",
+            reason: "bundle_binding_mismatch",
+            detail: "the claim answer named no executor_id",
+        };
+    }
+    const v = verifyServedPhaseBundle(res.text, jwksRes.body, {
+        org_id: orgOf(res.body),
+        session_id: sessionId,
+        epoch: claim.epoch,
+        executor_id: claim.executorId,
+        contract_sha256: claim.contractSha256,
+        contract_version: claim.contractVersion,
+    }, { now: deps.now });
+    if (!v.valid)
+        return { kind: "refused", reason: `bundle_${v.reason}`, detail: v.detail };
+    return { kind: "ok", bundle: v.bundle };
+}
+/**
+ * The org the bundle must name. The runner learns its org only from the server, so the bundle's
+ * own org_id is the expectation; what binds it to this runner is the session, epoch, executor and
+ * seal, all of which the runner knows independently.
+ */
+function orgOf(body) {
+    const o = body?.org_id;
+    return typeof o === "string" ? o : "";
+}
+async function amendedSeal(deps, sessionId, claim, running) {
+    const jr = await deps.api.job(sessionId);
+    const job = jr.status === 200 ? parseJob(jr.body) : null;
+    if (!job || job.version <= claim.contractVersion)
+        return null;
+    const fresh = await fetchBundle(deps, sessionId, {
+        ...claim,
+        contractSha256: job.contract_sha256,
+        contractVersion: job.version,
+    });
+    if (fresh.kind !== "ok")
+        return null;
+    // An amend reseals the charter, never the work: phases already run were signed as these, so a
+    // re-sealed bundle with another workflow or phase list fails closed rather than run stale phases.
+    if (!sameWork(fresh.bundle, running)) {
+        deps.log("the amended bundle changes the workflow or its phases");
+        return null;
+    }
+    const header = sealedContractHeader(Buffer.from(job.contract, "utf8"), job.contract_sha256);
+    if (!header.ok)
+        return null;
+    return { value: header.value, sha: job.contract_sha256, version: job.version };
+}
+function sameWork(a, b) {
+    return (canonicalJson({ workflow: a.workflow, phases: a.phases }) ===
+        canonicalJson({ workflow: b.workflow, phases: b.phases }));
+}
+/**
+ * Report a failed or refused job after claim (34.12 (6), (10)). The fail reason vocabulary is the
+ * Durable lead's to rule (A3 accepts only transcript_lost today); a refused report is logged and
+ * never changes the outcome, because the lease lapses on its own.
+ */
+export async function reportFail(deps, sessionId, epoch, kind, reason) {
+    const r = await deps.api.fail(sessionId, {
+        epoch,
+        nonce: deps.nonce,
+        reason: kind,
+        refs: { reason },
+    });
+    if (!ok2xx(r))
+        deps.log(`exec_fail ${kind}/${reason}: ${errorCode(r.body) ?? r.networkError ?? r.status}`);
+}
+async function release(deps, sessionId, epoch) {
+    const r = await deps.api.release(sessionId, { epoch, nonce: deps.nonce });
+    if (!ok2xx(r))
+        deps.log(`release failed (the lease lapses on its own): ${r.code ?? r.networkError ?? r.status}`);
+}
+async function stopJob(deps, sessionId, epoch) {
+    await release(deps, sessionId, epoch);
+    return { kind: "stopped" };
+}

package/dist/lib/runner/loop.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `mnemom agent run`'s claim loop (ruling 34.12 (1), (6), (7), (9); Doors W-L13, W3.11).
+ *
+ * --once: list the ready pool sessions (exec_ready_list, oldest first), try each in order, and run
+ * at most one job. A lost race, or an ineligible waiting / not_pool_member, moves to the next
+ * candidate; an empty list, or every candidate lost, ends no_job. --watch: the same, again and
+ * again, until SIGTERM or SIGINT. Every job prints exactly one outcome line (none when stopped
+ * mid-job), and the process exit code is the --once outcome's, or 0 for --watch stopped.
+ *
+ * Every side effect is in `JobDeps` (plus `emit`), so each arm is tested; `liveJobDeps`
+ * (commands/agent-run.ts) is the thin driver.
+ */
+import type { HttpResult } from "./executor-client.js";
+import { type JobDeps } from "./job.js";
+import { type RefusedReason } from "./outcome.js";
+import type { RunnerFailMode } from "./settings.js";
+export interface LoopOptions {
+    failMode: RunnerFailMode;
+    stop: AbortSignal;
+    /** Print one outcome line (stdout). */
+    emit(line: string): void;
+    /** --watch: wait between empty polls, ms. */
+    idlePollMs?: number;
+}
+export declare const WATCH_IDLE_POLL_MS = 15000;
+/** --watch backs off on a ready-list the api cannot answer, up to this, ms. */
+export declare const WATCH_MAX_BACKOFF_MS: number;
+type ListStep = {
+    kind: "ok";
+    ids: string[];
+} | {
+    kind: "refused";
+    reason: RefusedReason;
+    detail: string;
+};
+/** The ready list, oldest first as served; an id that is not a lowercase uuid is dropped. */
+export declare function readyIds(r: HttpResult): ListStep;
+/** --once: at most one job. Resolves the process exit code. */
+export declare function runOnce(deps: JobDeps, opts: LoopOptions): Promise<number>;
+/**
+ * --watch: one outcome line per job until stopped. A ready list the api cannot answer is not a
+ * job: it is logged and retried with backoff. A refused executor key ends the loop (exit 3).
+ */
+export declare function runWatch(deps: JobDeps, opts: LoopOptions): Promise<number>;
+export {};

package/dist/lib/runner/loop.js

@@ -0,0 +1,104 @@
+/**
+ * `mnemom agent run`'s claim loop (ruling 34.12 (1), (6), (7), (9); Doors W-L13, W3.11).
+ *
+ * --once: list the ready pool sessions (exec_ready_list, oldest first), try each in order, and run
+ * at most one job. A lost race, or an ineligible waiting / not_pool_member, moves to the next
+ * candidate; an empty list, or every candidate lost, ends no_job. --watch: the same, again and
+ * again, until SIGTERM or SIGINT. Every job prints exactly one outcome line (none when stopped
+ * mid-job), and the process exit code is the --once outcome's, or 0 for --watch stopped.
+ *
+ * Every side effect is in `JobDeps` (plus `emit`), so each arm is tested; `liveJobDeps`
+ * (commands/agent-run.ts) is the thin driver.
+ */
+import { READY_SESSIONS_LIMIT_MAX } from "../../vendor/durable-contract/index.js";
+import { authRefusal, runJob } from "./job.js";
+import { exitCodeFor, noJobOutcome, outcomeLine, refusedOutcome, } from "./outcome.js";
+export const WATCH_IDLE_POLL_MS = 15_000;
+/** --watch backs off on a ready-list the api cannot answer, up to this, ms. */
+export const WATCH_MAX_BACKOFF_MS = 5 * 60_000;
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The ready list, oldest first as served; an id that is not a lowercase uuid is dropped. */
+export function readyIds(r) {
+    const auth = authRefusal(r);
+    if (auth)
+        return { kind: "refused", reason: auth, detail: `ready list: ${r.code}` };
+    if (r.status !== 200) {
+        return {
+            kind: "refused",
+            reason: "api_unavailable",
+            detail: `ready list: ${r.code ?? r.networkError ?? r.status}`,
+        };
+    }
+    const sessions = r.body?.sessions;
+    if (!Array.isArray(sessions)) {
+        return { kind: "refused", reason: "api_unavailable", detail: "ready list: no sessions array" };
+    }
+    const ids = [];
+    for (const s of sessions) {
+        const id = s?.id;
+        if (typeof id === "string" && SESSION_ID_RE.test(id))
+            ids.push(id);
+    }
+    return { kind: "ok", ids };
+}
+/** One pass over the ready list: the first claimed job's outcome, or none. */
+async function onePass(deps, opts) {
+    const listed = readyIds(await deps.api.readyList(READY_SESSIONS_LIMIT_MAX));
+    if (listed.kind === "refused") {
+        deps.log(`refused (${listed.reason}): ${listed.detail}`);
+        return { kind: "outcome", outcome: refusedOutcome({}, listed.reason) };
+    }
+    for (const id of listed.ids) {
+        if (opts.stop.aborted)
+            return { kind: "stopped" };
+        const r = await runJob(id, { failMode: opts.failMode, stop: opts.stop }, deps);
+        if (r.kind === "next")
+            continue;
+        return r;
+    }
+    return { kind: "none" };
+}
+/** --once: at most one job. Resolves the process exit code. */
+export async function runOnce(deps, opts) {
+    const p = await onePass(deps, opts);
+    if (p.kind === "stopped")
+        return 0;
+    const outcome = p.kind === "outcome" ? p.outcome : noJobOutcome();
+    opts.emit(outcomeLine(outcome));
+    return exitCodeFor(outcome.outcome);
+}
+/** Refusals no later poll can cure: the executor key itself was refused. */
+const FATAL = new Set(["executor_revoked", "executor_unauthorized"]);
+/**
+ * --watch: one outcome line per job until stopped. A ready list the api cannot answer is not a
+ * job: it is logged and retried with backoff. A refused executor key ends the loop (exit 3).
+ */
+export async function runWatch(deps, opts) {
+    const idle = opts.idlePollMs ?? WATCH_IDLE_POLL_MS;
+    let backoff = idle;
+    while (!opts.stop.aborted) {
+        const p = await onePass(deps, opts);
+        if (p.kind === "stopped")
+            break;
+        if (p.kind === "outcome") {
+            const o = p.outcome;
+            if (o.outcome === "refused" && o.session_id === null && o.reason !== null) {
+                if (FATAL.has(o.reason)) {
+                    opts.emit(outcomeLine(o));
+                    return exitCodeFor(o.outcome);
+                }
+                if (o.reason === "api_unavailable") {
+                    await deps.sleep(backoff);
+                    backoff = Math.min(backoff * 2, WATCH_MAX_BACKOFF_MS);
+                    continue;
+                }
+            }
+            opts.emit(outcomeLine(o));
+            backoff = idle;
+            continue; // a job ran: look again at once
+        }
+        backoff = idle;
+        await deps.sleep(idle);
+    }
+    return 0;
+}

package/dist/lib/runner/oidc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `agent run --once --oidc`'s credential (ruling 34.12 (5), (6); 34.14 (2); Doors W4.12).
+ *
+ * The runner fetches the GitHub Actions ID token itself, for audience `mnemom-executor`, and posts
+ * it as {oidc_token} to exec_oidc_exchange, whose auth is github_oidc (the token in the body, no
+ * key header). The answer is a one-lease org-scope executor key, used for that single job. Every
+ * failure fails closed, whatever --fail-mode says, because no job is held yet: an exchange refusal
+ * is oidc_<code> for S1's OIDC_EXCHANGE_REFUSALS, anything else oidc_unavailable. The token never
+ * reaches argv, a log line or an outcome.
+ *
+ * S1 names the route but not its answer's field; `executor_key` is this runner's reading, open
+ * with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
+ */
+import { type FetchFn } from "./executor-client.js";
+import type { RefusedReason } from "./outcome.js";
+export type OidcExchange = {
+    ok: true;
+    executorKey: string;
+} | {
+    ok: false;
+    reason: RefusedReason;
+    detail: string;
+};
+/** The Actions ID token for `mnemom-executor`, or why there is none. */
+export declare function actionsIdToken(fetch: FetchFn, requestUrl: string, requestToken: string): Promise<{
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    detail: string;
+}>;
+/** Fetch the ID token and exchange it for a one-lease executor key. */
+export declare function exchangeOidc(opts: {
+    fetch: FetchFn;
+    apiUrl: string;
+    requestUrl: string;
+    requestToken: string;
+}): Promise<OidcExchange>;