looply-cli 0.0.0-stage → 0.2.0

package/dist/workspace.d.ts

@@ -0,0 +1,639 @@
+import { GitDriver } from './git-driver';
+import { type Liveness, type ProbeFn as LeaseProbeFn } from './run-lease';
+import { type ControlKind } from './control-file';
+import type { LedgerFs } from './ledger-store';
+/**
+ * WHERE A SECOND EXECUTION LIVES, AND WHO IS ALLOWED TO SAY SO.
+ *
+ * Phase 1 makes two executions safe by giving each its own checkout and its own
+ * execution state directory, rather than by making a dozen single-writer stores
+ * multi-writer. That is the cheaper half of a decision the recon argued at
+ * length: every store already takes `stateDir` as its first argument, so N state
+ * directories are already expressible — what was missing was a place to put
+ * them and something that knows they exist.
+ *
+ * TWO THINGS LIVE HERE AND THEY ARE DELIBERATELY SEPARATE:
+ *
+ *   the WORKSPACE   a linked git worktree plus its own `.looply/state`. Created
+ *                   through `GitDriver`, so it inherits every Phase 0/0.5
+ *                   defence rather than reimplementing a safe-enough subset.
+ *   the REGISTRY    one exclusively-created file per live execution, under the
+ *                   PROJECT's state directory. It is what makes capacity
+ *                   countable, `status` aggregable, and an orphan identifiable.
+ *
+ * ⚠️ THE REGISTRY IS NOT A LOCK. The run lease is still the mutual exclusion,
+ * still one per execution state directory, and still the thing that decides
+ * whether a checkout is busy. The registry answers a different question — "what
+ * else is running for this project" — which no lease can answer because leases
+ * cannot see each other.
+ */
+/** How a workspace's own directory is named under the workspaces root. */
+export declare const WORKSPACES_DIR = "workspaces";
+/**
+* Clear a workspace's creation marker, by name.
+*
+* 🔴 A MARKER WHOSE PID IS RECYCLED PINS ITS WORKSPACE AS "in use" FOR EVER.
+* `looply runs` shows it, `--reap` refuses it because something appears to be
+* using it, and nothing else can ever say otherwise — the same permanent wedge
+* a recycled pid makes of a slot, in a place with no `--release` to reach it.
+*
+* ⚠️ IT CLEARS THE MARKER, NOT THE CHECKOUT. Afterwards the workspace is
+* ordinary: `--reap` judges it on residue and evidence like any other, and will
+* still keep it if it holds a person's files.
+*/
+export declare function forgetCreationMarker(cwd: string, name: string): boolean;
+/**
+ * Where every workspace for a project lives — OUTSIDE the repository.
+ *
+ * 🔴 IT WAS INSIDE, AND THAT WAS WRONG. The first version put workspaces under
+ * `<root>/.looply/workspaces`, and `.gitignore` covers `.looply/state/` and
+ * `.looply/runs/` but not that. Measured: creating one workspace turned the main
+ * checkout's `git status --porcelain` into `?? .looply/`. Looply's own dirty
+ * check would not have noticed — `changedPaths` filters `.looply/**` — but a
+ * PERSON would, and a person who then typed `git add -A` would commit an entire
+ * second checkout into their repository.
+ *
+ * `~/.looply` is where this codebase already puts state that must survive the
+ * repository, and for the same stated reason: `git clean -fd` would delete
+ * in-tree credentials. A workspace has exactly that property.
+ *
+ * ⚠️ KEYED BY A HASH OF THE MAIN WORKTREE PATH, not by the project's name. Two
+ * checkouts of the same repository in two places are two projects here, which is
+ * the same identity rule `containerName` and `providerSessionDir` already use.
+ */
+export declare function workspacesRoot(cwd: string, home?: string): string;
+/**
+ * One live execution, as the project can see it.
+ *
+ * Everything here is what a later phase needs to correlate evidence: which
+ * execution, in which checkout, on which branch, from which commit, writing
+ * which state directory, under which process.
+ *
+ * ⚠️ THE PURSUIT IS DELIBERATELY ABSENT. The registry bounds capacity and
+ * identifies orphans, and it can do both without ever knowing what the work is
+ * FOR — which is the bar `goal-wiring.spec.ts` sets for that vocabulary. The
+ * correlation a later phase needs already exists: `run.started` joins this
+ * `runId` to its goal on the ledger, once, where the binding was checked.
+ */
+export interface RunRecord {
+    runId: string;
+    /** The checkout this execution owns. The main worktree for an ordinary run. */
+    workspace: string;
+    /** Its own state directory — `<workspace>/.looply/state`. */
+    stateDir: string;
+    branch: string;
+    /** The commit the workspace was cut from. Phase 5 needs it; Phase 1 records it. */
+    baseSha: string;
+    /** Null for the main checkout, which no execution created and none may remove. */
+    worktree: boolean;
+    pid: number;
+    host: string;
+    startedAt: string;
+    /**
+     * M4-2: who asked for this run. `machine` is the daemon's autonomy tick
+     * (the launcher says `--autonomous`); `person` is `looply run` by hand or a
+     * start-run command from the phone. ABSENT — every record from before — is
+     * a person's: only a machine-started run is ever preemptible.
+     */
+    startedBy?: 'machine' | 'person';
+}
+/** What a registry entry looks like once its process has been probed. */
+export type RunLiveness = {
+    kind: 'active';
+    record: RunRecord;
+}
+/** The process is PROVEN gone. The workspace may still hold work worth keeping. */
+ | {
+    kind: 'orphaned';
+    record: RunRecord;
+}
+/**
+ * The pid could not be judged — EPERM, an unfamiliar errno, a nonsense pid.
+ * ⚠️ NOT AN ORPHAN. Every consumer here must treat this as "do not touch":
+ * unknown means the reaper leaves the directory and the slot stays held.
+ */
+ | {
+    kind: 'unknown';
+    record: RunRecord;
+}
+/** The file could not be read or understood; never reaped on a guess. */
+ | {
+    kind: 'unreadable';
+    path: string;
+    because: string;
+};
+/**
+ * 🔴 THE PID PROBE IS `run-lease`'s, NOT A SECOND ONE. This file had its own,
+ * and it was worse in both directions:
+ *
+ *   • Two-valued. Anything other than `EPERM` — including an unfamiliar errno —
+ *     read as DEAD, which is the exact mistake `run-lease` documents at length
+ *     and defends against with a third answer.
+ *   • It never rejected pid 0. `process.kill(0, 0)` signals the CURRENT PROCESS
+ *     GROUP and succeeds, so a record carrying pid 0 read as alive forever and
+ *     its slot could never be reclaimed — a permanent capacity leak from one
+ *     torn write.
+ *
+ * The owner's standing rule about not building a second "safe enough" Git
+ * runner is the same rule: liveness has one implementation, hardened once.
+ */
+export type ProbeFn = LeaseProbeFn;
+export declare const nodeProbe: ProbeFn;
+export declare class WorkspaceError extends Error {
+}
+/**
+ * The registry of live executions for one project.
+ *
+ * Entries are one file each, created with `wx`, exactly as the run lease is —
+ * the filesystem decides the winner, no read-then-write, and a crash leaves a
+ * file that can be judged rather than a lock nobody can clear.
+ */
+export declare class RunRegistry {
+    private readonly projectState;
+    private readonly probe;
+    constructor(projectState: string, probe?: ProbeFn);
+    private get dir();
+    private pathFor;
+    /**
+     * Claim a slot. Throws if this runId is already registered.
+     *
+     * ⚠️ EXCLUSIVE CREATE, not "check then write". Two executions starting in the
+     * same moment must not both believe they took the last slot, and only the
+     * filesystem can arbitrate that without a lock of our own.
+     */
+    register(record: RunRecord): void;
+    /**
+     * Take one of `limit` slots, or refuse. THIS is the bound.
+     *
+     * 🔴 COUNTING WAS CHECK-THEN-ACT AND CLAIMED NOT TO BE. `capacityVerdict`
+     * read `active()`, judged, and only then did anything get created — and the
+     * exclusive `wx` this class pointed at as "the arbitration" is keyed on
+     * `runId`, minted fresh per run. Two runs starting together could never
+     * collide on that name, so both passed the count and both registered. Nothing
+     * upstream helped: two workspaces hold two different leases, and a lease
+     * cannot see another checkout.
+     *
+     * The SLOT is the exclusive thing. There are at most `limit` slot names, so at
+     * most `limit` runs can hold one, and the filesystem decides — exactly as it
+     * does for the run lease and the override marker.
+     *
+     * ⚠️ A SLOT HELD BY A DEAD PROCESS IS RECLAIMED, not counted. Otherwise one
+     * crash would lower this machine's concurrency until somebody noticed, which
+     * is the capacity leak this exists to avoid.
+     */
+    claim(record: RunRecord, limit: number): {
+        ok: true;
+        slot: number;
+    } | {
+        ok: false;
+        because: string;
+    };
+    /** Wait a short while for the claim lock, breaking one a dead process left. */
+    private waitForToken;
+    private claimUnderLock;
+    /**
+     * Having WON a slot, decide whether it may be kept.
+     *
+     * 🔴 THE OVER-LIMIT COUNT WAS CHECK-THEN-ACT, and it was the only thing that
+     * could see slots above the limit. The exclusive `wx` is the arbitration for
+     * `[0, limit)` and nothing else, so with two live runs on out-of-range slots
+     * and the limit lowered, several starts could all pass the count and then all
+     * win DIFFERENT in-range slots. Reproduced: five executions at a limit of
+     * three. The fix for one hole opened a smaller one beside it.
+     *
+     * A count cannot be made atomic, so the decision moves AFTER the exclusive
+     * create: take the slot, then look. At most `limit` in-range slots can exist,
+     * so what is left to judge is how many holders there are in total.
+     *
+     * ⚠️ THE TIE-BREAK IS THE SLOT NUMBER, so simultaneous winners do not all back
+     * out and leave the machine idle. A holder keeps its slot when the holders
+     * BELOW it, plus every out-of-range holder, still leave room; otherwise it
+     * gives the slot back and refuses. Deterministic, and it always leaves exactly
+     * as many runs as the limit allows.
+     */
+    private settle;
+    /**
+     * The claim lock, if one is being held, and by whom.
+     *
+     * 🔴 A WEDGED LOCK WAS INVISIBLE TO EVERY COMMAND. It is only breakable when
+     * its owner is PROVEN dead, so a lock left by a process that is alive but
+     * hung — or by one whose pid cannot be judged — denied every start of the
+     * project with a message about "another start deciding" and no way to see or
+     * clear it. That is the same wedge the slot files had before `looply runs`
+     * listed them.
+     */
+    claimLock(): {
+        pid: number | null;
+        liveness: Liveness | 'unknown';
+    } | null;
+    /** Clear a held claim lock. A person's last resort, as `forgetSlot` is. */
+    forgetClaimLock(): boolean;
+    /** Every slot that is still held, whatever its number. `except` is skipped. */
+    private allHolders;
+    private atCapacity;
+    /**
+     * Take a free slot. The ONLY way a slot file is ever created.
+     *
+     * ⚠️ `wx` AND NOTHING ELSE. No read first, no delete first: the filesystem is
+     * the arbitration, exactly as it is for the run lease and the override marker.
+     */
+    private take;
+    /**
+     * Remove a slot file whose holder is proven gone — or refuse to.
+     *
+     * 🔴 THE OLD RECLAIM WAS UNLINK-THEN-CREATE, WHICH IS THE CHECK-THEN-ACT THIS
+     * WHOLE CLASS EXISTS TO REMOVE. It judged a slot stale, unlinked it BY PATH,
+     * and only then tried its exclusive create. Two starters that both saw the
+     * same stale slot both unlinked — and the second unlink deleted the FIRST
+     * one's freshly created file, so both believed they held slot 0 and both ran.
+     * At limit 1. Reproduced with real concurrent processes.
+     *
+     * Two things fix it, and the second is the one that actually holds:
+     *
+     *   THE TOKEN     `slot-<n>.reclaiming`, created with `wx`. At most one
+     *                 process reclaims a given slot at a time, so the common case
+     *                 has no race to lose.
+     *   THE RE-READ   nothing is unlinked unless it is STILL the same record this
+     *                 judged, and still gone. A slot that has been re-taken names
+     *                 a different runId, and a different runId is never removed.
+     *
+     * The re-read is what makes this correct even if the token were somehow held
+     * twice — after a crash, say. The token only makes the correct path the quiet
+     * one.
+     *
+     * ⚠️ A TOKEN LEFT BY A CRASH IS BROKEN ONLY IF ITS OWN PID IS PROVEN DEAD, and
+     * then the re-read still decides. Otherwise a crash during reclaim would wedge
+     * one slot of this project for ever.
+     */
+    private reclaim;
+    private takeToken;
+    /**
+     * The token's contents, once they have stopped changing.
+     *
+     * An exclusive create is two syscalls — open, then write — so a token read in
+     * between is empty through no fault of its holder. This re-reads over a short
+     * window and only reports empty if it stays empty.
+     */
+    private settledText;
+    /** Give back a token THIS process holds. One held by anybody else is left. */
+    private dropToken;
+    /**
+     * Remove a token judged un-defendable — and ONLY if it is still the one that
+     * was judged.
+     *
+     * 🔴 THIS UNLINKED BY PATH. Two processes could both judge the same stale lock
+     * breakable; the first broke it and won the exclusive create, and the second —
+     * still inside its own break — then unlinked the FIRST one's fresh lock and
+     * created its own. Both were inside the critical section, and the loss
+     * cascaded from there. An adversarial pass measured up to four at once.
+     *
+     * `judged` is the content this decided about. If the file no longer says that,
+     * somebody else has already acted and this must not.
+     */
+    private breakToken;
+    /**
+     * Give back the slot THIS run holds. A slot held by anybody else is left.
+     *
+     * 🔴 IT USED TO UNLINK BY INDEX, unconditionally, and that was the worst
+     * defect in this file. `releaseHold` gives the lease back BEFORE the slot, and
+     * `claim` treats a slot whose holder's lease is gone as free — so between
+     * those two lines another run could legitimately reclaim slot N, and this
+     * run's teardown would then delete the NEW holder's claim. The bound is
+     * exceeded, and it stays exceeded: the same window reopens at every teardown.
+     *
+     * Every sibling here is keyed on identity — `release(runId)`, `forget(runId)`.
+     * This one is now too. Absent is success, and so is a slot that has moved on.
+     */
+    releaseSlot(slot: number, runId: string): void;
+    /** Every slot, as a person needs to see it — including ones nothing can read. */
+    slots(): {
+        slot: number;
+        record: RunRecord | null;
+        path: string;
+    }[];
+    /**
+     * The files in the slots directory that `slots()` refuses to name.
+     *
+     * 🔴 THE DOCBLOCK ABOVE CLAIMED THESE WERE REPORTED, AND THEY WERE NOT.
+     *
+     * Filtering `slot-abc.json` and `slot-01.json` out of `slots()` is right —
+     * a slot nobody can name is not a slot, and showing a person a row that
+     * `--release slot-01` cannot clear is worse than showing nothing. But the
+     * consequence of "not a slot" was "not anywhere": no row, no count, no
+     * mention, while the file sat in the directory looking exactly like the
+     * others. That is the failure mode this whole command exists to prevent.
+     *
+     * ⚠️ IT IS INERT, NOT DANGEROUS. Nothing counts it toward the bound and
+     * nothing reads it. It is reported because a file a person can see on disk
+     * and cannot see in `looply runs` is the thing that makes people distrust
+     * the listing — and because `rm` is the fix, which they can only reach if
+     * they are told the path.
+     */
+    strayFiles(): string[];
+    /**
+     * Clear one slot by NUMBER, whatever it holds or fails to hold.
+     *
+     * The companion to `forget(runId)` for the case a runId cannot answer: a slot
+     * file that is corrupt, or truncated, or written by a version that is gone.
+     * Nothing automatic reaches this either — a person types `slot-<n>`.
+     */
+    forgetSlot(slot: number): boolean;
+    /**
+     * Whether the run this slot names is still holding its own lease.
+     *
+     * ⚠️ A SECOND WITNESS, BECAUSE A PID IS A WEAK ONE. Pids are recycled, and a
+     * record left behind by a hard crash whose number a later process inherits
+     * probes as ALIVE for ever — so the slot it holds is never reclaimed and the
+     * machine's concurrency drops by one permanently, with nothing to point at.
+     *
+     * A live run always holds the lease in its own execution state directory: it
+     * is taken before the slot is claimed and given back in the same breath as
+     * the slot. So a slot whose run has NO lease is not a run, whatever its pid
+     * says — which covers the leak this cannot otherwise see, including the
+     * narrow one where releasing the lease succeeded and clearing the entry did
+     * not.
+     *
+     * ⚠️ IT DOES NOT CLOSE THE PID-RECYCLING HOLE, and saying so is the point: a
+     * hard crash leaves BOTH the lease and the record behind, so both witnesses
+     * agree and both are wrong. That residual is inherited from the lease's own
+     * liveness model, which documents it and deliberately has no heartbeat. What
+     * bounds it is that a person can always say so by name — see
+     * `looply runs --release`.
+     *
+     * ⚠️ AND IT FAILS TOWARDS "HELD". An unreadable lease is not evidence of
+     * absence; only a lease that is gone, or one that names a DIFFERENT run,
+     * frees the slot.
+     */
+    private leaseAgrees;
+    /**
+     * Forget a run entirely: its record and any slot it holds.
+     *
+     * ⚠️ THE ONLY THING THAT CAN CLEAR A SLOT WHOSE PID LOOKS ALIVE, and it exists
+     * for exactly one situation: a pid recycled onto a crashed run's number, where
+     * every automatic witness agrees and every one of them is wrong. It is not
+     * called by anything automatic — a person names the run.
+     */
+    forget(runId: string): {
+        forgot: boolean;
+        slot: number | null;
+    };
+    private slotPath;
+    private readSlot;
+    /** Give the slot back. Absent is success: releasing twice is not an error. */
+    release(runId: string): void;
+    /** Every entry, with its process probed. Never throws on a bad file. */
+    list(): RunLiveness[];
+    /**
+     * Everything NOT PROVEN DEAD — what capacity counts and what `stop` signals.
+     *
+     * ⚠️ 'unknown' IS INCLUDED, DELIBERATELY. Both callers are safer over-counting
+     * than under-counting: capacity would otherwise start an extra execution, and
+     * `stop` would otherwise report a run as finished while it is still writing.
+     */
+    active(): RunRecord[];
+}
+/**
+ * 🔴 `capacityVerdict` WAS DELETED, and its absence is the point.
+ *
+ * It counted live records and judged them against the limit, and it read like
+ * the concurrency bound — but `claim` replaced it and nothing called it any
+ * more. A function that looks like the bound, is exported, is tested, and
+ * decides nothing is worse than no function at all: the next person to reach
+ * for it gets check-then-act semantics back, with tests that pass.
+ *
+ * The bound is `RunRegistry.claim`. There is one.
+ */
+/**
+ * Write a control request where EVERY live execution will read it.
+ *
+ * 🔴 ONE SHARED FILE PLUS N CONSUMERS IS A BRAKE THAT RELEASES ITSELF, and both
+ * writers had the same hole. `ControlStore.consume()` writes `resume` into the
+ * file it read, so the FIRST execution to reach a round boundary clears the
+ * instruction and every other one reads `resume` and carries on.
+ *
+ * `looply stop` was taught to write an addressed request per execution; the
+ * DAEMON — which is how the phone's Stop and Pause arrive — was not, and it is
+ * the path that matters most, because nobody is standing at the terminal to
+ * notice that two of three runs kept going.
+ *
+ * So there is one function, and both call it.
+ *
+ * ⚠️ THE SHARED FILE IS STILL WRITTEN, FIRST. It is what a run started AFTER
+ * this request will read, what Simple Mode has always used, and what `resume`
+ * has to clear. The addressed files are additive.
+ *
+ * ⚠️ AND A FAILURE TO REACH ONE EXECUTION IS REPORTED, not swallowed. A brake
+ * that misses a run must say which.
+ */
+export declare function requestControlEverywhere(projectState: string, live: readonly RunRecord[], kind: ControlKind, actor: string, fs: LedgerFs, 
+/** Where this project's executions may legitimately keep state. See below. */
+cwd?: string): Promise<{
+    reached: string[];
+    unreachable: string[];
+}>;
+/**
+ * Create a workspace for an execution: a linked worktree on a fresh branch.
+ *
+ * ⚠️ THE GIT DRIVER DOES THE WORK, so the worktree is created by the same
+ * substrate every other verb uses — the repository-config refusal, the
+ * repository-root check, the rebuilt `GIT_` environment and the absolute git
+ * binary all apply. A provisioner with its own runner would be a second path
+ * around four defences at once.
+ */
+export declare function createWorkspace(git: GitDriver, cwd: string, runId: string, branch: string, baseSha: string, 
+/** Whose home the workspaces root lives under; the user's unless a test says otherwise (M4-1). */
+home?: string, 
+/**
+ * `run.carry_into_checkouts` — directories this fresh checkout needs that git
+ * does not carry, above all `node_modules`.
+ *
+ * 🔴 WITHOUT IT THE GATE CANNOT PASS HERE. A worktree holds what git tracks,
+ * the gate runs with no network by design, and so a second worker's every
+ * round went red on the same missing toolchain. Measured: four rounds, one
+ * output digest.
+ *
+ * ⚠️ LAST AND DEFAULTED, so every existing caller and fixture is untouched and
+ * an empty list is byte-identical to the old behaviour.
+ */
+carry?: readonly string[]): Promise<string>;
+/**
+ * 🔴 THE PART OF A REAP REFUSAL THAT NEVER CHANGES, ASKED ON ITS OWN.
+ *
+ * `looply runs` counted the orphans `--reap` could take by `record.worktree`,
+ * which does not mean "a checkout looply made". It means "not the main
+ * checkout" — and it is TRUE for a worktree a PERSON made and pointed `--in`
+ * at. So a crashed `--in` run was announced as "in a checkout looply made",
+ * the person ran `--reap`, and `--reap` refused it. Correctly, permanently,
+ * and once a day for ever.
+ *
+ * ⚠️ LIVENESS IS DELIBERATELY NOT ASKED HERE. That answer changes between the
+ * listing and the reap; this one does not. `reapVerdict` calls this, so the
+ * count in the summary and the refusal that follows it cannot drift apart
+ * again — there is one test, not two spellings of nearly the same one.
+ */
+export declare function reapableCheckout(record: RunRecord, cwd: string, 
+/** Whose home the workspaces root lives under; the user's unless a caller says otherwise (M4-4). */
+home?: string): {
+    ok: true;
+} | {
+    ok: false;
+    because: string;
+};
+export declare function reapVerdict(record: RunRecord, cwd: string, probe?: ProbeFn, home?: string): {
+    ok: true;
+} | {
+    ok: false;
+    because: string;
+};
+/**
+ * Remove a proven-dead workspace, worktree record and registry entry.
+ *
+ * ⚠️ `git worktree remove` WITHOUT `--force`, then nothing. If git refuses —
+ * because the tree is dirty, or a file is held — the directory is LEFT and the
+ * refusal is returned. `--force` deletes ignored files, which is how a reaper
+ * would take somebody's `node_modules` or `.env` with it, and it fires exactly
+ * when git has already judged there is something worth refusing over.
+ */
+/**
+ * Everything in a workspace that is not a pristine checkout — INCLUDING ignored
+ * files, which is the whole reason this exists.
+ *
+ * ⚠️ THE DRIVER MUST BE BUILT FOR THE WORKSPACE, not for the main checkout.
+ * `trustedGitEnv` pins GIT_DIR and GIT_WORK_TREE from the cwd a driver was made
+ * with, and a pinned work tree beats `-C` — so a main-checkout driver asked
+ * about a workspace answers about the main checkout, confidently and wrongly.
+ *
+ * A failure to ask counts AS residue: a reaper that cannot see what is there
+ * must not delete it.
+ */
+export declare function workspaceResidue(gitInWorkspace: GitDriver, workspace: string, 
+/**
+ * `run.carry_into_checkouts` — paths LOOPLY PUT HERE ITSELF, and therefore not
+ * the person's.
+ *
+ * 🔴 WITHOUT THIS, PROVISIONING A WORKSPACE MAKES IT UNREAPABLE FOR EVER.
+ * `--ignored` is the whole point of this check, and a carried `node_modules`
+ * is ignored by definition — so the reaper counted the product's own copy as
+ * "file(s) nothing else has a copy of" and refused. Measured immediately after
+ * the carry landed: SIX workspaces, every one kept, each naming
+ * `!! node_modules/` as the person's content.
+ *
+ * The reasoning is the same one that drops `.looply/state/` two lines below:
+ * this is looply's own, it was copied from a source that still has it, and
+ * deleting it loses nothing. It is a COPY — that is the whole contract of
+ * `carryIntoCheckout` — so "nothing else has a copy of it" is exactly false.
+ *
+ * ⚠️ TOP-LEVEL NAMES ONLY, matching what `carryNameTrouble` permits. A path
+ * deeper than one segment is not carriable, so it cannot be excused here.
+ */
+carried?: readonly string[]): Promise<string[]>;
+/**
+ * Move a dead execution's own state out of the workspace, so removing the
+ * checkout does not take the evidence with it.
+ *
+ * ⚠️ MOVED, NEVER DELETED, and the reap stops if this fails. A crashed run's
+ * ledger is the only account of why it crashed; a reaper that removes the
+ * checkout and loses it has destroyed the one thing somebody would come looking
+ * for. It lands in the PROJECT's state directory, which outlives every workspace.
+ *
+ * ⚠️ AND IT NEVER OVERWRITES. A second reap of the same runId — which can only
+ * happen if the first was interrupted — lands beside the first, not on it.
+ */
+export declare function retainEvidence(record: Pick<RunRecord, 'runId' | 'workspace'>, cwd: string): {
+    ok: true;
+    at: string | null;
+} | {
+    ok: false;
+    because: string;
+};
+export declare function reapWorkspace(git: GitDriver, registry: RunRegistry, record: RunRecord, cwd: string, probe?: ProbeFn, 
+/** A driver bound to the given checkout. See `workspaceResidue`. */
+gitInWorkspace?: (dir: string) => GitDriver, home?: string, 
+/**
+ * `run.carry_into_checkouts` - paths looply provisioned into the checkout
+ * itself. Passed through to `workspaceResidue`, which explains why.
+ */
+carried?: readonly string[]): Promise<{
+    reaped: boolean;
+    because?: string;
+    evidenceAt?: string;
+}>;
+/**
+ * Workspaces on disk that no live execution and no registry record account for.
+ *
+ * 🔴 THE LIFECYCLE HAD A THIRD HOLE, and I found this one by using the command I
+ * had just written. `looply run --new-workspace` cuts the checkout BEFORE the
+ * run registers, so anything that ends the run in between — a config error, a
+ * dirty tree, `--dry-run`, a crash — leaves a real worktree that `looply runs`
+ * cannot see and `--reap` cannot reach, because both work from registry records
+ * and there is none. They accumulate silently, one per failed start.
+ *
+ * ⚠️ ABSENCE OF A RECORD IS NOT ENOUGH TO CALL ONE ABANDONED. A run that has
+ * created its workspace and not yet registered is in exactly that state for a
+ * few hundred milliseconds. So the LEASE is the second witness, as it is for a
+ * slot: a workspace whose own execution state holds a lease naming a process
+ * that is not proven dead is left alone.
+ *
+ * ⚠️ AND IT LOOKS ONLY UNDER THE WORKSPACES ROOT — never at a `--in` checkout,
+ * which is the person's and which nothing here may ever remove.
+ */
+export declare function abandonedWorkspaces(cwd: string, registry: RunRegistry, probe?: ProbeFn, home?: string): {
+    abandoned: string[];
+    busy: string[];
+};
+export declare function checkoutBusy(stateDir: string, probe?: ProbeFn): boolean;
+/** Whose start marker a workspace carries, so a person can be warned before clearing it. */
+export declare function creationMarkerHolder(cwd: string, name: string, probe?: ProbeFn): {
+    pid: number;
+    liveness: Liveness;
+} | null;
+/**
+ * Drop the creation marker — the LAST thing a run does, and only then.
+ *
+ * 🔴 THE TIMING IS THE WHOLE DESIGN, and both extremes were shipped and wrong.
+ *
+ * Cleared EARLY (the moment the run had its lease and record) it reopened the
+ * window it exists to close: `releaseHold` gives the lease and the record back
+ * at the TOP of the teardown, with work still to do below it, so a concurrent
+ * `--reap` saw no lease, no record and no marker while the run was still
+ * writing.
+ *
+ * NEVER cleared, it becomes a permanent pid-shaped claim on a finished
+ * checkout: once that pid is recycled the workspace reads as busy for ever,
+ * invisible to `--reap`, with nothing a person could point at.
+ *
+ * So: last, after everything else the run does.
+ */
+export declare function clearCreationMarker(stateDir: string): void;
+/**
+ * Drop this run's addressed control file, once the run is over.
+ *
+ * ⚠️ NOT REQUIRED FOR CORRECTNESS EITHER — it is named for a runId that will
+ * never exist again, so nothing can ever read it. It is cleared because
+ * otherwise `looply stop` leaves one behind per stopped run, for ever, in a
+ * directory that never had them: an ordinary Simple Mode checkout would
+ * accumulate a `control.<runId>.json` every time a person pressed stop.
+ *
+ * ⚠️ AND AT TEARDOWN, NOT AT CONSUME. Between consuming a stop and actually
+ * ending, a run is still running and a second stop is still a thing a person
+ * may send it.
+ */
+export declare function clearAddressedControl(stateDir: string, runId: string): void;
+/**
+ * Retire a workspace that no record accounts for.
+ *
+ * Everything the record-based reap checks, minus the record: containment on the
+ * real path, residue, evidence retention, and `worktree remove` without
+ * `--force`. A person's `--in` checkout can never reach this — it is not under
+ * the workspaces root, which is checked first and by realpath.
+ */
+export declare function reapAbandoned(git: GitDriver, cwd: string, path: string, probe?: ProbeFn, gitInWorkspace?: (dir: string) => GitDriver, home?: string, 
+/**
+ * `run.carry_into_checkouts` - paths looply provisioned into the checkout
+ * itself. Passed through to `workspaceResidue`, which explains why.
+ */
+carried?: readonly string[]): Promise<{
+    reaped: boolean;
+    because?: string;
+}>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

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