harness-dispatch 0.4.0 → 0.6.0

package/dist/workspace-lock.js

@@ -0,0 +1,258 @@
+/**
+ * Mutual exclusion over a working directory, across processes.
+ *
+ * `workspace_policy: shared_locked` promises that two dispatches never edit
+ * one workspace at the same time. Until now that promise was implemented as a
+ * `Map` in module scope — real within a process, and every job used to get its
+ * OWN process, so concurrent jobs sharing a directory were free to clobber
+ * each other the entire time. The guarantee read correctly and did nothing.
+ * Pooling supervisors made it bind for jobs sharing a supervisor, which
+ * narrowed the hole to four ways instead of N but did not close it.
+ *
+ * Two layers, because they solve different halves:
+ *
+ *   1. An in-process promise chain. Fast, fair (FIFO by arrival), and it keeps
+ *      same-process waiters off the filesystem entirely.
+ *   2. A lock FILE, for everything the first layer cannot see. Created with
+ *      `wx`, which fails atomically if it already exists on both Windows and
+ *      POSIX.
+ *
+ * Lock files live in the state directory, keyed by a hash of the resolved
+ * path, rather than inside the workspace: a dispatcher should not drop
+ * bookkeeping files into a user's repository, where they would show up in
+ * `git status` and in the workspace diff the caller is handed back.
+ *
+ * A holder that dies must not wedge the directory forever, so the lock carries
+ * a heartbeat refreshed while held, and a lock whose heartbeat has gone stale
+ * is stolen. That is the same rule, and the same threshold, the job orphan
+ * check already uses — one staleness concept in the system, not two.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { stateRoot } from "./state-dir.js";
+/** Matches ORPHAN_THRESHOLD_MS in jobs.ts: one notion of "the holder is gone". */
+export const LOCK_STALE_MS = 90_000;
+/** How often a held lock refreshes its heartbeat. Comfortably inside the stale window. */
+const HEARTBEAT_MS = 15_000;
+/** Gap between attempts when another process holds the lock. */
+const RETRY_MS = 100;
+/**
+ * How long an EXISTING-but-unreadable lock file is given before it is treated
+ * as stealable. An unreadable record used to be stolen on sight, which made a
+ * torn read of a mid-rewrite heartbeat sufficient to take a LIVE holder's lock
+ * — two dispatches then edited the same workspace, the exact outcome
+ * `shared_locked` exists to prevent. Heartbeats are written atomically now, so
+ * within one build a torn read cannot happen; the grace keeps the steal honest
+ * against writers from older builds (in-place heartbeat rewrites during a
+ * rolling upgrade) and external interference.
+ */
+const UNREADABLE_GRACE_MS = 1_000;
+const inProcessLocks = new Map();
+function lockKey(workingDir) {
+    const resolved = path.resolve(workingDir || process.cwd());
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function lockFileFor(key) {
+    const dir = stateRoot();
+    const digest = createHash("sha256").update(key).digest("hex").slice(0, 16);
+    return path.join(dir, "workspace-locks", `${digest}.json`);
+}
+function readRecord(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed?.beatMs !== "number")
+            return undefined;
+        return { pid: Number(parsed.pid) || 0, key: String(parsed.key ?? ""), beatMs: parsed.beatMs };
+    }
+    catch {
+        // Unreadable or half-written: treat as absent, and let the staleness
+        // check below decide. A corrupt lock must not wedge the directory.
+        return undefined;
+    }
+}
+/** True if the recorded holder is definitely gone. */
+function isDead(record) {
+    if (Date.now() - record.beatMs > LOCK_STALE_MS)
+        return true;
+    if (record.pid > 0) {
+        try {
+            // Signal 0 tests for existence without touching the process.
+            process.kill(record.pid, 0);
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}
+function tryCreate(file, key) {
+    try {
+        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify({ pid: process.pid, key, beatMs: Date.now() }), {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Take a stale lock out of the way — by RENAME, not delete.
+ *
+ * Delete-then-recreate let two waiters both decide the same record was stale:
+ * the slower one's delete then removed the FASTER one's freshly created lock,
+ * and both ended up holding the directory. Rename is atomic and names a
+ * specific victim — whoever loses the rename gets ENOENT and simply goes
+ * round the acquire loop again. Returns true if this process performed the
+ * steal (the caller still has to win the `wx` create; a third waiter may get
+ * there first, which is an honest race, not a double hold).
+ */
+function stealLock(file) {
+    const tomb = `${file}.stolen-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        renameSync(file, tomb);
+    }
+    catch {
+        return false; // Another waiter stole it, or the holder released it first.
+    }
+    try {
+        rmSync(tomb, { force: true });
+    }
+    catch {
+        // A leftover tombstone is inert: nothing reads `*.stolen-*` names.
+    }
+    return true;
+}
+async function acquireFileLock(key, timeoutMs) {
+    const file = lockFileFor(key);
+    const deadline = Date.now() + timeoutMs;
+    let unreadableSince;
+    for (;;) {
+        if (tryCreate(file, key))
+            break;
+        const record = readRecord(file);
+        if (record === undefined) {
+            // Exists but unreadable (or vanished between the two calls). Give it a
+            // grace window rather than stealing on sight — see UNREADABLE_GRACE_MS.
+            unreadableSince ??= Date.now();
+            if (Date.now() - unreadableSince >= UNREADABLE_GRACE_MS) {
+                unreadableSince = undefined;
+                stealLock(file);
+                continue;
+            }
+        }
+        else {
+            unreadableSince = undefined;
+            if (isDead(record)) {
+                stealLock(file);
+                continue;
+            }
+        }
+        if (Date.now() >= deadline) {
+            // Proceeding unlocked would silently break the guarantee the caller
+            // asked for, so this is an error rather than a warning.
+            throw new Error(`workspace lock timed out after ${Math.round(timeoutMs / 1000)}s waiting for ` +
+                `pid ${record?.pid ?? "unknown"} to release ${key}. Another dispatch is still ` +
+                `using this workspace; use workspace_policy: copy to run them concurrently.`);
+        }
+        await new Promise((r) => setTimeout(r, RETRY_MS));
+    }
+    const beat = setInterval(() => {
+        // Refresh ATOMICALLY (tmp + rename), never by rewriting in place: an
+        // in-place rewrite truncates first, and a waiter reading in that window
+        // saw an empty record — grounds, under the old rules, to steal a lock
+        // whose holder was alive and mid-write.
+        //
+        // Ownership is checked first: if the record is no longer ours, this
+        // process froze past the stale window and was legitimately stolen.
+        // Overwriting would clobber the thief's record — and worse, make our own
+        // release() believe it still held the lock and delete it under the thief.
+        try {
+            const current = readRecord(file);
+            if (current !== undefined && current.pid !== process.pid) {
+                clearInterval(beat);
+                return;
+            }
+            if (current === undefined) {
+                // Missing or unreadable while we believe we hold it: a steal may be
+                // mid-flight. Recreating it could re-take a lock someone else now
+                // owns, so stop refreshing and let release()'s ownership check
+                // decide what to delete.
+                clearInterval(beat);
+                return;
+            }
+            const tmp = `${file}.${process.pid}.beat`;
+            writeFileSync(tmp, JSON.stringify({ pid: process.pid, key, beatMs: Date.now() }), {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+            renameSync(tmp, file);
+        }
+        catch {
+            // A failed refresh only risks the lock being stolen as stale, which is
+            // the correct outcome if this process really is in trouble. The next
+            // beat retries; a leftover .beat tmp file is inert.
+        }
+    }, HEARTBEAT_MS);
+    beat.unref?.();
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(beat);
+        try {
+            // Only remove it if we still hold it — a stolen lock now belongs to
+            // someone else and deleting it would hand the directory to a third
+            // party while the thief is mid-write.
+            const current = readRecord(file);
+            if (current === undefined || current.pid === process.pid) {
+                rmSync(file, { force: true });
+            }
+        }
+        catch {
+            // Left behind; it ages out via the staleness rule.
+        }
+    };
+}
+/**
+ * Take the lock for `workingDir`. Resolves once held; call the returned
+ * function to release.
+ *
+ * @param timeoutMs how long to wait for another process. Defaults to an hour,
+ * matching the job runtime ceiling — a legitimate holder can hold it that long.
+ */
+export async function acquireWorkspaceLock(workingDir, timeoutMs = 60 * 60 * 1000) {
+    const key = lockKey(workingDir);
+    // Layer 1: queue behind same-process waiters first, so a burst inside one
+    // supervisor costs one filesystem acquisition rather than N spinning ones.
+    const previous = inProcessLocks.get(key) ?? Promise.resolve();
+    let releaseLocal;
+    const current = previous.catch(() => undefined).then(() => new Promise((resolve) => {
+        releaseLocal = resolve;
+    }));
+    inProcessLocks.set(key, current);
+    await previous.catch(() => undefined);
+    // Layer 2: the cross-process lock.
+    let releaseFile;
+    try {
+        releaseFile = await acquireFileLock(key, timeoutMs);
+    }
+    catch (err) {
+        releaseLocal();
+        if (inProcessLocks.get(key) === current)
+            inProcessLocks.delete(key);
+        throw err;
+    }
+    return () => {
+        releaseFile();
+        releaseLocal();
+        if (inProcessLocks.get(key) === current)
+            inProcessLocks.delete(key);
+    };
+}
+//# sourceMappingURL=workspace-lock.js.map

package/dist/workspace-lock.js.map

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

package/dist/workspace-resolve.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What happens to isolated work AFTER the agent finishes.
+ *
+ * `copy` and `git_worktree` gave you a workspace path, a changed-file list and
+ * a `cleanupHint` — a string telling you to run `git worktree remove`
+ * yourself. Isolation worked and nothing was ever applied automatically, but
+ * there was no way to see the actual change, no way to keep it, and no way to
+ * clean up but by hand. Isolated dispatches were effectively write-only: you
+ * could look at a summary and then abandon the result.
+ *
+ * This module is the missing half — inspect, then keep or throw away.
+ *
+ * THE DANGEROUS PART IS `apply`, and it is dangerous in one specific way:
+ * applying a patch into a directory that has moved on since the agent started
+ * can conflict with, or silently overwrite, work the user did in the meantime.
+ * So apply refuses when the target has uncommitted changes unless the caller
+ * explicitly overrides, and it always writes the patch to disk first so there
+ * is a manual path (`git apply`) even when the automatic one declines.
+ */
+import type { WorkspaceRun } from "./types.js";
+/** Patches are read into memory and returned over MCP, so they are bounded. */
+export declare const MAX_PATCH_BYTES: number;
+/** How much of a patch is returned inline before it is truncated for display. */
+export declare const MAX_PATCH_CHARS = 60000;
+export declare function isResolvable(run: WorkspaceRun | undefined): run is WorkspaceRun;
+/**
+ * Produce a unified patch of what the agent changed, relative to the project
+ * root, so it applies with `git apply -p1` from `originalWorkingDir`.
+ *
+ * The two policies need different bases and getting this wrong is destructive:
+ *
+ *   git_worktree — diff against the COMMIT the worktree was created from.
+ *     A worktree starts at HEAD, not at the caller's working tree, so diffing
+ *     it against the original directory of a dirty project would report the
+ *     user's own uncommitted work as deletions.
+ *   copy — diff against the original directory, which is exactly what the
+ *     copy was made from, so the difference is the agent's work and nothing
+ *     else.
+ */
+export declare function buildWorkspacePatch(run: WorkspaceRun): Promise<string>;
+/**
+ * Rewrite `git diff --no-index` headers so the patch is repo-relative.
+ *
+ * --no-index emits the absolute paths it was given (`--- a/C:/long/path/...`),
+ * which applies nowhere but this machine. Rewriting them to a/<rel> and
+ * b/<rel> makes the patch portable and applicable with -p1, which is what
+ * every other git patch in the world expects.
+ */
+export declare function normaliseNoIndexPaths(patch: string, origRoot: string, isoRoot: string): string;
+export interface PatchResult {
+    jobId: string;
+    policy: WorkspaceRun["policy"];
+    /** Where the full patch was written, always, so there is a manual path. */
+    patchPath: string;
+    bytes: number;
+    /** Possibly truncated for display; patchPath always holds the whole thing. */
+    patch: string;
+    truncated: boolean;
+    changedFiles?: WorkspaceRun["changedFiles"];
+}
+/** Build the patch, cache it next to the job, and return it (bounded). */
+export declare function workspaceDiff(jobId: string, jobDir: string, run: WorkspaceRun): Promise<PatchResult>;
+export interface ApplyResult {
+    jobId: string;
+    applied: boolean;
+    patchPath: string;
+    message: string;
+    changedFiles?: WorkspaceRun["changedFiles"];
+}
+/**
+ * Apply the agent's work into the real project.
+ *
+ * Refuses by default when the target has uncommitted changes: the patch was
+ * built against a specific base, and applying it over work done since can
+ * conflict or clobber. `force` overrides, and the patch file is written
+ * either way so `git apply` by hand is always available.
+ */
+export declare function applyWorkspace(jobId: string, jobDir: string, run: WorkspaceRun, opts?: {
+    force?: boolean;
+}): Promise<ApplyResult>;
+export interface DiscardResult {
+    jobId: string;
+    discarded: boolean;
+    message: string;
+}
+/**
+ * Throw the isolated workspace away.
+ *
+ * A git worktree is not just a directory: `rm -rf` on it leaves the parent
+ * repository's worktree metadata behind, and git then complains about a
+ * missing worktree until someone runs `git worktree prune`. So worktrees are
+ * removed through git, with a filesystem sweep afterwards for the wrapper
+ * directory git does not own.
+ */
+export declare function discardWorkspace(jobId: string, run: WorkspaceRun): Promise<DiscardResult>;
+/** Read a previously written patch, if one was cached. */
+export declare function cachedPatch(jobDir: string): Promise<string | undefined>;
+//# sourceMappingURL=workspace-resolve.d.ts.map

package/dist/workspace-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-resolve.d.ts","sourceRoot":"","sources":["../src/workspace-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,+EAA+E;AAC/E,eAAO,MAAM,eAAe,QAAkB,CAAC;AAE/C,iFAAiF;AACjF,eAAO,MAAM,eAAe,QAAS,CAAC;AA4BtC,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,GAAG,IAAI,YAAY,CAE/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA0C5E;AAmFD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAwB9F;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;CAC7C;AAED,0EAA0E;AAC1E,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,WAAW,CAAC,CAiBtB;AA4BD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,OAAO,CAAC,WAAW,CAAC,CAiEtB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED,0DAA0D;AAC1D,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7E"}