@webpieces/rules-config 0.4.686 → 0.4.688

package/src/builds-log.js

@@ -0,0 +1,508 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildsLog = exports.RunningBuild = exports.BuildTicket = exports.MAX_ROW_BYTES = exports.BUILDS_LOG_GENERATIONS = exports.MAX_BUILDS_LOG_BYTES = exports.BUILD_DONE_FAIL = exports.BUILD_DONE_SUCCESS = exports.BUILD_START = exports.BUILDS_LOCK_FILE = exports.BUILDS_LOG_FILE = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const crypto = tslib_1.__importStar(require("crypto"));
+const fs = tslib_1.__importStar(require("fs"));
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const state_dir_1 = require("./state-dir");
+const home_config_1 = require("./home-config");
+const to_error_1 = require("./to-error");
+/**
+ * `~/.webpieces/builds.log` — the MACHINE-WIDE, append-only ledger of every build this box has started.
+ *
+ * ─── WHY THIS ONE FILE LIVES OUTSIDE THE REPO ─────────────────────────────────────────────────────────
+ * `no-machine-global-state.spec.ts` records the standing rule: webpieces writes state under
+ * `{repo}/.webpieces` and nowhere else. This is the ONE carve-out, and the argument is written out in
+ * `decisions/0006-the-build-ledger-is-machine-global.md`. In short:
+ *
+ *   • The FACT is machine-scoped. "How many builds are burning this box's CPU right now" is not a
+ *     property of any repo; it is a property of the machine. A per-repo ledger cannot answer it — every
+ *     linked worktree has its OWN `.webpieces/`, so it would be blind to the sibling worktree it is
+ *     actually contending with, never mind the four other repos on the disk.
+ *   • It is NOT A CACHE. The retired `PrBodyStore` that the no-machine-global rule was written for was a
+ *     local copy of a fact GitHub owned, so it could be stale, missing, or on the wrong computer. There
+ *     is no remote copy of this. The file IS the fact.
+ *   • Its key is an ABSOLUTE LOCAL PATH, which is stable precisely because it never leaves the machine —
+ *     the instability that killed `PrBodyStore`'s `<host>/<owner>/<repo>` key cannot arise here.
+ *
+ * ─── WHY IT IS SAFE TO WRITE CONCURRENTLY ─────────────────────────────────────────────────────────────
+ * Rows are deliberately kept under `MAX_ROW_BYTES` (512, macOS `PIPE_BUF`). A single `O_APPEND`
+ * `write(2)` at or below that size is indivisible, so two builds appending at the same instant cannot
+ * interleave halves of a line. The lock is therefore belt-and-braces for the APPEND and genuinely
+ * load-bearing for ROTATION, where a rename-and-reopen really does race.
+ *
+ * ─── IT MAY NEVER FAIL A BUILD ────────────────────────────────────────────────────────────────────────
+ * Every method here is best-effort and swallows its own errors. A build must never die because a log
+ * file was busy, unwritable, or on a full disk. Lock acquisition retries and then gives up and appends
+ * anyway — which the row-size invariant above makes safe.
+ */
+exports.BUILDS_LOG_FILE = 'builds.log';
+exports.BUILDS_LOCK_FILE = 'builds.log.lock';
+/** START, and the two terminal kinds. `DONE-` is the greppable prefix that pairs with a START. */
+exports.BUILD_START = 'START';
+exports.BUILD_DONE_SUCCESS = 'DONE-SUCCESS';
+exports.BUILD_DONE_FAIL = 'DONE-FAIL';
+/** Rotate at 1 MB, keeping five generations (`.1` … `.5`); the old `.5` is dropped. */
+exports.MAX_BUILDS_LOG_BYTES = 1024 * 1024;
+exports.BUILDS_LOG_GENERATIONS = 5;
+/**
+ * macOS `PIPE_BUF`. A row at or under this size is written by ONE indivisible `write(2)`, which is what
+ * makes a lost lock a non-event rather than a corrupted file. Long paths are clipped to hold the line
+ * under it — see `clip`.
+ */
+exports.MAX_ROW_BYTES = 512;
+/** How long a build may hold the lock before another writer stops waiting and appends anyway. */
+const LOCK_RETRY_MS = 50;
+const LOCK_TIMEOUT_MS = 2000;
+/**
+ * The handle a START row hands back, and the ONLY thing `finish()` accepts. Data-only (a class, per
+ * CLAUDE.md), carrying exactly the fields the DONE row needs to pair itself with its START: the uuid,
+ * the caller, the repo, and when it began (so `took=` is computed from one clock, not two).
+ */
+class BuildTicket {
+    id;
+    by;
+    repo;
+    startedMs;
+    constructor(id, by, repo, startedMs) {
+        this.id = id;
+        this.by = by;
+        this.repo = repo;
+        this.startedMs = startedMs;
+    }
+}
+exports.BuildTicket = BuildTicket;
+/**
+ * One build that is STILL RUNNING — a START row with no matching `DONE-`, whose pid is still alive.
+ * Data-only. This is what the refusal message renders, so it carries the three things a reader needs to
+ * recognise the build in question: where it is, which tree, and how old it is.
+ */
+class RunningBuild {
+    id;
+    by;
+    repo;
+    tree;
+    cwd;
+    branch;
+    pid;
+    startedMs;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(id, by, repo, tree, cwd, branch, pid, startedMs) {
+        this.id = id;
+        this.by = by;
+        this.repo = repo;
+        this.tree = tree;
+        this.cwd = cwd;
+        this.branch = branch;
+        this.pid = pid;
+        this.startedMs = startedMs;
+    }
+}
+exports.RunningBuild = RunningBuild;
+/**
+ * The ledger. See the file docblock for why it is machine-global and why every operation swallows its
+ * own errors.
+ *
+ * `homeDir` is a parameter on every public method, defaulted to `os.homedir()`, for exactly the reason
+ * `HomeConfigService.configPath` takes one: a spec must be able to exercise the real code against a temp
+ * directory and must never touch the developer's actual `~/.webpieces`.
+ */
+let BuildsLog = class BuildsLog {
+    dotDir;
+    constructor(dotDir) {
+        this.dotDir = dotDir;
+    }
+    /** `~/.webpieces/builds.log`. */
+    logPath(homeDir = os.homedir()) {
+        return path.join(homeDir, home_config_1.HOME_CONFIG_DIR, exports.BUILDS_LOG_FILE);
+    }
+    /** `~/.webpieces/builds.log.lock` — `{"pid":N,"started":<epochMs>}`. */
+    lockPath(homeDir = os.homedir()) {
+        return path.join(homeDir, home_config_1.HOME_CONFIG_DIR, exports.BUILDS_LOCK_FILE);
+    }
+    /** `~/.webpieces/builds.log.<n>` — generation `n`, 1 being the most recent. */
+    rotatedPath(generation, homeDir = os.homedir()) {
+        return `${this.logPath(homeDir)}.${String(generation)}`;
+    }
+    /**
+     * Record that a build is starting, and hand back the ticket its DONE row will need.
+     *
+     * `by` is the CALLER — `BuildGateOptions.stage`, i.e. `build` | `review` | `finish`. There is no
+     * second "caller" concept anywhere: the stage id already is one, and a second spelling of it would
+     * be the shim CLAUDE.md rejects.
+     *
+     * Returns a ticket even when the append failed. A build whose START row never landed still has to be
+     * able to call `finish()`; the alternative is a nullable return that every call site must branch on
+     * for a logging failure that is, by policy, not an error.
+     */
+    start(by, startDir, homeDir = os.homedir()) {
+        const ticket = new BuildTicket(crypto.randomUUID(), by, this.dotDir.primaryRoot(startDir), Date.now());
+        this.append(this.startRow(ticket, startDir), homeDir);
+        return ticket;
+    }
+    /**
+     * Record that the build behind `ticket` has ended. `exitCode` 0 writes `DONE-SUCCESS`; anything else
+     * writes `DONE-FAIL` carrying the code, so `grep DONE-FAIL` lists every red build on the machine.
+     */
+    finish(ticket, exitCode, homeDir = os.homedir()) {
+        this.append(this.doneRow(ticket, exitCode), homeDir);
+    }
+    /**
+     * Every build that is still live: a `START` with no matching `DONE-` row, whose pid is still alive.
+     *
+     * The pid filter is not an optimisation, it is what keeps the ledger from wedging the machine. A
+     * build killed with SIGKILL — an agent cancelled mid-run, a terminal closed — writes no DONE row, so
+     * without the liveness test its START would count forever and the fourth build would be refused for
+     * the rest of the machine's life. The uuid answers "which build"; the pid answers "is it still real".
+     *
+     * Only the CURRENT generation is read. A rotated-away START is by definition at least 1 MB of rows
+     * old and is not a build anyone is contending with.
+     */
+    running(homeDir = os.homedir()) {
+        const lines = this.readLines(this.logPath(homeDir));
+        const done = new Set();
+        for (const line of lines) {
+            if (line.startsWith(`${exports.BUILD_DONE_SUCCESS}\t`) || line.startsWith(`${exports.BUILD_DONE_FAIL}\t`)) {
+                done.add(this.field(line, 'id'));
+            }
+        }
+        const live = [];
+        for (const line of lines) {
+            if (!line.startsWith(`${exports.BUILD_START}\t`))
+                continue;
+            const build = this.toRunningBuild(line);
+            if (build === null || done.has(build.id))
+                continue;
+            if (!this.isAlive(build.pid))
+                continue;
+            live.push(build);
+        }
+        return live;
+    }
+    /**
+     * The `@webpieces` release ACTUALLY EXECUTING — found by walking UP from this module's own directory
+     * to the nearest enclosing `node_modules/@webpieces/<pkg>/package.json`. `''` when this code is
+     * running from source rather than from an installed package (which is the state in this repo's own
+     * specs, and a perfectly ordinary answer).
+     *
+     * ─── WHY THIS IS NOT `WebpiecesVersions.readInstalled(root)` ──────────────────────────────────────
+     * They answer DIFFERENT QUESTIONS and merging them would break the older one. `readInstalled` joins
+     * `<root>/node_modules/@webpieces/...` at a FIXED tree root ON PURPOSE: its whole job is to detect
+     * DRIFT between what a tree PINS and what some other tree pins, and a walk-up would silently resolve
+     * a worktree with no install of its own to the primary clone's copy — hiding exactly the skew that
+     * guard exists to catch. This question is the opposite one: "whichever copy is running, name it", and
+     * for that the walk-up is the only correct answer. Do not fold them together.
+     */
+    executingVersion() {
+        let dir = __dirname;
+        for (let hops = 0; hops < 40; hops += 1) {
+            const version = this.versionOfEnclosingPackage(dir);
+            if (version !== '')
+                return version;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return '';
+            dir = parent;
+        }
+        return '';
+    }
+    // `<dir>` is `node_modules/@webpieces/<pkg>/...`? Then that package's version, else ''.
+    versionOfEnclosingPackage(dir) {
+        const parent = path.dirname(dir);
+        const grandparent = path.dirname(parent);
+        if (path.basename(parent) !== '@webpieces' || path.basename(grandparent) !== 'node_modules')
+            return '';
+        const text = this.readTextOrEmpty(path.join(dir, 'package.json'));
+        const match = /"version"\s*:\s*"([^"]+)"/.exec(text);
+        return match === null ? '' : match[1];
+    }
+    // ─── ROW RENDERING ────────────────────────────────────────────────────────────────────────────────
+    startRow(ticket, startDir) {
+        return [
+            exports.BUILD_START,
+            `id=${ticket.id}`,
+            `t=${new Date(ticket.startedMs).toISOString()}`,
+            `ms=${String(ticket.startedMs)}`,
+            `by=${ticket.by}`,
+            `repo=${this.clip(ticket.repo)}`,
+            `tree=${this.dotDir.worktreeName(startDir) || 'primary'}`,
+            `cwd=${this.clip(startDir)}`,
+            `branch=${this.gitBranch(startDir)}`,
+            `pid=${String(process.pid)}`,
+            `wp=${this.executingVersion()}`,
+        ].join('\t');
+    }
+    doneRow(ticket, exitCode) {
+        const now = Date.now();
+        const fields = [
+            exitCode === 0 ? exports.BUILD_DONE_SUCCESS : exports.BUILD_DONE_FAIL,
+            `id=${ticket.id}`,
+            `t=${new Date(now).toISOString()}`,
+            `ms=${String(now)}`,
+            `by=${ticket.by}`,
+            `repo=${this.clip(ticket.repo)}`,
+            `took=${String(now - ticket.startedMs)}`,
+        ];
+        if (exitCode !== 0)
+            fields.push(`exit=${String(exitCode)}`);
+        fields.push(`pid=${String(process.pid)}`);
+        return fields.join('\t');
+    }
+    /**
+     * Hold a long path down to `max` characters by keeping its TAIL, which is the half that identifies
+     * the tree; a clipped value is marked with a leading `…` so nobody mistakes it for a real path.
+     *
+     * This is what keeps a row under `MAX_ROW_BYTES` — see the file docblock. `append` re-checks the
+     * assembled line as a backstop, because three clipped fields plus a long branch name can still add up.
+     */
+    clip(value, max = 120) {
+        const oneLine = value.replace(/[\t\n\r]/g, ' ');
+        return oneLine.length <= max ? oneLine : `…${oneLine.slice(oneLine.length - max)}`;
+    }
+    // ─── ROW PARSING ──────────────────────────────────────────────────────────────────────────────────
+    /** The value of `<name>=` on a TSV row, or '' when the row does not carry it. */
+    field(line, name) {
+        for (const part of line.split('\t')) {
+            if (part.startsWith(`${name}=`))
+                return part.slice(name.length + 1);
+        }
+        return '';
+    }
+    // A START row as a RunningBuild, or null when it is missing the two fields that make it usable.
+    toRunningBuild(line) {
+        const id = this.field(line, 'id');
+        const pid = Number.parseInt(this.field(line, 'pid'), 10);
+        if (id === '' || !Number.isInteger(pid) || pid <= 0)
+            return null;
+        const startedMs = Number.parseInt(this.field(line, 'ms'), 10);
+        return new RunningBuild(id, this.field(line, 'by'), this.field(line, 'repo'), this.field(line, 'tree'), this.field(line, 'cwd'), this.field(line, 'branch'), pid, Number.isInteger(startedMs) ? startedMs : 0);
+    }
+    /**
+     * Is `pid` still addressable? `process.kill(pid, 0)` sends no signal — it only asks the kernel. ESRCH
+     * is the ONE answer that proves death; EPERM proves the opposite (it exists, it is somebody else's).
+     * Same test, same reasoning, as `AgentWorktreeLockReader.isRunning`, including the accepted
+     * imprecision of pid reuse: being wrong in the "still running" direction costs one extra refusal,
+     * being wrong the other way lets a fourth build start.
+     */
+    isAlive(pid) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            return error.code !== 'ESRCH';
+        }
+    }
+    // ─── APPEND, LOCK, ROTATE ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Append one row, best-effort. Takes the lock so rotation cannot race, and appends ANYWAY when the
+     * lock cannot be had within `LOCK_TIMEOUT_MS` — the row is under `PIPE_BUF`, so an unlocked
+     * `O_APPEND` write is still indivisible, and a build must never die because a log file was busy.
+     */
+    append(row, homeDir) {
+        const line = `${this.truncateToRowLimit(row)}\n`;
+        const held = this.tryAcquireLock(homeDir);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            this.ensureDir(this.logPath(homeDir));
+            if (held)
+                this.rotateIfLarge(homeDir);
+            fs.appendFileSync(this.logPath(homeDir), line);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error; // logging may never fail a build — see the file docblock
+        }
+        finally {
+            if (held)
+                this.releaseLock(homeDir);
+        }
+    }
+    // The backstop for the PIPE_BUF invariant, measured in BYTES rather than characters because a path
+    // may hold multi-byte characters. Truncating a row loses fields off the end, which is strictly better
+    // than a torn line that breaks every row after it.
+    truncateToRowLimit(row) {
+        const bytes = Buffer.from(row, 'utf8');
+        // -1 for the newline `append` adds.
+        if (bytes.length <= exports.MAX_ROW_BYTES - 1)
+            return row;
+        return bytes.subarray(0, exports.MAX_ROW_BYTES - 1).toString('utf8');
+    }
+    /**
+     * Take the ledger lock, retrying every `LOCK_RETRY_MS` until `LOCK_TIMEOUT_MS`. False means "carry on
+     * without it" — never an error, and never a reason to skip the append.
+     *
+     * The mechanism is `MainSyncStatusService.tryAcquireMainSyncLock`'s, proven and deliberately copied
+     * rather than re-invented: an `wx` (O_CREAT|O_EXCL) create so exactly one of N racers wins, a payload
+     * carrying pid + started so a dead holder is identifiable, stale reclaim gated on pid liveness, and a
+     * re-read afterwards to confirm the entry on disk is OURS (a simultaneous reclaimer could have
+     * unlinked ours and written its own between the two calls).
+     */
+    tryAcquireLock(homeDir) {
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        this.ensureDir(this.lockPath(homeDir));
+        // Rendered rather than JSON.stringify'd off an anonymous object — two fields, both numbers, and
+        // the file's whole contract is `{"pid":N,"started":M}`.
+        const payload = `{"pid":${String(process.pid)},"started":${String(Date.now())}}\n`;
+        for (;;) {
+            if (this.createExclusive(this.lockPath(homeDir), payload))
+                return true;
+            if (!this.isHolderAlive(homeDir)) {
+                this.unlinkQuietly(this.lockPath(homeDir));
+                if (this.createExclusive(this.lockPath(homeDir), payload) && this.holderIsUs(homeDir))
+                    return true;
+            }
+            if (Date.now() >= deadline)
+                return false;
+            this.sleep(LOCK_RETRY_MS);
+        }
+    }
+    releaseLock(homeDir) {
+        if (!this.holderIsUs(homeDir))
+            return;
+        this.unlinkQuietly(this.lockPath(homeDir));
+    }
+    // O_CREAT|O_EXCL write: true when THIS call created the file, false when it already existed.
+    createExclusive(file, payload) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.writeFileSync(file, payload, { flag: 'wx' });
+            return true;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return false;
+        }
+    }
+    // The pid recorded in the lock file, or 0 when there is no readable lock.
+    lockHolderPid(homeDir) {
+        const text = this.readTextOrEmpty(this.lockPath(homeDir));
+        if (text === '')
+            return 0;
+        const match = /"pid"\s*:\s*(\d+)/.exec(text);
+        return match === null ? 0 : Number.parseInt(match[1], 10);
+    }
+    // An unreadable or pid-less lock file counts as DEAD: it is a corpse from a crashed writer, and
+    // leaving it forever would mean every future append silently skips rotation.
+    isHolderAlive(homeDir) {
+        const pid = this.lockHolderPid(homeDir);
+        return pid > 0 && this.isAlive(pid);
+    }
+    holderIsUs(homeDir) {
+        return this.lockHolderPid(homeDir) === process.pid;
+    }
+    /**
+     * `.4→.5, .3→.4, … .log→.1`, dropping the old `.5`. Runs INSIDE the lock, which is the one place the
+     * lock is genuinely load-bearing: a rename-and-reopen really does race, and a writer that opened the
+     * old inode mid-shift would append into a file nobody reads again.
+     */
+    rotateIfLarge(homeDir) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (!fs.existsSync(this.logPath(homeDir)))
+                return;
+            if (fs.statSync(this.logPath(homeDir)).size < exports.MAX_BUILDS_LOG_BYTES)
+                return;
+            this.unlinkQuietly(this.rotatedPath(exports.BUILDS_LOG_GENERATIONS, homeDir));
+            for (let gen = exports.BUILDS_LOG_GENERATIONS - 1; gen >= 1; gen -= 1) {
+                this.renameQuietly(this.rotatedPath(gen, homeDir), this.rotatedPath(gen + 1, homeDir));
+            }
+            this.renameQuietly(this.logPath(homeDir), this.rotatedPath(1, homeDir));
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    // ─── FILESYSTEM PRIMITIVES, ALL SWALLOWING ────────────────────────────────────────────────────────
+    ensureDir(file) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    unlinkQuietly(file) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (fs.existsSync(file))
+                fs.unlinkSync(file);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    renameQuietly(from, to) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (fs.existsSync(from))
+                fs.renameSync(from, to);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    readTextOrEmpty(file) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return '';
+        }
+    }
+    readLines(file) {
+        const text = this.readTextOrEmpty(file);
+        if (text === '')
+            return [];
+        return text.split('\n').filter((line) => line.trim() !== '');
+    }
+    // A blocking sleep, because the lock retry sits on a synchronous append path that must not become
+    // async — `finish()` is called from a `finally` and an async logger there could outlive the process.
+    sleep(ms) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    // The checked-out branch in `startDir`, or '' when git cannot say. spawnSync does not throw on a
+    // non-zero exit, so "not a repo" arrives as a status, not an exception.
+    gitBranch(startDir) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const result = (0, child_process_1.spawnSync)('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: startDir, encoding: 'utf8' });
+            if (result.status !== 0 || typeof result.stdout !== 'string')
+                return '';
+            return result.stdout.trim();
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return '';
+        }
+    }
+};
+exports.BuildsLog = BuildsLog;
+exports.BuildsLog = BuildsLog = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [state_dir_1.DotWebpieces])
+], BuildsLog);
+//# sourceMappingURL=builds-log.js.map

package/src/builds-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builds-log.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/builds-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as crypto from 'crypto';\nimport * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { DotWebpieces } from './state-dir';\nimport { HOME_CONFIG_DIR } from './home-config';\nimport { toError } from './to-error';\n\n/**\n * `~/.webpieces/builds.log` — the MACHINE-WIDE, append-only ledger of every build this box has started.\n *\n * ─── WHY THIS ONE FILE LIVES OUTSIDE THE REPO ─────────────────────────────────────────────────────────\n * `no-machine-global-state.spec.ts` records the standing rule: webpieces writes state under\n * `{repo}/.webpieces` and nowhere else. This is the ONE carve-out, and the argument is written out in\n * `decisions/0006-the-build-ledger-is-machine-global.md`. In short:\n *\n *   • The FACT is machine-scoped. \"How many builds are burning this box's CPU right now\" is not a\n *     property of any repo; it is a property of the machine. A per-repo ledger cannot answer it — every\n *     linked worktree has its OWN `.webpieces/`, so it would be blind to the sibling worktree it is\n *     actually contending with, never mind the four other repos on the disk.\n *   • It is NOT A CACHE. The retired `PrBodyStore` that the no-machine-global rule was written for was a\n *     local copy of a fact GitHub owned, so it could be stale, missing, or on the wrong computer. There\n *     is no remote copy of this. The file IS the fact.\n *   • Its key is an ABSOLUTE LOCAL PATH, which is stable precisely because it never leaves the machine —\n *     the instability that killed `PrBodyStore`'s `<host>/<owner>/<repo>` key cannot arise here.\n *\n * ─── WHY IT IS SAFE TO WRITE CONCURRENTLY ─────────────────────────────────────────────────────────────\n * Rows are deliberately kept under `MAX_ROW_BYTES` (512, macOS `PIPE_BUF`). A single `O_APPEND`\n * `write(2)` at or below that size is indivisible, so two builds appending at the same instant cannot\n * interleave halves of a line. The lock is therefore belt-and-braces for the APPEND and genuinely\n * load-bearing for ROTATION, where a rename-and-reopen really does race.\n *\n * ─── IT MAY NEVER FAIL A BUILD ────────────────────────────────────────────────────────────────────────\n * Every method here is best-effort and swallows its own errors. A build must never die because a log\n * file was busy, unwritable, or on a full disk. Lock acquisition retries and then gives up and appends\n * anyway — which the row-size invariant above makes safe.\n */\nexport const BUILDS_LOG_FILE = 'builds.log';\nexport const BUILDS_LOCK_FILE = 'builds.log.lock';\n\n/** START, and the two terminal kinds. `DONE-` is the greppable prefix that pairs with a START. */\nexport const BUILD_START = 'START';\nexport const BUILD_DONE_SUCCESS = 'DONE-SUCCESS';\nexport const BUILD_DONE_FAIL = 'DONE-FAIL';\n\n/** Rotate at 1 MB, keeping five generations (`.1` … `.5`); the old `.5` is dropped. */\nexport const MAX_BUILDS_LOG_BYTES = 1024 * 1024;\nexport const BUILDS_LOG_GENERATIONS = 5;\n\n/**\n * macOS `PIPE_BUF`. A row at or under this size is written by ONE indivisible `write(2)`, which is what\n * makes a lost lock a non-event rather than a corrupted file. Long paths are clipped to hold the line\n * under it — see `clip`.\n */\nexport const MAX_ROW_BYTES = 512;\n\n/** How long a build may hold the lock before another writer stops waiting and appends anyway. */\nconst LOCK_RETRY_MS = 50;\nconst LOCK_TIMEOUT_MS = 2000;\n\n/**\n * The handle a START row hands back, and the ONLY thing `finish()` accepts. Data-only (a class, per\n * CLAUDE.md), carrying exactly the fields the DONE row needs to pair itself with its START: the uuid,\n * the caller, the repo, and when it began (so `took=` is computed from one clock, not two).\n */\nexport class BuildTicket {\n    id: string;\n    by: string;\n    repo: string;\n    startedMs: number;\n\n    constructor(id: string, by: string, repo: string, startedMs: number) {\n        this.id = id;\n        this.by = by;\n        this.repo = repo;\n        this.startedMs = startedMs;\n    }\n}\n\n/**\n * One build that is STILL RUNNING — a START row with no matching `DONE-`, whose pid is still alive.\n * Data-only. This is what the refusal message renders, so it carries the three things a reader needs to\n * recognise the build in question: where it is, which tree, and how old it is.\n */\nexport class RunningBuild {\n    id: string;\n    by: string;\n    repo: string;\n    tree: string;\n    cwd: string;\n    branch: string;\n    pid: number;\n    startedMs: number;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        id: string, by: string, repo: string, tree: string,\n        cwd: string, branch: string, pid: number, startedMs: number,\n    ) {\n        this.id = id;\n        this.by = by;\n        this.repo = repo;\n        this.tree = tree;\n        this.cwd = cwd;\n        this.branch = branch;\n        this.pid = pid;\n        this.startedMs = startedMs;\n    }\n}\n\n/**\n * The ledger. See the file docblock for why it is machine-global and why every operation swallows its\n * own errors.\n *\n * `homeDir` is a parameter on every public method, defaulted to `os.homedir()`, for exactly the reason\n * `HomeConfigService.configPath` takes one: a spec must be able to exercise the real code against a temp\n * directory and must never touch the developer's actual `~/.webpieces`.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildsLog {\n    constructor(private readonly dotDir: DotWebpieces) {}\n\n    /** `~/.webpieces/builds.log`. */\n    logPath(homeDir: string = os.homedir()): string {\n        return path.join(homeDir, HOME_CONFIG_DIR, BUILDS_LOG_FILE);\n    }\n\n    /** `~/.webpieces/builds.log.lock` — `{\"pid\":N,\"started\":<epochMs>}`. */\n    lockPath(homeDir: string = os.homedir()): string {\n        return path.join(homeDir, HOME_CONFIG_DIR, BUILDS_LOCK_FILE);\n    }\n\n    /** `~/.webpieces/builds.log.<n>` — generation `n`, 1 being the most recent. */\n    rotatedPath(generation: number, homeDir: string = os.homedir()): string {\n        return `${this.logPath(homeDir)}.${String(generation)}`;\n    }\n\n    /**\n     * Record that a build is starting, and hand back the ticket its DONE row will need.\n     *\n     * `by` is the CALLER — `BuildGateOptions.stage`, i.e. `build` | `review` | `finish`. There is no\n     * second \"caller\" concept anywhere: the stage id already is one, and a second spelling of it would\n     * be the shim CLAUDE.md rejects.\n     *\n     * Returns a ticket even when the append failed. A build whose START row never landed still has to be\n     * able to call `finish()`; the alternative is a nullable return that every call site must branch on\n     * for a logging failure that is, by policy, not an error.\n     */\n    start(by: string, startDir: string, homeDir: string = os.homedir()): BuildTicket {\n        const ticket = new BuildTicket(\n            crypto.randomUUID(), by, this.dotDir.primaryRoot(startDir), Date.now());\n        this.append(this.startRow(ticket, startDir), homeDir);\n        return ticket;\n    }\n\n    /**\n     * Record that the build behind `ticket` has ended. `exitCode` 0 writes `DONE-SUCCESS`; anything else\n     * writes `DONE-FAIL` carrying the code, so `grep DONE-FAIL` lists every red build on the machine.\n     */\n    finish(ticket: BuildTicket, exitCode: number, homeDir: string = os.homedir()): void {\n        this.append(this.doneRow(ticket, exitCode), homeDir);\n    }\n\n    /**\n     * Every build that is still live: a `START` with no matching `DONE-` row, whose pid is still alive.\n     *\n     * The pid filter is not an optimisation, it is what keeps the ledger from wedging the machine. A\n     * build killed with SIGKILL — an agent cancelled mid-run, a terminal closed — writes no DONE row, so\n     * without the liveness test its START would count forever and the fourth build would be refused for\n     * the rest of the machine's life. The uuid answers \"which build\"; the pid answers \"is it still real\".\n     *\n     * Only the CURRENT generation is read. A rotated-away START is by definition at least 1 MB of rows\n     * old and is not a build anyone is contending with.\n     */\n    running(homeDir: string = os.homedir()): RunningBuild[] {\n        const lines = this.readLines(this.logPath(homeDir));\n        const done = new Set<string>();\n        for (const line of lines) {\n            if (line.startsWith(`${BUILD_DONE_SUCCESS}\\t`) || line.startsWith(`${BUILD_DONE_FAIL}\\t`)) {\n                done.add(this.field(line, 'id'));\n            }\n        }\n        const live: RunningBuild[] = [];\n        for (const line of lines) {\n            if (!line.startsWith(`${BUILD_START}\\t`)) continue;\n            const build = this.toRunningBuild(line);\n            if (build === null || done.has(build.id)) continue;\n            if (!this.isAlive(build.pid)) continue;\n            live.push(build);\n        }\n        return live;\n    }\n\n    /**\n     * The `@webpieces` release ACTUALLY EXECUTING — found by walking UP from this module's own directory\n     * to the nearest enclosing `node_modules/@webpieces/<pkg>/package.json`. `''` when this code is\n     * running from source rather than from an installed package (which is the state in this repo's own\n     * specs, and a perfectly ordinary answer).\n     *\n     * ─── WHY THIS IS NOT `WebpiecesVersions.readInstalled(root)` ──────────────────────────────────────\n     * They answer DIFFERENT QUESTIONS and merging them would break the older one. `readInstalled` joins\n     * `<root>/node_modules/@webpieces/...` at a FIXED tree root ON PURPOSE: its whole job is to detect\n     * DRIFT between what a tree PINS and what some other tree pins, and a walk-up would silently resolve\n     * a worktree with no install of its own to the primary clone's copy — hiding exactly the skew that\n     * guard exists to catch. This question is the opposite one: \"whichever copy is running, name it\", and\n     * for that the walk-up is the only correct answer. Do not fold them together.\n     */\n    executingVersion(): string {\n        let dir = __dirname;\n        for (let hops = 0; hops < 40; hops += 1) {\n            const version = this.versionOfEnclosingPackage(dir);\n            if (version !== '') return version;\n            const parent = path.dirname(dir);\n            if (parent === dir) return '';\n            dir = parent;\n        }\n        return '';\n    }\n\n    // `<dir>` is `node_modules/@webpieces/<pkg>/...`? Then that package's version, else ''.\n    private versionOfEnclosingPackage(dir: string): string {\n        const parent = path.dirname(dir);\n        const grandparent = path.dirname(parent);\n        if (path.basename(parent) !== '@webpieces' || path.basename(grandparent) !== 'node_modules') return '';\n        const text = this.readTextOrEmpty(path.join(dir, 'package.json'));\n        const match = /\"version\"\\s*:\\s*\"([^\"]+)\"/.exec(text);\n        return match === null ? '' : match[1];\n    }\n\n    // ─── ROW RENDERING ────────────────────────────────────────────────────────────────────────────────\n\n    private startRow(ticket: BuildTicket, startDir: string): string {\n        return [\n            BUILD_START,\n            `id=${ticket.id}`,\n            `t=${new Date(ticket.startedMs).toISOString()}`,\n            `ms=${String(ticket.startedMs)}`,\n            `by=${ticket.by}`,\n            `repo=${this.clip(ticket.repo)}`,\n            `tree=${this.dotDir.worktreeName(startDir) || 'primary'}`,\n            `cwd=${this.clip(startDir)}`,\n            `branch=${this.gitBranch(startDir)}`,\n            `pid=${String(process.pid)}`,\n            `wp=${this.executingVersion()}`,\n        ].join('\\t');\n    }\n\n    private doneRow(ticket: BuildTicket, exitCode: number): string {\n        const now = Date.now();\n        const fields = [\n            exitCode === 0 ? BUILD_DONE_SUCCESS : BUILD_DONE_FAIL,\n            `id=${ticket.id}`,\n            `t=${new Date(now).toISOString()}`,\n            `ms=${String(now)}`,\n            `by=${ticket.by}`,\n            `repo=${this.clip(ticket.repo)}`,\n            `took=${String(now - ticket.startedMs)}`,\n        ];\n        if (exitCode !== 0) fields.push(`exit=${String(exitCode)}`);\n        fields.push(`pid=${String(process.pid)}`);\n        return fields.join('\\t');\n    }\n\n    /**\n     * Hold a long path down to `max` characters by keeping its TAIL, which is the half that identifies\n     * the tree; a clipped value is marked with a leading `…` so nobody mistakes it for a real path.\n     *\n     * This is what keeps a row under `MAX_ROW_BYTES` — see the file docblock. `append` re-checks the\n     * assembled line as a backstop, because three clipped fields plus a long branch name can still add up.\n     */\n    private clip(value: string, max = 120): string {\n        const oneLine = value.replace(/[\\t\\n\\r]/g, ' ');\n        return oneLine.length <= max ? oneLine : `…${oneLine.slice(oneLine.length - max)}`;\n    }\n\n    // ─── ROW PARSING ──────────────────────────────────────────────────────────────────────────────────\n\n    /** The value of `<name>=` on a TSV row, or '' when the row does not carry it. */\n    private field(line: string, name: string): string {\n        for (const part of line.split('\\t')) {\n            if (part.startsWith(`${name}=`)) return part.slice(name.length + 1);\n        }\n        return '';\n    }\n\n    // A START row as a RunningBuild, or null when it is missing the two fields that make it usable.\n    private toRunningBuild(line: string): RunningBuild | null {\n        const id = this.field(line, 'id');\n        const pid = Number.parseInt(this.field(line, 'pid'), 10);\n        if (id === '' || !Number.isInteger(pid) || pid <= 0) return null;\n        const startedMs = Number.parseInt(this.field(line, 'ms'), 10);\n        return new RunningBuild(\n            id, this.field(line, 'by'), this.field(line, 'repo'), this.field(line, 'tree'),\n            this.field(line, 'cwd'), this.field(line, 'branch'), pid,\n            Number.isInteger(startedMs) ? startedMs : 0,\n        );\n    }\n\n    /**\n     * Is `pid` still addressable? `process.kill(pid, 0)` sends no signal — it only asks the kernel. ESRCH\n     * is the ONE answer that proves death; EPERM proves the opposite (it exists, it is somebody else's).\n     * Same test, same reasoning, as `AgentWorktreeLockReader.isRunning`, including the accepted\n     * imprecision of pid reuse: being wrong in the \"still running\" direction costs one extra refusal,\n     * being wrong the other way lets a fourth build start.\n     */\n    private isAlive(pid: number): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            process.kill(pid, 0);\n            return true;\n        } catch (err: unknown) {\n            const error = toError(err);\n            return (error as NodeJS.ErrnoException).code !== 'ESRCH';\n        }\n    }\n\n    // ─── APPEND, LOCK, ROTATE ─────────────────────────────────────────────────────────────────────────\n\n    /**\n     * Append one row, best-effort. Takes the lock so rotation cannot race, and appends ANYWAY when the\n     * lock cannot be had within `LOCK_TIMEOUT_MS` — the row is under `PIPE_BUF`, so an unlocked\n     * `O_APPEND` write is still indivisible, and a build must never die because a log file was busy.\n     */\n    private append(row: string, homeDir: string): void {\n        const line = `${this.truncateToRowLimit(row)}\\n`;\n        const held = this.tryAcquireLock(homeDir);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            this.ensureDir(this.logPath(homeDir));\n            if (held) this.rotateIfLarge(homeDir);\n            fs.appendFileSync(this.logPath(homeDir), line);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;  // logging may never fail a build — see the file docblock\n        } finally {\n            if (held) this.releaseLock(homeDir);\n        }\n    }\n\n    // The backstop for the PIPE_BUF invariant, measured in BYTES rather than characters because a path\n    // may hold multi-byte characters. Truncating a row loses fields off the end, which is strictly better\n    // than a torn line that breaks every row after it.\n    private truncateToRowLimit(row: string): string {\n        const bytes = Buffer.from(row, 'utf8');\n        // -1 for the newline `append` adds.\n        if (bytes.length <= MAX_ROW_BYTES - 1) return row;\n        return bytes.subarray(0, MAX_ROW_BYTES - 1).toString('utf8');\n    }\n\n    /**\n     * Take the ledger lock, retrying every `LOCK_RETRY_MS` until `LOCK_TIMEOUT_MS`. False means \"carry on\n     * without it\" — never an error, and never a reason to skip the append.\n     *\n     * The mechanism is `MainSyncStatusService.tryAcquireMainSyncLock`'s, proven and deliberately copied\n     * rather than re-invented: an `wx` (O_CREAT|O_EXCL) create so exactly one of N racers wins, a payload\n     * carrying pid + started so a dead holder is identifiable, stale reclaim gated on pid liveness, and a\n     * re-read afterwards to confirm the entry on disk is OURS (a simultaneous reclaimer could have\n     * unlinked ours and written its own between the two calls).\n     */\n    private tryAcquireLock(homeDir: string): boolean {\n        const deadline = Date.now() + LOCK_TIMEOUT_MS;\n        this.ensureDir(this.lockPath(homeDir));\n        // Rendered rather than JSON.stringify'd off an anonymous object — two fields, both numbers, and\n        // the file's whole contract is `{\"pid\":N,\"started\":M}`.\n        const payload = `{\"pid\":${String(process.pid)},\"started\":${String(Date.now())}}\\n`;\n        for (;;) {\n            if (this.createExclusive(this.lockPath(homeDir), payload)) return true;\n            if (!this.isHolderAlive(homeDir)) {\n                this.unlinkQuietly(this.lockPath(homeDir));\n                if (this.createExclusive(this.lockPath(homeDir), payload) && this.holderIsUs(homeDir)) return true;\n            }\n            if (Date.now() >= deadline) return false;\n            this.sleep(LOCK_RETRY_MS);\n        }\n    }\n\n    private releaseLock(homeDir: string): void {\n        if (!this.holderIsUs(homeDir)) return;\n        this.unlinkQuietly(this.lockPath(homeDir));\n    }\n\n    // O_CREAT|O_EXCL write: true when THIS call created the file, false when it already existed.\n    private createExclusive(file: string, payload: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.writeFileSync(file, payload, { flag: 'wx' });\n            return true;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return false;\n        }\n    }\n\n    // The pid recorded in the lock file, or 0 when there is no readable lock.\n    private lockHolderPid(homeDir: string): number {\n        const text = this.readTextOrEmpty(this.lockPath(homeDir));\n        if (text === '') return 0;\n        const match = /\"pid\"\\s*:\\s*(\\d+)/.exec(text);\n        return match === null ? 0 : Number.parseInt(match[1], 10);\n    }\n\n    // An unreadable or pid-less lock file counts as DEAD: it is a corpse from a crashed writer, and\n    // leaving it forever would mean every future append silently skips rotation.\n    private isHolderAlive(homeDir: string): boolean {\n        const pid = this.lockHolderPid(homeDir);\n        return pid > 0 && this.isAlive(pid);\n    }\n\n    private holderIsUs(homeDir: string): boolean {\n        return this.lockHolderPid(homeDir) === process.pid;\n    }\n\n    /**\n     * `.4→.5, .3→.4, … .log→.1`, dropping the old `.5`. Runs INSIDE the lock, which is the one place the\n     * lock is genuinely load-bearing: a rename-and-reopen really does race, and a writer that opened the\n     * old inode mid-shift would append into a file nobody reads again.\n     */\n    private rotateIfLarge(homeDir: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.existsSync(this.logPath(homeDir))) return;\n            if (fs.statSync(this.logPath(homeDir)).size < MAX_BUILDS_LOG_BYTES) return;\n            this.unlinkQuietly(this.rotatedPath(BUILDS_LOG_GENERATIONS, homeDir));\n            for (let gen = BUILDS_LOG_GENERATIONS - 1; gen >= 1; gen -= 1) {\n                this.renameQuietly(this.rotatedPath(gen, homeDir), this.rotatedPath(gen + 1, homeDir));\n            }\n            this.renameQuietly(this.logPath(homeDir), this.rotatedPath(1, homeDir));\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    // ─── FILESYSTEM PRIMITIVES, ALL SWALLOWING ────────────────────────────────────────────────────────\n\n    private ensureDir(file: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.mkdirSync(path.dirname(file), { recursive: true });\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    private unlinkQuietly(file: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (fs.existsSync(file)) fs.unlinkSync(file);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    private renameQuietly(from: string, to: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (fs.existsSync(from)) fs.renameSync(from, to);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    private readTextOrEmpty(file: string): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    private readLines(file: string): string[] {\n        const text = this.readTextOrEmpty(file);\n        if (text === '') return [];\n        return text.split('\\n').filter((line: string): boolean => line.trim() !== '');\n    }\n\n    // A blocking sleep, because the lock retry sits on a synchronous append path that must not become\n    // async — `finish()` is called from a `finally` and an async logger there could outlive the process.\n    private sleep(ms: number): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    // The checked-out branch in `startDir`, or '' when git cannot say. spawnSync does not throw on a\n    // non-zero exit, so \"not a repo\" arrives as a status, not an exception.\n    private gitBranch(startDir: string): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'],\n                { cwd: startDir, encoding: 'utf8' });\n            if (result.status !== 0 || typeof result.stdout !== 'string') return '';\n            return result.stdout.trim();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n}\n"]}

package/src/cli-args.d.ts

@@ -20,8 +20,11 @@ export declare class CliFlag {
  * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name, its one-line
  * summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
  *
- * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the
- * nine `wp-*` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is
+ * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what MOST `wp-*`
+ * bins are. (Deliberately not a count: the last one written down went stale the next time a bin grew a
+ * flag, which is exactly the drift the corollary in CLAUDE.md is about.)
+ *
+ * A flag a command does not DECLARE here is still rejected with exit 2: that guard is
  * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it
  * flag-aware must not soften it.
  */

package/src/cli-args.js

@@ -31,8 +31,11 @@ exports.CliFlag = CliFlag;
  * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name, its one-line
  * summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
  *
- * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the
- * nine `wp-*` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is
+ * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what MOST `wp-*`
+ * bins are. (Deliberately not a count: the last one written down went stale the next time a bin grew a
+ * flag, which is exactly the drift the corollary in CLAUDE.md is about.)
+ *
+ * A flag a command does not DECLARE here is still rejected with exit 2: that guard is
  * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it
  * flag-aware must not soften it.
  */
@@ -95,7 +98,7 @@ class CliScan {
 /** Argument guard for the no-argument `wp-*` bins. */
 let CliArgs = class CliArgs {
     // The help/usage block shown for `--help` and appended to an unknown-arg error. A command with no
-    // declared flags says so outright, because "takes no arguments" is the whole usage for eight of nine.
+    // declared flags says so outright, because "takes no arguments" is the whole usage for most of them.
     usageText(usage) {
         const head = `${usage.command} — ${usage.summary}\n\n`;
         if (usage.flags.length === 0) {