@ikarmic/forge-core 5.2.0 → 5.4.0

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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikarmic/forge-core",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Agent engine for IKarmic AI Forge. Model loop, tools, MCP, sandbox, memory, compaction, plan mode, skills, hooks.",
   "type": "module",
   "main": "./dist/index.js",