toolroll 0.5.0

package/dist/worktree.d.ts

@@ -0,0 +1,249 @@
+/**
+ * The pool of working copies, and the leases over them.
+ *
+ * Semantics copied from treehouse rather than reinvented, including the two
+ * rules that are easy to get wrong and expensive to get wrong quietly:
+ *
+ * **Untracked files count as dirty.** A repository whose `.gitignore` hides
+ * build output is still a repository with somebody's work in it, and a pool
+ * that recycles a directory because `git status` looked clean under the
+ * operator's config will delete something they wanted. So the check is run
+ * with ignored files excluded but untracked files included, which is the
+ * conservative reading of "is anyone using this".
+ *
+ * **Reconstructed state is leased-until-verified.** A worktree found on disk
+ * after a crash describes what a dead process was doing, not what is true now.
+ * It comes back into the pool marked unverified, and something has to look at
+ * it before it is handed to anybody.
+ *
+ * Where the pool lives is a decision, not a detail. Worktrees are created
+ * outside the repository — never inside it, where they would appear as
+ * untracked directories in the operator's own `git status`, and never inside a
+ * synced folder like OneDrive or Dropbox, where a sync client racing an agent
+ * over `.git` internals corrupts both.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+import type { Store, WorktreeRow } from "./store.js";
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+export type PoolOptions = {
+    /** Where worktrees are created. Outside the repo, and outside any sync root. */
+    root: string;
+    runner?: Runner;
+};
+export type LeaseRequest = {
+    repo: string;
+    branch: string;
+    runner: string;
+    taskRef?: number;
+    now: Date;
+    /** Branch to create from, when the branch does not exist yet. */
+    base?: string;
+    /**
+     * Reclaim this task's OWN leftover: when the checkout was released dirty
+     * by a finished attempt of the same task (not a dead runner's, not
+     * another task's), keep what it left as a patch under the last run's
+     * evidence and reset the tree for the next attempt. Without this a
+     * failed attempt's half-edit blocks every retry forever.
+     */
+    reclaim?: {
+        evidenceRoot: string;
+    };
+    /** With `base`: a branch that already exists (its checkout removed by storage retention) is checked out as it
+     * stands, as its kept checkout would have been reused. Without it, `base` always starts a new branch (and an
+     * existing one refuses). */
+    reuseBranch?: boolean;
+};
+export type LeaseResult = {
+    ok: true;
+    worktree: WorktreeRow;
+    created: boolean;
+    reclaimed?: string;
+    resumedFromRun?: number;
+    recoveryKind?: "completed" | "partial";
+} | {
+    ok: false;
+    reason: LeaseFailure;
+    message: string;
+};
+export type LeaseFailure = "held" | "dirty" | "git" | "unverified" | "unknown-runner" | "in-use";
+/** Why storage retention left a checkout in place. */
+export type KeptWhy = "has changes" | "has commits" | "unreadable" | "git refused";
+/**
+ * The note a lease leaves in the checkout, naming the process holding it.
+ *
+ * Deliberately inside the worktree rather than beside it: it travels with the
+ * directory, and `git status` will show it as untracked, which is honest —
+ * something is in there.
+ */
+export declare const MARKER = ".standing-orders-lease";
+/** Creating a worktree copies a tree; it is local work but not instant. */
+export declare const WORKTREE_TIMEOUT_MS = 60000;
+/**
+ * A path for this repository and branch that is stable across runs.
+ *
+ * Stable so that a second attempt at the same task reuses the checkout it
+ * already paid for, and flattened so a branch called `feat/a/b` cannot escape
+ * the pool root through its own slashes.
+ */
+export declare function worktreePath(root: string, repo: string, branch: string): string;
+/** Record a potentially writing subprocess against the original checkout lease. */
+export declare function recordWorktreeProcess(store: Store, path: string, runner: string, pid: number, leaseEpoch?: string | null): void;
+/** Read-only occupancy witness shared with stop settlement. */
+export declare function worktreeProcessOccupancy(path: string): {
+    held: true;
+    by: number;
+} | {
+    held: false;
+};
+export declare class WorktreePool {
+    private readonly store;
+    private readonly options;
+    private readonly runner;
+    constructor(store: Store, options: PoolOptions);
+    /**
+     * Take a working copy for this branch.
+     *
+     * Refused when somebody else holds it — losing is ordinary, and a caller
+     * that is told who holds it can go and do something else rather than poll.
+     */
+    /**
+     * Whether a live process is working in there, independently of what the
+     * database believes.
+     *
+     * treehouse's rule, and it exists because the database is the thing most
+     * likely to be wrong: a row saying "released" written by a process that then
+     * kept running, or a stale row from a crash, are both cases where the
+     * checkout is genuinely occupied and only the machine can say so. So each
+     * lease drops a note naming the process holding it, and `process.kill(pid, 0)`
+     * — which signals nothing and only asks whether the pid exists — is what
+     * answers the question afterwards.
+     *
+     * A pid can be recycled by the operating system, so this can say "in use"
+     * about a stranger. That is the safe direction: refusing a checkout somebody
+     * may be in costs a retry, and taking one they are in costs their work.
+     */
+    inUse(path: string): {
+        held: true;
+        by: number;
+    } | {
+        held: false;
+    };
+    /**
+     * Once a provider exists it, not the supervising console, is the process
+     * whose liveness protects this checkout. Rewriting the occupancy marker at
+     * spawn means a replacement control plane waits for an orphaned provider
+     * to finish instead of starting a second writer in the same worktree.
+     */
+    markProviderOccupancy(path: string, runner: string, providerPid: number, leaseEpoch?: string | null): boolean;
+    /** Spawn callbacks must fail if custody cannot be recorded. The transport
+     * kills and reaps its child before returning that callback failure. */
+    recordProviderOccupancy(path: string, runner: string, providerPid: number, leaseEpoch?: string | null): void;
+    lease(request: LeaseRequest): Promise<LeaseResult>;
+    private leaseNow;
+    /**
+     * A crash can strand either a finished handoff or a partial source draft.
+     * The expired lease can no longer authorize a commit, so this never ingests
+     * the old result. It classifies the recovery context for the next freshly
+     * fenced attempt, which must review and prove the inherited work itself.
+     */
+    private recoverableDraft;
+    /**
+     * Preserve a dirty tree's work as one patch — tracked changes against
+     * HEAD, then each untracked file against nothing — under the evidence of
+     * the last run that lived in this checkout (or a leftover folder when no
+     * run is on record). Nothing is deleted here.
+     */
+    private keepLeftover;
+    /** Back to HEAD, untracked gone, our lease note kept; proven clean after. */
+    private resetTree;
+    /** Leave a note naming the process holding this checkout. */
+    private mark;
+    /**
+     * Hand a working copy back.
+     *
+     * The tree is inspected first, and dirt is reported rather than cleaned.
+     * `git reset --hard` leaves untracked files behind and destroys work that
+     * might have been repairable, which is why the failure taxonomy this project
+     * borrows says to preserve a failed commit rather than blanket-reset.
+     */
+    release(path: string, now: Date): Promise<LeaseResult>;
+    /**
+     * Worktrees git knows about that this pool does not, and the reverse.
+     *
+     * The first is somebody else's business and is left alone. The second is
+     * ours: a row for a directory that is no longer there, which happens when a
+     * machine is reimaged or a pool root is deleted between runs.
+     */
+    /**
+     * Remove a released checkout and its branch (v4 review, finding 3): the
+     * read-only roles' workspaces are disposable, so the next attempt starts
+     * from the requested base instead of whatever the last one saw. Refused
+     * while a process holds the directory; a failure leaves the checkout
+     * where `worktrees` can see it rather than pretending it is gone.
+     */
+    discard(path: string, now: Date): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    orphans(repo: string): Promise<{
+        ok: true;
+        untracked: string[];
+        missing: string[];
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * Take responsibility for worktrees that exist but nothing recorded.
+     *
+     * These turn up after a crash between `git worktree add` and the row that
+     * should have followed it, or when a database is replaced while checkouts
+     * survive on disk. Left alone they are invisible: git knows about them,
+     * every pool query does not, and the same branch gets checked out again
+     * beside them.
+     *
+     * Adopted **released and unverified**, never leased. Nobody watched them
+     * being made, so they are a claim about the past — the same rule that
+     * governs a dead runner's worktrees, for the same reason.
+     *
+     * Rows whose directory is gone are dropped: a lease over a path that does
+     * not exist can only refuse work that could otherwise have run.
+     */
+    adopt(repo: string, now: Date): Promise<{
+        ok: true;
+        adopted: string[];
+        forgotten: string[];
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * Keep storage in check: remove the working copies nobody needs any more.
+     * A checkout goes when it was released `keepMs` ago or longer, nothing
+     * holds it, it is clean (build output that .gitignore hides is not work),
+     * everything its HEAD reaches is on a branch, tag or remote, and it isn't the
+     * checkout of one of `keep()`'s branches (those unfinished tasks work on or
+     * would come back to, read afresh before each removal), by its branch or by
+     * the name a lease of that branch would give it under any root. Only the
+     * working copy goes: its branch, and so every commit, stays, and a later
+     * lease of the same branch makes a new one. At most `max` go per pass.
+     */
+    prune(repo: string, now: Date, keepMs: number, keep: () => readonly string[], max?: number): Promise<{
+        removed: WorktreeRow[];
+        kept: {
+            path: string;
+            why: KeptWhy;
+        }[];
+    }>;
+    /**
+     * Whether anybody's work is in there. null means we could not tell, which is
+     * neither clean nor dirty and must not be rounded to either.
+     *
+     * `--untracked-files=all` and no `--ignored`: build output that .gitignore
+     * hides is not work, but a file somebody dropped in and never staged is.
+     */
+    private isDirty;
+    private git;
+}