@eir-labs/coltrane 0.23.1 → 0.24.0

package/dist/src/cli.d.ts

@@ -31,7 +31,7 @@ export interface CliIO {
     /** Injected for tests. Production reads stdin for `--input -`. */
     stdin?: () => string;
 }
-export declare const USAGE = "coltrane 0.23.1\n\n  coltrane validate                     load the genome; exit non-zero on load errors\n  coltrane dispatch <standard>          run a standard\n  coltrane monitor <gig-id>             report a gig's progress\n  coltrane logs <gig-id>                per-chair logs for a gig\n  coltrane abort <gig-id>               stop a running gig\n  coltrane trace <output-id>            walk an output's provenance\n  coltrane simulate <standard>          cost/shape a standard without running it\n  coltrane health                       engine + store health\n  coltrane serve                        run the MCP server on stdio\n  coltrane enqueue <standard>           queue a gig on the LOCAL file queue (no store, no key)\n                                        (env: COLTRANE_QUEUE_DIR \u2014 its absence is the whole\n                                         difference between local and hosted)\n  coltrane work                         claim one queued gig from the org store and run it\n  coltrane work --check                  report whether this box's drain environment is configured\n                                        and exit without claiming (0 ready, 1 not ready)\n                                        (env: COLTRANE_STORE_URL, COLTRANE_STORE_ANON,\n                                         COLTRANE_AGENT_TOKEN; results drain via\n                                         COLTRANE_DRAIN_URL + COLTRANE_DRAIN_KEY;\n                                         checkpoints under COLTRANE_WORKER_CHECKPOINTS,\n                                         default ~/.coltrane/worker-checkpoints;\n                                         exit 0 complete or parked, 1 failed, 3 queue empty)\n\nOptions\n  --input <json|@file|->                dispatch payload; @file reads a file, - reads stdin\n  --depth <skim|standard|deep>          tighten the per-chair turn cap\n  --budget <dollars>                    per-gig ceiling; the run stops when it is gone\n  --reuse                               allow chair-level reuse of prior sealed outputs\n  --resume <gig-id>                     continue a gig that died mid-pipeline\n  --approve <role>=<json|@file>         a human chair's verdict; repeat once per chair\n  --as <name>                           who is approving; sealed as the verdict's author\n  --wait                                block until the run finishes\n  --follow                              poll until the gig reaches a terminal state\n  --direction <upstream|downstream|both>  for trace\n  --json                                print the raw result to stdout\n  --genome <path>                       genome root (default: $COLTRANE_GENOME or cwd)\n  --help, --version\n\nA dispatch that reaches a chair a HUMAN holds parks: it names the waiting chair and exits 0,\nbecause a gig waiting on a person is not a failed gig. Approve it on the resume \u2014\n\n  coltrane dispatch <standard> --resume <gig> \\\n      --approve approve=@verdict.json --as eugene\n\n--input is NOT required on an approve-only resume: when every remaining chair is human the\ncheckpoint's recorded payload stands and the omission inherits it. If you DO pass --input it is\nchecked against the checkpoint, and a disagreement still refuses the resume.\n";
+export declare const USAGE = "coltrane 0.24.0\n\n  coltrane validate                     load the genome; exit non-zero on load errors\n  coltrane dispatch <standard>          run a standard\n  coltrane monitor <gig-id>             report a gig's progress\n  coltrane logs <gig-id>                per-chair logs for a gig\n  coltrane abort <gig-id>               stop a running gig\n  coltrane trace <output-id>            walk an output's provenance\n  coltrane simulate <standard>          cost/shape a standard without running it\n  coltrane health                       engine + store health\n  coltrane serve                        run the MCP server on stdio\n  coltrane enqueue <standard>           queue a gig on the LOCAL file queue (no store, no key)\n                                        (env: COLTRANE_QUEUE_DIR \u2014 its absence is the whole\n                                         difference between local and hosted)\n  coltrane work                         claim one queued gig from the org store and run it\n  coltrane work --check                  report whether this box's drain environment is configured\n                                        and exit without claiming (0 ready, 1 not ready)\n                                        (env: COLTRANE_STORE_URL, COLTRANE_STORE_ANON,\n                                         COLTRANE_AGENT_TOKEN; results drain via\n                                         COLTRANE_DRAIN_URL + COLTRANE_DRAIN_KEY;\n                                         checkpoints under COLTRANE_WORKER_CHECKPOINTS,\n                                         default ~/.coltrane/worker-checkpoints;\n                                         exit 0 complete or parked, 1 failed, 3 queue empty)\n\nOptions\n  --input <json|@file|->                dispatch payload; @file reads a file, - reads stdin\n  --depth <skim|standard|deep>          tighten the per-chair turn cap\n  --budget <dollars>                    per-gig ceiling; the run stops when it is gone\n  --reuse                               allow chair-level reuse of prior sealed outputs\n  --resume <gig-id>                     continue a gig that died mid-pipeline\n  --approve <role>=<json|@file>         a human chair's verdict; repeat once per chair\n  --as <name>                           who is approving; sealed as the verdict's author\n  --wait                                block until the run finishes\n  --follow                              poll until the gig reaches a terminal state\n  --direction <upstream|downstream|both>  for trace\n  --json                                print the raw result to stdout\n  --genome <path>                       genome root (default: $COLTRANE_GENOME or cwd)\n  --help, --version\n\nA dispatch that reaches a chair a HUMAN holds parks: it names the waiting chair and exits 0,\nbecause a gig waiting on a person is not a failed gig. Approve it on the resume \u2014\n\n  coltrane dispatch <standard> --resume <gig> \\\n      --approve approve=@verdict.json --as eugene\n\n--input is NOT required on an approve-only resume: when every remaining chair is human the\ncheckpoint's recorded payload stands and the omission inherits it. If you DO pass --input it is\nchecked against the checkpoint, and a disagreement still refuses the resume.\n";
 interface Parsed {
     cmd: string | undefined;
     positional: string[];

package/dist/src/fs_atomic.d.ts

@@ -1 +1,44 @@
 export declare function writeFileAtomic(file: string, text: string): void;
+/** The lock record — names WHO holds the tree, so a refusal can say who to wait on or abort. */
+export interface RepoLockRecord {
+    gig_id: string;
+    pid: number;
+    started_at: string;
+    genome_dir: string;
+}
+/** The outcome of a claim: the tree, or the live holder that refused it. */
+export type RepoLockAcquire = {
+    ok: true;
+    record: RepoLockRecord;
+    reacquired: boolean;
+} | {
+    ok: false;
+    held_by: RepoLockRecord;
+};
+/**
+ * The canonical lock path for a genome root: `<genomeDir>/.coltrane/repo-lock-<hex>.json`, where
+ * `<hex>` is a stable SHA-256 digest of the ABSOLUTE genome_dir truncated to 16 hex chars. The
+ * digest keeps the filename slash/space-free and bounded while the full path is preserved inside
+ * the record. `.coltrane/` is gitignored (beside the ledger and the mirror), so the artifact is a
+ * runtime lock, never committed.
+ */
+export declare function repoLockPath(genomeDir: string): string;
+/**
+ * Claim the per-repo lock for `genomeDir`, keyed on the resolved genome root.
+ *
+ * Atomic and exclusive via O_EXCL. On an existing destination:
+ *   - the SAME gig_id (a parked gig's own resume) re-acquires the tree it already holds;
+ *   - a LIVE holder refuses the claim, carrying `held_by`;
+ *   - a DEAD holder (or a torn file) is broken — recorded, unlinked — and the claim retried.
+ */
+export declare function acquireRepoLock(genomeDir: string, holder: {
+    gigId: string;
+    pid: number;
+    startedAt: string;
+}): RepoLockAcquire;
+/**
+ * Release the per-repo lock — but ONLY when the recorded holder is `gigId`. A release that finds a
+ * different holder never steals it (that lock belongs to another run). Returns whether a lock this
+ * gig held was actually removed.
+ */
+export declare function releaseRepoLock(genomeDir: string, gigId: string): boolean;

package/dist/src/fs_atomic.js

@@ -20,9 +20,9 @@
  * Two implementations of one concern, one of them documented and one of them absent, is the same
  * shape as the two identity gates that disagreed in the resume work.
  */
-import { mkdirSync, writeFileSync, renameSync } from "node:fs";
-import { dirname } from "node:path";
-import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync, renameSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { randomUUID, createHash } from "node:crypto";
 export function writeFileAtomic(file, text) {
     mkdirSync(dirname(file), { recursive: true });
     // randomUUID, not pid: two containers sharing a mounted volume routinely both have low pids,
@@ -31,4 +31,136 @@ export function writeFileAtomic(file, text) {
     writeFileSync(tmp, text, "utf8");
     renameSync(tmp, file);
 }
+/**
+ * The canonical lock path for a genome root: `<genomeDir>/.coltrane/repo-lock-<hex>.json`, where
+ * `<hex>` is a stable SHA-256 digest of the ABSOLUTE genome_dir truncated to 16 hex chars. The
+ * digest keeps the filename slash/space-free and bounded while the full path is preserved inside
+ * the record. `.coltrane/` is gitignored (beside the ledger and the mirror), so the artifact is a
+ * runtime lock, never committed.
+ */
+export function repoLockPath(genomeDir) {
+    const abs = resolve(genomeDir);
+    const hex = createHash("sha256").update(abs).digest("hex").slice(0, 16);
+    return join(abs, ".coltrane", `repo-lock-${hex}.json`);
+}
+function isCode(e, code) {
+    return typeof e === "object" && e !== null && e.code === code;
+}
+/** A holder pid is alive iff `process.kill(pid, 0)` does not throw ESRCH. EPERM means the process
+ *  exists but is not ours to signal — still alive. Any other error is treated conservatively as
+ *  alive so a transient fault never breaks a lock that might still be live. */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        if (isCode(e, "ESRCH"))
+            return false;
+        return true;
+    }
+}
+function readLockRecord(path) {
+    try {
+        const rec = JSON.parse(readFileSync(path, "utf8"));
+        if (rec && typeof rec.gig_id === "string" && typeof rec.pid === "number")
+            return rec;
+        return undefined;
+    }
+    catch {
+        return undefined; // ENOENT (raced away) or a torn/unparsable file — treat as no readable holder
+    }
+}
+/** Record a broken stale lock to stderr — never silent, so an operator can audit which dead gig's
+ *  grip was released and reclaimed. Shaped as a one-line JSON event like the gig milestone log. */
+function recordStaleBreak(dest, held) {
+    const line = JSON.stringify({
+        t: new Date().toISOString(),
+        ev: "repo_lock_stale_break",
+        stale_gig_id: held?.gig_id ?? "(unreadable)",
+        stale_pid: held?.pid ?? null,
+        reason: "holder pid not alive",
+        lock: dest,
+    });
+    try {
+        process.stderr.write(line + "\n");
+    }
+    catch {
+        /* best-effort — the break still happens; only its record is lost */
+    }
+}
+/**
+ * Claim the per-repo lock for `genomeDir`, keyed on the resolved genome root.
+ *
+ * Atomic and exclusive via O_EXCL. On an existing destination:
+ *   - the SAME gig_id (a parked gig's own resume) re-acquires the tree it already holds;
+ *   - a LIVE holder refuses the claim, carrying `held_by`;
+ *   - a DEAD holder (or a torn file) is broken — recorded, unlinked — and the claim retried.
+ */
+export function acquireRepoLock(genomeDir, holder) {
+    const dest = repoLockPath(genomeDir);
+    mkdirSync(dirname(dest), { recursive: true });
+    const record = {
+        gig_id: holder.gigId,
+        pid: holder.pid,
+        started_at: holder.startedAt,
+        genome_dir: resolve(genomeDir),
+    };
+    const payload = JSON.stringify(record);
+    // A small retry budget: each stale break unlinks and loops to re-create. More than one iteration
+    // is only reached under an active race (another process re-took the freed slot), which the next
+    // read resolves — never an unbounded spin.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            writeFileSync(dest, payload, { encoding: "utf8", flag: "wx" });
+            return { ok: true, record, reacquired: false };
+        }
+        catch (e) {
+            if (!isCode(e, "EEXIST"))
+                throw e;
+        }
+        const held = readLockRecord(dest);
+        if (held && held.gig_id === holder.gigId)
+            return { ok: true, record: held, reacquired: true };
+        if (held && pidAlive(held.pid))
+            return { ok: false, held_by: held };
+        // Dead holder or torn file — break it (recorded) and retry the exclusive create.
+        recordStaleBreak(dest, held);
+        try {
+            unlinkSync(dest);
+        }
+        catch (e) {
+            if (!isCode(e, "ENOENT"))
+                throw e;
+        }
+    }
+    // Exhausted the budget: another process keeps re-taking the freed slot. Refuse with the best
+    // holder we can read rather than clobber a live claim.
+    const held = readLockRecord(dest);
+    if (held && held.gig_id === holder.gigId)
+        return { ok: true, record: held, reacquired: true };
+    return { ok: false, held_by: held ?? record };
+}
+/**
+ * Release the per-repo lock — but ONLY when the recorded holder is `gigId`. A release that finds a
+ * different holder never steals it (that lock belongs to another run). Returns whether a lock this
+ * gig held was actually removed.
+ */
+export function releaseRepoLock(genomeDir, gigId) {
+    const dest = repoLockPath(genomeDir);
+    const held = readLockRecord(dest);
+    if (!held || held.gig_id !== gigId)
+        return false;
+    try {
+        unlinkSync(dest);
+        return true;
+    }
+    catch (e) {
+        if (isCode(e, "ENOENT"))
+            return false;
+        throw e;
+    }
+}
 //# sourceMappingURL=fs_atomic.js.map

package/dist/src/fs_atomic.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs_atomic.js","sourceRoot":"","sources":["../../src/fs_atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,6FAA6F;IAC7F,0FAA0F;IAC1F,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;IAC1C,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC"}
+{"version":3,"file":"fs_atomic.js","sourceRoot":"","sources":["../../src/fs_atomic.ts"],"names":[],"mappings":"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"}

package/dist/src/gig_tracker.d.ts

@@ -75,6 +75,16 @@ export interface GigRunState {
     /** Why. Surfaced by gig_monitor so `aborted` reads as a decision, not a mystery. */
     abort_reason?: string;
 }
+/**
+ * Is a gig's status TERMINAL — the run is over and holds the tree no longer?
+ *
+ * The single-flight per-repo lock (change c1d0c2e0) releases on exactly this set: complete, failed,
+ * and aborted. `awaiting_approval` is DELIBERATELY EXCLUDED — a parked gig is not terminal. It holds
+ * uncommitted work in the working tree (the chairs before the human gate already ran and left
+ * changes on disk) and will continue from that exact tree when approved, so it must RETAIN the lock
+ * while parked. Naming the terminal set here keeps the release site from re-deriving it and drifting.
+ */
+export declare function isTerminalStatus(status: GigStatus | string): boolean;
 export declare function newGigRun(gig_id: string, standard_slug: string, phases_total: number, now: string): GigRunState;
 export declare function applyGigProgress(state: GigRunState, ev: GigProgressEvent): void;
 /**

package/dist/src/gig_tracker.js

@@ -4,6 +4,18 @@
 // runtime fires GigProgressEvents as it walks the phase graph; this module folds those into
 // a GigRunState that gig_monitor reads. State is in-memory (per server lifetime): a restart
 // drops in-flight tracking — acceptable for v0, and a restart mid-gig is its own problem.
+/**
+ * Is a gig's status TERMINAL — the run is over and holds the tree no longer?
+ *
+ * The single-flight per-repo lock (change c1d0c2e0) releases on exactly this set: complete, failed,
+ * and aborted. `awaiting_approval` is DELIBERATELY EXCLUDED — a parked gig is not terminal. It holds
+ * uncommitted work in the working tree (the chairs before the human gate already ran and left
+ * changes on disk) and will continue from that exact tree when approved, so it must RETAIN the lock
+ * while parked. Naming the terminal set here keeps the release site from re-deriving it and drifting.
+ */
+export function isTerminalStatus(status) {
+    return status === "complete" || status === "failed" || status === "aborted";
+}
 export function newGigRun(gig_id, standard_slug, phases_total, now) {
     return {
         gig_id, standard_slug, status: "running", started_at: now,

package/dist/src/gig_tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"gig_tracker.js","sourceRoot":"","sources":["../../src/gig_tracker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gig_tracker.js","sourceRoot":"","sources":["../../src/gig_tracker.ts"],"names":[],"mappings":"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"}

package/dist/src/server.js

@@ -43,7 +43,8 @@ import { readFileSync, existsSync, mkdirSync, appendFileSync, readdirSync, write
 import { randomUUID, createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
-import { newGigRun, applyGigProgress, gigEventLogLine, pruneGigRuns } from "./gig_tracker.js";
+import { newGigRun, applyGigProgress, gigEventLogLine, pruneGigRuns, isTerminalStatus } from "./gig_tracker.js";
+import { acquireRepoLock, releaseRepoLock } from "./fs_atomic.js";
 import { isGig } from "./ledger.js";
 import { SubthreadRecorder, ApiVersionMismatchError } from "./subthread_recorder.js";
 import { canonJson, runFingerprint, CANONICAL_FORM_VERSION } from "./canonical_form.js";
@@ -96,6 +97,14 @@ function governanceRow(event, subject_slug, detail, subject_gig_id) {
         finished_at: now,
     };
 }
+/** The prose a single-flight refusal teaches a human: WHO holds the tree, and the two ways out
+ *  (wait for it to settle, or abort it). The machine-readable holder rides in `data.held_by`. */
+function heldTreeError(held) {
+    return (`the working tree at "${held.genome_dir}" is held by a running gig "${held.gig_id}" ` +
+        `(pid ${held.pid}, since ${held.started_at}). Single-flight is law: a second dispatch against ` +
+        `the same repository is REFUSED — it does not queue and does not wait. Let that gig reach a ` +
+        `terminal state, or abort it with gig_abort "${held.gig_id}".`);
+}
 const KNOWN_SLUGS = new Set(MCP_TOOLS.map((t) => t.slug));
 // Live registry of admissible tool slugs — the cage gate for agent_define's
 // allowed_tools. Seeded with the static MCP_TOOLS surface; tool_register grows
@@ -887,9 +896,41 @@ async function runImpl(slug, args, deps, approval) {
                         ...(res.gates_approved ? { gates_approved: res.gates_approved } : {}),
                         ...(res.resumed ? { resumed: res.resumed } : {}),
                     });
+                    // The gig id the whole performance runs under — minted ONCE for both the wait and async
+                    // doors, so the single-flight lock names the same holder either way.
+                    const chartGigId = resumeArg ?? randomUUID();
+                    // ── single-flight: ONE lock for the CHART's full lifetime, never per-movement ──────────
+                    // A chart runs its movements sequentially under one promise. The lock is claimed ONCE here
+                    // (holder = the chart's own gig_id) BEFORE the first movement and released only when the
+                    // performance settles. A per-movement acquire/release would either open a gap between
+                    // movements where a concurrent dispatch could slip in, or deadlock movement 2 against the
+                    // lock movement 1 still holds. Released on every terminal outcome; RETAINED through
+                    // awaiting_approval (a parked performance holds uncommitted work in the tree).
+                    let releaseChartLock;
+                    let chartLockReacquired = false; // re-entered a parked performance's own lock, vs freshly minted
+                    if (deps.genome_dir) {
+                        const acq = acquireRepoLock(deps.genome_dir, {
+                            gigId: chartGigId, pid: process.pid, startedAt: new Date().toISOString(),
+                        });
+                        if (!acq.ok) {
+                            return {
+                                ok: false, requires_approval: approval, refusal: "repo_locked",
+                                error: heldTreeError(acq.held_by), data: { held_by: acq.held_by },
+                            };
+                        }
+                        chartLockReacquired = acq.reacquired;
+                        const genomeDir = deps.genome_dir;
+                        releaseChartLock = () => { try {
+                            releaseRepoLock(genomeDir, chartGigId);
+                        }
+                        catch { /* best-effort */ } };
+                    }
                     if (wait) {
                         try {
-                            const res = await runChart(plan, gigInput, chartDeps);
+                            const res = await runChart(plan, gigInput, { ...chartDeps, gig_id: chartGigId });
+                            // Terminal (complete / budget-exhausted) frees the tree; a parked chart RETAINS it.
+                            if (releaseChartLock && res.status !== "awaiting_approval")
+                                releaseChartLock();
                             return {
                                 ok: true, requires_approval: approval,
                                 data: {
@@ -902,9 +943,15 @@ async function runImpl(slug, args, deps, approval) {
                         }
                         catch (e) {
                             if (e instanceof ResumeRefused) {
+                                // A re-entered lock belongs to the parked performance; a fresh one is freed here.
+                                if (releaseChartLock && !chartLockReacquired)
+                                    releaseChartLock();
                                 return { ok: false, requires_approval: approval, error: e.message,
                                     data: { resume_refused: true, gig_id: e.gig_id, drift: e.drift } };
                             }
+                            // Any other terminal throw (budget exhausted, a movement failed) frees the tree.
+                            if (releaseChartLock)
+                                releaseChartLock();
                             if (e instanceof BudgetExhausted) {
                                 const partial = partialGigUsage(e);
                                 return { ok: false, requires_approval: approval, error: e.message,
@@ -917,7 +964,6 @@ async function runImpl(slug, args, deps, approval) {
                     // Async, the default. Same live-state row an async standard dispatch registers, so
                     // gig_monitor and gig_abort reach a performance exactly as they reach a run: the row
                     // names the standard the performance OPENS with, and `chart_slug` names the arrangement.
-                    const chartGigId = resumeArg ?? randomUUID();
                     const chartRuns = deps.gig_runs ?? (deps.gig_runs = new Map());
                     const priorChartState = chartRuns.get(chartGigId);
                     const chartState = newGigRun(chartGigId, plan.movements[0].standard.slug, plan.movements.reduce((n, m) => n + m.standard.phases.length, 0), new Date().toISOString());
@@ -993,7 +1039,14 @@ async function runImpl(slug, args, deps, approval) {
                             chartState.budget_state = bs;
                         onChartProgress({ type: "gig_failed", error: chartState.error });
                     })
-                        .finally(() => { chartState.controller = undefined; });
+                        .finally(() => {
+                        chartState.controller = undefined; // don't pin a controller past settle
+                        // Free the tree on every terminal outcome (complete / failed / aborted); a parked
+                        // performance RETAINS it. A refused resume that re-entered a parked holder's lock
+                        // leaves it held; one that minted a fresh lock still frees it.
+                        if (releaseChartLock && isTerminalStatus(chartState.status) && !(chartRefusal && chartLockReacquired))
+                            releaseChartLock();
+                    });
                     if (resumeArg !== undefined) {
                         await Promise.resolve(); // one turn — see the ordering note on the standard path below
                         if (chartRefusal) {
@@ -1040,14 +1093,50 @@ async function runImpl(slug, args, deps, approval) {
                     venue, venues: deps.venues, venueRealizer: deps.venueRealizer,
                     repoUrl: dispatchRepoUrl,
                 });
+                // The gig id this run seals under — minted ONCE for both doors so the single-flight lock
+                // names the same holder whether the caller blocked (wait:true) or polled (async default).
+                const gigId = resumeArg ?? randomUUID();
+                // ── single-flight: claim the working tree BEFORE any chair runs ─────────────────────────
+                // Every LOCAL dispatch entry point funnels here (the in-process gig_dispatch tool AND the
+                // CLI, which calls dispatchTool). The lock is per genome ROOT (deps.genome_dir): two gigs
+                // against the same tree each derive their sealed change-set from `git diff` of a tree the
+                // other mutates, so the second is REFUSED — never queued — with a structured error naming
+                // the holder. A parked gig's OWN resume (same gig_id) re-enters the tree it already holds.
+                // The lock activates only when a genome_dir is present: a hosted/bare-deps drain carries no
+                // local tree to lock and is unaffected by construction.
+                let releaseLock;
+                // Did this claim RE-ENTER a lock the same gig already held (a parked gig's own resume), as
+                // opposed to minting a fresh one? A refused resume must NOT free a re-entered lock (the
+                // parked holder keeps its tree), but MUST free a fresh one (nothing else holds it).
+                let lockReacquired = false;
+                if (deps.genome_dir) {
+                    const acq = acquireRepoLock(deps.genome_dir, {
+                        gigId, pid: process.pid, startedAt: new Date().toISOString(),
+                    });
+                    if (!acq.ok) {
+                        return {
+                            ok: false, requires_approval: approval, refusal: "repo_locked",
+                            error: heldTreeError(acq.held_by), data: { held_by: acq.held_by },
+                        };
+                    }
+                    lockReacquired = acq.reacquired;
+                    const genomeDir = deps.genome_dir;
+                    releaseLock = () => { try {
+                        releaseRepoLock(genomeDir, gigId);
+                    }
+                    catch { /* best-effort */ } };
+                }
                 // Synchronous mode (opt-in via wait:true) — block, return the manifest. The
                 // deterministic test path and any caller that wants the answer in one call.
                 if (wait) {
                     try {
                         const res = await runGig(standard, gigInput, {
-                            ...dispatchDeps,
+                            ...dispatchDeps, gig_id: gigId,
                             ...(depth ? { depth } : {}), ...reuseWiring, ...humanWiring,
                         });
+                        // Terminal (complete) frees the tree; a parked gig (awaiting_approval) RETAINS it.
+                        if (releaseLock && res.status !== "awaiting_approval")
+                            releaseLock();
                         return {
                             ok: true, requires_approval: approval,
                             data: {
@@ -1069,11 +1158,18 @@ async function runImpl(slug, args, deps, approval) {
                     }
                     catch (e) {
                         // A refused resume is a REFUSAL, not a crash: nothing ran, nothing was spent, and
-                        // the caller needs the drift list to decide whether to re-dispatch cold.
+                        // the caller needs the drift list to decide whether to re-dispatch cold. The holder it
+                        // re-entered is unchanged, so the tree is NOT freed here.
                         if (e instanceof ResumeRefused) {
+                            // Free only a FRESH claim; a re-entered lock belongs to the parked holder, untouched.
+                            if (releaseLock && !lockReacquired)
+                                releaseLock();
                             return { ok: false, requires_approval: approval, error: e.message,
                                 data: { resume_refused: true, gig_id: e.gig_id, drift: e.drift } };
                         }
+                        // Every other terminal throw (budget exhausted, a chair failed) frees the tree.
+                        if (releaseLock)
+                            releaseLock();
                         if (e instanceof BudgetExhausted) {
                             // #236 — the synchronous half: a depleted gig also burned real dollars before it
                             // stopped, and the operator needs them in the same reply as the depletion notice.
@@ -1091,8 +1187,8 @@ async function runImpl(slug, args, deps, approval) {
                 // A resumed run CONTINUES the gig it resumes — same id — so the restored outputs stay
                 // in-gig and `output_trace` still reaches them. The live-state entry for the earlier
                 // attempt is replaced: that gig is running again, and showing its old `failed` state
-                // while it runs would be a lie the operator acts on.
-                const gigId = resumeArg ?? randomUUID();
+                // while it runs would be a lie the operator acts on. (`gigId` was minted above, before the
+                // wait/async split, so the single-flight lock names this same id.)
                 const runs = deps.gig_runs ?? (deps.gig_runs = new Map());
                 // #278 review — keep the prior attempt's record so a REFUSED resume can put it back.
                 // Overwriting it is right when the resume proceeds (that gig is running again), and
@@ -1203,7 +1299,15 @@ async function runImpl(slug, args, deps, approval) {
                         state.budget_state = bs;
                     onProgress({ type: "gig_failed", error: state.error });
                 })
-                    .finally(() => { state.controller = undefined; }); // don't pin a controller past settle
+                    .finally(() => {
+                    state.controller = undefined; // don't pin a controller past settle
+                    // Free the tree on every terminal outcome (complete / failed / aborted); a parked gig
+                    // (awaiting_approval) RETAINS it — it holds uncommitted work the resume continues from.
+                    // A refused resume that RE-ENTERED a parked holder's lock leaves it held; a refused
+                    // resume that minted a FRESH lock still frees it (nothing else holds that tree).
+                    if (releaseLock && isTerminalStatus(state.status) && !(resumeRefusal && lockReacquired))
+                        releaseLock();
+                });
                 if (resumeArg !== undefined) {
                     await Promise.resolve(); // one turn — see the ordering note above
                     if (resumeRefusal) {