@ikarmic/forge-core 5.3.0 → 5.4.0

package/dist/wakeup/wakeup.js

@@ -0,0 +1,151 @@
+/**
+ * Scheduled wakeups: the model asks to be woken later ("check the build in 10 minutes") and the chat delivers an
+ * automatic message when the time comes. The scheduler belongs to the chat, not to a run, and works only while the
+ * editor is open. Caps follow Kilo's wakeup/schema.ts; recurring (cron) wakeups are not offered.
+ */
+/** A delay under this is raised to it; an absolute time is honoured as given. */
+export const MIN_DELAY_MS = 10_000;
+/** A wakeup never fires further out than seven days. */
+export const MAX_HORIZON_MS = 7 * 24 * 60 * 60 * 1000;
+/** One chat holds at most this many pending wakeups. */
+export const MAX_PER_SESSION = 10;
+/** How often a due wakeup is offered again while the chat is busy. */
+const DEFAULT_RETRY_MS = 15_000;
+// ISO-8601 date-time; without an offset the wall clock is read in the host's timezone.
+const WHEN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/;
+// `30`, `30s`, `5m`, `2h`, `1d`; a bare number is seconds.
+const DELAY = /^\s*(\d+)\s*([smhd])?\s*$/i;
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** When a wakeup is due, with the clamp that applied (as a sentence for the model), or an error naming the problem. */
+export function resolveWakeupTime(input, now = Date.now()) {
+    const delay = input.delay?.trim() || undefined;
+    const when = input.when?.trim() || undefined;
+    if ((delay !== undefined) === (when !== undefined))
+        throw new Error('Provide exactly one of delay or when.');
+    if (when !== undefined) {
+        const target = WHEN.test(when) ? Date.parse(when) : NaN;
+        if (!Number.isFinite(target))
+            throw new Error(`Invalid time: ${when}. Use an ISO date and time such as 2026-10-27T15:30:00.`);
+        if (target <= now)
+            throw new Error(`Wakeup time is not in the future: ${when}`);
+        if (target > now + MAX_HORIZON_MS)
+            return { dueAt: now + MAX_HORIZON_MS, notice: `Requested time "${when}" is beyond the 7-day limit and was pulled back to it.` };
+        return { dueAt: target };
+    }
+    const m = DELAY.exec(delay);
+    if (!m)
+        throw new Error(`Invalid delay: ${delay}. Use a number of seconds, or 30s, 5m, 2h, 1d.`);
+    const span = Number(m[1]) * UNIT_MS[(m[2]?.toLowerCase() ?? 's')];
+    if (span <= 0)
+        throw new Error(`Wakeup delay is not in the future: ${delay}`);
+    if (span < MIN_DELAY_MS)
+        return { dueAt: now + MIN_DELAY_MS, notice: `Requested delay "${delay}" is under the 10-second minimum and was raised to it.` };
+    if (span > MAX_HORIZON_MS)
+        return { dueAt: now + MAX_HORIZON_MS, notice: `Requested delay "${delay}" is beyond the 7-day limit and was pulled back to it.` };
+    return { dueAt: now + span };
+}
+export class WakeupScheduler {
+    options;
+    pending = new Map();
+    timers = new Map();
+    nextId = 1;
+    disposed = false;
+    retryMs;
+    constructor(options) {
+        this.options = options;
+        this.retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+    }
+    list() {
+        return [...this.pending.values()].sort((a, b) => a.dueAt - b.dueAt);
+    }
+    async schedule(input) {
+        if (this.pending.size >= MAX_PER_SESSION)
+            throw new Error(`A chat can hold at most ${MAX_PER_SESSION} pending wakeups. Cancel one first.`);
+        const now = Date.now();
+        const { dueAt, notice } = resolveWakeupTime(input, now);
+        const wakeup = { id: `wk${this.nextId++}-${now.toString(36)}`, reason: input.reason, ...(input.prompt ? { prompt: input.prompt } : {}), dueAt, created: now };
+        this.pending.set(wakeup.id, wakeup);
+        this.arm(wakeup);
+        await this.save();
+        return notice ? { ...wakeup, notice } : wakeup;
+    }
+    async cancel(id) {
+        if (!this.pending.delete(id))
+            return false;
+        this.disarm(id);
+        await this.save();
+        return true;
+    }
+    async cancelAll() {
+        for (const id of [...this.pending.keys()])
+            this.disarm(id);
+        this.pending.clear();
+        await this.save();
+    }
+    /** Load what a previous window left; anything already due fires on the next tick. */
+    async restore() {
+        const saved = (await this.options.store?.load().catch(() => [])) ?? [];
+        for (const w of saved) {
+            if (this.pending.has(w.id))
+                continue;
+            this.pending.set(w.id, w);
+            this.arm(w);
+        }
+    }
+    /** Stop every timer without forgetting what is stored (the editor is closing, or the chat was deleted elsewhere). */
+    dispose() {
+        this.disposed = true;
+        for (const id of [...this.timers.keys()])
+            this.disarm(id);
+    }
+    arm(w, delayMs = Math.max(0, w.dueAt - Date.now())) {
+        this.disarm(w.id);
+        if (this.disposed)
+            return;
+        const timer = setTimeout(() => void this.fire(w), delayMs);
+        timer.unref?.();
+        this.timers.set(w.id, timer);
+    }
+    disarm(id) {
+        const t = this.timers.get(id);
+        if (t)
+            clearTimeout(t);
+        this.timers.delete(id);
+    }
+    async fire(w) {
+        this.timers.delete(w.id);
+        if (!this.pending.has(w.id))
+            return;
+        let delivered = false;
+        try {
+            delivered = await this.options.onDue(w);
+        }
+        catch {
+            delivered = false;
+        }
+        if (!this.pending.has(w.id))
+            return;
+        if (!delivered) {
+            this.arm(w, this.retryMs);
+            return;
+        }
+        this.pending.delete(w.id);
+        await this.save();
+    }
+    async save() {
+        await this.options.store?.save(this.list()).catch(() => undefined);
+    }
+}
+/**
+ * The automatic message a due wakeup becomes. It is a user-role message, so it says what it is and that the person's
+ * own words win: the first wording of the todo nudge ("carry on now") overrode "wait for my go-ahead" in live runs (RB-44).
+ */
+export function wakeupMessage(w) {
+    const minutes = Math.max(1, Math.round((w.dueAt - w.created) / 60_000));
+    return [
+        `This is an automatic message, not a message from the user. Earlier in this chat you asked to be woken after about ${minutes} minute${minutes === 1 ? '' : 's'}.`,
+        `Reason: ${w.reason}`,
+        ...(w.prompt ? [`What you planned to do: ${w.prompt}`] : []),
+        'Carry on with that now, unless the user has asked you to stop or wait since then. If they have, leave it and say nothing about this message.',
+    ].join('\n');
+}

package/dist/worktree/health.d.ts

@@ -0,0 +1,51 @@
+export interface ListedWorktree {
+    path: string;
+    head: string;
+    /** Short branch name, absent when detached. */
+    branch?: string;
+    detached: boolean;
+    locked: boolean;
+    lockReason?: string;
+    /** Git says its folder is gone and it can be pruned. */
+    prunable: boolean;
+}
+/** `git worktree list --porcelain` into entries. */
+export declare function parseWorktreeList(text: string): ListedWorktree[];
+export interface WorktreeInspection {
+    /** Worktrees git lists under `.forge/worktrees`. */
+    registered: ListedWorktree[];
+    /** Folders under `.forge/worktrees` that git does not list. */
+    strayFolders: string[];
+    /** Listed worktrees whose folder is gone. */
+    missing: ListedWorktree[];
+}
+export declare function inspectWorktrees(repoRoot: string): Promise<WorktreeInspection>;
+export interface HealthFinding {
+    path: string;
+    /** What is wrong, in a sentence. */
+    problem: string;
+    /** What to do about it, in a sentence. */
+    advice?: string;
+    /** A fix Forge can make itself, after the person confirms: forget a listing, or delete a stray folder. */
+    fix?: 'prune' | 'delete-folder';
+}
+/** Read-only checks of every Agent Manager worktree. An empty list means all is well. */
+export declare function doctorWorktrees(repoRoot: string): Promise<HealthFinding[]>;
+export interface WorktreeStats {
+    /** Commits on the session branch that the base does not have. */
+    ahead: number;
+    /** Commits on the base that the session branch does not have. */
+    behind: number;
+    /** Files changed against the base, committed or not. */
+    changed: number;
+    /** Lines added against the base in tracked files, committed or not. A new file git has not been told about is not counted. */
+    added: number;
+    /** Lines removed against the base, counted the same way. */
+    removed: number;
+}
+/** Numbers for one session's row. Never throws; a folder or branch that cannot be read gives zeros. */
+export declare function worktreeStats(repoRoot: string, worktreePath: string, branch: string, base: string): Promise<WorktreeStats>;
+/** Forget listings whose folder is gone. Returns how many of the Agent Manager's were forgotten. */
+export declare function pruneMissingWorktrees(repoRoot: string): Promise<number>;
+/** Delete a folder under `.forge/worktrees` that git does not know. Refuses anything else. */
+export declare function removeStrayFolder(repoRoot: string, dir: string): Promise<void>;

package/dist/worktree/health.js

@@ -0,0 +1,186 @@
+/**
+ * Worktree health for the Agent Manager (F9): what git knows against what is on disk, a doctor that names what is wrong
+ * in words, ahead/behind and changed-file counts for a poller, and the two fixes.
+ *
+ * The readers change nothing and take no git lock (`--no-optional-locks`), so a poller can run beside a person's own git.
+ * The fixes change repository metadata, so they go through the repo queue like create and remove (RB-25).
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { canonicalPath, onRepoQueue } from './worktree.js';
+const execFileAsync = promisify(execFile);
+async function git(cwd, args) {
+    const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+    return stdout;
+}
+/** `git worktree list --porcelain` into entries. */
+export function parseWorktreeList(text) {
+    const out = [];
+    for (const block of text.split(/\r?\n\r?\n/)) {
+        const lines = block.split(/\r?\n/).filter(Boolean);
+        const pathLine = lines.find((l) => l.startsWith('worktree '));
+        if (!pathLine)
+            continue;
+        const branchLine = lines.find((l) => l.startsWith('branch '));
+        const lock = lines.find((l) => l === 'locked' || l.startsWith('locked '));
+        out.push({
+            path: pathLine.slice('worktree '.length).trim(),
+            head: (lines.find((l) => l.startsWith('HEAD ')) ?? '').slice('HEAD '.length).trim(),
+            ...(branchLine ? { branch: branchLine.slice('branch '.length).trim().replace(/^refs\/heads\//, '') } : {}),
+            detached: lines.includes('detached'),
+            locked: lock !== undefined,
+            ...(lock && lock.length > 'locked'.length ? { lockReason: lock.slice('locked '.length).trim() } : {}),
+            prunable: lines.some((l) => l === 'prunable' || l.startsWith('prunable ')),
+        });
+    }
+    return out;
+}
+const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+const normal = (p) => path.resolve(p);
+function worktreesRootOf(repoRoot) {
+    return path.join(canonicalPath(repoRoot), '.forge', 'worktrees');
+}
+function isUnder(root, p) {
+    const rel = path.relative(root, p);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+export async function inspectWorktrees(repoRoot) {
+    const root = canonicalPath(repoRoot);
+    const wtRoot = worktreesRootOf(root);
+    let listed = [];
+    try {
+        listed = parseWorktreeList(await git(root, ['--no-optional-locks', 'worktree', 'list', '--porcelain']));
+    }
+    catch {
+        // not a repository, or git is missing: nothing to report
+    }
+    const registered = listed.map((w) => ({ ...w, path: normal(w.path) })).filter((w) => isUnder(wtRoot, w.path));
+    let strayFolders = [];
+    try {
+        const entries = await readdir(wtRoot, { withFileTypes: true });
+        strayFolders = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(wtRoot, e.name))
+            .filter((dir) => !registered.some((w) => same(w.path, dir)));
+    }
+    catch {
+        // no folder yet
+    }
+    const missing = registered.filter((w) => !existsSync(w.path));
+    return { registered, strayFolders, missing };
+}
+async function branchExists(repoRoot, branch) {
+    try {
+        await git(repoRoot, ['--no-optional-locks', 'show-ref', '--verify', '--quiet', `refs/heads/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read-only checks of every Agent Manager worktree. An empty list means all is well. */
+export async function doctorWorktrees(repoRoot) {
+    const root = canonicalPath(repoRoot);
+    const { registered, strayFolders, missing } = await inspectWorktrees(root);
+    const found = [];
+    for (const w of registered) {
+        if (missing.includes(w)) {
+            found.push({ path: w.path, problem: 'Its folder is gone, but git still lists it.', advice: 'Prune it to forget the listing.', fix: 'prune' });
+            continue;
+        }
+        if (w.detached || !w.branch) {
+            found.push({ path: w.path, problem: 'It is on a detached HEAD, so commits made here belong to no branch.', advice: 'Create a branch before you leave it, or the commits can be lost.' });
+        }
+        else if (!(await branchExists(root, w.branch))) {
+            found.push({ path: w.path, problem: `Its branch "${w.branch}" no longer exists.`, advice: 'Create the branch again from this folder, or discard the session.' });
+        }
+        if (w.locked)
+            found.push({ path: w.path, problem: `Git has it locked${w.lockReason ? ` (${w.lockReason})` : ''}.`, advice: 'Unlock it with git worktree unlock if nothing is using it.' });
+        try {
+            const gitDir = (await git(w.path, ['--no-optional-locks', 'rev-parse', '--absolute-git-dir'])).trim();
+            for (const name of ['index.lock', 'HEAD.lock']) {
+                if (existsSync(path.join(gitDir, name))) {
+                    found.push({ path: w.path, problem: `A leftover lock file (${name}) stops git commands here.`, advice: 'If no git command is running, delete that file.' });
+                }
+            }
+        }
+        catch {
+            // not readable as a git folder: another finding already covers a broken listing
+        }
+    }
+    for (const dir of strayFolders) {
+        found.push({ path: dir, problem: 'This folder is not a worktree that git knows.', advice: 'Look inside, and delete it if nothing there matters.', fix: 'delete-folder' });
+    }
+    return found;
+}
+const ZERO = { ahead: 0, behind: 0, changed: 0, added: 0, removed: 0 };
+/** Numbers for one session's row. Never throws; a folder or branch that cannot be read gives zeros. */
+export async function worktreeStats(repoRoot, worktreePath, branch, base) {
+    if (!existsSync(worktreePath))
+        return ZERO;
+    const root = canonicalPath(repoRoot);
+    try {
+        const counts = (await git(root, ['--no-optional-locks', 'rev-list', '--left-right', '--count', `${base}...${branch}`])).trim().split(/\s+/).map(Number);
+        const files = new Set();
+        const committed = await git(root, ['--no-optional-locks', 'diff', '--name-only', `${base}...${branch}`]);
+        for (const l of committed.split(/\r?\n/))
+            if (l.trim())
+                files.add(l.trim());
+        const status = await git(worktreePath, ['--no-optional-locks', 'status', '--porcelain=v1']);
+        for (const l of status.split(/\r?\n/))
+            if (l.trim())
+                files.add(l.slice(3).trim());
+        // One diff of the working tree against where the branch left the base, so a line edited twice is one change. A binary file shows "-" and adds no lines.
+        const mergeBase = (await git(worktreePath, ['merge-base', base, 'HEAD'])).trim();
+        let added = 0;
+        let removed = 0;
+        for (const l of (await git(worktreePath, ['--no-optional-locks', 'diff', '--numstat', mergeBase])).split(/\r?\n/)) {
+            const [a, r] = l.split('\t');
+            if (a && r && /^\d+$/.test(a) && /^\d+$/.test(r)) {
+                added += Number(a);
+                removed += Number(r);
+            }
+        }
+        return { behind: counts[0] ?? 0, ahead: counts[1] ?? 0, changed: files.size, added, removed };
+    }
+    catch {
+        return ZERO;
+    }
+}
+/** Forget listings whose folder is gone. Returns how many of the Agent Manager's were forgotten. */
+export function pruneMissingWorktrees(repoRoot) {
+    const root = canonicalPath(repoRoot);
+    return onRepoQueue(root, async () => {
+        const before = (await inspectWorktrees(root)).missing.length;
+        if (before === 0)
+            return 0;
+        await git(root, ['worktree', 'prune']);
+        return before - (await inspectWorktrees(root)).missing.length;
+    });
+}
+/** Delete a folder under `.forge/worktrees` that git does not know. Refuses anything else. */
+export function removeStrayFolder(repoRoot, dir) {
+    const root = canonicalPath(repoRoot);
+    return onRepoQueue(root, async () => {
+        const wtRoot = worktreesRootOf(root);
+        const target = path.resolve(dir);
+        if (same(target, wtRoot))
+            throw new Error('That is the worktrees folder itself; only a folder inside it can be removed.');
+        if (!isUnder(wtRoot, target))
+            throw new Error('Only a folder inside .forge/worktrees can be removed; this one is outside it.');
+        const { registered } = await inspectWorktrees(root);
+        if (registered.some((w) => same(w.path, target)))
+            throw new Error('That folder is a worktree git knows. Discard its session instead.');
+        if (existsSync(target)) {
+            if (lstatSync(target).isSymbolicLink())
+                throw new Error('That is a link, not a folder, so it was left alone.');
+            // Where the folder really is, after any link on the way (RB-20).
+            if (!isUnder(realpathSync.native(wtRoot), realpathSync.native(target)))
+                throw new Error('Only a folder inside .forge/worktrees can be removed; this one leads outside it.');
+        }
+        await rm(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 150 });
+    });
+}

package/dist/worktree/index.d.ts

@@ -15,3 +15,7 @@ export { compareWorktreeContexts, snapshotWorktreeContext, WorktreeManager, Work
 export type { CreateOptions, RemoveOptions, RemoveResult, WorktreeContextSnapshot, WorktreeInfo, WorktreeMismatchKind, WorktreeMismatchResult, } from './worktree.js';
 export { branchChangedFiles, branchDiff, commitAllInWorktree, deleteBranch, mergeBranch, } from './branch-ops.js';
 export type { MergeResult, WorktreeCommit } from './branch-ops.js';
+export { doctorWorktrees, inspectWorktrees, parseWorktreeList, pruneMissingWorktrees, removeStrayFolder, worktreeStats } from './health.js';
+export type { HealthFinding, ListedWorktree, WorktreeInspection, WorktreeStats } from './health.js';
+export { copyIntoWorktree, runSetupScript, setupWorktree } from './setup.js';
+export type { CopyOptions, CopyResult, ScriptOptions, ScriptResult, SetupOptions, SetupOutcome } from './setup.js';

package/dist/worktree/index.js

@@ -13,3 +13,5 @@
  */
 export { compareWorktreeContexts, snapshotWorktreeContext, WorktreeManager, WorktreeError, } from './worktree.js';
 export { branchChangedFiles, branchDiff, commitAllInWorktree, deleteBranch, mergeBranch, } from './branch-ops.js';
+export { doctorWorktrees, inspectWorktrees, parseWorktreeList, pruneMissingWorktrees, removeStrayFolder, worktreeStats } from './health.js';
+export { copyIntoWorktree, runSetupScript, setupWorktree } from './setup.js';

package/dist/worktree/setup.d.ts

@@ -0,0 +1,51 @@
+import { type ShellPreference } from '../tools/shell.js';
+export interface CopyResult {
+    /** Paths copied, relative to the repository, with `/`. */
+    copied: string[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+}
+export interface CopyOptions {
+    maxFiles?: number;
+    maxFileBytes?: number;
+}
+/**
+ * Copy the files matching `patterns` (a name such as `.env` matches at any depth, `config/*.json` is a path) from the
+ * repository into the worktree. Never overwrites, never follows a link, never enters `.git` or a build folder, and stops
+ * at a count and a size.
+ */
+export declare function copyIntoWorktree(repoRoot: string, worktreePath: string, patterns: readonly string[], options?: CopyOptions): Promise<CopyResult>;
+export interface ScriptOptions {
+    timeoutMs?: number;
+    tailChars?: number;
+    shell?: ShellPreference;
+}
+export interface ScriptResult {
+    ok: boolean;
+    exitCode: number | null;
+    timedOut: boolean;
+    /** The end of what the script printed (both streams). */
+    output: string;
+}
+/** Run `script` in a shell, in the worktree. Never throws: a script that cannot start is a failed result. */
+export declare function runSetupScript(worktreePath: string, script: string, options?: ScriptOptions): Promise<ScriptResult>;
+export interface SetupOptions extends CopyOptions {
+    copyFiles?: readonly string[];
+    setupScript?: string;
+    scriptTimeoutMs?: number;
+    shell?: ShellPreference;
+}
+export interface SetupOutcome {
+    ok: boolean;
+    copied: string[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    /** Why it stopped, in words, with the end of the script's output. */
+    message?: string;
+}
+/** Copy, then run the script. The first failure ends it. */
+export declare function setupWorktree(repoRoot: string, worktreePath: string, options: SetupOptions): Promise<SetupOutcome>;

package/dist/worktree/setup.js

@@ -0,0 +1,173 @@
+/**
+ * Getting a new worktree ready before an agent works in it (F7): copy a few files from the repository (an `.env`), then run
+ * a setup script (`npm ci`). Both are the person's own settings, never read from a repository (RB-12). A failed step ends
+ * the session before the agent runs in a half-made tree.
+ */
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { copyFile, lstat, mkdir, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileGlobMatcher } from '../tools/glob-filter.js';
+import { killTree } from '../tools/run-command.js';
+import { runnerShell, shellInvocation } from '../tools/shell.js';
+import { shellEnv } from '../tools/shell-env.js';
+import { DEFAULT_IGNORED_DIRS } from '../tools/shared.js';
+const DEFAULT_MAX_FILES = 200;
+const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_TAIL_CHARS = 2000;
+/** Output kept while a script runs; only the end is ever shown. */
+const KEEP_CHARS = 64 * 1024;
+function checkPattern(p) {
+    if (!p.trim() || path.isAbsolute(p) || /^[A-Za-z]:/.test(p) || p.split(/[\\/]/).includes('..')) {
+        throw new Error(`Copy pattern "${p}" must be relative to the repository and stay inside it.`);
+    }
+}
+/**
+ * Copy the files matching `patterns` (a name such as `.env` matches at any depth, `config/*.json` is a path) from the
+ * repository into the worktree. Never overwrites, never follows a link, never enters `.git` or a build folder, and stops
+ * at a count and a size.
+ */
+export async function copyIntoWorktree(repoRoot, worktreePath, patterns, options = {}) {
+    for (const p of patterns)
+        checkPattern(p);
+    const matchers = patterns.map((p) => fileGlobMatcher(p.replace(/\\/g, '/')));
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const result = { copied: [], skipped: [] };
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            // A link could lead anywhere on disk (RB-20): it is not followed and not copied.
+            if (entry.isSymbolicLink())
+                continue;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === '.git' || DEFAULT_IGNORED_DIRS.has(entry.name))
+                    continue;
+                await walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = path.relative(repoRoot, abs).split(path.sep).join('/');
+            if (!matchers.some((m) => m(rel, entry.name)))
+                continue;
+            if (result.copied.length >= maxFiles) {
+                result.skipped.push({ path: rel, reason: 'file limit' });
+                continue;
+            }
+            const size = (await lstat(abs)).size;
+            if (size > maxBytes) {
+                result.skipped.push({ path: rel, reason: 'too large' });
+                continue;
+            }
+            const dest = path.join(worktreePath, ...rel.split('/'));
+            // The destination must stay inside the worktree whatever the name was.
+            if (path.relative(worktreePath, dest).startsWith('..'))
+                continue;
+            await mkdir(path.dirname(dest), { recursive: true });
+            try {
+                await copyFile(abs, dest, constants.COPYFILE_EXCL);
+                result.copied.push(rel);
+            }
+            catch (err) {
+                if (err.code === 'EEXIST')
+                    result.skipped.push({ path: rel, reason: 'already exists' });
+                else
+                    throw err;
+            }
+        }
+    }
+    await walk(repoRoot);
+    return result;
+}
+/** Run `script` in a shell, in the worktree. Never throws: a script that cannot start is a failed result. */
+export function runSetupScript(worktreePath, script, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const tail = options.tailChars ?? DEFAULT_TAIL_CHARS;
+    return new Promise((resolve) => {
+        let output = '';
+        let timedOut = false;
+        const take = (chunk) => {
+            output += chunk;
+            if (output.length > KEEP_CHARS)
+                output = output.slice(output.length - KEEP_CHARS);
+        };
+        const inv = shellInvocation(runnerShell(options.shell), script);
+        const spawnOptions = {
+            cwd: worktreePath,
+            // Windows: never run a same-named program the repository ships in its root (RB-24).
+            env: shellEnv(process.env),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        };
+        let child;
+        try {
+            child = inv.file ? spawn(inv.file, inv.args, spawnOptions) : spawn(script, { ...spawnOptions, shell: true });
+        }
+        catch (err) {
+            resolve({ ok: false, exitCode: null, timedOut: false, output: err.message });
+            return;
+        }
+        child.stdout.setEncoding('utf8').on('data', take);
+        child.stderr.setEncoding('utf8').on('data', take);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child);
+        }, timeoutMs);
+        let finished = false;
+        const finish = (code) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            resolve({ ok: code === 0 && !timedOut, exitCode: code, timedOut, output: output.trim().slice(-tail) });
+        };
+        child.on('error', (err) => {
+            take(`${err.message}\n`);
+            finish(null);
+        });
+        // A grandchild that escaped the tree kill must not hold the pipes open and hang the session (RB-70).
+        child.on('exit', (code) => {
+            setTimeout(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+                finish(code);
+            }, 500).unref();
+        });
+        child.on('close', (code) => finish(code));
+    });
+}
+/** Copy, then run the script. The first failure ends it. */
+export async function setupWorktree(repoRoot, worktreePath, options) {
+    let copied = [];
+    let skipped = [];
+    const patterns = options.copyFiles ?? [];
+    if (patterns.length > 0) {
+        try {
+            const r = await copyIntoWorktree(repoRoot, worktreePath, patterns, options);
+            copied = r.copied;
+            skipped = r.skipped;
+        }
+        catch (err) {
+            return { ok: false, copied, skipped, message: `Copying files into the worktree failed: ${err.message}` };
+        }
+    }
+    const script = options.setupScript?.trim();
+    if (script) {
+        const r = await runSetupScript(worktreePath, script, { ...(options.scriptTimeoutMs ? { timeoutMs: options.scriptTimeoutMs } : {}), ...(options.shell ? { shell: options.shell } : {}) });
+        if (!r.ok) {
+            const why = r.timedOut ? 'ran too long and was stopped' : `failed${r.exitCode === null ? '' : ` (exit code ${r.exitCode})`}`;
+            return { ok: false, copied, skipped, message: `The setup script ${why}.${r.output ? `\n${r.output}` : ''}` };
+        }
+    }
+    return { ok: true, copied, skipped };
+}

package/dist/worktree/worktree.d.ts

@@ -335,3 +335,10 @@ export declare class WorktreeManager {
  * canonical too. Falls back to `path.resolve` when the path does not exist.
  */
 export declare function canonicalPath(p: string): string;
+/**
+ * Run `work` after every earlier queued worktree change of the same repository has finished. Parallel steps create
+ * and remove worktrees at the same moment, and two `git worktree add` / `remove` calls on one repository fight over
+ * git's lock files; one of them then fails at random, mostly under load. The agents still run in parallel: only these
+ * short git changes take turns.
+ */
+export declare function onRepoQueue<T>(repoRoot: string, work: () => Promise<T>): Promise<T>;

package/dist/worktree/worktree.js

@@ -296,9 +296,14 @@ export class WorktreeManager {
             throw new WorktreeError(`Worktree path already exists: ${worktreePath}. ` +
                 `Pick a unique label or remove the existing worktree.`);
         }
-        const args = ['worktree', 'add', '--no-track'];
-        if (!opts.detached) {
-            args.push('-b', branch);
+        const args = ['worktree', 'add'];
+        if (opts.detached) {
+            // Without --detach git makes a branch named after the folder, so the worktree was never detached (RB-74).
+            // --no-track is only allowed when a branch is created.
+            args.push('--detach');
+        }
+        else {
+            args.push('--no-track', '-b', branch);
         }
         if (opts.baseRef) {
             args.push(worktreePath, opts.baseRef);
@@ -642,7 +647,7 @@ const repoQueues = new Map();
  * git's lock files; one of them then fails at random, mostly under load. The agents still run in parallel: only these
  * short git changes take turns.
  */
-function onRepoQueue(repoRoot, work) {
+export function onRepoQueue(repoRoot, work) {
     const key = canonicalPath(repoRoot);
     const next = (repoQueues.get(key) ?? Promise.resolve()).then(work, work);
     repoQueues.set(key, next.catch(() => undefined));