looply-cli 0.0.0-stage → 0.3.0

package/dist/reaper.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVISIONED_MARKER = void 0;
+exports.writeProvisionedMarker = writeProvisionedMarker;
+exports.provisionedByDaemon = provisionedByDaemon;
+exports.idleMinutesOf = idleMinutesOf;
+exports.reapOneProvisioned = reapOneProvisioned;
+exports.nodeReaper = nodeReaper;
+exports.hasProvisionedMarker = hasProvisionedMarker;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const git_driver_1 = require("./git-driver");
+const workspace_1 = require("./workspace");
+/**
+ * THE MACHINE RETIRES WHAT IT MADE — when the project asked (M4-4).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Since M4-1 the daemon can make checkouts, and nothing removed them: idle ones
+ * accumulated up to `machine.max_workspaces` until a person ran the manual
+ * reap. With `machine.reap_provisioned: true` the daemon retires, at most ONE
+ * per cadence, after the tick, a checkout that meets ALL of:
+ *
+ *   1. IT MADE IT — the provisioner leaves `provisioned.json` in the checkout's
+ *      state dir; a checkout a person cut carries none and is never touched;
+ *   2. NOTHING RUNS THERE — `abandonedWorkspaces` lists it (no record claims
+ *      it, no live lease, no live creation marker), or its only record is of a
+ *      run that has DIED (an orphan the manual command retires the same way);
+ *   3. IT HAS BEEN IDLE for at least `machine.idle_checkout_minutes`, measured
+ *      from the newest of the marker and anything written to its state dir;
+ *   4. THE MANUAL COMMAND'S OWN FUNCTIONS AGREE — `reapAbandoned` /
+ *      `reapWorkspace`: not busy, not quarantined, no residue (uncommitted or
+ *      untracked work keeps it, with the reason), records retained, then
+ *      `git worktree remove` and prune.
+ *
+ * 🔴 NEVER A CHECKOUT THAT IS ABOUT TO BE USED. The daemon hands over the
+ * paths it placed a goal into this cadence and last (a launch is not an
+ * arrival: the run has not written its lease yet) and the one it provisioned
+ * this cadence; none of those is a candidate. And an orphan's checkout that a
+ * LIVE run now occupies is not touched either — the dead record is somebody
+ * else's leftover, the checkout is in use.
+ *
+ * ⚠️ AND IT KNOWS NOTHING ABOUT GOALS. A checkout is a checkout.
+ */
+exports.PROVISIONED_MARKER = 'provisioned.json';
+/** Written by the provisioner once the checkout is complete: the fact that the machine made it. */
+function writeProvisionedMarker(stateDir, at, pid) {
+    const marker = { by: 'daemon', at, pid };
+    const tmp = (0, node_path_1.join)(stateDir, `${exports.PROVISIONED_MARKER}.${pid}.tmp`);
+    (0, node_fs_1.writeFileSync)(tmp, `${JSON.stringify(marker, null, 2)}\n`);
+    (0, node_fs_1.renameSync)(tmp, (0, node_path_1.join)(stateDir, exports.PROVISIONED_MARKER));
+}
+function provisionedByDaemon(checkout) {
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(checkout, git_driver_1.STATE_DIR, 'state', exports.PROVISIONED_MARKER), 'utf8'));
+        return raw.by === 'daemon' && typeof raw.at === 'string' && typeof raw.pid === 'number' ? { by: 'daemon', at: raw.at, pid: raw.pid } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Minutes since anything last happened in the checkout: the marker, or the newest entry of its state dir. */
+function idleMinutesOf(checkout, marker, now) {
+    let newest = Date.parse(marker.at) || 0;
+    const stateDir = (0, node_path_1.join)(checkout, git_driver_1.STATE_DIR, 'state');
+    try {
+        for (const name of (0, node_fs_1.readdirSync)(stateDir)) {
+            try {
+                newest = Math.max(newest, (0, node_fs_1.statSync)((0, node_path_1.join)(stateDir, name)).mtimeMs);
+            }
+            catch {
+                /* a file that vanished between readdir and stat */
+            }
+        }
+    }
+    catch {
+        /* no state dir: the marker is all there is */
+    }
+    return Math.max(0, (now - newest) / 60_000);
+}
+const same = (p) => (0, node_path_1.resolve)(p).toLowerCase();
+/** One cadence's reaping: the first eligible checkout in path order, and only one. */
+async function reapOneProvisioned(deps) {
+    const probe = deps.probe ?? workspace_1.nodeProbe;
+    const home = deps.home ?? (0, node_os_1.homedir)();
+    const { abandoned } = (0, workspace_1.abandonedWorkspaces)(deps.cwd, deps.registry, probe, home);
+    const orphans = deps.registry
+        .list()
+        .flatMap((e) => (e.kind === 'orphaned' ? [e.record] : []));
+    const candidates = [
+        ...abandoned.map((path) => ({ path, kind: 'abandoned' })),
+        ...orphans.map((record) => ({ path: record.workspace, kind: 'orphaned', record })),
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const excluded = new Set((deps.exclude ?? []).map(same));
+    for (const c of candidates) {
+        if (excluded.has(same(c.path)))
+            continue;
+        // A dead record's checkout may be somebody's now: a live lease there is a run, whatever the record says.
+        if (c.kind === 'orphaned' && (0, workspace_1.checkoutBusy)((0, node_path_1.join)(c.path, git_driver_1.STATE_DIR, 'state'), probe))
+            continue;
+        const marker = provisionedByDaemon(c.path);
+        if (marker === null)
+            continue;
+        const idle = idleMinutesOf(c.path, marker, deps.now());
+        if (idle < deps.idleMinutes)
+            continue;
+        if (c.kind === 'abandoned') {
+            const out = await (0, workspace_1.reapAbandoned)(deps.git, deps.cwd, c.path, probe, undefined, home);
+            if (out.reaped) {
+                deps.log(`daemon  : retired the checkout it made at ${c.path} — idle ${Math.floor(idle)} min, nothing referenced it, no residue`);
+                return 'retired';
+            }
+            deps.log(`daemon  : kept the checkout it made at ${c.path} — ${out.because ?? 'unknown'}`);
+            return 'kept';
+        }
+        const out = await (0, workspace_1.reapWorkspace)(deps.git, deps.registry, c.record, deps.cwd, probe, undefined, home);
+        if (out.reaped) {
+            deps.log(`daemon  : retired the checkout it made at ${c.path} — idle ${Math.floor(idle)} min, its run ${c.record.runId} had died` +
+                (out.evidenceAt === undefined ? '' : `; its records kept at ${out.evidenceAt}`));
+            return 'retired';
+        }
+        deps.log(`daemon  : kept the checkout it made at ${c.path} — ${out.because ?? 'unknown'}`);
+        return 'kept';
+    }
+    return 'none';
+}
+/** The daemon's reaper: built only behind `machine.reap_provisioned`; a failure is a log line, never a stopped daemon. */
+function nodeReaper(cwd, projectState, opts) {
+    return async (exclude = []) => {
+        try {
+            return await reapOneProvisioned({
+                cwd,
+                registry: new workspace_1.RunRegistry(projectState),
+                git: new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(cwd)),
+                now: opts.now ?? (() => Date.now()),
+                idleMinutes: opts.idleMinutes,
+                log: opts.log,
+                exclude,
+                ...(opts.home === undefined ? {} : { home: opts.home }),
+            });
+        }
+        catch (e) {
+            opts.log(`daemon  : could not retire a checkout it made — ${e.message}`);
+            return 'failed';
+        }
+    };
+}
+/** For `looply runs` and tests: is there a marker at all? */
+function hasProvisionedMarker(checkout) {
+    return (0, node_fs_1.existsSync)((0, node_path_1.join)(checkout, git_driver_1.STATE_DIR, 'state', exports.PROVISIONED_MARKER));
+}
+//# sourceMappingURL=reaper.js.map

package/dist/reaper.js.map

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

package/dist/record-store.d.ts

@@ -0,0 +1,36 @@
+import type { LedgerFs } from './ledger-store';
+/**
+ * AN APPEND-ONLY RECORD FILE ON THE MACHINE — `.looply/state/<file>.jsonl`.
+ *
+ * One record per line, written once and never edited, the ledger's own shape:
+ * the file is a history a fresh process reads back in full. Keyed by the
+ * record's id, so a caller can ask "is this already on record" before doing
+ * the thing the record describes.
+ *
+ * ⚠️ A LINE THAT CANNOT BE READ IS SKIPPED AND COUNTED, never a throw: a torn
+ * write at the tail must not take the whole history with it, and a count is
+ * how a person finds out it happened.
+ */
+export declare class AppendOnlyStore<T extends {
+    readonly id: string;
+}> {
+    private readonly stateDir;
+    private readonly file;
+    private readonly accept;
+    private readonly fs;
+    private readonly byId;
+    private opened;
+    private unreadable;
+    constructor(stateDir: string, file: string, accept: (v: unknown) => v is T, fs: LedgerFs);
+    private get path();
+    isOpen(): boolean;
+    open(): Promise<{
+        records: number;
+        unreadable: number;
+    }>;
+    find(id: string): T | null;
+    all(): T[];
+    /** Written once. Appending an id already on record is a programming error, not a second answer. */
+    append(record: T): Promise<void>;
+}
+//# sourceMappingURL=record-store.d.ts.map

package/dist/record-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-store.d.ts","sourceRoot":"","sources":["../src/record-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE;IAM1D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAK;gBAGJ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,EAC9B,EAAE,EAAE,QAAQ;IAG/B,OAAO,KAAK,IAAI,GAEf;IAED,MAAM,IAAI,OAAO;IAIX,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAwB9D,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAI1B,GAAG,IAAI,CAAC,EAAE;IAIV,mGAAmG;IAC7F,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAMvC"}

package/dist/record-store.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppendOnlyStore = void 0;
+/**
+ * AN APPEND-ONLY RECORD FILE ON THE MACHINE — `.looply/state/<file>.jsonl`.
+ *
+ * One record per line, written once and never edited, the ledger's own shape:
+ * the file is a history a fresh process reads back in full. Keyed by the
+ * record's id, so a caller can ask "is this already on record" before doing
+ * the thing the record describes.
+ *
+ * ⚠️ A LINE THAT CANNOT BE READ IS SKIPPED AND COUNTED, never a throw: a torn
+ * write at the tail must not take the whole history with it, and a count is
+ * how a person finds out it happened.
+ */
+class AppendOnlyStore {
+    stateDir;
+    file;
+    accept;
+    fs;
+    byId = new Map();
+    opened = false;
+    unreadable = 0;
+    constructor(stateDir, file, accept, fs) {
+        this.stateDir = stateDir;
+        this.file = file;
+        this.accept = accept;
+        this.fs = fs;
+    }
+    get path() {
+        return `${this.stateDir}/${this.file}`;
+    }
+    isOpen() {
+        return this.opened;
+    }
+    async open() {
+        await this.fs.mkdir(this.stateDir);
+        const text = await this.fs.readFile(this.path);
+        this.byId.clear();
+        this.unreadable = 0;
+        for (const line of (text ?? '').split('\n')) {
+            if (line.trim() === '')
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                this.unreadable += 1;
+                continue;
+            }
+            if (!this.accept(parsed)) {
+                this.unreadable += 1;
+                continue;
+            }
+            this.byId.set(parsed.id, parsed);
+        }
+        this.opened = true;
+        return { records: this.byId.size, unreadable: this.unreadable };
+    }
+    find(id) {
+        return this.byId.get(id) ?? null;
+    }
+    all() {
+        return [...this.byId.values()];
+    }
+    /** Written once. Appending an id already on record is a programming error, not a second answer. */
+    async append(record) {
+        if (!this.opened)
+            throw new Error(`${this.file}: append before open()`);
+        if (this.byId.has(record.id))
+            throw new Error(`${this.file}: ${record.id} is already on record`);
+        await this.fs.appendFile(this.path, `${JSON.stringify(record)}\n`);
+        this.byId.set(record.id, record);
+    }
+}
+exports.AppendOnlyStore = AppendOnlyStore;
+//# sourceMappingURL=record-store.js.map

package/dist/record-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-store.js","sourceRoot":"","sources":["../src/record-store.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,MAAa,eAAe;IAMP;IACA;IACA;IACA;IARF,IAAI,GAAG,IAAI,GAAG,EAAa,CAAC;IACrC,MAAM,GAAG,KAAK,CAAC;IACf,UAAU,GAAG,CAAC,CAAC;IAEvB,YACmB,QAAgB,EAChB,IAAY,EACZ,MAA8B,EAC9B,EAAY;QAHZ,aAAQ,GAAR,QAAQ,CAAQ;QAChB,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAwB;QAC9B,OAAE,GAAF,EAAE,CAAU;IAC5B,CAAC;IAEJ,IAAY,IAAI;QACd,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,SAAS;YACjC,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;IAClE,CAAC;IAED,IAAI,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,MAAM,CAAC,MAAS;QACpB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,wBAAwB,CAAC,CAAC;QACxE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,uBAAuB,CAAC,CAAC;QACjG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;CACF;AA3DD,0CA2DC"}

package/dist/recovery-io.d.ts

@@ -0,0 +1,50 @@
+import { type Recovery } from './recovery';
+import type { RunnerQueue } from './round-runner';
+import type { AnyEventInput } from './ledger-store';
+/**
+ * Carrying out what the classifier decided.
+ *
+ * Deliberately separate from the decision, so the policy is a pure function
+ * over evidence and this is the only place with effects. Nothing here decides
+ * anything; if it is reached, the tree was already proven clean.
+ *
+ * Event-first. The machine does not reach across and patch the server's Run,
+ * Round and Item rows — it says what happened on the ledger it already owns and
+ * every projection converges from that. One execution history, many mirrors,
+ * and a repair that is visible in the same place as the work it repairs.
+ */
+export interface RecoveryIo {
+    /**
+     * Omitted by a caller that holds no lease — the daemon at startup.
+     *
+     * Item repairs are then *refused* rather than skipped. A silent skip is how a
+     * repair somebody expected becomes one nobody notices did not happen, and the
+     * two callers here differ on purpose: the run holds the lease and repairs the
+     * queue, the daemon does not and only closes the run.
+     */
+    queue?: RunnerQueue;
+    ledger: {
+        append(input: AnyEventInput): Promise<unknown>;
+    };
+    /**
+     * M5-5: whether the ledger about to be written ALREADY holds an ending for
+     * this run — read at WRITE time, not only when the recovery was decided.
+     *
+     * Measured before this existed (evidence/M5-4/11-endings-measurement.txt):
+     * the daemon's sweep closed a dead run, and one second later `looply run`
+     * starting in the same checkout found the same dead lease and closed it
+     * again — the run's own recovery never looked at the ledger. Two endings for
+     * one run is exactly the shape a report cannot read.
+     *
+     * `null` means the ledger could not be read: then NOTHING is written. A second
+     * ending is the failure this exists to prevent, and an unreadable ledger is
+     * not permission to write one. Optional so that a caller with no reader
+     * behaves exactly as before.
+     */
+    alreadyEnded?(runId: string): Promise<boolean | null>;
+    projectId: string;
+    now(): number;
+    log(line: string): void;
+}
+export declare function applyRecovery(recovery: Recovery, io: RecoveryIo): Promise<void>;
+//# sourceMappingURL=recovery-io.d.ts.map

package/dist/recovery-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-io.d.ts","sourceRoot":"","sources":["../src/recovery-io.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;IAC3D;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,IAAI,MAAM,CAAC;IACd,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmIrF"}

package/dist/recovery-io.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRecovery = applyRecovery;
+const core_1 = require("@looply/core");
+const recovery_1 = require("./recovery");
+async function applyRecovery(recovery, io) {
+    if (recovery.kind !== 'repairable')
+        return;
+    // Loud rather than quiet. A caller with no queue that was nonetheless handed
+    // item repairs has made a mistake about which half of the repair it owns, and
+    // quietly dropping them would leave items `in_progress` for ever while every
+    // log line said the run was recovered.
+    if (recovery.items.length > 0 && !io.queue) {
+        throw new Error('recovery: item repairs were handed to an applier with no queue — ' +
+            'strip them with runClosureOnly() or supply the queue');
+    }
+    const emit = async (kind, data, runId) => {
+        await io.ledger.append({
+            ts: new Date(io.now()).toISOString(),
+            runId,
+            projectId: io.projectId,
+            lane: 'feature',
+            kind,
+            actor: 'system',
+            data,
+        });
+    };
+    // Bound once, so the loop reads a queue the compiler knows is there. The
+    // guard above already refused the one combination this could hide — repairs
+    // with nowhere to put them — so an absent queue here means an empty list.
+    const queue = io.queue;
+    if (queue) {
+        for (const repair of recovery.items) {
+            const item = queue.get(repair.itemId);
+            if (!item)
+                continue;
+            // Only what is STILL mid-round. Recovery can be applied twice — a crash
+            // inside recovery itself, a repair list retried — and without this the
+            // second pass spends another attempt on an item the first pass already
+            // handed back. That is recovery inventing failures rather than repairing
+            // them, and it would let a crash loop eat an item's whole budget.
+            /**
+             * ⚠️ EACH ACTION CHECKS THE STATE IT CLAIMS TO REPAIR, so applying a
+             * repair list twice is a no-op rather than a second spent attempt.
+             */
+            if (repair.action === 'requeue' && item.state !== 'in_progress')
+                continue;
+            if (repair.action === 'unverify' && item.state !== 'verifying')
+                continue;
+            if (repair.action === 'done') {
+                await queue.update(item.id, item.version, { state: 'done' });
+            }
+            else if (repair.action === 'unverify') {
+                // Back to where the check found it, with NO attempt spent: the verify
+                // pass had not finished and no round had begun. The next run's own
+                // pass picks it up again, which is what `draft` means.
+                await queue.update(item.id, item.version, {
+                    state: 'draft',
+                    lastFailure: `a previous run stopped while this item was being checked (${repair.reason})`,
+                });
+            }
+            else {
+                // Put back with the attempt counted and the reason carried, exactly as a
+                // discarded round does — the next attempt starts knowing what happened,
+                // rather than repeating a round nobody can explain.
+                // The attempt IS spent: the round began, the item went `in_progress`,
+                // and the process died inside it. Counting it is what stops a crash
+                // loop handing the same item a fresh budget for ever — and
+                // `afterSpentAttempt` is what stops the last one coming back as
+                // pickable.
+                const spent = item.attempts + 1;
+                await queue.update(item.id, item.version, {
+                    state: (0, core_1.afterSpentAttempt)(spent),
+                    attempts: spent,
+                    lastFailure: `a previous run stopped before this round finished (${repair.reason})`,
+                });
+            }
+        }
+    }
+    // The run that never said it stopped. Closing it through the ledger is what
+    // makes `status.json` stop reading `live`, and — once the event reaches the
+    // server — what closes the Run row that would otherwise keep the project
+    // looking busy for ever and refusing to be deleted.
+    //
+    // `crashed`, not any ordinary reason: this run did not end its own loop, and
+    // the totals are the last the ledger knew rather than a claim about what
+    // finally happened. That is exactly what separates it from `aborted`, which
+    // a still-living process writes for itself with exact numbers.
+    let closeRun = recovery.closeRun;
+    if (closeRun !== null && io.alreadyEnded !== undefined) {
+        const ended = await io.alreadyEnded(closeRun);
+        if (ended !== false) {
+            io.log(ended === true
+                ? `recover : ${closeRun} already ended — not ending it again`
+                : `recover : could not tell whether ${closeRun} already ended — not ending it`);
+            closeRun = null;
+        }
+    }
+    if (closeRun !== null) {
+        await emit('run.ended', {
+            runId: closeRun,
+            elapsedMs: 0,
+            stopReason: 'crashed',
+            totals: { rounds: 0, committed: 0, discarded: 0, abandoned: 0 },
+        }, closeRun);
+    }
+    // What was DONE, not what was decided: a closing the guard above withheld is
+    // not on the ledger, so the alert must not claim it. Nothing done, no alert.
+    const done = { ...recovery, closeRun };
+    if ((0, recovery_1.describeRecovery)(done) === 'nothing to recover')
+        return;
+    // Said on the ledger so the phone can tell "looply crashed and recovered"
+    // from "looply is running", and so a person debugging an overnight run can
+    // answer "what happened" without reverse-engineering file timestamps.
+    await emit('alert', {
+        code: core_1.ALERT_CODES.runRecovered,
+        severity: 'warn',
+        text: (0, recovery_1.describeRecovery)(done),
+    }, closeRun ?? 'recovery');
+    io.log(`recover : ${(0, recovery_1.describeRecovery)(done)}`);
+}
+//# sourceMappingURL=recovery-io.js.map

package/dist/recovery-io.js.map

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

package/dist/recovery.d.ts

@@ -0,0 +1,146 @@
+import type { Item } from '@looply/core';
+import type { RunLease } from './run-lease';
+/**
+ * What a previous run left behind, and what may safely be done about it.
+ *
+ * A crashed runner leaves a specific mess: an item stuck `in_progress` that
+ * nothing anywhere resets — `round-runner` is its only writer — a `status.json`
+ * that still says `live`, and possibly a half-edited tree. The item is
+ * unpickable for ever, so the queue quietly shrinks by one every time a run
+ * dies, and `looply queue` says the item is "being worked on now".
+ *
+ * This is one deterministic policy rather than repair conditionals scattered
+ * across the daemon, the launcher and the runner. It is a pure function on
+ * gathered evidence so every branch is testable without a repository.
+ *
+ * The rule it exists to enforce, and the one that decides every hard case:
+ *
+ *   recovery may not destroy work to make looply's state look clean.
+ *
+ * A working tree carries no authorship. Nothing in git says whether an edit was
+ * made by a crashed agent or by the person who owns the machine, and looply's
+ * own scope globs describe where it is *allowed* to write, not what it *did*.
+ * So a dirty tree is never assumed to be ours: it blocks, with a message, and
+ * a human decides. That is deliberately more conservative than the per-round
+ * discard path, which resets and cleans — that path runs inside a round whose
+ * changes looply just caused and is still watching, which is a claim recovery
+ * cannot make about a tree it found lying there.
+ */
+/**
+ * The three read-only questions recovery asks git, and nothing else.
+ *
+ * `GitDriver` satisfies this structurally, so nothing has to change at the call
+ * sites — but handing recovery the whole driver puts `discard()`, which is
+ * `reset --hard` plus `clean -fd`, and `diff()`, which runs `git add -N` and
+ * mutates the index, one autocomplete away from a process that must never write
+ * to this repository. Narrowing it here makes "recovery performs no git
+ * mutation" something the compiler enforces rather than a convention every
+ * reviewer has to re-derive by reading the whole driver.
+ */
+export interface RecoveryGit {
+    changedPaths(): Promise<string[]>;
+    currentBranch(): Promise<string>;
+    messageOf(ref: string): Promise<string | null>;
+    /** F33: where HEAD is, for a goal-met Start that moved it. Optional: an older double reads nothing. */
+    headSha?(): Promise<string>;
+}
+/**
+ * The half of a repair a process holding no lease may carry out.
+ *
+ * Closing a run is a statement about history: the run stopped, and the ledger is
+ * where that is said. Requeuing an item is a statement about future work, and
+ * the queue belongs to whoever holds the lease — `QueueStore.persist` rewrites
+ * the whole file from its in-memory map, so a second writer does not race an
+ * item, it reverts the entire queue to its own snapshot. The daemon therefore
+ * says what happened and leaves the scheduling to the next run, which does its
+ * own recovery on the way in regardless.
+ */
+export declare function runClosureOnly(r: Recovery): Recovery;
+export interface RecoveryEvidence {
+    /** The lease left behind, when there is one and its process is gone. */
+    lease: RunLease | null;
+    /** Items the queue still shows as being worked on. */
+    stranded: Item[];
+    /** Working-tree paths that differ from HEAD, `.looply/state` already filtered. */
+    changedPaths: readonly string[];
+    /** The branch HEAD is on now. */
+    currentBranch: string;
+    /** The subject line of the commit at HEAD, or null when it could not be read. */
+    headSubject: string | null;
+    /**
+     * F33: what a goal-met Start said before it moved HEAD (`judging.json`), and where HEAD is. A
+     * detached HEAD at exactly the commit the dead run said it would judge is where THAT run left it.
+     */
+    judging?: {
+        readonly runId: string;
+        readonly sha: string;
+    } | null;
+    headSha?: string;
+}
+export type ItemRepair = 
+/** Nothing was committed for it; make it pickable again with the attempt counted. */
+{
+    itemId: string;
+    action: 'requeue';
+    reason: string;
+}
+/** Its commit is at HEAD; the round finished and only the bookkeeping was lost. */
+ | {
+    itemId: string;
+    action: 'done';
+    reason: string;
+}
+/**
+ * It was being CHECKED, not worked. Put it back to `draft`, spending nothing.
+ *
+ * 🔴 `verifying` IS A SECOND IN-FLIGHT STATE, AND RECOVERY KNEW ONLY THE
+ * FIRST — SO A RUN KILLED MID-CHECK KILLED ITS CHECKOUT WITH IT.
+ *
+ * `round-runner` sets `verifying` before it sets `in_progress`. A run that
+ * died in between left an item no state machine could move: the verify pass
+ * had not finished with it, no round had started it, and recovery's stranded
+ * set was `state === 'in_progress'` alone. MEASURED end to end: every
+ * subsequent run in that checkout answered
+ *
+ *     nothing to do — no ready items: the queue holds 1 verifying
+ *
+ * and the workspace was dead for that goal for ever after — which is exactly
+ * the coordinator proof's intermittent failure, since whether the kill lands
+ * inside the check is a matter of timing.
+ *
+ * ⚠️ AND IT SPENDS NO ATTEMPT, unlike `requeue`. An attempt is a ROUND that
+ * was tried; verification is what happens before one. Counting it here would
+ * be recovery inventing a failure, which the note in `recovery-io` forbids in
+ * as many words.
+ */
+ | {
+    itemId: string;
+    action: 'unverify';
+    reason: string;
+};
+export type Recovery = 
+/** Nothing to do. */
+{
+    kind: 'none';
+}
+/** Safe, and exactly what will be done. */
+ | {
+    kind: 'repairable';
+    lease: RunLease | null;
+    items: ItemRepair[];
+    closeRun: string | null;
+}
+/**
+ * Something is here that cannot be proven safe to touch. Nothing is changed —
+ * not the queue, not the tree, not one git ref — and the reason is reported
+ * so a person can settle it.
+ */
+ | {
+    kind: 'blocked';
+    reason: string;
+    lease: RunLease | null;
+};
+export declare function classifyRecovery(ev: RecoveryEvidence): Recovery;
+/** One line a person can act on, for the log and for the alert. */
+export declare function describeRecovery(r: Recovery): string;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,uGAAuG;IACvG,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAEpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,sDAAsD;IACtD,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,UAAU;AACpB,qFAAqF;AACnF;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvD,mFAAmF;GACjF;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;GACD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,MAAM,QAAQ;AAClB,qBAAqB;AACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,2CAA2C;GACzC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AAC9F;;;;GAIG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CA0E/D;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAmBpD"}