toolroll 0.9.60 → 0.9.62

package/dist/worktree.d.ts

@@ -52,6 +52,32 @@ export type LeaseRequest = {
      * stands, as its kept checkout would have been reused. Without it, `base` always starts a new branch (and an
      * existing one refuses). */
     reuseBranch?: boolean;
+    /**
+     * Start from current main (fresh base): a checkout still at its recorded base — no commits of its own — and with no
+     * changes moves, with its branch, to `main` before the attempt. Anything else is never moved; the result says how
+     * far behind main it is. Needs `taskRef`. `recordedBase` null means no attempt on the branch recorded one yet, and
+     * then only a HEAD that main already contains counts as having no commits of its own.
+     */
+    freshBase?: {
+        main: string;
+        recordedBase: string | null;
+    };
+};
+/** Where a checkout stands against current main once its lease is granted (fresh base). */
+export type BaseStanding = {
+    /** HEAD as the attempt starts. */
+    head: string;
+    /** Current main's commit. */
+    main: string;
+    /** Commits on main that HEAD does not have. */
+    behind: number;
+    /** Set when this lease moved the checkout to main: where it was, and how far behind that was. */
+    moved: {
+        from: string;
+        behind: number;
+    } | null;
+    /** Why a checkout behind main stayed where it is. */
+    kept: "has commits" | "has changes" | "not on its branch" | null;
 };
 export type LeaseResult = {
     ok: true;
@@ -60,6 +86,8 @@ export type LeaseResult = {
     reclaimed?: string;
     resumedFromRun?: number;
     recoveryKind?: "completed" | "partial";
+    /** With `freshBase`: where the checkout stands against main (null when main could not be read). */
+    base?: BaseStanding | null;
 } | {
     ok: false;
     reason: LeaseFailure;
@@ -76,6 +104,13 @@ export type KeptWhy = "has changes" | "has commits" | "unreadable" | "git refuse
  * something is in there.
  */
 export declare const MARKER = ".standing-orders-lease";
+/**
+ * The reflog message of a branch Toolroll created, naming it: its creation entry is the proof, later, that the branch
+ * is Toolroll's and how old it is. A branch copied or renamed from it names the old branch, so it proves nothing.
+ */
+export declare const branchCreatedMessage: (branch: string) => string;
+/** Scouts' disposable branches: never landed work. */
+export declare const SCOUT_PREFIX = "toolroll-scout/";
 /** What a kept checkout drops once its run ends (only where .gitignore hides it): dependencies and build output. */
 export declare const SLIM_NAMES: readonly string[];
 /** Creating a worktree copies a tree; it is local work but not instant. */
@@ -114,6 +149,8 @@ export declare class WorktreePool {
     private readonly store;
     private readonly options;
     private readonly runner;
+    /** Carried to the independent storage sweep process. */
+    get root(): string;
     constructor(store: Store, options: PoolOptions);
     /**
      * Take a working copy for this branch.
@@ -155,6 +192,13 @@ export declare class WorktreePool {
     recordProviderOccupancy(path: string, runner: string, providerPid: number, leaseEpoch?: string | null): void;
     lease(request: LeaseRequest): Promise<LeaseResult>;
     private leaseNow;
+    /**
+     * Move an untouched checkout to current main, or say how far behind it is. Untouched means all three: on its own
+     * branch, HEAD still the recorded base (or, with none recorded, a commit main already has), and nothing changed or
+     * untracked. The move is `git reset --keep`, which refuses rather than overwrite anything; HEAD and the tree are read
+     * again right before and after it, and any surprise fails the lease with the checkout left for a person.
+     */
+    private freshen;
     /**
      * A crash can strand either a finished handoff or a partial source draft.
      * The expired lease can no longer authorize a commit, so this never ingests
@@ -243,10 +287,11 @@ export declare class WorktreePool {
     /**
      * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
      * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
-     * lease since keeps it) and `inspect` finds it clean. Only the working copy goes: its branch, and so every commit,
+     * lease since keeps it) and `inspect` finds it clean, then clean still right before it goes (git refuses an edit
+     * made after that). Only the working copy goes: its branch, and so every commit,
      * stays, and a later lease of the same branch makes a new one. At most `max` go per pass.
      */
-    prune(rows: readonly WorktreeRow[], wanted: (row: WorktreeRow, fresh: boolean) => boolean, max?: number): Promise<{
+    prune(rows: readonly WorktreeRow[], wanted: (row: WorktreeRow, fresh: boolean) => boolean | Promise<boolean>, max?: number): Promise<{
         removed: WorktreeRow[];
         kept: {
             path: string;
@@ -278,8 +323,17 @@ export declare class WorktreePool {
         ok: false;
         message: string;
     }>;
-    /** Remove one idle checkout's working copy (the caller holds it in `busy`) and forget its row. */
+    /** Throw away one idle checkout's working copy, changes and all (the caller holds it in `busy`), and forget its row.
+     * Only `discardChanges`, where losing them is what a person asked for. */
     private removeWorkingCopy;
+    /**
+     * Remove one idle checkout's working copy only while it is still clean (the caller holds it in `busy`, and its
+     * reservation outside the checkout holds it for other processes): inspected once more right before it goes, then
+     * removed without --force, so git itself refuses an edit made since. Only Toolroll's own files go first, because
+     * git's check would count them.
+     */
+    private removeCleanCopy;
+    private forgetRemoved;
     /**
      * Whether anybody's work is in there. null means we could not tell, which is
      * neither clean nor dirty and must not be rounded to either.

package/dist/worktree.js

@@ -23,7 +23,7 @@
  * over `.git` internals corrupts both.
  */
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync, rmSync, realpathSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, rmSync, realpathSync, mkdirSync, readdirSync, renameSync } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
 import { run } from "./exec.js";
@@ -40,8 +40,70 @@ import { markNeverIndex } from "./never-index.js";
  * something is in there.
  */
 export const MARKER = ".standing-orders-lease";
+/**
+ * The reflog message of a branch Toolroll created, naming it: its creation entry is the proof, later, that the branch
+ * is Toolroll's and how old it is. A branch copied or renamed from it names the old branch, so it proves nothing.
+ */
+export const branchCreatedMessage = (branch) => `Toolroll created branch ${branch}`;
+/** Scouts' disposable branches: never landed work. */
+export const SCOUT_PREFIX = "toolroll-scout/";
 /** Checkouts this process is leasing or removing right now: a lease and storage retention never overlap on one. */
 const busy = new Map();
+// Outside the checkout so removal cannot erase the reservation before git and the row update finish.
+const reservationPath = (path) => `${path}.occupancy`;
+function reservation(path) {
+    try {
+        const note = JSON.parse(readFileSync(reservationPath(path), "utf8"));
+        if (Number.isSafeInteger(note.pid) && note.pid > 0 && typeof note.host === "string" && typeof note.token === "string")
+            return note;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+    }
+    // An unreadable reservation is occupied, never a reason to delete someone's checkout.
+    return { pid: 0, host: "unknown", bootId: null, token: "unknown" };
+}
+function reservationAlive(note) {
+    if (note.pid === 0 || note.host !== hostname())
+        return true;
+    if (note.bootId !== null && provenDeadByBootChange(note))
+        return false;
+    try {
+        process.kill(note.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/** A short store transaction arbitrates marker creation/recovery, never git, a scan or deletion.
+ * Atomic rename publishes a complete owner; a crash cannot leave a half-written reservation. */
+function reserveCheckout(store, path) {
+    const note = { pid: process.pid, host: hostname(), bootId: currentBootId(), token: randomBytes(12).toString("hex") };
+    const file = reservationPath(path), temp = `${file}.${note.token}`;
+    const held = store.transact(() => {
+        const prior = reservation(path);
+        if (prior !== null && reservationAlive(prior))
+            return false;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(temp, JSON.stringify(note), { flag: "wx", mode: 0o600 });
+            renameSync(temp, file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    });
+    if (!held)
+        return null;
+    return () => store.transact(() => { if (reservation(path)?.token === note.token)
+        rmSync(file, { force: true }); });
+}
 /** What a kept checkout drops once its run ends (only where .gitignore hides it): dependencies and build output. */
 export const SLIM_NAMES = ["node_modules", "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".turbo", ".parcel-cache", "coverage", "target"];
 /** Creating a worktree copies a tree; it is local work but not instant. */
@@ -94,6 +156,9 @@ export function recordWorktreeProcess(store, path, runner, pid, leaseEpoch) {
 }
 /** Read-only occupancy witness shared with stop settlement. */
 export function worktreeProcessOccupancy(path) {
+    const reserved = reservation(path);
+    if (reserved !== null && (reserved.pid !== process.pid || reserved.host !== hostname()) && reservationAlive(reserved))
+        return { held: true, by: reserved.pid };
     const note = join(path, MARKER);
     if (!existsSync(note))
         return { held: false };
@@ -176,6 +241,8 @@ export class WorktreePool {
     store;
     options;
     runner;
+    /** Carried to the independent storage sweep process. */
+    get root() { return this.options.root; }
     constructor(store, options) {
         this.store = store;
         this.options = options;
@@ -237,17 +304,18 @@ export class WorktreePool {
     }
     async lease(request) {
         const target = worktreePath(this.options.root, request.repo, request.branch);
-        if (busy.get(target) === "removing")
-            return { ok: false, reason: "in-use", message: `${target} is being removed; try again in a moment` };
-        const mine = !busy.has(target);
-        if (mine)
-            busy.set(target, "leasing");
+        if (busy.has(target))
+            return { ok: false, reason: "in-use", message: `${target} is busy; try again in a moment` };
+        const release = reserveCheckout(this.store, target);
+        if (release === null)
+            return { ok: false, reason: "in-use", message: `${target} is busy; try again in a moment` };
+        busy.set(target, "leasing");
         try {
             return await this.leaseNow(request);
         }
         finally {
-            if (mine)
-                busy.delete(target);
+            release();
+            busy.delete(target);
         }
     }
     async leaseNow(request) {
@@ -346,17 +414,34 @@ export class WorktreePool {
             catch { /* git reports it */ }
             markNeverIndex(this.options.root);
             markNeverIndex(dirname(path));
-            const add = await this.git(request.repo, [
-                "worktree",
-                "add",
-                ...(fromBase ? ["-b", request.branch] : []),
-                path,
-                ...(fromBase ? [request.base] : [request.branch]),
-            ]);
+            // A new branch is created first, on its own, so its reflog's first entry says Toolroll made it and when.
+            let made = null;
+            if (fromBase) {
+                const base = await this.git(request.repo, ["rev-parse", "--verify", "--quiet", `${request.base}^{commit}`], READ_ONLY);
+                const oid = base.stdout.trim();
+                if (base.code !== 0 || !/^[0-9a-f]{40,64}$/.test(oid))
+                    return { ok: false, reason: "git", message: `git couldn't find ${request.base}` };
+                const branch = await this.git(request.repo, ["update-ref", "--create-reflog", "-m", branchCreatedMessage(request.branch), `refs/heads/${request.branch}`, oid, "0".repeat(oid.length)]);
+                if (branch.code !== 0)
+                    return { ok: false, reason: "git", message: firstLine(branch.stderr) };
+                made = oid;
+            }
+            const add = await this.git(request.repo, ["worktree", "add", path, request.branch]);
             if (add.code !== 0) {
+                if (made !== null)
+                    await this.git(request.repo, ["update-ref", "-d", `refs/heads/${request.branch}`, made]);
                 return { ok: false, reason: "git", message: firstLine(add.stderr) };
             }
         }
+        // Fresh base, inside the same reservation as everything above: nothing else leases, prunes or slims this
+        // checkout between the inspection and the move.
+        let base;
+        if (request.freshBase !== undefined && request.taskRef !== undefined) {
+            const fresh = await this.freshen(path, request.branch, request.taskRef, request.freshBase, request.now);
+            if (!fresh.ok)
+                return { ok: false, reason: "git", message: fresh.message };
+            base = fresh.standing;
+        }
         const row = {
             path,
             repo: request.repo,
@@ -392,8 +477,50 @@ export class WorktreePool {
             ...(reclaimed === undefined ? {} : { reclaimed }),
             ...(resumedFromRun === undefined ? {} : { resumedFromRun }),
             ...(recoveryKind === undefined ? {} : { recoveryKind }),
+            ...(base === undefined ? {} : { base }),
         };
     }
+    /**
+     * Move an untouched checkout to current main, or say how far behind it is. Untouched means all three: on its own
+     * branch, HEAD still the recorded base (or, with none recorded, a commit main already has), and nothing changed or
+     * untracked. The move is `git reset --keep`, which refuses rather than overwrite anything; HEAD and the tree are read
+     * again right before and after it, and any surprise fails the lease with the checkout left for a person.
+     */
+    async freshen(path, branch, taskRef, fresh, now) {
+        const read = async (args) => {
+            const out = await this.runner(GIT, [...READ_ONLY, ...args], { cwd: path, timeoutMs: WORKTREE_TIMEOUT_MS });
+            return out.code === 0 ? out.stdout.trim() : null;
+        };
+        const main = await read(["rev-parse", "--verify", "--quiet", `${fresh.main}^{commit}`]);
+        const head = await read(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+        if (main === null || head === null)
+            return { ok: true, standing: null };
+        const count = await read(["rev-list", "--count", `${head}..${main}`]);
+        const behind = count === null ? NaN : Number(count);
+        if (!Number.isSafeInteger(behind))
+            return { ok: true, standing: null };
+        const stay = (kept) => ({ ok: true, standing: { head, main, behind, moved: null, kept } });
+        if (behind === 0)
+            return stay(null);
+        if (await read(["symbolic-ref", "-q", "HEAD"]) !== `refs/heads/${branch}`)
+            return stay("not on its branch");
+        if (fresh.recordedBase !== null && fresh.recordedBase !== head)
+            return stay("has commits");
+        const contained = await this.runner(GIT, [...READ_ONLY, "merge-base", "--is-ancestor", head, main], { cwd: path, timeoutMs: WORKTREE_TIMEOUT_MS });
+        if (contained.code !== 0)
+            return stay("has commits");
+        if (await this.isDirty(path) !== false)
+            return stay("has changes");
+        // Recorded before git moves it: a move that then fails leaves the next attempt's own base as the branch's origin.
+        this.store.recordBranchBaseMove(taskRef, branch, head, main, now);
+        const moved = await this.runner(GIT, ["reset", "--keep", main], { cwd: path, timeoutMs: WORKTREE_TIMEOUT_MS });
+        const after = await read(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+        const branchNow = await read(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}^{commit}`]);
+        if (moved.code !== 0 || after !== main || branchNow !== main || await this.isDirty(path) !== false) {
+            return { ok: false, message: `${path} could not be moved to current main (${firstLine(moved.stderr) || "it changed during the move"}) — leaving it for a person` };
+        }
+        return { ok: true, standing: { head: main, main, behind: 0, moved: { from: head, behind }, kept: null } };
+    }
     /**
      * A crash can strand either a finished handoff or a partial source draft.
      * The expired lease can no longer authorize a commit, so this never ingests
@@ -678,7 +805,8 @@ export class WorktreePool {
     /**
      * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
      * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
-     * lease since keeps it) and `inspect` finds it clean. Only the working copy goes: its branch, and so every commit,
+     * lease since keeps it) and `inspect` finds it clean, then clean still right before it goes (git refuses an edit
+     * made after that). Only the working copy goes: its branch, and so every commit,
      * stays, and a later lease of the same branch makes a new one. At most `max` go per pass.
      */
     async prune(rows, wanted, max = Infinity) {
@@ -688,7 +816,10 @@ export class WorktreePool {
         for (const row of rows) {
             if (removed.length >= max)
                 break;
-            if (row.releasedAt === null || row.runner !== null || busy.has(row.path) || !wanted(row, false))
+            if (row.releasedAt === null || row.runner !== null || busy.has(row.path))
+                continue;
+            const selected = wanted(row, false);
+            if (!(typeof selected === "boolean" ? selected : await selected))
                 continue;
             if (!existsSync(row.path) || !idle(row, row.releasedAt))
                 continue;
@@ -699,20 +830,28 @@ export class WorktreePool {
             }
             if (busy.has(row.path))
                 continue;
+            const release = reserveCheckout(this.store, row.path);
+            if (release === null)
+                continue;
             busy.set(row.path, "removing");
             try {
                 // A lease, or a task coming back, since the listing wins: look again right before removing.
                 const now = this.store.getWorktree(row.path);
-                if (!idle(now, row.releasedAt) || !wanted(now, true))
+                if (!idle(now, row.releasedAt))
                     continue;
-                const gone = await this.removeWorkingCopy(row);
-                if (!gone) {
-                    kept.push({ path: row.path, why: "git refused" });
+                // Landed cleanup rechecks Git here; existing synchronous guards keep their synchronous path.
+                const allowed = wanted(now, true);
+                if (!(typeof allowed === "boolean" ? allowed : await allowed))
+                    continue;
+                const gone = await this.removeCleanCopy(row);
+                if (gone !== "removed") {
+                    kept.push({ path: row.path, why: gone });
                     continue;
                 }
                 removed.push(row);
             }
             finally {
+                release();
                 busy.delete(row.path);
             }
         }
@@ -735,6 +874,9 @@ export class WorktreePool {
             .filter(one => { const name = one.split("/").at(-1); return SLIM_NAMES.includes(name) && (deps || name !== "node_modules"); });
         if (drop.length === 0)
             return { ok: true, dropped: [], bytes: 0 };
+        const release = reserveCheckout(this.store, row.path);
+        if (release === null)
+            return { ok: false, message: `${row.path} is in use` };
         busy.set(row.path, "removing");
         const note = join(row.path, MARKER);
         let held = false;
@@ -759,6 +901,7 @@ export class WorktreePool {
         finally {
             if (held)
                 rmSync(note, { force: true });
+            release();
             busy.delete(row.path);
         }
     }
@@ -775,8 +918,14 @@ export class WorktreePool {
         const occupied = this.inUse(path);
         if (occupied.held)
             return { ok: false, message: `${path} is being used by process ${occupied.by} — it can't be discarded now` };
+        const release = reserveCheckout(this.store, path);
+        if (release === null)
+            return { ok: false, message: `${path} is in use` };
         busy.set(path, "removing");
         try {
+            const fresh = this.store.getWorktree(path);
+            if (fresh === null || fresh.runner !== null || fresh.releasedAt !== row.releasedAt || this.inUse(path).held)
+                return { ok: false, message: `${path} is in use` };
             if (!existsSync(path)) {
                 this.store.transact(() => { const still = this.store.getWorktree(path); if (still !== null && still.runner === null && still.releasedAt === row.releasedAt)
                     this.store.forgetWorktree(path); });
@@ -785,10 +934,12 @@ export class WorktreePool {
             return (await this.removeWorkingCopy(row)) ? { ok: true, row } : { ok: false, message: `git would not remove ${path}` };
         }
         finally {
+            release();
             busy.delete(path);
         }
     }
-    /** Remove one idle checkout's working copy (the caller holds it in `busy`) and forget its row. */
+    /** Throw away one idle checkout's working copy, changes and all (the caller holds it in `busy`), and forget its row.
+     * Only `discardChanges`, where losing them is what a person asked for. */
     async removeWorkingCopy(row) {
         // Held while it goes: another process's lease sees this process in it (the busy map is this process's only).
         const note = join(row.path, MARKER);
@@ -803,12 +954,39 @@ export class WorktreePool {
             rmSync(note, { force: true });
             return false;
         }
+        this.forgetRemoved(row);
+        return true;
+    }
+    /**
+     * Remove one idle checkout's working copy only while it is still clean (the caller holds it in `busy`, and its
+     * reservation outside the checkout holds it for other processes): inspected once more right before it goes, then
+     * removed without --force, so git itself refuses an edit made since. Only Toolroll's own files go first, because
+     * git's check would count them.
+     */
+    async removeCleanCopy(row) {
+        const found = await this.inspect(row.path);
+        if (found !== "clean")
+            return found;
+        const status = await this.runner(GIT, [...READ_ONLY, "status", "--porcelain", "--untracked-files=all"], { cwd: row.path, timeoutMs: WORKTREE_TIMEOUT_MS });
+        if (status.code !== 0)
+            return "unreadable";
+        for (const line of status.stdout.split("\n")) {
+            const name = line.startsWith("?? ") ? line.slice(3).trim() : "";
+            if (name === MARKER || (name !== "" && looksLikeProtocolFile(name)))
+                rmSync(join(row.path, name), { recursive: true, force: true });
+        }
+        const gone = await this.git(row.repo, ["worktree", "remove", row.path]);
+        if (gone.code !== 0)
+            return (await this.isDirty(row.path)) === false ? "git refused" : "has changes";
+        this.forgetRemoved(row);
+        return "removed";
+    }
+    forgetRemoved(row) {
         this.store.transact(() => {
             const still = this.store.getWorktree(row.path);
             if (still !== null && still.runner === null && still.releasedAt === row.releasedAt)
                 this.store.forgetWorktree(row.path);
         });
-        return true;
     }
     /**
      * Whether anybody's work is in there. null means we could not tell, which is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.60",
+  "version": "0.9.62",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"