@openagt/skill-branches 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: branches
+description: Where your work goes (a branch named agent-<name>), how to name it, what must be true before you finish, and how to push it when you are asked to.
+---
+
+# Branch management
+
+Your work goes on a branch named `agent-<name>`, unless whoever started you continued you on another. It stays on this machine until you are asked to push it.
+
+## The command
+
+`branches` is a dependency of this repository (`@openagt/skill-branches`). If `node_modules` is missing, install with the lockfile's package manager (`npm install` for `package-lock.json`). Then run `npx branches` inside your checkout, never a bare `branches`: a fresh clone has none. `status`, `name` and `push` (with no flag) are yours; the rest are the caller's.
+
+## Where you are
+
+```
+npx branches status
+```
+
+It prints JSON; `branch` is the branch you are on.
+
+**A branch starting with `agent-`.** Its checkout is your whole workspace: read and write only there. Dependency files and skill folders are links to the user's copies: never edit them. If something you need is outside your checkout, say so and stop.
+
+Before your first change, name the session with `[a-z0-9-]+`, starting with a letter or digit, saying what the work is, unless your branch already differs from `path`'s last segment: then it is named, keep it.
+
+```
+npx branches name <name>
+```
+
+It renames your branch to `agent-<name>` and prints it in `branch`: `agent-<name>-2`, `-3`, … when `<name>` was taken; a name outside `[a-z0-9-]+` is refused as `invalid-name`.
+
+**Any other branch.** If the checkout sits under `.branches/`, you were put on this branch on purpose: stay on it, do not name it. Otherwise you are in a plain clone on someone else's branch. Before your first change, create your own and switch to it, `<name>` as above (another if it exists, locally or on origin):
+
+```
+git switch -c agent-<name>
+```
+
+From then on, work as on an `agent-` branch; nothing in a plain clone is a link.
+
+## Commit as you go
+
+Nothing is committed for you.
+
+## Before you finish
+
+```
+npx branches status
+```
+
+It must report `"clean": true`. `clean` is false while anything is uncommitted or untracked: commit or delete what you added; if what remains is not yours, say so and finish.
+
+## Push
+
+Only when your task or the person asks you to push or publish your work, and once clean:
+
+```
+npx branches push
+```
+
+It pushes your branch to origin and prints it in `branch`. `clean` false is refused as `dirty`: commit or delete first.
+
+## Merge
+
+Only when the person asks you to merge your work into the project's main branch, and once clean:
+
+```
+npx branches merge <your branch>
+```
+
+It merges your branch into the main branch, in the project's own folder. A conflict changes nothing and names the files in `files`: say so and stop. Your checkout and your branch stay.

package/bin/branches

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli.js'
+
+runCli(process.argv.slice(2), { cwd: process.cwd(), stdout: line => console.log(line), stderr: line => console.error(line) })
+  .then(code => {
+    process.exitCode = code
+  })
+  .catch(err => {
+    console.error(err)
+    process.exitCode = 1
+  })

package/dist/bin-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Where the `branches` executable lives, for a caller that puts it on a spawned
+ * process's PATH (#1725); an agent itself runs it through `npx`. Beside `dist/`, so it is the
+ * same path from a workspace checkout and from an installed package.
+ */
+export declare const CLI_BIN_DIR: string;
+//# sourceMappingURL=bin-dir.d.ts.map

package/dist/bin-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-dir.d.ts","sourceRoot":"","sources":["../src/bin-dir.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAqD,CAAA"}

package/dist/bin-dir.js

@@ -0,0 +1,8 @@
+import { fileURLToPath } from 'node:url';
+/**
+ * Where the `branches` executable lives, for a caller that puts it on a spawned
+ * process's PATH (#1725); an agent itself runs it through `npx`. Beside `dist/`, so it is the
+ * same path from a workspace checkout and from an installed package.
+ */
+export const CLI_BIN_DIR = fileURLToPath(new URL('../bin/', import.meta.url));
+//# sourceMappingURL=bin-dir.js.map

package/dist/bin-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-dir.js","sourceRoot":"","sources":["../src/bin-dir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA"}

package/dist/branch-links.d.ts

@@ -0,0 +1,37 @@
+import { type GitRunner } from '@openagt/agent-data';
+import { type WorktreeDirEntry } from './worktree.js';
+/** The filesystem the reconcile needs; `node:fs/promises` in production. */
+export interface LinksFs {
+    /** Names under `dir`; a missing dir yields `[]`. */
+    readdir(dir: string): Promise<string[]>;
+    /** Recursive mkdir. */
+    mkdir(dir: string): Promise<void>;
+    /** Create a symlink at `path` pointing to `target`. */
+    symlink(target: string, path: string): Promise<void>;
+    /** A symlink's target, or `undefined` when `path` is missing or not a symlink. */
+    readlink(path: string): Promise<string | undefined>;
+    /** Remove one file or symlink. */
+    unlink(path: string): Promise<void>;
+    /** Whether anything (file, dir, or dangling link) sits at `path`. */
+    lexists(path: string): Promise<boolean>;
+}
+/** Injectable seams for {@link reconcileBranchLinks}. */
+export interface BranchLinksDeps {
+    git?: GitRunner;
+    fs?: LinksFs;
+    /** The checkouts on disk (default {@link worktreeDirEntries}). */
+    worktrees?: (cwd: string) => Promise<WorktreeDirEntry[]>;
+    /** The branch a worktree is on, or none when the path is not a worktree root (default {@link worktreeBranch}). */
+    branchOf?: (path: string) => Promise<string | undefined>;
+}
+/**
+ * Bring one project's `.branches/` links in line with its worktrees: one link per worktree, named
+ * as the branch the worktree is on right now. Renames are covered by the same rule — the old name
+ * stops being wanted and is dropped, the new one is created.
+ *
+ * Touches only what is provably ours: a link is created, replaced, or removed only when it points
+ * (or would point) at a sibling checkout; anything else at those paths — a user's own file, dir,
+ * or symlink — is left alone. Never throws.
+ */
+export declare function reconcileBranchLinks(cwd: string, deps?: BranchLinksDeps): Promise<void>;
+//# sourceMappingURL=branch-links.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-links.d.ts","sourceRoot":"","sources":["../src/branch-links.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,SAAS,EAAgB,MAAM,qBAAqB,CAAA;AAEjF,OAAO,EAAsC,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAYzF,4EAA4E;AAC5E,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACvC,uBAAuB;IACvB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,uDAAuD;IACvD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACnD,kCAAkC;IAClC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,qEAAqE;IACrE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxC;AAeD,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACxD,kHAAkH;IAClH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjG"}

package/dist/branch-links.js

@@ -0,0 +1,67 @@
+import { basename, join } from 'node:path';
+import { nodeGitRunner, BRANCHES_DIR } from '@openagt/agent-data';
+import { isAgentBranch } from './branch-names.js';
+import { worktreeDirEntries, worktreeBranch } from './worktree.js';
+/** A {@link LinksFs} over `node:fs/promises`. */
+function nodeLinksFs() {
+    const fs = () => import('node:fs/promises');
+    return {
+        readdir: dir => fs().then(f => f.readdir(dir)).catch(() => []),
+        mkdir: dir => fs().then(f => f.mkdir(dir, { recursive: true })).then(() => { }),
+        symlink: (target, path) => fs().then(f => f.symlink(target, path)),
+        readlink: path => fs().then(f => f.readlink(path)).catch(() => undefined),
+        unlink: path => fs().then(f => f.unlink(path)),
+        lexists: path => fs().then(f => f.lstat(path)).then(() => true, () => false),
+    };
+}
+/**
+ * Bring one project's `.branches/` links in line with its worktrees: one link per worktree, named
+ * as the branch the worktree is on right now. Renames are covered by the same rule — the old name
+ * stops being wanted and is dropped, the new one is created.
+ *
+ * Touches only what is provably ours: a link is created, replaced, or removed only when it points
+ * (or would point) at a sibling checkout; anything else at those paths — a user's own file, dir,
+ * or symlink — is left alone. Never throws.
+ */
+export async function reconcileBranchLinks(cwd, deps = {}) {
+    const git = deps.git ?? nodeGitRunner();
+    const fs = deps.fs ?? nodeLinksFs();
+    const worktrees = deps.worktrees ?? worktreeDirEntries;
+    // A `.branches/` directory that is not a worktree root reads as no branch (#1654): otherwise
+    // it reads as the enclosing repo's, and a link named after the user's own branch appears.
+    const branchOf = deps.branchOf ?? ((path) => worktreeBranch(path, git));
+    const linksDir = join(cwd, BRANCHES_DIR);
+    /** Link name -> relative target, derived from what is actually checked out. */
+    const wanted = new Map();
+    for (const entry of await worktrees(cwd).catch(() => [])) {
+        const branch = await branchOf(entry.path).catch(() => undefined);
+        // A detached worktree has no name to link; a slashed name cannot be a
+        // link name at all — both simply get no link.
+        if (!branch || branch.includes('/'))
+            continue;
+        // The link is a sibling of the checkout. A dir already carrying the branch's name needs none.
+        const target = basename(entry.path);
+        if (branch === target)
+            continue;
+        wanted.set(branch, target);
+    }
+    // Drop our stale links: entries that are symlinks to a sibling checkout but no longer wanted,
+    // or wanted with a different target (a reused branch name now belongs to a newer worktree).
+    for (const name of await fs.readdir(linksDir)) {
+        const path = join(linksDir, name);
+        const target = await fs.readlink(path);
+        if (target === undefined || !isAgentBranch(target))
+            continue; // not ours to touch
+        if (wanted.get(name) === target)
+            continue;
+        await fs.unlink(path).catch(() => { });
+    }
+    for (const [name, target] of wanted) {
+        const path = join(linksDir, name);
+        if (await fs.lexists(path))
+            continue; // ours-and-current, or someone else's — either way, stay
+        await fs.mkdir(linksDir);
+        await fs.symlink(target, path).catch(() => { });
+    }
+}
+//# sourceMappingURL=branch-links.js.map

package/dist/branch-links.js.map

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

package/dist/branch-names.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The naming rules for everything the package mints in git, and the layout they imply under
+ * `.branches/` (the directory is `@openagt/agent-data`'s convention).
+ * Pure: no node imports, so browser-safe code can name branches too.
+ */
+/**
+ * An agent id is path-safe — no separators or traversal, only our own charset — and is not `data`:
+ * `agent-data` is the shared data branch of `@openagt/agent-data`, checked out beside the agent
+ * checkouts as `.branches/agent-data`, and an agent of that id would be indistinguishable from it.
+ */
+export declare function isSafeAgentId(id: string): boolean;
+/**
+ * What every branch the package mints is named under. Slash-free on purpose: a `/` in a ref name
+ * never resolves as a cloud session's revision (anthropics/claude-code#87235), and it is what
+ * lets a checkout directory be named exactly as its branch.
+ */
+export declare const AGENT_BRANCH_PREFIX = "agent-";
+/**
+ * The branch a checkout is created on: `agent-<agent id>`. The agent id exists before the session
+ * name does, so the branch is created from the id and renamed once the agent picks a name. It is
+ * also the checkout directory's name under `.branches/`, so the listing reads as branch names.
+ */
+export declare function agentBranchName(agentId: string): string;
+/** The inverse of {@link agentBranchName}: the agent id a checkout directory's name carries. */
+export declare function agentIdFromWorktreeDir(name: string): string;
+/**
+ * Whether a branch is one the package minted for an agent: the branch a checkout was created on,
+ * or the session-named `agent-<name>` it was renamed to. The only branches the package ever
+ * renames or deletes; a branch of the user's own is out of reach by name alone, and so is the
+ * data branch, `agent-data`, which carries the prefix without being anyone's.
+ */
+export declare function isAgentBranch(name: string): boolean;
+/**
+ * The session name a checkout's branch carries: `agent-<session name>` minus the prefix. The name
+ * is read off the branch and never recorded beside it — a checkout has one branch, and that
+ * branch is the name. Undefined for a branch the package did not mint, and while the agent has
+ * not named its session: the branch is still the one the checkout was created on, which the
+ * agent id names — a caller without an id has no such branch to rule out.
+ */
+export declare function sessionNameOf(branch: string | undefined, agentId: string | undefined): string | undefined;
+//# sourceMappingURL=branch-names.d.ts.map

package/dist/branch-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-names.d.ts","sourceRoot":"","sources":["../src/branch-names.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAA;AAE3C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzG"}

package/dist/branch-names.js

@@ -0,0 +1,54 @@
+import { DATA_BRANCH } from '@openagt/agent-data/names';
+/**
+ * The naming rules for everything the package mints in git, and the layout they imply under
+ * `.branches/` (the directory is `@openagt/agent-data`'s convention).
+ * Pure: no node imports, so browser-safe code can name branches too.
+ */
+/**
+ * An agent id is path-safe — no separators or traversal, only our own charset — and is not `data`:
+ * `agent-data` is the shared data branch of `@openagt/agent-data`, checked out beside the agent
+ * checkouts as `.branches/agent-data`, and an agent of that id would be indistinguishable from it.
+ */
+export function isSafeAgentId(id) {
+    return /^[A-Za-z0-9_-]+$/.test(id) && agentBranchName(id) !== DATA_BRANCH;
+}
+/**
+ * What every branch the package mints is named under. Slash-free on purpose: a `/` in a ref name
+ * never resolves as a cloud session's revision (anthropics/claude-code#87235), and it is what
+ * lets a checkout directory be named exactly as its branch.
+ */
+export const AGENT_BRANCH_PREFIX = 'agent-';
+/**
+ * The branch a checkout is created on: `agent-<agent id>`. The agent id exists before the session
+ * name does, so the branch is created from the id and renamed once the agent picks a name. It is
+ * also the checkout directory's name under `.branches/`, so the listing reads as branch names.
+ */
+export function agentBranchName(agentId) {
+    return `${AGENT_BRANCH_PREFIX}${agentId}`;
+}
+/** The inverse of {@link agentBranchName}: the agent id a checkout directory's name carries. */
+export function agentIdFromWorktreeDir(name) {
+    return name.slice(AGENT_BRANCH_PREFIX.length);
+}
+/**
+ * Whether a branch is one the package minted for an agent: the branch a checkout was created on,
+ * or the session-named `agent-<name>` it was renamed to. The only branches the package ever
+ * renames or deletes; a branch of the user's own is out of reach by name alone, and so is the
+ * data branch, `agent-data`, which carries the prefix without being anyone's.
+ */
+export function isAgentBranch(name) {
+    return name.startsWith(AGENT_BRANCH_PREFIX) && name !== DATA_BRANCH;
+}
+/**
+ * The session name a checkout's branch carries: `agent-<session name>` minus the prefix. The name
+ * is read off the branch and never recorded beside it — a checkout has one branch, and that
+ * branch is the name. Undefined for a branch the package did not mint, and while the agent has
+ * not named its session: the branch is still the one the checkout was created on, which the
+ * agent id names — a caller without an id has no such branch to rule out.
+ */
+export function sessionNameOf(branch, agentId) {
+    if (!branch || !isAgentBranch(branch) || (agentId !== undefined && branch === agentBranchName(agentId)))
+        return undefined;
+    return branch.slice(AGENT_BRANCH_PREFIX.length);
+}
+//# sourceMappingURL=branch-names.js.map

package/dist/branch-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-names.js","sourceRoot":"","sources":["../src/branch-names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAEvD;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,CAAC,KAAK,WAAW,CAAA;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAA;AAE3C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,GAAG,mBAAmB,GAAG,OAAO,EAAE,CAAA;AAC3C,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,IAAI,IAAI,KAAK,WAAW,CAAA;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAA0B,EAAE,OAA2B;IACnF,IAAI,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,KAAK,eAAe,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IACzH,OAAO,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACjD,CAAC"}

package/dist/branch-state.d.ts

@@ -0,0 +1,68 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * What a branch holds and where it stands (#1774): the caller's read of a finished agent's
+ * work, for the run page's handoff and the "never pushed" queue. Git facts only, read from the
+ * project's repository, so the answer is the same whether or not the agent's checkout still
+ * exists: the commits the branch has beyond the project's default branch, the files they
+ * changed, whether the remote has the tip, whether the default branch already contains it, and
+ * the uncommitted paths of the checkout that is on the branch, when one is. The pull request is
+ * the caller's own question, asked of the git host, never here.
+ *
+ * A caller that knows the commit a branch was made at names it (`from`), and the commits and the
+ * files are measured so that they are the branch's own ({@link measuredFrom}): from that commit
+ * for a branch made from another branch, which holds, beyond the default branch, that branch's
+ * work as well as its own, and for a branch the default branch already contains, which holds
+ * nothing beyond it and still did its work. A full commit id asked in place of a branch is read as
+ * a branch whose tip it is: what a branch held, for a caller that kept its last commit after the
+ * branch went.
+ *
+ * Forgiving throughout: a branch that is gone answers `exists: false` with empty lists, a
+ * project without a remote answers `hasRemote: false`, and a git read that fails reads as empty.
+ */
+/** One commit a branch holds beyond the base. */
+export interface BranchCommit {
+    sha: string;
+    subject: string;
+}
+/** One file a branch changed against the base. */
+export interface BranchFile {
+    path: string;
+    insertions: number;
+    deletions: number;
+    /** A binary file, where line counts mean nothing. */
+    binary: boolean;
+}
+export interface BranchState {
+    branch: string;
+    /** The name the agent gave its work: the branch minus this package's prefix. Absent for a branch the package did not mint, and for a checkout still on the branch it was created on. */
+    name?: string;
+    /** The branch exists in the repository. Gone: every list below is empty. */
+    exists: boolean;
+    /** What it is measured against: the commit the caller named or the default branch (the remote's, else a local `main` or `master`), whichever tells the branch's own work. Absent when none was found. */
+    base?: string;
+    /** The branch's own commits beyond the base, newest first. */
+    commits: BranchCommit[];
+    /** What it changed since it left the base. */
+    files: BranchFile[];
+    /** The repository has a remote. */
+    hasRemote: boolean;
+    /** `origin` has the branch at this same tip. */
+    pushed: boolean;
+    /** The base already contains the branch. */
+    merged: boolean;
+    /** The uncommitted paths of the checkout under `.branches/` that is on this branch; absent when no checkout is. */
+    pendingFiles?: string[];
+}
+/**
+ * The state of each branch named, in that order. One read of the checkouts serves them all.
+ * `from` is the commit they were made at, when the caller knows it; one this machine does not
+ * have is no base, and the default branch is.
+ */
+export declare function readBranchStates(repo: string, branches: readonly string[], git?: GitRunner, from?: string): Promise<BranchState[]>;
+/** Parse `git log --format=%H%x1f%s`. */
+export declare function parseCommits(out: string): BranchCommit[];
+/** Parse `git diff --numstat`: `<added>\t<removed>\t<path>`, `-` for a binary file. */
+export declare function parseNumstat(out: string): BranchFile[];
+/** The paths of `git status --porcelain`: a rename reads as its new path, a quoted path unquoted. */
+export declare function parsePorcelain(out: string): string[];
+//# sourceMappingURL=branch-state.d.ts.map

package/dist/branch-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-state.d.ts","sourceRoot":"","sources":["../src/branch-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKnE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,wLAAwL;IACxL,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IACf,yMAAyM;IACzM,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,8CAA8C;IAC9C,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAA;IAClB,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAA;IACf,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAA;IACf,mHAAmH;IACnH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAKD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,GAAE,SAA2B,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAMzJ;AAqGD,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAQxD;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAUtD;AAED,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAWpD"}

package/dist/branch-state.js

@@ -0,0 +1,146 @@
+import { nodeGitRunner } from '@openagt/agent-data';
+import { basename } from 'node:path';
+import { agentIdFromWorktreeDir, sessionNameOf } from './branch-names.js';
+import { repoHasRemote, worktreeBranch, worktreeDirEntries } from './worktree.js';
+/** A subject can hold anything, so the fields are unit-separated rather than space-split. */
+const SEP = String.fromCharCode(31);
+/**
+ * The state of each branch named, in that order. One read of the checkouts serves them all.
+ * `from` is the commit they were made at, when the caller knows it; one this machine does not
+ * have is no base, and the default branch is.
+ */
+export async function readBranchStates(repo, branches, git = nodeGitRunner(), from) {
+    const ask = soft(git, repo);
+    const [hasRemote, base, checkouts, start] = await Promise.all([repoHasRemote(repo, git), detectBase(ask), checkoutsByBranch(repo, git), from !== undefined ? commitOf(ask, from) : undefined]);
+    const states = [];
+    for (const branch of branches)
+        states.push(await readOne(repo, branch, { git, ask, hasRemote, base, from: start, checkouts }));
+    return states;
+}
+/** A full commit id: what a caller asks in place of a branch that is gone. */
+const COMMIT_ID = /^[0-9a-f]{40}$/;
+/** The commit `rev` names, when this machine has it. */
+async function commitOf(ask, rev) {
+    return (await ask(['rev-parse', '--verify', '--quiet', `${rev}^{commit}`])).trim() || undefined;
+}
+async function readOne(repo, branch, reads) {
+    const { ask, hasRemote, base } = reads;
+    const tip = (await commitOf(ask, `refs/heads/${branch}`)) ?? (COMMIT_ID.test(branch) ? await commitOf(ask, branch) : undefined);
+    // Whether it is merged is always the default branch's answer; what its own commits and files
+    // are measured from is decided below, once the tip is known.
+    const checkout = reads.checkouts.get(branch);
+    const pending = checkout ? await pendingFiles(reads.git, checkout) : {};
+    const name = sessionNameOf(branch, checkout ? agentIdFromWorktreeDir(basename(checkout)) : undefined);
+    const named = name ? { name } : {};
+    if (!tip)
+        return { branch, ...named, exists: false, commits: [], files: [], hasRemote, pushed: false, merged: false, ...pending };
+    const from = await measuredFrom(ask, tip, reads.from, base);
+    // `base..branch` is the branch's own commits; `base...branch` is the change since it left the
+    // base, whatever the base did since. Each spelling answers its own question.
+    const [commitsOut, numstatOut, remoteTip, mergedOut] = await Promise.all([
+        from ? ask(['log', '--format=%H%x1f%s', `${from}..${tip}`]) : Promise.resolve(''),
+        from ? ask(['diff', '--numstat', `${from}...${tip}`]) : Promise.resolve(''),
+        hasRemote ? ask(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`]) : Promise.resolve(''),
+        base ? ask(['branch', '--list', '--merged', base, branch]) : Promise.resolve(''),
+    ]);
+    return {
+        branch,
+        ...named,
+        exists: true,
+        ...(from ? { base: from } : {}),
+        commits: parseCommits(commitsOut),
+        files: parseNumstat(numstatOut),
+        hasRemote,
+        pushed: remoteTip.trim() === tip,
+        merged: mergedOut.trim().length > 0,
+        ...pending,
+    };
+}
+/**
+ * What a branch's own commits and files are measured from. With no commit named, the default
+ * branch. With one, the default branch still, while the branch left it at or after that commit
+ * and is not in it yet: what the branch took in from the default branch since, by a merge or a
+ * rebase, is then not counted as its own. The named commit otherwise: for a branch the default
+ * branch already contains, where nothing would be left to count, and for a branch that left the
+ * default branch before that commit, which is one made from another branch.
+ */
+async function measuredFrom(ask, tip, from, base) {
+    if (!from || !base)
+        return from ?? base;
+    const forkBase = (await ask(['merge-base', base, tip])).trim();
+    if (!forkBase || forkBase === tip)
+        return from;
+    const forkFrom = (await ask(['merge-base', from, tip])).trim();
+    return forkFrom && (await ask(['merge-base', forkFrom, forkBase])).trim() === forkFrom ? base : from;
+}
+/** `git` that resolves to '' instead of rejecting, for reads where "no answer" is a fine answer. */
+function soft(git, cwd) {
+    return args => git(args, cwd).catch(() => '');
+}
+/** The project's default branch: what the remote points HEAD at, else the first local conventional one. */
+async function detectBase(ask) {
+    const head = (await ask(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])).trim();
+    if (head)
+        return head;
+    for (const name of ['main', 'master']) {
+        if ((await ask(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`])).trim())
+            return name;
+    }
+    return undefined;
+}
+/** Each checkout under `.branches/` that git knows, by the branch it is on. */
+async function checkoutsByBranch(repo, git) {
+    const map = new Map();
+    for (const entry of await worktreeDirEntries(repo)) {
+        const branch = await worktreeBranch(entry.path, git);
+        if (branch && !map.has(branch))
+            map.set(branch, entry.path);
+    }
+    return map;
+}
+/** The uncommitted paths of a checkout, as a spreadable field; absent when git could not answer. */
+async function pendingFiles(git, checkout) {
+    const status = await git(['status', '--porcelain'], checkout).catch(() => undefined);
+    return status === undefined ? {} : { pendingFiles: parsePorcelain(status) };
+}
+/** Parse `git log --format=%H%x1f%s`. */
+export function parseCommits(out) {
+    return out
+        .split('\n')
+        .filter(line => line.includes(SEP))
+        .map(line => {
+        const [sha = '', subject = ''] = line.split(SEP);
+        return { sha, subject };
+    });
+}
+/** Parse `git diff --numstat`: `<added>\t<removed>\t<path>`, `-` for a binary file. */
+export function parseNumstat(out) {
+    const files = [];
+    for (const line of out.split('\n')) {
+        const [added, removed, ...rest] = line.split('\t');
+        const path = rest.join('\t');
+        if (!path || added === undefined || removed === undefined)
+            continue;
+        const binary = added === '-' || removed === '-';
+        files.push({ path, insertions: binary ? 0 : Number(added) || 0, deletions: binary ? 0 : Number(removed) || 0, binary });
+    }
+    return files;
+}
+/** The paths of `git status --porcelain`: a rename reads as its new path, a quoted path unquoted. */
+export function parsePorcelain(out) {
+    const paths = [];
+    for (const line of out.split('\n')) {
+        if (line.length < 4)
+            continue;
+        let path = line.slice(3);
+        const arrow = path.indexOf(' -> ');
+        if (arrow !== -1)
+            path = path.slice(arrow + 4);
+        if (path.length >= 2 && path.startsWith('"') && path.endsWith('"'))
+            path = path.slice(1, -1);
+        if (path)
+            paths.push(path);
+    }
+    return paths;
+}
+//# sourceMappingURL=branch-state.js.map

package/dist/branch-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-state.js","sourceRoot":"","sources":["../src/branch-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AA4DjF,6FAA6F;AAC7F,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;AAEnC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAA2B,EAAE,GAAG,GAAc,aAAa,EAAE,EAAE,IAAa;IAC/H,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAC3B,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9L,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,KAAK,MAAM,MAAM,IAAI,QAAQ;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;IAC9H,OAAO,MAAM,CAAA;AACf,CAAC;AAaD,8EAA8E;AAC9E,MAAM,SAAS,GAAG,gBAAgB,CAAA;AAElC,wDAAwD;AACxD,KAAK,UAAU,QAAQ,CAAC,GAAwC,EAAE,GAAW;IAC3E,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAA;AACjG,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,MAAc,EAAE,KAAY;IAC/D,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IACtC,MAAM,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,cAAc,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC/H,6FAA6F;IAC7F,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACvE,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACrG,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAClC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAA;IACjI,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC3D,8FAA8F;IAC9F,6EAA6E;IAC7E,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACvE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjF,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3E,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,uBAAuB,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5G,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;KACjF,CAAC,CAAA;IACF,OAAO;QACL,MAAM;QACN,GAAG,KAAK;QACR,MAAM,EAAE,IAAI;QACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC;QACjC,KAAK,EAAE,YAAY,CAAC,UAAU,CAAC;QAC/B,SAAS;QACT,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG;QAChC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACnC,GAAG,OAAO;KACX,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,YAAY,CAAC,GAAwC,EAAE,GAAW,EAAE,IAAwB,EAAE,IAAwB;IACnI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,IAAI,IAAI,CAAA;IACvC,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC9D,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAC9C,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC9D,OAAO,QAAQ,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACtG,CAAC;AAED,oGAAoG;AACpG,SAAS,IAAI,CAAC,GAAc,EAAE,GAAW;IACvC,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;AAC/C,CAAC;AAED,2GAA2G;AAC3G,KAAK,UAAU,UAAU,CAAC,GAAwC;IAChE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,cAAc,EAAE,SAAS,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACxF,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IACrB,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAA;IACjG,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,+EAA+E;AAC/E,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,GAAc;IAC3D,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QACpD,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC7D,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,oGAAoG;AACpG,KAAK,UAAU,YAAY,CAAC,GAAc,EAAE,QAAgB;IAC1D,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACpF,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,CAAA;AAC7E,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG;SACP,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;SAClC,GAAG,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,CAAC,GAAG,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAChD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAA;IACzB,CAAC,CAAC,CAAA;AACN,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,KAAK,GAAiB,EAAE,CAAA;IAC9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;YAAE,SAAQ;QACnE,MAAM,MAAM,GAAG,KAAK,KAAK,GAAG,IAAI,OAAO,KAAK,GAAG,CAAA;QAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IACzH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,SAAQ;QAC7B,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;QAC9C,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5F,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/checkout.d.ts

@@ -0,0 +1,25 @@
+import { type GitRunner } from '@openagt/agent-data';
+import { type AddedWorktree } from './worktree.js';
+import { type SkillLink } from './skill-links.js';
+/**
+ * A checkout as an agent gets it (#1725): the worktree, `.branches/` hidden from git, the parent's
+ * dependency trees linked in, the skill linked in where the agent's harness looks for it (#1739),
+ * and the `.branches/` links brought up to date — one sequence, whichever surface asks for it (a
+ * scheduler starting a run, the command line).
+ */
+/** Other skills to link into the checkout beside this package's own: see `SkillLink`. */
+export interface CheckoutSkills {
+    skills?: readonly SkillLink[];
+}
+/** A new agent's checkout, on a fresh `agent-<id>` branch from `base` or origin's default branch. */
+export declare function createCheckout(repo: string, opts: {
+    agentId: string;
+    base?: string;
+} & CheckoutSkills, git?: GitRunner): Promise<AddedWorktree>;
+/** 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 declare function attachCheckout(repo: string, opts: {
+    agentId: string;
+    branch: string;
+    base?: string;
+} & CheckoutSkills, git?: GitRunner): Promise<AddedWorktree>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAgC,MAAM,qBAAqB,CAAA;AAEjG,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAG/E,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAG5D;;;;;GAKG;AAEH,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;CAC9B;AAED,qGAAqG;AACrG,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,EACzD,GAAG,GAAE,SAA2B,GAC/B,OAAO,CAAC,aAAa,CAAC,CAIxB;AAED,sJAAsJ;AACtJ,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,EACzE,GAAG,GAAE,SAA2B,GAC/B,OAAO,CAAC,aAAa,CAAC,CAIxB"}