@event4u/agent-config 15.0.0 → 16.0.0

package/src/scripts/report_held_object_arrivals.ts

@@ -0,0 +1,456 @@
+#!/usr/bin/env tsx
+/**
+ * How many distinct consumed-inbox rounds raise a held object's subject.
+ *
+ * WHY A REPORTER AND NOT A GATE
+ * -----------------------------
+ * The count belongs on the held object as a human-authored line, so that a
+ * number arrives with a reason attached. This script derives the figure and
+ * prints it; it writes nothing, and the absence of any write is the contract.
+ * A generated counter would be a number nobody chose, and the first time it
+ * disagreed with the prose beside it the prose would be believed.
+ *
+ * THE UNIT IS A ROUND, NEVER A FILE
+ * ---------------------------------
+ * One round can carry a dozen revisions of the same argument. Counting files
+ * turns a single arrival into twelve, which inflates exactly the figure this
+ * practice exists to make trustworthy. So the unit is a top-level entry of the
+ * consumed-inbox tree: a directory is one round however many files it holds,
+ * and a loose file dropped at the top level is a round of one. Both are one
+ * arrival of the subject, and the report prints the split so a reader can tell
+ * which kind they are looking at.
+ *
+ * NOT-READABLE IS NOT ZERO
+ * ------------------------
+ * The consumed-inbox tree is gitignored and machine-local. A clone, a fresh
+ * worktree and CI all see no tree at all. Reporting that as "0 arrivals" would
+ * publish the strongest possible claim from the weakest possible evidence, so
+ * an unreachable tree exits 0 saying no prior rounds are readable, and prints
+ * no count at all.
+ *
+ * WHAT THE NUMBER IS NOT
+ * ----------------------
+ * It is a floor on recurrence over one machine's store, under one pattern. A
+ * narrower pattern reads lower and a broader one sweeps in incidental
+ * mentions, which is why the pattern and its provenance are printed beside
+ * every figure. Two counters written on different days under different
+ * patterns are not comparable, and this script's whole purpose is to make the
+ * pattern explicit so the next one can be.
+ *
+ * Exit: 0 always, except a usage error (2). It gates on nothing.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Where a held object lives, relative to a repository root. */
+export const HELD_DIRS = ['agents/roadmaps/stubs', 'agents/roadmaps/later'] as const;
+
+/** The consumed-inbox tree, relative to a repository root. */
+export const INBOX_REL = 'agents/tmp.old';
+
+/** A held object may declare the pattern its counter was measured under. */
+const SUBJECT_MARKER = /<!--\s*arrival-subject:\s*(.+?)\s*-->/;
+
+/** Biggest file the scanner will read. Above it the file is skipped and counted as skipped. */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+
+export type TreeOrigin =
+    | 'flag'
+    | 'env'
+    | 'repo-root'
+    | 'main-checkout'
+    | 'project-dir'
+    | 'unreadable';
+
+export interface TreeResolution {
+    /** Absolute path to the tree, or null when nothing readable was found. */
+    dir: string | null;
+    /** Which candidate answered — printed so a figure carries its provenance. */
+    origin: TreeOrigin;
+    /** Every candidate considered, in order, with whether it resolved. */
+    tried: ReadonlyArray<{ origin: TreeOrigin; dir: string; readable: boolean }>;
+}
+
+function isReadableDir(dir: string): boolean {
+    try {
+        return fs.statSync(dir).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The main checkout behind a linked git worktree, or null.
+ *
+ * Read off the filesystem rather than by shelling out. In a linked worktree
+ * `.git` is a file whose one line points at `<main>/.git/worktrees/<name>`, so
+ * the main root is three levels above it. No subprocess, which matters because
+ * an inherited git directory has already broken gates in this tree once.
+ */
+export function mainCheckoutOf(root: string): string | null {
+    const dotGit = path.join(root, '.git');
+    let raw: string;
+    try {
+        if (!fs.statSync(dotGit).isFile()) return null;
+        raw = fs.readFileSync(dotGit, 'utf8');
+    } catch {
+        return null;
+    }
+    const m = /^gitdir:\s*(.+)$/m.exec(raw);
+    if (m === null) return null;
+    const gitdir = path.resolve(root, m[1]?.trim() ?? '');
+    // <main>/.git/worktrees/<name> -> <main>
+    const worktrees = path.dirname(gitdir);
+    if (path.basename(worktrees) !== 'worktrees') return null;
+    return path.dirname(path.dirname(worktrees));
+}
+
+/**
+ * Find the consumed-inbox tree, reporting which candidate answered.
+ *
+ * AN EXPLICIT TREE OVERRIDES; IT DOES NOT COMPETE
+ * -----------------------------------------------
+ * A tree named on the command line or in the environment is the answer, even
+ * when it is unreadable. Treating it as the first of several candidates would
+ * mean that naming a path that does not exist silently reads some other tree
+ * instead — and on every machine where the real tree exists, that makes the
+ * unreadable branch impossible to reach. The one behaviour this reporter most
+ * needs to be able to demonstrate would be the one behaviour nobody could
+ * exercise, which is how a branch ends up shipping with unknown sensitivity.
+ *
+ * The implicit chain runs only when neither was given. Its order is this root,
+ * then the main checkout behind it, because a worktree carries no tree of its
+ * own and the honest answers there are either the main checkout's tree or none
+ * at all. The host-provided project directory comes last: it is known to point
+ * at the parent checkout even from inside a worktree, which is useful and is
+ * also a host's opinion rather than a fact about this repository.
+ */
+export function resolveTree(opts: {
+    root: string;
+    flag?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+}): TreeResolution {
+    const env = opts.env ?? process.env;
+    const fromEnv = env['AGENT_CONFIG_INBOX_TREE'];
+    const explicit: { origin: TreeOrigin; dir: string } | null =
+        opts.flag !== undefined && opts.flag !== ''
+            ? { origin: 'flag', dir: path.resolve(opts.root, opts.flag) }
+            : fromEnv !== undefined && fromEnv !== ''
+              ? { origin: 'env', dir: path.resolve(opts.root, fromEnv) }
+              : null;
+    if (explicit !== null) {
+        const readable = isReadableDir(explicit.dir);
+        const tried = [{ ...explicit, readable }];
+        return readable
+            ? { dir: explicit.dir, origin: explicit.origin, tried }
+            : { dir: null, origin: 'unreadable', tried };
+    }
+
+    const candidates: Array<{ origin: TreeOrigin; dir: string }> = [];
+    candidates.push({ origin: 'repo-root', dir: path.join(opts.root, INBOX_REL) });
+    const main = mainCheckoutOf(opts.root);
+    if (main !== null && path.resolve(main) !== path.resolve(opts.root)) {
+        candidates.push({ origin: 'main-checkout', dir: path.join(main, INBOX_REL) });
+    }
+    const projectDir = env['CLAUDE_PROJECT_DIR'];
+    if (projectDir !== undefined && projectDir !== '') {
+        candidates.push({ origin: 'project-dir', dir: path.join(projectDir, INBOX_REL) });
+    }
+
+    const tried = candidates.map((c) => ({ ...c, readable: isReadableDir(c.dir) }));
+    const hit = tried.find((c) => c.readable);
+    return hit === undefined
+        ? { dir: null, origin: 'unreadable', tried }
+        : { dir: hit.dir, origin: hit.origin, tried };
+}
+
+export interface RoundMatch {
+    /** Top-level entry name — the round's codename. */
+    name: string;
+    /** `dir` = a round directory. `file` = a loose drop at the top level. */
+    kind: 'dir' | 'file';
+}
+
+export interface RoundCount {
+    matches: RoundMatch[];
+    /** Top-level entries examined — the denominator the count was taken over. */
+    examined: number;
+    /** Files the scanner could not read, so a low count is never silently a clean one. */
+    unreadable: number;
+    /** Files skipped for size. */
+    oversized: number;
+}
+
+function fileRaises(file: string, re: RegExp, tally: { unreadable: number; oversized: number }): boolean {
+    let size: number;
+    try {
+        const st = fs.statSync(file);
+        if (!st.isFile()) return false;
+        size = st.size;
+    } catch {
+        tally.unreadable += 1;
+        return false;
+    }
+    if (size > MAX_FILE_BYTES) {
+        tally.oversized += 1;
+        return false;
+    }
+    try {
+        return re.test(fs.readFileSync(file, 'utf8'));
+    } catch {
+        tally.unreadable += 1;
+        return false;
+    }
+}
+
+function dirRaises(dir: string, re: RegExp, tally: { unreadable: number; oversized: number }): boolean {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        tally.unreadable += 1;
+        return false;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isSymbolicLink()) continue;
+        if (e.isDirectory()) {
+            if (dirRaises(full, re, tally)) return true;
+        } else if (e.isFile()) {
+            if (fileRaises(full, re, tally)) return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Count distinct rounds whose contents match `re`.
+ *
+ * A round stops being examined the moment one of its files matches: the
+ * question is whether the round raised the subject, not how loudly.
+ */
+export function countRounds(tree: string, re: RegExp): RoundCount {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(tree, { withFileTypes: true });
+    } catch {
+        return { matches: [], examined: 0, unreadable: 1, oversized: 0 };
+    }
+    const tally = { unreadable: 0, oversized: 0 };
+    const matches: RoundMatch[] = [];
+    let examined = 0;
+    for (const e of entries.slice().sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.name.startsWith('.')) continue;
+        if (e.isSymbolicLink()) continue;
+        const full = path.join(tree, e.name);
+        if (e.isDirectory()) {
+            examined += 1;
+            if (dirRaises(full, re, tally)) matches.push({ name: e.name, kind: 'dir' });
+        } else if (e.isFile()) {
+            examined += 1;
+            if (fileRaises(full, re, tally)) matches.push({ name: e.name, kind: 'file' });
+        }
+    }
+    return { matches, examined, unreadable: tally.unreadable, oversized: tally.oversized };
+}
+
+export interface HeldObject {
+    /** Repo-relative path. */
+    rel: string;
+    /** File stem. */
+    slug: string;
+    /** Declared subject pattern, when the object carries one. */
+    declared: string | null;
+}
+
+/** Locate a held object by path or by slug. */
+export function findHeldObject(root: string, ref: string): HeldObject | null {
+    const direct = path.isAbsolute(ref) ? ref : path.join(root, ref);
+    const candidates = [direct];
+    const bare = path.basename(ref).replace(/\.md$/, '');
+    for (const d of HELD_DIRS) candidates.push(path.join(root, d, `${bare}.md`));
+    for (const c of candidates) {
+        let text: string;
+        try {
+            if (!fs.statSync(c).isFile()) continue;
+            text = fs.readFileSync(c, 'utf8');
+        } catch {
+            continue;
+        }
+        const m = SUBJECT_MARKER.exec(text);
+        return {
+            rel: path.relative(root, c),
+            slug: path.basename(c).replace(/\.md$/, ''),
+            declared: m === null ? null : (m[1] ?? null),
+        };
+    }
+    return null;
+}
+
+/**
+ * A pattern derived from a slug, used only when the object declares none.
+ *
+ * Deliberately weak, and printed as such. The recorded counters in this tree
+ * were taken under hand-written subject patterns, and a slug is a filename
+ * rather than a subject — so this reads as a hard floor and usually as zero.
+ * It exists so the tool answers for any object rather than refusing, and the
+ * output says which kind of pattern produced the figure.
+ */
+export function slugPattern(slug: string): string {
+    return slug.replace(/^road-to-/, '').replace(/-/g, '[-_ .]');
+}
+
+type PatternOrigin = 'flag' | 'declared' | 'slug';
+
+function buildPattern(
+    obj: HeldObject | null,
+    flag: string | undefined,
+): { source: string; origin: PatternOrigin } {
+    if (flag !== undefined && flag !== '') return { source: flag, origin: 'flag' };
+    if (obj !== null && obj.declared !== null) return { source: obj.declared, origin: 'declared' };
+    if (obj !== null) return { source: slugPattern(obj.slug), origin: 'slug' };
+    return { source: '', origin: 'slug' };
+}
+
+const PATTERN_NOTE: Record<PatternOrigin, string> = {
+    flag: 'given on the command line',
+    declared: 'declared on the object itself',
+    slug: 'derived from the slug — a hard floor, and usually the wrong question; pass --pattern',
+};
+
+const ORIGIN_NOTE: Record<TreeOrigin, string> = {
+    flag: '--tree',
+    env: 'AGENT_CONFIG_INBOX_TREE',
+    'repo-root': 'this repository root',
+    'main-checkout': "the main checkout behind this worktree",
+    'project-dir': 'CLAUDE_PROJECT_DIR',
+    unreadable: 'nothing',
+};
+
+export interface ReportResult {
+    exit: number;
+    text: string;
+}
+
+export function report(argv: readonly string[], root: string): ReportResult {
+    const out: string[] = [];
+    const arg = (name: string): string | undefined => {
+        const i = argv.indexOf(name);
+        return i === -1 ? undefined : argv[i + 1];
+    };
+    // Only these flags consume the token after them. The earlier form treated
+    // EVERY `--`-prefixed token as value-taking, which silently ate the held
+    // object ref after `--list`, and let the documented short form `-i` through
+    // as a positional because it carries one dash rather than two. Both
+    // spellings are in the help text, so both have to parse.
+    const VALUE_FLAGS = new Set(['--pattern', '--tree', '--root']);
+    const positional = argv.filter(
+        (a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(String(argv[i - 1] ?? '')),
+    );
+    const ref = positional[0];
+    if (ref === undefined) {
+        return { exit: 2, text: 'usage: report_held_object_arrivals <held-object> [--pattern RE] [--tree DIR] [--root DIR] [--ignore-case] [--list]\n' };
+    }
+
+    const obj = findHeldObject(root, ref);
+    if (obj === null) {
+        out.push(`held object not found: ${ref}`);
+        out.push(`  looked in: ${HELD_DIRS.join(', ')}`);
+        return { exit: 2, text: `${out.join('\n')}\n` };
+    }
+
+    const { source, origin: patternOrigin } = buildPattern(obj, arg('--pattern'));
+    // Case-sensitive by default, so the tool reproduces a plain `grep -rl`.
+    // Every recorded counter in this tree was taken that way, and a figure
+    // that quietly reads two rounds higher than the line it is checking is
+    // worse than no figure: it looks like drift in the store rather than a
+    // difference in the question asked.
+    const fold = argv.includes('--ignore-case') || argv.includes('-i');
+    let re: RegExp;
+    try {
+        re = new RegExp(source, fold ? 'i' : '');
+    } catch (e) {
+        return { exit: 2, text: `bad --pattern: ${String(e)}\n` };
+    }
+
+    const tree = resolveTree({ root, flag: arg('--tree') });
+
+    out.push(`object:  ${obj.rel}`);
+    out.push(`pattern: /${source}/${fold ? 'i' : ''}  (${PATTERN_NOTE[patternOrigin]})`);
+
+    if (tree.dir === null) {
+        out.push('tree:    unreadable');
+        for (const t of tree.tried) out.push(`  · ${t.origin}: ${t.dir} — absent`);
+        out.push('');
+        out.push('no prior rounds readable — the consumed-inbox tree is gitignored and');
+        out.push('machine-local, so this environment cannot see it. This is NOT a count of');
+        out.push('zero arrivals: no reading was taken. Point --tree at the tree, or run');
+        out.push('where it lives.');
+        return { exit: 0, text: `${out.join('\n')}\n` };
+    }
+
+    const counted = countRounds(tree.dir, re);
+    // A tree that STATS as a directory but cannot be LISTED reaches here with
+    // examined 0 and unreadable 1. Printing "0 distinct round(s) of 0 examined"
+    // would be the zero-versus-unreadable conflation this tool exists to avoid,
+    // one layer in from the absent-tree branch above: `isReadableDir` passed, so
+    // resolution succeeded and only enumeration failed. Same message, because it
+    // is the same fact — no reading was taken.
+    if (counted.examined === 0 && counted.unreadable > 0) {
+        out.push(`tree:    ${tree.dir}  (via ${ORIGIN_NOTE[tree.origin]}, but not listable)`);
+        out.push('');
+        out.push('no prior rounds readable — the tree resolved but could not be enumerated');
+        out.push('(permissions, or a race with something rewriting it). This is NOT a count');
+        out.push('of zero arrivals: no reading was taken.');
+        return { exit: 0, text: `${out.join('\n')}\n` };
+    }
+    const dirs = counted.matches.filter((m) => m.kind === 'dir').length;
+    const files = counted.matches.length - dirs;
+    out.push(`tree:    ${tree.dir}  (via ${ORIGIN_NOTE[tree.origin]})`);
+    out.push('');
+    out.push(
+        `arrivals: ${String(counted.matches.length)} distinct round(s) of ${String(counted.examined)} examined` +
+            ` — ${String(dirs)} round director(ies), ${String(files)} loose drop(s)`,
+    );
+    if (counted.unreadable > 0) out.push(`  note: ${String(counted.unreadable)} path(s) unreadable — the count is a floor`);
+    if (counted.oversized > 0) out.push(`  note: ${String(counted.oversized)} file(s) skipped for size`);
+    out.push('');
+    out.push('The figure is a floor on recurrence over one machine\'s store under one');
+    out.push('pattern. Write it onto the object by hand, with this pattern and this');
+    out.push('denominator beside it, so the next reader can tell a measured count from a');
+    out.push('remembered one.');
+    if (argv.includes('--list') || counted.matches.length <= 40) {
+        out.push('');
+        out.push('rounds:');
+        for (const m of counted.matches) out.push(`  · ${m.name}${m.kind === 'file' ? ' (loose drop)' : ''}`);
+    }
+    return { exit: 0, text: `${out.join('\n')}\n` };
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(
+            'usage: report_held_object_arrivals <held-object> [--pattern RE] [--tree DIR] [--root DIR] [--list]\n\n' +
+                '  <held-object>  a path, or a bare slug resolved under the held-object directories\n' +
+                '  --pattern RE   the subject pattern; overrides any the object declares\n' +
+                '  --tree DIR     the consumed-inbox tree; otherwise resolved and reported\n' +
+                '  --ignore-case  fold case; the default is a case-sensitive grep\n' +
+                '  --list         list every matched round even when there are many\n',
+        );
+        return 0;
+    }
+    const i = argv.indexOf('--root');
+    const root = i === -1 ? REPO_ROOT : (argv[i + 1] ?? REPO_ROOT);
+    const res = report(argv, root);
+    process.stdout.write(res.text);
+    return res.exit;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/sync_agent_settings.ts

@@ -24,13 +24,22 @@
  * Usage:
  *     sync_agent_settings                       # write (default)
  *     sync_agent_settings --dry-run             # show diff, no write
- *     sync_agent_settings --check               # exit 2 on drift (for CI)
+ *     sync_agent_settings --check               # exit 2 if a sync is needed (CI)
  *     sync_agent_settings --profile balanced    # use a specific profile
  *     sync_agent_settings --path path/to/.agent-settings.yml
  *
  * Exit codes:
  *     0 — already in sync, or changes applied (or --dry-run ran cleanly)
- *     2 — drift detected under --check, or invalid arguments / missing files
+ *     2 — under --check, synchronization requires intervention; also invalid
+ *         arguments, missing files, and a duplicate-key repair this tool
+ *         refuses to perform.
+ *
+ * `--check` has two diagnostic cases and its stderr line already separates
+ * them, because the remedies differ: template drift ("drift detected"), and a
+ * duplicate-key repair with no drift ("duplicate keys need collapsing"). Both
+ * exit 2 — the target needs a write either way, and a green `--check` over a
+ * file the strict reader cannot parse would hide the breakage. A caller that
+ * needs the distinction reads the message, not the code.
  *
  * No behaviour changes vs. the retired Python implementation — historical quirks preserved (consumers pin the exact behaviour).
  */
@@ -441,6 +450,52 @@ function loadTemplate(p: string, profileValues: Record<string, string>): string
   return renderTemplate(fs.readFileSync(p, 'utf-8'), profileValues);
 }
 
+/**
+ * The comment `mergeIntoTemplate` writes above its appended flat-key block.
+ *
+ * Duplicated here rather than imported: the writer holds it as a literal in
+ * `src/server/io/yamlIO.ts` and exports no constant, and that module belongs
+ * to the server tree this CLI does not otherwise depend on. Keep the two in
+ * step — a drift makes the sweep below silently stop matching.
+ */
+const WIZARD_BLOCK_HEADER = '# Wizard-added keys (no template entry)';
+
+/**
+ * Drop a wizard-block header the collapse emptied.
+ *
+ * The non-idempotent writer appended the header AND its keys on every save, so
+ * a collapse that removes the later block's key lines leaves that block's
+ * header behind with nothing under it — and the next append puts a fresh
+ * header below the orphan, one more per save. A header names the keys beneath
+ * it; with none beneath it, it names nothing and misleads the next reader.
+ *
+ * A header counts as emptied only when no key line stands between it and the
+ * next header or EOF. Blanks and further comments do not count: a user comment
+ * written between the header and its first key is part of the block, not a
+ * replacement for it.
+ */
+function dropOrphanedWizardHeaders(lines: readonly string[]): string[] {
+  const drop = new Set<number>();
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]?.trim() !== WIZARD_BLOCK_HEADER) continue;
+    let hasKey = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l === undefined) continue;
+      if (l.trim() === WIZARD_BLOCK_HEADER) break;
+      if (l.trim() === '' || l.trimStart().startsWith('#')) continue;
+      hasKey = true;
+      break;
+    }
+    if (hasKey) continue;
+    drop.add(i);
+    // The writer emits the blank line above the header as part of the block,
+    // so removing the header alone widens the gap by one line per repair.
+    if (i > 0 && lines[i - 1]?.trim() === '') drop.add(i - 1);
+  }
+  return drop.size === 0 ? [...lines] : lines.filter((_, i) => !drop.has(i));
+}
+
 export interface DuplicateRepair {
   /** The document with every safely-collapsible duplicate run reduced to one. */
   text: string;
@@ -482,6 +537,9 @@ export interface DuplicateRepair {
  * A multi-document stream (`---` / `...`) is not repaired either. The reader
  * takes a single document and rejects such a file whatever this pass does, so
  * collapsing across a boundary could only merge two documents' keys into one.
+ *
+ * When — and only when — something did collapse, a wizard-block header the
+ * collapse emptied is removed with it; see `dropOrphanedWizardHeaders`.
  */
 export function collapseDuplicateFlatKeys(text: string): DuplicateRepair {
   // Line endings are preserved: splitting on `\n` alone leaves a trailing
@@ -630,10 +688,53 @@ export function collapseDuplicateFlatKeys(text: string): DuplicateRepair {
   if (collapsed.length === 0) {
     return { text, collapsed, unsafe };
   }
-  const kept = lines.filter((_, i) => !drop.has(i));
+  const kept = dropOrphanedWizardHeaders(lines.filter((_, i) => !drop.has(i)));
   return { text: kept.join(eol), collapsed, unsafe };
 }
 
+/**
+ * The parse error an input still carries once its duplicate keys are excused,
+ * or null when the duplicates were its only problem.
+ *
+ * `uniqueKeys: false` is what excuses them: the duplicate-key rejection is the
+ * single error the collapse has a mandate to remove, so anything the parser
+ * still raises is an error the collapse was never licensed to touch.
+ */
+function residualParseError(text: string): Error | null {
+  try {
+    parseYaml(text, { version: '1.1', uniqueKeys: false });
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err : new Error(String(err));
+  }
+}
+
+/**
+ * What the parser reliably exposes about a failure, as one indented block.
+ *
+ * Available on every `YAMLParseError` observed from this parser: `message`,
+ * whose first line already carries `at line L, column C` plus the detail, and
+ * `code`, a stable identifier. `linePos` is populated too, but only while
+ * `prettyErrors` stays on (the library's own condition), so it is printed when
+ * present and never relied on. Nothing here is asserted beyond the parser's
+ * own first message line, which is derived in the test rather than hardcoded —
+ * pinning a format this module does not own would make a safety test fail on a
+ * dependency's wording change.
+ */
+function formatParserDetail(err: Error): string {
+  const first = err.message.split('\n')[0] ?? err.message;
+  const parts: string[] = [`    ${first}`];
+  const code = (err as { code?: unknown }).code;
+  const linePos = (err as { linePos?: { line: number; col: number }[] }).linePos;
+  const at = linePos?.[0];
+  if (typeof code === 'string' && at !== undefined) {
+    parts.push(`    (${code} at line ${at.line}, column ${at.col})`);
+  } else if (typeof code === 'string') {
+    parts.push(`    (${code})`);
+  }
+  return parts.join('\n') + '\n';
+}
+
 function loadUserText(raw: string): Record<string, unknown> {
   const data = parseYaml(raw, { version: '1.1' });
   if (data === null || data === undefined) {
@@ -863,6 +964,42 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     return 2;
   }
   if (repair.collapsed.length > 0) {
+    // Refuse before anything else in this branch, including the notice below:
+    // in write mode that notice is past tense ("collapsed …"), so announcing
+    // it and then refusing describes a write that never happened.
+    //
+    // The collapse's safety rests on preserving the original's last-wins
+    // reading, and a document that is invalid for some FURTHER reason has no
+    // reading to preserve — the pass can then emit valid YAML carrying
+    // structure nobody authored, which every downstream check accepts. A
+    // stderr warning (what this branch used to do) is a weak control against a
+    // silent outcome; a refusal is loud and the operator can still recover.
+    // AI council, 2026-09-11, 2 of 2 seats, converged — including a rejection
+    // of any `--repair-anyway` escape: an operator who understands the file
+    // well enough to use it understands it well enough to fix the error first,
+    // and "read the diff" is not a trustworthy oracle for YAML semantics.
+    //
+    // Exit 2, per the taxonomy in this file's header: 2 is "this tool cannot
+    // proceed with this input", which is also what the sibling refusal above
+    // (duplicates it will not collapse) returns. 1 is spoken for — it is the
+    // mirrored `install.fail` exit and means a broken install asset.
+    //
+    // Nothing durable precedes this point: the only write in `main` is the
+    // single `writeFileSync` at the end, there is no temporary file and no
+    // rename, so the refusal leaves the target byte-for-byte unchanged.
+    const residual = residualParseError(rawText);
+    if (residual !== null) {
+      process.stderr.write(
+        `❌  ${target}: refusing the automatic duplicate repair — the file has ` +
+          `another YAML error besides its duplicate keys.\n` +
+          formatParserDetail(residual) +
+          `    Collapsing changes only WHETHER a file parses, never what it parses as, ` +
+          `and that promise is empty over a document with no valid reading.\n` +
+          `    Fix the syntax error by hand, then re-run to apply the duplicate repair.\n`,
+      );
+      return 2;
+    }
+
     // NOT gated on --quiet, and not on stdout. Both callers that matter run
     // quiet — the release's `sync-agent-settings` step and the pre-release
     // probe — so gating this would let a release rewrite the operator's own
@@ -878,21 +1015,6 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
       ? `collapsed ${repair.collapsed.length} duplicate key(s), last value kept`
       : `would collapse ${repair.collapsed.length} duplicate key(s), keeping the last value (no write in this mode)`;
     process.stderr.write(`🔧  ${target}: ${verb} — ${repair.collapsed.join(', ')}\n`);
-
-    // The collapse promises to change only WHETHER the file parses, never what
-    // it parses as — and that promise is only meaningful over an input that had
-    // a reading to preserve. If the original was unparseable for some further
-    // reason (an unterminated quote, say), the repaired file may parse to
-    // structure no human wrote, and the next `git diff` shows keys nobody
-    // added. Cheap to say, and the operator cannot recover it from the output.
-    try {
-      parseYaml(rawText, { version: '1.1', uniqueKeys: false });
-    } catch {
-      process.stderr.write(
-        `⚠️   ${target}: the original had a syntax error beyond the duplicate keys, so the ` +
-          `result may differ in structure, not only in duplicates — read the diff before trusting it.\n`,
-      );
-    }
   }
   const sourceText = repair.text;