looply-cli 0.0.0-stage → 0.3.0

package/dist/run-refusal-marks.d.ts

@@ -0,0 +1,189 @@
+import { type RunRefusalCode } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * Why a command's run refused, carried from the run process to the daemon.
+ *
+ * The run process knows exactly why it would not start — the goal's work is
+ * finished, or it is stalled, or the goal was abandoned, or the queue holds a
+ * plan for a version this Start has been overtaken by. It says so in the
+ * message of the `RunRefused` it throws, and `bin.ts` writes that message to
+ * stderr on its way out.
+ *
+ * Nobody was listening. The daemon spawns the run with `stdio: 'ignore'`
+ * (run-launcher.ts), because the child is detached and outlives the parent — so
+ * the words went nowhere at all, and the launcher reported the only thing it
+ * could see: `the run exited — exit 3`. That reached the server as a bare
+ * `outcome: 'refused'` with no reason, which made "your goal is done" and "your
+ * goal is wedged" the same answer on the phone. This file is the missing
+ * channel.
+ *
+ * WHY A FILE, and not the child's output: there is no output. Changing the
+ * spawn to pipe stderr would mean holding streams open on a deliberately
+ * detached process, and then treating whatever a run happens to print — agent
+ * transcripts, git errors, stack traces — as a client-readable string. A
+ * refusal is a decision, not a log line, so it is written down as one, and only
+ * an intentional `RunRefused` is ever written here.
+ *
+ * The shape is deliberately {@link RunStartMarks}': written by the RUN process,
+ * read by the DAEMON, keyed by the command that asked, capped, schema-tagged,
+ * and discarded rather than thrown over if it cannot be read. One writer and
+ * one reader per file, so neither can lose the other's updates.
+ */
+export declare const RUN_REFUSAL_MARKS_SCHEMA = 1;
+export interface RunRefusalMark {
+    /**
+     * The request whose run refused. The identity of the attempt, as with starts.
+     *
+     * NAMED `commandId` FOR THE DISK, not because it is a server command. It
+     * carries whatever execution identity asked for the run — a command id when a
+     * person tapped Start, `autonomyStartId(C, N)` when a controller spent an
+     * ordinal. Renaming the field would be silently destructive: `isMark` below
+     * drops rows one by one and `load` still succeeds on the untouched schema
+     * tag, so every existing refusal would vanish with no error and no log line.
+     */
+    commandId: string;
+    /** The `RunRefused` message, verbatim — this is what a person ends up reading. */
+    reason: string;
+    /** When the run refused, from the run's own clock. */
+    at: string;
+    /**
+     * WHY, as a machine reads it.
+     *
+     * The run knows exactly which refusal this is — it throws `RunRefused` with a
+     * `RunRefusalCode` at every site — and until 6D2A that knowledge died at the
+     * process boundary: `bin.ts` recorded the message and dropped the code, so the
+     * only thing that survived to the daemon was an English sentence.
+     *
+     * That was tolerable while the sole reader was a phone, which wants the
+     * sentence anyway. It is not tolerable for a controller, whose next move
+     * differs completely between "the goal is met" and "only a person can move
+     * this" — and which must never decide that by matching words.
+     *
+     * OPTIONAL, so every record written before this field existed is still a
+     * valid mark rather than a row silently dropped by the guard below. A refusal
+     * with no code is readable and reportable; it simply may not drive a terminal
+     * decision.
+     */
+    code?: RunRefusalCode;
+    /**
+     * The run's branch, when the run had one (M5-2).
+     *
+     * A terminal refusal is the run's LAST word, and for `goal_satisfied` the
+     * word that matters next is whose branch carries the work: the daemon, when
+     * it integrates for itself, will not close the grant until the lane has
+     * published that branch, and this is the only place the name crosses the
+     * process boundary.
+     *
+     * OPTIONAL, like `code`, so every mark written before it existed is still a
+     * mark. Absent means UNKNOWN — a branch that cannot be named cannot be shown
+     * published, so a grant whose caller asks for the third key is held and told
+     * why; a caller that does not ask never reads this field.
+     */
+    branch?: string;
+    /**
+     * WHAT KEY 2 SAW, for a `goal_satisfied` refusal only (L4b).
+     *
+     * The claim "this goal was met" crosses to the server as one state word, and
+     * the facts it rests on — which run delivered, at which commit, and how each
+     * required gate step came out — stayed on this machine. This is the same
+     * channel the branch rides (M5-2), so the daemon can hand them on when it
+     * settles the pursuit, instead of a fixed sentence.
+     *
+     * OPTIONAL, and a malformed one is DROPPED rather than the whole mark: the
+     * refusal is still true and its code still drives the controller; only the
+     * supporting facts are lost, and losing them must not cost the decision.
+     */
+    delivery?: RunDelivery;
+}
+/** One gate step's outcome as key 2 recorded it. `skipped` is not `passed`. */
+export type DeliveredCheck = 'passed' | 'failed' | 'skipped';
+/** The delivering run, the commit HEAD was on, and the required steps' outcomes. */
+export interface RunDelivery {
+    runId: string;
+    sha: string;
+    checks: Record<string, DeliveredCheck>;
+}
+/** A delivery this build can read, or null. Exported so the server-bound copy is judged by the same rule. */
+export declare function readDelivery(v: unknown): RunDelivery | null;
+/**
+ * How many to keep. Smaller than the start marks' fifty because a refusal is
+ * read once, on the poll after the child exits, and never needed again.
+ */
+export declare const MAX_REFUSALS = 50;
+/**
+ * A ceiling on the stored reason.
+ *
+ * Not defensive theatre: `Command.reason` is client-readable and this file is
+ * meant to stay a few kilobytes for ever, so the one place the machine decides
+ * what a client will read is the right place to bound it. Every reason today is
+ * a template with bounded interpolations — state counts, a goal id, a version,
+ * an item id — so this should never fire; it exists so that a future refusal
+ * built from something larger cannot quietly turn a dedupe file into a log.
+ */
+export declare const MAX_REASON = 500;
+export declare class RunRefusalMarks {
+    private readonly stateDir;
+    private readonly fs;
+    /** A discarded file is worth saying once, not silently. */
+    private readonly log?;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private refusals;
+    constructor(stateDir: string, fs: LedgerFs, 
+    /** A discarded file is worth saying once, not silently. */
+    log?: ((line: string) => void) | undefined);
+    private get path();
+    /**
+     * THE APPEND-ONLY LOG BESIDE THE CAPPED INDEX.
+     *
+     * 🔴 THE SAME LOST-UPDATE CLASS THE START MARKS HAD, for the same reason:
+     * this channel is now PROJECT-scoped, so every concurrent run in the project
+     * writes it, and the index is a whole-document rewrite. Two runs refusing in
+     * the same instant lose one of the two reasons — and a lost reason is a
+     * refusal reported in the plainer wording with no `code`, which strips a
+     * caller of the right to conclude anything about the goal.
+     *
+     * ⚠️ THE INDEX IS KEPT, NOT REPLACED: it bounds the file and an older build
+     * reads it. `load` merges both.
+     */
+    private get logPath();
+    /**
+     * Read what is on disk.
+     *
+     * Anything unreadable or wrongly shaped is DISCARDED rather than thrown over,
+     * exactly like the start marks and the goal mirror. Losing this file costs a
+     * reason, never a decision: the launcher still knows the child exited 3 and
+     * still reports the refusal terminally, just with the plainer wording it used
+     * before this file existed. It can never turn a refusal into a success.
+     */
+    load(): Promise<void>;
+    /**
+     * Fold the append-only log into what the index said.
+     *
+     * ⚠️ THE INDEX WINS ON CONFLICT. `record` REPLACES a command's earlier
+     * refusal, so the index holds the newest for every command it knows; the log
+     * only supplies commands the index lost entirely.
+     */
+    private mergeLog;
+    /**
+     * Why this command's run refused, if it did.
+     *
+     * By command id and nothing else. A refusal belongs to the request that
+     * produced it: the same rule that stops one command inheriting another's
+     * proof of starting stops it inheriting another's reason for not.
+     */
+    find(commandId: string): RunRefusalMark | null;
+    all(): RunRefusalMark[];
+    /**
+     * Write down why a command's run refused.
+     *
+     * The LAST refusal wins, where a start mark keeps the first. The asymmetry is
+     * real rather than an oversight: a run cannot start twice for one request, so
+     * the first start mark is the only true one — but a command redelivered after
+     * a daemon restart is genuinely launched again, and the second attempt may
+     * refuse for a different reason than the first. Reporting the older one would
+     * describe a machine that no longer exists.
+     */
+    record(mark: RunRefusalMark): Promise<void>;
+}
+//# sourceMappingURL=run-refusal-marks.d.ts.map

package/dist/run-refusal-marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-refusal-marks.d.ts","sourceRoot":"","sources":["../src/run-refusal-marks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACxC;AAID,6GAA6G;AAC7G,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAY3D;AAOD;;;GAGG;AACH,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,qBAAa,eAAe;IAOxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IATvB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,QAAQ,CAAwB;gBAGrB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAC7B,2DAA2D;IAC1C,GAAG,CAAC,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,aAAA;IAG/C,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;;;;;OAYG;IACH,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB3B;;;;;;OAMG;YACW,QAAQ;IAuBtB;;;;;;OAMG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI9C,GAAG,IAAI,cAAc,EAAE;IAIvB;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAsBlD"}

package/dist/run-refusal-marks.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunRefusalMarks = exports.MAX_REASON = exports.MAX_REFUSALS = exports.RUN_REFUSAL_MARKS_SCHEMA = void 0;
+exports.readDelivery = readDelivery;
+const core_1 = require("@looply/core");
+/**
+ * Why a command's run refused, carried from the run process to the daemon.
+ *
+ * The run process knows exactly why it would not start — the goal's work is
+ * finished, or it is stalled, or the goal was abandoned, or the queue holds a
+ * plan for a version this Start has been overtaken by. It says so in the
+ * message of the `RunRefused` it throws, and `bin.ts` writes that message to
+ * stderr on its way out.
+ *
+ * Nobody was listening. The daemon spawns the run with `stdio: 'ignore'`
+ * (run-launcher.ts), because the child is detached and outlives the parent — so
+ * the words went nowhere at all, and the launcher reported the only thing it
+ * could see: `the run exited — exit 3`. That reached the server as a bare
+ * `outcome: 'refused'` with no reason, which made "your goal is done" and "your
+ * goal is wedged" the same answer on the phone. This file is the missing
+ * channel.
+ *
+ * WHY A FILE, and not the child's output: there is no output. Changing the
+ * spawn to pipe stderr would mean holding streams open on a deliberately
+ * detached process, and then treating whatever a run happens to print — agent
+ * transcripts, git errors, stack traces — as a client-readable string. A
+ * refusal is a decision, not a log line, so it is written down as one, and only
+ * an intentional `RunRefused` is ever written here.
+ *
+ * The shape is deliberately {@link RunStartMarks}': written by the RUN process,
+ * read by the DAEMON, keyed by the command that asked, capped, schema-tagged,
+ * and discarded rather than thrown over if it cannot be read. One writer and
+ * one reader per file, so neither can lose the other's updates.
+ */
+exports.RUN_REFUSAL_MARKS_SCHEMA = 1;
+const DELIVERED_CHECKS = ['passed', 'failed', 'skipped'];
+/** A delivery this build can read, or null. Exported so the server-bound copy is judged by the same rule. */
+function readDelivery(v) {
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const d = v;
+    if (typeof d['runId'] !== 'string' || typeof d['sha'] !== 'string')
+        return null;
+    const c = d['checks'];
+    if (typeof c !== 'object' || c === null || Array.isArray(c))
+        return null;
+    const checks = {};
+    for (const [step, outcome] of Object.entries(c)) {
+        if (typeof outcome !== 'string' || !DELIVERED_CHECKS.includes(outcome))
+            return null;
+        checks[step] = outcome;
+    }
+    return { runId: d['runId'], sha: d['sha'], checks };
+}
+/**
+ * How many to keep. Smaller than the start marks' fifty because a refusal is
+ * read once, on the poll after the child exits, and never needed again.
+ */
+exports.MAX_REFUSALS = 50;
+/**
+ * A ceiling on the stored reason.
+ *
+ * Not defensive theatre: `Command.reason` is client-readable and this file is
+ * meant to stay a few kilobytes for ever, so the one place the machine decides
+ * what a client will read is the right place to bound it. Every reason today is
+ * a template with bounded interpolations — state counts, a goal id, a version,
+ * an item id — so this should never fire; it exists so that a future refusal
+ * built from something larger cannot quietly turn a dedupe file into a log.
+ */
+exports.MAX_REASON = 500;
+class RunRefusalMarks {
+    stateDir;
+    fs;
+    log;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    refusals = [];
+    constructor(stateDir, fs, 
+    /** A discarded file is worth saying once, not silently. */
+    log) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.log = log;
+    }
+    get path() {
+        return `${this.stateDir}/run-refusals.json`;
+    }
+    /**
+     * THE APPEND-ONLY LOG BESIDE THE CAPPED INDEX.
+     *
+     * 🔴 THE SAME LOST-UPDATE CLASS THE START MARKS HAD, for the same reason:
+     * this channel is now PROJECT-scoped, so every concurrent run in the project
+     * writes it, and the index is a whole-document rewrite. Two runs refusing in
+     * the same instant lose one of the two reasons — and a lost reason is a
+     * refusal reported in the plainer wording with no `code`, which strips a
+     * caller of the right to conclude anything about the goal.
+     *
+     * ⚠️ THE INDEX IS KEPT, NOT REPLACED: it bounds the file and an older build
+     * reads it. `load` merges both.
+     */
+    get logPath() {
+        return `${this.stateDir}/run-refusals.jsonl`;
+    }
+    /**
+     * Read what is on disk.
+     *
+     * Anything unreadable or wrongly shaped is DISCARDED rather than thrown over,
+     * exactly like the start marks and the goal mirror. Losing this file costs a
+     * reason, never a decision: the launcher still knows the child exited 3 and
+     * still reports the refusal terminally, just with the plainer wording it used
+     * before this file existed. It can never turn a refusal into a success.
+     */
+    async load() {
+        const text = await this.fs.readFile(this.path);
+        if (text === null) {
+            this.refusals = [];
+            return;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                parsed.schema !== exports.RUN_REFUSAL_MARKS_SCHEMA ||
+                !Array.isArray(parsed.refusals)) {
+                throw new Error('not a refusal file');
+            }
+            this.refusals = parsed.refusals.filter(isMark).map(sanitise);
+        }
+        catch (e) {
+            this.log?.(`run-refusals: discarding an unreadable file (${e.message})`);
+            this.refusals = [];
+        }
+        await this.mergeLog();
+    }
+    /**
+     * Fold the append-only log into what the index said.
+     *
+     * ⚠️ THE INDEX WINS ON CONFLICT. `record` REPLACES a command's earlier
+     * refusal, so the index holds the newest for every command it knows; the log
+     * only supplies commands the index lost entirely.
+     */
+    async mergeLog() {
+        let text;
+        try {
+            text = await this.fs.readFile(this.logPath);
+        }
+        catch {
+            return;
+        }
+        if (text === null)
+            return;
+        const known = new Set(this.refusals.map((m) => m.commandId));
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (!isMark(parsed) || known.has(parsed.commandId))
+                    continue;
+                known.add(parsed.commandId);
+                this.refusals.push(sanitise(parsed));
+            }
+            catch {
+                // A fragment from a torn write. Skipped by itself.
+            }
+        }
+    }
+    /**
+     * Why this command's run refused, if it did.
+     *
+     * By command id and nothing else. A refusal belongs to the request that
+     * produced it: the same rule that stops one command inheriting another's
+     * proof of starting stops it inheriting another's reason for not.
+     */
+    find(commandId) {
+        return this.refusals.find((m) => m.commandId === commandId) ?? null;
+    }
+    all() {
+        return [...this.refusals];
+    }
+    /**
+     * Write down why a command's run refused.
+     *
+     * The LAST refusal wins, where a start mark keeps the first. The asymmetry is
+     * real rather than an oversight: a run cannot start twice for one request, so
+     * the first start mark is the only true one — but a command redelivered after
+     * a daemon restart is genuinely launched again, and the second attempt may
+     * refuse for a different reason than the first. Reporting the older one would
+     * describe a machine that no longer exists.
+     */
+    async record(mark) {
+        const trimmed = { ...mark, reason: mark.reason.slice(0, exports.MAX_REASON) };
+        // Newest first, so the cap drops the oldest.
+        const next = [trimmed, ...this.refusals.filter((m) => m.commandId !== mark.commandId)].slice(0, exports.MAX_REFUSALS);
+        const body = { schema: exports.RUN_REFUSAL_MARKS_SCHEMA, refusals: next };
+        await this.fs.mkdir(this.stateDir);
+        // The durable write first, and it is the append. See `logPath`.
+        await this.fs.appendFile(this.logPath, `\n${JSON.stringify(trimmed)}\n`);
+        // Temp-then-rename, the same contract as every other store here: the daemon
+        // reads this file from another process and must never catch half of it.
+        // The temp name is PRIVATE TO THIS WRITER. A shared `run-refusals.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}.${(RunRefusalMarks.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(body, null, 2) + '\n');
+        await this.fs.rename(tmp, this.path);
+        // Committed to memory only after the durable write, so a failed write
+        // cannot leave this object claiming a mark the file does not have.
+        this.refusals = next;
+    }
+}
+exports.RunRefusalMarks = RunRefusalMarks;
+function isMark(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const m = v;
+    if (typeof m['commandId'] !== 'string' || typeof m['reason'] !== 'string')
+        return false;
+    if (typeof m['at'] !== 'string')
+        return false;
+    // Absent is fine — that is every record written before 6D2A, and a mark with
+    // no code is still a true refusal. PRESENT AND UNRECOGNISED is not: a word
+    // this build does not know would be handed to a decision table that has no
+    // entry for it, so the row is rejected and the refusal degrades to reason-only
+    // rather than to a guess.
+    if (m['code'] !== undefined && !(0, core_1.isRunRefusalCode)(m['code']))
+        return false;
+    // The same rule for the branch (M5-2): absent is every older mark; present
+    // and not a string is a row this build cannot read, not a branch to guess at.
+    if (m['branch'] !== undefined && typeof m['branch'] !== 'string')
+        return false;
+    // A delivery this build cannot read is stripped in `sanitise`, never fatal
+    // to the mark — see `RunRefusalMark.delivery`.
+    return true;
+}
+/** Drop an unreadable delivery, keep the refusal. */
+function sanitise(m) {
+    if (m.delivery === undefined)
+        return m;
+    const d = readDelivery(m.delivery);
+    if (d !== null)
+        return { ...m, delivery: d };
+    const { delivery: _dropped, ...rest } = m;
+    return rest;
+}
+//# sourceMappingURL=run-refusal-marks.js.map

package/dist/run-refusal-marks.js.map

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

package/dist/run-start-marks.d.ts

@@ -0,0 +1,153 @@
+import type { AnyEventInput, LedgerFs } from './ledger-store';
+/**
+ * Durable proof that a start-run command actually produced a Run.
+ *
+ * The daemon used to treat "the child it spawned was still alive 750ms later"
+ * as evidence that a run had started, and acked the command terminally on it.
+ * It is not evidence. A goal-bound run resolves its goal, takes the lease,
+ * adopts items and verifies drafts before a Run exists — verification alone
+ * calls an agent and can take minutes, and can still end in "nothing to do".
+ * Every one of those paths exits without a Run, long after the window closed,
+ * leaving a command acked done that nothing will ever carry out.
+ *
+ * So the run process says so itself, at the only moment that means anything:
+ * when `run.started` is durably appended to the ledger. That event IS the
+ * accepted start boundary — the server creates its Run row from it, and it is
+ * emitted after the dirty-tree check and after the branch exists.
+ *
+ * WHY A SEPARATE FILE, and not the ledger the mark is derived from: the daemon
+ * needs to answer "did command C produce a run" cheaply, on every poll, for a
+ * command whose run may have finished hours ago. The ledger answers it only by
+ * scanning, and grows without bound. This is a small, capped index over one
+ * question. It is also written by the RUN process, where `commands.json` is
+ * written by the daemon — one writer each, so neither can lose the other's
+ * updates.
+ */
+export declare const RUN_START_MARKS_SCHEMA = 1;
+export interface RunStartMark {
+    /** The start-run command that asked for this run. The identity of the request. */
+    commandId: string;
+    runId: string;
+    /** When `run.started` was appended, from the run's own clock. */
+    at: string;
+    /**
+     * WHERE THE RUN IS EXECUTING — the checkout whose `.looply/state` holds its
+     * ledger. Absent on marks written by builds before this field existed and
+     * read as "the project's own checkout", which is the only place those
+     * builds could have been running.
+     *
+     * 🔴 THE DURABLE LINK FROM A REQUEST TO ITS LEDGER. The registry record
+     * carries the workspace too, but a run gives that record back on its way out
+     * — AFTER writing `run.ended` — so for a run that ended normally the record
+     * is gone by the time the daemon asks where the ending is. The mark is
+     * written once, at registration, and is never released; it is the one
+     * project-scoped fact that survives the run and names its checkout.
+     */
+    workspace?: string;
+}
+/**
+ * How many to keep.
+ *
+ * Enough that a daemon which was down for a long time still finds the mark for
+ * anything the redelivery window could still be offering, and small enough that
+ * the file stays a few kilobytes for ever.
+ */
+export declare const MAX_MARKS = 50;
+export declare class RunStartMarks {
+    private readonly stateDir;
+    private readonly fs;
+    /** A discarded file is worth saying once, not silently. */
+    private readonly log?;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private marks;
+    /** Whether `load` has run. Recording before it would truncate the file. */
+    private loaded;
+    constructor(stateDir: string, fs: LedgerFs, 
+    /** A discarded file is worth saying once, not silently. */
+    log?: ((line: string) => void) | undefined);
+    private get path();
+    /**
+     * THE APPEND-ONLY LOG BESIDE THE CAPPED INDEX.
+     *
+     * 🔴 THE INDEX IS A WHOLE-DOCUMENT REWRITE, AND THIS FILE IS NOW SHARED BY
+     * EVERY CONCURRENT RUN IN THE PROJECT.
+     *
+     * The comment in `bin.ts` predicted precisely this: "A later phase that
+     * launches into workspaces must move this channel to project scope AND make
+     * it append-only first: it is a whole-document rewrite, so sharing it between
+     * concurrent runs without that is the lost-update class." This is that phase.
+     *
+     * Two runs that cross their start boundary in the same instant both read the
+     * index, both add themselves, and both rename their own copy into place. One
+     * mark survives. The daemon then reads no mark for the other request,
+     * concludes its Start "never began", and after three attempts escalates a
+     * perfectly healthy goal to `human_required` — the same visible failure the
+     * scope bug produced, arrived at by a race instead of a path.
+     *
+     * ⚠️ THE INDEX IS KEPT, NOT REPLACED. It is what bounds the file at
+     * `MAX_MARKS` and what an older build reads. The log is the durable truth and
+     * `load` merges both, so a mark the index lost is still found.
+     *
+     * ⚠️ LED BY A NEWLINE, for the reason `coordinator.recordActions` wrote down:
+     * a torn write must cost one record rather than two.
+     */
+    private get logPath();
+    /**
+     * Read what is on disk.
+     *
+     * Anything unreadable or wrongly shaped is DISCARDED rather than thrown over,
+     * exactly like the goal mirror. The cost of being wrong here is bounded and
+     * safe: without a mark the daemon cannot prove a run started, so it keeps the
+     * command queued rather than acking it — and the lease still stops a second
+     * runner. Losing this file delays an ack; it can never duplicate a run.
+     */
+    load(): Promise<void>;
+    /**
+     * Fold the append-only log into what the index said.
+     *
+     * ⚠️ THE LOG WINS ON PRESENCE, NOT ON ORDER. A mark is a fact that a request
+     * produced a run; there is no version of it to be newer or older. So a
+     * commandId already known keeps the entry it has, and one the index lost is
+     * added — which is the whole repair.
+     *
+     * ⚠️ A FRAGMENT FROM A TORN WRITE IS SKIPPED ALONE, which is what the leading
+     * newline buys, and an unreadable log leaves the index exactly as it was.
+     */
+    private mergeLog;
+    /** The run this command produced, if it produced one. */
+    find(commandId: string): RunStartMark | null;
+    /**
+     * The mark that names this run, if one does — the daemon's way from a runId
+     * back to the checkout that run is (or was) executing in.
+     */
+    findByRun(runId: string): RunStartMark | null;
+    all(): RunStartMark[];
+    /**
+     * Record that a command's run crossed the boundary.
+     *
+     * Re-recording the same command is a no-op rather than a second entry: the
+     * first mark is the one that is true, and a run cannot start twice for one
+     * request.
+     */
+    record(mark: RunStartMark): Promise<void>;
+}
+/** The one method the runner needs of its ledger. */
+export interface AppendsEvents {
+    append(input: AnyEventInput): Promise<unknown>;
+}
+/**
+ * A ledger that records the start mark when the run crosses the boundary.
+ *
+ * A decorator rather than a hook on RoundRunner, so the runner gains nothing at
+ * all: it appends `run.started` because that is what starting a run means, and
+ * this notices. The runner has no idea a command exists, which is the same
+ * reason it has no idea a goal does.
+ *
+ * The mark is written AFTER the event is durably appended. The other order
+ * would claim a run that the ledger might then fail to record.
+ */
+export declare function markingStartsOn(inner: AppendsEvents, marks: RunStartMarks, commandId: string, onError?: (e: Error) => void, 
+/** The checkout the run executes in, so a late mark still names its ledger. */
+workspace?: string): AppendsEvents;
+//# sourceMappingURL=run-start-marks.d.ts.map

package/dist/run-start-marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-start-marks.d.ts","sourceRoot":"","sources":["../src/run-start-marks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,qBAAa,aAAa;IAStB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IAXvB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,KAAK,CAAsB;IACnC,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAC7B,2DAA2D;IAC1C,GAAG,CAAC,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,aAAA;IAG/C,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B;;;;;;;;;;OAUG;YACW,QAAQ;IAuBtB,yDAAyD;IACzD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI5C;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI7C,GAAG,IAAI,YAAY,EAAE;IAIrB;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAuChD;AAaD,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI;AAC5B,+EAA+E;AAC/E,SAAS,CAAC,EAAE,MAAM,GACjB,aAAa,CAyBf"}