@eir-labs/coltrane 0.6.2 → 0.7.3

package/dist/src/worker.js

@@ -0,0 +1,737 @@
+// worker.ts — the drain worker's verb set. The gig table IS the queue; this module is the
+// consumer that turns a queued row into a completed one.
+//
+// The credential model is two keys with two jobs (governor rulings, 2026-08-10):
+//   * a ctk_ AGENT token — per-agent, authenticates WHO is working. Claim, genome read, and
+//     failure reporting all speak through it; authorization derives from the CHAIR CONTRACT
+//     the agent is seated on (the store enforces it — "standards should be authorized on
+//     chair contract"). A token narrows the office, never widens it.
+//   * a cdk_ DRAIN key — per-ORGANIZATION, because the org is the resource boundary. It is
+//     the write path for results (outputs + gig header), consumed by the engine's drain
+//     layer via COLTRANE_DRAIN_URL / COLTRANE_DRAIN_KEY, not by this module directly.
+//
+// workOnce runs the claimed gig UNDER THE CLAIMED GIG'S ID (deps.gig_id), so the drained
+// header completes the queue row itself — one record per gig, no parallel bookkeeping. A
+// run that throws is recorded as failed through coltrane_mcp_gig_fail; a worker crash
+// leaves only an expiring lease, which the claim RPC hands to the next worker.
+//
+// The third outcome is the HUMAN SEAT. A run that reaches a chair a person holds parks:
+// coltrane_mcp_gig_park sets the row to awaiting_approval and clears the lease, so the store's
+// approve RPC can re-queue it at once. The approval comes back on the next claim payload, and
+// the durable checkpoint (workerStateRoot) means the approved re-claim RESTORES the chairs that
+// already sealed instead of paying for them twice.
+//
+// THAT LOCAL CHECKPOINT IS ONLY THE FAST PATH. A human-in-the-loop delay is measured in hours
+// or days, and the worker that re-claims is a different process — often on a different machine
+// — from the one that parked. `workerStateRoot()` cannot travel, so on its own it makes the
+// saving conditional on the accident of which box picked the row up.
+//
+// The SINK already is the checkpoint. Every sealed output drained to the org store carries its
+// content_sha, its input_shas, its phase, its agent_slug and its whole `data`; the drained gig
+// header carries the run's genome_hash. So a worker with no local record reconstructs one from
+// the sink (`resumeStateFromDrain` below) and resumes from that. Resume state's home is the
+// store; the local checkpoint demotes to a fast path.
+import * as fs from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { runGig, ResumeRefused, genomeHash, CORE_TO_PRIMITIVE } from "./runtime.js";
+import { loadRegistry } from "./registry.js";
+import { createOutputStore } from "./outputs.js";
+import { MemoryLedger } from "./ledger.js";
+import { rpcGenomeStore } from "./genome_store.js";
+import { createOutputMirror } from "./output_mirror.js";
+import { PRIMITIVE_OUTPUT_TYPE } from "./core_types.js";
+import { sha256Hex, canonJson, outputContentHash, CANONICAL_FORM_VERSION } from "./canonical_form.js";
+import { createCheckpointStore, producersSha, CHECKPOINT_SCHEMA_VERSION, } from "./reuse.js";
+/**
+ * The worker's durable state root: `checkpoints/` for the resume records, `outputs/` + `refs/`
+ * for the sealed rows those records name — the sibling layout `createCheckpointStore` documents.
+ *
+ * BOTH halves have to outlive the process. A worker is a short-lived consumer: it claims one
+ * row and exits, and the approved re-claim is a DIFFERENT process. A checkpoint whose outputs
+ * the next process cannot read refuses the resume it exists to permit, so the run would be
+ * paid for twice — which is the whole cost this store exists to avoid.
+ */
+export function workerStateRoot() {
+    const override = process.env["COLTRANE_WORKER_CHECKPOINTS"];
+    if (override && override.length > 0)
+        return override;
+    return join(homedir(), ".coltrane", "worker-checkpoints");
+}
+/** Default worker-state TTL, in days. A checkpoint older than this is presumed abandoned. */
+export const DEFAULT_WORKER_STATE_TTL_DAYS = 7;
+/** Resolve the reaper TTL from `COLTRANE_WORKER_STATE_TTL_DAYS`, falling back to the default. */
+export function workerStateTtlDays() {
+    const raw = process.env["COLTRANE_WORKER_STATE_TTL_DAYS"];
+    if (raw && raw.trim().length > 0) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_WORKER_STATE_TTL_DAYS;
+}
+/**
+ * Bound the worker state root's growth. The runtime deletes a checkpoint on SUCCESS, but a
+ * FAILED / awaiting-approval / abandoned gig leaves its `checkpoints/<gig>.json` (plus the
+ * `outputs/<gig>.jsonl` + `refs/<gig>.jsonl` it names) behind forever — an unbounded disk
+ * leak. This drops what is old enough to be presumed abandoned.
+ *
+ * WHAT IT TOUCHES:
+ *  - A `checkpoints/<gig>.json` whose MTIME is older than the TTL, together with that gig's
+ *    sibling `outputs/<gig>.jsonl` and `refs/<gig>.jsonl` — they are dead weight once the
+ *    checkpoint that named them is gone.
+ *  - An ORPHAN `outputs/<gig>.jsonl` / `refs/<gig>.jsonl` (no checkpoint file for that gig at
+ *    all — e.g. a completed gig whose checkpoint was already dropped on success) older than the
+ *    TTL. This is the other half of the leak: success removes the checkpoint but leaves the rows.
+ *
+ * WHAT IT NEVER TOUCHES:
+ *  - Any gig whose checkpoint is FRESHER than the TTL. A parked / awaiting-approval gig's
+ *    checkpoint is LOAD-BEARING for the approved resume, and the TTL is the "reasonable window"
+ *    that protects it — the reaper cannot see the org store's row status locally, so mtime is
+ *    the proxy: recent state is kept. A fresh checkpoint's outputs are never swept even if the
+ *    outputs file itself looks old (a restore-only resume re-touches the checkpoint but appends
+ *    no new rows), because the sweep is driven from checkpoint age, not output age.
+ *
+ * Best-effort by construction: every filesystem op is caught and recorded in `errors`; the
+ * function never throws, so a reap failure can never fail the claim it runs ahead of.
+ */
+export function reapWorkerState(root, opts) {
+    const result = { checkpoints_removed: [], orphans_removed: [], kept: 0, errors: [] };
+    const ttlDays = opts?.ttlDays ?? workerStateTtlDays();
+    const now = opts?.now ?? Date.now();
+    const ttlMs = ttlDays * 24 * 60 * 60 * 1000;
+    const cpDir = join(root, "checkpoints");
+    const outDir = join(root, "outputs");
+    const refDir = join(root, "refs");
+    const listDir = (dir) => {
+        try {
+            return fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+        }
+        catch (e) {
+            result.errors.push(`readdir ${dir}: ${e instanceof Error ? e.message : String(e)}`);
+            return [];
+        }
+    };
+    const ageMs = (file) => {
+        try {
+            return now - fs.statSync(file).mtimeMs;
+        }
+        catch (e) {
+            result.errors.push(`stat ${file}: ${e instanceof Error ? e.message : String(e)}`);
+            return null;
+        }
+    };
+    const rm = (file) => {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch (e) {
+            result.errors.push(`rm ${file}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    // Pass 1 — checkpoint-driven. A gig id is exactly a checkpoint file's basename.
+    const liveGigs = new Set();
+    for (const name of listDir(cpDir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const gig = name.slice(0, -".json".length);
+        const age = ageMs(join(cpDir, name));
+        if (age === null) {
+            liveGigs.add(gig);
+            continue;
+        } // couldn't stat → keep, don't guess
+        if (age > ttlMs) {
+            rm(join(cpDir, name));
+            rm(join(outDir, `${gig}.jsonl`));
+            rm(join(refDir, `${gig}.jsonl`));
+            result.checkpoints_removed.push(gig);
+        }
+        else {
+            // Fresh checkpoint — load-bearing. Its gig's rows are protected regardless of their own age.
+            liveGigs.add(gig);
+            result.kept += 1;
+        }
+    }
+    // Pass 2 — orphan rows: an outputs/refs file for a gig that has NO checkpoint at all.
+    const sweepOrphans = (dir) => {
+        for (const name of listDir(dir)) {
+            if (!name.endsWith(".jsonl"))
+                continue;
+            const gig = name.slice(0, -".jsonl".length);
+            if (liveGigs.has(gig))
+                continue; // a live checkpoint owns it — keep
+            if (result.checkpoints_removed.includes(gig))
+                continue; // already removed as a sibling
+            const age = ageMs(join(dir, name));
+            if (age === null || age <= ttlMs)
+                continue;
+            rm(join(dir, name));
+            if (!result.orphans_removed.includes(gig))
+                result.orphans_removed.push(gig);
+        }
+    };
+    sweepOrphans(outDir);
+    sweepOrphans(refDir);
+    return result;
+}
+async function workerRpc(ctx, fn, body) {
+    const res = await fetch(`${ctx.baseUrl}/rest/v1/rpc/${fn}`, {
+        method: "POST",
+        headers: {
+            apikey: ctx.anonKey,
+            // A ctk_ bearer is not a JWT — it authenticates inside the definer RPC via the body;
+            // the transport rides the anon key.
+            Authorization: `Bearer ${ctx.anonKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let message = text || `store error ${res.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed.message)
+                message = parsed.message;
+        }
+        catch { /* keep the raw text */ }
+        throw new Error(`${fn}: ${message}`);
+    }
+    return text ? JSON.parse(text) : null;
+}
+/** Atomically claim the oldest runnable gig (queued, or running with an expired lease) the
+ *  seated agent's chair contract authorizes. Null means the queue holds nothing for us. */
+export async function claimNextGig(ctx) {
+    const out = await workerRpc(ctx, "coltrane_mcp_claim", {
+        p_bearer: ctx.agentToken,
+        p_worker: ctx.worker ?? null,
+    });
+    return out ?? null;
+}
+/**
+ * Release the lease on a PARKED gig: the row goes `awaiting_approval` and its lease clears, so
+ * an approval can re-queue it immediately instead of waiting the lease out. Deliberately NOT
+ * `gig_fail` — a run waiting on a person is not a failed run, and recording it as one both lies
+ * to the operator and takes the row out of the approve→requeue path.
+ *
+ * False means the store did not record the release — including a store that has not deployed
+ * the RPC yet. The run's own drained header already carries `awaiting_approval`, so an absent
+ * release is a missing convenience, not a lost fact, and must not fail the claim.
+ */
+export async function parkGig(ctx, gig_id) {
+    try {
+        const out = await workerRpc(ctx, "coltrane_mcp_gig_park", {
+            p_bearer: ctx.agentToken,
+            p_gig: gig_id,
+        });
+        return out === true;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        // PostgREST answers an undeployed function with PGRST202 / "Could not find the function".
+        if (/PGRST202|could not find the function|does not exist/i.test(message))
+            return false;
+        throw e;
+    }
+}
+/** Record a failed run on the claimed row. True iff the store recorded it (row was running). */
+export async function failGig(ctx, gig_id, error) {
+    const out = await workerRpc(ctx, "coltrane_mcp_gig_fail", {
+        p_bearer: ctx.agentToken,
+        p_gig: gig_id,
+        p_error: error,
+    });
+    return out === true;
+}
+/** The sink's sealed rows for one gig. `[]` covers "no drain to read" as well as "nothing drained". */
+export async function fetchDrainedOutputs(ctx, gig_id) {
+    let out;
+    try {
+        out = await workerRpc(ctx, "coltrane_mcp_gig_outputs", { p_bearer: ctx.agentToken, p_gig: gig_id });
+    }
+    catch (e) {
+        // Every failure here is the same kind of event: resume state could not be read. The queue
+        // row is still runnable work, so this never fails the claim — it costs a cold run, which is
+        // exactly what the worker did before this path existed.
+        return { rows: [], error: e instanceof Error ? e.message : String(e) };
+    }
+    if (!Array.isArray(out))
+        return { rows: [] };
+    return { rows: out.filter((r) => !!r && typeof r === "object") };
+}
+/**
+ * The `genome_hash` the sink recorded on this gig's drained HEADER.
+ *
+ * This is the only identity a drained gig carries, and reading it is what keeps the
+ * reconstruction from being a splice. `genomeHash` folds the standard's whole phase graph and
+ * every bound agent's type surface — chair `depends_on`, `input_contract`, an added or removed
+ * phase — none of which reaches an individual row's `content_sha`. Without this check a
+ * pipeline could be re-wired between the park and the approval and the restored outputs would
+ * be consumed by chairs that never produced them, with nothing in the manifest recording it.
+ *
+ * STATED GAP: the header carries no `producers_sha`, so a rewritten agent `method` (or a
+ * rewritten skill under a stable version) is invisible to this path — the very hole
+ * `RunIdentity.producers_sha` exists to close for a LOCAL checkpoint. A drain-reconstructed
+ * resume is therefore a weaker gate than a local one by exactly that much, and the strongest
+ * available check is the one applied: the sink's structural hash plus a per-row re-seal.
+ */
+export async function fetchDrainedGenomeHash(ctx, gig_id) {
+    let out;
+    try {
+        out = await workerRpc(ctx, "coltrane_mcp_gig_status", { p_bearer: ctx.agentToken, p_gig: gig_id });
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    // The RPC may answer with the header row or a single-row array; both are the same fact.
+    const row = Array.isArray(out) ? out[0] : out;
+    if (!row || typeof row !== "object")
+        return {};
+    const gh = row["genome_hash"];
+    // 64 hex or nothing: the header stores `null` for a run with no hash, and the ledger writes
+    // "n/a" in places. Neither is a genome identity, and treating one as if it were is the bug.
+    return typeof gh === "string" && /^[0-9a-f]{64}$/.test(gh) ? { genome_hash: gh } : {};
+}
+/**
+ * Re-derive every chair's seal specs from the loaded standard.
+ *
+ * This mirrors the runtime's own derivation chair-kind for chair-kind (`outputSpecsFor`, the
+ * skill-backed branch of `prepareChair`, and the human-seat branch of the phase loop), because
+ * `content_sha` folds exactly what it produces. Divergence here would not be a cosmetic
+ * mismatch — it would compute a different sha for an unchanged row and refuse every resume.
+ */
+function chairSeats(standard, outputs) {
+    const seats = [];
+    for (const phase of standard.phases) {
+        for (const chair of phase.chairs) {
+            const specs = new Map();
+            if (chair.human === true && (chair.agent_slug ?? "") === "") {
+                const dt = chair.output_contract[0] ?? "Judgment";
+                const core = outputs.coreTypeOf(dt) ?? dt;
+                specs.set(dt, { core_type: core, primitive: CORE_TO_PRIMITIVE[core] ?? "JUDGE", domain: standard.domain });
+                seats.push({ chair, phase: phase.name, producer: { kind: "human" }, specs });
+                continue;
+            }
+            if (chair.skill_slug && (chair.agent_slug ?? "") === "") {
+                const dt = chair.output_contract[0] ?? "Signal";
+                const core = outputs.coreTypeOf(dt) ?? "Signal";
+                specs.set(dt, { core_type: core, primitive: CORE_TO_PRIMITIVE[core] ?? "SENSE", domain: standard.domain });
+                seats.push({ chair, phase: phase.name, producer: { kind: "skill", slug: chair.skill_slug }, specs });
+                continue;
+            }
+            const agent = standard.agents.find((a) => a.slug === chair.agent_slug);
+            const fallback = agent?.primitives[0];
+            // A chair whose agent the genome no longer holds could not have sealed anything under
+            // THIS genome. Skipping it means its rows find no seat and the reconstruction refuses,
+            // which is the honest outcome.
+            if (!agent || !fallback)
+                continue;
+            const wanted = chair.output_contract.length
+                ? agent.output_types.filter((t) => chair.output_contract.includes(t))
+                : agent.output_types;
+            const domain = agent.domain ?? standard.domain;
+            for (const dt of wanted) {
+                const core = outputs.coreTypeOf(dt) ?? PRIMITIVE_OUTPUT_TYPE[fallback];
+                specs.set(dt, { core_type: core, primitive: CORE_TO_PRIMITIVE[core] ?? fallback, domain });
+            }
+            seats.push({ chair, phase: phase.name, producer: { kind: "agent", slug: agent.slug }, specs });
+        }
+    }
+    return seats;
+}
+/**
+ * The run identity a COLD run of this claim would compute, field for field.
+ *
+ * Kept adjacent to the `runGig` call in `workOnce` on purpose: `model_version` and `depth` are
+ * that call's defaults (it passes neither), and `skills: []` is what `resolvedSkillHashes()`
+ * folds for a worker that registers no `skill_dirs` — a store-loaded skill has no code half by
+ * construction. Change what `workOnce` passes and this has to move with it, or every
+ * reconstruction is refused for identity drift against its own run.
+ */
+function coldRunIdentity(standard, gigInput) {
+    return {
+        standard_slug: standard.slug,
+        genome_hash: genomeHash(standard),
+        producers_sha: producersSha({ agents: standard.agents, skills: [] }),
+        gig_input_sha: sha256Hex(canonJson(gigInput)),
+        model_version: "unknown",
+        depth: "",
+        canonical_form_version: CANONICAL_FORM_VERSION,
+    };
+}
+/** Accumulate one restored record onto its chair's checkpoint role, whether written or adopted. */
+function noteRole(byRole, p, output_id, content_sha) {
+    const role = p.seat.chair.role;
+    const cur = byRole.get(role) ?? {
+        role, phase: p.seat.phase,
+        output_ids: [], content_shas: [], domain_types: [], type_fingerprints: [],
+        sealed_at: p.row.created_at,
+    };
+    cur.output_ids.push(output_id);
+    cur.content_shas.push(content_sha);
+    cur.domain_types.push(p.row.domain_type);
+    cur.type_fingerprints.push(p.fingerprint);
+    if (p.row.created_at > cur.sealed_at)
+        cur.sealed_at = p.row.created_at;
+    byRole.set(role, cur);
+}
+/**
+ * Turn the sink's sealed rows into a resume checkpoint — or refuse, with a reason.
+ *
+ * ALL-OR-NOTHING, in two passes. Pass one derives and verifies every row while nothing is
+ * durable; pass two writes. A gig whose second row fails must not leave its first one in the
+ * local store seeding a half-resume, which is the same invariant #243 gave a single chair, one
+ * scope up.
+ *
+ * ROLE MAPPING. The sink does not record `from_role`, so each row is mapped to a chair by
+ * `phase` + the chair's SEAT: `agent_slug` for an agent chair, the skill slug for a skill-backed
+ * one, and name-agnostically for a human chair (its record seals under the approving principal,
+ * whom the genome cannot know). The row's `domain_type` narrows further — a chair that does not
+ * seal that type is not a candidate. Zero candidates or MORE THAN ONE both refuse: a guess about
+ * which chair produced a sealed output is a guess about the provenance chain.
+ *
+ * SHA VERIFICATION. Every row is re-sealed under the derived core/primitive/domain and the sha
+ * compared to the one the sink recorded. A mismatch refuses the WHOLE reconstruction — a sink
+ * row that no longer hashes to its claimed sha must never silently seed a resume, and one such
+ * row is evidence about the sink, not about that row alone.
+ */
+export function resumeStateFromDrain(args) {
+    const { gig_id, standard, identity, rows, outputs } = args;
+    if (rows.length === 0)
+        return { ok: false, reason: "the sink holds no sealed outputs for this gig" };
+    const seats = chairSeats(standard, outputs);
+    // created_at order, so a row's in-gig predecessors are already re-written when it is written.
+    const ordered = [...rows].sort((a, b) => (a.created_at < b.created_at ? -1 : a.created_at > b.created_at ? 1 : 0));
+    const planned = [];
+    for (const row of ordered) {
+        const phase = typeof row.phase === "string" && row.phase !== "" ? row.phase : undefined;
+        if (phase === undefined) {
+            return { ok: false, reason: `sink row "${row.id}" records no phase, so it cannot be mapped to a chair` };
+        }
+        if (typeof row.content_sha !== "string" || !row.data || typeof row.data !== "object") {
+            return { ok: false, reason: `sink row "${row.id}" is not a sealed output shape (content_sha + data)` };
+        }
+        const candidates = seats.filter((s) => s.phase === phase && s.specs.has(row.domain_type) &&
+            (s.producer.kind === "human" || s.producer.slug === row.agent_slug));
+        if (candidates.length === 0) {
+            return {
+                ok: false,
+                reason: `no chair in phase "${phase}" seals "${row.domain_type}" for producer "${row.agent_slug}" — the standard has moved since that output sealed`,
+            };
+        }
+        if (candidates.length > 1) {
+            return {
+                ok: false,
+                reason: `chairs [${candidates.map((c) => c.chair.role).join(", ")}] in phase "${phase}" could each have sealed "${row.domain_type}" — the sink records no from_role, so the mapping is ambiguous`,
+            };
+        }
+        const seat = candidates[0];
+        const spec = seat.specs.get(row.domain_type);
+        // The registry moves independently of the standard, so genome_hash does not see a type that
+        // changed shape. Same fingerprint tool the local resume gate and the reuse cache use.
+        const fingerprint = outputs.typeFingerprint(row.domain_type);
+        if (fingerprint === "") {
+            return { ok: false, reason: `the registry can no longer describe type "${row.domain_type}", so the sink's row cannot be checked` };
+        }
+        const gate = outputs.validateWrite({ core_type: spec.core_type, domain_type: row.domain_type, data: row.data });
+        if (!gate.valid) {
+            return { ok: false, reason: `sink row "${row.id}" would not pass the seal boundary today — ${gate.reason}` };
+        }
+        const sha = outputContentHash({
+            core_type: spec.core_type,
+            domain_type: row.domain_type,
+            domain_type_version: 1,
+            domain: spec.domain,
+            primitive: spec.primitive,
+            phase,
+            agent_slug: row.agent_slug,
+            data: row.data,
+        });
+        if (sha !== row.content_sha) {
+            return {
+                ok: false,
+                reason: `sink row "${row.id}" ("${row.domain_type}", phase "${phase}") re-seals to a different content_sha than the sink recorded — the row no longer hashes to its claimed content_sha`,
+            };
+        }
+        planned.push({ row, seat, spec, fingerprint });
+    }
+    // Pass two — durable. The resume gate resolves a checkpoint's `output_ids` against the LOCAL
+    // output store, so the sink's rows have to become local records before they can be restored.
+    //
+    // IDEMPOTENT. The local store may already hold these rows: the checkpoint file can go missing
+    // while `outputs/<gig_id>.jsonl` survives (a swallowed checkpoint write, a cleared checkpoints
+    // dir), and appending second copies would leave `output_query` and `output_trace` reporting a
+    // gig that sealed each record twice. An existing IN-GIG record with the same content_sha IS
+    // that record — content_sha folds core, type, version, domain, primitive, phase, agent_slug and
+    // data, so an identical sha is an identical derivation — and it is adopted by id.
+    const alreadyHeld = new Map();
+    for (const rec of outputs.all()) {
+        if (rec.gig_id === gig_id && !alreadyHeld.has(rec.content_sha))
+            alreadyHeld.set(rec.content_sha, rec.id);
+    }
+    const byRole = new Map();
+    const shaToId = new Map();
+    for (const p of planned) {
+        const adopted = alreadyHeld.get(p.row.content_sha);
+        if (adopted !== undefined) {
+            shaToId.set(p.row.content_sha, adopted);
+            noteRole(byRole, p, adopted, p.row.content_sha);
+            continue;
+        }
+        const inputShas = (p.row.input_shas ?? []).map((s) => (typeof s === "string" ? s : ""));
+        const mapped = inputShas.map((s) => shaToId.get(s));
+        // Object identity is machine-local: the sink's own output ids name nothing here, and the ids
+        // of the rows we are writing are fresh. The HASH chain does travel — each `input_sha` names
+        // the content a row consumed — so remap ids only when every entry resolves, and otherwise
+        // keep the engine-stamped hashes and leave `input_refs` empty rather than emit a
+        // half-aligned pair.
+        const remapped = mapped.every((id) => typeof id === "string") ? mapped : undefined;
+        let rec;
+        try {
+            rec = outputs.write({
+                core_type: p.spec.core_type,
+                domain_type: p.row.domain_type,
+                domain_type_version: 1,
+                domain: p.spec.domain,
+                gig_id,
+                agent_slug: p.row.agent_slug,
+                from_role: p.seat.chair.role,
+                phase: p.seat.phase,
+                primitive: p.spec.primitive,
+                data: p.row.data,
+                input_refs: remapped ?? [],
+                input_shas: inputShas,
+            });
+        }
+        catch (e) {
+            // Unreachable: `validateWrite` above is the same gate `write` runs, from one implementation.
+            return { ok: false, reason: `sink row "${p.row.id}" could not be written locally — ${e instanceof Error ? e.message : String(e)}` };
+        }
+        if (rec.content_sha !== p.row.content_sha) {
+            return { ok: false, reason: `sink row "${p.row.id}" sealed locally to a different content_sha than the sink recorded` };
+        }
+        shaToId.set(rec.content_sha, rec.id);
+        noteRole(byRole, p, rec.id, rec.content_sha);
+    }
+    return {
+        ok: true,
+        checkpoint: {
+            schema_version: CHECKPOINT_SCHEMA_VERSION,
+            gig_id,
+            identity,
+            // The sink's own timestamps. `prior_usage` is deliberately absent: the outputs RPC carries
+            // no cost fields, so what the earlier attempt spent is genuinely unknown here, and an
+            // invented zero would be the "not captured reported as $0.00" defect #235/#236 removed.
+            started_at: ordered[0].created_at,
+            updated_at: ordered[ordered.length - 1].created_at,
+            roles: [...byRole.values()],
+        },
+    };
+}
+/** Read the sink and rebuild this claim's resume state, or say why it cannot be rebuilt. */
+async function rebuildFromDrain(ctx, claim, standard, outputs) {
+    const drained = await fetchDrainedOutputs(ctx, claim.gig_id);
+    if (drained.error !== undefined)
+        return { ok: false, reason: `the sink's outputs could not be read — ${drained.error}` };
+    if (drained.rows.length === 0)
+        return { ok: false, reason: "the sink holds no sealed outputs for this gig" };
+    const header = await fetchDrainedGenomeHash(ctx, claim.gig_id);
+    const current = genomeHash(standard);
+    if (header.genome_hash === undefined) {
+        // A miss is free; a wrong hit is not. An identity that cannot be checked resolves to doing
+        // the work — the same asymmetry every other substitution gate in this engine resolves on.
+        return {
+            ok: false,
+            reason: `the sink reports no genome_hash for this gig${header.error !== undefined ? ` (${header.error})` : ""}, so the pipeline those outputs sealed under cannot be checked`,
+        };
+    }
+    if (header.genome_hash !== current) {
+        return {
+            ok: false,
+            reason: `the genome moved since those outputs sealed (sink genome_hash="${header.genome_hash}" current="${current}")`,
+        };
+    }
+    return resumeStateFromDrain({
+        gig_id: claim.gig_id,
+        standard,
+        identity: coldRunIdentity(standard, claim.input),
+        rows: drained.rows,
+        outputs,
+    });
+}
+/**
+ * Map the claim's per-role approval entries onto runGig's two arguments.
+ *
+ * The store keys each verdict by ROLE (a standard may hold more than one human chair) while
+ * runGig takes a single `approved_by` for the run. So the name is read from the entry for the
+ * chair this claim will actually reach — the first human chair the checkpoint does not already
+ * hold — and falls back to the first entry when that is not discernible. Attribution on a seal
+ * is not decoration: the approval output carries it as its `agent_slug`.
+ */
+export function approvalWiring(approvals, standard, completedRoles = []) {
+    const entries = Object.entries(approvals ?? {}).filter(([, e]) => e && typeof e.verdict === "object" && e.verdict !== null);
+    if (entries.length === 0)
+        return {};
+    const held = new Set(completedRoles);
+    const awaitingRole = standard.phases
+        .flatMap((p) => p.chairs)
+        .find((c) => c.human === true && !held.has(c.role))?.role;
+    const named = (awaitingRole === undefined ? undefined : entries.find(([role]) => role === awaitingRole)) ?? entries[0];
+    const approved_by = named[1].approved_by;
+    return {
+        approvals: Object.fromEntries(entries.map(([role, e]) => [role, e.verdict])),
+        ...(typeof approved_by === "string" && approved_by !== "" ? { approved_by } : {}),
+    };
+}
+/** One unit of work: claim → load the org genome (as the agent) → run under the claimed
+ *  gig's id → results drain via the org drain key (engine drain layer, env-configured), or
+ *  the failure is recorded. Never throws for a run failure — a thrown claim/store error
+ *  means the worker itself could not speak to the store.
+ *
+ *  A run that reaches an unapproved human chair PARKS: the row is released (parkGig) and the
+ *  outcome is `awaiting_approval` — its own status, because it is neither finished nor broken. */
+export async function workOnce(ctx, deps) {
+    const log = deps.log ?? (() => { });
+    // Best-effort bounded reap of the worker state root before we claim. Wrapped so a reap
+    // failure can never fail a claim — the money-losing outcome is a run refused, not a file kept.
+    try {
+        const reaped = reapWorkerState(workerStateRoot());
+        if (reaped.checkpoints_removed.length > 0 || reaped.orphans_removed.length > 0) {
+            log(`reaped worker state: ${reaped.checkpoints_removed.length} checkpoint(s), ${reaped.orphans_removed.length} orphan row(s)`);
+        }
+    }
+    catch (e) {
+        log(`worker-state reap skipped: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const claim = await claimNextGig(ctx);
+    if (!claim)
+        return { claimed: false };
+    log(`claimed ${claim.gig_id} (${claim.standard_slug}, ${claim.mode}) as ${claim.acting_for}`);
+    try {
+        const genome = await rpcGenomeStore(ctx).load();
+        const standard = genome.standards.get(claim.standard_slug);
+        if (!standard) {
+            throw new Error(`claimed standard "${claim.standard_slug}" is not in the org genome this token can read` +
+                (genome.load_errors.length ? ` (${genome.load_errors.length} load error(s) — system_health has them)` : ""));
+        }
+        const registry = loadRegistry(genome);
+        const stateRoot = workerStateRoot();
+        // The mirror tier is where OUTPUT drain lives (the header drains from the runtime
+        // directly) — without it a worker's sealed outputs never reach the sink. Found live:
+        // the first worker run drained its failure header and none of its sealed phases.
+        //
+        // `persistDir` is the RESUME half of the same concern: the checkpoint names sealed rows by
+        // id, and the process that resumes is not the process that sealed them. Without a durable
+        // row store every re-claim is refused ("the output store no longer holds") and pays again.
+        const outputs = createOutputStore(registry, {
+            persistDir: stateRoot,
+            mirror: createOutputMirror(join(tmpdir(), "coltrane-worker-mirror")),
+        });
+        const ledger = new MemoryLedger();
+        const invoke = deps.makeInvoke(registry, genome);
+        const checkpoints = createCheckpointStore(stateRoot);
+        // ORDER OF PREFERENCE: the local checkpoint (fast path — same box, nothing to fetch), then
+        // the DRAIN reconstruction (a different box, or a state root that was cleared), then cold.
+        // Exactly one line is logged for whichever path is taken, including the reason for cold.
+        let checkpoint;
+        let resumeSource = "local";
+        let coldReason = "no local checkpoint and no drain to rebuild one from";
+        try {
+            checkpoint = checkpoints.read(claim.gig_id);
+        }
+        catch (e) {
+            // A damaged checkpoint is not a reason to fail a runnable row — it is a reason to pay for
+            // a cold run, and to say so.
+            log(`checkpoint for ${claim.gig_id} unreadable, running cold: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!checkpoint) {
+            const rebuilt = await rebuildFromDrain(ctx, claim, standard, outputs);
+            if (rebuilt.ok) {
+                // Written to the LOCAL store because that is where the runtime's resume gate reads a
+                // checkpoint from. The reconstruction seeds that gate; the gate remains the authority —
+                // it re-resolves every output id, re-checks every content_sha and type fingerprint, and
+                // compares the identity itself, so a bad reconstruction is refused by the same code a
+                // bad local checkpoint is.
+                checkpoints.write(rebuilt.checkpoint);
+                checkpoint = rebuilt.checkpoint;
+                resumeSource = "drain";
+            }
+            else {
+                coldReason = rebuilt.reason;
+            }
+        }
+        const human = approvalWiring(claim.approvals, standard, checkpoint?.roles.map((r) => r.role) ?? []);
+        const run = (resume) => runGig(standard, claim.input, {
+            outputs,
+            ledger,
+            invoke,
+            gig_id: claim.gig_id, // ← the run IS the queue row; the drained header completes it
+            skills: genome.skills,
+            // Store-loaded skills carry no local package dir (no code half) by construction, so
+            // no skill_dirs: a skill-BACKED chair in a store standard fails precisely at prep
+            // with the runtime's own "no skill_dir is registered" error, not a confabulated run.
+            checkpoints,
+            ...(resume ? { resume_from: claim.gig_id } : {}),
+            ...human,
+        });
+        let res;
+        if (checkpoint) {
+            // An approved re-claim is the common case for this branch: the chairs before the human
+            // seat already sealed and were already paid for, so replaying them is money spent twice.
+            log(`resuming ${claim.gig_id} from its ${resumeSource === "drain" ? "DRAIN-reconstructed" : "local"} ` +
+                `checkpoint (${checkpoint.roles.length} chair(s) recorded)`);
+            try {
+                res = await run(true);
+            }
+            catch (e) {
+                if (!(e instanceof ResumeRefused))
+                    throw e;
+                // A refusal is the engine declining to splice two runs together (the genome, the
+                // payload or a type moved). The queue row is still work that must happen, so it is run
+                // COLD and the second payment is stated rather than hidden.
+                log(`resume refused for ${claim.gig_id} — running it COLD: ${e.message}`);
+                res = await run(false);
+            }
+        }
+        else {
+            log(`running ${claim.gig_id} COLD — ${coldReason}`);
+            res = await run(false);
+        }
+        if (res.status === "awaiting_approval") {
+            const awaiting = res.awaiting;
+            log(`gig ${claim.gig_id} awaiting approval` +
+                (awaiting ? ` at human chair "${awaiting.role}" (phase "${awaiting.phase}")` : "") +
+                ` — ${res.outputs.length} sealed output(s)`);
+            try {
+                const released = await parkGig(ctx, claim.gig_id);
+                if (!released) {
+                    log(`park not recorded for ${claim.gig_id} (coltrane_mcp_gig_park absent or the row moved) — the drained header carries awaiting_approval`);
+                }
+            }
+            catch (pe) {
+                // Same posture as an unrecordable failure: say it, and let the lease expire.
+                log(`could not park ${claim.gig_id} (lease will expire): ${pe instanceof Error ? pe.message : String(pe)}`);
+            }
+            return {
+                claimed: true, gig_id: claim.gig_id, status: "awaiting_approval",
+                outputs_count: res.outputs.length,
+                ...(awaiting ? { awaiting } : {}),
+            };
+        }
+        log(`gig ${claim.gig_id} ${res.status} — ${res.outputs.length} sealed output(s)`);
+        return { claimed: true, gig_id: claim.gig_id, status: "complete", outputs_count: res.outputs.length };
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        log(`gig ${claim.gig_id} failed: ${message}`);
+        try {
+            await failGig(ctx, claim.gig_id, message);
+        }
+        catch (fe) {
+            // The failure could not even be recorded — surface both; the lease will expire.
+            log(`could not record failure (lease will expire): ${fe instanceof Error ? fe.message : String(fe)}`);
+        }
+        return { claimed: true, gig_id: claim.gig_id, status: "failed", error: message };
+    }
+}
+//# sourceMappingURL=worker.js.map