@webpieces/pr-gate 0.4.666 → 0.4.668

package/src/scripts/workflow/build-affected.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-affected.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-affected.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { loadAndValidate, CliExitError, HomeConfigService, DEFAULT_BUILD_COMMAND } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { BuildGateLog } from './build-gate-log';\n\n// Single source of truth for RUNNING the build gate. `wp-start-upsert-pr` runs NO build; stage ②\n// (`wp-review-upsert-pr`) runs it authoritatively before any reviewer is spawned, and stage ③\n// (`wp-finish-upsert-pr`) re-runs it only when HEAD has moved since. nx `affected` only rebuilds\n// changed projects. The fallback command itself lives in @webpieces/rules-config as\n// DEFAULT_BUILD_COMMAND — whole-repo-build-guard prints the same string, and one definition is what\n// keeps the refusal message naming the build that actually runs.\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The caller-supplied framing for the build gate (label, re-run command, failure headline, stage id). Kept\n * as a parameter object so runBuildGate stays agnostic of who invokes it. A class (not an object literal)\n * per the codebase's data-structure convention.\n */\nexport class BuildGateOptions {\n    label: string;            // section header shown above the gate\n    rerunCommand: string;     // command the AI re-runs after fixing the build\n    failureHeadline: string;  // first line printed on failure\n    // WHICH stage's gate this is — REVIEW_STAGE or FINISH_STAGE. Required, with no default: it is part of\n    // the captured log's filename, and a default would silently make two stages share one log file.\n    stage: string;\n\n    constructor(label: string, rerunCommand: string, failureHeadline: string, stage: string) {\n        this.label = label;\n        this.rerunCommand = rerunCommand;\n        this.failureHeadline = failureHeadline;\n        this.stage = stage;\n    }\n}\n\n/** Runs the authoritative nx-affected build gate for wp-review-upsert-pr and wp-finish-upsert-pr. */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildAffected {\n    constructor(\n        private readonly homeConfig: HomeConfigService,\n        private readonly buildLog: BuildGateLog,\n    ) {}\n\n    /**\n     * EXPERIMENTAL, and OFF unless the OPTIONAL machine-local `~/.webpieces/config.json` turns it on.\n     *\n     * That file does not exist for essentially anyone, and its absence is not an error, a warning or a\n     * behaviour change of any kind — `HomeConfigService.load` returns all-defaults silently. False here is\n     * therefore the state every consumer is in, and false means runBuildGate executes exactly the code it\n     * executed before this feature existed.\n     */\n    isCaptureEnabled(): boolean {\n        return this.homeConfig.load().buildGateLogCapture;\n    }\n\n    /**\n     * Resolve the exact build command this gate will run: the project's configured\n     * PrGateConfig.buildCommand, or the default affected-ci command when none is set.\n     */\n    resolveBuildCommand(repoRoot: string): string {\n        const configured = loadAndValidate(repoRoot).prGate.buildCommand;\n        return configured !== undefined && configured.trim() !== '' ? configured : DEFAULT_BUILD_COMMAND;\n    }\n\n    /**\n     * Run the build gate. Returns the process exit code (0 = pass).\n     *\n     * Prints NOTHING itself — `runBuildGate` announces the command in one line. This used to print its own\n     * `▶ Build gate: <cmd>` banner on top of that, so the command appeared twice in a row.\n     */\n    runBuildAffected(repoRoot: string, buildCommand?: string): number {\n        const cmd = buildCommand !== undefined && buildCommand.trim() !== '' ? buildCommand : DEFAULT_BUILD_COMMAND;\n        const result = spawnSync(cmd, { stdio: 'inherit', cwd: repoRoot, shell: true });\n        return result.status ?? 1;\n    }\n\n    /** Run the build gate using the project's configured command (PrGateConfig.buildCommand). */\n    runConfiguredBuildGate(repoRoot: string): number {\n        return this.runBuildAffected(repoRoot, loadAndValidate(repoRoot).prGate.buildCommand);\n    }\n\n    /**\n     * Run the configured build gate with consistent framing, throwing CliExitError(buildCode) on\n     * failure so the bin's main()/runMain owns the exit. Single source of truth: wp-start-upsert-pr and\n     * wp-finish-upsert-pr both call THIS (only the BuildGateOptions differ).\n     */\n    runBuildGate(repoRoot: string, opts: BuildGateOptions): void {\n        const buildCommand = this.resolveBuildCommand(repoRoot);\n        // TWO lines on the happy path — the command, then the result. The old framing spent a banner and a\n        // paragraph explaining how to reproduce a build that was about to pass anyway; that explanation is\n        // only useful when the build FAILS, so it now lives solely on the failure path below.\n        process.stdout.write(`\\n${opts.label}: ${buildCommand}\\n`);\n        // '' means NOT capturing, which is the case for every user who has not created the OPTIONAL\n        // `~/.webpieces/config.json`. Everything below then runs exactly the code it ran before this\n        // feature existed — same spawn, same message, no extra file, no extra line of output.\n        const logPath = this.isCaptureEnabled() ? this.buildLog.pathFor(repoRoot, opts.stage) : '';\n        const buildCode = logPath === ''\n            ? this.runConfiguredBuildGate(repoRoot)\n            : this.buildLog.run(repoRoot, buildCommand, logPath);\n        if (buildCode !== 0) throw new CliExitError(buildCode, this.failureText(opts, buildCommand, logPath));\n        process.stdout.write('\\n✅ Build passed.\\n');\n    }\n\n    /**\n     * On failure, WITHOUT capture: the pre-existing text, which tells the AI to re-run the build itself.\n     * WITH capture: a deliberately tiny pointer at the log the gate already wrote — the whole point of the\n     * feature is that the agent reads one file instead of rebuilding the repo and eating the transcript.\n     */\n    private failureText(opts: BuildGateOptions, buildCommand: string, logPath: string): string {\n        if (logPath !== '') return this.buildLog.failureMessage(buildCommand, logPath);\n        return `\\n❌ ${opts.failureHeadline}\\n\\n` +\n            `Run THIS exact command to reproduce and fix all errors, then re-run ${opts.rerunCommand}:\\n\\n` +\n            `    ${buildCommand}\\n`;\n    }\n}\n"]}
+{"version":3,"file":"build-affected.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-affected.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { loadAndValidate, CliExitError, HomeConfigService, DEFAULT_BUILD_COMMAND } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { BuildGateLog } from './build-gate-log';\n\n// Single source of truth for RUNNING the build gate. `wp-start-upsert-pr` runs NO build; stage ②\n// (`wp-review-upsert-pr`) runs it authoritatively before any reviewer is spawned, and stage ③\n// (`wp-finish-upsert-pr`) re-runs it only when HEAD has moved since. nx `affected` only rebuilds\n// changed projects. The fallback command itself lives in @webpieces/rules-config as\n// DEFAULT_BUILD_COMMAND — whole-repo-build-guard prints the same string, and one definition is what\n// keeps the refusal message naming the build that actually runs.\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The caller-supplied framing for the build gate (label, re-run command, failure headline, stage id). Kept\n * as a parameter object so runBuildGate stays agnostic of who invokes it. A class (not an object literal)\n * per the codebase's data-structure convention.\n */\nexport class BuildGateOptions {\n    label: string;            // section header shown above the gate\n    rerunCommand: string;     // command the AI re-runs after fixing the build\n    failureHeadline: string;  // first line printed on failure\n    // WHICH stage's gate this is — REVIEW_STAGE, FINISH_STAGE or BUILD_STAGE. Required, with no default:\n    // it decides the captured log's filename, and a default would silently make two stages share one file.\n    stage: string;\n    // Capture regardless of the EXPERIMENTAL `~/.webpieces/config.json` opt-in. True for `wp-build`, whose\n    // entire contract IS the log file — its console output is a heartbeat and a pointer at that file, so a\n    // wp-build that did not capture would have nothing to point at. The PR-flow stages pass false and stay\n    // on the opt-in until the experiment lands for them too.\n    alwaysCapture: boolean;\n\n    constructor(label: string, rerunCommand: string, failureHeadline: string, stage: string, alwaysCapture: boolean) {\n        this.label = label;\n        this.rerunCommand = rerunCommand;\n        this.failureHeadline = failureHeadline;\n        this.stage = stage;\n        this.alwaysCapture = alwaysCapture;\n    }\n}\n\n/** Runs the authoritative nx-affected build gate for wp-review-upsert-pr and wp-finish-upsert-pr. */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildAffected {\n    constructor(\n        private readonly homeConfig: HomeConfigService,\n        private readonly buildLog: BuildGateLog,\n    ) {}\n\n    /**\n     * EXPERIMENTAL, and OFF unless the OPTIONAL machine-local `~/.webpieces/config.json` turns it on.\n     *\n     * That file does not exist for essentially anyone, and its absence is not an error, a warning or a\n     * behaviour change of any kind — `HomeConfigService.load` returns all-defaults silently. False here is\n     * therefore the state every consumer is in, and false means runBuildGate executes exactly the code it\n     * executed before this feature existed.\n     */\n    isCaptureEnabled(): boolean {\n        return this.homeConfig.load().buildGateLogCapture;\n    }\n\n    /**\n     * Resolve the exact build command this gate will run: the project's configured\n     * PrGateConfig.buildCommand, or the default affected-ci command when none is set.\n     */\n    resolveBuildCommand(repoRoot: string): string {\n        const configured = loadAndValidate(repoRoot).prGate.buildCommand;\n        return configured !== undefined && configured.trim() !== '' ? configured : DEFAULT_BUILD_COMMAND;\n    }\n\n    /**\n     * Run the build gate. Returns the process exit code (0 = pass).\n     *\n     * Prints NOTHING itself — `runBuildGate` announces the command in one line. This used to print its own\n     * `▶ Build gate: <cmd>` banner on top of that, so the command appeared twice in a row.\n     */\n    runBuildAffected(repoRoot: string, buildCommand?: string): number {\n        const cmd = buildCommand !== undefined && buildCommand.trim() !== '' ? buildCommand : DEFAULT_BUILD_COMMAND;\n        const result = spawnSync(cmd, { stdio: 'inherit', cwd: repoRoot, shell: true });\n        return result.status ?? 1;\n    }\n\n    /** Run the build gate using the project's configured command (PrGateConfig.buildCommand). */\n    runConfiguredBuildGate(repoRoot: string): number {\n        return this.runBuildAffected(repoRoot, loadAndValidate(repoRoot).prGate.buildCommand);\n    }\n\n    /**\n     * Run the configured build gate with consistent framing, throwing CliExitError(buildCode) on\n     * failure so the bin's main()/runMain owns the exit. Single source of truth: wp-start-upsert-pr and\n     * wp-finish-upsert-pr both call THIS (only the BuildGateOptions differ).\n     */\n    async runBuildGate(repoRoot: string, opts: BuildGateOptions): Promise<void> {\n        const buildCommand = this.resolveBuildCommand(repoRoot);\n        // TWO lines on the happy path — the command, then the result. The old framing spent a banner and a\n        // paragraph explaining how to reproduce a build that was about to pass anyway; that explanation is\n        // only useful when the build FAILS, so it now lives solely on the failure path below.\n        process.stdout.write(`\\n${opts.label}: ${buildCommand}\\n`);\n        // '' means NOT capturing: a PR-flow stage on a machine that has not created the OPTIONAL\n        // `~/.webpieces/config.json`. Everything below then runs exactly the code it ran before capture\n        // existed — same spawn, streamed to the terminal, same message, no extra file.\n        const logPath = opts.alwaysCapture || this.isCaptureEnabled() ? this.buildLog.pathFor(repoRoot, opts.stage) : '';\n        const buildCode = logPath === ''\n            ? this.runConfiguredBuildGate(repoRoot)\n            : await this.buildLog.run(repoRoot, buildCommand, logPath);\n        if (buildCode !== 0) throw new CliExitError(buildCode, this.failureText(opts, buildCommand, logPath));\n        process.stdout.write(logPath === '' ? '\\n✅ Build passed.\\n' : this.buildLog.successMessage(logPath));\n    }\n\n    /**\n     * On failure, WITHOUT capture: the pre-existing text, which tells the AI to re-run the build itself.\n     * WITH capture: a deliberately tiny pointer at the log the gate already wrote — the whole point of the\n     * feature is that the agent reads one file instead of rebuilding the repo and eating the transcript.\n     */\n    private failureText(opts: BuildGateOptions, buildCommand: string, logPath: string): string {\n        if (logPath !== '') return this.buildLog.failureMessage(buildCommand, logPath);\n        return `\\n❌ ${opts.failureHeadline}\\n\\n` +\n            `Run THIS exact command to reproduce and fix all errors, then re-run ${opts.rerunCommand}:\\n\\n` +\n            `    ${buildCommand}\\n`;\n    }\n}\n"]}

package/src/scripts/workflow/build-gate-log.d.ts

@@ -1,64 +1,105 @@
+/** How often the heartbeat reports the log's size. Hardcoded: a knob here would be a knob the PR gate's
+ * own build never receives, and the two must stay the same command. */
+export declare const HEARTBEAT_MS = 10000;
+/** How many trailing log lines the failure message echoes, so the immediate cause is visible without a
+ * second command. Small on purpose — the FULL log is one grep away and the message must not become the
+ * transcript it exists to replace. */
+export declare const FAILURE_TAIL_LINES = 20;
 /**
- * Which stage's gate is being captured. The value is part of the log FILENAME, so review and finish never
- * write the same file even at the same commit on the same branch.
+ * Which stage's gate is being captured. The value decides the log FILENAME.
  */
 export declare const REVIEW_STAGE = "review";
 export declare const FINISH_STAGE = "finish";
 export declare const BUILD_STAGE = "build";
+/** The one fixed log name — see BuildGateLog.fileNameFor for why only `wp-build` gets one. */
+export declare const BUILD_LOG_NAME = "build.log";
 /**
- * Captures the build gate's full output to `.webpieces/logs/`, and renders the small pointer the AI is
- * handed instead of a rebuild instruction.
+ * The heartbeat's state: the line count reported on the PREVIOUS tick, so a tick that has not moved can
+ * say so. Stateful per RUN, which is why it is constructed per run rather than injected.
  *
- * ─── Why the filename cannot collide ───────────────────────────────────────────────────────────────────
- * The path is `dotWebpieces.logsFile(repoRoot, 'build-gate-<stage>-<branch>-<shortSha>.log')`, and each
- * component rules out one class of concurrent writer:
- *   • the DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree
- *     name>/logs/` in a linked worktree. Every worktree therefore has its own log directory already, which
- *     is what makes "N agents in N worktrees" safe by construction rather than by naming.
- *   • `<stage>` separates review from finish, the two gates that CAN run against one commit.
- *   • `<branch>` — a branch can be checked out in at most one worktree (git enforces it), so within one
- *     log directory the branch is effectively constant; it is in the name so a human reading the directory
- *     can tell whose log is whose, and so switching branches never appends to a stale file.
- *   • `<shortSha>` — a re-run at a NEW commit gets a new file, so the log a failure message points at is
- *     always the build for the code that failed. A re-run at the SAME commit deliberately TRUNCATES: it is
- *     the same build of the same tree, and the fresh one is the one worth reading.
- * The residual case is two agents running the same stage, at the same commit, in the SAME worktree,
- * simultaneously. That is already unsupported — both would be driving one git index and one merge state —
- * and it is the only case this scheme does not separate.
+ * `still` is the load-bearing word. A build that is linking, or waiting on a cold nx cache, produces no
+ * output for minutes; without `still` the caller sees the same number twice and cannot tell a stalled
+ * BUILD from a stalled REPORTER.
+ */
+export declare class BuildLogHeartbeat {
+    private readonly logPath;
+    private readonly displayPath;
+    private previous;
+    constructor(logPath: string, displayPath: string);
+    /** One heartbeat line — `<path> size <n> lines`, plus ` still` when <n> has not moved. */
+    tick(): string;
+    private lineCount;
+}
+/**
+ * Captures the build gate's full output to a file, reports progress while it runs, and renders the
+ * pointer the caller is handed instead of a rebuild instruction.
+ *
+ * ─── Two naming schemes, one rule each ─────────────────────────────────────────────────────────────────
+ *   • `wp-build` (BUILD_STAGE) writes ONE fixed path, `.webpieces/build.log`. It is fixed because a HUMAN
+ *     OR AN AGENT TYPES IT — `grep -n error .webpieces/build.log` has to be writable from memory, and a
+ *     name carrying a branch and a sha is not. History comes from the rotation below instead.
+ *   • stage ② and stage ③ write `logs/build-gate-<stage>-<branch>-<shortSha>.log`, because those two
+ *     gates CAN run against one commit and a failure message from one must not be pointing at a file the
+ *     other overwrote. Nobody types those names; the failure message prints them.
+ *
+ * ─── Rotation, everywhere ──────────────────────────────────────────────────────────────────────────────
+ * Every run moves an existing log to `<log>.bak` before writing, so the last TWO runs are always on disk.
+ * One rule for every stage: no branch, and the previous run of a re-run at the same commit survives
+ * instead of being truncated away.
+ *
+ * ─── Concurrency ───────────────────────────────────────────────────────────────────────────────────────
+ * The DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree name>/`
+ * in a linked worktree — so "N agents in N worktrees" is safe by construction rather than by naming. The
+ * residual case is two builds in the SAME worktree at once, which is already unsupported: both would be
+ * driving one git index.
  */
 export declare class BuildGateLog {
-    /** Absolute path of the log for `stage` at the current HEAD, creating the log directory. */
+    /** Absolute path of the log for `stage` at the current HEAD, creating its directory. */
     pathFor(repoRoot: string, stage: string): string;
     /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */
     existingLogFor(repoRoot: string, stage: string): string;
-    /** `build-gate-<stage>-<branch>-<shortSha>.log` — see the class docstring for why this cannot collide. */
+    /** `build.log` for `wp-build`; `build-gate-<stage>-<branch>-<shortSha>.log` for the PR-flow stages. */
     fileNameFor(repoRoot: string, stage: string): string;
+    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */
+    backupPathFor(logPath: string): string;
+    /**
+     * Move an existing log aside to `<log>.bak`, overwriting any previous backup. A missing log is the
+     * normal first-run state and is not an error.
+     */
+    rotate(logPath: string): void;
+    /**
+     * Run `buildCommand` with its stdout AND stderr redirected in full to `logPath`, printing a heartbeat
+     * to the console every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code.
+     * Nothing is truncated and nothing is streamed.
+     */
+    run(repoRoot: string, buildCommand: string, logPath: string): Promise<number>;
     /**
-     * Run `buildCommand` with its combined stdout+stderr streaming to the terminal AND appended in full to
-     * `logPath`. Returns the BUILD's exit code (not tee's). Nothing is truncated.
+     * The success summary: the caller is told WHERE the full output is, not handed the output.
      */
-    run(repoRoot: string, buildCommand: string, logPath: string): number;
+    successMessage(logPath: string): string;
     /**
-     * The ENTIRE message the AI gets on a captured failure. Deliberately tiny: the whole point is that the
-     * agent reads ONE file rather than carrying a build transcript in its context.
+     * The ENTIRE message the caller gets on a failed build. It names the log, echoes the last
+     * FAILURE_TAIL_LINES lines so the immediate cause needs no second command, and forbids the rebuild
+     * this whole file exists to prevent.
      *
      * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong
-     * (a runner that died without printing, a truncated pipe), and the worst possible response is an agent
-     * guessing or rebuilding — so it is told to surface the contradiction to the human and stop.
+     * (a runner that died without printing, a truncated redirect), and the worst possible response is an
+     * agent guessing or rebuilding — so it is told to surface the contradiction to the human and stop.
      */
     failureMessage(buildCommand: string, logPath: string): string;
+    private logPointer;
     /**
-     * `{ ( <build> ) ; echo $? > <status> ; } 2>&1 | tee <log>` — written across LINES so a build command
-     * ending in a `#` comment cannot swallow what follows it.
+     * The log's last FAILURE_TAIL_LINES lines, or a plain statement of why there are none.
      *
-     * The inner `( … )` is load-bearing, not decoration. The left side of a pipeline is already a subshell,
-     * so a build command containing a plain `exit 7` (or any script that calls `exit`) would terminate that
-     * subshell OUTRIGHT — `echo $?` never runs, the side file never appears, and the only status left is
-     * tee's 0. The nested subshell absorbs the `exit`, so `$?` is the build's code every time.
+     * A read that fails is REPORTED, never allowed to throw: this renders the message for a build that has
+     * ALREADY failed, so an I/O error escaping here would replace the real failure with the renderer's own
+     * — the caller would lose the build error and be handed a filesystem error instead. The full log is
+     * still named on the line above, so nothing is hidden by degrading to one line.
      */
-    private wrap;
-    private readStatus;
-    private quote;
+    private tail;
+    private awaitExit;
+    private displayPath;
+    private resolvePath;
     private slug;
     private git;
 }

package/src/scripts/workflow/build-gate-log.js

@@ -1,138 +1,245 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BuildGateLog = exports.BUILD_STAGE = exports.FINISH_STAGE = exports.REVIEW_STAGE = void 0;
+exports.BuildGateLog = exports.BuildLogHeartbeat = exports.BUILD_LOG_NAME = exports.BUILD_STAGE = exports.FINISH_STAGE = exports.REVIEW_STAGE = exports.FAILURE_TAIL_LINES = exports.HEARTBEAT_MS = void 0;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const rules_config_1 = require("@webpieces/rules-config");
 const inversify_1 = require("inversify");
-// EXPERIMENTAL (opt-in via `~/.webpieces/config.json` → experimental.buildGateLogCapture). Nothing in this
-// file runs for a user who has not created that OPTIONAL file — see `HomeConfigService`
-// (`@webpieces/rules-config`), which returns all-defaults silently when it is absent.
-//
-// EVERY key in that file is optional, so the smallest document enabling THIS feature is just:
-//     { "experimental": { "buildGateLogCapture": true } }
-// Optional is not a convenience: the file is MACHINE-GLOBAL and the repos on one machine pin different
-// webpieces releases, so a REQUIRED key there has no satisfiable value — omitting it fails the new
-// release, adding it fails every older one. `HomeConfigService` owns that rule.
-//
 // ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────
-// The build gate already builds everything. When it fails, the pre-existing message says "run THIS exact
-// command to reproduce", and an AI agent obeys it — so the repo is built a SECOND time purely to see the
-// errors that scrolled past the first time. This captures the first build's output instead.
+// The build gate already builds everything. When the output only ever went to the CONSOLE, an agent that
+// wanted a different slice of it re-ran the WHOLE BUILD to get it: one measured session spent 23.9 minutes
+// across nine `nx affected` runs, five of them with NO code change in between — `| tail -50`, then
+// `> /tmp/file`, then `| grep`, then `| sed -n '1100,1230p'`. ~19 minutes spent re-reading a log.
+//
+// So the build's output is not streamed; it is REDIRECTED, in full, to a file whose path the caller is
+// handed on completion. Reading a different slice is then a `grep` of a FILE, not a second build.
 //
-// ─── Why a shell `tee` and not spawnSync's pipes ───────────────────────────────────────────────────────
-// spawnSync BUFFERS a piped stream and hands it over only after the child exits, so the human would watch
-// a silent terminal for the length of a full build. The output has to be split at the OS level, which is
-// what `tee` is. The gate keeps `stdio: 'inherit'`, so the terminal is byte-identical to today.
+// ─── Why a redirect and not `tee` ──────────────────────────────────────────────────────────────────────
+// An earlier cut of this used `cmd 2>&1 | tee log`, to keep the terminal byte-identical. That is what
+// makes the transcript expensive in the first place — an AI caller carries every line of it in context.
+// The redirect keeps the console to a handful of lines (a heartbeat, then a pointer at the file), which is
+// the entire productivity claim. Losing `tee` also deletes the `$?`-into-a-side-file dance it needed: in a
+// pipeline the shell reports TEE's status, which is 0 whether the build passed or failed, so the status
+// had to be smuggled out through a side file. With no pipe, the child's own exit code IS the answer.
 //
-// ─── Why an exit-status side file and not `pipefail` ───────────────────────────────────────────────────
-// In a pipeline the shell reports the LAST command's status, i.e. tee's, which is 0 whether the build
-// passed or failed. `set -o pipefail` and `${PIPESTATUS[0]}` are bash/zsh, and spawnSync's `shell: true`
-// gives `/bin/sh` — dash on Debian. Writing `$?` to a side file inside the group is plain POSIX and works
-// under every one of them. The redirect keeps it out of the pipe, so it never lands in the log.
-const STATUS_SUFFIX = '.status';
+// ─── Why async (`spawn`, not `spawnSync`) ──────────────────────────────────────────────────────────────
+// `spawnSync` blocks the event loop for the length of the build, so NOTHING can print while it runs — and
+// a silent terminal for 3–7 minutes is indistinguishable from a hang. The heartbeat is the reason this is
+// async, and it is why `run` returns a Promise and `BuildAffected.runBuildGate` is async with it.
+/** How often the heartbeat reports the log's size. Hardcoded: a knob here would be a knob the PR gate's
+ * own build never receives, and the two must stay the same command. */
+exports.HEARTBEAT_MS = 10_000;
+/** How many trailing log lines the failure message echoes, so the immediate cause is visible without a
+ * second command. Small on purpose — the FULL log is one grep away and the message must not become the
+ * transcript it exists to replace. */
+exports.FAILURE_TAIL_LINES = 20;
 /**
- * Which stage's gate is being captured. The value is part of the log FILENAME, so review and finish never
- * write the same file even at the same commit on the same branch.
+ * Which stage's gate is being captured. The value decides the log FILENAME.
  */
 exports.REVIEW_STAGE = 'review';
 exports.FINISH_STAGE = 'finish';
 // `wp-build`, which is not a stage of the PR flow but runs the SAME gate (BuildAffected.runBuildGate).
-// Its own id so a developer's inner-loop build never overwrites the log stage ② or ③ is holding.
 exports.BUILD_STAGE = 'build';
+/** The one fixed log name — see BuildGateLog.fileNameFor for why only `wp-build` gets one. */
+exports.BUILD_LOG_NAME = 'build.log';
+const BACKUP_SUFFIX = '.bak';
 /**
- * Captures the build gate's full output to `.webpieces/logs/`, and renders the small pointer the AI is
- * handed instead of a rebuild instruction.
+ * The heartbeat's state: the line count reported on the PREVIOUS tick, so a tick that has not moved can
+ * say so. Stateful per RUN, which is why it is constructed per run rather than injected.
+ *
+ * `still` is the load-bearing word. A build that is linking, or waiting on a cold nx cache, produces no
+ * output for minutes; without `still` the caller sees the same number twice and cannot tell a stalled
+ * BUILD from a stalled REPORTER.
+ */
+class BuildLogHeartbeat {
+    logPath;
+    displayPath;
+    previous = null;
+    constructor(logPath, displayPath) {
+        this.logPath = logPath;
+        this.displayPath = displayPath;
+    }
+    /** One heartbeat line — `<path> size <n> lines`, plus ` still` when <n> has not moved. */
+    tick() {
+        const count = this.lineCount();
+        const still = this.previous !== null && count === this.previous ? ' still' : '';
+        this.previous = count;
+        return `${this.displayPath} size ${count} lines${still}`;
+    }
+    // Lines currently in the log. A log that does not exist yet is zero lines, not an error: the build may
+    // simply not have written its first byte, and a heartbeat may never be the reason a build stops.
+    lineCount() {
+        if (!fs.existsSync(this.logPath))
+            return 0;
+        const body = fs.readFileSync(this.logPath, 'utf8');
+        if (body === '')
+            return 0;
+        return body.split('\n').length - (body.endsWith('\n') ? 1 : 0);
+    }
+}
+exports.BuildLogHeartbeat = BuildLogHeartbeat;
+/**
+ * Captures the build gate's full output to a file, reports progress while it runs, and renders the
+ * pointer the caller is handed instead of a rebuild instruction.
+ *
+ * ─── Two naming schemes, one rule each ─────────────────────────────────────────────────────────────────
+ *   • `wp-build` (BUILD_STAGE) writes ONE fixed path, `.webpieces/build.log`. It is fixed because a HUMAN
+ *     OR AN AGENT TYPES IT — `grep -n error .webpieces/build.log` has to be writable from memory, and a
+ *     name carrying a branch and a sha is not. History comes from the rotation below instead.
+ *   • stage ② and stage ③ write `logs/build-gate-<stage>-<branch>-<shortSha>.log`, because those two
+ *     gates CAN run against one commit and a failure message from one must not be pointing at a file the
+ *     other overwrote. Nobody types those names; the failure message prints them.
+ *
+ * ─── Rotation, everywhere ──────────────────────────────────────────────────────────────────────────────
+ * Every run moves an existing log to `<log>.bak` before writing, so the last TWO runs are always on disk.
+ * One rule for every stage: no branch, and the previous run of a re-run at the same commit survives
+ * instead of being truncated away.
  *
- * ─── Why the filename cannot collide ───────────────────────────────────────────────────────────────────
- * The path is `dotWebpieces.logsFile(repoRoot, 'build-gate-<stage>-<branch>-<shortSha>.log')`, and each
- * component rules out one class of concurrent writer:
- *   • the DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree
- *     name>/logs/` in a linked worktree. Every worktree therefore has its own log directory already, which
- *     is what makes "N agents in N worktrees" safe by construction rather than by naming.
- *   • `<stage>` separates review from finish, the two gates that CAN run against one commit.
- *   • `<branch>` — a branch can be checked out in at most one worktree (git enforces it), so within one
- *     log directory the branch is effectively constant; it is in the name so a human reading the directory
- *     can tell whose log is whose, and so switching branches never appends to a stale file.
- *   • `<shortSha>` — a re-run at a NEW commit gets a new file, so the log a failure message points at is
- *     always the build for the code that failed. A re-run at the SAME commit deliberately TRUNCATES: it is
- *     the same build of the same tree, and the fresh one is the one worth reading.
- * The residual case is two agents running the same stage, at the same commit, in the SAME worktree,
- * simultaneously. That is already unsupported — both would be driving one git index and one merge state —
- * and it is the only case this scheme does not separate.
+ * ─── Concurrency ───────────────────────────────────────────────────────────────────────────────────────
+ * The DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree name>/`
+ * in a linked worktree — so "N agents in N worktrees" is safe by construction rather than by naming. The
+ * residual case is two builds in the SAME worktree at once, which is already unsupported: both would be
+ * driving one git index.
  */
 let BuildGateLog = class BuildGateLog {
-    /** Absolute path of the log for `stage` at the current HEAD, creating the log directory. */
+    /** Absolute path of the log for `stage` at the current HEAD, creating its directory. */
     pathFor(repoRoot, stage) {
-        const file = rules_config_1.dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));
+        const file = this.resolvePath(repoRoot, stage);
         fs.mkdirSync(path.dirname(file), { recursive: true });
         return file;
     }
     /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */
     existingLogFor(repoRoot, stage) {
-        const file = rules_config_1.dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));
+        const file = this.resolvePath(repoRoot, stage);
         return fs.existsSync(file) ? file : '';
     }
-    /** `build-gate-<stage>-<branch>-<shortSha>.log` — see the class docstring for why this cannot collide. */
+    /** `build.log` for `wp-build`; `build-gate-<stage>-<branch>-<shortSha>.log` for the PR-flow stages. */
     fileNameFor(repoRoot, stage) {
+        if (stage === exports.BUILD_STAGE)
+            return exports.BUILD_LOG_NAME;
         const branch = this.slug(this.git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']));
         const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));
         return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;
     }
+    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */
+    backupPathFor(logPath) {
+        return `${logPath}${BACKUP_SUFFIX}`;
+    }
+    /**
+     * Move an existing log aside to `<log>.bak`, overwriting any previous backup. A missing log is the
+     * normal first-run state and is not an error.
+     */
+    rotate(logPath) {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        if (!fs.existsSync(logPath))
+            return;
+        fs.rmSync(this.backupPathFor(logPath), { force: true });
+        fs.renameSync(logPath, this.backupPathFor(logPath));
+    }
     /**
-     * Run `buildCommand` with its combined stdout+stderr streaming to the terminal AND appended in full to
-     * `logPath`. Returns the BUILD's exit code (not tee's). Nothing is truncated.
+     * Run `buildCommand` with its stdout AND stderr redirected in full to `logPath`, printing a heartbeat
+     * to the console every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code.
+     * Nothing is truncated and nothing is streamed.
      */
-    run(repoRoot, buildCommand, logPath) {
-        const statusFile = `${logPath}${STATUS_SUFFIX}`;
-        fs.rmSync(statusFile, { force: true });
-        const result = (0, child_process_1.spawnSync)(this.wrap(buildCommand, logPath, statusFile), { stdio: 'inherit', cwd: repoRoot, shell: true });
-        const fromFile = this.readStatus(statusFile);
-        fs.rmSync(statusFile, { force: true });
-        if (fromFile !== null)
-            return fromFile;
-        // The side file never appeared ⇒ the shell died before the echo. The PIPELINE's status is tee's,
-        // which is 0, and reporting 0 there would call a dead build green — so fail CLOSED instead.
-        return result.status !== null && result.status !== 0 ? result.status : 1;
+    async run(repoRoot, buildCommand, logPath) {
+        this.rotate(logPath);
+        const fd = fs.openSync(logPath, 'w');
+        const heartbeat = new BuildLogHeartbeat(logPath, this.displayPath(repoRoot, logPath));
+        const timer = setInterval(() => { process.stdout.write(`${heartbeat.tick()}\n`); }, exports.HEARTBEAT_MS);
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the timer and the fd MUST be released
+        // whatever the child does, and the exit code is returned rather than thrown so runBuildGate owns
+        // the one CliExitError.
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return await this.awaitExit((0, child_process_1.spawn)(buildCommand, { cwd: repoRoot, shell: true, stdio: ['ignore', fd, fd] }), fd);
+        }
+        finally {
+            clearInterval(timer);
+            fs.closeSync(fd);
+        }
     }
     /**
-     * The ENTIRE message the AI gets on a captured failure. Deliberately tiny: the whole point is that the
-     * agent reads ONE file rather than carrying a build transcript in its context.
+     * The success summary: the caller is told WHERE the full output is, not handed the output.
+     */
+    successMessage(logPath) {
+        return `\nBuild success\n${this.logPointer(logPath)}`;
+    }
+    /**
+     * The ENTIRE message the caller gets on a failed build. It names the log, echoes the last
+     * FAILURE_TAIL_LINES lines so the immediate cause needs no second command, and forbids the rebuild
+     * this whole file exists to prevent.
      *
      * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong
-     * (a runner that died without printing, a truncated pipe), and the worst possible response is an agent
-     * guessing or rebuilding — so it is told to surface the contradiction to the human and stop.
+     * (a runner that died without printing, a truncated redirect), and the worst possible response is an
+     * agent guessing or rebuilding — so it is told to surface the contradiction to the human and stop.
      */
     failureMessage(buildCommand, logPath) {
-        return `\n❌ The CI build failed. We ran\n\n` +
-            `    ${buildCommand} > ${logPath}\n\n` +
-            `and it failed, so read that file for the failures. Do NOT re-run the build to see them.\n` +
+        return `\nBuild Failed: ${buildCommand}\n${this.logPointer(logPath)}\n` +
+            `Last ${exports.FAILURE_TAIL_LINES} lines of that log:\n${this.tail(logPath)}\n` +
+            `Read that FILE for the failures. Do NOT re-run the build to see them.\n` +
             `If you do not see failures in that log, report that to the user and stop.\n`;
     }
+    // The two lines that name the log, identical on success and failure so there is one thing to recognise.
+    // The backup line says what is TRUE RIGHT NOW: on the very first build in a tree there is no `.bak`
+    // yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.
+    logPointer(logPath) {
+        const name = path.basename(logPath);
+        const backedUp = fs.existsSync(this.backupPathFor(logPath))
+            ? `(${name} is backed up to ${name}${BACKUP_SUFFIX} every run so you have the last 2 builds of logs)`
+            : `(the previous ${name} is kept as ${name}${BACKUP_SUFFIX} on every run — this is the first, so there is none yet)`;
+        return `FullLog : ${logPath}\n${backedUp}\n`;
+    }
     /**
-     * `{ ( <build> ) ; echo $? > <status> ; } 2>&1 | tee <log>` — written across LINES so a build command
-     * ending in a `#` comment cannot swallow what follows it.
+     * The log's last FAILURE_TAIL_LINES lines, or a plain statement of why there are none.
      *
-     * The inner `( … )` is load-bearing, not decoration. The left side of a pipeline is already a subshell,
-     * so a build command containing a plain `exit 7` (or any script that calls `exit`) would terminate that
-     * subshell OUTRIGHT — `echo $?` never runs, the side file never appears, and the only status left is
-     * tee's 0. The nested subshell absorbs the `exit`, so `$?` is the build's code every time.
+     * A read that fails is REPORTED, never allowed to throw: this renders the message for a build that has
+     * ALREADY failed, so an I/O error escaping here would replace the real failure with the renderer's own
+     * — the caller would lose the build error and be handed a filesystem error instead. The full log is
+     * still named on the line above, so nothing is hidden by degrading to one line.
      */
-    wrap(buildCommand, logPath, statusFile) {
-        return `{\n(\n${buildCommand}\n)\necho $? > ${this.quote(statusFile)}\n} 2>&1 | tee ${this.quote(logPath)}`;
-    }
-    // The build's own exit code, or null when the side file never appeared (the shell died before the echo).
-    readStatus(statusFile) {
-        if (!fs.existsSync(statusFile))
-            return null;
-        const parsed = Number.parseInt(fs.readFileSync(statusFile, 'utf8').trim(), 10);
-        return Number.isNaN(parsed) ? null : parsed;
-    }
-    // POSIX single-quoting: everything is literal inside '…', and a literal ' is spelled '\''.
-    quote(value) {
-        return `'${value.split("'").join(`'\\''`)}'`;
+    tail(logPath) {
+        if (!fs.existsSync(logPath))
+            return `    (no log file at ${logPath})\n`;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: see above, the failure renderer may not
+        // replace the build's failure with its own.
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter((l) => l !== '');
+            if (lines.length === 0)
+                return '    (the log is empty)\n';
+            return lines.slice(-exports.FAILURE_TAIL_LINES).map((l) => `    ${l}\n`).join('');
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            return `    (could not read ${logPath}: ${error.message})\n`;
+        }
+    }
+    // Resolve, and wait for, the child's exit code. A spawn that never starts (a shell that is missing, a
+    // cwd that vanished) fails CLOSED to 1 — calling a build that never ran green is the one outcome that
+    // must be impossible — and the reason is APPENDED TO THE LOG, so the failure message's pointer still
+    // leads to it rather than to an empty file.
+    awaitExit(child, fd) {
+        return new Promise((resolve) => {
+            child.on('error', (err) => {
+                fs.writeSync(fd, `\nThe build command could not be started: ${err.message}\n`);
+                resolve(1);
+            });
+            child.on('close', (code) => { resolve(code ?? 1); });
+        });
+    }
+    // The path as the heartbeat shows it: relative to the repo when it sits inside it (a linked worktree's
+    // state lives under the PRIMARY clone, so it often does not), absolute otherwise.
+    displayPath(repoRoot, logPath) {
+        const relative = path.relative(repoRoot, logPath);
+        return relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? logPath : relative;
+    }
+    resolvePath(repoRoot, stage) {
+        const name = this.fileNameFor(repoRoot, stage);
+        // `wp-build`'s log sits at the ROOT of the state dir, not under `logs/`, because it is the one log
+        // path a person types from memory. Everything else keeps the per-commit names in `logs/`.
+        return stage === exports.BUILD_STAGE ? rules_config_1.dotWebpieces.localFile(repoRoot, name) : rules_config_1.dotWebpieces.logsFile(repoRoot, name);
     }
     // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.
     slug(value) {