@openagt/skill-branches 0.0.1

package/dist/checkout.js

@@ -0,0 +1,37 @@
+import { nodeGitRunner, BRANCHES_DIR, excludeFromGit } from '@openagt/agent-data';
+import { agentBranchName } from './branch-names.js';
+import { addWorktree, attachWorktree } from './worktree.js';
+import { linkDependencies } from './worktree-deps.js';
+import { reconcileBranchLinks } from './branch-links.js';
+import { linkSkill } from './skill-links.js';
+import { linkOwnCommand } from './command-link.js';
+/** A new agent's checkout, on a fresh `agent-<id>` branch from `base` or origin's default branch. */
+export async function createCheckout(repo, opts, git = nodeGitRunner()) {
+    const worktree = await addWorktree(repo, { agentId: opts.agentId, branch: agentBranchName(opts.agentId), ...(opts.base ? { base: opts.base } : {}) }, git);
+    await settle(repo, worktree.path, git, opts.skills);
+    return worktree;
+}
+/** A continued agent's checkout, back on the branch its work is on; a branch gone everywhere starts again from `base`, or origin's default branch. */
+export async function attachCheckout(repo, opts, git = nodeGitRunner()) {
+    const worktree = await attachWorktree(repo, { agentId: opts.agentId, branch: opts.branch, ...(opts.base ? { base: opts.base } : {}) }, git);
+    await settle(repo, worktree.path, git, opts.skills);
+    return worktree;
+}
+/**
+ * What a checkout gets besides its files. All best-effort: the checkouts are the package's state
+ * and hidden from the project's git the moment the first one exists (#1600) — as an untracked
+ * directory at the root, `.branches/` would ride any sweeping `git add -A` onto a code branch —
+ * through the repository's own exclude file, so no tracked file changes; `node_modules` is
+ * gitignored, so a fresh checkout has none and a link that cannot be made is a worse run, not a
+ * failed one; the package's own command is linked into a checkout that has none, so the skill's
+ * `npx branches` runs it and downloads nothing (`command-link.ts`); a link under `.branches/` is a view, and the next reconcile pass makes it.
+ */
+async function settle(repo, path, git, skills = []) {
+    await excludeFromGit(repo, `/${BRANCHES_DIR}`, undefined, git).catch(() => { });
+    await linkDependencies(repo, path).catch(() => []);
+    // After the project's own tools: a project that installed this package keeps its copy of the command.
+    await linkOwnCommand(repo, path, git);
+    await linkSkill(repo, path, undefined, git, skills);
+    await reconcileBranchLinks(repo, { git }).catch(() => { });
+}
+//# sourceMappingURL=checkout.js.map

package/dist/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAsB,MAAM,eAAe,CAAA;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,SAAS,EAAkB,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAclD,qGAAqG;AACrG,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,IAAyD,EACzD,GAAG,GAAc,aAAa,EAAE;IAEhC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;IAC1J,MAAM,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACnD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,sJAAsJ;AACtJ,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,IAAyE,EACzE,GAAG,GAAc,aAAa,EAAE;IAEhC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;IAC3I,MAAM,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACnD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,IAAY,EAAE,GAAc,EAAE,MAAM,GAAyB,EAAE;IACjG,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,YAAY,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAC9E,MAAM,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAClD,sGAAsG;IACtG,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;IACrC,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;IACnD,MAAM,oBAAoB,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAC3D,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,36 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * The command line over the package (#1725): the same functions a caller's code calls, for an agent
+ * (and a person) in a shell. One implementation, every surface a caller.
+ *
+ * The contract: JSON on stdout, one line for a person on stderr, and the exit code says how it
+ * went — 0 for a result, 1 for a refusal or a git failure, 2 for a command that could not be
+ * read. A refusal is a rule saying no (a dirty tree, a name that is not a session name); it is
+ * reported on stdout as `{ ok: false, reason }` so a caller parsing the output learns why, and
+ * on stderr so a person does.
+ *
+ * Where the project is comes from the working directory: for every command that acts on the
+ * project (`create`, `attach`, `show`, `list`, `remove`, `prune`, and `push --branch`) it is
+ * the checkout whose `.branches/` the working directory is under, else the checkout itself — so
+ * the same command works from inside an agent's checkout; the commands that act on one checkout
+ * (`name`, `status`, a bare `push`) act on the one the working directory is in.
+ *
+ * Git only (#1820): what the project's git host does with a pushed branch, the pull request and its
+ * merge, is the git host package's own command; this one never names it.
+ */
+export declare const USAGE = "usage: branches <command>\n\n  create <id> [--base <ref>]   a checkout for agent <id>, on a fresh branch agent-<id>\n  attach <id> <branch> [--base <ref>]\n                               a checkout for agent <id>, on an existing branch; one that is gone starts again from <ref>\n  name <name>                  rename this checkout's branch to agent-<name>; prints the name it got\n  status [path]                the checkout's branch, whether it is clean, whether it is on the remote\n  show [--from <commit>] <branch>...\n                               what each branch holds and where it stands: its commits and files beyond the base, whether it is pushed, merged, and what its checkout left uncommitted;\n                               measured from <commit>, the one the branches started from, in place of the default branch; a full commit id in place of a branch is read as a branch that ends there\n  push [--branch <b>]          push this checkout's branch, or branch <b>, to origin; a dirty checkout is refused\n  merge <branch>               merge branch <branch> into the default branch, in the project's folder, then delete it; a conflict changes nothing and names the files\n  list [--sizes]               every agent checkout under .branches/\n  remove <id> [--from <commit>] reclaim agent <id>'s checkout, once its branch holds everything in it; the branch stays, nothing is pushed;\n                               <commit> is the one its branch started from, in place of the default branch\n         [--discard]           ... or drop it whatever it holds, uncommitted work included; the branch stays\n  prune                        remove, for every checkout\n\nJSON on stdout. Exit code 1 for a refusal or a git failure (the reason on stderr), 2 for a usage error.";
+/** The streams and the working directory a run of the CLI sees. */
+export interface CliIo {
+    cwd: string;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}
+/** A refusal: a rule said no, and the caller learns which. */
+export type CliRefusal = {
+    ok: false;
+    reason: string;
+    [key: string]: unknown;
+};
+/** Run the CLI: `argv` is everything after the program name. Resolves to the exit code. */
+export declare function runCli(argv: string[], io: CliIo, git?: GitRunner): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0C,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAsB5F;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,KAAK,yvDAkBsF,CAAA;AAExG,mEAAmE;AACnE,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAED,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAY9E,2FAA2F;AAC3F,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,GAAE,SAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBzG"}

package/dist/cli.js

@@ -0,0 +1,310 @@
+import { parseArgs } from 'node:util';
+import { basename, resolve } from 'node:path';
+import { realpath, stat } from 'node:fs/promises';
+import { nodeGitRunner, checkoutRoot, gitReason } from '@openagt/agent-data';
+import { agentBranchName, agentIdFromWorktreeDir, isSafeAgentId, sessionNameOf } from './branch-names.js';
+import { branchPushed, currentBranch, isWorktreeRoot, nameBranch, projectRoot, worktreeBranch, worktreeClean, worktreeDirEntries, worktreePath, worktreeSize, } from './worktree.js';
+import { createCheckout, attachCheckout } from './checkout.js';
+import { reconcileBranchLinks } from './branch-links.js';
+import { discardWorktree, reclaimWorktree } from './reclaim.js';
+import { pushBranchByName, pushCheckout } from './push.js';
+import { mergeBranch } from './merge.js';
+import { readBranchStates } from './branch-state.js';
+/**
+ * The command line over the package (#1725): the same functions a caller's code calls, for an agent
+ * (and a person) in a shell. One implementation, every surface a caller.
+ *
+ * The contract: JSON on stdout, one line for a person on stderr, and the exit code says how it
+ * went — 0 for a result, 1 for a refusal or a git failure, 2 for a command that could not be
+ * read. A refusal is a rule saying no (a dirty tree, a name that is not a session name); it is
+ * reported on stdout as `{ ok: false, reason }` so a caller parsing the output learns why, and
+ * on stderr so a person does.
+ *
+ * Where the project is comes from the working directory: for every command that acts on the
+ * project (`create`, `attach`, `show`, `list`, `remove`, `prune`, and `push --branch`) it is
+ * the checkout whose `.branches/` the working directory is under, else the checkout itself — so
+ * the same command works from inside an agent's checkout; the commands that act on one checkout
+ * (`name`, `status`, a bare `push`) act on the one the working directory is in.
+ *
+ * Git only (#1820): what the project's git host does with a pushed branch, the pull request and its
+ * merge, is the git host package's own command; this one never names it.
+ */
+export const USAGE = `usage: branches <command>
+
+  create <id> [--base <ref>]   a checkout for agent <id>, on a fresh branch agent-<id>
+  attach <id> <branch> [--base <ref>]
+                               a checkout for agent <id>, on an existing branch; one that is gone starts again from <ref>
+  name <name>                  rename this checkout's branch to agent-<name>; prints the name it got
+  status [path]                the checkout's branch, whether it is clean, whether it is on the remote
+  show [--from <commit>] <branch>...
+                               what each branch holds and where it stands: its commits and files beyond the base, whether it is pushed, merged, and what its checkout left uncommitted;
+                               measured from <commit>, the one the branches started from, in place of the default branch; a full commit id in place of a branch is read as a branch that ends there
+  push [--branch <b>]          push this checkout's branch, or branch <b>, to origin; a dirty checkout is refused
+  merge <branch>               merge branch <branch> into the default branch, in the project's folder, then delete it; a conflict changes nothing and names the files
+  list [--sizes]               every agent checkout under .branches/
+  remove <id> [--from <commit>] reclaim agent <id>'s checkout, once its branch holds everything in it; the branch stays, nothing is pushed;
+                               <commit> is the one its branch started from, in place of the default branch
+         [--discard]           ... or drop it whatever it holds, uncommitted work included; the branch stays
+  prune                        remove, for every checkout
+
+JSON on stdout. Exit code 1 for a refusal or a git failure (the reason on stderr), 2 for a usage error.`;
+/** Thrown inside a command to end it with a refusal. */
+class Refused extends Error {
+    outcome;
+    line;
+    constructor(outcome, line) {
+        super(line);
+        this.outcome = outcome;
+        this.line = line;
+    }
+}
+/** Thrown inside a command for an argument that cannot be read: usage on stderr, exit 2. */
+class Usage extends Error {
+}
+/** Run the CLI: `argv` is everything after the program name. Resolves to the exit code. */
+export async function runCli(argv, io, git = nodeGitRunner()) {
+    const [command, ...rest] = argv;
+    const run = command && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
+    if (!run) {
+        io.stderr(USAGE);
+        return 2;
+    }
+    try {
+        io.stdout(JSON.stringify(await run(rest, io.cwd, git)));
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof Usage) {
+            io.stderr(`${err.message}\n\n${USAGE}`);
+            return 2;
+        }
+        if (err instanceof Refused) {
+            io.stdout(JSON.stringify(err.outcome));
+            io.stderr(err.line);
+            return 1;
+        }
+        const detail = gitReason(err);
+        io.stdout(JSON.stringify({ ok: false, reason: 'git-failed', detail }));
+        io.stderr(detail);
+        return 1;
+    }
+}
+const COMMANDS = {
+    async create(args, cwd, git) {
+        const { positionals, values } = parse(args, { base: { type: 'string' } }, 1);
+        const agentId = agentIdArg(positionals[0]);
+        const repo = await project(cwd, git);
+        return { ok: true, ...(await createCheckout(repo, { agentId, ...(values.base ? { base: values.base } : {}) }, git)) };
+    },
+    async attach(args, cwd, git) {
+        const { positionals, values } = parse(args, { base: { type: 'string' } }, 2);
+        const [agentId, branch] = [agentIdArg(positionals[0]), positionals[1]];
+        const repo = await project(cwd, git);
+        return { ok: true, ...(await attachCheckout(repo, { agentId, branch, ...(values.base ? { base: values.base } : {}) }, git)) };
+    },
+    async name(args, cwd, git) {
+        const { positionals } = parse(args, {}, 1);
+        const name = positionals[0];
+        const checkout = await inRepo(() => checkoutRoot(cwd, git));
+        const outcome = await nameBranch(checkout, name, git);
+        if (!outcome.ok)
+            throw new Refused(outcome, NAME_REFUSALS[outcome.reason](name, checkout));
+        // The `.branches/<name>` link follows the rename now, not at the next reconcile.
+        await reconcileBranchLinks(await projectRoot(checkout, git), { git });
+        return outcome;
+    },
+    async status(args, cwd, git) {
+        const { positionals } = parse(args, {}, 0, 1);
+        const path = positionals[0] ? resolve(cwd, positionals[0]) : await inRepo(() => checkoutRoot(cwd, git));
+        if (!(await isWorktreeRoot(path, git)))
+            throw new Refused({ ok: false, reason: 'not-a-worktree', path }, `${path} is not a git worktree`);
+        const branch = await currentBranch(path, git);
+        const clean = await worktreeClean(path, git);
+        const onRemote = branch ? await branchPushed(await projectRoot(path, git), branch, git) : false;
+        return { ok: true, path, ...(branch ? { branch } : {}), clean, onRemote };
+    },
+    async show(args, cwd, git) {
+        const { values, positionals } = parse(args, { from: { type: 'string' } }, 1, Infinity);
+        if (values.from !== undefined && !values.from.trim())
+            throw new Usage('--from names a commit');
+        const repo = await project(cwd, git);
+        return readBranchStates(repo, positionals, git, values.from);
+    },
+    async push(args, cwd, git) {
+        const { values } = parse(args, { branch: { type: 'string' } }, 0);
+        if (values.branch !== undefined) {
+            if (!values.branch.trim())
+                throw new Usage('--branch names a branch');
+            const outcome = await pushBranchByName(await project(cwd, git), values.branch, git);
+            if (!outcome.ok)
+                throw new Refused(outcome, pushRefusalLine(values.branch, outcome));
+            return outcome;
+        }
+        const checkout = await inRepo(() => checkoutRoot(cwd, git));
+        const outcome = await pushCheckout(checkout, git);
+        if (!outcome.ok)
+            throw new Refused(outcome, pushRefusalLine(checkout, outcome));
+        return outcome;
+    },
+    async merge(args, cwd, git) {
+        const { positionals } = parse(args, {}, 1);
+        const repo = await project(cwd, git);
+        const outcome = await mergeBranch(repo, positionals[0], git);
+        if (!outcome.ok)
+            throw new Refused(outcome, mergeRefusalLine(outcome));
+        // A link named after a branch that just went is stale from this moment.
+        if (outcome.deleted)
+            await reconcileBranchLinks(repo, { git });
+        return outcome;
+    },
+    async list(args, cwd, git) {
+        const { values } = parse(args, { sizes: { type: 'boolean' } }, 0);
+        const repo = await project(cwd, git);
+        const rows = [];
+        for (const entry of await worktreeDirEntries(repo)) {
+            const branch = await worktreeBranch(entry.path, git);
+            const sizeBytes = values.sizes ? await worktreeSize(entry.path) : undefined;
+            const name = sessionNameOf(branch, entry.agentId);
+            rows.push({ ...entry, ...(branch ? { branch } : {}), ...(name ? { name } : {}), ...(sizeBytes === undefined ? {} : { sizeBytes }) });
+        }
+        return rows;
+    },
+    async remove(args, cwd, git) {
+        const { positionals, values } = parse(args, { discard: { type: 'boolean' }, from: { type: 'string' } }, 1);
+        if (values.from !== undefined && !values.from.trim())
+            throw new Usage('--from names a commit');
+        const agentId = agentIdArg(positionals[0]);
+        const repo = await project(cwd, git);
+        const outcome = values.discard ? await discard(repo, agentId, git) : await reclaim(repo, agentId, git, values.from);
+        if (!outcome.ok)
+            throw new Refused(outcome, refusalLine(agentId, outcome));
+        // A link named after a branch that just went with its checkout is stale from this moment.
+        await reconcileBranchLinks(repo, { git });
+        return outcome;
+    },
+    async prune(args, cwd, git) {
+        parse(args, {}, 0);
+        const repo = await project(cwd, git);
+        const removed = [];
+        const skipped = [];
+        for (const { agentId } of await worktreeDirEntries(repo)) {
+            const outcome = await reclaim(repo, agentId, git);
+            if (outcome.ok)
+                removed.push(agentId);
+            else
+                skipped.push({ agentId, reason: outcome.reason, detail: refusalLine(agentId, outcome) });
+        }
+        // Once for the whole pass: a reconcile reads every checkout that is left.
+        if (removed.length)
+            await reconcileBranchLinks(repo, { git });
+        return { ok: true, removed, skipped };
+    },
+};
+/**
+ * One agent's checkout under the reclaim rule; a missing checkout is its own refusal. The
+ * argument may be the session name a rename link carries rather than the id, so the birth
+ * branch is read off the checkout's own directory, never off the argument (#1757): a link's
+ * name is the branch the agent chose, and that one is not the birth branch.
+ */
+async function reclaim(repo, agentId, git, from) {
+    const path = worktreePath(repo, agentId);
+    if (!(await stat(path).then(s => s.isDirectory(), () => false)))
+        return { ok: false, reason: 'no-checkout', agentId };
+    const checkout = await realpath(path);
+    return reclaimWorktree(repo, checkout, { birthBranch: agentBranchName(agentIdFromWorktreeDir(basename(checkout))), ...(from !== undefined ? { from } : {}), git });
+}
+/** One agent's checkout dropped whatever it holds; a missing checkout is its own refusal. */
+async function discard(repo, agentId, git) {
+    const path = worktreePath(repo, agentId);
+    if (!(await stat(path).then(s => s.isDirectory(), () => false)))
+        return { ok: false, reason: 'no-checkout', agentId };
+    return discardWorktree(repo, await realpath(path), { git });
+}
+/** Why a checkout stayed, as one line for a person. */
+function refusalLine(agentId, outcome) {
+    const reason = outcome.reason;
+    switch (reason) {
+        case 'no-checkout':
+            return `no checkout for agent ${agentId}`;
+        case 'not-a-worktree':
+            return `agent ${agentId}'s directory is not a git worktree; left alone`;
+        case 'no-branch':
+            return `agent ${agentId}'s checkout is on no branch; kept`;
+        case 'dirty':
+            return `${branchOf(outcome)} has uncommitted work; the checkout was kept`;
+    }
+}
+const branchOf = (outcome) => String(outcome.branch);
+/** Why a branch was not pushed, as one line for a person. */
+function mergeRefusalLine(outcome) {
+    switch (outcome.reason) {
+        case 'no-branch':
+            return `no branch ${outcome.branch} on this machine`;
+        case 'no-default-branch':
+            return 'the project has no main branch to merge into';
+        case 'not-on-default':
+            return `the project's folder is on ${outcome.current ?? 'no branch'}, not on ${outcome.into}; switch it to ${outcome.into}, then merge`;
+        case 'dirty':
+            return `${outcome.branch} has uncommitted work; commit or delete it, then merge`;
+        case 'conflict':
+            return `${outcome.branch} does not merge cleanly into ${outcome.into}: it conflicts in ${outcome.files.join(', ')}; nothing was changed`;
+        case 'merge-failed':
+            return `${outcome.branch} could not be merged into ${outcome.into}: ${outcome.detail}`;
+    }
+}
+function pushRefusalLine(subject, outcome) {
+    switch (outcome.reason) {
+        case 'not-a-worktree':
+            return `${subject} is not a git worktree`;
+        case 'no-branch':
+            return outcome.branch !== undefined ? `no branch ${outcome.branch}, here or on origin` : `${subject} is on no branch`;
+        case 'dirty':
+            return `${outcome.branch} has uncommitted work; commit or delete it, then push`;
+        case 'push-failed':
+            return `${outcome.branch} could not be pushed: ${outcome.detail ?? 'the push did not land'}`;
+    }
+}
+const NAME_REFUSALS = {
+    'invalid-name': name => `${name} is not a session name: use [a-z0-9-]+`,
+    'not-a-worktree': (_, checkout) => `${checkout} is not a git worktree`,
+    'no-branch': (_, checkout) => `${checkout} is on no branch`,
+    'not-an-agent-branch': (_, checkout) => `${checkout} is not on an agent branch; only agent-* branches are renamed`,
+};
+/** An agent id is path-safe, or the command has nothing to name a checkout with. */
+function agentIdArg(agentId) {
+    if (!isSafeAgentId(agentId))
+        throw new Refused({ ok: false, reason: 'invalid-id', agentId }, `${agentId} is not an agent id`);
+    return agentId;
+}
+/** The project the working directory belongs to. */
+async function project(cwd, git) {
+    return inRepo(() => projectRoot(cwd, git));
+}
+/**
+ * Outside a repo, the commands have nothing to act on: said as a refusal, not a git failure.
+ * Only git's own "not a git repository" reads as that; a timeout, a missing git, or a corrupt
+ * repo stays the failure it is.
+ */
+async function inRepo(read) {
+    try {
+        return await read();
+    }
+    catch (err) {
+        if (!/not a git repository/i.test(err instanceof Error ? err.message : String(err)))
+            throw err;
+        throw new Refused({ ok: false, reason: 'not-a-repo' }, 'not inside a git repository');
+    }
+}
+/** `parseArgs` with the positional count checked: too few or too many is a usage error. */
+function parse(args, options, min, max = min) {
+    try {
+        const parsed = parseArgs({ args, options, allowPositionals: true, strict: true });
+        if (parsed.positionals.length < min || parsed.positionals.length > max)
+            throw new Usage(`expected ${max === min ? min : max === Infinity ? `at least ${min}` : `${min} to ${max}`} argument(s), got ${parsed.positionals.length}`);
+        return parsed;
+    }
+    catch (err) {
+        throw err instanceof Usage ? err : new Usage(err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/command-link.d.ts

@@ -0,0 +1,20 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * This package's command, linked into a checkout that has none: `node_modules/.bin/branches`.
+ *
+ * The skill tells the agent to run `npx branches`. In a project that depends on this package the
+ * checkout already has the command, linked with the project's other tools. In a project with
+ * nothing installed (an empty folder a dashboard added) it has none, and `npx` then downloads
+ * whatever package holds the name `branches` on npm and runs it: a stranger's code, in the
+ * person's project. With the command linked here `npx` finds it in the checkout and downloads
+ * nothing.
+ *
+ * Hidden from the project's git through the repository's exclude file, like the skill's link: the
+ * link is the package's state, not the agent's work. Best-effort: a command already there (the
+ * project's own copy) is left alone, and a link that cannot be made is a worse run, not a failed
+ * one.
+ */
+/** The command's name, and where a checkout holds its tools. */
+export declare const COMMAND = "branches";
+export declare function linkOwnCommand(repo: string, checkout: string, git?: GitRunner): Promise<void>;
+//# sourceMappingURL=command-link.d.ts.map

package/dist/command-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-link.d.ts","sourceRoot":"","sources":["../src/command-link.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGnF;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,eAAO,MAAM,OAAO,aAAa,CAAA;AAGjC,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,SAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpH"}

package/dist/command-link.js

@@ -0,0 +1,37 @@
+import { lstat, mkdir, symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { excludeFromGit, nodeGitRunner } from '@openagt/agent-data';
+import { CLI_BIN_DIR } from './bin-dir.js';
+/**
+ * This package's command, linked into a checkout that has none: `node_modules/.bin/branches`.
+ *
+ * The skill tells the agent to run `npx branches`. In a project that depends on this package the
+ * checkout already has the command, linked with the project's other tools. In a project with
+ * nothing installed (an empty folder a dashboard added) it has none, and `npx` then downloads
+ * whatever package holds the name `branches` on npm and runs it: a stranger's code, in the
+ * person's project. With the command linked here `npx` finds it in the checkout and downloads
+ * nothing.
+ *
+ * Hidden from the project's git through the repository's exclude file, like the skill's link: the
+ * link is the package's state, not the agent's work. Best-effort: a command already there (the
+ * project's own copy) is left alone, and a link that cannot be made is a worse run, not a failed
+ * one.
+ */
+/** The command's name, and where a checkout holds its tools. */
+export const COMMAND = 'branches';
+const BIN_DIR = 'node_modules/.bin';
+export async function linkOwnCommand(repo, checkout, git = nodeGitRunner()) {
+    const link = join(checkout, BIN_DIR, COMMAND);
+    // lstat, not stat: a link that is there counts, whatever it points at.
+    if (await lstat(link).then(() => true, () => false))
+        return;
+    await excludeFromGit(repo, `/${BIN_DIR}/${COMMAND}`, undefined, git).catch(() => { });
+    try {
+        await mkdir(join(checkout, BIN_DIR), { recursive: true });
+        await symlink(join(CLI_BIN_DIR, COMMAND), link);
+    }
+    catch {
+        // A filesystem that refuses the link: the agent still starts.
+    }
+}
+//# sourceMappingURL=command-link.js.map

package/dist/command-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-link.js","sourceRoot":"","sources":["../src/command-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAkB,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAA;AACjC,MAAM,OAAO,GAAG,mBAAmB,CAAA;AAEnC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,QAAgB,EAAE,GAAG,GAAc,aAAa,EAAE;IACnG,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IAC7C,uEAAuE;IACvE,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC;QAAE,OAAM;IAC3D,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,OAAO,IAAI,OAAO,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACpF,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACzD,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAA;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC"}

package/dist/file-branch.d.ts

@@ -0,0 +1,150 @@
+import { type GitRunner } from './git.js';
+/** The persistent checkout of `branch` under a project: `<repo>/.branches/<branch>`. */
+export declare function fileBranchPath(repo: string, branch: string): string;
+/** Injectable seams; production takes the defaults. */
+export interface FileBranchDeps {
+    git?: GitRunner;
+    log?: (message: string) => void;
+}
+/**
+ * Make sure the branch and its persistent checkout exist. Idempotent and cheap when everything is
+ * in place (one `git rev-parse` against the checkout); never throws — a project this cannot be
+ * set up in reports why and is left alone.
+ */
+export declare function ensureFileBranch(repo: string, branch: string, deps?: FileBranchDeps): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * What one funneled write did. `changed: false` is the clean no-op (the op wrote nothing new).
+ * A failure says whether the change still landed as a local commit (`committed` — the push is
+ * what failed, and the next cycle carries it out) or nothing survived at all.
+ */
+export type FileBranchWrite = {
+    ok: true;
+    changed: boolean;
+    pushed: boolean;
+} | {
+    ok: false;
+    committed: boolean;
+    error: string;
+};
+/** A writer's message: fixed, or resolved after the op ran (a batch only knows what it did then). */
+export type CommitMessage = string | (() => string);
+/**
+ * Apply one change to the branch through its persistent checkout: sync with origin, run `op`
+ * against the checkout, commit whatever it changed, push. The single funnel a long-lived
+ * process's writes go through.
+ *
+ * `op` must be re-runnable: when the push loses a race with another writer, the cycle re-syncs
+ * and runs it again against the fresher state rather than force-fitting a stale commit — the op
+ * *is* the intent, the commit is just its serialization. Two attempts; a push that still fails
+ * (the network, most likely) keeps the commit local and reports the error — the next cycle's sync
+ * rebases it onto whatever origin has by then, and the next push carries it.
+ *
+ * Never throws: callers run on background ticks with nothing to catch it.
+ */
+export declare function withFileBranch(repo: string, branch: string, message: CommitMessage, op: (dir: string) => Promise<void>, deps?: FileBranchDeps): Promise<FileBranchWrite>;
+/** How a pull went: converged with origin, or why it could not. */
+export type FileBranchSync = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The eager pull: sync the persistent checkout with origin so this machine reads what other
+ * machines and cloud sessions committed, without waiting for the next local write — and push
+ * anything a failed cycle left stranded locally, via the same owed-push rule as the writer.
+ * Ensures the checkout exists, so a fresh clone converges on its first tick. Never throws.
+ *
+ * Reports why it could not converge: a push origin rejects, or no origin to converge with at
+ * all. The writer treats a remote-less repo as fine — the commit is safe locally — but a sync's
+ * whole job is to meet the other machines, and a repo nothing can reach is an error state the
+ * caller has to surface, not a mode this supports.
+ */
+export declare function pullFileBranch(repo: string, branch: string, deps?: FileBranchDeps): Promise<FileBranchSync>;
+/**
+ * The repository `cwd` belongs to: the directory holding the repo's real `.git`. From the main
+ * checkout that is `cwd` itself; from an agent's worktree it is the repo the worktree was made
+ * from — where the persistent checkout lives, and the address every funneled write goes to.
+ * `undefined` outside any repo.
+ */
+export declare function fileBranchRepo(cwd: string, git?: GitRunner): Promise<string | undefined>;
+/**
+ * Read one file off the branch, from anywhere in the repo: the persistent checkout when this
+ * `cwd`'s repo has one, else `git show` against the local branch (worktrees share the repo's
+ * refs, so an agent's checkout reads the same files without holding any of them), else against
+ * `origin/…`. `undefined` when the file exists in none of them. Never throws.
+ */
+export declare function readBranchFile(cwd: string, branch: string, rel: string, opts?: {
+    fresh?: boolean;
+}, deps?: FileBranchDeps): Promise<string | undefined>;
+/**
+ * The entries of one directory on the branch, by name — a read off the ref, like
+ * {@link readBranchFile}, for a reader that holds no checkout. `[]` for a directory the branch
+ * does not have. Never throws.
+ */
+export declare function listBranchDir(cwd: string, branch: string, dir: string, opts?: {
+    fresh?: boolean;
+}, deps?: FileBranchDeps): Promise<string[]>;
+/** Reads off one ref of the branch, for a reader that opens many files: fetched once, up front. */
+export interface BranchReader {
+    /** The ref every read goes to: origin's copy when the repo has a remote, else the local branch. */
+    ref: string;
+    /** One file's content, or `undefined` when the ref has no such file. */
+    read: (rel: string) => Promise<string | undefined>;
+    /** One directory's entries by name; `[]` when the ref has no such directory. */
+    list: (dir: string) => Promise<string[]>;
+}
+/**
+ * Open the branch for reading from any clone, holding no checkout: fetch origin's copy once and
+ * read that (a one-shot reader — a command an agent runs — must see what other writers pushed,
+ * its own detached write included, which the local ref never moves for), else the local branch
+ * when there is no remote. Every read then goes to that one ref; nothing is fetched again.
+ */
+export declare function openBranchReader(cwd: string, branch: string, deps?: FileBranchDeps): Promise<BranchReader>;
+/** What a detached write did, or why it could not: the repo has no remote to carry it. */
+export type DetachedWrite = {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: 'no-remote';
+};
+/**
+ * Apply one change to the branch as a one-shot remote writer, from any clone: fetch origin's
+ * tip, check it out in a throwaway worktree, run `op` against it, commit, push straight to the
+ * branch, remove the worktree. A push that loses a race re-fetches, resets to origin's tip and
+ * re-runs the op, twice, the same intent rule as the funnel; a push that still fails throws with
+ * git's reason.
+ *
+ * Never the persistent checkout: that is a long-lived process's, whose funnel sweeps its
+ * checkout with `git add -A` and resets it on failure, so a second writer inside it would be
+ * committed under the wrong message or wiped. The local branch ref is not moved either — the
+ * persistent checkout, when there is one, converges on its own next pull.
+ *
+ * A branch origin does not have yet is born by the write itself, parentless. A repo with no
+ * remote refuses: a change nothing can reach is the caller's error state, not a mode.
+ */
+export declare function writeFileBranchDetached(cwd: string, branch: string, message: CommitMessage, op: (dir: string) => Promise<void>, deps?: FileBranchDeps): Promise<DetachedWrite>;
+/**
+ * The file seams an operation inside a funneled write needs — read, write, delete and list plain
+ * files under the directory the funnel hands it. Injectable so an operation is unit-testable off
+ * disk and git; production takes the defaults. Parents are created on write because the
+ * directory itself is not a given: retiring the last file removes it (git keeps no empty dirs),
+ * and a branch is born without it.
+ */
+export interface BranchFileFs {
+    /** Read one file; rejects when it cannot — a caller reads the rejection as "absent". */
+    read: (path: string) => Promise<string>;
+    /** Write one file, creating parents. */
+    write: (path: string, content: string) => Promise<void>;
+    /** Delete one file. */
+    remove: (path: string) => Promise<void>;
+    /** The files under a directory, by filename; a missing directory reads as none. */
+    list: (dir: string) => Promise<string[]>;
+}
+/** {@link BranchFileFs} over `node:fs/promises`. */
+export declare function nodeBranchFileFs(): BranchFileFs;
+//# sourceMappingURL=file-branch.d.ts.map