@mnemom/mnemom 0.17.32-next.4 → 0.17.33

package/dist/lib/runner/executor-client.js

@@ -0,0 +1,97 @@
+/**
+ * The thin runner's executor client (ruling 34.12 (7)): S1's executor routes, the same protocol as
+ * C2's host client, plus the two post-claim reads outside S1 (the job, W-L15; the served bundle,
+ * W-L12) and the JWKS. Every executor route carries the executor key in X-Mnemom-Api-Key and
+ * never Authorization (ruling 33.28 (1)), and so does the job read (api#4165 authorizes the executor
+ * holding the lease); the bundle fetch carries the lease key the same way.
+ *
+ * Nothing here decides an outcome: each call returns its status, body and error code, and the job
+ * (job.ts) maps them to 34.12's reasons. Never throws: a network failure is status 0.
+ */
+import { EXECUTOR_KEY_HEADER, routePath } from "../../vendor/durable-contract/index.js";
+export function errorCode(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const b = body;
+    if (b.error && typeof b.error === "object") {
+        const c = b.error.code;
+        if (typeof c === "string")
+            return c;
+    }
+    if (typeof b.error === "string")
+        return b.error;
+    return typeof b.code === "string" ? b.code : null;
+}
+export function errorDetails(body) {
+    if (!body || typeof body !== "object")
+        return {};
+    const e = body.error;
+    const d = e && typeof e === "object" ? e.details : undefined;
+    return d && typeof d === "object" && !Array.isArray(d) ? d : {};
+}
+/** The post-claim job read (W-L15), with the executor key. */
+export const JOB_READ_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/job`;
+/** The served bundle fetch, per claim (W-L12). */
+export const BUNDLE_FETCH_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/bundle`;
+export const JWKS_PATH = "/v1/.well-known/jwks.json";
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function runnerApi(opts) {
+    const base = opts.apiUrl.replace(/\/+$/, "");
+    const call = async (path, method, key, body) => {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 15_000);
+        const headers = { accept: "application/json" };
+        if (key !== null)
+            headers[EXECUTOR_KEY_HEADER] = key;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        try {
+            const res = await opts.fetch(`${base}${path}`, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: ctl.signal,
+            });
+            const text = await res.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = text;
+            }
+            return {
+                status: res.status,
+                body: parsed,
+                text,
+                code: res.status >= 400 ? errorCode(parsed) : null,
+            };
+        }
+        catch (e) {
+            return { status: 0, body: null, text: "", code: null, networkError: e.message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    // A session id from the api goes into a path; refuse anything but a lowercase uuid.
+    const scoped = (id) => {
+        if (!SESSION_ID_RE.test(id))
+            throw new RangeError("session id must be a lowercase uuid");
+        return id;
+    };
+    const ex = opts.executorKey;
+    return {
+        readyList: (limit) => call(`${routePath("exec_ready_list")}?limit=${limit}`, "GET", ex),
+        attest: (id, nonce) => call(routePath("exec_attest", scoped(id)), "POST", ex, { nonce }),
+        claim: (id, body) => call(routePath("exec_claim", scoped(id)), "POST", ex, body),
+        append: (id, body) => call(routePath("exec_append", scoped(id)), "POST", ex, body),
+        hello: (id, body) => call(routePath("exec_hello", scoped(id)), "POST", ex, body),
+        heartbeat: (body) => call(routePath("exec_heartbeat"), "POST", ex, body),
+        release: (id, body) => call(routePath("exec_release", scoped(id)), "POST", ex, body),
+        fail: (id, body) => call(routePath("exec_fail", scoped(id)), "POST", ex, body),
+        job: (id) => call(JOB_READ_PATH(scoped(id)), "GET", ex),
+        bundle: (id, leaseKey) => call(BUNDLE_FETCH_PATH(scoped(id)), "GET", leaseKey),
+        jwks: () => call(JWKS_PATH, "GET", null),
+    };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * 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 { type HttpResult, type RunnerApi } from "./executor-client.js";
+import { type OutcomeFields, type RefusedReason } from "./outcome.js";
+import { type PhaseInvocation } from "./phases.js";
+import type { ModelProxy, ProxyState } from "./proxy.js";
+import { type RunnerFailMode } from "./settings.js";
+/** A claimed job's working copy. */
+export interface Workspace {
+    dir: string;
+    /** A fresh, empty HOME for the phases. */
+    home: string;
+    branch: string;
+}
+export interface JobDeps {
+    api: RunnerApi;
+    /** One nonce per runner process, reused on every call (A3 fences on it). */
+    nonce: string;
+    newSpawnId(): string;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    log(line: string): void;
+    gatewayUrl: string;
+    startProxy(state: ProxyState): Promise<ModelProxy>;
+    prepareWorkspace(repo: string, sessionId: string): Promise<Workspace>;
+    /** Run one phase's process; resolves its exit code. Rejects only when it could not start. */
+    runPhase(inv: PhaseInvocation, ws: Workspace, modelUrl: string, signal: AbortSignal): Promise<number>;
+    /** Push the job branch and open its PR; resolves the PR URL. */
+    openPr(repo: string, ws: Workspace, title: string): Promise<string>;
+    enableAutoMerge(prUrl: string): Promise<void>;
+    cleanup(ws: Workspace): Promise<void>;
+}
+export interface JobOptions {
+    failMode: RunnerFailMode;
+    /** Aborted by SIGTERM or SIGINT: release the lease, print no outcome line. */
+    stop: AbortSignal;
+}
+/** What one claim attempt came to. */
+export type JobResult = {
+    kind: "next";
+} | {
+    kind: "outcome";
+    outcome: OutcomeFields;
+} | {
+    kind: "stopped";
+};
+/** A3's executor auth rejections, on whichever executor route comes first (34.12 (8), (10)). */
+export declare function authRefusal(r: HttpResult): RefusedReason | null;
+/**
+ * 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 declare function runJob(sessionId: string, opts: JobOptions, deps: JobDeps): Promise<JobResult>;
+/**
+ * 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 declare function reportFail(deps: JobDeps, sessionId: string, epoch: number, kind: "runner_failed" | "runner_refused", reason: string): Promise<void>;

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 {};