@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/release_drill.ts

@@ -26,6 +26,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -37,6 +38,8 @@ import {
     Plan,
     SystemExitError,
 } from './release.js';
+import { releaseHoldPreflight } from './_lib/release_holds.js';
+import { die } from './release_publication.js';
 import { DERIVED_MARKER } from './_lib/release_highlights.js';
 import {
     AUGMENT_MARKETPLACE_JSON,
@@ -126,6 +129,33 @@ interface WorldConfig {
      * existed.
      */
     branch_behind_main?: number;
+    /**
+     * Commits `origin/<release-branch>` carries that this checkout does not.
+     *
+     * Sibling of `branch_behind_main`, one ref over: that one fakes `git
+     * rev-list --count HEAD..origin/main`, this one the distance to the
+     * release branch's OWN remote — the divergence a GitHub *Update branch*
+     * press or a concurrent resume run produces.
+     */
+    branch_behind_remote?: number;
+    /**
+     * Commits this checkout carries that `origin/<release-branch>` does not.
+     *
+     * Defaults to 1 so every pre-existing scenario keeps the local-ahead shape
+     * it was written against. Set to 0 together with `branch_behind_remote: 0`
+     * to reach the state where the remote is already AT head and the push must
+     * therefore not be issued at all.
+     */
+    branch_ahead_remote?: number;
+    /**
+     * Whether `origin/<release-branch>` exists at the start of the run.
+     *
+     * Internal state until 2026-09-12 — a scenario could only reach `false`
+     * indirectly, by having the run delete the branch. The remote-position
+     * probe added with `_remote_branch_state` has a never-pushed arm that no
+     * scenario could otherwise enter, so the knob is now declared.
+     */
+    branch_exists_remote?: boolean;
     /**
      * Whether `execute()` is invoked with `--resume`. Defaults to TRUE so every
      * pre-existing scenario keeps the shape it was written against.
@@ -319,6 +349,8 @@ class FakeWorld {
     private push_rejections: number;
     private behind_probes: number;
     private branch_behind_main: number;
+    private branch_behind_remote: number;
+    private readonly branch_ahead_remote: number;
     private merge_races_once: boolean;
     private merge_fails_hard: boolean;
     private checks_fail: boolean;
@@ -341,6 +373,9 @@ class FakeWorld {
         this.tag_remote = cfg.tag_already_remote ?? false;
         this.behind_probes = cfg.behind_probes ?? 0;
         this.branch_behind_main = cfg.branch_behind_main ?? 0;
+        this.branch_exists_remote = cfg.branch_exists_remote ?? true;
+        this.branch_behind_remote = cfg.branch_behind_remote ?? 0;
+        this.branch_ahead_remote = cfg.branch_ahead_remote ?? 1;
         this.merge_races_once = cfg.merge_races_once ?? false;
         this.merge_fails_hard = cfg.merge_fails_hard ?? false;
         this.checks_fail = cfg.checks_fail ?? false;
@@ -375,6 +410,18 @@ class FakeWorld {
             this.branch_behind_main = 0;
             return OK;
         }
+        if (cmd === `git rev-list --left-right --count HEAD...origin/${this.branch}`) {
+            return {
+                ...OK,
+                stdout: `${String(this.branch_ahead_remote)}\t${String(this.branch_behind_remote)}\n`,
+            };
+        }
+        if (cmd === `git merge --no-edit origin/${this.branch}`) {
+            // A real merge closes the gap, so the re-read sees 0 — the same
+            // reason the origin/main handler above zeroes its own counter.
+            this.branch_behind_remote = 0;
+            return OK;
+        }
         if (cmd === `git rev-parse --verify --quiet refs/heads/${this.branch}`) {
             return this.pr_merged ? { ...OK, status: 1 } : OK;
         }
@@ -544,6 +591,16 @@ interface Scenario {
     /** What the scenario proves — printed by the CLI. */
     summary: string;
     config: WorldConfig;
+    /**
+     * Run THIS instead of `execute()`.
+     *
+     * Added for the release-holds scenarios, whose boundary is `preflight()` —
+     * it runs before step 1 and therefore before `execute()`, so a scenario
+     * driving `execute()` could never reach it. Every pre-existing scenario
+     * omits the field and keeps `execute()` byte-identically; the override is
+     * additive and changes nothing it does not set.
+     */
+    run?: () => void;
     /** Whether execute() is expected to complete (vs die/throw). */
     expect_success: boolean;
     /** Extra assertions over the finished world; return failure strings. */
@@ -560,7 +617,137 @@ function _count(world: FakeWorld, needle: string): number {
     return world.calls.filter((c) => c === needle).length;
 }
 
+
+/* ------------------------------------------------------------------ *
+ * Release-holds fixtures (template rule 28, roadmap step 4.3).
+ *
+ * A throwaway tree per scenario, because the assertion is about what the
+ * evaluator READS — a mocked return would assert the mock.
+ * ------------------------------------------------------------------ */
+
+function _holdFixtureRoot(name: string, body: string): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), `release-holds-${name}-`));
+    const dir = path.join(root, 'agents', 'roadmaps');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'fixture.md'), body, 'utf8');
+    return root;
+}
+
+function _openHoldBody(channel: string): string {
+    return [
+        '## Phase 1',
+        '- [x] **1.1 opener** <!-- opens-hold: half-wired -->',
+        '      verify: the opener\'s own check',
+        '- [ ] **1.2 clearer** <!-- clears-hold: half-wired -->',
+        '      verify: ./scripts-run src/scripts/check_surface_whole',
+        '',
+        '## Release holds',
+        '',
+        '### hold: half-wired',
+        `- **Channel:** ${channel}`,
+        '- **Opened by:** 1.1',
+        '- **Cleared by:** 1.2',
+        '- **State:** the surface is half wired while this is open.',
+        '- **Why not a guard:** the entry point is reachable and cannot be made inert.',
+        '',
+    ].join('\n');
+}
+
 const SCENARIOS: Record<string, Scenario> = {
+    'release-hold-open-all-refuses-the-cut': {
+        summary:
+            'pre-flight: an open hold with `Channel: all` refuses the cut, naming the roadmap, the hold, its opener, its closer and the closer\'s verify command',
+        config: {},
+        expect_success: false,
+        run: () => {
+            releaseHoldPreflight(_holdFixtureRoot('all', _openHoldBody('all')), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            // All five fields, asserted individually. A refusal missing any one
+            // of them tells the operator they are stuck rather than what to do,
+            // which is the failure step 4.1 names.
+            for (const field of [
+                'fixture.md',
+                'half-wired',
+                'opened by:  1.1',
+                'cleared by: 1.2',
+                'check_surface_whole',
+            ]) {
+                _expect(msg.includes(field), `the refusal never named \`${field}\`: ${msg}`, f);
+            }
+            for (const way of ['finish the clearing step', '-next.N', 'release line']) {
+                _expect(msg.includes(way), `the refusal never offered \`${way}\`: ${msg}`, f);
+            }
+            return f;
+        },
+    },
+    'release-hold-open-latest-refuses-the-stable-cut': {
+        summary:
+            'pre-flight: an open hold with `Channel: latest` still refuses, because release.ts cuts a bare X.Y.Z and never silently redirects it to a prerelease',
+        config: {},
+        expect_success: false,
+        run: () => {
+            releaseHoldPreflight(_holdFixtureRoot('latest', _openHoldBody('latest')), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            _expect(msg.includes('half-wired'), `the refusal never named the hold: ${msg}`, f);
+            _expect(
+                msg.includes('channel latest'),
+                `the refusal never showed the hold's own channel: ${msg}`,
+                f,
+            );
+            // The silent-redirect prohibition, asserted as a behaviour rather
+            // than as a grep: the run DIED. A release.ts that quietly converted
+            // this into `-next.N` would have completed.
+            _expect(
+                msg.startsWith('SystemExit('),
+                `the stable cut was not refused — a silent channel redirect: ${msg}`,
+                f,
+            );
+            return f;
+        },
+    },
+    'release-hold-not-evaluable-refuses-the-cut': {
+        summary:
+            'pre-flight: a malformed declaration the evaluator cannot read refuses the cut — there is no path on which "could not evaluate" reads as safe',
+        config: {},
+        expect_success: false,
+        run: () => {
+            // Missing `Why not a guard:`, which rule 28 makes mandatory. The
+            // evaluator can parse the file but not trust the declaration, which
+            // is exactly the not-evaluable row.
+            const body = _openHoldBody('all').replace(
+                /- \*\*Why not a guard:\*\*.*\n/,
+                '',
+            );
+            releaseHoldPreflight(_holdFixtureRoot('bad', body), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            _expect(
+                msg.startsWith('SystemExit('),
+                `an unreadable declaration did not refuse — it failed OPEN: ${msg}`,
+                f,
+            );
+            _expect(
+                msg.includes('not evaluable'),
+                `the refusal did not say the declaration was unreadable: ${msg}`,
+                f,
+            );
+            _expect(
+                msg.includes('Why not a guard'),
+                `the refusal did not name what was wrong with it: ${msg}`,
+                f,
+            );
+            return f;
+        },
+    },
+
     'findings-ledger-verified-on-the-remote-branch': {
         summary:
             'step 7: the ledger is on the remote branch and the gate passes — the release continues without producing anything',
@@ -752,6 +939,81 @@ const SCENARIOS: Record<string, Scenario> = {
             return f;
         },
     },
+    'remote-branch-moved-merges-before-push': {
+        summary:
+            'step 4: a release branch that diverged on the remote is merged in BEFORE the push — not after a rejection the local preflight never lets git produce',
+        // Measured 2026-09-12 on 16.0.0. `origin/release/16.0.0` carried five
+        // commits this checkout did not have. `push_release_branch` has a
+        // merge-and-retry for exactly that, keyed on git's rejection wording —
+        // but the local pre-push preflight refused first, with
+        // `check_pr_ci_current`'s own message naming the divergence. git never
+        // printed `[rejected]`, `_is_non_fast_forward` correctly answered
+        // "not the fetch-and-retry case" on the text it was given, and the
+        // recovery was unreachable from the state it was written for.
+        config: { branch_behind_remote: 5 },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            const merge = w.calls.indexOf(`git merge --no-edit origin/${w.branch}`);
+            const push = w.calls.indexOf(`git push -u origin ${w.branch}`);
+            _expect(merge >= 0, 'the diverged remote branch was never merged in', f);
+            _expect(push >= 0, 'the branch was never pushed', f);
+            // Ordering is the whole point: a merge only AFTER the push means
+            // the reactive path ran, and that path is what the gate pre-empts.
+            _expect(
+                merge >= 0 && push >= 0 && merge < push,
+                'the remote branch was merged after the push, not before it',
+                f,
+            );
+            _expect(
+                _count(w, `git merge --no-edit origin/${w.branch}`) === 1,
+                'merged the remote branch more than once — the probe is not re-read after the merge',
+                f,
+            );
+            return f;
+        },
+    },
+    'remote-already-at-head-skips-the-push': {
+        summary:
+            'step 4: a remote already carrying this commit is not pushed to again — the no-op push still runs the pre-push hook, and the hook refuses',
+        // The second half of the same 16.0.0 failure, and the one no rejection
+        // text can reach. The push had succeeded; a resumed run re-entered
+        // step 4 and pushed again. `git push -u` is idempotent on the network
+        // side, but git runs the pre-push hook BEFORE discovering there is
+        // nothing to send — so the preflight was handed the head this run had
+        // just pushed, found its CI still pending, and killed the release.
+        config: { branch_ahead_remote: 0, branch_behind_remote: 0 },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            _expect(
+                !w.calls.includes(`git push -u origin ${w.branch}`),
+                'pushed a branch the remote already carries — that push runs the pre-push hook for nothing',
+                f,
+            );
+            return f;
+        },
+    },
+    'unpushed-branch-still-pushes': {
+        summary:
+            'step 4: a branch that was never pushed is pushed, and no distance is probed against a remote ref that does not exist',
+        // The near-miss for the direction the new probe opens: `git rev-list
+        // HEAD...origin/<branch>` against a missing ref is the 9.26.0 shape all
+        // over again — an exit from the recovery masking the real state.
+        // `--exit-code` on the ls-remote probe is what keeps it closed.
+        config: { branch_exists_remote: false },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            _expect(w.calls.includes(`git push -u origin ${w.branch}`), 'the branch was never pushed', f);
+            _expect(
+                !w.calls.includes(`git rev-list --left-right --count HEAD...origin/${w.branch}`),
+                'probed the distance to a remote ref that does not exist',
+                f,
+            );
+            return f;
+        },
+    },
     'local-gates-refuse-before-push': {
         summary:
             'step 4: a red local release gate stops the run BEFORE the branch is pushed — no branch on origin, no PR, no CI',
@@ -1087,7 +1349,11 @@ function run_scenario(name: string): ScenarioOutcome {
     // Without this the drill's step 9 reads the repository's real CHANGELOG.md.
     _set_changelog_reader(() => world.changelog_file);
     try {
-        execute(plan, { wait_for_checks: true, dry_run: false, resume: scenario.config.resume ?? true });
+        if (scenario.run !== undefined) {
+            scenario.run();
+        } else {
+            execute(plan, { wait_for_checks: true, dry_run: false, resume: scenario.config.resume ?? true });
+        }
     } catch (err) {
         if (err instanceof SystemExitError) {
             error = `SystemExit(${err.code}): ${captured.join('')}`;

package/src/scripts/release_publication.ts

@@ -745,8 +745,59 @@ export function guard_release_curation(version: string, prMerged = false): void
     );
 }
 
+/**
+ * What `REMOTE/<branch>` holds relative to HEAD, before anything is pushed.
+ *
+ * `push_release_branch` used to issue the push and learn the remote's position
+ * only from the rejection that came back. That reading is unavailable in two
+ * measured states, both on 16.0.0 (2026-09-12): the local pre-push gate refuses
+ * a diverged branch before git can print `[rejected]`, and a remote already AT
+ * head produces no rejection at all — git runs the pre-push hook before it
+ * discovers there is nothing to send, so the hook refuses over CI still pending
+ * on the head this run had already pushed. Asking first is the only place both
+ * are visible.
+ */
+type RemoteBranchState = 'absent' | 'in-sync' | 'remote-ahead' | 'local-ahead';
+
+function _remote_branch_state(branch: string): RemoteBranchState {
+    // `--exit-code` so a never-pushed branch reads as a clean non-zero rather
+    // than an empty success the count below would then run against a missing
+    // ref — the exit-128 masking this file already carries a test for.
+    const exists = run(['git', 'ls-remote', '--exit-code', '--heads', REMOTE, branch], {
+        check: false,
+        capture: true,
+    });
+    if (exists.returncode !== 0) return 'absent';
+    run(['git', 'fetch', REMOTE, branch], { check: false, capture: true });
+    const counts = run(['git', 'rev-list', '--left-right', '--count', `HEAD...${REMOTE}/${branch}`], {
+        check: false,
+        capture: true,
+    });
+    // Unreadable → push and let git judge, which is the pre-2026-09-12 behaviour.
+    if (counts.returncode !== 0) return 'local-ahead';
+    const [ahead = '0', behind = '0'] = counts.stdout.trim().split(/\s+/);
+    if (Number(behind) > 0) return 'remote-ahead';
+    return Number(ahead) > 0 ? 'local-ahead' : 'in-sync';
+}
+
 function push_release_branch(branch: string): void {
+    let state = _remote_branch_state(branch);
+    if (state === 'remote-ahead') {
+        process.stdout.write(`↻  ${REMOTE}/${branch} moved under us — merging it in before the push\n`);
+        run(['git', 'merge', '--no-edit', `${REMOTE}/${branch}`]);
+        // Re-read: a fast-forward merge lands HEAD exactly on the remote, and
+        // the push that followed would then be the no-op case below.
+        state = _remote_branch_state(branch);
+    }
+
     guard_release_branch_push(branch);
+
+    // Ahead of the skip on purpose: the guard validates the release content,
+    // which has to be right whether or not this run is the one that sends it.
+    if (state === 'in-sync') {
+        process.stdout.write(`✅  ${REMOTE}/${branch} already carries this commit — nothing to push\n`);
+        return;
+    }
     const first = run(['git', 'push', '-u', REMOTE, branch], { check: false, capture: true });
     if (first.returncode === 0) {
         process.stdout.write(first.stdout);