@event4u/agent-config 9.25.0 → 9.27.0

package/src/scripts/orchestration_backfill.ts

@@ -0,0 +1,354 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Backfill orchestration telemetry from the host transcript corpus.
+ *
+ * Why this exists (road-to-orchestrator-first-execution Phase 1). Two roadmaps
+ * are blocked on "≥20 orchestration lines in the current month", with the
+ * stated remedy "use the agent on real delegable work". Measured 2026-08-07:
+ * the agent was used on real delegable work **370 times** in this repo over one
+ * month, and `orchestration_record` — a model-carried emit step — captured
+ * exactly **one** of them. The blocker was never a usage problem; it is an
+ * instrumentation defect, and the data it was waiting for is already on disk.
+ *
+ * What this reads. The host writes one JSONL transcript per session under
+ * `~/.claude/projects/<slugified-project-path>/`. An `Agent` dispatch appears
+ * as a `tool_use` block; its result appears as a `toolUseResult` object.
+ *
+ * The coverage limit, which is the point rather than a footnote. Only
+ * SYNCHRONOUS dispatches carry cost: `totalTokens`, `totalDurationMs`,
+ * `usage`. An ASYNCHRONOUS dispatch returns a launch acknowledgement
+ * (`isAsync: true`, `status: "async_launched"`) and its completion never
+ * writes cost back into the parent transcript. So the metric-bearing
+ * population is a strict subset, and this script reports both counts rather
+ * than the flattering one. Emitting 370 lines of which 331 carry a null cost
+ * would inflate n against a gate that counts lines.
+ *
+ * What this deliberately does NOT do. It does not compute a `token_delta`
+ * against an in-session baseline. That counterfactual is not on disk and is
+ * not measured by anything, so synthesising one here and stamping it
+ * `measured` is the exact laundering `orchestration-observed-dispatch-cost`
+ * criterion (2) forbids. The orchestrated side is measured; the baseline is a
+ * downstream decision that must name its own method.
+ *
+ * Read-only. Never mutates a transcript.
+ */
+
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+/** One dispatch-family. `unclassified` is a real answer, never a guess. */
+export type DispatchFamily =
+    | 'read-only-fanout'
+    | 'ordered-steps'
+    | 'competitive'
+    | 'verdict-judge'
+    | 'unclassified';
+
+/**
+ * One backfilled dispatch.
+ *
+ * PII/leak-exclusion by construction: the host's free-text `description` and
+ * `prompt` are read to CLASSIFY and are then dropped — no field here can carry
+ * free-form content. This is not fastidiousness: the first real run emitted a
+ * historical task description carrying a denylisted external-source name and
+ * tripped `check_no_external_sources`. A type that cannot hold arbitrary text
+ * has no scrubber to fail, which is the same principle
+ * `artifact-engagement-recording` states for telemetry events. Never widen
+ * this with a `description` / `notes` / `payload` field.
+ */
+export interface BackfilledDispatch {
+    session_id: string;
+    tool_use_id: string;
+    timestamp: string | null;
+    subagent_type: string | null;
+    family: DispatchFamily;
+    family_signal: string;
+    resolved_model: string | null;
+    /** Measured orchestrated-side cost. `null` on an async dispatch. */
+    total_tokens: number | null;
+    wall_clock_ms: number | null;
+    tool_use_count: number | null;
+    /** `measured` only when the host recorded the cost; never inferred. */
+    cost_provenance: 'measured' | 'absent';
+    async_launch: boolean;
+}
+
+/**
+ * Slugify a project path the way the host names its transcript directory:
+ * every character outside `[A-Za-z0-9]` becomes `-`.
+ */
+export function transcriptDirFor(projectPath: string, home = homedir()): string {
+    return join(home, '.claude', 'projects', projectPath.replace(/[^A-Za-z0-9]/g, '-'));
+}
+
+/**
+ * Classify a dispatch into a family from OBSERVABLE fields only.
+ *
+ * The council's round-2 finding was that eight dispatch templates were being
+ * treated as one hypothesis. Family is therefore carried per line. Where no
+ * enumerated signal matches, the answer is `unclassified` — the same
+ * discipline `classifyTask` applies when no delegable signal matches. A
+ * classifier that always produces a family would make the per-family split
+ * meaningless.
+ */
+export function classifyFamily(
+    subagentType: string | null,
+    description: string | null,
+    prompt: string | null,
+): { family: DispatchFamily; signal: string } {
+    const hay = `${description ?? ''}\n${prompt ?? ''}`.toLowerCase();
+
+    // Verdict/judge first — it is the narrowest and can otherwise be swallowed
+    // by the read-only signal, since most verdict passes are also read-only.
+    if (subagentType === 'production-validator') {
+        return { family: 'verdict-judge', signal: 'subagent_type=production-validator' };
+    }
+    if (/\b(verify|verdict|judge|adjudicat|audit this|review this|acceptance criterion)\b/.test(hay)) {
+        return { family: 'verdict-judge', signal: 'verdict-shaped verb in description/prompt' };
+    }
+
+    if (subagentType === 'Explore') {
+        return { family: 'read-only-fanout', signal: 'subagent_type=Explore' };
+    }
+    if (/\b(read-only|do not edit|never edit|investigation only|map |inventory|locate)\b/.test(hay)) {
+        return { family: 'read-only-fanout', signal: 'read-only declaration in prompt' };
+    }
+
+    if (/\b(step \d|then |after (the )?previous|in order|sequentially|depends on step)\b/.test(hay)) {
+        return { family: 'ordered-steps', signal: 'ordering language in prompt' };
+    }
+
+    if (/\b(variant|competing|alternative approach|candidate [ab]|independently propose)\b/.test(hay)) {
+        return { family: 'competitive', signal: 'competitive framing in prompt' };
+    }
+
+    return { family: 'unclassified', signal: 'no enumerated family signal matched' };
+}
+
+interface Extraction {
+    dispatches: BackfilledDispatch[];
+    sessions_scanned: number;
+    unparseable_lines: number;
+}
+
+/** Walk one project's transcript corpus and pair each `Agent` tool_use with its result. */
+export function extract(dir: string): Extraction {
+    if (!existsSync(dir)) {
+        return { dispatches: [], sessions_scanned: 0, unparseable_lines: 0 };
+    }
+    const files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    const dispatches: BackfilledDispatch[] = [];
+    let unparseable = 0;
+
+    for (const file of files) {
+        const sessionId = file.replace(/\.jsonl$/, '');
+        // tool_use_id → the dispatch we are still waiting on a result for.
+        const pending = new Map<string, Partial<BackfilledDispatch> & { prompt: string | null; description: string | null }>();
+        const emitted = new Map<string, BackfilledDispatch>();
+
+        for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+            if (line.trim() === '') continue;
+            let obj: Record<string, unknown>;
+            try {
+                obj = JSON.parse(line) as Record<string, unknown>;
+            } catch {
+                unparseable += 1;
+                continue;
+            }
+
+            const message = obj.message as Record<string, unknown> | undefined;
+            const content = message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block as Record<string, unknown>;
+                    if (b.type !== 'tool_use' || b.name !== 'Agent') continue;
+                    const input = (b.input ?? {}) as Record<string, unknown>;
+                    const id = String(b.id ?? '');
+                    if (id === '') continue;
+                    pending.set(id, {
+                        session_id: sessionId,
+                        tool_use_id: id,
+                        timestamp: typeof obj.timestamp === 'string' ? obj.timestamp : null,
+                        subagent_type: typeof input.subagent_type === 'string' ? input.subagent_type : null,
+                        description: typeof input.description === 'string' ? input.description : null,
+                        prompt: typeof input.prompt === 'string' ? input.prompt : null,
+                    });
+                }
+            }
+
+            const result = obj.toolUseResult as Record<string, unknown> | undefined;
+            if (!result || typeof result !== 'object') continue;
+            // The result carries no tool_use_id of its own; the host pairs it via
+            // the enclosing user message's tool_result block.
+            let resultId: string | null = null;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block as Record<string, unknown>;
+                    if (b.type === 'tool_result' && typeof b.tool_use_id === 'string') {
+                        resultId = b.tool_use_id;
+                    }
+                }
+            }
+            if (resultId === null || !pending.has(resultId)) continue;
+            const head = pending.get(resultId)!;
+            pending.delete(resultId);
+
+            const totalTokens = typeof result.totalTokens === 'number' ? result.totalTokens : null;
+            const { family, signal } = classifyFamily(
+                head.subagent_type ?? null,
+                head.description ?? null,
+                head.prompt,
+            );
+
+            emitted.set(resultId, {
+                session_id: sessionId,
+                tool_use_id: resultId,
+                timestamp: head.timestamp ?? null,
+                subagent_type: head.subagent_type ?? null,
+                family,
+                family_signal: signal,
+                resolved_model: typeof result.resolvedModel === 'string' ? result.resolvedModel : null,
+                total_tokens: totalTokens,
+                wall_clock_ms: typeof result.totalDurationMs === 'number' ? result.totalDurationMs : null,
+                tool_use_count: typeof result.totalToolUseCount === 'number' ? result.totalToolUseCount : null,
+                cost_provenance: totalTokens === null ? 'absent' : 'measured',
+                async_launch: result.isAsync === true,
+            });
+        }
+
+        dispatches.push(...emitted.values());
+        // A dispatch whose result never landed in this transcript (session ended
+        // mid-flight) is reported as a gap rather than dropped silently.
+        for (const [id, head] of pending) {
+            const { family, signal } = classifyFamily(
+                head.subagent_type ?? null,
+                head.description ?? null,
+                head.prompt,
+            );
+            dispatches.push({
+                session_id: sessionId,
+                tool_use_id: id,
+                timestamp: head.timestamp ?? null,
+                subagent_type: head.subagent_type ?? null,
+                family,
+                family_signal: signal,
+                resolved_model: null,
+                total_tokens: null,
+                wall_clock_ms: null,
+                tool_use_count: null,
+                cost_provenance: 'absent',
+                async_launch: false,
+            });
+        }
+    }
+
+    return { dispatches, sessions_scanned: files.length, unparseable_lines: unparseable };
+}
+
+/**
+ * The shape that actually gets written to disk.
+ *
+ * `tool_use_id` is pairing plumbing: it exists to match a dispatch to its
+ * result during extraction and has no analytical role afterwards. It is
+ * dropped at the TYPE level rather than scrubbed at write time, because the
+ * host ids are high-entropy opaque tokens and `check_secret_leak` flags them
+ * as candidate credentials — correctly, in the sense that it cannot know they
+ * are not. Emitting a field only to allow-list it downstream is the worse
+ * trade: the artifact does not need it.
+ */
+export type EmittedDispatch = Omit<BackfilledDispatch, 'tool_use_id'>;
+
+/** Project an extracted dispatch onto the emitted shape. */
+export function toEmitted(d: BackfilledDispatch): EmittedDispatch {
+    const { tool_use_id: _pairingKey, ...rest } = d;
+    return rest;
+}
+
+/** Per-family roll-up. Medians, never means — one 530k outlier should not carry a family. */
+export function summarize(dispatches: BackfilledDispatch[]): Record<string, unknown> {
+    const byFamily = new Map<string, number[]>();
+    for (const d of dispatches) {
+        if (d.cost_provenance !== 'measured' || d.total_tokens === null) continue;
+        const bucket = byFamily.get(d.family) ?? [];
+        bucket.push(d.total_tokens);
+        byFamily.set(d.family, bucket);
+    }
+    const families: Record<string, unknown> = {};
+    for (const [family, tokens] of byFamily) {
+        tokens.sort((a, b) => a - b);
+        families[family] = {
+            n: tokens.length,
+            // criterion (1): n<5 is UNDERPOWERED and is never merged to reach n.
+            power: tokens.length < 5 ? 'UNDERPOWERED' : 'reportable',
+            median_tokens: tokens[Math.floor(tokens.length / 2)],
+            min_tokens: tokens[0],
+            max_tokens: tokens[tokens.length - 1],
+            sum_tokens: tokens.reduce((a, b) => a + b, 0),
+        };
+    }
+    const measured = dispatches.filter((d) => d.cost_provenance === 'measured').length;
+    return {
+        dispatches_total: dispatches.length,
+        dispatches_with_measured_cost: measured,
+        dispatches_without_cost: dispatches.length - measured,
+        async_launches: dispatches.filter((d) => d.async_launch).length,
+        cost_coverage_ratio: dispatches.length === 0 ? 0 : Number((measured / dispatches.length).toFixed(4)),
+        families,
+        models: dispatches
+            .filter((d) => d.cost_provenance === 'measured')
+            .reduce<Record<string, number>>((acc, d) => {
+                const key = d.resolved_model ?? 'unknown';
+                acc[key] = (acc[key] ?? 0) + 1;
+                return acc;
+            }, {}),
+        baseline_note:
+            'No in-session counterfactual exists on disk. token_delta is NOT computed here; ' +
+            'any downstream comparison must name its own baseline method and stamp it estimated.',
+    };
+}
+
+function main(argv: string[]): number {
+    const projectArg = argv.indexOf('--project');
+    const project =
+        projectArg >= 0 && argv[projectArg + 1] !== undefined ? argv[projectArg + 1]! : process.cwd();
+    const outArg = argv.indexOf('--out');
+    const dir = transcriptDirFor(project);
+
+    if (!existsSync(dir)) {
+        process.stderr.write(`orchestration_backfill: no transcript corpus at ${dir}\n`);
+        return 1;
+    }
+
+    const { dispatches, sessions_scanned, unparseable_lines } = extract(dir);
+    const summary = summarize(dispatches);
+    // Emit the corpus identity, never the absolute path: the transcript
+    // directory is rooted at the operator's home and a committed report
+    // carrying it leaks an identity-revealing local path for no analytical
+    // gain (the basename already identifies which corpus was read).
+    const report = {
+        schema_version: 1,
+        source_corpus: basename(dir),
+        sessions_scanned,
+        unparseable_lines,
+        ...summary,
+    };
+
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+
+    if (outArg >= 0 && argv[outArg + 1] !== undefined) {
+        const lines = dispatches
+            .filter((d) => d.cost_provenance === 'measured')
+            .map((d) => JSON.stringify({ input_kind: 'orchestration', orchestration: toEmitted(d) }))
+            .join('\n');
+        writeFileSync(argv[outArg + 1]!, lines === '' ? '' : `${lines}\n`, 'utf8');
+        process.stderr.write(
+            `orchestration_backfill: wrote ${summary.dispatches_with_measured_cost} measured line(s) to ${argv[outArg + 1]}\n`,
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('orchestration_backfill')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/pr_url_reminder_hook.ts

@@ -66,6 +66,20 @@ function _isObject(v: unknown): v is JsonObject {
 }
 
 /** Return [tool_name, command_text] from a tool-event payload. */
+/**
+ * Unwrap the dispatcher envelope.
+ *
+ * The dispatcher hands every concern `{event, platform, payload: <native>}`,
+ * but this hook read `tool_name` / `tool_response` off the TOP level. Fed a raw
+ * payload it worked; fed the real envelope it found nothing and returned ALLOW.
+ * Measured 2026-08-06: standalone 624 bytes of output, through the built
+ * dispatcher 0 bytes — the reminder had never fired in production.
+ */
+function _unwrap(envelope: JsonObject): JsonObject {
+  const inner = envelope["payload"];
+  return _isObject(inner) ? inner : envelope;
+}
+
 function _extractCommand(payload: JsonObject): [string | null, string | null] {
   const toolRaw = payload["tool_name"] ?? payload["toolName"] ?? payload["tool"];
   const tool = typeof toolRaw === "string" ? toolRaw : null;
@@ -124,12 +138,13 @@ export function main(): number {
     return EXIT_ALLOW;
   }
 
-  const [tool, command] = _extractCommand(envelope);
+  const inner = _unwrap(envelope);
+  const [tool, command] = _extractCommand(inner);
   if (!_isPrCreate(tool, command)) {
     return EXIT_ALLOW;
   }
 
-  const match = _PR_URL.exec(_toolOutput(envelope));
+  const match = _PR_URL.exec(_toolOutput(inner));
   if (match === null) {
     return EXIT_ALLOW; // create attempted but no URL produced (failed / dry-run) — do not nag
   }

package/src/scripts/release.ts

@@ -700,13 +700,84 @@ export function _failed_checks_report(names: readonly string[]): string {
     return lines.join('\n');
 }
 
+/** Rounds of re-watching before an absent required check is called absent. */
+const _NO_CHECKS_ROUNDS = 10;
+/** Delay between those rounds — 10 × 60 s ≈ 10 minutes of tolerance. */
+const _NO_CHECKS_DELAY_MS = 60_000;
+
 /**
- * Watch PR checks and tolerate the 'no checks' case.
+ * Required status-check contexts for a branch, parsed from
+ * `gh api repos/{owner}/{repo}/rules/branches/{branch}`.
+ *
+ * That endpoint is the one that answers the question here: this repo protects
+ * `main` with a RULESET, and the classic `/branches/main/protection` API
+ * answers "Branch not protected" for it — so a check built on the classic
+ * endpoint would conclude "no required checks" and wave everything through.
+ *
+ * Any parse or shape surprise yields [] — the caller then behaves exactly as
+ * it did before this function existed.
+ */
+export function _required_contexts_from_rules(json: string): string[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(json);
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed)) return [];
+    const out: string[] = [];
+    for (const rule of parsed) {
+        const r = rule as { type?: unknown; parameters?: { required_status_checks?: unknown } };
+        if (r.type !== 'required_status_checks') continue;
+        const checks = r.parameters?.required_status_checks;
+        if (!Array.isArray(checks)) continue;
+        for (const c of checks) {
+            const ctx = (c as { context?: unknown }).context;
+            if (typeof ctx === 'string' && ctx !== '') out.push(ctx);
+        }
+    }
+    return out;
+}
+
+export type NoChecksAction = 'retry' | 'accept' | 'die';
+
+/**
+ * What to do when `gh pr checks` reports no checks at all.
+ *
+ * The old code had one answer — accept — for two situations it could not tell
+ * apart: a repo that configures no required checks (nothing will ever arrive,
+ * accepting is correct) and a repo whose checks have simply not been
+ * dispatched yet (accepting merges, tags and publishes unvalidated).
+ *
+ * The branch's own protection rules separate them. Required contexts declared
+ * ⇒ something IS expected, so absence means not-yet, and the answer is to wait
+ * and finally to refuse. None declared ⇒ the pre-existing tolerance stands.
+ */
+export function _no_checks_action(
+    required: readonly string[],
+    round: number,
+    maxRounds: number = _NO_CHECKS_ROUNDS,
+): NoChecksAction {
+    if (required.length === 0) return 'accept';
+    return round < maxRounds ? 'retry' : 'die';
+}
+
+/**
+ * Watch PR checks and tolerate the 'no checks' case ONLY where it is tolerable.
  *
  * `gh pr checks --watch` exits 1 both on real failures and when no checks are
- * reported at all (no workflow triggered, no required checks configured in
- * branch protection). The latter must not block the release — we warn and
- * continue. Real failures still die.
+ * reported at all. Real failures still die.
+ *
+ * Measured 2026-08-06/07: during a critical GitHub Actions incident
+ * (15:22–02:04 UTC, webhook triggers throttled from 20:34) `pull_request`
+ * events were delivered 15–30 minutes late. The five-second grace period below
+ * expires long before that, so the old unconditional accept would have tagged
+ * `main` and published to npm without a single check having run. It did not
+ * only because `main` happened to be independently green.
+ *
+ * So the tolerance is now conditional on the branch declaring no required
+ * checks. Where it declares some, absence is treated as latency: re-watch, and
+ * refuse rather than release blind.
  *
  * A short grace period gives GitHub time to register workflow runs on a
  * freshly-pushed branch.
@@ -721,41 +792,76 @@ function watch_pr_checks(branch: string): void {
             // busy-wait stand-in for time.sleep(5) without an event-loop yield.
         }
     }
-    // The branch is passed explicitly — `gh` inferring the PR from HEAD
-    // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
-    // whole release died on "no pull requests found for branch main".
-    const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
-        check: false,
-        capture: true,
-    });
-    const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
-    const returncode = proc.returncode;
-    if (returncode === 0) {
+    // Rounds exist only for the no-checks-yet case below; every other outcome
+    // returns or dies on the first pass, exactly as before.
+    for (let round = 0; ; round++) {
+        // The branch is passed explicitly — `gh` inferring the PR from HEAD
+        // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
+        // whole release died on "no pull requests found for branch main".
+        const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
+            check: false,
+            capture: true,
+        });
+        const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
+        const returncode = proc.returncode;
+        if (returncode === 0) {
+            if (output) {
+                process.stdout.write(output + '\n');
+            }
+            return;
+        }
+        if (output.toLowerCase().includes('no checks reported')) {
+            const rules = run(
+                ['gh', 'api', `repos/{owner}/{repo}/rules/branches/${MAIN_BRANCH}`],
+                { check: false, capture: true },
+            );
+            const required = _required_contexts_from_rules(rules.stdout ?? '');
+            const action = _no_checks_action(required, round, _NO_CHECKS_ROUNDS);
+
+            if (action === 'accept') {
+                process.stdout.write(`⚠️  ${output}\n`);
+                process.stdout.write(
+                    '   Continuing without check validation — configure required ' +
+                        'checks in branch protection to enforce this gate.\n',
+                );
+                return;
+            }
+            if (action === 'retry') {
+                process.stdout.write(
+                    `⏳  no checks reported yet, but ${MAIN_BRANCH} requires ` +
+                        `${String(required.length)} (${required.join(', ')}) — ` +
+                        `waiting (${String(round + 1)}/${String(_NO_CHECKS_ROUNDS)})\n`,
+                );
+                if (_exec_override === null) {
+                    const until = Date.now() + _NO_CHECKS_DELAY_MS;
+                    while (Date.now() < until) {
+                        // blocking wait, same shape as the grace period above
+                    }
+                }
+                continue;
+            }
+            die(
+                `no checks reported for ${branch} after ` +
+                    `${String(_NO_CHECKS_ROUNDS)} rounds, but ${MAIN_BRANCH} requires ` +
+                    `${required.join(', ')}. Refusing to merge, tag and publish ` +
+                    'unvalidated — GitHub may be delaying event delivery (check ' +
+                    'githubstatus.com). Re-run with `task release -- --resume --yes` ' +
+                    'once the checks appear.',
+            );
+        }
         if (output) {
-            process.stdout.write(output + '\n');
+            process.stderr.write(output + '\n');
         }
-        return;
-    }
-    if (output.toLowerCase().includes('no checks reported')) {
-        process.stdout.write(`⚠️  ${output}\n`);
-        process.stdout.write(
-            '   Continuing without check validation — configure required ' +
-                'checks in branch protection to enforce this gate.\n',
-        );
-        return;
-    }
-    if (output) {
-        process.stderr.write(output + '\n');
-    }
-    const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
-        check: false,
-        capture: true,
-    });
-    const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
-    if (report) {
-        process.stderr.write(report + '\n');
+        const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
+            check: false,
+            capture: true,
+        });
+        const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
+        if (report) {
+            process.stderr.write(report + '\n');
+        }
+        die(`PR checks failed (exit ${returncode})`);
     }
-    die(`PR checks failed (exit ${returncode})`);
 }
 
 /**
@@ -767,11 +873,48 @@ function watch_pr_checks(branch: string): void {
  * 2026-08-03, 9.15.0). Same-branch commits are never ours to drop, so the
  * recovery is merge-and-retry, never force-push.
  */
+/**
+ * True when git rejected the push because the remote ref moved ahead — the
+ * ONLY failure the merge-and-retry recovery below can repair.
+ *
+ * git's wording for this is stable across versions: the hint is `fetch first`
+ * / `Updates were rejected`, and the ref line carries `[rejected]` with
+ * `non-fast-forward` or `fetch first`.
+ */
+export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
+    const text = `${stderr}\n${stdout}`;
+    return (
+        /\[rejected\]/i.test(text) &&
+        /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text)
+    );
+}
+
 function push_release_branch(branch: string): void {
-    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false });
+    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false, capture: true });
     if (first.returncode === 0) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
         return;
     }
+
+    // A push can fail for many reasons — a pre-push hook refusing the commit,
+    // no credentials, a protected branch. Only ONE of them is repaired by
+    // fetch+merge+retry, and the recovery's first step (`git fetch <branch>`)
+    // exits 128 for a branch that was never pushed. Taking that path
+    // unconditionally replaced every real error with
+    // `couldn't find remote ref <branch>` — measured 2026-08-06 on 9.26.0,
+    // where a pre-push gate rejection surfaced as a git-fetch crash and cost
+    // an hour of diagnosis pointed at the wrong layer.
+    if (!_is_non_fast_forward(first.stderr, first.stdout)) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        die(
+            `push of ${branch} failed (exit ${first.returncode}) and the remote ref did not move — ` +
+                'this is not the fetch-and-retry case. The push output above is the real error ' +
+                '(a pre-push gate, credentials, or branch protection); fix that and re-run.',
+        );
+    }
+
     process.stdout.write(`↻  ${REMOTE}/${branch} moved — integrating and retrying push\n`);
     run(['git', 'fetch', REMOTE, branch]);
     run(['git', 'merge', '--no-edit', `${REMOTE}/${branch}`]);