@agentproto/worktree 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -731,6 +731,25 @@ interface ForgeClient {
      * (PLAN.md §1.3 step 2, verified for #273/#312/#325/#271).
      */
     ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
+    /**
+     * Every OPEN PR/MR in the repo, in one round-trip — the bulk twin of
+     * `pullRequestsForBranch` for callers that must protect hundreds of refs at
+     * once (`branch-gc.ts`: one call per ref would be a forge request per
+     * branch). Optional so existing test doubles keep compiling; a client that
+     * doesn't implement it is treated as "open-PR detection unavailable" by
+     * those callers, never as "no open PRs".
+     */
+    listOpenPullRequests?(): Promise<ForgePullRequestRef[]>;
+    /**
+     * Every MERGED PR/MR in the repo, in one round-trip — the bulk twin of
+     * `listOpenPullRequests` for the merged-head shortcut (`branch-gc.ts`): a
+     * branch whose tip is EXACTLY a merged PR's head commit lost nothing (that
+     * commit was reviewed and merged), so it is reclaimable without an LLM
+     * review. Optional so existing test doubles keep compiling; a client that
+     * doesn't implement it is treated as "merged-PR detection unavailable" by
+     * those callers, never as "no merged PRs".
+     */
+    listMergedPullRequests?(): Promise<ForgePullRequestRef[]>;
 }
 /** A client that always reports itself unreachable — the "no gh, no token" case. */
 declare class UnreachableForgeClient implements ForgeClient {
@@ -739,6 +758,8 @@ declare class UnreachableForgeClient implements ForgeClient {
     pullRequestsForBranch(): Promise<ForgePullRequestRef[]>;
     pullRequestsForCommit(): Promise<ForgePullRequestRef[]>;
     ensurePullHeadFetched(): Promise<void>;
+    listOpenPullRequests(): Promise<ForgePullRequestRef[]>;
+    listMergedPullRequests(): Promise<ForgePullRequestRef[]>;
 }
 /** Runs `gh` in `repoRoot` so it auto-detects owner/repo from the `origin` remote there. */
 declare class GhCliForgeClient implements ForgeClient {
@@ -749,9 +770,17 @@ declare class GhCliForgeClient implements ForgeClient {
     private parseOutput;
     pullRequestsForBranch(branch: string): Promise<ForgePullRequestRef[]>;
     pullRequestsForCommit(sha: string): Promise<ForgePullRequestRef[]>;
+    listOpenPullRequests(): Promise<ForgePullRequestRef[]>;
+    listMergedPullRequests(): Promise<ForgePullRequestRef[]>;
     ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
 }
-/** Parse `owner/repo` out of a `git remote get-url origin` value (ssh or https form). */
+/**
+ * Parse `owner/repo` out of a `git remote get-url origin` value (ssh or https
+ * form). The ssh form also accepts the multi-account `~/.ssh/config` alias
+ * convention, `git@github.com-<alias>:owner/repo` (a `Host github.com-work`
+ * entry that picks a key but still points at github.com), which is what a
+ * machine juggling two GitHub identities has as its origin.
+ */
 declare function parseGithubOwnerRepo(remoteUrl: string): {
     owner: string;
     repo: string;
@@ -768,6 +797,8 @@ declare class RestForgeClient implements ForgeClient {
     private pullRequestList;
     pullRequestsForBranch(branch: string): Promise<ForgePullRequestRef[]>;
     pullRequestsForCommit(sha: string): Promise<ForgePullRequestRef[]>;
+    listOpenPullRequests(): Promise<ForgePullRequestRef[]>;
+    listMergedPullRequests(): Promise<ForgePullRequestRef[]>;
     ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
 }
 /**
@@ -799,6 +830,13 @@ declare function createForgeClient(repoRoot: string): Promise<ForgeClient>;
 
 type TreeState = {
     state: "clean";
+    /**
+     * Set only when the tree is clean BECAUSE every dirty path was on the
+     * caller's noise allowlist (`ComputeTreeStateOptions.noisePaths`) — the
+     * paths a removal must restore/delete first, since git's own
+     * non-`--force` `worktree remove` still sees them as dirt.
+     */
+    noise?: string[];
 } | {
     state: "dirty";
     modified: number;
@@ -812,6 +850,15 @@ type TreeState = {
      */
     newestMtimeMs: number | null;
 };
+interface ComputeTreeStateOptions {
+    /**
+     * Worktree-relative paths whose dirt is known noise (e.g. a tool's lockfile
+     * churn that shows up in every agent worktree). A tree whose ONLY dirt is
+     * on this list reads `clean` (with `noise` set). Default none — callers
+     * opt in; see `DEFAULT_GC_NOISE_PATHS` in `gc.ts` for gc's default.
+     */
+    noisePaths?: readonly string[];
+}
 /**
  * `git status --porcelain=v2` in the worktree itself, via `-C worktreePath`
  * (tree state is per-worktree, not `repoRoot`'s). The spawn's own `cwd`,
@@ -826,7 +873,7 @@ type TreeState = {
  * `worktree remove` tolerance for them (PLAN.md §0.5) — the two notions of
  * "clean" agree by construction.
  */
-declare function computeTreeState(repoRoot: string, worktreePath: string): Promise<TreeState>;
+declare function computeTreeState(repoRoot: string, worktreePath: string, options?: ComputeTreeStateOptions): Promise<TreeState>;
 declare const integrationStateSchema: z.ZodUnion<readonly [z.ZodObject<{
     state: z.ZodLiteral<"fresh">;
     checkedAt: z.ZodString;
@@ -1056,10 +1103,29 @@ interface Classification {
  * `hold`.
  */
 declare function classify(tree: TreeState, integration: IntegrationState, liveness: LivenessState, nowMs?: number): Classification;
+/** How far a worktree's tip has moved from the base it is compared against. */
+interface BaseDivergence {
+    /** The ref the tip is compared against (`defaultBranchRef`, e.g. `origin/main`). */
+    ref: string;
+    /** Commits on the tip that the base doesn't have. */
+    ahead: number;
+    /** Commits on the base that the tip doesn't have. */
+    behind: number;
+}
+/**
+ * `git rev-list --left-right --count <base>...<head>`: one read, both sides
+ * of the symmetric difference. `null` for a detached/unborn tip, or when git
+ * can't resolve either side (base ref never fetched, object gone) — a
+ * best-effort display fact, never a reason to fail a status sweep. Spawn
+ * `cwd` is `repoRoot`, like every other read here (see `computeTreeState`).
+ */
+declare function computeBaseDivergence(repoRoot: string, head: string, baseRef: string): Promise<BaseDivergence | null>;
 interface WorktreeStatusEntry {
     path: string;
     branch: string | null;
     head: string;
+    /** Ahead/behind vs `defaultBranchRef` — see `computeBaseDivergence`. */
+    base: BaseDivergence | null;
     tree: TreeState;
     integration: IntegrationState;
     liveness: LivenessState;
@@ -1086,6 +1152,8 @@ interface ComputeWorktreeStatusInput {
      * and therefore always-"recent", delta). Defaults to `Date.now()`.
      */
     nowMs?: number;
+    /** See `ComputeTreeStateOptions.noisePaths`. Default none. */
+    noisePaths?: readonly string[];
 }
 /** Computes all three axes + provenance + classification for one worktree. */
 declare function computeWorktreeStatus(input: ComputeWorktreeStatusInput): Promise<WorktreeStatusEntry>;
@@ -1097,6 +1165,12 @@ interface ListWorktreeStatusesInput {
     defaultBranchRef?: string;
     sessionsPath?: string;
     now?: () => string;
+    /**
+     * Compute only the worktrees at these paths (compared resolved) — a
+     * single-worktree read (the per-session `worktree_status` lookup) costs one
+     * forge round-trip instead of one per worktree in the repo. Omitted = all.
+     */
+    paths?: readonly string[];
 }
 /** Enumerates every linked worktree of `repoRoot` (`git worktree list`) and computes its status. */
 declare function listWorktreeStatuses(input: ListWorktreeStatusesInput): Promise<WorktreeStatusEntry[]>;
@@ -1231,7 +1305,17 @@ declare function classifyForGc(tree: TreeState, integration: IntegrationState, l
  *     only irreversible thing history nearly did to it (deleting the branch)
  *     must not happen either. See "prunable reclaim" below.
  */
-type GcReclaimReason = "dep-bump" | "orphan" | "prunable";
+type GcReclaimReason = "dep-bump" | "orphan" | "prunable" | InBaseReclaimReason;
+/**
+ * `branch gc`'s proof tiers (`classifyTip`, branch-gc.ts) that promote a
+ * clean, idle worktree out of `hold` when the forge can't: its branch's
+ * CONTENT is provably in base even though no merged PR contains its tip (a
+ * squash that went through another PR, a cherry-pick, a later reorg). See
+ * "in-base promotion" below.
+ */
+type InBaseReclaimReason = "squash-merged" | "patch-merged" | "content-merged";
+/** gc's default noise allowlist — overridable per call via `noisePaths` (`[]` disables it). */
+declare const DEFAULT_GC_NOISE_PATHS: readonly string[];
 /** The hold reasons this module can attach, distinct from `classify`'s snapshot-based holds. */
 type GcHoldReason = "live-session-cwd";
 /**
@@ -1250,6 +1334,11 @@ type GcHoldReason = "live-session-cwd";
 declare function isMechanicalDepBumpRange(repoRoot: string, baseRef: string, tipSha: string): Promise<boolean>;
 interface ResolveGcClassOptions extends ClassifyForGcOptions {
     repoRoot: string;
+    /**
+     * Run `branch gc`'s content ladder for a clean, idle worktree still in
+     * `hold` (see "in-base promotion"). Default true.
+     */
+    inBaseCheck?: boolean;
     /** The tip commit of the worktree being classified — `worktree.head`. */
     tipSha: string;
     /** Default `"origin/main"` — matches `reconcileIntegration`'s own default. */
@@ -1336,6 +1425,8 @@ interface PlanGcInput {
      * protection beyond `classify`'s own snapshot-based liveness axis.
      */
     protectedPaths?: string[];
+    /** Noise allowlist (see "noise allowlist" above). Default `DEFAULT_GC_NOISE_PATHS`; `[]` disables it. */
+    noisePaths?: readonly string[];
 }
 /**
  * The dry-run plan (PLAN.md §5.2 layer 1): classify every linked worktree,
@@ -1360,6 +1451,8 @@ interface ApplyGcOptions {
     salvageRoot?: string;
     /** See `PlanGcInput.protectedPaths` — re-checked here at apply time (layer 2), independent of what the plan entry says, so a stale plan can never remove a now-protected path. */
     protectedPaths?: string[];
+    /** See `PlanGcInput.noisePaths`. */
+    noisePaths?: readonly string[];
 }
 type GcApplyOutcome = {
     path: string;
@@ -1429,4 +1522,471 @@ declare function reclaimOneWorktree(worktreePath: string, options: ApplyGcOption
     includeDetached?: boolean;
 }): Promise<GcApplyOutcome | null>;
 
-export { type AgentprotoConfig, type ApplyGcOptions, CONFIG_FILENAME, type Classification, type ClassifyForGcOptions, type ComputeProvenanceOptions, type ComputeWorktreeStatusInput, ConfigError, DEFAULT_PROXY_PORT, type DaemonAgentSessionHost, type DaemonClient, ENV_VARS, type ExecOptions, type ExecResult, FileVerdictMemoStore, type ForgeClient, type ForgePullRequestRef, ForgeUnavailableError, type GateState, type GcApplyOutcome, type GcClass, type GcHoldReason, type GcPlanEntry, type GcReclaimReason, GhCliForgeClient, type GitWorktreeRef, HookError, type HookRun, type HostnameParts, InMemoryVerdictMemoStore, type IntegrationState, type ListWorktreeStatusesInput, type LivenessState, type NamedScript, type PeerService, type PlanGcInput, type ProvenanceConfidence, type ProvenanceInfo, ProxyTable, type ReconcileIntegrationInput, type ResolveGcClassOptions, type ResolveSupervisorInput, type ResolvedGcClass, type ResolvedWorktreeRuntime, RestForgeClient, type RunningProxy, SALVAGE_ROOT, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, type SalvageManifest, type SalvageResult, type SalvageWorktreeInput, type ScriptConfig, type ServiceRuntime, type ServiceStatus, ServiceSupervisor, type SessionRef, type SupervisorOptions, type TreeState, UnreachableForgeClient, VERDICT_MEMO_PATH, type VerdictMemoRecord, type VerdictMemoStore, WORKTREES_TURBO_CACHE_DIR_ENV, type WorktreeAgentInput, type WorktreeClass, type WorktreeEnvContext, type WorktreeMarker, WorktreeNotRemovableError, type WorktreeStatusEntry, allocatePort, applyGc, classify, classifyForGc, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, connectDaemonAgentSessionHost, createForgeClient, createProxyServer, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isMechanicalDepBumpRange, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, makeDaemonAgentSessionHost, normalizeHook, parseConfig, parseGithubOwnerRepo, peerEnv, peerEnvKey, planGc, readSessionsRegistry, readWorktreeMarker, reclaimOneWorktree, reconcileIntegration, repoLabel, resolveGcClass, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, salvageWorktree, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, startProxy, stripPort, worktreeAgentInputSchema, worktreeAgentWorkflow, writeWorktreeMarker };
+/**
+ * `branch gc`: the sibling of worktree `gc` (`gc.ts`) for refs instead of
+ * worktrees — local branches (`refs/heads`), the base remote's tracking
+ * branches (`refs/remotes/<remote>`), and ORPHAN tracking refs
+ * (`refs/remotes/<ns>/*` whose `<ns>` is no longer a configured remote, which
+ * nothing — not even `fetch --prune` — ever cleans up). Same contract as
+ * worktree `gc`:
+ *
+ *   1. `planBranchGc` is pure read: every ref is classified `reclaim` /
+ *      `review` / `hold` and nothing is mutated. A dry run IS "call this,
+ *      print it, stop."
+ *   2. `applyBranchGc` re-lists the refs and re-classifies every entry from
+ *      scratch immediately before touching it; a tip that moved, vanished or
+ *      now classifies differently is refused, never acted on.
+ *   3. `hold` is never touched and `review` is never touched — only
+ *      `reclaim`. A reviewed-unmerged ref only becomes `reclaim` via
+ *      `includeReviewed` + a stored gate verdict that agreed for the SAME tip
+ *      sha; this module stores and reads verdicts, it never decides them.
+ *   4. Every deletion is written to a restore log (sha + exact re-create
+ *      command) BEFORE the delete runs, so every apply is undoable.
+ *
+ * `reclaim` means "the work is provably in base", by a ladder of increasingly
+ * expensive checks (`classifyTip`), ported from the audited
+ * `branch-hygiene.mjs` maintenance script that first cleaned a 460-ref repo:
+ *
+ *   pr-merged       the tip IS the head commit (`headRefOid`) of a MERGED PR
+ *                   — that exact commit was reviewed and merged, so nothing
+ *                   was lost (forge shortcut in `classifyRef`: the ladder
+ *                   still runs, but an "unmerged" verdict is overridden
+ *                   before any reclaim/hold decision, skipping the
+ *                   push-state/verdict lookups below it)
+ *   merged          tip is an ancestor of base
+ *   squash-merged   `git merge-tree --write-tree base tip` == base's tree
+ *                   (merging it changes nothing)
+ *   patch-merged    `git cherry` reports every commit as already applied —
+ *                   ONLY tried when merge-tree conflicts (cherry patch-ids
+ *                   every base commit since the merge-base: seconds per
+ *                   branch on a busy base, and a clean merge with a
+ *                   non-empty residual is unmerged regardless)
+ *   content-merged  every path the branch changed is, BY BLOB, somewhere in
+ *                   base's tree (any path — survives moves/reorgs) or
+ *                   gitignored there, with zero `evolved` (same basename in
+ *                   base, other content), zero `unique`, zero `deletes`
+ *
+ * Anything else is `unmerged` and — once older than `minAgeDays` and not
+ * protected — becomes `review`, carrying everything a reviewer needs (coverage
+ * summary, the files NOT provably in base, push state).
+ */
+
+declare const BRANCH_GC_SCOPES: readonly ["local", "remote", "orphan"];
+/** `local` = refs/heads, `remote` = the base remote's tracking refs, `orphan` = refs/remotes/<ns>/* of a remote that no longer exists. */
+type BranchRefKind = (typeof BRANCH_GC_SCOPES)[number];
+/** The verdict for one tip, in order of increasing cost (`pr-merged` is the forge shortcut that overrides an "unmerged" ladder verdict, not a check that skips the ladder). */
+type BranchStatus = "pr-merged" | "merged" | "squash-merged" | "patch-merged" | "content-merged" | "unmerged";
+/**
+ * `current`: the tip shares history with base. `pre-rewrite`: it doesn't, but
+ * base was re-rooted and an anchor (the old-history twin of base's root)
+ * answers for it. `unrelated`: no shared history and no anchor — unmerged by
+ * definition, since nothing can prove it landed.
+ */
+type BranchHistory = "current" | "pre-rewrite" | "unrelated";
+type BranchGcClass = "reclaim" | "review" | "hold";
+/** Why a `reclaim` entry is reclaimable: one of the ladder's proven tiers, or a stored gate verdict (`includeReviewed`). */
+type BranchGcReclaimReason = Exclude<BranchStatus, "unmerged"> | "reviewed";
+/**
+ * Why an entry is `hold`:
+ *   - `protected`: base or a well-known protected name (main, master, …)
+ *   - `worktree`: checked out in a worktree — the local branch AND its remote
+ *     twin (a live worktree may still push to it)
+ *   - `open-pr`: the head of an open PR
+ *   - `pr-check-unavailable`: open-PR detection could not run, so every
+ *     local/remote ref is held rather than silently losing that protection
+ *   - `young`: unmerged and younger than `minAgeDays`
+ */
+type BranchGcHoldReason = "protected" | "worktree" | "open-pr" | "pr-check-unavailable" | "young";
+/**
+ * Where else an unmerged tip lives — matters because deleting the only copy
+ * lets `git gc` destroy the commits. Local refs: `same-tip-on-remote` /
+ * `contained-in-remote` / `diverged-from-remote` / `local-only`. Orphan refs:
+ * `contained-elsewhere` / `only-copy`.
+ */
+type BranchPushState = "same-tip-on-remote" | "contained-in-remote" | "diverged-from-remote" | "local-only" | "contained-elsewhere" | "only-copy";
+/**
+ * Content coverage of everything the branch changed (merge-base..tip), file
+ * by file, against base's CONTENT rather than its history:
+ *   covered   the exact blob exists somewhere in base (moved or copied)
+ *   ignored   gitignored in the repo (generated output)
+ *   evolved   a same-named file exists in base with other content
+ *   unique    no trace in base
+ *   deletes   the branch deletes a path base still has (an unlanded intent)
+ * evolved + unique + deletes == 0 → nothing but history is lost by deleting.
+ */
+interface BranchCoverage {
+    residual: number;
+    covered: number;
+    ignored: number;
+    evolved: number;
+    unique: number;
+    deletes: number;
+}
+interface TipClassification {
+    status: BranchStatus;
+    history: BranchHistory;
+    /** Commits on the tip not in the compare base; `null` for an unrelated tip. */
+    ahead: number | null;
+    /** Commits in the compare base not on the tip; `null` when not computed. */
+    behind: number | null;
+    /** Set once merge-tree ran: `true` when merging into base conflicts. */
+    conflicts?: boolean;
+    /** Base, or the anchor for a pre-rewrite tip — what ancestry/cherry ran against. Set for `unmerged`. */
+    compareBase?: string;
+    mergeBase?: string;
+    /** Tree of base-with-the-branch-merged, `null` when the merge conflicts. Set for `unmerged`. */
+    mergedTree?: string | null;
+    coverage?: BranchCoverage;
+    /** The files a reviewer must look at: unique, then evolved, then deletes. Capped at 200. */
+    residualFiles?: string[];
+    residualFileCount?: number;
+}
+interface BranchRef {
+    kind: BranchRefKind;
+    /** Short name: `feat/x` for local/remote, `<ns>/feat/x` for an orphan. */
+    name: string;
+    /** Full ref, e.g. `refs/remotes/origin/feat/x`. */
+    ref: string;
+    sha: string;
+    /** Committer date of the tip, ISO-8601. */
+    date: string;
+    author: string;
+    subject: string;
+    /** The remote a `remote`-kind ref belongs to. */
+    remote?: string;
+}
+/** Summary of a stored verdict for this exact tip, when one exists. */
+interface BranchVerdictSummary {
+    triage: BranchTriageVerdict;
+    agree: boolean | null;
+    reviewer: string;
+}
+interface BranchGcPlanEntry extends BranchRef, TipClassification {
+    ageDays: number;
+    class: BranchGcClass;
+    reclaimReason?: BranchGcReclaimReason;
+    holdReason?: BranchGcHoldReason;
+    /** Human detail for a hold: the worktree path, `PR #n`, or why the PR check failed. */
+    holdDetail?: string;
+    /** Set when the status is `pr-merged`: the number of the merged PR whose head commit IS this tip. */
+    mergedPr?: number;
+    /** Set for unmerged local and orphan refs. */
+    pushed?: BranchPushState;
+    verdict?: BranchVerdictSummary;
+}
+interface BranchGcPlan {
+    repoRoot: string;
+    repoName: string;
+    base: string;
+    baseSha: string;
+    baseTree: string;
+    /** The remote whose tracking refs are `remote`-kind — the base's own remote. `null` when base isn't a remote ref and there is no `origin`. */
+    remote: string | null;
+    /** Old-history twin of base's root for a re-rooted base, else `null`. */
+    anchor: string | null;
+    prCheck: {
+        available: boolean;
+        reason?: string;
+    };
+    scopes: BranchRefKind[];
+    minAgeDays: number;
+    includeReviewed: boolean;
+    generatedAt: string;
+    /** Refs of OTHER configured remotes: never classified, never touched. */
+    otherRemoteRefs: number;
+    entries: BranchGcPlanEntry[];
+}
+/** Base content index, built once per base: path→blob, every blob, every basename. */
+interface TreeIndex {
+    byPath: Map<string, string>;
+    blobs: Set<string>;
+    names: Set<string>;
+}
+interface LadderContext {
+    repoRoot: string;
+    baseSha: string;
+    baseTree: string;
+    anchor: string | null;
+    /** Built lazily: only content coverage needs it. */
+    index: () => Promise<TreeIndex>;
+    /** Tip sha → "shares history with `baseSha`", when already known (the
+     *  plan's anchor detection asks the same question of every tip) — saves
+     *  the ladder's first `merge-base` per tip. */
+    related?: ReadonlyMap<string, boolean>;
+}
+declare function createLadderContext(repoRoot: string, baseRef: string, anchor: string | null, related?: ReadonlyMap<string, boolean>): Promise<LadderContext>;
+/**
+ * Run the ladder for one tip against `ctx`'s base. Pure read. A tip with no
+ * history in common with base is checked against the anchor when there is one
+ * (ancestry/cherry against the anchor; merge-tree with
+ * `--merge-base=merge-base(anchor, tip)`), else it is `unmerged`/`unrelated`.
+ */
+declare function classifyTip(ctx: LadderContext, tip: string): Promise<TipClassification>;
+/**
+ * One-shot ladder for a caller that has a single tip and no plan (worktree
+ * `gc`'s content-merged promotion). No anchor: a pre-rewrite tip reads
+ * `unrelated`/`unmerged` here, which only ever errs toward keeping.
+ */
+declare function classifyTipAgainstBase(repoRoot: string, baseRef: string, tip: string): Promise<TipClassification>;
+/**
+ * A re-rooted base (history rewritten into a fresh snapshot commit) shares no
+ * ancestor with branches cut before the rewrite. The ANCHOR is the
+ * old-history commit whose tree the snapshot was taken from: searched in the
+ * unrelated tips' history within 3 days before the root's date, closest tree
+ * to the root wins, accepted only when fewer than 200 files apart.
+ */
+declare function detectAnchor(repoRoot: string, baseSha: string, tips: readonly string[], 
+/** Filled with every tip's answer (`true` = shares history with base) for
+ *  the ladder to reuse — see {@link LadderContext.related}. */
+related?: Map<string, boolean>): Promise<string | null>;
+declare const DEFAULT_BRANCH_GC_MIN_AGE_DAYS = 3;
+interface PlanBranchGcInput {
+    repoRoot: string;
+    repoName: string;
+    /** Default `origin/main`. */
+    base?: string;
+    /** Subset of kinds to classify. Default all three. */
+    scopes?: readonly BranchRefKind[];
+    /** Unmerged refs younger than this are `hold`. Default 3. */
+    minAgeDays?: number;
+    /** Promote a `review` ref whose stored verdict agreed for the same tip sha to `reclaim` (`reviewed`). Default false. */
+    includeReviewed?: boolean;
+    /** Explicit anchor for a re-rooted base. Omitted → auto-detected. */
+    anchor?: string;
+    /** Open-PR detection (`listOpenPullRequests`). Omitted or unable → every local/remote ref is `hold` (`pr-check-unavailable`). */
+    forge?: ForgeClient;
+    verdicts?: BranchVerdictStore;
+    /** Clock for `ageDays`. Default `Date.now()`. */
+    nowMs?: number;
+    /** Parallel ladder runs. Default 8. */
+    concurrency?: number;
+}
+/** The dry-run plan: classify every ref in `scopes`, mutate nothing. */
+declare function planBranchGc(input: PlanBranchGcInput): Promise<BranchGcPlan>;
+interface BranchGcSummary {
+    /** kind → class → count. */
+    byClass: Record<BranchRefKind, Record<BranchGcClass, number>>;
+    /**
+     * kind → (status | "protected") → count, where "protected" = held for
+     * base/protected, worktree, or open PR. Same buckets as the reference
+     * script's audit summary, so the two can be compared line for line.
+     */
+    byStatus: Record<BranchRefKind, Record<string, number>>;
+}
+declare function summarizeBranchGcPlan(plan: BranchGcPlan): BranchGcSummary;
+interface BranchReviewCandidate {
+    name: string;
+    kind: BranchRefKind;
+    sha: string;
+    ageDays: number;
+    author: string;
+    subject: string;
+    history: BranchHistory;
+    /** Base sha. */
+    base: string;
+    compareBase?: string;
+    mergeBase?: string;
+    mergedTree?: string | null;
+    conflicts?: boolean;
+    ahead: number | null;
+    behind: number | null;
+    pushed?: BranchPushState;
+    coverage?: BranchCoverage;
+    residualFiles?: string[];
+    residualFileCount?: number;
+    /** Every ref sharing this tip (a local branch and its remote twin share one review). */
+    refs: string[];
+    verdict?: BranchVerdictSummary;
+}
+interface BranchReviewQueue {
+    base: string;
+    baseSha: string;
+    anchor: string | null;
+    candidates: BranchReviewCandidate[];
+}
+/**
+ * The `review` entries of a plan, one per unique tip sha, with everything a
+ * reviewer needs. Tips that already carry a stored verdict are skipped unless
+ * `all` — verdicts are keyed by sha, so only tips that moved get re-reviewed.
+ */
+declare function branchReviewQueue(plan: BranchGcPlan, options?: {
+    all?: boolean;
+}): BranchReviewQueue;
+type BranchGcApplyOutcome = {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "deleted";
+    reclaimReason: BranchGcReclaimReason;
+} | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "held";
+    holdReason?: BranchGcHoldReason;
+}
+/** `review` class: never touched by apply — the review/approval path decides these. */
+ | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "skipped-review";
+}
+/** The ref now points somewhere else than the plan saw — never delete what wasn't classified. */
+ | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "aborted-moved";
+    currentSha: string;
+}
+/** The ref no longer exists. */
+ | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "aborted-vanished";
+}
+/** Re-classified from scratch and no longer `reclaim`. */
+ | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "aborted-reclassified";
+    from: BranchGcClass;
+    to: BranchGcClass;
+    holdReason?: BranchGcHoldReason;
+} | {
+    kind: BranchRefKind;
+    name: string;
+    sha: string;
+    result: "failed";
+    message: string;
+};
+interface ApplyBranchGcOptions {
+    /** REQUIRED and non-empty: which kinds apply may delete. Entries of other kinds are left out of the outcomes. */
+    scopes: readonly BranchRefKind[];
+    forge?: ForgeClient;
+    verdicts?: BranchVerdictStore;
+    /** Where restore logs go. Default `~/.agentproto/branch-gc`. */
+    stateDir?: string;
+    nowMs?: number;
+    /** Remote refs per `git push --delete`. Default 50. */
+    remoteBatchSize?: number;
+}
+interface BranchGcApplyResult {
+    outcomes: BranchGcApplyOutcome[];
+    /** Restore log for this run, `null` when nothing was deleted. */
+    restoreLog: string | null;
+}
+declare const BRANCH_GC_STATE_DIR: () => string;
+interface BranchGcRestoreEntry {
+    kind: BranchRefKind;
+    name: string;
+    ref: string;
+    sha: string;
+    remote?: string;
+    /** git arguments (no leading `git`) that re-create the ref, run with `-C repoRoot`. */
+    argv: string[];
+    /** The same, as a copy-pasteable shell command. */
+    command: string;
+    /** Set once the delete ran. */
+    deleted?: boolean;
+}
+interface BranchGcRestoreLog {
+    schema: "branch-gc-restore/v1";
+    repoRoot: string;
+    base: string;
+    baseSha: string;
+    createdAt: string;
+    entries: BranchGcRestoreEntry[];
+}
+/**
+ * Execute a plan. Only `reclaim` entries whose kind is in `options.scopes`
+ * are touched, and each is first re-derived from scratch: the ref is
+ * re-listed (moved → `aborted-moved`, gone → `aborted-vanished`) and fully
+ * re-classified against fresh worktree / open-PR / verdict state (anything but
+ * `reclaim` → `aborted-reclassified`). The restore log is written before the
+ * first delete runs.
+ */
+declare function applyBranchGc(plan: BranchGcPlan, options: ApplyBranchGcOptions): Promise<BranchGcApplyResult>;
+/** Read a restore log written by `applyBranchGc`. */
+declare function readBranchGcRestoreLog(path: string): Promise<BranchGcRestoreLog>;
+declare const BRANCH_TRIAGE_VERDICTS: readonly ["obsolete", "superseded", "salvage", "in-progress", "unclear"];
+type BranchTriageVerdict = (typeof BRANCH_TRIAGE_VERDICTS)[number];
+/**
+ * One reviewer verdict for one branch tip. `gate` is the second opinion that
+ * actually licenses deletion (`agree: true`); a triage-only verdict (no
+ * `gate`) records the review but never makes a ref reclaimable. An agreeing
+ * gate must cite evidence.
+ */
+declare const branchVerdictSchema: z.ZodObject<{
+    name: z.ZodString;
+    sha: z.ZodString;
+    triage: z.ZodObject<{
+        verdict: z.ZodEnum<{
+            salvage: "salvage";
+            obsolete: "obsolete";
+            superseded: "superseded";
+            "in-progress": "in-progress";
+            unclear: "unclear";
+        }>;
+        confidence: z.ZodNumber;
+        reason: z.ZodString;
+        salvage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    gate: z.ZodOptional<z.ZodObject<{
+        agree: z.ZodBoolean;
+        verdict: z.ZodEnum<{
+            salvage: "salvage";
+            obsolete: "obsolete";
+            superseded: "superseded";
+            "in-progress": "in-progress";
+            unclear: "unclear";
+        }>;
+        reason: z.ZodString;
+        evidence: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    reviewer: z.ZodString;
+}, z.core.$strip>;
+type BranchVerdict = z.infer<typeof branchVerdictSchema>;
+interface BranchVerdictRecord extends BranchVerdict {
+    repo: string;
+    recordedAt: string;
+}
+interface BranchVerdictStore {
+    /** The verdict for this exact tip, or `null`. A ref whose tip moved simply finds nothing. */
+    get(repo: string, sha: string): Promise<BranchVerdictRecord | null>;
+    set(record: BranchVerdictRecord): Promise<void>;
+}
+declare const BRANCH_VERDICTS_PATH: () => string;
+/** `~/.agentproto/branch-gc-verdicts.json`, keyed by (repo, tip sha). */
+declare class FileBranchVerdictStore implements BranchVerdictStore {
+    private readonly path;
+    private cache;
+    constructor(path?: string);
+    private load;
+    get(repo: string, sha: string): Promise<BranchVerdictRecord | null>;
+    set(record: BranchVerdictRecord): Promise<void>;
+}
+declare class InMemoryBranchVerdictStore implements BranchVerdictStore {
+    private readonly map;
+    get(repo: string, sha: string): Promise<BranchVerdictRecord | null>;
+    set(record: BranchVerdictRecord): Promise<void>;
+}
+declare class BranchVerdictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate and store one verdict. Rejects a malformed verdict, an agreeing
+ * gate with no evidence, and a sha that isn't a commit in this repo.
+ */
+declare function recordBranchVerdict(input: {
+    repoRoot: string;
+    repoName: string;
+    verdict: unknown;
+    store: BranchVerdictStore;
+    now?: () => string;
+}): Promise<BranchVerdictRecord>;
+
+export { type AgentprotoConfig, type ApplyBranchGcOptions, type ApplyGcOptions, BRANCH_GC_SCOPES, BRANCH_GC_STATE_DIR, BRANCH_TRIAGE_VERDICTS, BRANCH_VERDICTS_PATH, type BaseDivergence, type BranchCoverage, type BranchGcApplyOutcome, type BranchGcApplyResult, type BranchGcClass, type BranchGcHoldReason, type BranchGcPlan, type BranchGcPlanEntry, type BranchGcReclaimReason, type BranchGcRestoreEntry, type BranchGcRestoreLog, type BranchGcSummary, type BranchHistory, type BranchPushState, type BranchRef, type BranchRefKind, type BranchReviewCandidate, type BranchReviewQueue, type BranchStatus, type BranchTriageVerdict, type BranchVerdict, BranchVerdictError, type BranchVerdictRecord, type BranchVerdictStore, type BranchVerdictSummary, CONFIG_FILENAME, type Classification, type ClassifyForGcOptions, type ComputeProvenanceOptions, type ComputeTreeStateOptions, type ComputeWorktreeStatusInput, ConfigError, DEFAULT_BRANCH_GC_MIN_AGE_DAYS, DEFAULT_GC_NOISE_PATHS, DEFAULT_PROXY_PORT, type DaemonAgentSessionHost, type DaemonClient, ENV_VARS, type ExecOptions, type ExecResult, FileBranchVerdictStore, FileVerdictMemoStore, type ForgeClient, type ForgePullRequestRef, ForgeUnavailableError, type GateState, type GcApplyOutcome, type GcClass, type GcHoldReason, type GcPlanEntry, type GcReclaimReason, GhCliForgeClient, type GitWorktreeRef, HookError, type HookRun, type HostnameParts, type InBaseReclaimReason, InMemoryBranchVerdictStore, InMemoryVerdictMemoStore, type IntegrationState, type LadderContext, type ListWorktreeStatusesInput, type LivenessState, type NamedScript, type PeerService, type PlanBranchGcInput, type PlanGcInput, type ProvenanceConfidence, type ProvenanceInfo, ProxyTable, type ReconcileIntegrationInput, type ResolveGcClassOptions, type ResolveSupervisorInput, type ResolvedGcClass, type ResolvedWorktreeRuntime, RestForgeClient, type RunningProxy, SALVAGE_ROOT, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, type SalvageManifest, type SalvageResult, type SalvageWorktreeInput, type ScriptConfig, type ServiceRuntime, type ServiceStatus, ServiceSupervisor, type SessionRef, type SupervisorOptions, type TipClassification, type TreeIndex, type TreeState, UnreachableForgeClient, VERDICT_MEMO_PATH, type VerdictMemoRecord, type VerdictMemoStore, WORKTREES_TURBO_CACHE_DIR_ENV, type WorktreeAgentInput, type WorktreeClass, type WorktreeEnvContext, type WorktreeMarker, WorktreeNotRemovableError, type WorktreeStatusEntry, allocatePort, applyBranchGc, applyGc, branchReviewQueue, branchVerdictSchema, classify, classifyForGc, classifyTip, classifyTipAgainstBase, computeBaseDivergence, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, connectDaemonAgentSessionHost, createForgeClient, createLadderContext, createProxyServer, detectAnchor, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isMechanicalDepBumpRange, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, makeDaemonAgentSessionHost, normalizeHook, parseConfig, parseGithubOwnerRepo, peerEnv, peerEnvKey, planBranchGc, planGc, readBranchGcRestoreLog, readSessionsRegistry, readWorktreeMarker, reclaimOneWorktree, reconcileIntegration, recordBranchVerdict, repoLabel, resolveGcClass, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, salvageWorktree, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, startProxy, stripPort, summarizeBranchGcPlan, worktreeAgentInputSchema, worktreeAgentWorkflow, writeWorktreeMarker };