toolroll 0.9.61 → 0.9.62

package/dist/store.js

@@ -355,6 +355,22 @@ CREATE TABLE IF NOT EXISTS run_activity (
   at   TEXT NOT NULL
 );
 `;
+/** A task branch moved to current main before an attempt (fresh base; v122, a new table: additive only): the branch
+ * had no commits of its own and no changes, so it started over from `to_rev`. `after_run` is the newest run id when it
+ * moved: the branch's whole-task diff runs from the first builder base recorded after it (firstBuilderBase), never from
+ * the older main it left. */
+export const BRANCH_BASE_MOVE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS branch_base_move (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_ref  INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,
+  branch    TEXT NOT NULL,
+  from_rev  TEXT NOT NULL,
+  to_rev    TEXT NOT NULL,
+  after_run INTEGER NOT NULL,
+  moved_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS branch_base_move_branch ON branch_base_move (task_ref, branch, id);
+`;
 /** Pausing a running Claude build (live steering, v121: additive only). A person's Pause asks the build to
  * stop its current turn and keep its session: one row per request, bound to the exact run it was asked of, under the
  * request id the asker chose (a repeated request is the same request). `note` is the steering note a Pause and steer
@@ -605,7 +621,10 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v121 adds, and changes no saved row: the Agents board (run.attempt_key; agent_turn, agent_now, agent_question,
 // agent_seen, agent_view), live steering (a note's live identity and sends, a run's stdin session; run_pause and
 // run_resume) and landed work's teardown journal (landed_cleanup, landed_cleanup_item).
-export const SCHEMA_VERSION = 121;
+// v122 adds, and changes no saved row: the remote URL an owner's project add recorded (project.remote_url), the only
+// remote whose main automatic completion trusts (remote-main.ts; saved projects read none until it is recorded), and
+// fresh base's record of a task branch moved to current main before an attempt (branch_base_move).
+export const SCHEMA_VERSION = 122;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export const V118_MERGED_TABLES = Object.freeze({ api_token: "person", coordinator_credential: "coordinator", lead_credential: "lead" });
 /** The foreign keys that named a merged table, exactly as their DDL wrote them; each names `credential(id)` instead. */
@@ -730,9 +749,11 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * (planning_generation on task_ref, run and plan_revision, defaulting to 0, and decision.superseded_reason, null);
  * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns). v120 only adds
  * three nullable task_steer columns (the running build's steering folder), checked the same way. v121 only adds
- * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way.
+ * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way. v122 only adds a new
+ * table (branch_base_move) and the nullable column in V122_ADDED_COLUMNS (a project's recorded remote), checked the
+ * same way.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122]);
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
 export const V119_ADDED_COLUMNS = Object.freeze({
     task_ref: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
@@ -778,6 +799,11 @@ export const V121_ADDED_COLUMNS = Object.freeze({
     task_steer: LIVE_STEER_COLUMNS.task_steer,
     run: { ...LIVE_STEER_COLUMNS.run, attempt_key: { definition: "TEXT", saved: "NULL" } },
 });
+/** v122: the column it adds, with the value every row saved before it reads: the remote URL an owner's project add
+ * recorded (projects added before it read none, until `repos add <project> --remote <url>` records one). */
+export const V122_ADDED_COLUMNS = Object.freeze({
+    project: { remote_url: { definition: "TEXT", saved: "NULL" } },
+});
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export function updateSafeSchema(version) {
     if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
@@ -3508,6 +3534,8 @@ function initializeStore(db, file) {
     db.exec(CHAT_APPROVAL_SCHEMA);
     // What a running agent did last (no version bump: additive only; absent means no word yet).
     db.exec(RUN_ACTIVITY_SCHEMA);
+    // v122: a task branch moved to current main before an attempt (fresh base): a new table, nothing carried over.
+    db.exec(BRANCH_BASE_MOVE_SCHEMA);
     // v121: the Agents board: each run's attempt key (V121_ADDED_COLUMNS, below), its turn history and current snapshot,
     // the agent's open questions, who has seen a finished run and who is watching one now. Older runs read null keys.
     db.exec(AGENT_BOARD_SCHEMA);
@@ -3540,6 +3568,12 @@ function initializeStore(db, file) {
     db.exec(STORAGE_SWEEP_SCHEMA);
     // v121: landed work's teardown journal (landed-cleanup.ts): new tables.
     db.exec(LANDED_CLEANUP_SCHEMA);
+    // v122: the remote URL an owner's project add recorded (V122_ADDED_COLUMNS; additive only, saved projects read none):
+    // automatic completion trusts only that remote's main (remote-main.ts), never the shared repository's config.
+    for (const [table, columns] of Object.entries(V122_ADDED_COLUMNS)) {
+        for (const [column, { definition }] of Object.entries(columns))
+            addColumn(db, table, column, definition);
+    }
     db.exec(BACKUP_SCHEMA);
     // Sprint 8: the organisation policy (one row, or none: nothing restricted).
     db.exec(POLICY_SCHEMA);
@@ -3712,6 +3746,8 @@ function createBaseline(db, file) {
         }
         db.exec(BASELINE_SCHEMA);
         db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(BASELINE_SCHEMA_VERSION);
+        const installedAt = new Date().toISOString();
+        db.prepare("INSERT INTO installation_fact (key, value, created_at) VALUES ('installed-at', ?, ?)").run(installedAt, installedAt);
         db.exec("COMMIT");
     }
     catch (error) {
@@ -12140,13 +12176,46 @@ export class Store {
      * legacy first-attempt behavior, unchanged byte-for-byte.
      */
     firstBuilderBase(taskRef, branch) {
+        // A branch moved to current main (fresh base) had no commits of its own:
+        // its origin is the first base recorded after the move, not the older main.
         const row = this.db
             .prepare(`SELECT base_revision FROM run
           WHERE task_ref = ? AND branch = ? AND role = 'builder' AND base_revision IS NOT NULL
+            AND id > COALESCE((SELECT after_run FROM branch_base_move WHERE task_ref = ? AND branch = ? ORDER BY id DESC LIMIT 1), 0)
           ORDER BY id ASC LIMIT 1`)
-            .get(taskRef, branch);
+            .get(taskRef, branch, taskRef, branch);
+        return row === undefined ? null : row.base_revision;
+    }
+    /** Where a task branch's attempts start now: a builder branch's pinned base, or the newest base any other attempt on
+     * it recorded (a planner never commits). Null before any attempt on the branch recorded one, or after a move to
+     * current main until the next attempt records its base. */
+    recordedBranchBase(taskRef, branch) {
+        const pinned = this.firstBuilderBase(taskRef, branch);
+        if (pinned !== null)
+            return pinned;
+        const row = this.db
+            .prepare(`SELECT base_revision FROM run
+          WHERE task_ref = ? AND branch = ? AND role <> 'builder' AND base_revision IS NOT NULL
+            AND id > COALESCE((SELECT after_run FROM branch_base_move WHERE task_ref = ? AND branch = ? ORDER BY id DESC LIMIT 1), 0)
+          ORDER BY id DESC LIMIT 1`)
+            .get(taskRef, branch, taskRef, branch);
         return row === undefined ? null : row.base_revision;
     }
+    /** Record a task branch's move to current main, before git moves it: a move that then fails leaves the next
+     * attempt's own base (still the old one) as the branch's origin, which is exactly right. */
+    recordBranchBaseMove(taskRef, branch, from, to, now) {
+        this.db
+            .prepare(`INSERT INTO branch_base_move (task_ref, branch, from_rev, to_rev, after_run, moved_at)
+         VALUES (?, ?, ?, ?, (SELECT COALESCE(MAX(id), 0) FROM run), ?)`)
+            .run(taskRef, branch, from, to, now.toISOString());
+    }
+    /** The newest move of a task branch to current main, or null. */
+    latestBranchBaseMove(taskRef, branch) {
+        const row = this.db
+            .prepare("SELECT from_rev, to_rev, after_run, moved_at FROM branch_base_move WHERE task_ref = ? AND branch = ? ORDER BY id DESC LIMIT 1")
+            .get(taskRef, branch);
+        return row === undefined ? null : { from: String(row["from_rev"]), to: String(row["to_rev"]), afterRun: Number(row["after_run"]), movedAt: String(row["moved_at"]) };
+    }
     finishRun(id, result) {
         this.transact(() => {
             // Read before the write (Telegram task updates): only the OPEN → closed
@@ -15594,17 +15663,38 @@ export class Store {
     // ---- projects ------------------------------------------------------------
     /** Remember a project was opened. Upsert keeps added_at; recency always moves.
      * A project added for the first time starts on Quick checks. */
-    upsertProject(path, name, now) {
+    upsertProject(path, name, now, admission) {
         this.transact(() => {
             const added = this.db.prepare("SELECT 1 FROM project WHERE path = ?").get(path) === undefined;
             this.db
                 .prepare(`INSERT INTO project (path, name, added_at, last_opened_at) VALUES (?, ?, ?, ?)
            ON CONFLICT (path) DO UPDATE SET name = excluded.name, last_opened_at = excluded.last_opened_at`)
                 .run(path, name, now.toISOString(), now.toISOString());
+            // Admission owns remote changes; ordinary openings preserve the saved value.
+            if (admission !== undefined)
+                this.db.prepare("UPDATE project SET remote_url = ? WHERE path = ?").run(admission.remoteUrl, path);
             if (added)
                 stampNewProjectLevel(this, path, now);
         });
     }
+    /** Includes removed/legacy projects, so deleting a row never makes build-writable config authoritative again. */
+    projectAdmissionKnown(path) {
+        return this.db.prepare(`SELECT 1 FROM project WHERE path = ?
+      UNION ALL SELECT 1 FROM action_ledger WHERE repo = ?
+      UNION ALL SELECT 1 FROM task_ref WHERE repo = ?
+      UNION ALL SELECT 1 FROM worktree WHERE repo = ? LIMIT 1`).get(path, path, path, path) !== undefined;
+    }
+    /** Full structured URL audit, without the generic ledger's display-text truncation. */
+    recordProjectRemote(actor, repo, previous, remoteUrl, now) {
+        this.db.prepare(`INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source,detail)
+      VALUES (?,?,?,NULL,NULL,'project remote recorded','recorded','access',?)`)
+            .run(now.toISOString(), actor, repo, JSON.stringify({ previousRemote: previous, remoteUrl }));
+    }
+    /** The remote URL captured on admission or explicitly supplied by the owner; null when none was (or the project was removed). */
+    projectRemote(path) {
+        const url = this.db.prepare("SELECT remote_url FROM project WHERE path = ?").get(path)?.["remote_url"];
+        return typeof url === "string" && url !== "" ? url : null;
+    }
     /** A project removed from the lists (project-admission.ts): only its row goes; its tasks, results and settings stay. */
     forgetProject(path) {
         this.db.prepare("DELETE FROM project WHERE path = ?").run(path);
@@ -15619,6 +15709,7 @@ export class Store {
             name: String(row["name"]),
             addedAt: String(row["added_at"]),
             lastOpenedAt: String(row["last_opened_at"]),
+            remoteUrl: typeof row["remote_url"] === "string" ? row["remote_url"] : null,
         }));
     }
     /**

package/dist/surface.js

@@ -67,9 +67,11 @@ const GUIDE_ROWS = [
     // D5: the central team service (connect, the central lead verbs, conversation …) and native coding sessions are
     // deprecated: they still run this release, with a warning, but are no longer declared here.
     operator("chat", "talk to your lead: one conversation across every project; --say sends one message; --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
-    { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+    // Unkeyed: --remote with a different URL replaces the project's trusted remote (recorded in the action ledger).
+    { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token; --remote records or replaces its trusted remote", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
         positionals: [{ name: "path", required: false, meaning: "the repository (default: the one you are in)" }],
-        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" },
+            { name: "remote", takesValue: true, meaning: "an HTTPS or SSH URL without credentials whose main may complete landed work; replaces a different recorded one (owner or an instance operator's lead only)" }],
         notableReasons: ["not-git", "unavailable", "refused", "locked"] },
     { invocation: "repos remove", synopsis: "remove a project from the console and the builder; its tasks and results stay saved", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         positionals: [{ name: "path", required: true, meaning: "the repository" }],

package/dist/task-base.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Where a task's work starts, against current main (fresh base): one view for
+ * the task page and `task show`. The base is saved run lineage — a builder
+ * branch's pinned origin, or the newest plan's base — and the behind count is
+ * read from Git now. Reads only.
+ */
+import type { Store } from "./store.js";
+export type TaskBaseView = {
+    /** The base commit, in full. */
+    base: string;
+    branch: string;
+    /** The project's main: its checked-out branch, as a dispatch pass resolves it. Null when Git could not say. */
+    main: string | null;
+    /** Commits on main the base does not have; null when Git could not say. */
+    behind: number | null;
+    /** One short line: `Base 9d087efe · Behind main by 2 commits`. */
+    words: string;
+};
+/** A synchronous, read-only Git call in `cwd`: its trimmed output, or null on any failure. */
+export type GitRead = (cwd: string, args: readonly string[]) => string | null;
+export declare const readGit: GitRead;
+/** The base line on its own, for surfaces that label it already: `9d087efe · Behind main by 2 commits`. */
+export declare function baseStandingWords(view: Pick<TaskBaseView, "base" | "main" | "behind">): string;
+/**
+ * The lease's fresh-base request for one attempt on `branch`, or nothing when the task's start is pinned elsewhere: a
+ * revision keeps the head of the attempt it revises, and a prepared candidate or coding review keeps the base its
+ * candidate was proved against.
+ */
+export declare function freshBaseFor(store: Store, taskId: string, branch: string, main: string): {
+    freshBase: {
+        main: string;
+        recordedBase: string | null;
+    };
+} | Record<string, never>;
+export declare function taskBaseOf(store: Store, taskId: string, git?: GitRead): TaskBaseView | null;

package/dist/task-base.js

@@ -0,0 +1,51 @@
+/**
+ * Where a task's work starts, against current main (fresh base): one view for
+ * the task page and `task show`. The base is saved run lineage — a builder
+ * branch's pinned origin, or the newest plan's base — and the behind count is
+ * read from Git now. Reads only.
+ */
+import { execFileSync } from "node:child_process";
+export const readGit = (cwd, args) => {
+    try {
+        return execFileSync("git", ["--no-optional-locks", ...args], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, maxBuffer: 65_536 }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+const commits = (count) => `${count} commit${count === 1 ? "" : "s"}`;
+/** The base line on its own, for surfaces that label it already: `9d087efe · Behind main by 2 commits`. */
+export function baseStandingWords(view) {
+    const short = view.base.slice(0, 8);
+    if (view.main === null || view.behind === null)
+        return short;
+    return view.behind === 0 ? `${short} · Up to date with ${view.main}` : `${short} · Behind ${view.main} by ${commits(view.behind)}`;
+}
+/**
+ * The lease's fresh-base request for one attempt on `branch`, or nothing when the task's start is pinned elsewhere: a
+ * revision keeps the head of the attempt it revises, and a prepared candidate or coding review keeps the base its
+ * candidate was proved against.
+ */
+export function freshBaseFor(store, taskId, branch, main) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null || ref.revisionOf !== null || store.getScope(taskId)?.candidate != null || store.filedViaOf(taskId)?.startsWith("coding:") === true)
+        return {};
+    return { freshBase: { main, recordedBase: store.recordedBranchBase(ref.id, branch) } };
+}
+export function taskBaseOf(store, taskId, git = readGit) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null || ref.repo === null)
+        return null;
+    const latest = store.runsFor(ref.id).find(one => one.role !== "reviewer" && one.branch !== null && one.baseRevision !== null);
+    if (latest === undefined || latest.branch === null || latest.baseRevision === null)
+        return null;
+    const branch = latest.branch;
+    // A move to current main newer than the latest attempt is where the next one starts.
+    const move = store.latestBranchBaseMove(ref.id, branch);
+    const base = move !== null && move.afterRun >= latest.id ? move.to : store.recordedBranchBase(ref.id, branch) ?? latest.baseRevision;
+    const main = git(ref.repo, ["symbolic-ref", "--short", "-q", "HEAD"]) || null;
+    const counted = main === null ? null : git(ref.repo, ["rev-list", "--count", `${base}..refs/heads/${main}`]);
+    const behind = counted === null || !/^\d+$/.test(counted) ? null : Number(counted);
+    const view = { base, branch, main: behind === null ? null : main, behind };
+    return { ...view, words: `Base ${baseStandingWords(view)}` };
+}

package/dist/toolroll-update.js

@@ -35,7 +35,7 @@ import { processMayBeAlive } from "./process-liveness.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
 import { NAME } from "./names.js";
-import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS } from "./store.js";
+import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS } from "./store.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -399,7 +399,8 @@ const HISTORY_RULES = {
     // v120: a steering note's mailing and acknowledgement, and a run's steering folder, are new columns; every row
     // saved before them reads none.
     // v121: live steering's columns and a run's attempt key read none, and no sends, the same way.
-    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS),
+    // v122: a project's recorded remote reads none the same way.
+    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS),
 };
 /** The tables a migration may remove whole (v115's removed features). */
 export const RETIRED_TABLES = Object.freeze(Object.keys(HISTORY_RULES).filter(name => HISTORY_RULES[name].retired));

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. */
@@ -157,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
@@ -245,7 +287,8 @@ 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 | Promise<boolean>, max?: number): Promise<{
@@ -280,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

@@ -40,6 +40,13 @@ 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.
@@ -407,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,
@@ -453,7 +477,49 @@ 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.
@@ -739,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) {
@@ -776,9 +843,9 @@ export class WorktreePool {
                 const allowed = wanted(now, true);
                 if (!(typeof allowed === "boolean" ? allowed : await allowed))
                     continue;
-                const gone = await this.removeWorkingCopy(row);
-                if (!gone) {
-                    kept.push({ path: row.path, why: "git refused" });
+                const gone = await this.removeCleanCopy(row);
+                if (gone !== "removed") {
+                    kept.push({ path: row.path, why: gone });
                     continue;
                 }
                 removed.push(row);
@@ -871,7 +938,8 @@ export class WorktreePool {
             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);
@@ -886,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.61",
+  "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"