harness-dispatch 0.7.9 → 0.9.0

package/dist/workspaces.js

@@ -1,7 +1,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, existsSync } from "node:fs";
-import { copyFile, mkdir, readdir, readFile, readlink, rm, stat, symlink, } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, readdir, readFile, readlink, realpath, rm, stat, symlink, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -34,7 +34,17 @@ export function isIsolatedWorkspacePolicy(policy) {
 function safeName(value) {
     return value.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 80) || "route";
 }
-function workspaceRunId(routeName) {
+/**
+ * Exported for tests, which must build run directories with the SAME function
+ * that makes real ones rather than by hand.
+ *
+ * Three separate tests in this repo used a hand-written name the product
+ * cannot generate — run directories with four-character suffixes where a real
+ * one has eight hex — and each therefore asserted something about an input
+ * that never occurs. Two of them passed while the bug they claimed to cover
+ * was live. A fixture is only evidence if it is the thing.
+ */
+export function workspaceRunId(routeName) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     return `${stamp}-${process.pid}-${safeName(routeName)}-${randomUUID().slice(0, 8)}`;
 }
@@ -70,12 +80,22 @@ function resolveDir(workingDir) {
  * HARNESS_DISPATCH_WORKSPACES_DIR overrides it for anyone who wants the
  * workspaces on the project's volume.
  */
-/** The directory all per-project workspace roots hang off. */
-function workspacesBase() {
+/**
+ * The directory all per-project workspace roots hang off.
+ *
+ * Exported because the apply-time dirty check has to know it too: with the
+ * override pointed inside the project — which README recommends, to keep the
+ * copy on one volume for reflinks — the workspaces directory is itself an
+ * untracked change, so `apply` refused on an otherwise pristine tree, every
+ * time. The same "feature blocked by its own leftovers" the recursion guard
+ * above was written for, one step further along.
+ */
+export function workspacesBase() {
     return (process.env.HARNESS_DISPATCH_WORKSPACES_DIR ??
         path.join(os.tmpdir(), "harness-dispatch", "workspaces"));
 }
-function workspaceRootFor(originalWorkingDir) {
+/** Exported for tests, for the same reason as `workspaceRunId`. */
+export function workspaceRootFor(originalWorkingDir) {
     const base = workspacesBase();
     // The per-project segment applies to the override too. Without it, every
     // project pointed at one HARNESS_DISPATCH_WORKSPACES_DIR shared a flat
@@ -88,6 +108,305 @@ function workspaceRootFor(originalWorkingDir) {
     // basename stays in the name so the directory is still recognisable by eye.
     return path.join(base, `${safeName(path.basename(originalWorkingDir))}-${pathKey(originalWorkingDir)}`);
 }
+/**
+ * Written into every project root this tool creates, so reclamation can delete
+ * a directory because it KNOWS it made it rather than because the name looks
+ * about right.
+ *
+ * The previous attempt matched the generated name shape, `-[0-9a-f]{8}$`. Eight
+ * decimal digits are valid hex, so any `<name>-<YYYYMMDD>` collided: a second
+ * acceptance pass planted `backup-20260401/data.bin` beside directories that
+ * survived and watched one dispatch delete it recursively. A heuristic cannot
+ * answer "did I create this" — only a mark can.
+ */
+const ROOT_MARKER = ".harness-dispatch-root";
+/**
+ * The shape `workspaceRunId` generates: an ISO stamp, pid, route, 8 hex.
+ * Used ONLY to recognise roots created before the marker existed, so those are
+ * still reclaimed instead of leaking forever.
+ */
+const RUN_DIR_RE = /^\d{4}-\d{2}-\d{2}T[\d-]+Z-\d+-.+-[0-9a-f]{8}$/;
+/**
+ * Bring an existing workspace root up to 0700, and refuse one we do not own.
+ *
+ * Two separate problems, both POSIX-only, both found by an acceptance pass
+ * measuring the shipped `mode:` fix on real Linux rather than trusting it:
+ *
+ *   ALREADY THERE — `mkdir`'s mode applies only to directories it creates, so
+ *     an existing 0755 root stayed 0755. Every pre-existing user was
+ *     unaffected by the "fix". An explicit chmod is the only thing that
+ *     changes them.
+ *   SOMEBODY ELSE'S — the root path is fully deterministic
+ *     (`<tmp>/harness-dispatch/workspaces/<basename>-<hash of path>`) inside a
+ *     SHARED `os.tmpdir()`, so on the multi-user machine this whole guard
+ *     exists for, another local user can create it first. Then it is theirs:
+ *     chmod fails, and copying the project into it would hand them the
+ *     source. That is not a mode to fix, it is a directory to refuse.
+ *
+ * Throws on the second case. `markProjectRoot`'s caller treats a marker
+ * failure as harmless — correctly, a root without its marker is merely not
+ * auto-reclaimed — but "another user owns the directory I am about to copy
+ * your code into" is not in that category and must not be swallowed.
+ *
+ * Windows is skipped deliberately: `uid` is 0 for every process, Node ignores
+ * mode, and `os.tmpdir()` is already per-user there.
+ */
+/**
+ * Build the workspace root one segment at a time, and hand back the path that
+ * was actually created.
+ *
+ * THIS REPLACES A CHECK-THEN-USE GUARD, and the replacement is the point. Four
+ * consecutive releases patched a validator that inspected a path STRING and
+ * then let the rest of the module re-resolve that same string on every write.
+ * Each patch closed the hole it was shown and left the shape intact, so the
+ * next pass found another one:
+ *
+ *   - `stat` followed the link it was checking (release 1);
+ *   - the guard was applied to one of the two isolation policies (release 2);
+ *   - it inspected only the last path segment (release 3);
+ *   - it stopped AT `workspacesBase()` and never looked at that directory's
+ *     own parent — the one the release notes said it now checked;
+ *   - it compared with `startsWith` against an un-normalised base, so a
+ *     trailing slash or a `..` in HARNESS_DISPATCH_WORKSPACES_DIR turned the
+ *     whole guard off silently;
+ *   - and validating once left every later write re-resolving the string, so
+ *     swapping a directory for a link DURING the copy redirected it (3,877
+ *     files landed in an attacker's directory in the reproduction).
+ *
+ * So the rule is no longer "look at the path and then trust it". Every segment
+ * from the anchor down is CREATED BY US with a non-recursive mkdir, which
+ * cannot traverse a link we did not make: if something is already there,
+ * `mkdir` fails and we inspect it deliberately rather than following it. The
+ * verified, fully-resolved directory is then RETURNED, and callers use that
+ * value instead of re-deriving the string.
+ *
+ * The anchor is the directory the user chose (HARNESS_DISPATCH_WORKSPACES_DIR)
+ * or the system temp directory. Above it is not ours to police —
+ * `os.tmpdir()` is legitimately a symlink on macOS (`/var` -> `/private/var`),
+ * which is exactly why the anchor is RESOLVED rather than refused. Everything
+ * below it is ours, and a link there is refused.
+ *
+ * What this still does not give: `mkdir`/`lstat` name a path, not an open
+ * handle, so a sufficiently fast swap between two syscalls remains
+ * theoretically possible — Node exposes no `openat`/`O_NOFOLLOW`. The window
+ * is now one syscall rather than the whole dispatch, and every destructive
+ * operation re-verifies (see `assertStillOurs`) instead of trusting a check
+ * made minutes earlier.
+ */
+async function verifySegment(dir) {
+    const info = await lstat(dir);
+    // Symlink check on EVERY platform. This was skipped entirely on Windows for
+    // a stated reason that covers only the ownership half — uid is 0 there and
+    // mode is ignored. Junctions need no privileges, `lstat` reports them as
+    // symbolic links, and a junction planted at the workspace path was measured
+    // taking a whole project into the victim's directory on this maintainer's
+    // own machine.
+    if (info.isSymbolicLink()) {
+        throw new Error(`${dir} is a symbolic link, and this tool never creates one there. Refusing to use ` +
+            `it: following it would put your project — and this tool's recursive cleanup — ` +
+            `wherever the link points. Remove it, or set HARNESS_DISPATCH_WORKSPACES_DIR to a ` +
+            `location you control.`);
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`${dir} exists and is not a directory. Refusing to use it as a workspace location. ` +
+            `Remove it, or set HARNESS_DISPATCH_WORKSPACES_DIR to a location you control.`);
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined && info.uid !== uid) {
+        throw new Error(`${dir} is owned by another user (uid ${info.uid}, this process is uid ${uid}). ` +
+            `Refusing to put your project beneath it: this path is predictable, so a directory ` +
+            `you do not own may have been created there deliberately. Remove it, or set ` +
+            `HARNESS_DISPATCH_WORKSPACES_DIR to a location you control.`);
+    }
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+        await chmod(dir, 0o700);
+}
+/**
+ * Re-check, immediately before a destructive or bulk operation, that a
+ * directory verified earlier is still the one we verified.
+ *
+ * The old code validated once at the start of a dispatch and then trusted the
+ * path string for everything that followed. This is the narrow version of that
+ * trust: it costs one `lstat` and it turns "checked minutes ago" into "checked
+ * a syscall ago".
+ */
+export async function assertStillOurs(dir) {
+    await verifySegment(dir);
+}
+/**
+ * The anchor, resolved. Above this we do not police; below it we do.
+ *
+ * `path.resolve` is what fixes the guard being silently inert for a
+ * HARNESS_DISPATCH_WORKSPACES_DIR written with a trailing slash or containing
+ * `..` — the old comparison was `startsWith` against the raw string, so those
+ * spellings failed to match and the loop body never ran even once.
+ */
+async function resolvedAnchor() {
+    const configured = process.env.HARNESS_DISPATCH_WORKSPACES_DIR;
+    const anchor = configured !== undefined ? path.resolve(configured) : os.tmpdir();
+    // VERIFY THE NEAREST EXISTING ANCESTOR BEFORE CREATING ANYTHING.
+    //
+    // Creating the anchor first was still a "touch, then check": with a link at
+    // `<tmp>/hd`, a recursive mkdir of `<tmp>/hd/workspaces` traversed it and
+    // left an empty directory inside the attacker's tree before the refusal
+    // arrived. Small, but it is the same mistake in miniature — and this
+    // function exists to stop making it.
+    //
+    // Walking up to what already exists, resolving THAT, and checking who owns
+    // it means the first thing we create is created somewhere we have already
+    // vouched for.
+    let existing = anchor;
+    while (!existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            break;
+        existing = parent;
+    }
+    // realpath here, not lstat: the anchor is allowed to BE a link, because
+    // os.tmpdir() is one on macOS (`/var` -> `/private/var`) and a user pointing
+    // the override at a link is making a choice about their own machine. What
+    // must hold is that wherever it lands belongs to us.
+    const resolvedExisting = await realpath(existing);
+    const info = await lstat(resolvedExisting);
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined && info.uid !== uid && info.uid !== 0) {
+        throw new Error(`${resolvedExisting} is owned by another user (uid ${info.uid}, this process is uid ` +
+            `${uid}), and the workspace location resolves beneath it. Refusing to create ` +
+            `anything there. Set HARNESS_DISPATCH_WORKSPACES_DIR to a location you control.`);
+    }
+    // Segments computed in DECLARED space and created in DECLARED space.
+    //
+    // Computing them between the resolved ancestor and the declared anchor
+    // produced `..` components whenever the two differed — i.e. on every macOS
+    // machine — and the loop then walked upwards creating nonsense. The resolve
+    // happens once, at the end, after the chain exists.
+    const relative = path.relative(existing, path.resolve(anchor));
+    let current = existing;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            await mkdir(current, { mode: 0o700 });
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            await verifySegment(current);
+        }
+    }
+    // BOTH values are returned, and the distinction is load-bearing.
+    //
+    // `declared` is what the rest of the module derives paths from
+    // (`workspacesBase()` builds on the unresolved `os.tmpdir()`), and
+    // `resolved` is where those paths actually land. Comparing a declared target
+    // against the RESOLVED anchor is wrong on macOS, where `os.tmpdir()` is
+    // `/var/folders/...` and resolves to `/private/var/folders/...`: every
+    // legitimate run then looks like it is outside the anchor and is refused.
+    // Caught in a container before CI, by running the macOS path shape
+    // deliberately rather than assuming POSIX is POSIX.
+    return { declared: path.resolve(anchor), resolved: await realpath(current) };
+}
+/**
+ * Create and verify every segment from the anchor down to `root`, and return
+ * the verified path.
+ */
+export async function prepareVerifiedRoot(root) {
+    const anchor = await resolvedAnchor();
+    const target = path.resolve(root);
+    // Relative to the DECLARED anchor (how the caller built the path), then
+    // created beneath the RESOLVED one (where it really lives).
+    const relative = path.relative(anchor.declared, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        // Not beneath the anchor at all. Only reachable if the caller derived the
+        // path from something other than workspacesBase(); refusing beats
+        // silently operating outside the area this function can vouch for.
+        throw new Error(`Refusing to use ${target} as a workspace location: it is not beneath ` +
+            `${anchor.declared}, so this tool cannot vouch for the path it would write and ` +
+            `delete under.`);
+    }
+    let current = anchor.resolved;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        // Non-recursive on purpose: a recursive mkdir traverses whatever is
+        // already there, including a link. This creates each level itself, so the
+        // only way a link enters the chain is if it existed first — in which case
+        // mkdir fails with EEXIST and we inspect it rather than following it.
+        try {
+            await mkdir(current, { mode: 0o700 });
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            await verifySegment(current);
+            continue;
+        }
+    }
+    return current;
+}
+/**
+ * Create the project's workspace root and mark it as ours, returning the
+ * VERIFIED path that was actually created.
+ *
+ * Callers must use the returned value rather than the string they passed in.
+ * That is the whole change: the old signature returned nothing, so every
+ * caller went on using its own copy of the path and re-resolved it on each
+ * write — which is how a directory swapped for a symlink mid-copy redirected
+ * the rest of it.
+ *
+ * The MARKER stays best effort: a root without one is merely not reclaimed
+ * automatically, which is the safe direction to fail in. Creating and
+ * verifying the directory is not, and must not be swallowed.
+ */
+async function markProjectRoot(root) {
+    const verified = await prepareVerifiedRoot(root);
+    try {
+        const marker = path.join(verified, ROOT_MARKER);
+        if (!existsSync(marker)) {
+            await writeFile(marker, "Created by harness-dispatch. This directory and its dated run\n" +
+                "subdirectories are managed — and eventually deleted — by it.\n", "utf8");
+        }
+    }
+    catch {
+        // A root without its marker is merely not reclaimed automatically, which
+        // is the safe direction to fail in.
+    }
+    return verified;
+}
+/**
+ * Is this directory one we created, and therefore ours to delete?
+ *
+ * The marker settles it. The fallback covers roots created before the marker
+ * existed: every child must be a generated run directory, and there must be at
+ * least one — an empty unmarked directory is somebody else's empty directory,
+ * not ours. A foreign directory passes only if everything inside it happens to
+ * be named like a timestamped run, which is not a thing that happens by
+ * accident. This deletes recursively and has now been wrong twice, so it takes
+ * positive evidence rather than the absence of a reason to stop.
+ */
+const PROJECT_ROOT_RE = /^.+-[0-9a-f]{8}$/;
+function isOurProjectRoot(full, children) {
+    // The NAME must fit too, not just the marker.
+    //
+    // The marker is an ordinary file, and anything that can write to the
+    // workspaces base can create one — including a delegated agent, when
+    // HARNESS_DISPATCH_WORKSPACES_DIR points inside the project, which README
+    // recommends and the walkthrough exercises. An acceptance pass used exactly
+    // that to get an unrelated directory holding the only copy of its contents
+    // recursively deleted.
+    //
+    // Requiring the generated shape as WELL as the marker does not make this
+    // unforgeable — a name is guessable and the marker is writable — but it
+    // turns "create a file called .harness-dispatch-root" into "also name the
+    // directory the way pathKey would have". Combined with the reclamation only
+    // ever running inside our own base, that is the honest limit of what a
+    // same-uid check can promise here: the caller and the attacker are the same
+    // user, so no permission check can separate them.
+    if (!PROJECT_ROOT_RE.test(path.basename(full)))
+        return false;
+    if (existsSync(path.join(full, ROOT_MARKER)))
+        return true;
+    const runs = children.filter((name) => name !== ROOT_MARKER);
+    return runs.length > 0 && runs.every((name) => RUN_DIR_RE.test(name));
+}
 /** Short stable digest of a project path, to keep same-named projects apart. */
 function pathKey(dir) {
     return createHash("sha256").update(path.resolve(dir)).digest("hex").slice(0, 8);
@@ -121,6 +440,19 @@ function workspaceMaxAgeMs() {
  */
 async function pruneStaleCopyWorkspaces(root, copyProjectGitRoot) {
     const maxAgeMs = workspaceMaxAgeMs();
+    // Before the early return below: a project dispatching for the FIRST time
+    // has no root of its own to sweep, and that is exactly the caller most
+    // likely to be running on a machine full of other projects' leftovers.
+    // The base is derived from `root`, NOT from workspacesBase().
+    //
+    // `root` is now the VERIFIED, fully-resolved path, while `workspacesBase()`
+    // returns the DECLARED one. On any machine where the two differ — every
+    // macOS box, since `os.tmpdir()` resolves through `/private` — the
+    // "exclude our own root" comparison inside this sweep compared strings from
+    // two different spaces, failed to match, and deleted the directory the
+    // dispatch had just created. Caught in a container running the macOS path
+    // shape; it would have been a total failure of `copy` on macOS.
+    await pruneAbandonedProjectRoots(path.dirname(root), root);
     let entries;
     try {
         entries = await readdir(root, { withFileTypes: true });
@@ -133,6 +465,18 @@ async function pruneStaleCopyWorkspaces(root, copyProjectGitRoot) {
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        // Only directories WE named. This loop deletes recursively and had no
+        // check of any kind — not a name, not a marker, not an owner — while its
+        // sibling `pruneAbandonedProjectRoots` has all three under a comment
+        // saying "this deletes directories nothing else is watching". With a
+        // symlink planted at the root, that gap swept a user's own files.
+        //
+        // The same guard `pruneStaleJobs` already uses, and for the same reason:
+        // a recursive delete takes positive evidence that the thing is ours,
+        // rather than the absence of a reason to stop. `RUN_DIR_RE` is the exact
+        // shape `workspaceRunId` generates.
+        if (!RUN_DIR_RE.test(entry.name))
+            continue;
         const full = path.join(root, entry.name);
         try {
             const info = await stat(full);
@@ -161,8 +505,103 @@ async function pruneStaleCopyWorkspaces(root, copyProjectGitRoot) {
         await git(["worktree", "prune"], copyProjectGitRoot).catch(() => undefined);
     }
 }
+/**
+ * Reclaim the per-project directories of projects that never dispatch again.
+ *
+ * The sweep above only ever looks INSIDE one project's root, and only runs
+ * when a dispatch happens for that same project. So a project dispatched once
+ * and then renamed, deleted, or — most commonly — created as a temp directory
+ * by the test suite keeps its stale runs forever: the code that would reclaim
+ * them is reachable only by the project that no longer exists.
+ *
+ * Measured on the maintainer's machine before this existed: 840 project roots,
+ * 839 of them still holding run directories five days past a 24-hour
+ * retention window. This project has already lost a disk to leaked scratch
+ * directories once — tests/setup-env.ts records 2,605 orphans and 0 bytes free
+ * on a 931 GB volume — which is why an unbounded leak gets fixed rather than
+ * noted.
+ *
+ * Deliberately conservative, because this deletes directories nothing else is
+ * watching:
+ *  - never the caller's own root, which is about to be written into;
+ *  - only when EVERY run inside is past retention, so one live run keeps its
+ *    project root alive;
+ *  - an empty root is removed only if it carries our marker. Unmarked and
+ *    empty means there is nothing to identify it by, and an unidentified
+ *    directory is somebody else's — measured, because this line previously
+ *    claimed empty roots are removed full stop, which stopped being true when
+ *    ownership moved from a name shape to a marker;
+ *  - best effort throughout — a prune failure must never fail a dispatch.
+ *
+ * A git_worktree root is left alone here. Removing one behind git's back
+ * strands `.git/worktrees` metadata, and the sweep above only knows how to
+ * unregister worktrees for the repository the CURRENT dispatch belongs to.
+ */
+async function pruneAbandonedProjectRoots(base, currentRoot) {
+    const maxAgeMs = workspaceMaxAgeMs();
+    let entries;
+    try {
+        entries = await readdir(base, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = path.join(base, entry.name);
+        if (path.resolve(full) === path.resolve(currentRoot))
+            continue;
+        try {
+            const runs = await readdir(full, { withFileTypes: true });
+            // Age is not evidence of ownership, and this deletes recursively.
+            // HARNESS_DISPATCH_WORKSPACES_DIR is a setting the README actively
+            // recommends ("on the project's own volume, for instance"), so the base
+            // is not necessarily ours alone and anything else living there is
+            // somebody's data.
+            if (!isOurProjectRoot(full, runs.map((r) => r.name)))
+                continue;
+            let allStale = true;
+            for (const run of runs) {
+                if (run.name === ROOT_MARKER)
+                    continue;
+                const runPath = path.join(full, run.name);
+                // A worktree run needs git's own removal; leave the whole project
+                // root to the owning repository rather than stranding metadata.
+                if (existsSync(path.join(runPath, "worktree"))) {
+                    allStale = false;
+                    break;
+                }
+                const info = await stat(runPath);
+                if (now - info.mtimeMs <= maxAgeMs) {
+                    allStale = false;
+                    break;
+                }
+            }
+            if (allStale)
+                await rm(full, { recursive: true, force: true });
+        }
+        catch {
+            // best effort — locked, vanished, or permission-denied entries are skipped
+        }
+    }
+}
 async function pruneStaleGitWorktrees(gitRoot, root) {
     const maxAgeMs = workspaceMaxAgeMs();
+    // Same reclamation the copy path does, for a machine that only ever
+    // dispatches under git_worktree. Abandoned worktree roots are left alone by
+    // that sweep either way — see pruneAbandonedProjectRoots.
+    // The base is derived from `root`, NOT from workspacesBase().
+    //
+    // `root` is now the VERIFIED, fully-resolved path, while `workspacesBase()`
+    // returns the DECLARED one. On any machine where the two differ — every
+    // macOS box, since `os.tmpdir()` resolves through `/private` — the
+    // "exclude our own root" comparison inside this sweep compared strings from
+    // two different spaces, failed to match, and deleted the directory the
+    // dispatch had just created. Caught in a container running the macOS path
+    // shape; it would have been a total failure of `copy` on macOS.
+    await pruneAbandonedProjectRoots(path.dirname(root), root);
     let entries;
     try {
         entries = await readdir(root, { withFileTypes: true });
@@ -175,6 +614,11 @@ async function pruneStaleGitWorktrees(gitRoot, root) {
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        // Only directories WE named — the same guard the copy sweep and
+        // pruneStaleJobs use. This loop `rm -rf`s recursively and had no name,
+        // marker or ownership check of any kind.
+        if (!RUN_DIR_RE.test(entry.name))
+            continue;
         const workspaceRoot = path.join(root, entry.name);
         try {
             const info = await stat(workspaceRoot);
@@ -227,7 +671,7 @@ function shouldExclude(relPath, direntName) {
  * was spelled, and it covers the whole workspaces root rather than this run's
  * directory alone — a sibling run's workspace is no more copyable than our own.
  */
-function isUnderOrEqual(candidate, root) {
+export function isUnderOrEqual(candidate, root) {
     const c = path.resolve(candidate);
     const r = path.resolve(root);
     if (c === r)
@@ -279,7 +723,18 @@ async function copyLink(sourceRoot, destRoot, childRel, skipped) {
         // missing in-tree link is a far smaller problem than an escaping one.
     }
 }
-async function copyTree(sourceRoot, destRoot, rel = "", skipped = [], vanished = [], excludeRoots = []) {
+async function copyTree(sourceRoot, destRoot, rel = "", skipped = [], vanished = [], excludeRoots = [], 
+/**
+ * EXCLUDED_DIRS entries that actually existed and were left out. Collected
+ * because the omission was invisible: `bin`, `dist`, `build`, `target`,
+ * `obj` and `.venv` are all on that list and all plausible SOURCE
+ * directories, and an acceptance pass watched a delegate "edit" a committed
+ * `bin/tool.sh` that was never in its workspace — the run then reported one
+ * changed file, the patch held one file, and apply landed one file, with
+ * nothing anywhere saying the rest of the tree had been withheld. The agent
+ * also reasons from an incomplete tree, which is the worse half.
+ */
+excludedDirs = []) {
     const sourceDir = rel ? path.join(sourceRoot, rel) : sourceRoot;
     const destDir = rel ? path.join(destRoot, rel) : destRoot;
     await mkdir(destDir, { recursive: true });
@@ -288,12 +743,20 @@ async function copyTree(sourceRoot, destRoot, rel = "", skipped = [], vanished =
         const childRel = rel ? path.join(rel, entry.name) : entry.name;
         try {
             if (entry.isDirectory()) {
-                if (shouldExclude(childRel, entry.name))
+                if (shouldExclude(childRel, entry.name)) {
+                    // Only the name-list exclusions are reported. The workspaces-root
+                    // ones below are this tool's own scratch space and mean nothing to
+                    // the user; `.git` is excluded on every branch and would be noise on
+                    // every single run.
+                    if (EXCLUDED_DIRS.has(entry.name) && entry.name !== ".git") {
+                        excludedDirs.push(childRel.split(path.sep).join("/"));
+                    }
                     continue;
+                }
                 const childAbs = path.join(sourceDir, entry.name);
                 if (excludeRoots.some((root) => isUnderOrEqual(childAbs, root)))
                     continue;
-                await copyTree(sourceRoot, destRoot, childRel, skipped, vanished, excludeRoots);
+                await copyTree(sourceRoot, destRoot, childRel, skipped, vanished, excludeRoots, excludedDirs);
                 continue;
             }
             if (entry.isFile()) {
@@ -498,18 +961,34 @@ async function prepareCopyWorkspace(routeName, workingDir, files) {
     const projectGitRoot = await git(["rev-parse", "--show-toplevel"], originalWorkingDir)
         .then((out) => out || undefined)
         .catch(() => undefined);
-    await pruneStaleCopyWorkspaces(root, projectGitRoot);
-    const workspaceRoot = path.join(root, workspaceRunId(routeName));
+    // SECURE BEFORE PRUNING. The order was the other way round, and the guard
+    // could not protect the one operation that deletes: `pruneStaleCopyWorkspaces`
+    // ran first and `rm -rf`d every aged subdirectory of `root` — a root the
+    // guard had not yet looked at. With a symlink planted at that path, the
+    // victim's own directory was swept. Reproduced end to end.
+    //
+    // `markProjectRoot` is what creates and secures the root, so calling it
+    // first means the prune can only ever run against a directory that exists,
+    // is not a link, and belongs to this user.
+    // Everything below uses the VERIFIED path, not the string computed above.
+    // Re-deriving the string is what let a swapped directory redirect the copy.
+    const verifiedRoot = await markProjectRoot(root);
+    await pruneStaleCopyWorkspaces(verifiedRoot, projectGitRoot);
+    const workspaceRoot = path.join(verifiedRoot, workspaceRunId(routeName));
+    // Created here, and verified, rather than left to copyTree's recursive
+    // mkdir — the run directory is the segment an attacker would swap between
+    // the prune and the copy.
+    await mkdir(workspaceRoot, { recursive: false, mode: 0o700 });
+    await assertStillOurs(workspaceRoot);
     const effectiveWorkingDir = path.join(workspaceRoot, "workspace");
     const skippedLinks = [];
     const vanishedFiles = [];
+    const excludedDirs = [];
     // The whole workspaces BASE, not this run's directory and not even this
     // project's root under it. A sibling run's workspace is no more copyable
     // than our own, and another project's is no more copyable than a sibling's —
     // all of them sit inside the source tree whenever the override points there.
-    await copyTree(originalWorkingDir, effectiveWorkingDir, "", skippedLinks, vanishedFiles, [
-        workspacesBase(),
-    ]);
+    await copyTree(originalWorkingDir, effectiveWorkingDir, "", skippedLinks, vanishedFiles, [workspacesBase()], excludedDirs);
     const before = await fingerprintTree(effectiveWorkingDir);
     return {
         policy: "copy",
@@ -542,6 +1021,16 @@ async function prepareCopyWorkspace(routeName, workingDir, files) {
                                 `directory that was being written to.`,
                         ]
                         : []),
+                    ...(excludedDirs.length > 0
+                        ? [
+                            `${excludedDirs.length} director(ies) were NOT copied into the workspace and were ` +
+                                `invisible to the agent: ${excludedDirs.slice(0, 8).join(", ")}` +
+                                `${excludedDirs.length > 8 ? ", …" : ""}. These names are excluded as build ` +
+                                `output or dependencies, but some of them (bin, dist, build, target, obj) are ` +
+                                `real source directories in some projects — if the task needed one, the agent ` +
+                                `worked from an incomplete tree and no change to it can appear in the patch.`,
+                        ]
+                        : []),
                     ...(skippedLinks.length > 0
                         ? [
                             `Dropped ${skippedLinks.length} symlink(s) pointing outside the workspace, which would ` +
@@ -554,20 +1043,71 @@ async function prepareCopyWorkspace(routeName, workingDir, files) {
         },
     };
 }
+/**
+ * Decline git's OPTIONAL locks.
+ *
+ * git runs background maintenance, which creates and removes
+ * `.git/objects/maintenance.lock` underneath whatever else is reading the
+ * repository. A CI leg failed with `stat '.../maintenance.lock': No such file
+ * or directory` from an ordinary diff — the lock vanished mid-command. We only
+ * ever ask git to read, or to apply a patch we already hold, so declining
+ * optional locks costs nothing and removes a race we do not control.
+ */
+export const GIT_ENV = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
 async function git(args, cwd) {
-    const { stdout } = await execFile("git", args, { cwd, windowsHide: true });
+    const { stdout } = await execFile("git", args, { cwd, windowsHide: true, env: GIT_ENV });
     return String(stdout).trim();
 }
 async function prepareGitWorktreeWorkspace(routeName, workingDir, files) {
     const originalWorkingDir = resolveDir(workingDir);
-    const gitRoot = await git(["rev-parse", "--show-toplevel"], originalWorkingDir);
+    // Preconditions answered as themselves, not as whatever git printed.
+    //
+    // The resolve path (`workspace diff`/`apply`) explains a missing git and a
+    // long path; the DISPATCH path had none of it, so the three ordinary ways
+    // this cannot start reached the caller as raw git internals with no route
+    // taken and no mention of the alternative — an acceptance pass measured
+    // `spawn git ENOENT`, `fatal: not a git repository`, and
+    // `fatal: ambiguous argument 'HEAD'` on a freshly-initialised project, which
+    // is an ordinary state rather than an error.
+    const gitRoot = await git(["rev-parse", "--show-toplevel"], originalWorkingDir).catch((err) => {
+        if (err?.code === "ENOENT") {
+            throw new Error("workspace_policy: git_worktree needs git on PATH, and it was not found. Install " +
+                "git, or use workspace_policy: copy, which needs no git. `doctor` reports whether " +
+                "it found one.");
+        }
+        throw new Error(`workspace_policy: git_worktree needs ${originalWorkingDir} to be inside a git ` +
+            `repository, and it is not. Use workspace_policy: copy for a directory that is not ` +
+            `version-controlled.`);
+    });
     const prefix = await git(["rev-parse", "--show-prefix"], originalWorkingDir);
     const gitWorkspaceRoot = gitWorkspaceRootFor(gitRoot);
-    await pruneStaleGitWorktrees(gitRoot, gitWorkspaceRoot);
-    const workspaceRoot = path.join(gitWorkspaceRoot, workspaceRunId(routeName));
+    // SECURE BEFORE PRUNING, exactly as the copy path does.
+    //
+    // This ordering fix and the name check inside the sweep were applied to
+    // `copy` only, so the identical attack still worked here: same predictable
+    // path, same delete-before-validate. Reproduced as two real users — with a
+    // symlink planted at the root, the copy policy refused and the worktree
+    // policy DELETED the victim's directory, then raised the guard's error
+    // afterwards. The release that fixed `copy` claimed the class was closed.
+    //
+    // Two policies, one hazard: whenever one of these gets a guard, check the
+    // other in the same edit.
+    // Same as the copy path: use the VERIFIED root from here down.
+    const verifiedGitRoot = await markProjectRoot(gitWorkspaceRoot);
+    await pruneStaleGitWorktrees(gitRoot, verifiedGitRoot);
+    const workspaceRoot = path.join(verifiedGitRoot, workspaceRunId(routeName));
     const worktreeRoot = path.join(workspaceRoot, "worktree");
-    await mkdir(workspaceRoot, { recursive: true });
-    const baseCommit = await git(["rev-parse", "HEAD"], gitRoot);
+    // Non-recursive, then verified: this run's directory holds the worktree
+    // checkout, i.e. the project's source, and it is the segment an attacker
+    // would swap between the prune and `git worktree add`.
+    await mkdir(workspaceRoot, { recursive: false, mode: 0o700 });
+    await assertStillOurs(workspaceRoot);
+    // A repository with no commits yet is an ordinary state, not a fault, and
+    // `git worktree add` has nothing to branch from in it.
+    const baseCommit = await git(["rev-parse", "HEAD"], gitRoot).catch(() => {
+        throw new Error(`workspace_policy: git_worktree needs at least one commit to branch a worktree from, ` +
+            `and ${gitRoot} has none yet. Make an initial commit, or use workspace_policy: copy.`);
+    });
     await git(["worktree", "add", "--detach", worktreeRoot, baseCommit], gitRoot);
     const effectiveWorkingDir = prefix ? path.join(worktreeRoot, prefix) : worktreeRoot;
     await stat(effectiveWorkingDir);
@@ -582,6 +1122,55 @@ async function prepareGitWorktreeWorkspace(routeName, workingDir, files) {
         async finish(result) {
             const after = await fingerprintTree(worktreeRoot);
             const changedFiles = diffFingerprints(before, after);
+            // A failed attempt that changed nothing leaves nothing to inspect, and
+            // its worktree is a registration inside the USER's repository that
+            // retention will never reclaim — the sweep deliberately refuses to
+            // remove worktrees, because unregistering one needs git and only the
+            // owning repo can do it.
+            //
+            // So they accumulate per attempt, and the ones nobody knows about are
+            // the worst: a fallback arm that fails is not named in the response at
+            // all, so its worktree has no cleanupHint anywhere. An acceptance pass
+            // measured one HTTP request leaving TWO entries in `git worktree list`.
+            // This project has already paid for one unbounded directory leak.
+            //
+            // Only when the attempt both failed AND changed nothing. A failure that
+            // wrote files may still hold work worth recovering, and deleting that
+            // to tidy up would be the trade this codebase keeps refusing.
+            if (!result.success && changedFiles.length === 0) {
+                // The directory goes only if GIT let go of it first.
+                //
+                // The first version swallowed the result of `git worktree remove`,
+                // deleted the directory regardless, and reported "unregistered and
+                // removed" either way. When git fails — an index lock, a concurrent
+                // git operation — that strands `.git/worktrees/<name>` inside the
+                // user's repository, which is the exact outcome the comment above
+                // says this refuses to cause, while telling them it did not happen.
+                // An acceptance pass caught it by reading, inside the fix that
+                // introduced it.
+                const unregistered = await git(["worktree", "remove", "--force", worktreeRoot], gitRoot)
+                    .then(() => true)
+                    .catch(() => false);
+                if (unregistered) {
+                    await rm(workspaceRoot, { recursive: true, force: true }).catch(() => undefined);
+                    return attachWorkspace(result, {
+                        policy: "git_worktree",
+                        originalWorkingDir,
+                        effectiveWorkingDir,
+                        baseCommit,
+                        isolated: true,
+                        securityBoundary: "project_state_and_process_cwd",
+                        changedFiles,
+                        diffSummary: diffSummary(changedFiles),
+                        notes: [
+                            "This attempt failed without changing any file, so its git worktree was " +
+                                "unregistered and removed rather than left in your repository.",
+                        ],
+                    });
+                }
+                // Fall through: git still owns it, so it is reported like any other
+                // retained worktree, with the hint that names how to remove it.
+            }
             return attachWorkspace(result, {
                 policy: "git_worktree",
                 originalWorkingDir,