@openagt/skill-branches 0.0.1

package/dist/merge.js.map

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

package/dist/publish.d.ts

@@ -0,0 +1,138 @@
+import { type GitRunner } from '@gemstack/agent-data';
+/**
+ * Publishing a checkout (#1774): the agent's own last step. Push the branch, open its pull
+ * request with the title and body the agent wrote, and arm the merge when the agent was told
+ * the work may land on its own. One rule before any of it: the tree is clean, since what is
+ * published is what is committed, and nothing is committed on the agent's behalf.
+ *
+ * A branch that already has an open pull request gets no second one: the request is reported as
+ * it is, and only the push and the merge arming happen.
+ *
+ * The merge is GitHub's auto-merge where the repository allows it. Where it does not, this tool's
+ * own watcher waits for the checks and merges (`merge-watch.ts`); where the request is already
+ * green, GitHub will not arm anything and the request is merged at once.
+ *
+ * A checkout under a hold (`merge-hold.ts`) arms nothing: the merge is recorded as wanted, the
+ * request's body says it is held, and the caller who put the hold releases it (`releaseMerge`).
+ *
+ * A person publishes a finished agent's work through the same door (#1774), by branch
+ * (`publishBranch`): the agent's checkout when one is still on the branch, under the same clean
+ * rule; else the branch itself, pushed when this machine has it, as it is when only the remote
+ * does. And lands its request (`mergePr`): a draft is marked ready first, then the merge is
+ * armed exactly as `--merge` arms it.
+ */
+/** A `gh` runner: the standard output of one invocation; rejects with gh's own line on failure. */
+export type GhRunner = (args: string[], cwd: string) => Promise<string>;
+/** `gh` on PATH, one minute per call: these talk to the network. */
+export declare function nodeGhRunner(): GhRunner;
+export interface PublishOptions {
+    /** The pull request's title: one line naming what the change does. */
+    title: string;
+    /** The pull request's body: what changed and why. */
+    body?: string;
+    /** Arm the merge: the request lands on its own once its checks pass. */
+    merge?: boolean;
+    /** Start the merge watcher for a request (default {@link spawnMergeWatch}). For tests. */
+    watch?: (repo: string, number: number) => Promise<void>;
+    /** Open the request as a draft. Not with `merge`: a draft cannot be merged. */
+    draft?: boolean;
+    git?: GitRunner;
+    gh?: GhRunner;
+}
+/** Why a checkout was not published. */
+export type PublishRefusal = 
+/** The directory is not a git worktree root. */
+'not-a-worktree'
+/** The checkout is on no branch. */
+ | 'no-branch'
+/** The tree holds uncommitted work: commit or delete it first. */
+ | 'dirty'
+/** The branch could not be pushed. */
+ | 'push-failed'
+/** The pull request could not be opened. */
+ | 'pr-failed';
+export type PublishOutcome = {
+    ok: true;
+    branch: string;
+    pr: {
+        number: number;
+        url: string;
+    };
+    /** Whether the request was open already. */
+    existing: boolean;
+    /**
+     * How the merge arming went, when asked for: GitHub's auto-merge armed, merged at once (the
+     * request was already green), this tool's watcher started (the repository does not allow
+     * auto-merge), or held (the checkout is under a hold; armed at its release).
+     */
+    merge?: MergeArming | {
+        outcome: 'held';
+    };
+} | {
+    ok: false;
+    reason: 'not-a-worktree';
+}
+/** The checkout is on no branch; or, published by name, neither this machine nor the remote has the branch. */
+ | {
+    ok: false;
+    reason: 'no-branch';
+    branch?: string;
+} | {
+    ok: false;
+    reason: 'dirty' | 'push-failed' | 'pr-failed';
+    branch: string;
+    detail?: string;
+};
+/** How arming a merge went. */
+export type MergeArming = {
+    outcome: 'auto-armed' | 'merged' | 'watching';
+} | {
+    outcome: 'failed';
+    error: string;
+};
+export declare function publishCheckout(path: string, opts: PublishOptions): Promise<PublishOutcome>;
+/**
+ * Publish a branch by name, from the project (#1774): the caller's form, for a person landing a
+ * finished agent's work. The checkout under `.branches/` that is on the branch, when one is,
+ * is published as the agent would publish it, its clean rule included. Without one, the branch
+ * itself: pushed when this machine has it; left as it is when only `origin` has it (a branch
+ * pushed from elsewhere, with nothing here to push). Neither: `no-branch`. No hold applies
+ * without a checkout: a hold is a checkout's.
+ */
+export declare function publishBranch(repo: string, branch: string, opts: PublishOptions): Promise<PublishOutcome>;
+/** What landing a request for a person did: armed as `--merge` arms, or why not. */
+export type MergePrOutcome = MergeArming | {
+    outcome: 'not-open';
+    state: string;
+};
+export interface MergePrOptions {
+    gh?: GhRunner;
+    /** Start the merge watcher for a request (default {@link spawnMergeWatch}). For tests. */
+    watch?: (repo: string, number: number) => Promise<void>;
+}
+/**
+ * Land a pull request for a person (#1774): "it is good, land it". A draft is marked ready
+ * first, since asking for the merge is the statement that its review happened; then the merge
+ * is armed exactly as `publish --merge` arms it. A request that is not open is `not-open` with
+ * its state: already merged is an answer, not an action.
+ */
+export declare function mergePr(repo: string, number: number, opts?: MergePrOptions): Promise<MergePrOutcome>;
+export type ReleaseOutcome = MergeArming | {
+    outcome: 'not-held';
+} | {
+    outcome: 'closed';
+    state: string;
+};
+export interface ReleaseOptions {
+    gh?: GhRunner;
+    /** Start the merge watcher for a request (default {@link spawnMergeWatch}). For tests. */
+    watch?: (repo: string, number: number) => Promise<void>;
+}
+/**
+ * Release a held merge: the request's merge is armed the way `publish --merge` arms it, and then
+ * the held note leaves its body. A request with no held merge is `not-held` (its publish never asked
+ * to merge), one no longer open is `closed` and its record dropped. A failed arming keeps the
+ * record and the note, so the release can be tried again and the request still says it is held.
+ */
+export declare function releaseMerge(repo: string, number: number, opts?: ReleaseOptions): Promise<ReleaseOutcome>;
+//# sourceMappingURL=publish.d.ts.map

package/dist/publish.d.ts.map

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

package/dist/publish.js

@@ -0,0 +1,215 @@
+import { nodeGitRunner, pushBranch } from '@gemstack/agent-data';
+import { currentBranch, isWorktreeRoot, projectRoot, worktreeBranch, worktreeClean, worktreeDirEntries } from './worktree.js';
+import { spawnMergeWatch } from './merge-watch.js';
+import { dropHeldMerge, heldMergeRecorded, MERGE_HELD_NOTE, mergeHeld, recordHeldMerge, withHeldNote, withoutHeldNote } from './merge-hold.js';
+/** `gh` on PATH, one minute per call: these talk to the network. */
+export function nodeGhRunner() {
+    return async (args, cwd) => {
+        const { execFile } = await import('node:child_process');
+        return new Promise((resolve, reject) => {
+            execFile('gh', args, { cwd, timeout: 60_000 }, (err, stdout, stderr) => {
+                if (err)
+                    reject(new Error(String(stderr).trim() || err.message));
+                else
+                    resolve(String(stdout));
+            });
+        });
+    };
+}
+export async function publishCheckout(path, opts) {
+    const git = opts.git ?? nodeGitRunner();
+    const gh = opts.gh ?? nodeGhRunner();
+    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' };
+    if (!(await worktreeClean(path, git).catch(() => false)))
+        return { ok: false, reason: 'dirty', branch };
+    const repo = await projectRoot(path, git);
+    const held = opts.merge === true && (await mergeHeld(path, git));
+    const pushed = await pushBranch(repo, branch, git);
+    if (!pushed.ok)
+        return { ok: false, reason: 'push-failed', branch, detail: pushed.error };
+    return openAndArm(repo, path, branch, opts, held, gh);
+}
+/**
+ * Publish a branch by name, from the project (#1774): the caller's form, for a person landing a
+ * finished agent's work. The checkout under `.branches/` that is on the branch, when one is,
+ * is published as the agent would publish it, its clean rule included. Without one, the branch
+ * itself: pushed when this machine has it; left as it is when only `origin` has it (a branch
+ * pushed from elsewhere, with nothing here to push). Neither: `no-branch`. No hold applies
+ * without a checkout: a hold is a checkout's.
+ */
+export async function publishBranch(repo, branch, opts) {
+    const git = opts.git ?? nodeGitRunner();
+    const gh = opts.gh ?? nodeGhRunner();
+    for (const entry of await worktreeDirEntries(repo)) {
+        if ((await worktreeBranch(entry.path, git)) === branch)
+            return publishCheckout(entry.path, opts);
+    }
+    const local = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repo).then(out => out.trim() !== '', () => false);
+    if (local) {
+        const pushed = await pushBranch(repo, branch, git);
+        if (!pushed.ok)
+            return { ok: false, reason: 'push-failed', branch, detail: pushed.error };
+    }
+    else {
+        const remote = await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], repo).then(out => out.trim() !== '', () => false);
+        if (!remote)
+            return { ok: false, reason: 'no-branch', branch };
+    }
+    return openAndArm(repo, repo, branch, opts, false, gh);
+}
+/** The half after the push: the open request or a new one, then the merge arming, the hold honored. */
+async function openAndArm(repo, cwd, branch, opts, held, gh) {
+    let pr = await openPr(cwd, branch, gh);
+    let existing = true;
+    if (!pr) {
+        existing = false;
+        try {
+            const args = ['pr', 'create', '--head', branch, '--title', opts.title, '--body', held ? withHeldNote(opts.body ?? '') : (opts.body ?? '')];
+            if (opts.draft && !opts.merge)
+                args.push('--draft');
+            const out = await gh(args, cwd);
+            const url = out.trim().split('\n').filter(Boolean).at(-1);
+            const number = prNumber(url);
+            pr = url && number !== undefined ? { number, url } : await openPr(cwd, branch, gh);
+            if (!pr)
+                return { ok: false, reason: 'pr-failed', branch, detail: 'gh printed no pull request URL' };
+        }
+        catch (err) {
+            return { ok: false, reason: 'pr-failed', branch, detail: errorMessage(err) };
+        }
+    }
+    const outcome = { ok: true, branch, pr, existing };
+    if (held) {
+        await recordHeldMerge(repo, pr.number);
+        if (existing)
+            await noteHeld(cwd, pr.number, gh);
+        outcome.merge = { outcome: 'held' };
+    }
+    else if (opts.merge) {
+        outcome.merge = await armMerge(repo, pr.number, gh, opts.watch ?? spawnMergeWatch);
+    }
+    return outcome;
+}
+/**
+ * Land a pull request for a person (#1774): "it is good, land it". A draft is marked ready
+ * first, since asking for the merge is the statement that its review happened; then the merge
+ * is armed exactly as `publish --merge` arms it. A request that is not open is `not-open` with
+ * its state: already merged is an answer, not an action.
+ */
+export async function mergePr(repo, number, opts = {}) {
+    const gh = opts.gh ?? nodeGhRunner();
+    let view;
+    try {
+        view = JSON.parse(await gh(['pr', 'view', String(number), '--json', 'state,isDraft'], repo));
+    }
+    catch (err) {
+        return { outcome: 'failed', error: errorMessage(err) };
+    }
+    const state = typeof view.state === 'string' ? view.state : 'OPEN';
+    if (state !== 'OPEN')
+        return { outcome: 'not-open', state };
+    if (view.isDraft === true) {
+        try {
+            await gh(['pr', 'ready', String(number)], repo);
+        }
+        catch (err) {
+            return { outcome: 'failed', error: errorMessage(err) };
+        }
+    }
+    return armMerge(repo, number, gh, opts.watch ?? spawnMergeWatch);
+}
+/** An open request's body gains the held note, once. The note is for a person: an edit gh refuses never fails the publish. */
+async function noteHeld(cwd, number, gh) {
+    try {
+        const body = String(JSON.parse(await gh(['pr', 'view', String(number), '--json', 'body'], cwd)).body ?? '');
+        if (!body.includes(MERGE_HELD_NOTE))
+            await gh(['pr', 'edit', String(number), '--body', withHeldNote(body)], cwd);
+    }
+    catch {
+        // The record is written; only the line for a person is missing.
+    }
+}
+/**
+ * Release a held merge: the request's merge is armed the way `publish --merge` arms it, and then
+ * the held note leaves its body. A request with no held merge is `not-held` (its publish never asked
+ * to merge), one no longer open is `closed` and its record dropped. A failed arming keeps the
+ * record and the note, so the release can be tried again and the request still says it is held.
+ */
+export async function releaseMerge(repo, number, opts = {}) {
+    const gh = opts.gh ?? nodeGhRunner();
+    if (!(await heldMergeRecorded(repo, number)))
+        return { outcome: 'not-held' };
+    let view;
+    try {
+        view = JSON.parse(await gh(['pr', 'view', String(number), '--json', 'state,body'], repo));
+    }
+    catch (err) {
+        return { outcome: 'failed', error: errorMessage(err) };
+    }
+    const state = typeof view.state === 'string' ? view.state : 'OPEN';
+    if (state !== 'OPEN') {
+        await dropHeldMerge(repo, number);
+        return { outcome: 'closed', state };
+    }
+    const merge = await armMerge(repo, number, gh, opts.watch ?? spawnMergeWatch);
+    if (merge.outcome === 'failed')
+        return merge;
+    await dropHeldMerge(repo, number);
+    const body = typeof view.body === 'string' ? view.body : '';
+    if (body.includes(MERGE_HELD_NOTE))
+        await gh(['pr', 'edit', String(number), '--body', withoutHeldNote(body)], repo).catch(() => { });
+    return merge;
+}
+/**
+ * GitHub's words for "auto-merge is not allowed in this repository" and for "this request is
+ * already green, so there is nothing to wait for". Matched loosely on purpose: a rephrase on
+ * GitHub's side lands in `failed`, said out loud, never in a wrong merge.
+ */
+const AUTO_MERGE_OFF = /auto[- ]?merge is not allowed/i;
+const ALREADY_GREEN = /clean status/i;
+async function armMerge(repo, number, gh, watch) {
+    try {
+        await gh(['pr', 'merge', String(number), '--squash', '--auto'], repo);
+        return { outcome: 'auto-armed' };
+    }
+    catch (err) {
+        const refusal = errorMessage(err);
+        try {
+            if (ALREADY_GREEN.test(refusal)) {
+                await gh(['pr', 'merge', String(number), '--squash'], repo);
+                return { outcome: 'merged' };
+            }
+            if (AUTO_MERGE_OFF.test(refusal)) {
+                await watch(repo, number);
+                return { outcome: 'watching' };
+            }
+        }
+        catch (next) {
+            return { outcome: 'failed', error: errorMessage(next) };
+        }
+        return { outcome: 'failed', error: refusal };
+    }
+}
+/** The open pull request of a branch, or `undefined`. */
+async function openPr(cwd, branch, gh) {
+    try {
+        const list = JSON.parse(await gh(['pr', 'list', '--head', branch, '--state', 'open', '--limit', '1', '--json', 'number,url'], cwd));
+        const first = list[0];
+        return first && typeof first.number === 'number' && typeof first.url === 'string' ? { number: first.number, url: first.url } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function prNumber(url) {
+    const match = url?.match(/\/pull\/(\d+)(?:$|[/?#])/);
+    return match ? Number(match[1]) : undefined;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=publish.js.map

package/dist/publish.js.map

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

package/dist/push.d.ts

@@ -0,0 +1,53 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * Pushing a branch to origin (#1820): the last git step of an agent's work, and the step before
+ * whatever the project's git host package does with the branch. This package knows git and nothing
+ * beyond it: the pull request, if the project has a git host, is another package's command.
+ *
+ * One rule before the push: the tree is clean, since what is pushed is what is committed, and
+ * nothing is committed on the agent's behalf.
+ *
+ * A person pushes a finished agent's branch through the same door, by name (`pushBranchByName`):
+ * the agent's checkout when one is still on the branch, under the same clean rule; else the
+ * branch itself, pushed when this machine has it, left as it is when only origin does.
+ */
+/** Why a branch was not pushed. */
+export type PushRefusal = 
+/** The directory is not a git worktree root. */
+'not-a-worktree'
+/** The checkout is on no branch; or, by name, neither this machine nor origin has the branch. */
+ | 'no-branch'
+/** The tree holds uncommitted work: commit or delete it first. */
+ | 'dirty'
+/** The branch could not be pushed. */
+ | 'push-failed';
+export type PushOutcome = 
+/** `pushed` is false when only origin had the branch: nothing here to push, and nothing missing there. */
+{
+    ok: true;
+    branch: string;
+    pushed: boolean;
+} | {
+    ok: false;
+    reason: 'not-a-worktree';
+} | {
+    ok: false;
+    reason: 'no-branch';
+    branch?: string;
+} | {
+    ok: false;
+    reason: 'dirty' | 'push-failed';
+    branch: string;
+    detail?: string;
+};
+/** Push the branch the checkout at `path` is on, once the checkout is clean. */
+export declare function pushCheckout(path: string, git?: GitRunner): Promise<PushOutcome>;
+/**
+ * Push a branch by name, from the project: the caller's form, for a person landing a finished
+ * agent's work. The checkout under `.branches/` that is on the branch, when one is, is pushed as
+ * the agent would push it, its clean rule included. Without one, the branch itself: pushed when
+ * this machine has it; left as it is when only `origin` has it (a branch pushed from elsewhere,
+ * with nothing here to push). Neither: `no-branch`.
+ */
+export declare function pushBranchByName(repo: string, branch: string, git?: GitRunner): Promise<PushOutcome>;
+//# sourceMappingURL=push.d.ts.map

package/dist/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../src/push.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAG/E;;;;;;;;;;;GAWG;AAEH,mCAAmC;AACnC,MAAM,MAAM,WAAW;AACrB,gDAAgD;AAC9C,gBAAgB;AAClB,iGAAiG;GAC/F,WAAW;AACb,kEAAkE;GAChE,OAAO;AACT,sCAAsC;GACpC,aAAa,CAAA;AAEjB,MAAM,MAAM,WAAW;AACrB,0GAA0G;AACxG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnF,gFAAgF;AAChF,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,SAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CAQvG;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,SAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CAa3H"}

package/dist/push.js

@@ -0,0 +1,41 @@
+import { nodeGitRunner, pushBranch } from '@openagt/agent-data';
+import { currentBranch, isWorktreeRoot, projectRoot, worktreeBranch, worktreeClean, worktreeDirEntries } from './worktree.js';
+/** Push the branch the checkout at `path` is on, once the checkout is clean. */
+export async function pushCheckout(path, git = nodeGitRunner()) {
+    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' };
+    if (!(await worktreeClean(path, git).catch(() => false)))
+        return { ok: false, reason: 'dirty', branch };
+    const pushed = await pushBranch(await projectRoot(path, git), branch, git);
+    if (!pushed.ok)
+        return { ok: false, reason: 'push-failed', branch, detail: pushed.error };
+    return { ok: true, branch, pushed: true };
+}
+/**
+ * Push a branch by name, from the project: the caller's form, for a person landing a finished
+ * agent's work. The checkout under `.branches/` that is on the branch, when one is, is pushed as
+ * the agent would push it, its clean rule included. Without one, the branch itself: pushed when
+ * this machine has it; left as it is when only `origin` has it (a branch pushed from elsewhere,
+ * with nothing here to push). Neither: `no-branch`.
+ */
+export async function pushBranchByName(repo, branch, git = nodeGitRunner()) {
+    for (const entry of await worktreeDirEntries(repo)) {
+        if ((await worktreeBranch(entry.path, git)) === branch)
+            return pushCheckout(entry.path, git);
+    }
+    const local = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repo).then(out => out.trim() !== '', () => false);
+    if (local) {
+        const pushed = await pushBranch(repo, branch, git);
+        if (!pushed.ok)
+            return { ok: false, reason: 'push-failed', branch, detail: pushed.error };
+        return { ok: true, branch, pushed: true };
+    }
+    const remote = await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], repo).then(out => out.trim() !== '', () => false);
+    if (!remote)
+        return { ok: false, reason: 'no-branch', branch };
+    return { ok: true, branch, pushed: false };
+}
+//# sourceMappingURL=push.js.map

package/dist/push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../src/push.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAiC7H,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,GAAG,GAAc,aAAa,EAAE;IAC/E,IAAI,CAAC,CAAC,MAAM,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;IACtF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;IACtD,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;IACvG,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;IAC1E,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;IACzF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAc,EAAE,GAAG,GAAc,aAAa,EAAE;IACnG,KAAK,MAAM,KAAK,IAAI,MAAM,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,MAAM;YAAE,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC9F,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IACvI,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;QAClD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;QACzF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;IAC3C,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,uBAAuB,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IACjJ,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAA;IAC9D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC5C,CAAC"}

package/dist/reclaim.d.ts

@@ -0,0 +1,74 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * Reclaiming a checkout (#752/#737): the one implementation behind every surface that removes
+ * one — a scheduler at a run's end and in its sweep, a dashboard's Remove button, the CLI.
+ *
+ * **One rule: only what is committed may go.** The checkout is removed only once its branch holds
+ * everything in it: a clean tree. The branch stays on this machine, so nothing the agent made
+ * goes with the checkout. Nothing is committed on the agent's behalf (#1638): a checkout holding
+ * uncommitted work is kept, until a person commits or deletes it. And nothing is pushed:
+ * publishing a branch is a person's call, never a cleanup's.
+ *
+ * What the caller knows and git does not comes in as options: the branch the checkout was created
+ * on, and the commit its branch was made at.
+ */
+export interface ReclaimOptions {
+    /**
+     * The branch the checkout was created on, when that may differ from the branch it ended on: an
+     * agent that branched away leaves it behind, and it goes with the checkout once the branch the
+     * checkout ended on contains it (#1657).
+     */
+    birthBranch?: string;
+    /**
+     * The commit the checkout's branch was made at, when the caller knows it. A branch with no
+     * commit past it holds nothing of its own.
+     */
+    from?: string;
+    /** Run once removal is decided, just before the checkout goes: stop what serves the tree. */
+    beforeRemove?: () => Promise<void>;
+    git?: GitRunner;
+}
+/** Why {@link reclaimWorktree} left a checkout where it was. */
+export type ReclaimRefusal = 
+/** The directory is not a git worktree root: nothing was run in it (#1654). */
+'not-a-worktree'
+/** The checkout is on no branch (detached). */
+ | 'no-branch'
+/** The tree holds uncommitted work. */
+ | 'dirty';
+export type ReclaimOutcome = {
+    ok: true;
+    /**
+     * Branches that went with the checkout: the branch it was on, when that held nothing of
+     * its own (#1650); the birth branch, when everything on it is in the branch that stays
+     * (#1657). Absent when nothing went.
+     */
+    branchesDeleted?: string[];
+} | {
+    ok: false;
+    reason: 'not-a-worktree' | 'no-branch';
+} | {
+    ok: false;
+    reason: 'dirty';
+    /** The branch the checkout is on. */
+    branch: string;
+};
+/**
+ * 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 declare function reclaimWorktree(repo: string, path: string, opts: ReclaimOptions): Promise<ReclaimOutcome>;
+/**
+ * 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 declare function discardWorktree(repo: string, path: string, opts?: Pick<ReclaimOptions, 'git' | 'beforeRemove'>): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-a-worktree';
+}>;
+//# sourceMappingURL=reclaim.d.ts.map

package/dist/reclaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.d.ts","sourceRoot":"","sources":["../src/reclaim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAWxF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc;AACxB,+EAA+E;AAC7E,gBAAgB;AAClB,+CAA+C;GAC7C,WAAW;AACb,uCAAuC;GACrC,OAAO,CAAA;AAEX,MAAM,MAAM,cAAc,GACtB;IACE,EAAE,EAAE,IAAI,CAAA;IACR;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAA;CAAE,GACrD;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,OAAO,CAAA;IACf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAEL;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAiC/G;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,cAAc,CAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAO1L"}