looply-cli 0.0.0-stage → 0.3.0

package/dist/loop-safety-store.js

@@ -0,0 +1,800 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeSafetyFs = exports.LoopSafetyStore = void 0;
+const core_1 = require("@looply/core");
+function isObservation(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return (typeof o['goalId'] === 'string' &&
+        typeof o['goalVersion'] === 'number' &&
+        typeof o['ordinal'] === 'number' &&
+        typeof o['outcome'] === 'string' &&
+        typeof o['progressFingerprint'] === 'string');
+}
+function isIncident(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return (typeof o['id'] === 'string' &&
+        typeof o['goalId'] === 'string' &&
+        typeof o['goalVersion'] === 'number' &&
+        typeof o['kind'] === 'string' &&
+        typeof o['because'] === 'string');
+}
+class LoopSafetyStore {
+    stateDir;
+    fs;
+    now;
+    migrate;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    observations = [];
+    incidents = [];
+    state = 'ok';
+    opened = false;
+    /**
+     * ⚠️ `migrate` RUNS BEFORE ANY READ, AND ITS REFUSAL LEAVES THE STORE
+     * UNREADABLE — which is a REFUSAL TO START, not a silent pass.
+     *
+     * The history's home moved out of the repository (see `rails-home.ts`). During
+     * a move, "I could not read the old history" and "there is no old history"
+     * look the same, and this store must never confuse them: an empty history
+     * discharges every hold it holds. A `repeated_failure` hold raised an hour ago
+     * would vanish, the run it was stopping would start, and nothing would say why.
+     *
+     * Omitted, there is no migration and nothing changes.
+     */
+    constructor(stateDir, 
+    /**
+     * ⚠️ `readDir` IS OPTIONAL, so every existing fake still satisfies this.
+     * A store that cannot list the ordinal claims simply falls back to deriving
+     * the next attempt number from the observations, which is what it did
+     * before — weaker, and never wrong in a direction that loses a hold.
+     */
+    fs, now = () => Date.now(), migrate) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.now = now;
+        this.migrate = migrate;
+    }
+    get path() {
+        return `${this.stateDir}/loop-safety.json`;
+    }
+    /**
+     * The append-only history of attempts.
+     *
+     * 🔴 A SEPARATE FILE FROM THE INCIDENTS, AND APPEND-ONLY, BECAUSE A REWRITE
+     * LOSES A CONCURRENT WRITER'S WORK. Two writers for one goal on one machine is
+     * ordinary — the run recording what it achieved, and the Start gate spending a
+     * retry — and a whole-document rewrite meant whichever loaded first clobbered
+     * the other. For the spent retry that was survivable (the marker file is the
+     * authority). For an OBSERVATION it was not: a shorter history holds LATER, so
+     * the machine keeps working, which is the direction that costs a person money.
+     *
+     * The shape is `ledger-store.ts`'s, deliberately: events appended as JSONL,
+     * never rewritten, with the small mutable thing kept as a projection beside
+     * it. ⚠️ NOT `command-receipts.ts` — that one rewrites its whole document too,
+     * and an earlier draft of this file's own handoff cited it as the append-only
+     * precedent. It is not one.
+     *
+     * NEVER COMPACT THIS FILE. `ledger-store` says the same of its own events and
+     * for the same reason: a compaction is a rewrite, and a concurrent append
+     * during one is exactly the loss this change exists to prevent.
+     *
+     * ⚠️ THE COST THIS TRADE BUYS, STATED PLAINLY RATHER THAN LEFT TO BE FOUND.
+     * The whole file is read and parsed on every observation, because the verdict
+     * must be a fact about the machine rather than about one process. So the read
+     * grows with the machine's LIFETIME, not with its current workload: one record
+     * per attempt, forever, re-parsed each time.
+     *
+     * That is affordable at the scale this runs at — attempts are minutes apart
+     * and bounded by the very brake this file feeds — and it is the honest
+     * successor to the limit it replaced, not the absence of one. If a machine
+     * ever accumulates enough attempts for this to matter, the answer is a second
+     * ledger file rolled by date with the old one left in place, NOT a compaction
+     * of this one.
+     */
+    get eventsPath() {
+        return `${this.stateDir}/loop-safety-events.jsonl`;
+    }
+    /** Where an override's exclusive-create claim lives. One file per incident. */
+    /**
+     * Where incidents are written now: APPEND-ONLY, one per line.
+     *
+     * 🔴 `persist()` REWROTE THE WHOLE DOCUMENT from an `open()`-time snapshot,
+     * and Phase 1 turned that into a hold-erasing race. Moving this file to the
+     * project state directory is what lets a hold raised in one workspace be seen
+     * in another — and the same change put two concurrent writers on it. Two runs
+     * raising holds for two different pursuits each wrote a document without the
+     * other's incident, so one brake vanished. Unlike an override, nothing
+     * recovers it.
+     *
+     * Observations were made append-only long ago for exactly this reason.
+     * Incidents simply never were, because until Phase 1 there could not be two
+     * writers.
+     */
+    get incidentsPath() {
+        return `${this.stateDir}/loop-safety-incidents.jsonl`;
+    }
+    /** A short unique token for an incident id. Filename-safe by construction. */
+    incidentToken() {
+        return `${this.now().toString(36)}${Math.floor(Math.random() * 1e6).toString(36)}`;
+    }
+    overridePath(incidentId) {
+        return `${this.stateDir}/loop-safety-overrides/${incidentId}.json`;
+    }
+    /** Read what is on disk. Never throws: an unreadable file is a state, not a crash. */
+    async open() {
+        this.opened = true;
+        if (this.migrate !== undefined) {
+            const moved = await this.migrate();
+            if (!moved.ok) {
+                this.state = 'unreadable';
+                return this.state;
+            }
+        }
+        let text;
+        try {
+            text = await this.fs.readFile(this.path);
+        }
+        catch {
+            this.state = 'unreadable';
+            return this.state;
+        }
+        if (text === null) {
+            this.incidents = [];
+            await this.loadIncidents();
+            await this.loadObservations();
+            await this.foldInSpentRetries();
+            this.state = 'ok';
+            return this.state;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== 'object' || parsed === null) {
+                this.state = 'unreadable';
+                return this.state;
+            }
+            this.incidents = Array.isArray(parsed.incidents) ? parsed.incidents.filter(isIncident) : [];
+            /**
+             * ⚠️ OBSERVATIONS ARE READ FROM THE LEDGER, AND A DOCUMENT WRITTEN BY AN
+             * OLDER BUILD MAY STILL CARRY SOME. They are taken as the history's start
+             * so an upgrade does not silently discharge a pursuit that was three
+             * barren attempts deep, and the ledger is appended after them.
+             */
+            const carried = Array.isArray(parsed.observations)
+                ? parsed.observations.filter(isObservation)
+                : [];
+            await this.loadIncidents();
+            await this.loadObservations(carried);
+            await this.foldInSpentRetries();
+            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 happened" would silently discharge every hold this file
+             * holds, which is the one direction that must never fail open.
+             */
+            this.state = 'unreadable';
+        }
+        return this.state;
+    }
+    status() {
+        return this.state;
+    }
+    /**
+     * The active incident for a pursuit, or null.
+     *
+     * ⚠️ AN UNREADABLE FILE ANSWERS `null`, AND THAT IS DELIBERATE — but it is
+     * NOT the same as failing open. The caller (`autonomy-tick`) treats an
+     * unreadable store as a hold in its own right, because a machine that cannot
+     * read its safety history must not spend a night on the assumption that it is
+     * empty. Deciding that here would hide it inside a getter.
+     */
+    /**
+     * Whether this store could read its history.
+     *
+     * 🔴 EXPOSED BECAUSE THE RULE ABOVE HAD A SECOND CALLER THAT DID NOT KNOW IT.
+     * `activeIncident` answers null on an unreadable file and says, correctly,
+     * that deciding there "would hide it inside a getter" — but that only works
+     * while every caller applies the rule. `autonomy-tick` did; the coordinator's
+     * `holdsFor` did not, and returned NO HOLDS for an unreadable history, which
+     * `decideSchedule` reads as "nothing is held" and answers with `start`.
+     *
+     * `open()` already returns this; a store that has been opened elsewhere had
+     * no way to be asked again.
+     */
+    readable() {
+        return this.state === 'ok';
+    }
+    activeIncident(goalId, goalVersion) {
+        return (this.incidents.find((i) => i.goalId === goalId &&
+            i.goalVersion === goalVersion &&
+            i.overriddenByStartId === undefined) ?? null);
+    }
+    /** Every incident ever derived for this pursuit, newest last. History, not state. */
+    history(goalId) {
+        return this.incidents.filter((i) => i.goalId === goalId);
+    }
+    observationsFor(goalId) {
+        return this.observations.filter((o) => o.goalId === goalId);
+    }
+    /**
+     * The number to give the next attempt for this pursuit.
+     *
+     * ⚠️ NOT `observationsFor(...).length + 1`, WHICH IS WHAT THIS REPLACED. The
+     * history is bounded at `MAX_SAFETY_OBSERVATIONS`, so a count SATURATES: past
+     * sixteen attempts every one of them is numbered seventeen, and the evidence
+     * a person reads to understand why their machine stopped becomes three
+     * identical lines. No detector reads the ordinal, so nothing went wrong — it
+     * was only unreadable, which is the kind of defect a test suite never has an
+     * opinion about.
+     *
+     * Counting on from the LAST one survives trimming, because trimming keeps the
+     * newest. It restarts at one for a pursuit with no history, which is correct:
+     * a person who has never seen this Goal run should be shown attempt one.
+     */
+    nextOrdinalFor(goalId) {
+        const mine = this.observationsFor(goalId);
+        const last = mine[mine.length - 1];
+        return last === undefined ? 1 : last.ordinal + 1;
+    }
+    /**
+     * The largest attempt number anybody has already claimed for this goal, or 0.
+     *
+     * ⚠️ CLAIMS, NOT OBSERVATIONS. See `mintOrdinal`. An unreadable directory
+     * answers 0, which makes the caller fall back to the observation-derived
+     * start — the same answer it had before, rather than a refusal.
+     */
+    async highestClaim(goalId) {
+        let names;
+        try {
+            names = (await this.fs.readDir?.(`${this.stateDir}/loop-safety-ordinals`)) ?? [];
+        }
+        catch {
+            return 0;
+        }
+        let top = 0;
+        const prefix = `${goalId}-`;
+        for (const name of names) {
+            if (!name.startsWith(prefix) || !name.endsWith('.json'))
+                continue;
+            const n = Number.parseInt(name.slice(prefix.length, -'.json'.length), 10);
+            if (Number.isInteger(n) && n > top)
+                top = n;
+        }
+        return top;
+    }
+    /** Where an ordinal's exclusive-create claim lives. One file per attempt. */
+    ordinalPath(goalId, ordinal) {
+        return `${this.stateDir}/loop-safety-ordinals/${goalId}-${ordinal}.json`;
+    }
+    /**
+     * TAKE THE NEXT ATTEMPT NUMBER, EXCLUSIVELY.
+     *
+     * 🔴 `nextOrdinalFor` IS A READ, AND TWO RUNS READ THE SAME ANSWER.
+     *
+     * It derives the next number from the last observation on disk. That was
+     * sound while one run owned one checkout. With N workspaces two runs on one
+     * goal start within the same second, both read "the last attempt was 3", and
+     * both record attempt 4 — so the evidence a person is shown to explain why
+     * their machine stopped contains two different attempt fours and no five.
+     * `MAX_SAME_FAILURE_REPEATS` still fires correctly, because no detector reads
+     * the ordinal; what breaks is the only part of a hold a person can act on.
+     *
+     * ⚠️ THE SAME PRIMITIVE THE OVERRIDE MARKER USES, three files away: the
+     * filesystem arbitrates, never a read-then-write, because the two claimants
+     * may be two processes. On EEXIST the candidate simply advances — losing a
+     * race means somebody else has that number, which is exactly the information
+     * needed to pick the next one.
+     *
+     * ⚠️ GAPS ARE FINE, DUPLICATES ARE NOT. A run that mints 4 and then crashes
+     * burns 4, and the next attempt is 5. Nothing counts ordinals — the history's
+     * length is what detectors read — so a gap costs a person nothing, while a
+     * duplicate costs them the ability to tell two attempts apart.
+     */
+    async mintOrdinal(goalId) {
+        if (!this.opened)
+            throw new Error('LoopSafetyStore.mintOrdinal before open()');
+        /**
+         * ⚠️ PATH SAFETY, NOT VALIDATION THEATRE: the goal id becomes a filename.
+         * A goal id that cannot be a filename gets the unsynchronised answer rather
+         * than a thrown error — this is bookkeeping for a person to read, and no
+         * run should ever end because its goal was named unusually.
+         */
+        if (/[^A-Za-z0-9_-]/.test(goalId))
+            return this.nextOrdinalFor(goalId);
+        await this.fs.mkdir(`${this.stateDir}/loop-safety-ordinals`);
+        /**
+         * ⚠️ RELOAD FIRST. `nextOrdinalFor` reads the snapshot taken at `open()`,
+         * and a run opens the store at its first second and mints hours later. The
+         * EEXIST loop below would climb past a stale start eventually, but starting
+         * from the truth means it almost never has to.
+         */
+        await this.loadObservations();
+        /**
+         * 🔴 THE START IS THE HIGHEST CLAIM ON DISK, NOT THE LAST OBSERVATION — AND
+         * WITHOUT THAT THE WHOLE MECHANISM WEDGED AFTER 64 MINTS.
+         *
+         * A claim file is written for every MINT; an OBSERVATION is only recorded
+         * when the attempt counts. An excluded attempt — awaiting approval, an
+         * ambiguous governed action, a blocked environment — therefore leaves a
+         * claim above the last observation, permanently. Starting from the last
+         * observation meant the loop walked the same burnt range every time, and
+         * after 64 such attempts it exhausted the window and fell through to the
+         * unsynchronised answer FOR EVER. MEASURED: 70 mints with no observations
+         * returned 1..64 and then 1, 1, 1, 1 — two concurrent runs both handed
+         * ordinal 1, which is exactly what this function exists to prevent, and
+         * silently.
+         *
+         * Reading the claims answers the real question — what has anyone taken —
+         * rather than a proxy for it.
+         */
+        const from = Math.max(this.nextOrdinalFor(goalId), (await this.highestClaim(goalId)) + 1);
+        /**
+         * Bounded, because an unbounded loop against a filesystem is a hang. The
+         * bound is the number of runs that could have taken a number between this
+         * one's read and its write; sixty-four is far past any real machine, and
+         * exhausting it yields the unsynchronised answer rather than failing the run.
+         */
+        for (let ordinal = from; ordinal < from + 64; ordinal++) {
+            try {
+                await this.fs.createExclusive(this.ordinalPath(goalId, ordinal), `${JSON.stringify({ goalId, ordinal, pid: process.pid, at: new Date(this.now()).toISOString() })}\n`);
+                return ordinal;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    return this.nextOrdinalFor(goalId);
+            }
+        }
+        return from;
+    }
+    /**
+     * Record what one attempt achieved, and say whether that makes it unsafe to
+     * continue.
+     *
+     * The verdict is computed from what is now on disk rather than from the
+     * caller's belief, so a caller that forgets to persist cannot produce a
+     * verdict about a history that does not exist.
+     */
+    async observe(o) {
+        if (!this.opened)
+            throw new Error('LoopSafetyStore.observe before open()');
+        /**
+         * ⚠️ THERE USED TO BE AN `unreadable` GUARD HERE, AND ITS REASON DIED WITH
+         * THE REWRITE. It said "refuse to rewrite a file we could not read" — true
+         * and load-bearing while `observe` rewrote the whole document, and false the
+         * moment the history became an append-only ledger. A mutation battery found
+         * it: deleting the guard changed no test, because there was no longer
+         * anything for it to protect.
+         *
+         * What it did instead was DISCARD EVIDENCE. An unreadable incidents document
+         * is no reason to stop recording what a run achieved: appending cannot
+         * corrupt anything, and `raise()` still refuses to create an incident from a
+         * document it could not read, so nothing is decided on bad information.
+         *
+         * A guard whose stated reason has stopped being true is worse than no guard.
+         * It reads as protection and is not, and the next person to touch this file
+         * would have reasoned from the comment rather than from the code.
+         */
+        /**
+         * Append, then RE-READ before judging. The re-read is what makes the verdict
+         * a fact about the machine rather than about this process: another writer's
+         * attempt is on disk and not in this object's memory, and a detector that
+         * counted only its own caller's attempts would hold a pursuit late by
+         * exactly as many attempts as the other writer made.
+         */
+        /**
+         * 🔴 LED BY A NEWLINE, NOT MERELY TERMINATED BY ONE — and a test written to
+         * check a torn append is what found this. A crash part-way through a write
+         * leaves a fragment with no trailing newline; the NEXT record then appends
+         * straight onto it and the two become one unparseable line, so a single
+         * torn write cost TWO attempts rather than one.
+         *
+         * Leading each record instead means a fragment always ends up alone on its
+         * line and is skipped by itself. The blank line this leaves in the ordinary
+         * case is skipped by the same rule, which is why this needs no read of the
+         * file first and so stays safe against another writer appending at the same
+         * moment.
+         */
+        /**
+         * ⚠️ `mkdir` FIRST, WHICH `raise` AND `record` BOTH DO AND THIS DID NOT.
+         *
+         * It never mattered while the directory was inside a checkout that had to
+         * exist for the run to start. The machine-level home does not: on a fresh
+         * machine the first thing that touches it is this append, and an ENOENT
+         * here is not caught anywhere on the path from `runLoop`.
+         */
+        await this.fs.mkdir(this.stateDir);
+        await this.fs.appendFile(this.eventsPath, `\n${JSON.stringify(o)}\n`);
+        await this.loadObservations();
+        // Named explicitly rather than relying on the caller's history happening to
+        // hold one pursuit: this store holds every goal on the machine.
+        return (0, core_1.evaluateLoopSafety)({
+            observations: this.observations,
+            goalVersion: o.goalVersion,
+            goalId: o.goalId,
+        });
+    }
+    /**
+     * Write down that autonomy has stopped, and why.
+     *
+     * Idempotent on the pursuit: a second derivation while one is already active
+     * returns the existing incident rather than stacking. Two holds for one
+     * stuck condition would need two overrides to clear, and a person would have
+     * to press the button twice for reasons nobody could explain.
+     */
+    async raise(input) {
+        if (!this.opened)
+            throw new Error('LoopSafetyStore.raise before open()');
+        if (this.state === 'unreadable')
+            return null;
+        const existing = this.activeIncident(input.goalId, input.goalVersion);
+        if (existing !== null)
+            return existing;
+        const at = new Date(this.now()).toISOString();
+        const incident = {
+            // Derived from the pursuit and the moment, so two machines cannot mint
+            // the same id and a person can find it in a log.
+            /**
+             * 🔴 NOT `incidents.length + 1`, AND THE REASON IS WORSE THAN A COLLISION.
+             *
+             * That counted each writer's OWN snapshot, so two concurrent raises minted
+             * the identical id. The override marker is keyed by id, is permanent, and
+             * is exclusive-create — so an id reused by a LATER generation finds a
+             * months-old marker waiting for it, and a genuinely new stuck-loop hold is
+             * discharged at birth. Measured: raise, override, lose the document to a
+             * concurrent writer, raise again — and the fresh hold reads as already
+             * overridden. The brake applies and releases itself, silently.
+             *
+             * Unique per raise, and within [A-Za-z0-9_-] because it becomes a filename.
+             */
+            id: `safety-${input.goalId}-${input.goalVersion}-${this.incidentToken()}`,
+            goalId: input.goalId,
+            goalVersion: input.goalVersion,
+            kind: input.kind,
+            because: input.because,
+            evidence: [...input.evidence],
+            triggeredAt: at,
+        };
+        this.incidents.push(incident);
+        // APPENDED, never rewritten. See `incidentsPath`.
+        await this.fs.mkdir(this.stateDir);
+        /**
+         * 🔴 LED BY A NEWLINE, LIKE THE EVENTS FILE, AND FOR THE SAME REASON.
+         *
+         * This was terminated by one only. A crash part-way through a write leaves
+         * a fragment with no trailing newline; the NEXT incident then appends
+         * straight onto it and the two become one unparseable line — so a torn
+         * write costs TWO incidents rather than one, and an incident is a HOLD. The
+         * events file worked this out and wrote it down; incidents never followed,
+         * because until Phase 1 there could not be two writers here.
+         *
+         * `loadIncidents` already skips blank lines, so the extra newline in the
+         * ordinary case costs nothing.
+         */
+        await this.fs.appendFile(this.incidentsPath, `\n${JSON.stringify(incident)}\n`);
+        return incident;
+    }
+    /**
+     * A PERSON SPENDS AN INCIDENT'S ONE RETRY.
+     *
+     * 🔴 EXCLUSIVE CREATE, AND NOTHING ELSE. Two Starts arriving together must not
+     * both believe they may proceed, and the filesystem is what arbitrates —
+     * never a read-then-write, and never an in-memory flag, because the two Starts
+     * may be two processes. The same Start asking twice gets the same answer, so
+     * a dropped response cannot cost a person their retry.
+     *
+     * ⚠️ ONE RETRY, NOT "SAFETY OFF". The incident is marked as spent rather than
+     * deleted, and the observation history is left exactly where it is. If the
+     * authorised Run also achieves nothing, the detectors see the whole history
+     * and raise a NEW incident — which is the difference between a person saying
+     * "try once more" and a person disabling a brake.
+     */
+    async override(incidentId, startId) {
+        if (!this.opened)
+            throw new Error('LoopSafetyStore.override before open()');
+        if (this.state === 'unreadable') {
+            return { ok: false, because: 'the safety history could not be read' };
+        }
+        if (/[^A-Za-z0-9_-]/.test(incidentId)) {
+            // Path safety, not validation theatre: the id becomes a filename.
+            return { ok: false, because: `${incidentId} is not a usable incident id` };
+        }
+        const found = this.incidents.find((i) => i.id === incidentId);
+        if (found === undefined)
+            return { ok: false, because: 'no such safety incident' };
+        if (found.overriddenByStartId !== undefined && found.overriddenByStartId !== startId) {
+            return { ok: false, because: 'another Start already took this one retry' };
+        }
+        await this.fs.mkdir(`${this.stateDir}/loop-safety-overrides`);
+        try {
+            await this.fs.createExclusive(this.overridePath(incidentId), `${JSON.stringify({ incidentId, startId, at: new Date(this.now()).toISOString() }, null, 2)}\n`);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            // Somebody holds it. The SAME Start asking again is a dropped response,
+            // not a rival — anything else is the second Start and must be refused.
+            const held = await this.readOverride(incidentId);
+            if (held === null) {
+                /**
+                 * FAILS CLOSED, AND SAYS HOW TO GET OUT. We cannot tell whether the one
+                 * retry was spent, and guessing "not spent" would hand out a second.
+                 * But refusing without naming a way forward leaves a person stuck at a
+                 * sentence — amending the Goal starts a new version, which this hold
+                 * does not cover, and that is the door they cannot see from here.
+                 */
+                return {
+                    ok: false,
+                    because: 'the record of this retry cannot be read, so it cannot be given out again — change the goal to start a fresh version',
+                };
+            }
+            if (held !== startId)
+                return { ok: false, because: 'another Start already took this one retry' };
+        }
+        const spent = { ...found, overriddenByStartId: startId };
+        this.incidents = this.incidents.map((i) => (i.id === incidentId ? spent : i));
+        /**
+         * NO DOCUMENT WRITE. The exclusively-created marker above IS the record that
+         * this retry was spent, and `foldInSpentRetries` reads it back at every
+         * open — so persisting here would add nothing but a second whole-document
+         * rewrite racing every concurrent raise.
+         */
+        return { ok: true, incident: spent };
+    }
+    /**
+     * Read the attempt history from the append-only ledger.
+     *
+     * Bounded IN MEMORY rather than on disk: the file is never rewritten, so the
+     * only place a bound can be applied without a rewrite is here. `carried` is
+     * whatever an older build left in the document, and goes first because it is
+     * older than anything in the ledger.
+     *
+     * 🔴 A BAD LINE IS SKIPPED, NOT FATAL — and that is the opposite of how this
+     * class treats a bad INCIDENTS document, deliberately. A torn final line is
+     * what a crash mid-append leaves, and it costs one observation, which is the
+     * bounded loss this design already accepts. Refusing to read the history over
+     * it would report NO active incident and so discharge every hold on the
+     * machine, which is the one direction that must never fail open. The
+     * incidents document still fails closed; it is what holds are made of.
+     */
+    async loadObservations(carried = []) {
+        let text = null;
+        try {
+            text = await this.fs.readFile(this.eventsPath);
+        }
+        catch {
+            text = null;
+        }
+        const fromLedger = [];
+        for (const line of (text ?? '').split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (isObservation(parsed))
+                    fromLedger.push(parsed);
+            }
+            catch {
+                // A torn write. See above: one attempt, not the whole history.
+            }
+        }
+        /**
+         * 🔴 BOUNDED PER PURSUIT, AND A GLOBAL BOUND HERE WAS A REAL DEFECT. The
+         * daemon runs up to `MAX_CONTROLLERS_PER_TICK` controllers, so several goals
+         * interleave attempts into this one ledger. Keeping the newest sixteen
+         * ACROSS ALL OF THEM let a busy pursuit evict a quiet one's history before
+         * it ever reached the three barren attempts `no_progress` needs — so the
+         * brake switched itself off on the machine doing the most work, silently,
+         * with nothing anywhere going red.
+         *
+         * Per goal, the window means what it says: sixteen attempts of THIS pursuit.
+         * Memory stays bounded at sixteen times the number of goals the ledger
+         * mentions, which is a machine's real workload rather than its uptime.
+         */
+        const byGoal = new Map();
+        for (const o of [...carried, ...fromLedger]) {
+            const mine = byGoal.get(o.goalId);
+            if (mine === undefined)
+                byGoal.set(o.goalId, [o]);
+            else
+                mine.push(o);
+        }
+        const kept = [];
+        for (const mine of byGoal.values()) {
+            kept.push(...(mine.length > core_1.MAX_SAFETY_OBSERVATIONS
+                ? mine.slice(mine.length - core_1.MAX_SAFETY_OBSERVATIONS)
+                : mine));
+        }
+        this.observations = kept;
+    }
+    /**
+     * Mark every incident whose retry has already been taken.
+     *
+     * 🔴 THE MARKER FILE IS THE AUTHORITY; THE FIELD IS A CACHE. `persist()`
+     * rewrites the whole document, so a writer that loaded before another
+     * writer's write clobbers it — and the daemon spending a retry while a run
+     * records what it achieved is not an exotic interleaving, it is what happens
+     * every time somebody presses Start as a run ends. The field really is lost
+     * there; it is measured in `loop-safety-race.spec.ts`.
+     *
+     * What cannot be lost is `loop-safety-overrides/<id>`, because it is written
+     * with an exclusive create and never rewritten. So the document is believed
+     * about WHAT was raised, and the marker files about WHICH retries are spent.
+     * Reading them here keeps `activeIncident` synchronous for its callers.
+     *
+     * Bounded by the incident count rather than by anything a person can grow: a
+     * pursuit has one active incident at a time, and only unspent ones are asked
+     * about.
+     */
+    /**
+     * Fold the append-only incident log over whatever the legacy document held.
+     *
+     * A malformed line is SKIPPED rather than fatal: an append can be torn by a
+     * crash mid-write, and discarding every hold on the strength of one truncated
+     * last line would be the fail-open this whole file exists to prevent.
+     */
+    async loadIncidents() {
+        let text;
+        try {
+            text = await this.fs.readFile(this.incidentsPath);
+        }
+        catch {
+            this.state = 'unreadable';
+            return;
+        }
+        if (text === null)
+            return;
+        const known = new Set(this.incidents.map((i) => i.id));
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (!isIncident(parsed))
+                    continue;
+                if (known.has(parsed.id))
+                    continue;
+                known.add(parsed.id);
+                this.incidents.push(parsed);
+            }
+            catch {
+                // A torn final line. Everything before it still counts.
+            }
+        }
+    }
+    async foldInSpentRetries() {
+        const unspent = this.incidents.filter((i) => i.overriddenByStartId === undefined);
+        if (unspent.length === 0)
+            return;
+        const spent = await Promise.all(unspent.map(async (i) => ({ id: i.id, startId: await this.readOverride(i.id) })));
+        const byId = new Map(spent.filter((x) => x.startId !== null).map((x) => [x.id, x.startId]));
+        if (byId.size === 0)
+            return;
+        this.incidents = this.incidents.map((i) => {
+            const startId = byId.get(i.id);
+            return startId === undefined ? i : { ...i, overriddenByStartId: startId };
+        });
+    }
+    async readOverride(incidentId) {
+        let text;
+        try {
+            text = await this.fs.readFile(this.overridePath(incidentId));
+        }
+        catch {
+            return null;
+        }
+        if (text === null)
+            return null;
+        try {
+            const parsed = JSON.parse(text);
+            return typeof parsed.startId === 'string' ? parsed.startId : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async persist() {
+        await this.fs.mkdir(this.stateDir);
+        /**
+         * Temp-then-rename, with a name PRIVATE TO THIS WRITER. A shared
+         * `loop-safety.json.tmp` is some other writer's half-written file, and
+         * renaming that over the real one is exactly the corruption the rename
+         * exists to prevent.
+         */
+        const tmp = `${this.path}.${process.pid}.${(LoopSafetyStore.writes += 1)}.tmp`;
+        // Incidents ONLY. Observations live in the append-only ledger; writing them
+        // here as well would reintroduce the clobber under a second name.
+        const body = { incidents: this.incidents };
+        await this.fs.writeFile(tmp, `${JSON.stringify(body, null, 2)}\n`);
+        await this.fs.rename(tmp, this.path);
+    }
+}
+exports.LoopSafetyStore = LoopSafetyStore;
+/**
+ * The real filesystem, in the shape this store needs.
+ *
+ * `createExclusive` is the whole argument for a separate factory: it is the one
+ * operation that must be atomic against another PROCESS, and it is spelled with
+ * the `wx` flag rather than a read-then-write for exactly that reason.
+ */
+exports.nodeSafetyFs = {
+    readFile: async (path) => {
+        const { readFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    },
+    appendFile: async (path, data) => {
+        const { appendFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        await appendFile(path, data, 'utf8');
+    },
+    writeFile: async (path, data) => {
+        const { writeFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        await writeFile(path, data, 'utf8');
+    },
+    rename: async (from, to) => {
+        const { rename } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        await rename(from, to);
+    },
+    mkdir: async (path) => {
+        const { mkdir } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        await mkdir(path, { recursive: true });
+    },
+    readDir: async (path) => {
+        const { readdir } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        try {
+            return await readdir(path);
+        }
+        catch {
+            return [];
+        }
+    },
+    createExclusive: async (path, data) => {
+        const { writeFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        await writeFile(path, data, { encoding: 'utf8', flag: 'wx' });
+    },
+};
+//# sourceMappingURL=loop-safety-store.js.map