looply-cli 0.0.0-stage → 0.3.0

package/dist/checkout-carry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WHAT A FRESH CHECKOUT NEEDS THAT GIT DOES NOT CARRY.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE PRODUCT MAKES CHECKOUTS AND THEN GATES THEM, AND THEY HAD NO
+ * DEPENDENCIES.
+ *
+ * Two places create a checkout and immediately run the project's own gate in it:
+ *
+ *   workspace.ts            a second worker's tree (`run --new-workspace`)
+ *   integration-runtime.ts  the throwaway tree a candidate is checked in
+ *
+ * Both are `git worktree add`, so both contain exactly what git tracks — and
+ * `node_modules` is gitignored in every JavaScript project there has ever been.
+ * The contained gate runs with `network: 'none'` BY DESIGN, so it cannot install
+ * them either. The result is a gate that cannot pass for any project with a
+ * dependency, in a checkout the product made for the purpose of gating.
+ *
+ * MEASURED, on a TypeScript project whose gate is `tsc` + `node --test`:
+ * two workers, four rounds each, every round red on `tsc` with the SAME output
+ * digest (38faf4ea), 95–106 s per attempt; and the integration lane refusing
+ * both finished branches with "2 required check(s) failed against the
+ * candidate: tsc, test" — while the identical commit passed 8/8 in a checkout
+ * that happened to have `node_modules` in it.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY A DECLARED LIST, AND NOT A CLEVERER ANSWER.
+ *
+ * `npm ci` is the obvious thought and it is wrong here twice: it needs the
+ * network the gate deliberately does not have, and it assumes a package manager
+ * this product does not otherwise care about. Guessing `node_modules` is wrong
+ * for a different reason — it is a guess, and a product that silently copies
+ * directories a person did not name is a product nobody can predict.
+ *
+ * So the person names them, in `run.carry_into_checkouts`, and absent means
+ * absent: an empty list copies nothing and every existing project behaves
+ * exactly as it did.
+ *
+ * ⚠️ A COPY, NEVER A LINK. A junction would be faster and is the one thing this
+ * must not do: both call sites DELETE their checkout when they are finished —
+ * `removeWorktree` then `rmSync(recursive)` — and a recursive delete walks a
+ * junction into the real directory behind it. The cost of getting that wrong is
+ * the project's own `node_modules`, and it is paid silently.
+ */
+export declare class CarryError extends Error {
+}
+/**
+ * Names this will carry, and the rule is deliberately narrow: one plain
+ * top-level directory name, nothing else.
+ *
+ * ⚠️ NO SEPARATORS, NO `..`, NO ABSOLUTE PATHS, NO DOT NAMES. A carry list is
+ * read from `.looply/config.yaml`, which lives inside the worktree the model may
+ * edit. `..` or `C:\` would turn a convenience into a copy of somewhere else
+ * entirely, and a dot name would let `.git` or `.looply` be overwritten in the
+ * new checkout — the two directories whose contents decide what git executes
+ * and what the run believes about itself.
+ */
+export declare function carryNameTrouble(name: string): string | null;
+export interface CarryResult {
+    readonly carried: readonly string[];
+    /** Named but not present in the project. Not an error: a project may not have built yet. */
+    readonly absent: readonly string[];
+}
+/**
+ * Copy each named directory from the project into a checkout the product made.
+ *
+ * ⚠️ NEVER OVERWRITES. If the checkout already has the name — because somebody
+ * tracked it, or a previous carry ran — it is left exactly as it is. The tracked
+ * tree is what git says it is, and this must not quietly replace part of it.
+ *
+ * ⚠️ AND A FAILED CARRY IS A THROW, NOT A SHRUG. A checkout half-provisioned is
+ * a gate that fails for a reason nobody can see; the caller turns this into a
+ * refusal that names the directory.
+ */
+export declare function carryIntoCheckout(projectRoot: string, checkoutDir: string, names: readonly string[]): CarryResult;
+//# sourceMappingURL=checkout-carry.d.ts.map

package/dist/checkout-carry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-carry.d.ts","sourceRoot":"","sources":["../src/checkout-carry.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,WAAW,CAmCb"}

package/dist/checkout-carry.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarryError = void 0;
+exports.carryNameTrouble = carryNameTrouble;
+exports.carryIntoCheckout = carryIntoCheckout;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * WHAT A FRESH CHECKOUT NEEDS THAT GIT DOES NOT CARRY.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE PRODUCT MAKES CHECKOUTS AND THEN GATES THEM, AND THEY HAD NO
+ * DEPENDENCIES.
+ *
+ * Two places create a checkout and immediately run the project's own gate in it:
+ *
+ *   workspace.ts            a second worker's tree (`run --new-workspace`)
+ *   integration-runtime.ts  the throwaway tree a candidate is checked in
+ *
+ * Both are `git worktree add`, so both contain exactly what git tracks — and
+ * `node_modules` is gitignored in every JavaScript project there has ever been.
+ * The contained gate runs with `network: 'none'` BY DESIGN, so it cannot install
+ * them either. The result is a gate that cannot pass for any project with a
+ * dependency, in a checkout the product made for the purpose of gating.
+ *
+ * MEASURED, on a TypeScript project whose gate is `tsc` + `node --test`:
+ * two workers, four rounds each, every round red on `tsc` with the SAME output
+ * digest (38faf4ea), 95–106 s per attempt; and the integration lane refusing
+ * both finished branches with "2 required check(s) failed against the
+ * candidate: tsc, test" — while the identical commit passed 8/8 in a checkout
+ * that happened to have `node_modules` in it.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY A DECLARED LIST, AND NOT A CLEVERER ANSWER.
+ *
+ * `npm ci` is the obvious thought and it is wrong here twice: it needs the
+ * network the gate deliberately does not have, and it assumes a package manager
+ * this product does not otherwise care about. Guessing `node_modules` is wrong
+ * for a different reason — it is a guess, and a product that silently copies
+ * directories a person did not name is a product nobody can predict.
+ *
+ * So the person names them, in `run.carry_into_checkouts`, and absent means
+ * absent: an empty list copies nothing and every existing project behaves
+ * exactly as it did.
+ *
+ * ⚠️ A COPY, NEVER A LINK. A junction would be faster and is the one thing this
+ * must not do: both call sites DELETE their checkout when they are finished —
+ * `removeWorktree` then `rmSync(recursive)` — and a recursive delete walks a
+ * junction into the real directory behind it. The cost of getting that wrong is
+ * the project's own `node_modules`, and it is paid silently.
+ */
+class CarryError extends Error {
+}
+exports.CarryError = CarryError;
+/**
+ * Names this will carry, and the rule is deliberately narrow: one plain
+ * top-level directory name, nothing else.
+ *
+ * ⚠️ NO SEPARATORS, NO `..`, NO ABSOLUTE PATHS, NO DOT NAMES. A carry list is
+ * read from `.looply/config.yaml`, which lives inside the worktree the model may
+ * edit. `..` or `C:\` would turn a convenience into a copy of somewhere else
+ * entirely, and a dot name would let `.git` or `.looply` be overwritten in the
+ * new checkout — the two directories whose contents decide what git executes
+ * and what the run believes about itself.
+ */
+function carryNameTrouble(name) {
+    if (name.length === 0)
+        return 'is empty';
+    if (name === '.' || name === '..')
+        return 'is a relative path, not a name';
+    if (/[\\/]/.test(name))
+        return 'contains a path separator — name one top-level directory';
+    if (name.startsWith('.'))
+        return 'starts with a dot — .git and .looply are not carriable';
+    if (/^[A-Za-z]:/.test(name))
+        return 'is an absolute path, not a name';
+    return null;
+}
+/**
+ * Copy each named directory from the project into a checkout the product made.
+ *
+ * ⚠️ NEVER OVERWRITES. If the checkout already has the name — because somebody
+ * tracked it, or a previous carry ran — it is left exactly as it is. The tracked
+ * tree is what git says it is, and this must not quietly replace part of it.
+ *
+ * ⚠️ AND A FAILED CARRY IS A THROW, NOT A SHRUG. A checkout half-provisioned is
+ * a gate that fails for a reason nobody can see; the caller turns this into a
+ * refusal that names the directory.
+ */
+function carryIntoCheckout(projectRoot, checkoutDir, names) {
+    const carried = [];
+    const absent = [];
+    for (const name of names) {
+        const trouble = carryNameTrouble(name);
+        if (trouble !== null) {
+            throw new CarryError(`run.carry_into_checkouts: "${name}" ${trouble}`);
+        }
+        const from = (0, node_path_1.join)(projectRoot, name);
+        const to = (0, node_path_1.join)(checkoutDir, name);
+        if (!(0, node_fs_1.existsSync)(from)) {
+            absent.push(name);
+            continue;
+        }
+        if ((0, node_fs_1.existsSync)(to))
+            continue;
+        /**
+         * 🔴 THE SOURCE MUST BE A REAL DIRECTORY. If the project's own
+         * `node_modules` is itself a junction — which is how some monorepos are laid
+         * out — copying THROUGH it is still a copy, but `dereference: false` would
+         * reproduce the link in a checkout that is about to be deleted recursively.
+         * That is the hazard this file exists to avoid, reached from the other side.
+         */
+        const st = (0, node_fs_1.lstatSync)(from);
+        if (st.isSymbolicLink()) {
+            throw new CarryError(`run.carry_into_checkouts: "${name}" is a link in this project, and copying a link into a checkout that is deleted recursively would delete what it points at`);
+        }
+        if (!st.isDirectory()) {
+            throw new CarryError(`run.carry_into_checkouts: "${name}" is not a directory`);
+        }
+        (0, node_fs_1.cpSync)(from, to, { recursive: true, dereference: false, errorOnExist: false, force: false });
+        carried.push(name);
+    }
+    return { carried, absent };
+}
+//# sourceMappingURL=checkout-carry.js.map

package/dist/checkout-carry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-carry.js","sourceRoot":"","sources":["../src/checkout-carry.ts"],"names":[],"mappings":";;;AA6DA,4CAOC;AAmBD,8CAuCC;AA9HD,qCAAwD;AACxD,yCAAiC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAa,UAAW,SAAQ,KAAK;CAAG;AAAxC,gCAAwC;AAExC;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IACzC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,gCAAgC,CAAC;IAC3E,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,0DAA0D,CAAC;IAC1F,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,wDAAwD,CAAC;IAC1F,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,iCAAiC,CAAC;IACtE,OAAO,IAAI,CAAC;AACd,CAAC;AAQD;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAC/B,WAAmB,EACnB,WAAmB,EACnB,KAAwB;IAExB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,UAAU,CAAC,8BAA8B,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACrC,MAAM,EAAE,GAAG,IAAA,gBAAI,EAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAA,oBAAU,EAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QACD,IAAI,IAAA,oBAAU,EAAC,EAAE,CAAC;YAAE,SAAS;QAC7B;;;;;;WAMG;QACH,MAAM,EAAE,GAAG,IAAA,mBAAS,EAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,UAAU,CAClB,8BAA8B,IAAI,4HAA4H,CAC/J,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,UAAU,CAAC,8BAA8B,IAAI,sBAAsB,CAAC,CAAC;QACjF,CAAC;QACD,IAAA,gBAAM,EAAC,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7F,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC"}

package/dist/citation-readers.d.ts

@@ -0,0 +1,26 @@
+import { type GitExec } from './git-driver';
+/**
+ * RE-READING WHAT A PROPOSAL OR A PLAN CITED — from the repository, git and
+ * the ledger.
+ *
+ * A proposal is not believed; it is checked. Each citation names something
+ * deterministic, and these readers fetch exactly that: a line of a file at the
+ * COMMITTED tree the question was asked at (not the working tree, which moves
+ * under a run), a file's presence there, the first line of it showing an
+ * excerpt, a commit by sha, a ledger event by sequence number, a gate step's
+ * last recorded result. `null` means "could not be read", which the judges
+ * treat as refuted — an unreadable citation is not a satisfied one.
+ */
+export interface CitationReaders {
+    /** `path:line <text>` at the tree, or null when the file or the line is not there. */
+    file(path: string, line: number, treeSha: string): Promise<string | null>;
+    /** `path <p> (<n> lines)` at the tree, or null when the file is not there. */
+    path(path: string, treeSha: string): Promise<string | null>;
+    /** `path:line <text>` of the first line showing the excerpt (whitespace aside), or null. */
+    find(path: string, excerpt: string, treeSha: string): Promise<string | null>;
+    commit(sha: string): Promise<string | null>;
+    event(seq: number): Promise<string | null>;
+    gate(step: string): Promise<string | null>;
+}
+export declare function nodeCitationReaders(cwd: string, stateDir: string, exec?: GitExec): CitationReaders;
+//# sourceMappingURL=citation-readers.d.ts.map

package/dist/citation-readers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-readers.d.ts","sourceRoot":"","sources":["../src/citation-readers.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1E,8EAA8E;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,4FAA4F;IAC5F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5C;AAmCD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,OAA0B,GAAG,eAAe,CAwDpH"}

package/dist/citation-readers.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeCitationReaders = nodeCitationReaders;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+const git_driver_1 = require("./git-driver");
+async function ledgerLines(stateDir) {
+    let text;
+    try {
+        text = await node_fs_1.promises.readFile((0, node_path_1.join)(stateDir, 'events.jsonl'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const v = JSON.parse(line);
+            if (v !== null && typeof v === 'object')
+                out.push(v);
+        }
+        catch {
+            /* a torn line is not an event */
+        }
+    }
+    return out;
+}
+const linesOf = (text) => {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+};
+function nodeCitationReaders(cwd, stateDir, exec = (0, git_driver_1.nodeGitExec)(cwd)) {
+    const git = new git_driver_1.GitDriver(exec);
+    /** The file's text at the committed tree, or null when it is not there. */
+    const blobAt = async (path, treeSha) => {
+        try {
+            const entry = (await git.listTree(treeSha)).find((e) => e.path === path);
+            return entry === undefined ? null : await git.readBlob(entry.blobSha);
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        async file(path, line, treeSha) {
+            const text = await blobAt(path, treeSha);
+            if (text === null || line < 1)
+                return null;
+            const found = text.split('\n')[line - 1];
+            return found === undefined ? null : `${path}:${line} ${found}`;
+        },
+        async path(path, treeSha) {
+            const text = await blobAt(path, treeSha);
+            if (text === null)
+                return null;
+            const n = linesOf(text).length;
+            return `path ${path} (${n} line${n === 1 ? '' : 's'})`;
+        },
+        async find(path, excerpt, treeSha) {
+            const q = (0, core_1.normaliseExcerpt)(excerpt);
+            if (q === '')
+                return null;
+            const text = await blobAt(path, treeSha);
+            if (text === null)
+                return null;
+            const lines = linesOf(text);
+            const i = lines.findIndex((l) => (0, core_1.normaliseExcerpt)(l).includes(q));
+            return i < 0 ? null : `${path}:${i + 1} ${lines[i]}`;
+        },
+        async commit(sha) {
+            const r = await exec(['log', '-1', '--format=%H %s', sha]);
+            const text = r.stdout.trim();
+            return r.code === 0 && text !== '' ? `commit ${text}` : null;
+        },
+        async event(seq) {
+            const hits = (await ledgerLines(stateDir)).filter((e) => e.seq === seq);
+            // A sequence number is per run; one that names two events is not a citation anybody can check.
+            if (hits.length !== 1)
+                return null;
+            const e = hits[0];
+            return `event ${seq} ${String(e.kind)} ${JSON.stringify(e.data ?? null)}`;
+        },
+        async gate(step) {
+            const gated = (await ledgerLines(stateDir)).filter((e) => e.kind === 'round.gated');
+            const last = gated[gated.length - 1];
+            if (last === undefined)
+                return null;
+            const data = (last.data ?? {});
+            const steps = (Array.isArray(data.steps) ? data.steps : Array.isArray(data.results) ? data.results : []);
+            const hit = steps.find((s) => s.step === step);
+            if (hit === undefined)
+                return null;
+            return `gate step ${step} ${hit.ok === true ? 'passed' : 'failed'}${hit.timedOut === true ? ' (timed out)' : ''}`;
+        },
+    };
+}
+//# sourceMappingURL=citation-readers.js.map

package/dist/citation-readers.js.map

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

package/dist/command-receipts.d.ts

@@ -0,0 +1,79 @@
+import type { LedgerFs } from './ledger-store';
+/**
+ * What this machine has already carried out — `commands.json` under the state dir.
+ *
+ * The run lease answers "is something running here *now*". It cannot answer
+ * "did I already do this", because it stops existing the moment the run ends.
+ * That gap is real and reachable: a `start-run` whose ack was lost redelivers
+ * for the whole hour-long window, and if the run it started has since finished,
+ * the lease is free and a second full run begins. The phone asked once.
+ *
+ * So a terminal disposition is written down. The guarantee this file exists to
+ * provide is the one Phase 0's redelivery made necessary:
+ *
+ *   a command that reached a terminal outcome never executes again.
+ *
+ * Bounded on purpose. This is a dedupe window, not an audit log — the server
+ * holds the record of every command with its outcome. Keeping the newest few
+ * hundred covers a redelivery window measured in an hour; keeping all of them
+ * would grow a file on the append path of an overnight run for no benefit.
+ */
+/** One command this machine finished with. */
+export interface CommandReceipt {
+    id: string;
+    kind: string;
+    outcome: 'done' | 'refused';
+    at: string;
+    /**
+     * Why it was refused, when it was.
+     *
+     * Kept because the receipt is what answers a REDELIVERY: a command whose ack
+     * was lost comes back, and the daemon replies from here rather than doing the
+     * work again. Without the reason stored, that second answer would be a
+     * strictly worse one than the first — the same refusal, stripped of the only
+     * part a person could act on.
+     *
+     * Optional, and only ever set alongside `outcome: 'refused'`. Receipts
+     * written by an older build simply do not have it.
+     */
+    reason?: string;
+}
+/**
+ * How many receipts to keep.
+ *
+ * Comfortably more than a redelivery window can hold: the server's window is
+ * one hour and the daemon polls every three seconds, so even a pathological
+ * burst cannot push a still-redeliverable id out of this range.
+ */
+export declare const MAX_RECEIPTS = 512;
+export type ReceiptsState = 'ok' | 'unreadable';
+export declare class CommandReceipts {
+    private readonly stateDir;
+    private readonly fs;
+    private readonly now;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private receipts;
+    private state;
+    private opened;
+    constructor(stateDir: string, fs: LedgerFs, now?: () => number);
+    private get path();
+    /** Read what is on disk. Never throws: an unreadable file is a state, not a crash. */
+    open(): Promise<ReceiptsState>;
+    /** Whether the file could be read. Callers decide what an unreadable one means. */
+    status(): ReceiptsState;
+    /** Has this exact command already reached a terminal outcome here? */
+    seen(id: string): CommandReceipt | undefined;
+    /**
+     * Write down that a command is finished with.
+     *
+     * Recorded after the handler acted and before the ack, so a crash between the
+     * two leaves the receipt rather than losing it — the redelivery that follows
+     * is then recognised instead of re-executed. The other order would make a
+     * lost ack indistinguishable from work never done.
+     */
+    record(id: string, kind: string, outcome: 'done' | 'refused', reason?: string): Promise<void>;
+    private persist;
+}
+export declare function isRepeatable(kind: string): boolean;
+//# sourceMappingURL=command-receipts.d.ts.map

package/dist/command-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-receipts.d.ts","sourceRoot":"","sources":["../src/command-receipts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,YAAY,CAAC;AAEhD,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,EACZ,GAAG,GAAE,MAAM,MAAyB;IAGvD,OAAO,KAAK,IAAI,GAEf;IAED,sFAAsF;IAChF,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IA+BpC,mFAAmF;IACnF,MAAM,IAAI,aAAa;IAIvB,sEAAsE;IACtE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI5C;;;;;;;OAOG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAuBrF,OAAO;CAatB;AAYD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/dist/command-receipts.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandReceipts = exports.MAX_RECEIPTS = void 0;
+exports.isRepeatable = isRepeatable;
+/**
+ * How many receipts to keep.
+ *
+ * Comfortably more than a redelivery window can hold: the server's window is
+ * one hour and the daemon polls every three seconds, so even a pathological
+ * burst cannot push a still-redeliverable id out of this range.
+ */
+exports.MAX_RECEIPTS = 512;
+class CommandReceipts {
+    stateDir;
+    fs;
+    now;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    receipts = [];
+    state = 'ok';
+    opened = false;
+    constructor(stateDir, fs, now = () => Date.now()) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.now = now;
+    }
+    get path() {
+        return `${this.stateDir}/commands.json`;
+    }
+    /** Read what is on disk. Never throws: an unreadable file is a state, not a crash. */
+    async open() {
+        this.opened = true;
+        let text;
+        try {
+            text = await this.fs.readFile(this.path);
+        }
+        catch {
+            this.state = 'unreadable';
+            return this.state;
+        }
+        if (text === null) {
+            this.receipts = [];
+            this.state = 'ok';
+            return this.state;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (!Array.isArray(parsed)) {
+                this.state = 'unreadable';
+                return this.state;
+            }
+            this.receipts = parsed.filter(isReceipt);
+            this.state = 'ok';
+        }
+        catch {
+            // Written temp-then-rename, so a torn file should be impossible; garbage
+            // here is a fact about the machine rather than a race, and guessing
+            // "nothing has run" would re-open the duplicate-run window this closes.
+            this.state = 'unreadable';
+        }
+        return this.state;
+    }
+    /** Whether the file could be read. Callers decide what an unreadable one means. */
+    status() {
+        return this.state;
+    }
+    /** Has this exact command already reached a terminal outcome here? */
+    seen(id) {
+        return this.receipts.find((r) => r.id === id);
+    }
+    /**
+     * Write down that a command is finished with.
+     *
+     * Recorded after the handler acted and before the ack, so a crash between the
+     * two leaves the receipt rather than losing it — the redelivery that follows
+     * is then recognised instead of re-executed. The other order would make a
+     * lost ack indistinguishable from work never done.
+     */
+    async record(id, kind, outcome, reason) {
+        if (!this.opened)
+            throw new Error('CommandReceipts.record before open()');
+        if (this.state === 'unreadable') {
+            // Refuse to rewrite a file we could not read: that would silently discard
+            // whatever it held, which is the history this whole file is.
+            return;
+        }
+        this.receipts = this.receipts.filter((r) => r.id !== id);
+        this.receipts.push({
+            id,
+            kind,
+            outcome,
+            at: new Date(this.now()).toISOString(),
+            // Only on a refusal, and only if there is one. A `done` receipt with a
+            // reason attached is the stale-explanation bug written down.
+            ...(outcome === 'refused' && reason !== undefined ? { reason } : {}),
+        });
+        if (this.receipts.length > exports.MAX_RECEIPTS) {
+            this.receipts = this.receipts.slice(this.receipts.length - exports.MAX_RECEIPTS);
+        }
+        await this.persist();
+    }
+    async persist() {
+        await this.fs.mkdir(this.stateDir);
+        // Same contract as every other store here: a reader in the daemon's next
+        // life must never catch half a file.
+        // The temp name is PRIVATE TO THIS WRITER. A shared `commands.json.tmp` is
+        // two processes writing one path: the second truncates and rewrites what
+        // the first is midway through, and then both rename it into place. The
+        // rename is atomic and the file it renames is a splice of two writes, and
+        // nothing downstream can tell.
+        const tmp = `${this.path}.${process.pid}.${(CommandReceipts.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(this.receipts, null, 2) + '\n');
+        await this.fs.rename(tmp, this.path);
+    }
+}
+exports.CommandReceipts = CommandReceipts;
+/**
+ * Commands that may safely run again if their outcome was never recorded.
+ *
+ * Everything not listed here is treated as consequential: if we cannot prove it
+ * has not already been done, we refuse rather than do it twice. `start-run` and
+ * `scan` each spawn a process that mutates the repository; the others write a
+ * single control request whose effect is the same however many times it lands.
+ */
+const REPEATABLE = new Set(['pause', 'stop', 'resume']);
+function isRepeatable(kind) {
+    return REPEATABLE.has(kind);
+}
+function isReceipt(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    // The OUTCOME is checked too, not just the identity. A receipt without one
+    // used to load through and be handed straight back as the disposition, which
+    // put `undefined` where the daemon expected 'done' or 'refused' — past the
+    // retry check, and on to the server as the outcome of a command. Anything
+    // that cannot say how it ended is not a receipt.
+    return (typeof r['id'] === 'string' &&
+        typeof r['kind'] === 'string' &&
+        (r['outcome'] === 'done' || r['outcome'] === 'refused') &&
+        (r['reason'] === undefined || typeof r['reason'] === 'string'));
+}
+//# sourceMappingURL=command-receipts.js.map

package/dist/command-receipts.js.map

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

package/dist/command-runner.d.ts

@@ -0,0 +1,32 @@
+import type { CommandRunner } from './gate';
+/**
+ * The real command runner behind the gate.
+ *
+ * Steps run through a shell (`npx --no-install jest --ci` is a shell line, not an
+ * argv), so the pid we hold is the shell's, not the tool's. The timeout therefore
+ * kills the whole process *group* — killing only the shell would orphan the actual
+ * hung jest, and the round would wait on it forever (DESIGN §12 case 5). Process
+ * creation and killing come through {@link CommandRunnerDeps}, so the timeout,
+ * settlement and output behaviour are all testable without spawning anything.
+ */
+/** The slice of a child process the runner needs; callbacks may fire in any order. */
+export interface SpawnHandle {
+    pid: number | undefined;
+    /** `code` is null when the process died to a signal rather than exiting. */
+    onExit(cb: (code: number | null) => void): void;
+    /** Spawn-level failure: the shell itself could not start. */
+    onError(cb: (err: Error) => void): void;
+    /** Interleaved stdout + stderr, already decoded. */
+    onOutput(cb: (chunk: string) => void): void;
+}
+export interface CommandRunnerDeps {
+    spawn(cmd: string): SpawnHandle;
+    /** Must take down `pid` and every descendant, not just `pid`. */
+    killTree(pid: number): void;
+}
+export declare function makeCommandRunner(deps: CommandRunnerDeps): CommandRunner;
+export declare function nodeSpawn(cmd: string): SpawnHandle;
+export declare function nodeKillTree(pid: number): void;
+/** The runner the gate executor should be handed in real use. */
+export declare const nodeCommandRunner: CommandRunner;
+//# sourceMappingURL=command-runner.d.ts.map

package/dist/command-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-runner.d.ts","sourceRoot":"","sources":["../src/command-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG3D;;;;;;;;;GASG;AAEH,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IAChD,6DAA6D;IAC7D,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAmCxE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAkBlD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAmC9C;AAED,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,aAG9B,CAAC"}