looply-cli 0.0.0-stage → 0.3.0

package/dist/stale-run-sweep.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sweepTargets = sweepTargets;
+exports.makeStaleRunSweep = makeStaleRunSweep;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const daemon_recovery_1 = require("./daemon-recovery");
+const git_driver_1 = require("./git-driver");
+const ledger_store_1 = require("./ledger-store");
+const run_lease_1 = require("./run-lease");
+const trusted_git_1 = require("./trusted-git");
+const workspace_1 = require("./workspace");
+const workspace_quarantine_1 = require("./workspace-quarantine");
+/**
+ * The checkouts a sweep of this project covers, in a deterministic order: the
+ * main checkout first, then the workspaces by name.
+ */
+function sweepTargets(cwd, home = (0, node_os_1.homedir)()) {
+    const seen = new Set();
+    const out = [];
+    const add = (path) => {
+        let key;
+        try {
+            key = node_fs_1.realpathSync.native(path);
+        }
+        catch {
+            return; // gone between the listing and here; nothing to sweep
+        }
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(path);
+    };
+    add((0, node_path_1.resolve)(cwd));
+    const root = (0, workspace_1.workspacesRoot)(cwd, home);
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(root).sort();
+    }
+    catch {
+        return out;
+    }
+    const identity = (0, trusted_git_1.repoIdentityPath)(cwd);
+    for (const name of names) {
+        const path = (0, node_path_1.join)(root, name);
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(path, git_driver_1.STATE_DIR)))
+            continue;
+        if ((0, workspace_quarantine_1.quarantineOf)(cwd, path) !== null)
+            continue;
+        if ((0, trusted_git_1.repoIdentityPath)(path) !== identity)
+            continue;
+        add(path);
+    }
+    return out;
+}
+/**
+ * The daemon's `recoverStaleRun` dependency. ONE factory for the daemon and the
+ * end-to-end proof, so the proof sweeps with the sweep the daemon runs.
+ */
+function makeStaleRunSweep(deps) {
+    const home = deps.home ?? (0, node_os_1.homedir)();
+    const now = deps.now ?? (() => Date.now());
+    return async () => {
+        const swept = [];
+        for (const checkout of sweepTargets(deps.cwd, home)) {
+            const stateDir = (0, git_driver_1.executionStateDir)(checkout);
+            try {
+                const outcome = await (0, daemon_recovery_1.recoverStaleRunOnStartup)({
+                    leases: new run_lease_1.RunLeaseStore(stateDir, run_lease_1.nodeLeaseFs, deps.probe),
+                    git: new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(checkout)),
+                    ledger: new ledger_store_1.LedgerStore(stateDir, ledger_store_1.nodeLedgerFs),
+                    ledgerStateDir: stateDir,
+                    ledgerFs: ledger_store_1.nodeLedgerFs,
+                    projectId: deps.projectId,
+                    now,
+                    log: deps.log,
+                });
+                swept.push({ checkout, outcome });
+            }
+            catch (e) {
+                const because = e.message;
+                deps.log(`recover : could not check ${checkout} for a dead run (${because})`);
+                swept.push({ checkout, outcome: { kind: 'failed', because } });
+            }
+        }
+        /**
+         * M5-5: THE RECORD THAT LINGERS. A registered run whose process is PROVEN
+         * dead and whose checkout is gone — the reaper removed it (M4-4), or a
+         * person did — kept its record and its slot until `looply runs --release`
+         * (STATE §5 item 15; measured after the managed harness: one). Nothing can
+         * still be running there, so the record is released and the slot freed.
+         * A live record, a record the pid cannot be judged for, or one whose
+         * checkout still stands is left exactly alone — those are the reaper's and
+         * the person's to decide.
+         */
+        try {
+            const registry = new workspace_1.RunRegistry((0, git_driver_1.projectStateDir)(deps.cwd), deps.probe);
+            for (const entry of registry.list()) {
+                if (entry.kind !== 'orphaned')
+                    continue;
+                if ((0, node_fs_1.existsSync)(entry.record.workspace))
+                    continue;
+                const because = `its process is gone and so is its checkout ${entry.record.workspace}`;
+                const out = registry.forget(entry.record.runId);
+                deps.log(`recover : released the record of run ${entry.record.runId} — ${because}${out.slot === null ? '' : ` (slot ${out.slot} freed)`}`);
+                swept.push({ checkout: entry.record.workspace, outcome: { kind: 'released', runId: entry.record.runId, because } });
+            }
+        }
+        catch (e) {
+            deps.log(`recover : could not read the run registry (${e.message})`);
+        }
+        return swept;
+    };
+}
+//# sourceMappingURL=stale-run-sweep.js.map

package/dist/stale-run-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-run-sweep.js","sourceRoot":"","sources":["../src/stale-run-sweep.ts"],"names":[],"mappings":";;AA6EA,oCAgCC;AAMD,8CAkDC;AArKD,qCAAgE;AAChE,qCAAkC;AAClC,yCAA0C;AAC1C,uDAAmF;AACnF,6CAAqG;AACrG,iDAA2D;AAC3D,2CAAuE;AACvE,+CAAiD;AACjD,2CAA0D;AAC1D,iEAAsD;AAgEtD;;;GAGG;AACH,SAAgB,YAAY,CAAC,GAAW,EAAE,OAAe,IAAA,iBAAO,GAAE;IAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,GAAG,GAAG,CAAC,IAAY,EAAQ,EAAE;QACjC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,sBAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,sDAAsD;QAChE,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,CAAC;IACF,GAAG,CAAC,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC,CAAC;IAElB,MAAM,IAAI,GAAG,IAAA,0BAAc,EAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACvC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,IAAA,qBAAW,EAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,IAAA,8BAAgB,EAAC,GAAG,CAAC,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAA,oBAAU,EAAC,IAAA,gBAAI,EAAC,IAAI,EAAE,sBAAS,CAAC,CAAC;YAAE,SAAS;QACjD,IAAI,IAAA,mCAAY,EAAC,GAAG,EAAE,IAAI,CAAC,KAAK,IAAI;YAAE,SAAS;QAC/C,IAAI,IAAA,8BAAgB,EAAC,IAAI,CAAC,KAAK,QAAQ;YAAE,SAAS;QAClD,GAAG,CAAC,IAAI,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,IAAuB;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAA,iBAAO,GAAE,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,OAAO,KAAK,IAA8B,EAAE;QAC1C,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;YACpD,MAAM,QAAQ,GAAG,IAAA,8BAAiB,EAAC,QAAQ,CAAC,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,IAAA,0CAAwB,EAAC;oBAC7C,MAAM,EAAE,IAAI,yBAAa,CAAC,QAAQ,EAAE,uBAAW,EAAE,IAAI,CAAC,KAAK,CAAC;oBAC5D,GAAG,EAAE,IAAI,sBAAS,CAAC,IAAA,wBAAW,EAAC,QAAQ,CAAC,CAAC;oBACzC,MAAM,EAAE,IAAI,0BAAW,CAAC,QAAQ,EAAE,2BAAY,CAAC;oBAC/C,cAAc,EAAE,QAAQ;oBACxB,QAAQ,EAAE,2BAAY;oBACtB,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,GAAG;oBACH,GAAG,EAAE,IAAI,CAAC,GAAG;iBACd,CAAC,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,OAAO,GAAI,CAAW,CAAC,OAAO,CAAC;gBACrC,IAAI,CAAC,GAAG,CAAC,6BAA6B,QAAQ,oBAAoB,OAAO,GAAG,CAAC,CAAC;gBAC9E,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;QACD;;;;;;;;;WASG;QACH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,uBAAW,CAAC,IAAA,4BAAe,EAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACxE,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;oBAAE,SAAS;gBACxC,IAAI,IAAA,oBAAU,EAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC;oBAAE,SAAS;gBACjD,MAAM,OAAO,GAAG,8CAA8C,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACvF,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAChD,IAAI,CAAC,GAAG,CAAC,wCAAwC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC;gBAC3I,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YACtH,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,CAAC,8CAA+C,CAAW,CAAC,OAAO,GAAG,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/start-attempts.d.ts

@@ -0,0 +1,385 @@
+import { type RunRefusalCode } from '@looply/core';
+import { type Liveness, type ProbeFn } from './run-lease';
+import { type LedgerFs } from './ledger-store';
+/**
+ * ONE ATTEMPT TO EXECUTE ONE BOUNDED START.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TWO FACTS, NOT ONE
+ *
+ * A grant's ordinal receipt (autonomy-store.ts) says one thing and must go on
+ * saying only that: CONTROLLER C HAS PERMANENTLY SPENT START SLOT N. It is
+ * immutable, it is the budget, and nothing that goes wrong afterwards refunds
+ * it.
+ *
+ * This file records something different: ONE PROCESS HAS ATTEMPTED TO EXECUTE
+ * REQUEST S. A process can claim an attempt and die without ever reaching a
+ * Run, and that must be recoverable — otherwise a machine that crashed in the
+ * wrong second would burn a person's whole night one ordinal at a time.
+ *
+ * Conflating the two is what makes a controller wedge. If "the ordinal is
+ * reserved" also means "a Start is in flight", then a reservation followed by a
+ * crash is a Start that is in flight forever, against a process that does not
+ * exist, and nothing can ever move.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE REQUEST ID NEVER CHANGES
+ *
+ * Attempts 1, 2 and 3 of ordinal N all carry the SAME requestId. They are not
+ * three Starts; they are three tries at establishing one Start, and every
+ * durable fact about it — the lease, the start mark, the refusal mark — is
+ * filed under that one id. A retry that minted a new id would be a second
+ * Start wearing a disguise, and the budget would be a lie.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE CHILD CLAIMS, NOT THE DAEMON
+ *
+ * The claim is made by the process that could actually go on to do the work,
+ * immediately before it does. That is deliberate and it is the whole reason
+ * this is safe.
+ *
+ * A daemon that claimed before spawning would be recording the identity of a
+ * process that is NOT the executor: children here are detached and outlive
+ * their parent, so a dead daemon proves nothing about whether the run it
+ * launched is still going. The claimant would be a corpse and the executor
+ * would still be compiling. By having the child write its own pid, the durable
+ * claimant IS the process whose liveness decides whether a retry is safe.
+ */
+/** Bumped only when the on-disk shape changes incompatibly. Read, not decorative. */
+export declare const START_ATTEMPTS_SCHEMA = 1;
+/**
+ * How many times one Start request may be attempted.
+ *
+ * Three, matching `MAX_ITEM_EXECUTION_ATTEMPTS` — the repository's existing
+ * answer to "how many times may one thing be tried before we stop and say so".
+ *
+ * It needs its own bound rather than borrowing one. A HUMAN Start is bounded by
+ * the server's one-hour redelivery window: `pop` marks anything un-acked and
+ * older than that `expired`, and stops offering it. An autonomous Start has no
+ * server row, so it inherits none of that — the only ceiling it would otherwise
+ * have is the grant's 24-hour lifetime, which at a ten-second cadence is more
+ * than eight thousand attempts at a request that has failed the same way every
+ * time.
+ */
+export declare const MAX_START_REQUEST_ATTEMPTS = 3;
+/**
+ * The deterministic name of one attempt.
+ *
+ * Derived, never minted, for the same reason `autonomyStartId` is: two daemons
+ * that independently conclude attempt 2 of request S is due must compute the
+ * same name, so that the filesystem can tell them apart instead of both
+ * believing they own it.
+ */
+export declare function startAttemptId(requestId: string, attempt: number): string;
+/** What a claimant says about itself. Written once, never rewritten. */
+export interface StartAttemptClaim {
+    requestId: string;
+    attempt: number;
+    /**
+     * Distinguishes this claimant from a later process that reuses the pid.
+     *
+     * The same three fields the run lease records, and for the same reason: a
+     * pid on its own is not an identity, because the operating system hands
+     * numbers out again. `RunLeaseStore` already learned this; nothing here
+     * invents a second convention.
+     */
+    token: string;
+    pid: number;
+    host: string;
+    claimedAt: string;
+}
+/**
+ * A DAEMON SAYING IT IS ABOUT TO SPAWN. The retry budget, and nothing else.
+ *
+ * The claim beside it is written by the CHILD, at the admission seam, and that
+ * is right: the child is the process whose liveness decides whether work is
+ * still happening. But a receipt written by the child can only count children
+ * that GOT there, and a launch that dies first — a missing binary, an argv the
+ * CLI rejects, EPERM on the state directory, a partial upgrade — leaves nothing
+ * behind at all.
+ *
+ * So the bound counted admissions and the failure mode never produced one. A
+ * certification pass measured it: five hundred ticks, five hundred spawns,
+ * every one of them calling itself attempt 1, `MAX_START_REQUEST_ATTEMPTS`
+ * never once consulted with anything to consult it about. The only ceiling was
+ * the grant's own 24 hours, at eight thousand spawns.
+ *
+ * Two different facts, so two different artifacts:
+ *
+ *   LAUNCH   a daemon spent one of three tries. Written BEFORE the spawn,
+ *            because a budget consumed after the risky act is not a budget.
+ *   CLAIM    a child crossed the admission seam. Written by that child.
+ *
+ * Neither pretends to be the other.
+ */
+export interface StartLaunch {
+    requestId: string;
+    attempt: number;
+    /**
+     * The daemon that reserved this try, so a successor can tell "somebody is
+     * spawning right now" from "somebody died mid-spawn". Same three fields as a
+     * claim, and for the same reason: a pid alone is not an identity.
+     */
+    token: string;
+    pid: number;
+    host: string;
+    at: string;
+}
+/**
+ * WHETHER A CHILD ACTUALLY CAME INTO EXISTENCE, recorded by the daemon that
+ * asked for one.
+ *
+ * Without it, a launch with no claim is unreadable: it could be a spawn that
+ * failed outright, a child that died before its first write, or a child that is
+ * about to claim a millisecond from now. Guessing "dead" would start a second
+ * executor on an assumption — the failure 6D2B exists to prevent. Guessing
+ * "alive" would stall a grant on a spawn that never happened.
+ *
+ * So the daemon writes down what the launcher told it, the moment it is told.
+ */
+export interface StartSpawn {
+    requestId: string;
+    attempt: number;
+    /** False when the launcher could not produce a child at all. */
+    spawned: boolean;
+    /** The child's pid when there is one and the platform reported it. */
+    pid?: number;
+    host: string;
+    at: string;
+}
+/**
+ * Where one request's attempts live.
+ *
+ * A directory per request, beside nothing else. Deliberately NOT a field on
+ * any of the whole-file JSON stores this state directory already holds: each of
+ * those is rewritten entire by writers that hold no lease, so attempt history
+ * filed there would be erased by a process that never knew it existed.
+ *
+ * The directory name is derived rather than used raw. A request id contains
+ * colons (`controller-start:aut_1:3`) and a colon cannot appear in a Windows
+ * filename, so the readable part is sanitised and an eight-hex digest of the
+ * WHOLE id is appended — readable enough to debug by eye, and unique because
+ * the digest is over the original.
+ */
+export declare function attemptDirName(requestId: string): string;
+export type ClaimOutcome = {
+    ok: true;
+    claim: StartAttemptClaim;
+}
+/** Somebody else owns this exact attempt. NOT a statement about the goal. */
+ | {
+    ok: false;
+    because: string;
+};
+/**
+ * WHAT HAS BEEN TRIED, AND WHETHER ANOTHER TRY IS ALLOWED.
+ *
+ * One authority, read by the daemon side and by every test. A second derivation
+ * living somewhere else is how two halves of a system come to disagree about
+ * whether a Start already happened.
+ */
+export type AttemptProgress = 
+/** Nothing has been tried. Attempt 1 may be claimed. */
+{
+    kind: 'none';
+    nextAttempt: 1;
+}
+/**
+ * The latest claimant may still be working.
+ *
+ * Covers `alive` AND `unknown`, and the second is the point: a pid this
+ * process cannot probe is not evidence of death, and starting a second
+ * executor on a guess is the failure the whole file exists to prevent.
+ */
+ | {
+    kind: 'active';
+    attempt: number;
+    liveness: Liveness;
+    claim: StartAttemptClaim;
+}
+/** The latest claimant is PROVEN dead and the budget has room. */
+ | {
+    kind: 'retryable';
+    nextAttempt: number;
+    deadAttempt: number;
+}
+/** A Run demonstrably began for this request. Irreversible. */
+ | {
+    kind: 'run-started';
+    runId: string;
+}
+/** The run itself decided. Irreversible. */
+ | {
+    kind: 'refused';
+    code: RunRefusalCode;
+    reason: string;
+}
+/** Every permitted attempt has been spent without a durable outcome. */
+ | {
+    kind: 'exhausted';
+    attempts: number;
+}
+/** The record cannot be trusted. Never guessed around. */
+ | {
+    kind: 'corrupt';
+    because: string;
+}
+/**
+ * The record could not be READ this instant. Not the same thing at all.
+ *
+ * `corrupt` is durable damage: the bytes are wrong and reading them again
+ * reaches the same conclusion, so the only honest end is to stop and ask a
+ * person. This is weather — an antivirus scanner or the search indexer
+ * holding a handle for a few milliseconds, which on Windows is ordinary.
+ *
+ * Collapsing the two ended a person's pursuit over a file lock that cleared
+ * before they read the message.
+ */
+ | {
+    kind: 'unreadable';
+    because: string;
+};
+/** What `attemptProgress` needs to know that is not its own business to read. */
+export interface RequestOutcomes {
+    /** The start mark for this request, if a Run demonstrably began. */
+    startedRun: {
+        runId: string;
+    } | null;
+    /** The refusal mark for this request, if the run decided against one. */
+    refusal: {
+        reason: string;
+        code?: RunRefusalCode;
+    } | null;
+    /**
+     * Whether the ordinal this request spends is still reserved.
+     *
+     * An attempt with no reservation behind it is a contradiction — the budget
+     * says nothing was spent while the attempt history says something was tried —
+     * and a contradiction is not something to pick a side of.
+     */
+    ordinalReserved: boolean;
+}
+export declare class StartAttempts {
+    private readonly stateDir;
+    private readonly fs;
+    private readonly probe;
+    private readonly deps;
+    constructor(stateDir: string, fs: AttemptFs, probe?: ProbeFn, deps?: {
+        now?: () => number;
+        pid?: () => number;
+        host?: () => string;
+        token?: () => string;
+    });
+    private dir;
+    private path;
+    /** The daemon's "I am spending a try" receipt. Beside the claim, never instead of it. */
+    private launchPath;
+    /** What the launcher reported: a child, or no child. */
+    private spawnPath;
+    /**
+     * SPEND ONE OF THE THREE TRIES, before anything is spawned.
+     *
+     * Exclusive, like every other budget fact here, so two daemons that both
+     * decide attempt N is due cannot both take it. The loser is told, and does
+     * not spawn.
+     *
+     * Deliberately written BEFORE the launcher is called. A try recorded
+     * afterwards is not recorded at all for precisely the failures that need
+     * bounding — the ones where nothing comes back.
+     */
+    reserveLaunch(requestId: string, attempt: number): Promise<{
+        ok: true;
+        launch: StartLaunch;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+    /**
+     * Record what the launcher answered. Idempotent on the same answer.
+     *
+     * A second, DIFFERENT answer for one launch is two processes disagreeing
+     * about whether a child exists, which is not something to overwrite.
+     */
+    noteSpawn(requestId: string, attempt: number, outcome: {
+        spawned: boolean;
+        pid?: number;
+    }): Promise<void>;
+    /**
+     * Every try spent on this request, lowest first, and what became of each.
+     *
+     * A hole is refused here for the same reason it is refused among the ordinal
+     * receipts: launches are taken in order, so a gap means one was removed, and
+     * a removed launch is a retry budget quietly topped up.
+     */
+    launches(requestId: string): Promise<{
+        ok: true;
+        launches: {
+            launch: StartLaunch;
+            spawn: StartSpawn | null;
+        }[];
+    } | {
+        ok: false;
+        transient: boolean;
+        because: string;
+    }>;
+    /**
+     * Take attempt N of this request, or lose it.
+     *
+     * Exclusive create and nothing else — no read, no check, no "does it exist".
+     * The operating system hands the file to exactly one caller, and the loser
+     * finds out from the filesystem rather than from a stale read of its own.
+     *
+     * There is deliberately NO takeover path. If the claimant of attempt 1 is
+     * dead, the answer is attempt 2, not attempt 1 again: an attempt receipt is a
+     * historical fact and rewriting one would both lose the history that bounds
+     * the retries and reopen the dead-lease race class this repository already
+     * closed once.
+     */
+    claim(requestId: string, attempt: number): Promise<ClaimOutcome>;
+    /** Every claim on record for this request, lowest attempt first. */
+    claims(requestId: string): Promise<{
+        ok: true;
+        claims: StartAttemptClaim[];
+    } | {
+        ok: false;
+        transient: boolean;
+        because: string;
+    }>;
+    /**
+     * What has become of this request, as something that must DECIDE reads it.
+     *
+     * The order of the questions is the safety argument, and it is not
+     * negotiable:
+     *
+     *   A Run that demonstrably began outranks everything. Once `run.started` is
+     *   durable no further attempt may ever be made, whatever the attempt history
+     *   says and whichever process died — the work is happening, or it happened.
+     *
+     *   A refusal the run itself made outranks the attempt history too. The run
+     *   reached a decision; trying again would ask the same question of the same
+     *   repository and get the same answer.
+     *
+     *   Only then does whether anybody is still working matter.
+     */
+    progress(requestId: string, outcomes: RequestOutcomes): Promise<AttemptProgress>;
+    /**
+     * Whether the process that made this claim is still about.
+     *
+     * A claim made on another machine is `unknown`, never `dead`: a pid means
+     * nothing off the host that issued it, and probing a local pid that happens
+     * to match somebody else's would be reading a stranger's process as evidence
+     * about ours.
+     */
+    private livenessOf;
+}
+/** The filesystem this store needs. `createExclusive` is the whole argument. */
+export interface AttemptFs extends LedgerFs {
+    /** Create only if absent. MUST reject with an `EEXIST` error when it is not. */
+    createExclusive(path: string, data: string): Promise<void>;
+}
+export declare const nodeAttemptFs: AttemptFs;
+/** Narrow a refusal mark's code without trusting it. */
+export declare function codeOf(mark: {
+    code?: unknown;
+} | null): RunRefusalCode | undefined;
+//# sourceMappingURL=start-attempts.d.ts.map

package/dist/start-attempts.d.ts.map

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