looply-cli 0.0.0-stage → 0.2.0

package/dist/status-cmd.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STALE_AFTER_MS = void 0;
+exports.parseStatusFile = parseStatusFile;
+exports.renderStatus = renderStatus;
+const core_1 = require("@looply/core");
+const gate_1 = require("./gate");
+/**
+ * `looply status` — a one-screen snapshot read from `status.json` and nothing
+ * else (DESIGN §5.2). Not the ledger, not the queue: the projection is the
+ * contract, and it is the same file a phone polls. If it cannot answer a
+ * question the screen needs, the fix belongs in the projection, never in a
+ * side-channel read here that only the CLI would benefit from.
+ *
+ * Pure text-in, text-out; the filesystem and the clock stay in `bin.ts`.
+ */
+/**
+ * The longest legal silence in a healthy run is one gate step running to its
+ * default timeout, so the stale window is that plus slack. DESIGN §12 case 25:
+ * a quiet run must read as STALE, not resting — a silent loop and a healthy
+ * one look identical otherwise.
+ */
+exports.STALE_AFTER_MS = (gate_1.DEFAULT_TIMEOUT_S + 300) * 1000;
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Shallow shape check only: the writer is our own `LedgerStore`, so this guard
+ * exists to catch a foreign or hand-edited file, not to re-validate our schema.
+ */
+function parseStatusFile(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(v))
+        return null;
+    if (!isRecord(v.totals) || typeof v.totals.rounds !== 'number')
+        return null;
+    if (!Array.isArray(v.openQuestions))
+        return null;
+    return v;
+}
+function liveness(s, now) {
+    if (!s.live)
+        return `ended (${s.stopReason ?? 'unknown'})`;
+    if (s.lastEventAt !== null && (0, core_1.isStale)(s, now, exports.STALE_AFTER_MS)) {
+        const min = Math.floor((now - Date.parse(s.lastEventAt)) / 60_000);
+        return `STALE — no event for ${min}min`;
+    }
+    return 'live';
+}
+function roundLine(s) {
+    if (s.round === null)
+        return s.live ? 'round   : between rounds' : 'round   : none';
+    const r = s.round;
+    const what = r.title ?? r.itemId ?? '(unknown item)';
+    return `round   : #${r.n} attempt ${r.attempt} — ${r.state ?? 'picked'} — ${what}`;
+}
+function renderStatus(text, now) {
+    if (text === null) {
+        return {
+            out: 'status  : no status.json yet — nothing has run here (try `looply doctor`, then `looply run`)\n',
+            code: 1,
+        };
+    }
+    const s = parseStatusFile(text);
+    if (s === null) {
+        // status.json is rewritten via temp-then-rename, so a half-written file
+        // cannot exist; unparseable means something other than looply wrote it.
+        // Refuse loudly rather than rendering a guess as if it were the run.
+        return { out: 'status  : status.json is not a looply projection — refusing to guess\n', code: 1 };
+    }
+    const lines = [];
+    /**
+     * 🔴 THE SAME WORD THE PHONE SHOWS, FROM THE SAME FUNCTION.
+     *
+     * This said "none recorded yet" off its own `runId === null` check while the
+     * route said nothing at all — so the two surfaces described an unstarted
+     * project differently, and the phone's version was wrong (it read as a
+     * finished run). `projectStanding` is in core precisely so a CLI-only
+     * side-channel cannot grow here: the owner's ruling is one vocabulary for
+     * both, and this is the CLI's half of it.
+     */
+    const standing = (0, core_1.projectStanding)(s);
+    if (standing === 'no-runs-yet') {
+        lines.push(`run     : ${(0, core_1.describeProjectStanding)(standing).toLowerCase()}`);
+    }
+    else if (s.runId === null) {
+        lines.push('run     : none recorded yet');
+    }
+    else {
+        lines.push(`run     : ${s.runId} on ${s.branch ?? '(no branch)'} — ${liveness(s, now)}`);
+        if (s.startedAt !== null)
+            lines.push(`started : ${s.startedAt}`);
+    }
+    lines.push(roundLine(s));
+    const t = s.totals;
+    lines.push(`tallies : ${t.rounds} rounds — ${t.committed} committed · ${t.discarded} discarded · ${t.abandoned} abandoned`);
+    if (s.lastOutcomes.length > 0)
+        lines.push(`recent  : ${s.lastOutcomes.join(', ')}`);
+    if (s.openQuestions.length === 0) {
+        lines.push('questions: none open');
+    }
+    else {
+        lines.push('questions:');
+        for (const q of s.openQuestions) {
+            lines.push(`  - [${q.qId}] ${q.text} (default ${q.default}, by ${q.deadline})`);
+        }
+    }
+    return { out: lines.join('\n') + '\n', code: 0 };
+}
+//# sourceMappingURL=status-cmd.js.map

package/dist/status-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-cmd.js","sourceRoot":"","sources":["../src/status-cmd.ts"],"names":[],"mappings":";;;AAkCA,0CAWC;AAkBD,oCAkDC;AAjHD,uCAA8F;AAC9F,iCAA2C;AAE3C;;;;;;;;GAQG;AAEH;;;;;GAKG;AACU,QAAA,cAAc,GAAG,CAAC,wBAAiB,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;AAO/D,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAU,CAAC;IACf,IAAI,CAAC;QACH,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,CAAsB,CAAC;AAChC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,IAAI,CAAC,CAAC,CAAC,IAAI;QAAE,OAAO,UAAU,CAAC,CAAC,UAAU,IAAI,SAAS,GAAG,CAAC;IAC3D,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,IAAA,cAAO,EAAC,CAAC,EAAE,GAAG,EAAE,sBAAc,CAAC,EAAE,CAAC;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACnE,OAAO,wBAAwB,GAAG,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACpF,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,IAAI,gBAAgB,CAAC;IACrD,OAAO,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI,QAAQ,MAAM,IAAI,EAAE,CAAC;AACrF,CAAC;AAED,SAAgB,YAAY,CAAC,IAAmB,EAAE,GAAW;IAC3D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO;YACL,GAAG,EAAE,gGAAgG;YACrG,IAAI,EAAE,CAAC;SACR,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QACf,wEAAwE;QACxE,wEAAwE;QACxE,qEAAqE;QACrE,OAAO,EAAE,GAAG,EAAE,wEAAwE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACpG,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B;;;;;;;;;OASG;IACH,MAAM,QAAQ,GAAG,IAAA,sBAAe,EAAC,CAAC,CAAC,CAAC;IACpC,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,aAAa,IAAA,8BAAuB,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;SAAM,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,MAAM,IAAI,aAAa,MAAM,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,CAAC,SAAS,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnB,KAAK,CAAC,IAAI,CACR,aAAa,CAAC,CAAC,MAAM,aAAa,CAAC,CAAC,SAAS,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,CAAC,CAAC,SAAS,YAAY,CAChH,CAAC;IACF,IAAI,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpF,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACrC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC"}

package/dist/stop-follow-up.d.ts

@@ -0,0 +1,107 @@
+/**
+ * THE FOLLOW-UP ON A RUN THAT IGNORES ITS STOP (M6-5, STATE §5 item 16).
+ *
+ * A stop is a request. A person's tap on the phone and the coordinator's
+ * preemption both write `stop` to a control file the run reads between rounds
+ * (round-runner.ts), and the run honours it at its next round boundary: "the
+ * run ends after the current round". Nothing followed that up. A run that never
+ * reads the file — a runner without a control source, a stuck round, a bug —
+ * or that reads it and begins another round anyway kept spending, and the
+ * daemon's log said "stop written" and then nothing.
+ *
+ * This module NOTICES and SAYS SO. Once per sweep cadence the daemon looks at
+ * every live run whose control file says `stop`; if the run has begun a round
+ * since the request (plus a grace for the read-then-pick race at the boundary),
+ * the daemon names the run once in its log and appends ONE `alert` to the run's
+ * own ledger — the kind the phone already shows — so it ships on the next flush
+ * with no server or app change. Idempotent per (run, requestedAt): the alert on
+ * the ledger is the memory, so a restarted daemon does not repeat it.
+ *
+ * IT DOES NOT KILL. Ending a run by force is a person's act, or a later slice's;
+ * this one turns silence into a sentence the person can act on.
+ *
+ * The decision is pure (`decideStopFollowUp`); the reading and the writing are
+ * behind `followUpOnStops`'s deps, with the node ones in `nodeStopFollowUp`.
+ */
+import type { AnyEvent } from '@looply/core';
+import { type ControlRequest } from './control-file';
+import { type AnyEventInput, type LedgerFs } from './ledger-store';
+import { type RunRecord } from './workspace';
+/**
+ * A round picked this soon after the request is the boundary race — the runner
+ * read the control file, found nothing, and picked before the stop landed —
+ * not a run refusing to stop. Fifteen seconds is far longer than that read
+ * takes and far shorter than any round.
+ */
+export declare const STOP_GRACE_MS = 15000;
+/** The alert's `code`; the text carries the request's stamp, which is what makes it once-per-request. */
+export declare const STOP_IGNORED_CODE = "stop-ignored";
+export interface StopFollowUpFacts {
+    readonly runId: string;
+    /** The standing stop, or null when the control file says nothing, `pause` or `resume`. */
+    readonly stop: {
+        readonly requestedAt: string;
+        readonly actor?: string;
+    } | null;
+    /** The registry still lists the run as live. */
+    readonly alive: boolean;
+    /** The ledger carries the run's `run.ended`. */
+    readonly ended: boolean;
+    /** `round.picked` events written after the request plus the grace. */
+    readonly roundsBegunAfter: number;
+    /** The ledger already carries this request's alert. */
+    readonly alreadySaid: boolean;
+}
+export type StopFollowUp = {
+    readonly kind: 'nothing';
+    readonly because: string;
+} | {
+    readonly kind: 'alert';
+    readonly code: typeof STOP_IGNORED_CODE;
+    readonly text: string;
+};
+export declare function stopIgnoredSentence(runId: string, stop: {
+    readonly requestedAt: string;
+    readonly actor?: string;
+}, roundsBegunAfter: number): string;
+/** Pure: what the daemon should do about one live run and its control file. */
+export declare function decideStopFollowUp(f: StopFollowUpFacts): StopFollowUp;
+/** The `round.picked` events of `runId` written after `requestedAt` plus the grace. */
+export declare function roundsBegunAfter(events: readonly AnyEvent[], runId: string, requestedAt: string, graceMs?: number): number;
+export declare function hasEnded(events: readonly AnyEvent[], runId: string): boolean;
+export declare function alreadySaid(events: readonly AnyEvent[], runId: string, requestedAt: string): boolean;
+export interface StopFollowUpDeps {
+    /** The runs the registry lists as live, the same list `requestControlEverywhere` writes to. */
+    readonly live: () => readonly RunRecord[];
+    /** The run's standing control request: its addressed file first, then the project's. */
+    readonly controlOf: (record: RunRecord) => Promise<ControlRequest | null>;
+    /** The run's ledger, or null when it cannot be read this pass. */
+    readonly eventsOf: (record: RunRecord) => Promise<readonly AnyEvent[] | null>;
+    readonly appendTo: (record: RunRecord, input: AnyEventInput) => Promise<void>;
+    readonly projectId: string;
+    readonly now: () => number;
+    readonly log: (line: string) => void;
+}
+export interface StopFollowUpOutcome {
+    readonly runId: string;
+    readonly outcome: StopFollowUp | {
+        readonly kind: 'unreadable';
+        readonly because: string;
+    };
+}
+/** One pass over the live runs. Never throws for one run's sake; each is named on its own. */
+export declare function followUpOnStops(deps: StopFollowUpDeps): Promise<StopFollowUpOutcome[]>;
+/** The ledger's lines, as `LedgerStore.open()` reads them; a malformed line is skipped, not fatal. */
+export declare function parseLedgerText(text: string): AnyEvent[];
+export interface NodeStopFollowUpOptions {
+    readonly projectState: string;
+    readonly projectId: string;
+    readonly fs?: LedgerFs;
+    readonly log: (line: string) => void;
+    readonly now?: () => number;
+    /** The registry's live list by default; a test hands in its own records. */
+    readonly live?: () => readonly RunRecord[];
+}
+/** The daemon's follow-up: real registry, real control files, real ledgers. */
+export declare function nodeStopFollowUp(o: NodeStopFollowUpOptions): () => Promise<StopFollowUpOutcome[]>;
+//# sourceMappingURL=stop-follow-up.d.ts.map

package/dist/stop-follow-up.d.ts.map

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

package/dist/stop-follow-up.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_IGNORED_CODE = exports.STOP_GRACE_MS = void 0;
+exports.stopIgnoredSentence = stopIgnoredSentence;
+exports.decideStopFollowUp = decideStopFollowUp;
+exports.roundsBegunAfter = roundsBegunAfter;
+exports.hasEnded = hasEnded;
+exports.alreadySaid = alreadySaid;
+exports.followUpOnStops = followUpOnStops;
+exports.parseLedgerText = parseLedgerText;
+exports.nodeStopFollowUp = nodeStopFollowUp;
+const control_file_1 = require("./control-file");
+const ledger_store_1 = require("./ledger-store");
+const workspace_1 = require("./workspace");
+/**
+ * A round picked this soon after the request is the boundary race — the runner
+ * read the control file, found nothing, and picked before the stop landed —
+ * not a run refusing to stop. Fifteen seconds is far longer than that read
+ * takes and far shorter than any round.
+ */
+exports.STOP_GRACE_MS = 15_000;
+/** The alert's `code`; the text carries the request's stamp, which is what makes it once-per-request. */
+exports.STOP_IGNORED_CODE = 'stop-ignored';
+function stopIgnoredSentence(runId, stop, roundsBegunAfter) {
+    const who = stop.actor === undefined ? '' : ` by ${stop.actor}`;
+    const rounds = `${roundsBegunAfter} round${roundsBegunAfter === 1 ? '' : 's'}`;
+    return (`run ${runId} was asked to stop at ${stop.requestedAt}${who} and has begun ${rounds} since — ` +
+        'it is not honouring the stop; nothing here ends it');
+}
+/** Pure: what the daemon should do about one live run and its control file. */
+function decideStopFollowUp(f) {
+    if (f.stop === null)
+        return { kind: 'nothing', because: 'no stop is standing' };
+    if (f.ended)
+        return { kind: 'nothing', because: 'the run has ended' };
+    if (!f.alive)
+        return { kind: 'nothing', because: 'the run is not alive — the sweep closes it' };
+    if (f.roundsBegunAfter === 0)
+        return { kind: 'nothing', because: 'no round has begun since the stop' };
+    if (f.alreadySaid)
+        return { kind: 'nothing', because: 'already said' };
+    return { kind: 'alert', code: exports.STOP_IGNORED_CODE, text: stopIgnoredSentence(f.runId, f.stop, f.roundsBegunAfter) };
+}
+/** The `round.picked` events of `runId` written after `requestedAt` plus the grace. */
+function roundsBegunAfter(events, runId, requestedAt, graceMs = exports.STOP_GRACE_MS) {
+    const after = Date.parse(requestedAt) + graceMs;
+    if (Number.isNaN(after))
+        return 0;
+    return events.filter((e) => e.runId === runId && e.kind === 'round.picked' && Date.parse(e.ts) > after).length;
+}
+function hasEnded(events, runId) {
+    return events.some((e) => e.runId === runId && e.kind === 'run.ended');
+}
+function alreadySaid(events, runId, requestedAt) {
+    return events.some((e) => e.runId === runId &&
+        e.kind === 'alert' &&
+        e.data.code === exports.STOP_IGNORED_CODE &&
+        e.data.text.includes(requestedAt));
+}
+/** One pass over the live runs. Never throws for one run's sake; each is named on its own. */
+async function followUpOnStops(deps) {
+    const out = [];
+    for (const record of deps.live()) {
+        const runId = record.runId;
+        let control;
+        try {
+            control = await deps.controlOf(record);
+        }
+        catch (e) {
+            deps.log(`daemon  : could not read the control file of run ${runId} — ${e.message}`);
+            out.push({ runId, outcome: { kind: 'unreadable', because: e.message } });
+            continue;
+        }
+        const stop = control !== null && control.kind === 'stop'
+            ? { requestedAt: control.requestedAt, ...(control.actor === undefined ? {} : { actor: control.actor }) }
+            : null;
+        if (stop === null) {
+            out.push({ runId, outcome: { kind: 'nothing', because: 'no stop is standing' } });
+            continue;
+        }
+        let events = null;
+        let why = 'the ledger could not be read this pass';
+        try {
+            events = await deps.eventsOf(record);
+        }
+        catch (e) {
+            why = e.message;
+        }
+        if (events === null) {
+            // Named every pass it stays unreadable: a ledger nobody can read while a
+            // stop stands is itself something a person should hear about.
+            deps.log(`daemon  : could not read the ledger of run ${runId} to follow up its stop — ${why}`);
+            out.push({ runId, outcome: { kind: 'unreadable', because: why } });
+            continue;
+        }
+        const decided = decideStopFollowUp({
+            runId,
+            stop,
+            alive: true,
+            ended: hasEnded(events, runId),
+            roundsBegunAfter: roundsBegunAfter(events, runId, stop.requestedAt),
+            alreadySaid: alreadySaid(events, runId, stop.requestedAt),
+        });
+        if (decided.kind === 'alert') {
+            const started = events.find((e) => e.runId === runId && e.kind === 'run.started');
+            try {
+                await deps.appendTo(record, {
+                    ts: new Date(deps.now()).toISOString(),
+                    runId,
+                    projectId: deps.projectId,
+                    lane: started?.lane ?? 'feature',
+                    kind: 'alert',
+                    actor: 'system',
+                    data: { code: decided.code, severity: 'warn', text: decided.text },
+                });
+                deps.log(`daemon  : ${decided.text}`);
+            }
+            catch (e) {
+                deps.log(`daemon  : could not record that run ${runId} ignores its stop — ${e.message}`);
+                out.push({ runId, outcome: { kind: 'unreadable', because: e.message } });
+                continue;
+            }
+        }
+        out.push({ runId, outcome: decided });
+    }
+    return out;
+}
+/** The ledger's lines, as `LedgerStore.open()` reads them; a malformed line is skipped, not fatal. */
+function parseLedgerText(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.runId === 'string' && typeof parsed.kind === 'string' && typeof parsed.ts === 'string') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            /* a half-written line; the next pass sees it whole */
+        }
+    }
+    return out;
+}
+/** The daemon's follow-up: real registry, real control files, real ledgers. */
+function nodeStopFollowUp(o) {
+    const fs = o.fs ?? ledger_store_1.nodeLedgerFs;
+    const now = o.now ?? (() => Date.now());
+    const project = new control_file_1.ControlStore(o.projectState, fs);
+    const deps = {
+        live: o.live ?? (() => new workspace_1.RunRegistry(o.projectState).active()),
+        controlOf: async (record) => {
+            const mine = await control_file_1.ControlStore.addressed(record.stateDir, record.runId, fs).read();
+            return mine ?? project.read();
+        },
+        eventsOf: async (record) => {
+            const text = await fs.readFile(`${record.stateDir}/events.jsonl`);
+            return text === null ? [] : parseLedgerText(text);
+        },
+        appendTo: async (record, input) => {
+            const ledger = new ledger_store_1.LedgerStore(record.stateDir, fs);
+            await ledger.open();
+            await ledger.append(input);
+        },
+        projectId: o.projectId,
+        now,
+        log: o.log,
+    };
+    return () => followUpOnStops(deps);
+}
+//# sourceMappingURL=stop-follow-up.js.map

package/dist/stop-follow-up.js.map

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

package/dist/surface-lease.d.ts

@@ -0,0 +1,118 @@
+import { type Fence, type SurfaceKey } from '@looply/core';
+/**
+ * A LEASE OVER A RESOURCE SURFACE, WITH A FENCE.
+ *
+ * ⚠️ THE SAME PRIMITIVE `RunLeaseStore` USES, PARAMETERISED — the recon's own
+ * words: "`RunLeaseStore` parameterised from `run.lease.json` to
+ * `leases/<surfaceKey>.json` is a resource lease with no new correctness
+ * argument." What IS new is the fence, and it is new because this lease may
+ * expire and the run lease may not.
+ *
+ * 🔴 EXPIRY EXISTS ONLY HERE, AND ONLY BECAUSE OF THE FENCE.
+ *
+ * The run lease has no expiry on purpose: a run inside a forty-five-minute
+ * model call is legitimately silent, and a lease that timed out would be
+ * reclaimed from a run that was working perfectly. A SURFACE lease can expire
+ * because a stale holder is caught at the publishing site by comparing two
+ * integers — which still works when the thing being checked has been asleep.
+ * Take the fence away and the expiry becomes exactly the hazard the run lease
+ * refuses to have.
+ */
+/** Where one surface's claims live: `<projectState>/leases/<hash>/`. */
+export declare function surfaceDir(cwd: string, surface: SurfaceKey): string;
+export interface SurfaceClaim {
+    readonly surface: SurfaceKey;
+    readonly ordinal: number;
+    readonly runId: string;
+    readonly pid: number;
+    readonly host: string;
+    readonly acquiredAt: string;
+    /** Milliseconds. See the note on expiry above. */
+    readonly ttlMs: number;
+}
+export type AcquireOutcome = {
+    readonly ok: true;
+    readonly held: readonly Fence[];
+} | {
+    readonly ok: false;
+    readonly because: string;
+    readonly blockedBy?: SurfaceKey;
+};
+/** The highest ordinal ever issued for a surface, or null when it cannot be read. */
+export declare function highestIssued(cwd: string, surface: SurfaceKey): number | null;
+/**
+ * Who holds this surface right now, if anybody.
+ *
+ * 🔴 THE LOWEST LIVE ORDINAL HOLDS IT — READING ONLY THE HIGHEST WAS A SECOND
+ * WRITER.
+ *
+ * MEASURED: run_LOW claims ordinal 1 and run_HIGH claims ordinal 2; run_HIGH
+ * releases; `holderOf` reads the top, sees it released, and answers NOBODY
+ * while run_LOW is alive and unaware. A third run then acquires ordinal 3 and
+ * two live holders write the same files.
+ *
+ * A lease is first-come-first-served, so the holder is the OLDEST claim that is
+ * still live. That composes with the fence rather than contradicting it: the
+ * fence asks "is my ordinal still the highest ever issued" at the moment of
+ * PUBLISHING, which is what catches a holder whose lease lapsed while a newer
+ * one took over.
+ *
+ * ⚠️ AND AN UNREADABLE CLAIM IS A HOLDER. `readClaim` returning null used to
+ * mean "free", which is the exact inversion of `mayPublish`'s own rule that
+ * unknown is a refusal — and it is reachable by a torn write, a full disk, or a
+ * permissions change. A surface this process cannot judge is one it must not
+ * take.
+ */
+export declare function holderOf(cwd: string, surface: SurfaceKey, now?: number): SurfaceClaim | null;
+/**
+ * TAKE EVERY DECLARED SURFACE, IN ORDER, ALL OR NOTHING.
+ *
+ * 🔴 THE ORDER IS WHAT MAKES DEADLOCK UNREPRESENTABLE. Lexicographic and
+ * total, so two Runs wanting the same pair always contend on the same one
+ * first. A Run never acquires a second surface while holding a first — which is
+ * the same statement, and is why there is no detector here to write.
+ *
+ * ⚠️ AND A PARTIAL ACQUISITION IS ROLLED BACK. Holding two of three surfaces
+ * while waiting for the third is precisely the state a total order exists to
+ * make impossible; leaving one behind on a failure would reintroduce it by the
+ * back door.
+ */
+export declare function acquireSurfaces(cwd: string, surfaces: readonly SurfaceKey[], who: {
+    runId: string;
+    ttlMs: number;
+}, now?: number): AcquireOutcome;
+/**
+ * MAY THIS HOLDER PUBLISH?
+ *
+ * The whole point of the fence, asked at the moment of the write rather than
+ * assumed at the moment of the claim.
+ */
+export declare function checkFence(cwd: string, fence: Fence): {
+    ok: true;
+} | {
+    ok: false;
+    because: string;
+};
+/**
+ * Give a surface back.
+ *
+ * 🔴 IT MARKS, IT DOES NOT DELETE — AND THE FIRST VERSION DELETED, WHICH BROKE
+ * THE FENCE OUTRIGHT. Caught by this file's own test.
+ *
+ * `highestIssued` reads the directory. Remove the claim and the count drops
+ * back, so the next acquirer is handed the SAME ordinal — and a revived holder
+ * from the previous generation then compares EQUAL to the current one and is
+ * allowed to publish. Two writers on one surface, arrived at by giving a
+ * surface back politely.
+ *
+ * "Highest ever issued" has to mean EVER. So the directory is append-only, like
+ * every other ledger in this codebase: a release adds `<NNNN>.released` beside
+ * the claim rather than taking the claim away. `highestIssued` counts claims;
+ * `holderOf` reads the marker.
+ *
+ * ⚠️ BY IDENTITY, AND BY EXCLUSIVE CREATE. Phase 1 measured what removing a
+ * claim by PATH costs: a process that had already lost its hold deleted the
+ * winner's, and four processes then held one lock.
+ */
+export declare function releaseSurface(cwd: string, fence: Fence, runId: string): boolean;
+//# sourceMappingURL=surface-lease.d.ts.map

package/dist/surface-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-lease.d.ts","sourceRoot":"","sources":["../src/surface-lease.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,KAAK,EACV,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAKtB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CAanE;AAwED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC;AAEtF,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAgB7E;AAuDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,GAAE,MAAmB,GAAG,YAAY,GAAG,IAAI,CAwBxG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACrC,GAAG,GAAE,MAAmB,GACvB,cAAc,CAchB;AAwKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAEnG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAkBhF"}