looply-cli 0.0.0-stage → 0.3.0

package/dist/run-start-marks.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunStartMarks = exports.MAX_MARKS = exports.RUN_START_MARKS_SCHEMA = void 0;
+exports.markingStartsOn = markingStartsOn;
+/**
+ * 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.
+ */
+exports.RUN_START_MARKS_SCHEMA = 1;
+/**
+ * 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.
+ */
+exports.MAX_MARKS = 50;
+class RunStartMarks {
+    stateDir;
+    fs;
+    log;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    marks = [];
+    /** Whether `load` has run. Recording before it would truncate the file. */
+    loaded = false;
+    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-starts.json`;
+    }
+    /**
+     * 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.
+     */
+    get logPath() {
+        return `${this.stateDir}/run-starts.jsonl`;
+    }
+    /**
+     * 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.
+     */
+    async load() {
+        this.loaded = true;
+        const text = await this.fs.readFile(this.path);
+        if (text === null) {
+            this.marks = [];
+            return;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                parsed.schema !== exports.RUN_START_MARKS_SCHEMA ||
+                !Array.isArray(parsed.marks)) {
+                throw new Error('not a mark file');
+            }
+            this.marks = parsed.marks.filter(isMark);
+        }
+        catch (e) {
+            this.log?.(`run-starts: discarding an unreadable file (${e.message})`);
+            this.marks = [];
+        }
+        await this.mergeLog();
+    }
+    /**
+     * 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.
+     */
+    async mergeLog() {
+        let text;
+        try {
+            text = await this.fs.readFile(this.logPath);
+        }
+        catch {
+            return;
+        }
+        if (text === null)
+            return;
+        const known = new Set(this.marks.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.marks.push(parsed);
+            }
+            catch {
+                // A fragment. Skipped by itself.
+            }
+        }
+    }
+    /** The run this command produced, if it produced one. */
+    find(commandId) {
+        return this.marks.find((m) => m.commandId === commandId) ?? 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) {
+        return this.marks.find((m) => m.runId === runId) ?? null;
+    }
+    all() {
+        return [...this.marks];
+    }
+    /**
+     * 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.
+     */
+    async record(mark) {
+        if (!this.loaded) {
+            // Recording without having read is how a fifty-entry index becomes a
+            // one-entry one: `this.marks` is empty, so the whole file is replaced by
+            // whatever is being written. The twin refusal store's writer loads first
+            // and `CommandReceipts.record` throws outright; this one silently did
+            // neither, and the accumulation its own documentation describes has never
+            // actually shipped.
+            throw new Error('RunStartMarks.record before load()');
+        }
+        if (this.find(mark.commandId))
+            return;
+        await this.fs.mkdir(this.stateDir);
+        /**
+         * 🔴 THE DURABLE WRITE FIRST, AND IT IS THE APPEND. See `logPath`: the
+         * index below is a whole-document rewrite, and two runs crossing their
+         * start boundary together lose one of the two marks — which the daemon
+         * reads as "never began" and escalates to a human.
+         *
+         * An append cannot lose a neighbour's record, so the fact is safe before
+         * the convenience index is touched.
+         */
+        await this.fs.appendFile(this.logPath, `\n${JSON.stringify(mark)}\n`);
+        // Newest first, so the cap drops the oldest.
+        const next = [mark, ...this.marks].slice(0, exports.MAX_MARKS);
+        const body = { schema: exports.RUN_START_MARKS_SCHEMA, marks: next };
+        // 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-starts.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}.${(RunStartMarks.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.marks = next;
+    }
+}
+exports.RunStartMarks = RunStartMarks;
+function isMark(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const m = v;
+    if (typeof m['commandId'] !== 'string' || typeof m['runId'] !== 'string' || typeof m['at'] !== 'string') {
+        return false;
+    }
+    // Optional, and when present it must be a path. A mark whose workspace is
+    // some other shape is not a mark this can act on.
+    return m['workspace'] === undefined || typeof m['workspace'] === 'string';
+}
+/**
+ * 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.
+ */
+function markingStartsOn(inner, marks, commandId, onError, 
+/** The checkout the run executes in, so a late mark still names its ledger. */
+workspace) {
+    let recorded = false;
+    return {
+        async append(input) {
+            const event = await inner.append(input);
+            if (!recorded && input.kind === 'run.started') {
+                recorded = true;
+                try {
+                    await marks.record({
+                        commandId,
+                        runId: input.data.runId,
+                        at: input.ts,
+                        ...(workspace === undefined ? {} : { workspace }),
+                    });
+                }
+                catch (e) {
+                    // Never fatal. A run that is genuinely under way must not be killed
+                    // because the daemon's evidence file could not be written — the cost
+                    // is an unacked command, which the redelivery window already bounds.
+                    recorded = false;
+                    onError?.(e);
+                }
+            }
+            return event;
+        },
+    };
+}
+//# sourceMappingURL=run-start-marks.js.map

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

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

package/dist/scan-cmd.d.ts

@@ -0,0 +1,14 @@
+import type { LooplyConfig } from './config';
+import { type ScanReport } from './scan';
+export interface ScanOptions {
+    cwd: string;
+    config: LooplyConfig;
+    /** Cap the lens set, for a cheap first look. */
+    only?: string[];
+    perLens?: number;
+    /** Report what it found without writing to the queue. */
+    dryRun?: boolean;
+    log: (line: string) => void;
+}
+export declare function scanProject(opts: ScanOptions): Promise<ScanReport>;
+//# sourceMappingURL=scan-cmd.d.ts.map

package/dist/scan-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-cmd.d.ts","sourceRoot":"","sources":["../src/scan-cmd.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAgB7C,OAAO,EASL,KAAK,UAAU,EAChB,MAAM,QAAQ,CAAC;AAwBhB,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAsDD,wBAAsB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CASxE"}

package/dist/scan-cmd.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanProject = scanProject;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const queue_store_1 = require("./queue-store");
+const ledger_store_1 = require("./ledger-store");
+const syncing_ledger_1 = require("./syncing-ledger");
+const sync_1 = require("./sync");
+const scan_events_1 = require("./scan-events");
+const git_driver_1 = require("./git-driver");
+const model_transport_1 = require("./model-transport");
+const providers_1 = require("./providers");
+const agent_envelope_1 = require("./agent-envelope");
+const scan_1 = require("./scan");
+const queue_write_lease_1 = require("./queue-write-lease");
+/**
+ * The composition root for `looply scan`.
+ *
+ * Lenses run one at a time rather than in parallel. Cost and rate limits are
+ * global, and six concurrent read-only passes over a large repository is a good
+ * way to spend a lot of money quickly for no better result — the passes do not
+ * depend on each other, so nothing is gained by overlapping them beyond finishing
+ * sooner.
+ */
+const LENS_TIMEOUT_MS = 8 * 60 * 1000;
+/** Missing is the normal case for a lens that answered in prose; not an error. */
+function readIfPresent(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Open the ledger this scan reports through, and stream it if the machine is
+ * paired.
+ *
+ * The project id comes from the sync when there is one. The config's
+ * `project.id` is a guess this repo made about itself, and ingest drops every
+ * event whose `projectId` is not the one the server registered — so events
+ * written under the guess would land on disk, upload, and be discarded in
+ * silence, which looks exactly like a scan that emitted nothing.
+ */
+async function openScanStream(cwd, config, log) {
+    const ledger = new ledger_store_1.LedgerStore((0, node_path_1.join)(cwd, git_driver_1.STATE_DIR, 'state'), ledger_store_1.nodeLedgerFs);
+    await ledger.open();
+    const sync = await (0, sync_1.attachSync)(cwd, config, log, 'scan');
+    const sink = sync ? new syncing_ledger_1.SyncingLedger(ledger, sync.daemon, (0, syncing_ledger_1.logSinkErrorOnce)(log)) : ledger;
+    return {
+        ctx: {
+            scanId: (0, scan_events_1.newScanId)(),
+            projectId: sync?.projectId ?? config.project.id ?? 'local',
+            now: () => Date.now(),
+        },
+        emit: async (input) => {
+            try {
+                await sink.append(input);
+            }
+            catch (e) {
+                // The scan's product is the queue, not the ledger. A failed append is
+                // worth saying out loud and is never worth throwing away the passes
+                // that have already been paid for.
+                log(`scan    : could not record ${input.kind} — ${e.message}`);
+            }
+        },
+        close: async () => {
+            // Flushes what the last passes produced; without it the scan's own
+            // `scan.finished` can be lost on exit and the phone shows a scan that
+            // never ends.
+            if (sync)
+                await sync.stop();
+        },
+    };
+}
+async function scanProject(opts) {
+    // A dry run answers a question and changes nothing, so it opens no ledger and
+    // tells the phone nothing — there is no scan to watch.
+    const stream = opts.dryRun ? null : await openScanStream(opts.cwd, opts.config, opts.log);
+    try {
+        return await runScan(opts, stream);
+    }
+    finally {
+        if (stream)
+            await stream.close();
+    }
+}
+async function runScan(opts, stream) {
+    const { cwd, config, log } = opts;
+    const lenses = opts.only?.length
+        ? scan_1.DEFAULT_LENSES.filter((l) => opts.only.includes(l.key))
+        : [...scan_1.DEFAULT_LENSES];
+    if (!lenses.length) {
+        throw new Error(`no lenses matched. Available: ${scan_1.DEFAULT_LENSES.map((l) => l.key).join(', ')}`);
+    }
+    const ctx = {
+        projectName: config.project.name,
+        scope: [...config.scope.free, ...config.scope.additive],
+        rails: config.rails.forbiddenPaths,
+        perLens: opts.perLens ?? 8,
+        outputPath: '',
+    };
+    // `--output-format json`, not `text`: the runner merges stdout and stderr into
+    // one stream, so in text mode a single warning line from the agent's own
+    // startup is concatenated with its answer and the whole-document parse of a
+    // findings object fails for a reason nothing in the transcript explains.
+    // `unwrapEnvelope` hands `runLens` the final message on its own, and turns a
+    // run truncated at its turn limit — which still exits zero — into a failed
+    // pass rather than a lens that reports the codebase clean.
+    // Read-only, for the same reason: a scan reports, it does not change code.
+    /**
+     * 🔴 THE PRESET, HERE TOO. This passed `config.agent` unresolved, so
+     * `agent.provider` was ignored by `looply scan` entirely and the same project
+     * used a different binary depending on which verb was typed.
+     */
+    const picked = (0, providers_1.agentSpecFor)(config);
+    if (!picked.ok) {
+        log(picked.message);
+        throw new Error(picked.message);
+    }
+    if (picked.warning !== null)
+        log(`provider: ${picked.warning}`);
+    const agent = (0, model_transport_1.makeMediatedAgentRunner)(cwd, 'scanner', picked.spec, { format: 'json' });
+    const invoke = async (prompt, timeoutMs) => (0, agent_envelope_1.unwrapEnvelope)(await agent(prompt, timeoutMs));
+    if (stream) {
+        await stream.emit((0, scan_events_1.scanStartedEvent)(lenses.map((l) => l.key), stream.ctx));
+    }
+    const results = [];
+    for (const lens of lenses) {
+        log(`scan    : ${lens.label}…`);
+        // Outside the repository, deliberately. Inside it, the findings file is a
+        // file in a project the same prompt tells the agent not to modify — and the
+        // agent correctly obeyed the wider instruction and wrote nothing, every
+        // time. A path in the temp directory removes the contradiction instead of
+        // asking the agent to resolve it.
+        //
+        // Fresh per lens and removed first: a stale file from the previous lens
+        // would be read as this one's answer, which is worse than no answer at all.
+        const outputPath = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `looply-scan-${process.pid}-${lens.key}.json`);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outputPath), { recursive: true });
+        (0, node_fs_1.rmSync)(outputPath, { force: true });
+        // Forward slashes into the prompt. A Windows path travels through shell
+        // quoting and the agent's own parsing, and each layer treats a backslash as
+        // an escape — the path arrived as `C:UsersGeorge…`, so the agent wrote its
+        // findings somewhere meaningless and reported success. Windows accepts
+        // forward slashes, and nothing along the way can eat them.
+        const promptPath = outputPath.replace(/\\/g, '/');
+        const r = await (0, scan_1.runLens)(invoke, lens, { ...ctx, outputPath: promptPath }, LENS_TIMEOUT_MS, () => readIfPresent(outputPath));
+        // Per pass, not per scan: a lens that finishes in minute three is news in
+        // minute three, and a scan that reports only at the end is the silence this
+        // whole change exists to remove.
+        if (stream)
+            await stream.emit((0, scan_events_1.lensResultEvent)(r, lens.label, stream.ctx));
+        // A lens that failed is reported where it happened, not summarised away at
+        // the end — you want to know which pass to re-run, not that "some" failed.
+        if (!r.ok) {
+            log(`          ${lens.key} produced nothing usable: ${r.reason ?? 'unknown'}`);
+            if (r.transcriptTail) {
+                // Without this the only symptom is a zero, and a zero from a healthy
+                // codebase and a zero from an agent that answered in prose look the same.
+                log('          what it actually said:');
+                for (const line of r.transcriptTail.trim().split('\n').slice(-6)) {
+                    log(`          | ${line.slice(0, 110)}`);
+                }
+            }
+        }
+        else {
+            const over = r.overflow ? ` (${r.overflow} past the cap, cut)` : '';
+            log(`          ${r.findings.length} found${over}`);
+            // Said out loud because it is what this lens cost: the pass answered in
+            // prose and a second call had to turn it into findings.
+            if (r.distilled)
+                log('          (the pass answered in prose; a second call reformatted it)');
+        }
+        results.push(r);
+    }
+    const report = (0, scan_1.mergeFindings)(results, {
+        projectId: config.project.id ?? 'local',
+        maxSameShape: config.queue.maxSameShape,
+    });
+    log('');
+    log((0, scan_1.renderScanReport)(report));
+    if (opts.dryRun) {
+        log('dry run: nothing was added to the queue.');
+        return report;
+    }
+    /**
+     * 🔴 THE LEASE, AND ONLY HERE — AFTER THE DRY-RUN RETURN ABOVE.
+     *
+     * A scan that writes while a run is going does not merely race it: the run
+     * holds the whole queue in memory and writes it back wholesale after its next
+     * round, so the scan's items are silently reverted. See queue-write-lease.ts.
+     *
+     * A dry run "answers a question and changes nothing" by its own contract, so
+     * it must not need the machine to be idle — which is why this is not at the
+     * top of the function.
+     */
+    /**
+     * 🔴 THE STREAM IS CLOSED ON THE REFUSAL PATH TOO, OR THE PHONE SHOWS A SCAN
+     * THAT NEVER ENDS.
+     *
+     * `scan.started` and the per-lens alerts have already been emitted by the
+     * time this refuses, and `scanFinishedEvents` — the only emitter of
+     * `scan.finished` — is below it. This file already states the standard:
+     * "without it the scan's own `scan.finished` can be lost on exit and the
+     * phone shows a scan that never ends." Moving the refusal to the write put a
+     * new throw between the two.
+     *
+     * ⚠️ AND THE FINDINGS ARE STILL PRINTED. Six lens passes at eight minutes
+     * apiece have already been paid for; discarding the report as well as the
+     * queue write would waste the whole cost twice.
+     */
+    let held;
+    try {
+        held = await (0, queue_write_lease_1.takeQueueWriteLease)(cwd, 'a scan');
+    }
+    catch (e) {
+        if (stream) {
+            for (const ev of (0, scan_events_1.scanFinishedEvents)({ ...report, items: [] }, stream.ctx))
+                await stream.emit(ev);
+        }
+        throw e;
+    }
+    try {
+        const queue = new queue_store_1.QueueStore((0, node_path_1.join)(cwd, git_driver_1.STATE_DIR, 'state'), ledger_store_1.nodeLedgerFs);
+        await queue.open();
+        /**
+         * 🔴 ONE WRITE, NOT N. `insert()` persists the WHOLE map per call, so this
+         * was one full rewrite of queue.json per scanned item — and a crash part-way
+         * left an arbitrary prefix on disk with no record of what was missing.
+         *
+         * ⚠️ AND IT NO LONGER THROWS ON A RE-SCAN. `insert` rejects a duplicate id;
+         * `insertAll` skips it and reports it. Re-scanning a project is an ordinary
+         * thing to do, and ending the command on the first item it had already seen
+         * was never the useful answer.
+         */
+        const written = await queue.insertAll(report.items);
+        if (!written.ok) {
+            /**
+             * ⚠️ THE SAME ID TWICE IN ONE BATCH IS A SCANNER BUG, NOT A REPEAT, and
+             * `insertAll` refuses the whole batch rather than picking one — which is
+             * why this reports instead of continuing. Nothing was written.
+             */
+            log(`scan    : nothing was queued — the scan produced ${written.id} twice`);
+            return report;
+        }
+        if (written.alreadyPresent.length > 0) {
+            log(`scan    : ${written.alreadyPresent.length} item(s) were already queued and were left alone`);
+        }
+        // After the queue write, never before: an `item.created` the queue does not
+        // hold would send the phone to an item that is not there.
+        if (stream) {
+            for (const e of (0, scan_events_1.scanFinishedEvents)(report, stream.ctx))
+                await stream.emit(e);
+        }
+        // Only when something was written. "queued : 0 items, all unverified until a
+        // check pass confirms them" is a success line for a scan that produced
+        // nothing; the report above has already said what the zero means.
+        if (report.items.length) {
+            log(`queued  : ${report.items.length} items, all unverified until a check pass confirms them.`);
+        }
+        return report;
+    }
+    finally {
+        await held.release();
+    }
+}
+//# sourceMappingURL=scan-cmd.js.map

package/dist/scan-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-cmd.js","sourceRoot":"","sources":["../src/scan-cmd.ts"],"names":[],"mappings":";;AAoHA,kCASC;AA7HD,yCAA0C;AAC1C,qCAA0D;AAC1D,qCAAiC;AAEjC,+CAA2C;AAC3C,iDAA+E;AAC/E,qDAAmE;AACnE,iCAAoC;AACpC,+CAMuB;AACvB,6CAAyC;AACzC,uDAA4D;AAC5D,2CAA2C;AAC3C,qDAAkD;AAClD,iCAUgB;AAChB,2DAA0D;AAE1D;;;;;;;;GAQG;AAEH,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC,kFAAkF;AAClF,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,CAAC;QACH,OAAO,IAAA,sBAAY,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAoBD;;;;;;;;;GASG;AACH,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,MAAoB,EACpB,GAA2B;IAE3B,MAAM,MAAM,GAAG,IAAI,0BAAW,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,sBAAS,EAAE,OAAO,CAAC,EAAE,2BAAY,CAAC,CAAC;IAC5E,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACpB,MAAM,IAAI,GAAG,MAAM,IAAA,iBAAU,EAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,8BAAa,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAA,iCAAgB,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAE3F,OAAO;QACL,GAAG,EAAE;YACH,MAAM,EAAE,IAAA,uBAAS,GAAE;YACnB,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO;YAC1D,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;SACtB;QACD,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACpB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,sEAAsE;gBACtE,oEAAoE;gBACpE,mCAAmC;gBACnC,GAAG,CAAC,8BAA8B,KAAK,CAAC,IAAI,MAAO,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;QACD,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,mEAAmE;YACnE,sEAAsE;YACtE,cAAc;YACd,IAAI,IAAI;gBAAE,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,WAAW,CAAC,IAAiB;IACjD,8EAA8E;IAC9E,uDAAuD;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1F,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;YAAS,CAAC;QACT,IAAI,MAAM;YAAE,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,IAAiB,EAAE,MAAyB;IACjE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAElC,MAAM,MAAM,GAAW,IAAI,CAAC,IAAI,EAAE,MAAM;QACtC,CAAC,CAAC,qBAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC,GAAG,qBAAc,CAAC,CAAC;IAExB,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,iCAAiC,qBAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAgB;QACvB,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI;QAChC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc;QAClC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC;QAC1B,UAAU,EAAE,EAAE;KACf,CAAC;IAEF,+EAA+E;IAC/E,yEAAyE;IACzE,4EAA4E;IAC5E,yEAAyE;IACzE,6EAA6E;IAC7E,2EAA2E;IAC3E,2DAA2D;IAC3D,2EAA2E;IAC3E;;;;OAIG;IACH,MAAM,MAAM,GAAG,IAAA,wBAAY,EAAC,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,GAAG,CAAC,aAAa,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvF,MAAM,MAAM,GAAe,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC,IAAA,+BAAc,EAAC,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAEvG,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,MAAM,CAAC,IAAI,CACf,IAAA,8BAAgB,EACd,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,MAAM,CAAC,GAAG,CACX,CACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,GAAG,CAAC,aAAa,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QAEhC,0EAA0E;QAC1E,4EAA4E;QAC5E,wEAAwE;QACxE,0EAA0E;QAC1E,kCAAkC;QAClC,EAAE;QACF,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,UAAU,GAAG,IAAA,gBAAI,EAAC,IAAA,gBAAM,GAAE,EAAE,eAAe,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;QACjF,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,IAAA,gBAAM,EAAC,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAEpC,wEAAwE;QACxE,4EAA4E;QAC5E,2EAA2E;QAC3E,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAElD,MAAM,CAAC,GAAG,MAAM,IAAA,cAAO,EACrB,MAAM,EACN,IAAI,EACJ,EAAE,GAAG,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,EAClC,eAAe,EACf,GAAG,EAAE,CAAC,aAAa,CAAC,UAAU,CAAC,CAChC,CAAC;QACF,0EAA0E;QAC1E,4EAA4E;QAC5E,iCAAiC;QACjC,IAAI,MAAM;YAAE,MAAM,MAAM,CAAC,IAAI,CAAC,IAAA,6BAAe,EAAC,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,GAAG,CAAC,aAAa,IAAI,CAAC,GAAG,6BAA6B,CAAC,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;gBACrB,qEAAqE;gBACrE,0EAA0E;gBAC1E,GAAG,CAAC,kCAAkC,CAAC,CAAC;gBACxC,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjE,GAAG,CAAC,eAAe,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,MAAM,SAAS,IAAI,EAAE,CAAC,CAAC;YACnD,wEAAwE;YACxE,wDAAwD;YACxD,IAAI,CAAC,CAAC,SAAS;gBAAE,GAAG,CAAC,sEAAsE,CAAC,CAAC;QAC/F,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,oBAAa,EAAC,OAAO,EAAE;QACpC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO;QACvC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY;KACxC,CAAC,CAAC;IAEH,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,IAAA,uBAAgB,EAAC,MAAM,CAAC,CAAC,CAAC;IAE9B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,GAAG,CAAC,0CAA0C,CAAC,CAAC;QAChD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;OAUG;IACH;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAA,uCAAmB,EAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,MAAM,EAAE,CAAC;YACX,KAAK,MAAM,EAAE,IAAI,IAAA,gCAAkB,EAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnG,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,wBAAU,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,sBAAS,EAAE,OAAO,CAAC,EAAE,2BAAY,CAAC,CAAC;QAC1E,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB;;;;;;;;;WASG;QACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB;;;;eAIG;YACH,GAAG,CAAC,oDAAoD,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC5E,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,GAAG,CAAC,aAAa,OAAO,CAAC,cAAc,CAAC,MAAM,kDAAkD,CAAC,CAAC;QACpG,CAAC;QAED,4EAA4E;QAC5E,0DAA0D;QAC1D,IAAI,MAAM,EAAE,CAAC;YACX,KAAK,MAAM,CAAC,IAAI,IAAA,gCAAkB,EAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/E,CAAC;QAED,6EAA6E;QAC7E,uEAAuE;QACvE,kEAAkE;QAClE,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACxB,GAAG,CAAC,aAAa,MAAM,CAAC,KAAK,CAAC,MAAM,0DAA0D,CAAC,CAAC;QAClG,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/scan-events.d.ts

@@ -0,0 +1,50 @@
+import type { AnyEventInput } from './ledger-store';
+import type { LensResult, ScanReport } from './scan';
+/**
+ * The events a scan writes.
+ *
+ * A scan is the longest thing looply does that produces nothing until it is
+ * finished: six read-only agent passes, twenty minutes, and — until now — not a
+ * single line in the ledger. From the phone that is indistinguishable from a
+ * machine that has stopped answering, which is the worst way for a working
+ * system to look.
+ *
+ * The builders are pure and the ledger is passed in, so what a scan reports is
+ * testable without a filesystem, an agent or a server.
+ */
+/**
+ * Every event carries a `runId`, and a scan is not a run — but the lane is a
+ * free string, so it is what says which this is. A scan mints a run-shaped id
+ * (the server keys events on it and will create a row for it either way) and
+ * marks the lane, so the app can tell the two apart without a schema change.
+ */
+export declare const SCAN_LANE = "scan";
+export interface ScanEventContext {
+    /** The id every event of this scan shares; see {@link newScanId}. */
+    scanId: string;
+    /** The project the server knows, not the one the config guesses; see scan-cmd. */
+    projectId: string;
+    now(): number;
+}
+export declare function newScanId(now?: number): string;
+/** Written before the first pass, so the phone knows what it is waiting for. */
+export declare function scanStartedEvent(lensKeys: readonly string[], ctx: ScanEventContext): AnyEventInput;
+/**
+ * One pass finished.
+ *
+ * There is no per-lens kind in the schema, and the only kind that carries free
+ * text is `alert` — so this is an alert, at `info` when the pass worked. Waiting
+ * for `scan.finished` instead would mean the phone shows nothing at all for the
+ * length of the scan, which is the thing being fixed. A pass that produced
+ * nothing usable is a genuine `warn`: it means a sixth of the scan was wasted
+ * and the reason is worth reading now rather than after the whole scan.
+ */
+export declare function lensResultEvent(result: LensResult, label: string, ctx: ScanEventContext): AnyEventInput;
+/**
+ * What the scan produced, in the order it happened: the items first, then the
+ * summary. An `item.created` for something the queue does not hold would send
+ * the phone to an item that is not there, so callers emit these only after the
+ * queue write, and only for the items that were actually inserted.
+ */
+export declare function scanFinishedEvents(report: ScanReport, ctx: ScanEventContext): AnyEventInput[];
+//# sourceMappingURL=scan-events.d.ts.map

package/dist/scan-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.d.ts","sourceRoot":"","sources":["../src/scan-events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAErD;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,SAAS,CAAC;AAMhC,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,IAAI,MAAM,CAAC;CACf;AAED,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAkBD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAElG;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,GACpB,aAAa,CAcf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAY7F"}