cyber-agentkit 0.0.0-stage → 1.0.0

package/dist/worktrees.d.ts

@@ -0,0 +1,690 @@
+import { t as HarnessId } from "./harness-id-BgKL-x6C.js";
+//#region src/worktrees/exec.d.ts
+/**
+ * Runs a command and resolves its trimmed stdout, or `null` on any failure. Every git and forge call
+ * in this folder goes through it, so a caller can drive the whole worktree layer with a fake or with
+ * its own environment (a pinned `GIT_CONFIG_GLOBAL`, a different `PATH`).
+ */
+type Exec = (cmd: string, args: readonly string[]) => Promise<string | null>;
+/** The default `Exec`: `execFile` with stderr captured, never inherited, because routine failures
+ * (no `origin/HEAD`, a branch with no upstream) would otherwise spam the caller's terminal. */
+export declare const nodeExec: Exec;
+//#endregion
+//#region src/worktrees/landed.d.ts
+/**
+ * Which signal established that a branch's work has landed on the default branch, in the cost order
+ * the signals run. Each is positive-only: a signal that cannot match never contributes a `false`, so
+ * two signals can never contradict each other.
+ *
+ * - `ancestor`: the branch tip is an ancestor of the default branch (`git branch --merged`).
+ * - `upstream-gone`: the branch's remote-tracking ref has disappeared (`[gone]`), meaning the forge
+ *   merged the pull request and deleted its head branch. Only as fresh as the caller's last
+ *   `git fetch --prune`; this module never fetches.
+ * - `squash-patch`: the branch, collapsed to one commit, is already applied on the default branch
+ *   (`git cherry`). Matches a clean squash or rebase merge, not a hand-edited one.
+ * - `forge`: the forge reports a merged pull request for the branch. Needs network and auth, so it
+ *   runs only when the caller passes a `ForgeMergedProbe`.
+ */
+type LandedSignal = 'ancestor' | 'upstream-gone' | 'squash-patch' | 'forge';
+/** Asks the forge whether `branch` is the head of a merged pull request. `undefined` means the forge
+ * could not say, which, like `false`, clears nothing. */
+type ForgeMergedProbe = (branch: string) => Promise<boolean | undefined>;
+/**
+ * A `ForgeMergedProbe` backed by the GitHub CLI: `gh pr list --head <branch> --state merged`. Every
+ * way it can fail (no `gh`, no auth, no network, a non-GitHub origin) resolves `undefined`.
+ */
+export declare function ghForgeMergedProbe(exec: Exec, primaryRoot: string): ForgeMergedProbe;
+//#endregion
+//#region src/worktrees/lease.d.ts
+/** A held worktree: what `acquire` hands out and `release` takes back. */
+interface Lease {
+  /** The worktree root, as `WorktreeEntry.root` gives it. */
+  worktree: string;
+  leaseId: string;
+  holder: string;
+  /**
+   * The repo's git common dir, recorded at claim so `release` can still clear the lock after the
+   * worktree's directory is gone. Absent on a hand-built lease; then the checkout must exist.
+   */
+  commonDir?: string | undefined;
+}
+/**
+ * The file operations the lease store performs on git's `locked` file, injected so a caller can
+ * sandbox them or a test can stage the race with `git worktree lock` (E-GIT-L5). Paths are absolute.
+ */
+interface LeaseFs {
+  /** Create the file only if nothing is there; `false` when something already is. */
+  createExclusive(path: string, text: string): Promise<boolean>;
+  /** The file's text, or `undefined` when it does not exist. */
+  readText(path: string): Promise<string | undefined>;
+  /** Delete the file; a no-op when it is already gone. */
+  remove(path: string): Promise<void>;
+}
+/** The default `LeaseFs`, on `node:fs/promises`. */
+export declare const nodeLeaseFs: LeaseFs;
+interface LeaseStoreOptions {
+  exec?: Exec | undefined;
+  /** Defaults to `nodeLeaseFs`. */
+  fs?: LeaseFs | undefined;
+}
+/**
+ * `$GIT_COMMON_DIR/worktrees/<id>/locked` for a linked worktree, or `undefined` when git cannot say.
+ * The `<id>` is git's admin folder name, which need not match the basename, so it is read from
+ * `--git-dir` rather than built. When the checkout is gone, `commonDir` finds the admin folder by the
+ * `gitdir` pointer it keeps, so a lease on a vanished worktree can still be cleared.
+ */
+export declare function leaseFile(worktreeRoot: string, exec?: Exec, commonDir?: string | undefined): Promise<string | undefined>;
+/**
+ * Claim a worktree: exclusive-create its `locked` file with the lease as a one-line JSON reason, which
+ * git then honours as a lock (E-GIT-L1, E-GIT-L2, E-GIT-L3), and read it back. `git worktree lock`
+ * checks then truncates, so it can overwrite a lease created inside its window (E-GIT-L5); the read
+ * back catches that. `undefined` when the worktree is already locked or the claim was lost.
+ */
+export declare function claimLease(worktreeRoot: string, holder: string, options?: LeaseStoreOptions & {
+  leaseId?: string | undefined;
+}): Promise<Lease | undefined>;
+/** Whether the worktree's `locked` file still records this lease. Checked again before a destructive
+ * step, since a manual `git worktree unlock` or a racing `lock` can take it away (E-GIT-L4, E-GIT-L5). */
+export declare function holdsLease(lease: Lease, options?: LeaseStoreOptions): Promise<boolean>;
+type ReleaseResult = {
+  released: true;
+} |
+/** The `locked` file no longer records this lease: someone unlocked it, broke it with
+ * `remove -f -f` (E-GIT-L4), or locked over it. Reported, not thrown: that is the user's override. */
+{
+  released: false;
+  reason: 'lost';
+};
+/**
+ * Give a lease back by deleting the `locked` file, only when it still records this `leaseId`. It does
+ * not recycle: an occupant such as a judge may still be working there, so the next `acquire` recycles
+ * after probing.
+ */
+export declare function release(lease: Lease, options?: LeaseStoreOptions): Promise<ReleaseResult>;
+//#endregion
+//#region src/worktrees/list-worktrees.d.ts
+/** A worktree as git reports it, plus the landed and dirty facts the reuse and cleanup checks read. */
+interface WorktreeEntry {
+  /** Absolute checkout path, symlinks resolved. */
+  root: string;
+  /** The checked-out commit; absent for a bare entry. */
+  head?: string | undefined;
+  /** The checked-out branch, without `refs/heads/`; absent when detached or bare. */
+  branch?: string | undefined;
+  /** HEAD is detached. */
+  detached: boolean;
+  /** `false` for the primary checkout, `true` for a linked worktree. */
+  linked: boolean;
+  /** git considers the entry stale: its checkout is gone from disk. */
+  prunable: boolean;
+  /**
+   * The lock reason when the worktree is locked (`''` for a lock with no reason), absent when it is
+   * not. A lock may be a lease, a harness's own hold, or a user's.
+   */
+  locked?: string | undefined;
+  /**
+   * The branch's work has landed on the default branch. Absent when undeterminable (no branch, or no
+   * default branch to compare against), never `false` as a stand-in.
+   */
+  merged?: boolean | undefined;
+  /** Which signal established `merged: true`. */
+  mergedSignal?: LandedSignal | undefined;
+  /**
+   * The checkout has uncommitted changes, tracked or untracked. Absent for a prunable entry or when
+   * git could not answer.
+   */
+  dirty?: boolean | undefined;
+}
+interface PrimaryRootOptions {
+  /** Any directory inside the repository, the primary checkout or a linked worktree. Defaults to `.`. */
+  from?: string | undefined;
+  exec?: Exec | undefined;
+}
+/**
+ * The primary checkout's root, from the primary checkout or any linked worktree:
+ * `--git-common-dir` always points at the primary's `.git`.
+ */
+export declare function primaryRoot(options?: PrimaryRootOptions): Promise<string>;
+/**
+ * The single normalization for every path matched against another, so a symlinked repo or macOS's
+ * `/tmp` → `/private/tmp` still matches. Falls back to `resolve` for a path not on disk.
+ */
+export declare function normalizeWorktreePath(path: string): Promise<string>;
+interface ListWorktreesOptions {
+  /** The primary checkout's root; see `primaryRoot`. */
+  primaryRoot: string;
+  exec?: Exec | undefined;
+  /** Paths whose changes do not make a worktree dirty; see `DirtyOptions.ignore`. */
+  ignore?: readonly string[] | undefined;
+  /** The opt-in forge signal; the offline signals run either way. */
+  forge?: ForgeMergedProbe | undefined;
+}
+/** Every worktree of the repo, from `git worktree list --porcelain`, with landed and dirty facts. */
+export declare function listWorktrees(options: ListWorktreesOptions): Promise<WorktreeEntry[]>;
+//#endregion
+//#region src/worktrees/process-source.d.ts
+/**
+ * One process as the probe sees it. Every field but `pid` may be missing: a process can exit
+ * mid-read, and another user's process hides its `exe`, `cwd`, and `environ`.
+ */
+interface ProcessInfo {
+  pid: number;
+  /** Parent pid; absent when unreadable. */
+  ppid?: number | undefined;
+  /** Resolved executable path, with any ` (deleted)` suffix removed. */
+  exe?: string | undefined;
+  /** The command line; empty for a kernel thread or an unreadable process. */
+  argv: readonly string[];
+  /** Resolved working directory, with any ` (deleted)` suffix removed. */
+  cwd?: string | undefined;
+  /** The process's environment; absent when unreadable. */
+  env?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Lists every process the caller can see, or `null` when this platform has no supported way to read
+ * another process's executable and working directory. Inject one to run the probe on fixtures, or on
+ * a platform the default does not cover.
+ */
+type ProcessSource = () => Promise<readonly ProcessInfo[] | null>;
+/**
+ * Reads processes from a Linux `/proc` (or a mounted copy at `procRoot`). On any other platform the
+ * default root returns `null`: macOS would need `proc_pidinfo` (E-PROC-OS2), and Windows has no
+ * documented way to read another process's cwd (E-PROC-OS3).
+ */
+export declare function procfsProcessSource(procRoot?: string): ProcessSource;
+//#endregion
+//#region src/worktrees/session-signatures.d.ts
+/** A harness the process probe recognises: the detected harnesses plus two seen only as processes. */
+type SessionHarnessId = HarnessId | 'goose' | 'antigravity-cli';
+//#endregion
+//#region src/worktrees/occupancy.d.ts
+/** A live agent session working inside a worktree. A wrapper and its native or relaunched child are
+ * one session (E-PROC-KILO1, E-PROC-GEM1). */
+interface Session {
+  harness: SessionHarnessId;
+  /** The session's top process: the wrapper when there is one. */
+  pid: number;
+  /** Every process of the session, the wrapper and its child; any one inside the worktree counts. */
+  pids: readonly number[];
+  /** The session id, when one of its tool processes carries it in the harness's link variable. */
+  sessionId?: string | undefined;
+  /** Evidence IDs the match rests on. */
+  research: readonly string[];
+}
+/**
+ * Why a process left in a worktree was reported:
+ * - `session-gone`: its link variable names no live session (E-PROC-CC2, E-PROC-CX2).
+ * - `helper-orphaned`: a per-session helper, such as Cursor's worker, outlived its session
+ *   (E-PROC-CUR3).
+ * - `harness-idle`: a helper shared by every session of a harness, such as Cline's hub, with no
+ *   session of that harness alive (E-PROC-CLINE1).
+ * - `no-link`: no live session above it and no link variable, so orphaned and user-started look the
+ *   same (cline, OpenHands, crush tool processes, or a user's own terminal).
+ * - `unresolved-link`: its session id matches none known, but a live session of that harness has not
+ *   revealed its id, so the process may still be that session's.
+ * - `env-unreadable`: no live session above it and its environment could not be read.
+ */
+type LeftoverReason = 'session-gone' | 'helper-orphaned' | 'harness-idle' | 'no-link' | 'unresolved-link' | 'env-unreadable';
+/** A non-session process inside a worktree with no live session above it. Reported, never killed. */
+interface LeftoverProcess {
+  pid: number;
+  ppid?: number | undefined;
+  argv: readonly string[];
+  cwd: string;
+  /** The harness its link variable or helper signature names, when known. */
+  harness?: SessionHarnessId | undefined;
+  reason: LeftoverReason;
+}
+interface WorktreeOccupancy {
+  /**
+   * A live agent session works here, so the worktree must not be recycled or removed. Dev services
+   * do not count. When the probe is unverified this is `strict`.
+   */
+  busy: boolean;
+  /** `false` when the platform's processes could not be read; `occupants` is then empty, not proof. */
+  verified: boolean;
+  /** Every live session found inside; never limited in number or role. */
+  occupants: Session[];
+  /** Processes no live session launched, provably: safe for a caller to reclaim. */
+  lingering: LeftoverProcess[];
+  /** Processes with no live session above them whose launcher cannot be told; reported, not lingering. */
+  unlinked: LeftoverProcess[];
+}
+interface ProbeOptions {
+  /** Where processes come from; defaults to Linux `/proc`. */
+  source?: ProcessSource | undefined;
+}
+interface OccupancyOptions {
+  /** Treat an unverified probe as busy. Off by default: reuse proceeds, reported as unverified. */
+  strict?: boolean | undefined;
+  /**
+   * Roots of worktrees nested inside this one (Claude Code puts its worktrees under
+   * `<repo>/.claude/worktrees/`, E-PROC-CC5); processes there belong to them, not to this one.
+   */
+  nested?: readonly string[] | undefined;
+}
+/** One snapshot of the process table, answering for any number of worktrees. */
+interface ProcessProbe {
+  verified: boolean;
+  /** @param worktreeRoot absolute, symlinks resolved, as `WorktreeEntry.root` gives it. */
+  occupancy(worktreeRoot: string, options?: OccupancyOptions): WorktreeOccupancy;
+}
+/**
+ * Snapshots processes once and classifies each against the session signature table. Read-only: the
+ * probe never signals or kills a process. A harness missing from the table is invisible to it.
+ */
+export declare function probeProcesses(options?: ProbeOptions): Promise<ProcessProbe>;
+/**
+ * The live agent sessions inside a worktree, or `undefined` when the probe could not read this
+ * platform's processes.
+ */
+export declare function occupants(worktreeRoot: string, options?: ProbeOptions & Pick<OccupancyOptions, 'nested'>): Promise<Session[] | undefined>;
+//#endregion
+//#region src/worktrees/owner.d.ts
+/**
+ * Who a worktree belongs to. Only `self`, a worktree this library leased, may be reused or removed;
+ * every other owner is foreign and left alone.
+ *
+ * - `self`: locked with this library's lease, or an idle slot the library created: unlocked, at a
+ *   library-assigned path (`slotPath`). A lease is a lock that release deletes (E-GIT-L1), so the
+ *   slot path is what still marks a released worktree as ours.
+ * - `claude-code`, `codex`: recognised by a researched marker.
+ * - `cursor`: not produced yet. Its worktree root rests on a forum post only (E-CUR-W1, Low), so a
+ *   Cursor worktree reports `unknown` until that is verified.
+ * - `user`: the primary checkout.
+ * - `unknown`: anything else, including Copilot CLI and herdr worktrees, whose layouts are not
+ *   documented (E-COP-W1, E-HERDR-W1), and a lock whose reason names no one we recognise.
+ */
+type WorktreeOwnerKind = 'self' | 'claude-code' | 'cursor' | 'codex' | 'user' | 'unknown';
+interface WorktreeOwner {
+  owner: WorktreeOwnerKind;
+  /** The `.research/worktree-management` evidence IDs the classification rests on; empty when none. */
+  research: readonly string[];
+}
+/** The `library` value a lease reason carries. */
+export declare const LEASE_LIBRARY = "cyber-agentkit";
+/** A lease as recorded in the `locked` file: one line of JSON (E-GIT-L1, E-GIT-L2). */
+interface LeaseReason {
+  library: typeof LEASE_LIBRARY;
+  leaseId: string;
+  holder: string;
+}
+/** The lease a lock reason records, or `undefined` when the lock is not this library's. */
+export declare function parseLeaseReason(reason: string | undefined): LeaseReason | undefined;
+interface ClassifyOwnerOptions {
+  /** The primary checkout's root, normalized as `WorktreeEntry.root` is (`normalizeWorktreePath`). */
+  primaryRoot: string;
+  /**
+   * Codex's home (`$CODEX_HOME`), normalized. Without it no worktree is recognised as Codex's: the
+   * research records the `$CODEX_HOME/worktrees` root but not its default.
+   */
+  codexHome?: string | undefined;
+}
+/** Classify a worktree's owner from its lock reason and path. Pure: reads nothing from disk. */
+export declare function classifyOwner(entry: WorktreeEntry, options: ClassifyOwnerOptions): WorktreeOwner;
+//#endregion
+//#region src/worktrees/acquire.d.ts
+/**
+ * Why a worktree cannot be reused, in the order the checks run (E-TH-2). The first that applies wins.
+ *
+ * - `primary`: the primary checkout, never reused.
+ * - `foreign`: another tool or the user owns it; see `owner`.
+ * - `leased`: a holder has it; see `holder`. The lease protects it whatever the probe sees.
+ * - `prunable`: its checkout is gone from disk.
+ * - `busy`: a live agent session works inside.
+ * - `unverified`: the probe could not read processes and the caller asked for `strict`.
+ * - `dirty`: uncommitted changes, or git could not say (fail closed).
+ * - `unmerged`: HEAD has not landed on the reset target, or that could not be told.
+ * - `rejected`: the caller's `available` predicate said no.
+ */
+type SkipReason = 'primary' | 'foreign' | 'leased' | 'prunable' | 'busy' | 'unverified' | 'dirty' | 'unmerged' | 'rejected';
+/** One worktree's standing for reuse. */
+interface WorktreeVerdict {
+  worktree: WorktreeEntry;
+  owner: WorktreeOwner;
+  /** Absent when the worktree can be reused. */
+  skip?: SkipReason | undefined;
+  /** The lease holder, when `skip` is `leased`. */
+  holder?: string | undefined;
+  /** What the probe saw, when the checks reached it. */
+  occupancy?: WorktreeOccupancy | undefined;
+  /**
+   * `false` when the probe could not read processes, so a reusable verdict is not proof that no
+   * session works there. `true` when the probe answered or was never needed.
+   */
+  verified: boolean;
+}
+interface ExplainOptions {
+  /** Any directory inside the repository; ignored when `primaryRoot` is given. Defaults to `.`. */
+  from?: string | undefined;
+  /** The primary checkout's root; resolved from `from` when absent. */
+  primaryRoot?: string | undefined;
+  /** The ref a recycle resets to. Defaults to `origin/HEAD`, then the primary checkout's branch. */
+  base?: string | undefined;
+  exec?: Exec | undefined;
+  /** Paths whose changes do not make a worktree dirty; see `DirtyOptions.ignore`. */
+  ignore?: readonly string[] | undefined;
+  /** The opt-in forge signal for "landed"; see `ListWorktreesOptions.forge`. */
+  forge?: ForgeMergedProbe | undefined;
+  /** A process snapshot; one is taken when absent. */
+  probe?: ProcessProbe | undefined;
+  /** Treat a probe that could not read processes as busy. Off by default: reuse proceeds, unverified. */
+  strict?: boolean | undefined;
+  /** `$CODEX_HOME`, so Codex worktrees classify as `codex`; see `ClassifyOwnerOptions`. */
+  codexHome?: string | undefined;
+  /** An extra condition, checked after every safety check; it cannot make a skipped worktree reusable. */
+  available?: ((worktree: WorktreeEntry) => boolean | Promise<boolean>) | undefined;
+}
+/** Every worktree of the repo with the reason it cannot be reused, or none when it can. */
+export declare function explain(options?: ExplainOptions): Promise<WorktreeVerdict[]>;
+/** What a `WorktreeCreator` is asked to make. */
+interface CreateWorktreeRequest {
+  primaryRoot: string;
+  /** The library-chosen path, `<parent>/<repo>.worktrees/<repo>-<n>`; the creator must use it. */
+  path: string;
+  /** The ref to start from. */
+  base: string;
+  /** The branch to check out: an existing one, or a new one at `base`. Detached at `base` when absent. */
+  branch?: string | undefined;
+}
+/**
+ * Makes the worktree at the library-chosen path, so a caller can create it through another tool,
+ * such as herdr, which binds only worktrees it created itself (E-MUX-7). Throw on failure.
+ */
+type WorktreeCreator = (request: CreateWorktreeRequest) => Promise<void>;
+/**
+ * Undoes what a `WorktreeCreator` did besides the checkout itself, such as a herdr workspace bound to
+ * the path. `acquire` calls it when the slot it just created lost its lease claim: the checkout may
+ * now belong to whoever won the claim (E-GIT-L5), so this must leave the worktree and its directory
+ * alone. Failures are swallowed so the retry still runs.
+ */
+type WorktreeCreatorUndo = (request: CreateWorktreeRequest) => Promise<void>;
+/** The default `WorktreeCreator`: `git worktree add`. */
+export declare function gitWorktreeCreator(exec?: Exec): WorktreeCreator;
+interface AcquireOptions extends ExplainOptions {
+  /** Who holds the lease, such as a Captain or Pod; recorded in the lock reason. */
+  holder: string;
+  /** The branch to work on: an existing one, or a new one at `base`. Detached at `base` when absent. */
+  branch?: string | undefined;
+  /** The most slots the repo may have; a new one is created only below it. Unlimited when absent. */
+  max?: number | undefined;
+  /** Defaults to `gitWorktreeCreator(exec)`. */
+  create?: WorktreeCreator | undefined;
+  /** Called when a slot `create` made lost its lease claim; see `WorktreeCreatorUndo`. */
+  undoCreate?: WorktreeCreatorUndo | undefined;
+  /** The lease store's file operations; see `LeaseFs`. */
+  fs?: LeaseFs | undefined;
+  /** Makes lease ids; defaults to a random UUID. */
+  newLeaseId?: (() => string) | undefined;
+}
+interface AcquireResult extends Lease {
+  /** `true` when an idle worktree was recycled, `false` when a new one was created. A reused path
+   * carries path-keyed harness state, so a "continue" there resumes the previous task (E-PROC-CC6). */
+  reused: boolean;
+  /** The branch now checked out; absent when detached. */
+  branch?: string | undefined;
+  /** The branch a reused worktree had before the recycle. */
+  previousBranch?: string | undefined;
+  /** That branch was merged and has been deleted. */
+  previousBranchDeleted?: boolean | undefined;
+  /** `false` when the reused worktree was not checked for live sessions because the probe could not
+   * read processes. */
+  verified: boolean;
+  /** Dev services left running in a reused worktree with no live session behind them. Never killed. */
+  lingering: LeftoverProcess[];
+}
+type AcquireErrorCode = 'pool-full' | 'no-base' | 'contended';
+export declare class AcquireError extends Error {
+  readonly code: AcquireErrorCode;
+  /** The skip reason for every worktree, from the last look. */
+  readonly verdicts: readonly WorktreeVerdict[];
+  constructor(code: AcquireErrorCode, message: string,
+  /** The skip reason for every worktree, from the last look. */
+  verdicts: readonly WorktreeVerdict[]);
+}
+/**
+ * Lease a worktree: recycle an idle one of ours when there is one, otherwise create one at the next
+ * free slot if under `max`. Never fetches and never kills a process.
+ */
+export declare function acquire(options: AcquireOptions): Promise<AcquireResult>;
+//#endregion
+//#region src/worktrees/dirty.d.ts
+interface DirtyOptions {
+  exec: Exec;
+  /**
+   * Paths, relative to the worktree root, whose changes do not count — a tool's own marker file, such
+   * as cyberlegion's `.agents/cyberlegion/config.json`. Passed to git as `:(exclude)` pathspecs.
+   */
+  ignore?: readonly string[] | undefined;
+}
+/**
+ * Whether a checkout has uncommitted changes, tracked or untracked, or `undefined` when git could not
+ * say. `undefined` is not `false`: a caller deciding whether a worktree is safe to reuse must not read
+ * an unanswered question as a clean tree.
+ *
+ * `--untracked-files=all` is explicit because a repo's `status.showUntrackedFiles=no` would otherwise
+ * hide untracked work.
+ */
+export declare function readDirty(worktreeRoot: string, options: DirtyOptions): Promise<boolean | undefined>;
+//#endregion
+//#region src/worktrees/naming.d.ts
+/**
+ * Where the library puts a repo's worktrees: `<parent>/<repo>.worktrees`, a sibling of the primary
+ * checkout (E-MUX-2, E-LEG-1). Every worktree the library creates is a slot in this folder.
+ */
+export declare function worktreesDir(primaryRoot: string): string;
+/**
+ * The path of slot `n`: `<parent>/<repo>.worktrees/<repo>-<n>`. The library assigns `n` and the
+ * caller cannot, so the name stays meaningless and true for the worktree's whole life; what it is
+ * for lives in its branch and lease holder, which change on reuse (decision 2026-10-05, E-TH-7).
+ */
+export declare function slotPath(primaryRoot: string, n: number): string;
+/**
+ * The slot number of a worktree root, or `undefined` when the root is not one of the library's slots.
+ * Both paths are normalized (`normalizeWorktreePath`). `n` is a positive integer with no leading
+ * zero, so `repo-01` is not slot 1.
+ */
+export declare function slotNumber(primaryRoot: string, worktreeRoot: string): number | undefined;
+//#endregion
+//#region src/worktrees/prune-worktrees.d.ts
+/**
+ * Why a worktree was left in place, in the fail-closed order the checks run (E-MUX-5, E-TH-2):
+ *
+ * - `primary`: the primary checkout. Never removed, with no override.
+ * - `foreign`: owned by another tool or person (`classifyOwner`), including a worktree off this library's slot paths.
+ * - `leased`: held by this library's lease. git itself refuses to remove it (E-GIT-L3); `release`
+ *   it first.
+ * - `prunable`: its checkout is already gone; `git worktree prune` collects the entry.
+ * - `busy`: a live agent session works inside.
+ * - `unverified`: the process probe could not read this platform, and the caller kept the strict
+ *   rule.
+ * - `dirty`: uncommitted changes, tracked or untracked.
+ * - `dirty-unknown`: git could not say whether it is clean.
+ * - `unmerged`: its branch has not landed on the default branch.
+ * - `merge-unknown`: whether it landed cannot be told (detached HEAD, or no default branch).
+ * - `unlisted`: only `removeWorktree` reports it: the named path is no worktree of this repository.
+ */
+type PruneSkipReason = 'primary' | 'foreign' | 'leased' | 'prunable' | 'busy' | 'unverified' | 'dirty' | 'dirty-unknown' | 'unmerged' | 'merge-unknown' | 'unlisted';
+interface PruneOutcome {
+  root: string;
+  branch?: string | undefined;
+  owner: WorktreeOwnerKind;
+  /**
+   * - `candidate`: passed every check; a dry run stops here.
+   * - `removed`: `git worktree remove` succeeded.
+   * - `failed`: passed every check, but git refused, or the tree changed before removal.
+   * - `skipped`: see `reason`.
+   */
+  status: 'candidate' | 'removed' | 'failed' | 'skipped';
+  reason?: PruneSkipReason | undefined;
+  /** The probe could not read this platform, and the caller opted out of the strict rule. */
+  unverified?: true | undefined;
+  /** Live agent sessions found inside. */
+  occupants: Session[];
+  /** Dev services no live session launched: the caller may reclaim them. Never killed. */
+  lingering: LeftoverProcess[];
+  /** Processes whose launcher cannot be told. Reported, never killed. */
+  unlinked: LeftoverProcess[];
+}
+interface PruneReport {
+  /** `false` for a dry run. */
+  applied: boolean;
+  /** One outcome per considered worktree, in `git worktree list` order. */
+  worktrees: PruneOutcome[];
+  /** `git worktree prune` succeeded; absent on a dry run. */
+  pruned?: boolean | undefined;
+}
+interface PruneWorktreesOptions {
+  /** The primary checkout's root; see `primaryRoot`. */
+  primaryRoot: string;
+  /** Remove the candidates and run `git worktree prune`. Off by default: a dry run. */
+  apply?: boolean | undefined;
+  /** Consider only these worktree roots; every worktree when absent. */
+  roots?: readonly string[] | undefined;
+  /**
+   * Skip every worktree when the process probe cannot read this platform. On by default, since
+   * removal cannot be undone; `false` proceeds and marks each outcome `unverified`.
+   */
+  strict?: boolean | undefined;
+  exec?: Exec | undefined;
+  /** Paths whose changes do not make a worktree dirty; see `DirtyOptions.ignore`. */
+  ignore?: readonly string[] | undefined;
+  /** The opt-in forge signal for landed detection. */
+  forge?: ForgeMergedProbe | undefined;
+  /** Where processes come from; defaults to Linux `/proc`. */
+  source?: ProcessSource | undefined;
+  /** Codex's home, normalized; see `ClassifyOwnerOptions.codexHome`. */
+  codexHome?: string | undefined;
+}
+/**
+ * Removes the worktrees this library owns that nothing needs any more: unleased, idle, clean, and
+ * landed. A dry run unless `apply` is set. Never touches the primary checkout, a foreign worktree, a
+ * leased one, or a busy one, and never kills a process: lingering services are reported so the caller
+ * can reclaim them (E-TH-5 is the counterexample).
+ *
+ * An unleased worktree carries no record of its owner, since the lease is the only one this library
+ * writes; `classifyOwner` recognises it as this library's by its slot path (`slotPath`).
+ */
+export declare function pruneWorktrees(options: PruneWorktreesOptions): Promise<PruneReport>;
+//#endregion
+//#region src/worktrees/remove-worktree.d.ts
+interface RemoveWorktreeOptions {
+  /** The primary checkout's root; see `primaryRoot`. */
+  primaryRoot: string;
+  /** The worktree to remove, by path. Symlinks and trailing separators are normalized. */
+  root: string;
+  /**
+   * Remove it with `git worktree remove --force`. `true` waives foreign, `prunable`, dirty, and unmerged,
+   * but still skips a busy or `unverified` worktree. `'in-use'` waives those two as well, reporting the
+   * occupants and never killing them. Off by default: the same fail-closed checks `pruneWorktrees` runs.
+   * The primary checkout and a leased worktree are never removed, in any mode.
+   */
+  force?: boolean | 'in-use' | undefined;
+  /**
+   * Skip a busy worktree when the process probe cannot read this platform. On by default; `false`
+   * proceeds and marks the outcome `unverified`. Moot under `force: 'in-use'`, which does not consult it.
+   */
+  strict?: boolean | undefined;
+  exec?: Exec | undefined;
+  /** Paths whose changes do not make a worktree dirty; see `DirtyOptions.ignore`. */
+  ignore?: readonly string[] | undefined;
+  /** The opt-in forge signal for landed detection. */
+  forge?: ForgeMergedProbe | undefined;
+  /** Where processes come from; defaults to Linux `/proc`. */
+  source?: ProcessSource | undefined;
+  /** Codex's home, normalized; see `ClassifyOwnerOptions.codexHome`. */
+  codexHome?: string | undefined;
+}
+/**
+ * Removes one worktree the caller names, the single-target counterpart of `pruneWorktrees`, and
+ * reports the same `PruneOutcome` with a skip `reason`. The caller naming it is what a prune lacks, so
+ * the landed check can be waived with `force`, and the idle check with `force: 'in-use'`; ownership cannot:
+ *
+ * | worktree | without `force` | `force: true` | `force: 'in-use'` |
+ * | --- | --- | --- | --- |
+ * | the primary checkout | `primary` | `primary` | `primary` |
+ * | held by this library's lease | `leased`; `release` it first | `leased` | `leased`; the lease is never broken |
+ * | foreign (another tool, person, or lock) | `foreign` | removed, unless git refuses a locked one: `failed` | same |
+ * | a live agent session inside | `busy` (or `unverified`) | `busy` (or `unverified`) | removed; the sessions are reported, never killed |
+ * | checkout already gone | `prunable` | `git worktree remove --force` is tried | same |
+ * | dirty or unmerged | the matching reason | removed | removed |
+ * | a path that is no worktree of this repository | `unlisted` | `unlisted` | `unlisted` |
+ *
+ * `--force` is passed once and `-f -f` never: one refuses a locked worktree, so a lease taken after the
+ * listing holds (E-GIT-L3, E-GIT-L4). Never kills a process; lingering services are reported so the
+ * caller can reclaim them. Always applies: there is no dry run, since the caller named the target.
+ */
+export declare function removeWorktree(options: RemoveWorktreeOptions): Promise<PruneOutcome>;
+//#endregion
+//#region src/worktrees/seed-worktree.d.ts
+/**
+ * The file operations `seedWorktree` performs, injected so a caller can dry-run, sandbox, or log
+ * them. Paths are absolute. Nothing here runs a command: the include file is data, never a script
+ * (research: 'E-TH-4').
+ */
+interface SeedFs {
+  /** The file's text, or `undefined` when it does not exist. */
+  readText(path: string): Promise<string | undefined>;
+  /** Whether anything — file, directory, or link — is at the path. */
+  exists(path: string): Promise<boolean>;
+  /** Create a directory and its parents; a no-op when it exists. */
+  mkdirp(path: string): Promise<void>;
+  copyFile(from: string, to: string): Promise<void>;
+}
+/** The default `SeedFs`, on `node:fs/promises`. */
+export declare const nodeSeedFs: SeedFs;
+interface SeedWorktreeOptions {
+  exec: Exec;
+  /** Defaults to `nodeSeedFs`. */
+  fs?: SeedFs | undefined;
+  /**
+   * Replace a file the worktree already has. Off by default: a recycled worktree keeps its ignored
+   * files (a recycle runs `clean -fd` without `-x`, research: 'E-TH-3'), and its own `.env` may have
+   * been edited on purpose.
+   */
+  overwrite?: boolean | undefined;
+}
+type SeedSkipReason =
+/** Matches the include file but is not gitignored, so a checkout already carries it or it is
+ * untracked work that belongs to the source checkout (research: 'E-CC-W2'). */
+'not-ignored' |
+/** The worktree already has something at that path, and `overwrite` is off. */
+'exists' |
+/** The copy threw; `error` holds the message. */
+'failed';
+interface SeedSkip {
+  /** Relative to the checkout root, with `/` separators, as git prints it. */
+  path: string;
+  reason: SeedSkipReason;
+  error?: string | undefined;
+}
+interface SeedInventory {
+  /**
+   * `absent` when the source has no `.worktreeinclude`, so nothing was attempted; `unknown` when git
+   * could not list the candidates, so nothing was copied and nothing is known to be missing.
+   */
+  include: 'present' | 'absent' | 'unknown';
+  /** Paths copied, relative to the checkout root. */
+  copied: string[];
+  skipped: SeedSkip[];
+}
+/** The include file's name and place: the project root, `.gitignore` syntax (research: 'E-CC-W2'). */
+export declare const WORKTREE_INCLUDE = ".worktreeinclude";
+/**
+ * Copies the gitignored files a `.worktreeinclude` names from a source checkout (normally the primary)
+ * into a new or recycled worktree, and reports what it copied and what it skipped.
+ *
+ * Claude Code's semantics (research: 'E-CC-W2'): the file sits at the project root and uses
+ * `.gitignore` syntax, and only a file that matches a pattern *and* is gitignored is copied, so
+ * tracked files are never duplicated. Git does the matching here, so negation, anchoring, and
+ * directory patterns behave exactly as they do in `.gitignore`. Inside a wholly ignored directory, a
+ * pattern that starts with `**` and a slash matches every file below it here, while Claude Code reaches
+ * in only when the directory's path holds the pattern's first name (research: 'E-CC-W6'), so this can
+ * copy a superset of what Claude Code would.
+ *
+ * The include file is read from the source's working tree, as Claude Code does, not from its
+ * committed HEAD as Treehouse does (research: 'E-TH-4'), so an uncommitted edit takes effect.
+ */
+export declare function seedWorktree(sourceRoot: string, worktreeRoot: string, options: SeedWorktreeOptions): Promise<SeedInventory>;
+//#endregion
+export type { AcquireErrorCode, AcquireOptions, AcquireResult, ClassifyOwnerOptions, CreateWorktreeRequest, DirtyOptions, Exec, ExplainOptions, ForgeMergedProbe, LandedSignal, Lease, LeaseFs, LeaseReason, LeaseStoreOptions, LeftoverProcess, LeftoverReason, ListWorktreesOptions, OccupancyOptions, PrimaryRootOptions, ProbeOptions, ProcessInfo, ProcessProbe, ProcessSource, PruneOutcome, PruneReport, PruneSkipReason, PruneWorktreesOptions, ReleaseResult, RemoveWorktreeOptions, SeedFs, SeedInventory, SeedSkip, SeedSkipReason, SeedWorktreeOptions, Session, SessionHarnessId, SkipReason, WorktreeCreator, WorktreeCreatorUndo, WorktreeEntry, WorktreeOccupancy, WorktreeOwner, WorktreeOwnerKind, WorktreeVerdict };