@openagt/skill-branches 0.0.1

package/dist/reclaim.js

@@ -0,0 +1,87 @@
+import { nodeGitRunner, originDefaultBranch } from '@openagt/agent-data';
+import { isAgentBranch } from './branch-names.js';
+import { currentBranch, deleteBranch, isWorktreeRoot, pruneWorktrees, removeWorktree, worktreeClean, } from './worktree.js';
+/**
+ * Remove one checkout under the rule above. Throws only for a git failure past the decision
+ * (the removal itself); every refusal is an outcome.
+ */
+export async function reclaimWorktree(repo, path, opts) {
+    const git = opts.git ?? nodeGitRunner();
+    // Before any git runs in it (#1654): a directory under `.branches/` that git does not know as
+    // a worktree root makes every command below act on the enclosing repo — the user's checkout,
+    // the user's branch. Nothing is pushed or deleted through it; it is left where it is.
+    if (!(await isWorktreeRoot(path, git)))
+        return { ok: false, reason: 'not-a-worktree' };
+    const branch = await currentBranch(path, git);
+    if (!branch)
+        return { ok: false, reason: 'no-branch' };
+    // Every way out below needs a clean tree: `removeWorktree` forces past a dirty one, so a dirty
+    // tree is kept (#1638), and so is a tree git cannot read. Asked once, for all of them.
+    if (!(await worktreeClean(path, git).catch(() => false)))
+        return { ok: false, reason: 'dirty', branch };
+    // Whether the checkout's branch goes with it (#1650): only when it holds no commit of its own —
+    // an agent that committed nothing — and only a branch minted for an agent: a leftover checkout
+    // can sit on the user's own branch (one was found on `main`), and deleting that is not this
+    // code's call even when it holds nothing — git's refusal to delete a checked-out branch must
+    // never be the guard.
+    const emptyBranch = isAgentBranch(branch) && (await branchHoldsNothing(repo, branch, opts.from, git));
+    // The birth branch (#1657) is judged before anything is deleted: the containment reads both refs.
+    // Only a branch the package minted: the rule that guards the checkout's own branch guards this one.
+    const birthBranchGoes = opts.birthBranch !== undefined && opts.birthBranch !== branch && isAgentBranch(opts.birthBranch) && (await isAncestor(repo, `refs/heads/${opts.birthBranch}`, `refs/heads/${branch}`, git));
+    await opts.beforeRemove?.();
+    await removeWorktree(repo, path, git);
+    await pruneWorktrees(repo, git);
+    // After the checkout: git refuses to delete a branch a worktree still has checked out.
+    // Only a branch that actually went is named: git refuses to delete a branch another worktree
+    // has checked out, and the caller must not report that one as gone.
+    const deleted = [];
+    if (emptyBranch && (await deleteBranch(repo, branch, git)))
+        deleted.push(branch);
+    if (birthBranchGoes && opts.birthBranch && (await deleteBranch(repo, opts.birthBranch, git)))
+        deleted.push(opts.birthBranch);
+    return deleted.length ? { ok: true, branchesDeleted: deleted } : { ok: true };
+}
+/**
+ * Discard one checkout (#1774): it goes whatever it holds, uncommitted work included. A person's
+ * call, for a run they are throwing away, where the rule above would keep the checkout. The
+ * branch and its commits stay: deleting a branch that may carry an open pull request is git's
+ * business, never this tool's on the way out of a checkout. Only the not-a-worktree guard
+ * applies: a directory git does not know as a worktree is left alone.
+ */
+export async function discardWorktree(repo, path, opts = {}) {
+    const git = opts.git ?? nodeGitRunner();
+    if (!(await isWorktreeRoot(path, git)))
+        return { ok: false, reason: 'not-a-worktree' };
+    await opts.beforeRemove?.();
+    await git(['worktree', 'remove', '--force', path], repo);
+    await pruneWorktrees(repo, git);
+    return { ok: true };
+}
+/**
+ * Whether a branch holds nothing of its own (#1650). Either answer is enough: it has no commit
+ * past the commit it was made at, when the caller names that commit and this machine has it; or
+ * origin's default branch already has everything on it, read from the local remote-tracking ref
+ * and never fetched. The first is the only one a project with no remote can give, and the only
+ * one for a branch made from another branch nobody published. The second is the only one for a
+ * caller that names no commit, and for a branch whose work was merged.
+ *
+ * Not "the tip is on the remote under another name", the earlier test: a branch another agent was
+ * started from has its tip inside that agent's branch once that one is pushed, and it is still
+ * the only branch that work is its own on.
+ */
+async function branchHoldsNothing(repo, branch, from, git) {
+    const tip = `refs/heads/${branch}`;
+    if (from !== undefined) {
+        // The commit itself, never the caller's words handed on to git; one this machine lacks proves nothing.
+        const start = await git(['rev-parse', '--verify', '--quiet', '--end-of-options', `${from}^{commit}`], repo).then(out => out.trim(), () => '');
+        if (start !== '' && (await isAncestor(repo, tip, start, git)))
+            return true;
+    }
+    const main = await originDefaultBranch(repo, git);
+    return main !== undefined && (await isAncestor(repo, tip, `refs/remotes/${main}`, git));
+}
+/** Whether `inner` is `outer` or an ancestor of it — everything on it is on `outer` too. False on any doubt. */
+async function isAncestor(cwd, inner, outer, git) {
+    return git(['merge-base', '--is-ancestor', inner, outer], cwd).then(() => true, () => false);
+}
+//# sourceMappingURL=reclaim.js.map

package/dist/reclaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.js","sourceRoot":"","sources":["../src/reclaim.ts"],"names":[],"mappings":"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"}

package/dist/skill-links.d.ts

@@ -0,0 +1,43 @@
+import { type GitRunner } from '@openagt/agent-data';
+import { type LinkFs } from './worktree-deps.js';
+/**
+ * The skill, where the agent's harness looks for one (#1739). A harness discovers skills under a
+ * directory of its own at the checkout root — `.claude/skills/<name>/SKILL.md` for Claude Code,
+ * `.agents/skills/<name>/SKILL.md` for Codex — and a checkout under `.branches/` is its own
+ * repository root to it, so nothing the project keeps in those directories reaches the agent.
+ * Every checkout the package creates therefore gets one symlink per harness, named as the skill
+ * and pointing at this package, whose `SKILL.md` is the skill. One mechanism for every harness,
+ * and the same text for every agent; a new harness is one more entry in {@link HARNESS_SKILL_DIRS}.
+ */
+/** The skill's name: the `name` in `SKILL.md`'s front matter, and the directory a harness lists it under. */
+export declare const SKILL_NAME = "branches";
+/** Where each harness looks for skills, relative to the checkout root. */
+export declare const HARNESS_SKILL_DIRS: readonly ['.claude/skills', '.agents/skills'];
+/**
+ * This package's directory — the one holding `SKILL.md`. Beside `dist/`, so it is the same path
+ * from a workspace checkout and from an installed package.
+ */
+export declare const SKILL_DIR: string;
+/**
+ * A skill to link into a checkout: its name (the directory a harness lists it under) and the
+ * directory holding its `SKILL.md`.
+ *
+ * A caller names the skills it ships itself and wants in every checkout it makes, skills that
+ * live with the caller and not in the repository. A skill a project uses
+ * is the project's own tracked `.claude/skills/<name>`, in every worktree by itself.
+ */
+export interface SkillLink {
+    name: string;
+    dir: string;
+}
+/** This package's own skill, as a {@link SkillLink}. */
+export declare const OWN_SKILL: SkillLink;
+/**
+ * Link the skill into `checkout` for every harness — this package's own, plus whatever `skills`
+ * the caller names (see {@link SkillLink}) — and hide the links from the project's git
+ * through the repository's exclude file: a symlink at the checkout root would otherwise ride any
+ * sweeping `git add -A` onto the agent's branch. Best-effort: an entry already at a link's path is
+ * left alone, and a link that cannot be made is a worse run, not a failed one.
+ */
+export declare function linkSkill(repo: string, checkout: string, fs?: LinkFs, git?: GitRunner, skills?: readonly SkillLink[]): Promise<void>;
+//# sourceMappingURL=skill-links.d.ts.map

package/dist/skill-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-links.d.ts","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;;;;;;;GAQG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,UAAU,aAAa,CAAA;AAEpC,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,YAAI,gBAAgB,EAAE,gBAAgB,CAAU,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,SAAS,QAAsD,CAAA;AAE5E;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,EAAE,SAAgD,CAAA;AAExE;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,EAAE,GAAE,MAAqB,EACzB,GAAG,GAAE,SAA2B,EAChC,MAAM,GAAE,SAAS,SAAS,EAAO,GAChC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/skill-links.js

@@ -0,0 +1,50 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nodeGitRunner, excludeFromGit } from '@openagt/agent-data';
+import { nodeLinkFs } from './worktree-deps.js';
+/**
+ * The skill, where the agent's harness looks for one (#1739). A harness discovers skills under a
+ * directory of its own at the checkout root — `.claude/skills/<name>/SKILL.md` for Claude Code,
+ * `.agents/skills/<name>/SKILL.md` for Codex — and a checkout under `.branches/` is its own
+ * repository root to it, so nothing the project keeps in those directories reaches the agent.
+ * Every checkout the package creates therefore gets one symlink per harness, named as the skill
+ * and pointing at this package, whose `SKILL.md` is the skill. One mechanism for every harness,
+ * and the same text for every agent; a new harness is one more entry in {@link HARNESS_SKILL_DIRS}.
+ */
+/** The skill's name: the `name` in `SKILL.md`'s front matter, and the directory a harness lists it under. */
+export const SKILL_NAME = 'branches';
+/** Where each harness looks for skills, relative to the checkout root. */
+export const HARNESS_SKILL_DIRS = ['.claude/skills', '.agents/skills'];
+/**
+ * This package's directory — the one holding `SKILL.md`. Beside `dist/`, so it is the same path
+ * from a workspace checkout and from an installed package.
+ */
+export const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+/** This package's own skill, as a {@link SkillLink}. */
+export const OWN_SKILL = { name: SKILL_NAME, dir: SKILL_DIR };
+/**
+ * Link the skill into `checkout` for every harness — this package's own, plus whatever `skills`
+ * the caller names (see {@link SkillLink}) — and hide the links from the project's git
+ * through the repository's exclude file: a symlink at the checkout root would otherwise ride any
+ * sweeping `git add -A` onto the agent's branch. Best-effort: an entry already at a link's path is
+ * left alone, and a link that cannot be made is a worse run, not a failed one.
+ */
+export async function linkSkill(repo, checkout, fs = nodeLinkFs(), git = nodeGitRunner(), skills = []) {
+    for (const skill of [OWN_SKILL, ...skills]) {
+        for (const dir of HARNESS_SKILL_DIRS) {
+            const rel = `${dir}/${skill.name}`;
+            await excludeFromGit(repo, `/${rel}`, undefined, git).catch(() => { });
+            try {
+                const path = join(checkout, rel);
+                if (await fs.entryExists(path))
+                    continue;
+                await fs.mkdir(join(checkout, dir));
+                await fs.symlinkDir(skill.dir, path);
+            }
+            catch {
+                // A filesystem that refuses the link: the agent still starts, without the skill.
+            }
+        }
+    }
+}
+//# sourceMappingURL=skill-links.js.map

package/dist/skill-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-links.js","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,aAAa,EAAkB,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAE,UAAU,EAAe,MAAM,oBAAoB,CAAA;AAE5D;;;;;;;;GAQG;AAEH,6GAA6G;AAC7G,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAA;AAEpC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAU,CAAA;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAe5E,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAc,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,CAAA;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,QAAgB,EAChB,EAAE,GAAW,UAAU,EAAE,EACzB,GAAG,GAAc,aAAa,EAAE,EAChC,MAAM,GAAyB,EAAE;IAEjC,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;YACrC,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;YAClC,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;YACrE,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;gBAChC,IAAI,MAAM,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC;oBAAE,SAAQ;gBACxC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA;gBACnC,MAAM,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,iFAAiF;YACnF,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/worktree-deps.d.ts

@@ -0,0 +1,30 @@
+/** The filesystem this module needs. Injectable so the scan is testable. */
+export interface LinkFs {
+    /** Entry names in a directory. A missing/unreadable dir yields `[]`. */
+    readdir(path: string): Promise<string[]>;
+    /** True when `path` is a directory (following symlinks). Any error reads as `false`. */
+    isDirectory(path: string): Promise<boolean>;
+    /** True when anything exists at `path`, symlinks included (no link following). */
+    entryExists(path: string): Promise<boolean>;
+    /** Recursive. */
+    mkdir(path: string): Promise<void>;
+    /** Create a directory symlink at `path` pointing to `target`. */
+    symlinkDir(target: string, path: string): Promise<void>;
+}
+/** The `node:fs/promises` implementation of {@link LinkFs}. */
+export declare function nodeLinkFs(): LinkFs;
+/**
+ * Every `node_modules` directory in `repo`, as repo-relative paths, down to
+ * {@link MAX_DEPTH}. Sorted, so the linking order (and any log of it) is stable.
+ */
+export declare function findDependencyDirs(repo: string, fs?: LinkFs): Promise<string[]>;
+/**
+ * Mirror `repo`'s dependency trees into `worktree` at the same relative paths: a real
+ * directory per tree, holding a link per entry (the package manager's private state
+ * left out, see above). Returns the trees mirrored. Best-effort throughout: a worktree
+ * with no deps is a worse run, not a failed one, so a link that cannot be made is
+ * skipped rather than thrown. A tree already present is left alone (the agent may
+ * have installed already).
+ */
+export declare function linkDependencies(repo: string, worktree: string, fs?: LinkFs): Promise<string[]>;
+//# sourceMappingURL=worktree-deps.d.ts.map

package/dist/worktree-deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-deps.d.ts","sourceRoot":"","sources":["../src/worktree-deps.ts"],"names":[],"mappings":"AAkDA,4EAA4E;AAC5E,MAAM,WAAW,MAAM;IACrB,wEAAwE;IACxE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACxC,wFAAwF;IACxF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,kFAAkF;IAClF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,iBAAiB;IACjB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,iEAAiE;IACjE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,MAAM,CAyBnC;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAanG;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAqBnH"}

package/dist/worktree-deps.js

@@ -0,0 +1,128 @@
+import { join, relative } from 'node:path';
+/**
+ * Give a fresh worktree a dependency tree (#736). `node_modules` is gitignored, so
+ * `git worktree add` hands the agent an empty one and every command in it fails.
+ *
+ * Three ways to fix that: copy the tree (correct, but gigabytes per agent), install
+ * into each worktree (correct, but real latency on every start), or link the
+ * parent checkout's trees in (instant, no extra disk, one store shared by N runs).
+ * We link — but each *entry* of a dependency directory, into a real directory of
+ * the worktree's own, never the directory itself (#1262). A directory link made the
+ * parent's tree the worktree's modules directory in the package manager's eyes:
+ * an agent that changed a dependency and ran `pnpm install` had pnpm resolve
+ * through the link and rewrite — or, under `CI=true`, purge outright — the parent
+ * checkout's real `node_modules`, and every later agent died at boot. With a real
+ * directory holding links, an install in the worktree writes into the worktree.
+ *
+ * The package manager's own state (`.pnpm`, `.modules.yaml`, and the like — every
+ * dot-entry but `.bin`) is deliberately not linked: it is what tells the package
+ * manager "this tree is mine, installed here", and the worktree's is not. The
+ * packages still resolve without it — a package entry in a pnpm tree is a relative
+ * link into `.pnpm`, and a link to that link resolves where the target lives, in
+ * the parent checkout. `.bin` is linked because an agent runs the project's tools.
+ * A scope directory is mirrored one level down the same way, a real directory
+ * holding a link per package, so a new scoped package lands in the worktree too.
+ */
+/** The dependency directory mirrored into a worktree. */
+const NODE_MODULES = 'node_modules';
+/** How deep below the repo root a `node_modules` is looked for (root = 0). Covers a
+ *  pnpm/npm workspace's `packages/<pkg>/node_modules` without walking the world. */
+const MAX_DEPTH = 2;
+/** Directory names never descended into while scanning for dependency trees. */
+const SKIP = new Set([NODE_MODULES, '.git', 'dist', 'build', 'coverage']);
+/** The one dot-entry of a dependency directory that is linked: the project's executables. */
+const BIN = '.bin';
+/** The package manager's private state in a dependency directory: never linked (see above). */
+const isPrivate = (name) => name.startsWith('.') && name !== BIN;
+/**
+ * A scope (`@acme`) holds packages rather than being one. Linked whole, an install of a new
+ * `@acme/pkg` in the worktree would go through the link into the parent's tree, so a scope is a
+ * real directory of the worktree's own too, holding a link per package.
+ */
+const isScope = (name) => name.startsWith('@');
+/** The `node:fs/promises` implementation of {@link LinkFs}. */
+export function nodeLinkFs() {
+    return {
+        async readdir(path) {
+            const { readdir } = await import('node:fs/promises');
+            return readdir(path).catch(() => []);
+        },
+        async isDirectory(path) {
+            const { stat } = await import('node:fs/promises');
+            return stat(path).then(s => s.isDirectory(), () => false);
+        },
+        async entryExists(path) {
+            const { lstat } = await import('node:fs/promises');
+            return lstat(path).then(() => true, () => false);
+        },
+        async mkdir(path) {
+            const { mkdir } = await import('node:fs/promises');
+            await mkdir(path, { recursive: true });
+        },
+        async symlinkDir(target, path) {
+            const { symlink } = await import('node:fs/promises');
+            // 'junction' is the only directory-link type Windows grants without elevation;
+            // it is ignored on POSIX.
+            await symlink(target, path, process.platform === 'win32' ? 'junction' : 'dir');
+        },
+    };
+}
+/**
+ * Every `node_modules` directory in `repo`, as repo-relative paths, down to
+ * {@link MAX_DEPTH}. Sorted, so the linking order (and any log of it) is stable.
+ */
+export async function findDependencyDirs(repo, fs = nodeLinkFs()) {
+    const found = [];
+    const walk = async (dir, depth) => {
+        if (await fs.isDirectory(join(dir, NODE_MODULES)))
+            found.push(relative(repo, join(dir, NODE_MODULES)));
+        if (depth >= MAX_DEPTH)
+            return;
+        for (const name of await fs.readdir(dir)) {
+            if (name.startsWith('.') || SKIP.has(name))
+                continue;
+            const child = join(dir, name);
+            if (await fs.isDirectory(child))
+                await walk(child, depth + 1);
+        }
+    };
+    await walk(repo, 0);
+    return found.sort();
+}
+/**
+ * Mirror `repo`'s dependency trees into `worktree` at the same relative paths: a real
+ * directory per tree, holding a link per entry (the package manager's private state
+ * left out, see above). Returns the trees mirrored. Best-effort throughout: a worktree
+ * with no deps is a worse run, not a failed one, so a link that cannot be made is
+ * skipped rather than thrown. A tree already present is left alone (the agent may
+ * have installed already).
+ */
+export async function linkDependencies(repo, worktree, fs = nodeLinkFs()) {
+    const linked = [];
+    for (const rel of await findDependencyDirs(repo, fs)) {
+        const source = join(repo, rel);
+        const dir = join(worktree, rel);
+        try {
+            if (await fs.entryExists(dir))
+                continue;
+            await fs.mkdir(dir);
+            for (const name of await fs.readdir(source)) {
+                if (isPrivate(name))
+                    continue;
+                if (isScope(name) && (await fs.isDirectory(join(source, name)))) {
+                    await fs.mkdir(join(dir, name));
+                    for (const pkg of await fs.readdir(join(source, name)))
+                        await fs.symlinkDir(join(source, name, pkg), join(dir, name, pkg)).catch(() => { });
+                }
+                else
+                    await fs.symlinkDir(join(source, name), join(dir, name)).catch(() => { });
+            }
+            linked.push(rel);
+        }
+        catch {
+            // Raced, or a filesystem that refuses the directory: the agent still starts.
+        }
+    }
+    return linked;
+}
+//# sourceMappingURL=worktree-deps.js.map

package/dist/worktree-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-deps.js","sourceRoot":"","sources":["../src/worktree-deps.ts"],"names":[],"mappings":"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"}

package/dist/worktree.d.ts

@@ -0,0 +1,220 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * Git-worktree lifecycle for concurrent agents (#453/#735): give each agent its own
+ * checkout so N agents on one repo never fight over the working tree. Pure plumbing
+ * over the {@link GitRunner} seam: this module only knows how to add, list, name,
+ * remove, and prune worktrees, and to read what a retention decision needs.
+ */
+/** The path an agent's worktree gets (#1580): `<repo>/.branches/<agent branch>`. */
+export declare function worktreePath(repo: string, agentId: string): string;
+/** One checkout on disk: where it is, and whose it is. */
+export interface WorktreeDirEntry {
+    path: string;
+    agentId: string;
+}
+/**
+ * Lists the names of the *directories* under `path` — a symlink is not one, whatever it points
+ * to. A missing or unreadable directory yields `[]`.
+ */
+export type DirReader = (path: string) => Promise<string[]>;
+/**
+ * Every checkout directory on disk (#1580): a directory under `.branches/` named as an agent
+ * branch. Only directories count — the same place holds the rename links (#1589), symlinks named
+ * as agent branches too, which are views, not checkouts. Forgiving: a missing root yields nothing.
+ */
+export declare function worktreeDirEntries(repo: string, readdir?: DirReader): Promise<WorktreeDirEntry[]>;
+/**
+ * The agent ids that have a worktree directory (#737/#1580). Forgiving — a project that never ran
+ * concurrently has no such dir and yields `[]`.
+ */
+export declare function listWorktreeDirs(repo: string, readdir?: DirReader): Promise<string[]>;
+/** One entry parsed from `git worktree list --porcelain`. */
+export interface WorktreeInfo {
+    /** Absolute worktree path (the main checkout included). */
+    path: string;
+    /** The checked-out commit. */
+    head: string;
+    /** The checked-out branch (short name), or absent when detached. */
+    branch?: string;
+}
+/** Inputs to {@link addWorktree}. The caller owns branch naming (#736). */
+export interface AddWorktreeOptions {
+    agentId: string;
+    /** The branch to create for the agent. */
+    branch: string;
+    /** Base ref to branch from; defaults to origin's default branch ({@link freshStart}). */
+    base?: string;
+}
+/** The worktree {@link addWorktree} created. */
+export interface AddedWorktree {
+    path: string;
+    branch: string;
+    /** The branch was gone everywhere and was made again, from the base or origin's default branch: nothing it held before is on it. */
+    again?: true;
+}
+/** How long a new agent branch waits for origin's default branch to be fetched: Claude Code's own cap. */
+export declare const FRESH_START_FETCH_MS = 5000;
+/**
+ * Create a worktree for an agent on a fresh branch: `git worktree add --no-track -b <branch>
+ * <path> <base>`, the base origin's default branch unless the caller names one. No upstream:
+ * tracking writes the repository's shared `.git/config`, whose lock a running agent's own git
+ * command in another checkout may hold. Git makes the leaf dir (and any missing parents) itself. The
+ * `agentId` is validated as path-safe first so a caller can never traverse out of
+ * `.branches/`. Rejects on any git failure (a caller that wants a
+ * run needs its checkout, so failure must surface, not be swallowed).
+ */
+export declare function addWorktree(repo: string, opts: AddWorktreeOptions, git?: GitRunner): Promise<AddedWorktree>;
+/**
+ * Check an *existing* branch out into an agent's worktree (#762). Continuing an agent puts it back
+ * on the branch its work is already on, rather than branching again and stranding what it did
+ * last time. The branch as this clone has it; else origin's copy, as a new local branch with no
+ * upstream set, as in {@link addWorktree}; else, gone everywhere, a new branch where the agent's
+ * first one started: the base the caller names, as this clone has it or else as origin does, and
+ * with none, or one that is gone too, where a new agent branch starts ({@link freshStart}); the
+ * answer then says the branch was made again. The
+ * only branch the package deletes is one that held nothing past a commit the remote already had,
+ * so nothing of the agent's is lost. Anything git refuses — the branch checked out elsewhere, say —
+ * rejects, like {@link addWorktree}: a continued agent needs its checkout.
+ */
+export declare function attachWorktree(repo: string, opts: {
+    agentId: string;
+    branch: string;
+    base?: string;
+}, git?: GitRunner): Promise<AddedWorktree>;
+/**
+ * Every worktree registered for the repo (the main checkout included). Forgiving:
+ * a non-repo / git failure yields `[]` so a reconcile scan never throws.
+ */
+export declare function listWorktrees(repo: string, git?: GitRunner): Promise<WorktreeInfo[]>;
+/**
+ * Parse `git worktree list --porcelain`: blank-line-separated records, each with
+ * a `worktree <path>` line, a `HEAD <sha>` line, and either `branch refs/heads/...`
+ * or `detached`. Extra attributes (bare/locked/prunable) are ignored. Exported so
+ * the parsing is unit-testable without a real repo.
+ */
+export declare function parseWorktreeList(porcelain: string): WorktreeInfo[];
+/**
+ * Remove an agent's worktree. Tolerant of an already-gone / never-registered path so
+ * teardown stays idempotent (a caller may run it twice).
+ *
+ * Plain removal first: it refuses a checkout git considers unclean, which after the
+ * caller's {@link worktreeClean} check means a state we did not anticipate. Falling back to
+ * `--force` keeps teardown working (an ignored build artifact must not strand a
+ * worktree forever), but it says so, because forcing past unknown state is exactly
+ * how uncommitted work got deleted in the first place.
+ */
+export declare function removeWorktree(repo: string, path: string, git?: GitRunner): Promise<void>;
+/**
+ * Delete a branch that holds nothing (#1650). `-D`, because "merged" in git's eyes is the wrong
+ * test: the caller proved the tip is a commit the remote already has, which is the stronger fact.
+ * Forgiving: the checkout is already gone by the time this runs, and a branch that would not
+ * delete is a leftover name, not lost work. Says whether it went, so a caller names only the
+ * branches that are actually gone (#1757).
+ */
+export declare function deleteBranch(repo: string, branch: string, git?: GitRunner): Promise<boolean>;
+/**
+ * Whether `path` is the root of a git worktree — the main checkout's or a linked one (#1654).
+ *
+ * Git answers for any directory *inside* a repository, so a `.branches/<agent>` directory that is
+ * no longer a worktree (a checkout removed by hand, a marker written after teardown) makes every
+ * git command run in it act on the enclosing repo: the user's own checkout, on the user's own
+ * branch. The one question that tells the two apart is whether git's top level is this very
+ * directory. False on any failure, and the caller leaves the directory alone.
+ */
+export declare function isWorktreeRoot(path: string, git?: GitRunner): Promise<boolean>;
+/**
+ * The branch checked out at `path` when `path` is a worktree root (#1654), else `undefined` —
+ * the read every consumer of a `.branches/<agent>` directory wants, so none of them can take the
+ * enclosing repo's branch for the run's.
+ */
+export declare function worktreeBranch(path: string, git?: GitRunner): Promise<string | undefined>;
+/**
+ * The branch checked out at `path`, or `undefined` when detached / not a repo.
+ * Forgiving, like {@link listWorktrees}: callers use it to decide, not to fail.
+ */
+export declare function currentBranch(path: string, git?: GitRunner): Promise<string | undefined>;
+/**
+ * The project a directory belongs to (#1725): the checkout whose `.branches/` holds the agent
+ * checkouts. From inside an agent's checkout that is two levels up, by the layout every checkout
+ * is created with; from anywhere else it is the checkout itself. Read from the layout rather than
+ * from git's common dir, so a project that is itself a linked worktree, or a submodule, answers
+ * with the directory the caller registered. Rejects outside a repo.
+ */
+export declare function projectRoot(cwd: string, git?: GitRunner): Promise<string>;
+/** A session name as the agent picks it: the charset the skill asks for. */
+export declare function isSessionName(name: string): boolean;
+/** Why {@link nameBranch} left the branch as it was. */
+export type NameBranchRefusal = 
+/** Not `[a-z0-9-]+`. */
+'invalid-name'
+/** The directory is not a git worktree root: nothing was run in it. */
+ | 'not-a-worktree'
+/** The checkout is on no branch (detached). */
+ | 'no-branch'
+/** The checkout is on a branch the package did not mint — the user's own. */
+ | 'not-an-agent-branch';
+export type NameBranchOutcome = {
+    ok: true;
+    /** The name the branch ends up with: `agent-<name>`, suffixed when that was taken. */
+    branch: string;
+} | {
+    ok: false;
+    reason: NameBranchRefusal;
+};
+/**
+ * Name the session (#1725): rename the checkout's branch to `agent-<name>`. A rename, not a new
+ * branch, so the branch the checkout was born on is the branch it ends on and nothing is left
+ * behind to clean up. Only a branch the package minted is ever renamed: an agent that somehow
+ * runs in the user's own checkout must not rename `main`.
+ *
+ * A taken name gets a numeric suffix (`agent-<name>-2`, `-3`, …) rather than a refusal: the agent
+ * asked for a name, and the caller reads back the one it got. Taken means any local branch or
+ * any remote-tracking branch, so the later push does not land on someone else's branch — except
+ * the checkout's own branch, pushed or not, which is why asking again for the name the checkout
+ * already carries (suffixed or not) changes nothing. Two checkouts naming the same thing at the
+ * same moment race on the rename itself; the loser reads the branches again and takes the next
+ * free suffix.
+ */
+export declare function nameBranch(path: string, name: string, git?: GitRunner): Promise<NameBranchOutcome>;
+/**
+ * `git worktree prune`: drop administrative entries for worktree dirs a crash left
+ * behind. Never removes a live worktree, so it is always safe. Forgiving.
+ */
+export declare function pruneWorktrees(repo: string, git?: GitRunner): Promise<void>;
+/** Runs `du`, resolving its stdout. Injectable so the size read can be tested without a real tree. */
+export type SizeRunner = (path: string) => Promise<string>;
+/** A {@link SizeRunner} over `du -sk`: one process, and it does not follow the symlinked deps (#736). */
+export declare function nodeSizeRunner(): SizeRunner;
+/**
+ * A worktree's size on disk in bytes, or undefined when it cannot be read (#798). Best-effort by
+ * design: this only ever labels a "remove this" button, so a missing number costs nothing while a
+ * throw or a hang would cost the listing it sits in. `du` is absent on Windows, which reads as
+ * unknown like any other failure.
+ */
+export declare function worktreeSize(path: string, size?: SizeRunner): Promise<number | undefined>;
+/**
+ * Whether a branch is on the remote, with the local tip already there.
+ *
+ * What a caller asks to say whether a branch's work is published yet.
+ *
+ * `git rev-parse` of the remote-tracking ref, then a merge-base check: the ref existing is not
+ * enough, because a branch pushed and then committed to again has a tip the remote has never seen.
+ * Reads only local refs (no fetch), so it is cheap enough to ask on every poll — the remote ref
+ * is written by the push this is checking for, which is what makes that sound.
+ *
+ * Anything unreadable answers `false`, and so does a repo with no remote configured.
+ */
+export declare function branchPushed(repo: string, branch: string, git?: GitRunner): Promise<boolean>;
+/**
+ * Whether the checkout has nothing uncommitted. A read, never a commit (#1638): the package
+ * commits nothing on an agent's behalf, so a checkout holding uncommitted work is one the caller
+ * keeps. Throws when git cannot answer, so the caller keeps the checkout rather than guessing.
+ */
+export declare function worktreeClean(path: string, git?: GitRunner): Promise<boolean>;
+/**
+ * Whether the repo has any remote configured at all: with none there is nowhere to publish a
+ * branch to, and a caller offers no push. Anything unreadable answers `false`, like
+ * {@link branchPushed}.
+ */
+export declare function repoHasRemote(repo: string, git?: GitRunner): Promise<boolean>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}