@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/session_memory_index.ts

@@ -20,12 +20,25 @@
  * deterministic (real tokenizer, reported by `session_index_cost()`); the
  * hit-rate arm needs a live paired run and has NOT been executed — so the
  * default is off, per the roadmap's "off unless proven".
+ *
+ * loss_class: recoverable-lossy
+ * loss_recovery: agents/memory/ — this module renders the block and applies
+ * `capRows`, so it carries the same class as the cap it applies. Each dropped
+ * row names a curated entry that remains on disk and is fetchable by id.
  */
 
-import { CURATED_TYPES, retrieve_v1 } from './memory_lookup.js';
+import { CURATED_TYPES, MEMORY_ROOT, retrieve_v1 } from './memory_lookup.js';
 import { load_agent_settings } from './_lib/agent_settings.js';
+import {
+    capRows,
+    orderRows,
+    SESSION_INDEX_ROW_CAP,
+    verifyMemoryRoot,
+    type TrustGrant,
+    type TrustVerdict,
+} from './_lib/session_index_trust.js';
 
-export const SESSION_INDEX_ROW_CAP = 30;
+export { SESSION_INDEX_ROW_CAP };
 
 interface IndexRow {
     id: string;
@@ -54,21 +67,72 @@ export function session_index_enabled(root: string): boolean {
  * Expects the caller to have chdir'd to the workspace root — memory roots
  * are cwd-relative, same contract as the MCP tool handlers.
  */
+/**
+ * How many entries retrieval is asked for before the declared order picks.
+ *
+ * R2 finding 2: asking retrieval for the CAP made P4 decorative. Every curated
+ * hit scores an identical 0.1 with an empty key set, so `retrieve` sliced the
+ * first 30 in STORE order at `memory_lookup.ts:995` and `orderRows` then sorted
+ * a set the cap had already chosen. Measured by the reviewer: a 40-entry corpus
+ * with the 5 cheapest last emitted zero cheap rows.
+ *
+ * The number must therefore exceed any realistic curated corpus, not merely the
+ * cap. 500 is a STATED DEFAULT, not a measured optimum — the cost of asking for
+ * more than exists is bounded by what exists, since `detail: 'index'` returns a
+ * row rather than a body. Its falsifier is recorded in the roadmap: a corpus
+ * larger than this bound makes store order decide again, silently.
+ */
+export const SESSION_INDEX_RETRIEVAL_LIMIT = 500;
+
 export function session_index_rows(cap: number = SESSION_INDEX_ROW_CAP): IndexRow[] {
-    const envelope = retrieve_v1([...CURATED_TYPES], [], cap, { detail: 'index' });
+    // Retrieval is asked for far more than the cap, so the declared order below
+    // is what chooses which rows survive truncation. P4 and P6 are one
+    // decision: retrieve wide, order, THEN cap — and never the reverse.
+    const envelope = retrieve_v1([...CURATED_TYPES], [], SESSION_INDEX_RETRIEVAL_LIMIT, { detail: 'index' });
     const entries = (envelope['entries'] as Array<Record<string, unknown>>) ?? [];
-    return entries.slice(0, cap).map((e) => ({
+    const rows: IndexRow[] = entries.map((e) => ({
         id: String(e['id'] ?? ''),
         title: String(e['title'] ?? ''),
         tokens_estimate: Number(e['tokens_estimate'] ?? 0),
     }));
+    return capRows(orderRows(rows), cap);
 }
 
 /**
- * Render the injectable block, or `null` when the corpus is empty (no
- * block beats an empty scaffold).
+ * The trust gate, separated from the render so a caller can log WHY nothing
+ * was injected. `null` from {@link build_session_index_block} is ambiguous by
+ * construction — empty corpus and refused root look identical — and the
+ * distinction is the point of the contract, so it is available here.
+ *
+ * The workspace root is REQUIRED. `MEMORY_ROOT` is relative, so without a root
+ * to resolve it against there is nothing to check identity or containment
+ * against, and a default would be a bypass wearing a convenience.
  */
-export function build_session_index_block(cap: number = SESSION_INDEX_ROW_CAP): string | null {
+export function session_index_trust(workspaceRoot: string, now?: Date): TrustVerdict {
+    // `exactOptionalPropertyTypes` refuses `now: undefined` on an optional
+    // field, so the key is omitted rather than passed as undefined.
+    return verifyMemoryRoot({
+        workspaceRoot,
+        relativeMemoryRoot: MEMORY_ROOT,
+        ...(now === undefined ? {} : { now }),
+    });
+}
+
+/**
+ * RENDER a block from whatever `MEMORY_ROOT` currently resolves to. Checks
+ * nothing, serves nothing.
+ *
+ * Split out on R2 findings 6 and 7. The trust check used to be an OPTIONAL
+ * parameter, which made the serving path opt-in — and `session_index_cost()`
+ * omitted it, so the one function whose name suggests it only measures was also
+ * the one that could render unchecked. Now the two operations have two names:
+ * this one renders (for cost measurement and for the unit seam that injects an
+ * absolute fixture root via `_setMemoryRoot`, which by construction sits
+ * outside any workspace), and {@link serve_session_index_block} is the only way
+ * to obtain a block for INJECTION — it takes a granted verdict, so there is no
+ * unchecked serving path to forget.
+ */
+export function render_session_index_block(cap: number = SESSION_INDEX_ROW_CAP): string | null {
     const rows = session_index_rows(cap);
     if (rows.length === 0) return null;
     const lines = [
@@ -81,13 +145,27 @@ export function build_session_index_block(cap: number = SESSION_INDEX_ROW_CAP):
     return lines.join('\n');
 }
 
+/**
+ * The only path to a block that will be INJECTED.
+ *
+ * Takes a granted verdict rather than a root, so the check happens once, at the
+ * caller, and cannot be skipped here — R2 finding 7 was that the hook and the
+ * builder each computed it, for a diagnostic the dispatcher does not forward.
+ * The type is `TrustGrant`, not `TrustVerdict`: a refusal cannot be passed in,
+ * so "did you check?" is answered by the signature instead of by a convention.
+ */
+export function serve_session_index_block(_grant: TrustGrant, cap: number = SESSION_INDEX_ROW_CAP): string | null {
+    return render_session_index_block(cap);
+}
+
 /**
  * Deterministic fixed cost of the block in real tokens (cl100k_base) —
  * the measurable arm of the roadmap's ship-criterion. Lazy-loads the
  * tokenizer so the enabled=off fast path never pays it.
  */
 export async function session_index_cost(cap: number = SESSION_INDEX_ROW_CAP): Promise<number> {
-    const block = build_session_index_block(cap);
+    // Renders rather than serves: this measures a cost, it injects nothing.
+    const block = render_session_index_block(cap);
     if (block === null) return 0;
     const { gpt_tokens } = await import('./_lib/token_count.js');
     return gpt_tokens(block).tokens;

package/src/scripts/sync_agent_settings.ts

@@ -441,11 +441,201 @@ function loadTemplate(p: string, profileValues: Record<string, string>): string
   return renderTemplate(fs.readFileSync(p, 'utf-8'), profileValues);
 }
 
-function loadUser(p: string): Record<string, unknown> {
-  if (!isFile(p)) {
-    return {};
+export interface DuplicateRepair {
+  /** The document with every safely-collapsible duplicate run reduced to one. */
+  text: string;
+  /** Keys that were collapsed, in first-seen order. */
+  collapsed: string[];
+  /** Duplicated keys this pass refuses to touch, with the reason. */
+  unsafe: string[];
+}
+
+/**
+ * Collapse duplicate TOP-LEVEL inline-scalar keys, keeping the last value.
+ *
+ * A strict YAML parser rejects a duplicate mapping key outright, so one such
+ * pair takes the whole file — and with it `task sync`, `task release-prepare`
+ * and every release — out of service with "Map keys must be unique". The
+ * duplicates in the wild were written by `mergeIntoTemplate`, whose flat
+ * `a.b: value` append was not idempotent before this change: each wizard save
+ * re-appended the entire "Wizard-added keys" block. That writer is fixed, but
+ * every file it already corrupted stays unreadable until something repairs
+ * it, and a release is the worst moment to discover that.
+ *
+ * Last-wins is value-neutral, not a guess: a lenient reader already resolved
+ * such a run that way, so collapsing changes what the file PARSES as in no
+ * way — it only changes whether it parses at all.
+ *
+ * Deliberately narrow, and the narrowness is what makes last-wins safe. A key
+ * is collapsible only when EVERY occurrence in the run is ONE-LINE-ONLY — its
+ * value sits on the key's own line and it owns no continuation lines at all.
+ * Anything else is reported in `unsafe` and left alone, because dropping the
+ * loser of a multi-line pair does not drop its body: the body survives, stops
+ * being that key's value, and attaches to whatever line precedes it. That
+ * turns a parse error into silent data corruption, which is strictly worse.
+ *
+ * Refused for that reason: a block key with indented children, a block scalar
+ * (`|`, `>`), a flow collection opened on one line and closed on another, and
+ * an anchor / alias / tag / merge value, whose meaning depends on which
+ * occurrence a reader binds rather than only on the value.
+ *
+ * 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.
+ */
+export function collapseDuplicateFlatKeys(text: string): DuplicateRepair {
+  // Line endings are preserved: splitting on `\n` alone leaves a trailing
+  // `\r` on every CRLF line, which the key pattern then never matches — so a
+  // CRLF file reported zero duplicates and fell straight into the parse error
+  // this pass exists to prevent.
+  //
+  // The MAJORITY terminator, not "any CRLF present". A mostly-LF file with one
+  // stray CRLF line would otherwise be rewritten to CRLF throughout — a whole-
+  // file change nobody asked for, on a pass whose entire promise is that it
+  // touches only what it must. Matches `sync_yaml_rt.detectEol`.
+  const crlfCount = (text.match(/\r\n/g) ?? []).length;
+  const lfCount = (text.match(/(^|[^\r])\n/g) ?? []).length;
+  const eol = crlfCount > lfCount ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+
+  // A document separator anywhere means more than one document may be in play.
+  if (lines.some((l) => /^(---|\.\.\.)\s*$/.test(l))) {
+    return { text, collapsed: [], unsafe: [] };
+  }
+
+  // A mapping key ends at a colon FOLLOWED BY SPACE OR END OF LINE — YAML's
+  // own plain-scalar rule. Stopping at the first colon instead reads `a:b: 1`
+  // as the key `a`, so a file carrying both `a:b:` and `a:` saw two `a` heads
+  // and collapsed them: the `a:b` entry vanished and the result parsed
+  // cleanly, so nothing downstream could notice. `sync_yaml_rt`'s own
+  // tokeniser already had this right; the two disagreeing was the defect.
+  //
+  // The value is captured with `[\s\S]` rather than `.`, which does not match
+  // a lone `\r`. A line holding one (a value like `"x\ry"`) was not recognised
+  // as a head at all, so a duplicate of it stayed invisible and the parse
+  // error this pass exists to remove survived untouched.
+  const HEAD_RE = /^([A-Za-z_][A-Za-z0-9_.-]*)[ \t]*:(?=[ \t]|$)([\s\S]*)$/;
+
+  /** Top-level key lines, in order. */
+  const heads: { key: string; at: number; rest: string }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    // Top level only — an indented `a.b:` is somebody else's child key.
+    if (line.length !== line.trimStart().length) continue;
+    const m = HEAD_RE.exec(line);
+    if (m === null) continue;
+    heads.push({ key: m[1] as string, at: i, rest: (m[2] as string).trim() });
+  }
+
+  /**
+   * Why this key may NOT be collapsed, or null when it may.
+   *
+   * Collapsing is safe only for a key that occupies exactly its own line: its
+   * value is a plain inline scalar and nothing between here and the next
+   * top-level key belongs to it. Everything else keeps its real reason, so the
+   * refusal message names what actually blocked it rather than asserting
+   * "different children" over a null, an anchor or a block scalar.
+   */
+  const blocker = (h: { at: number; rest: string }, nextAt: number): string | null => {
+    const v = h.rest;
+    if (v === '' || v.startsWith('#')) return 'a block key or a null value';
+    if (/^[|>]/.test(v)) return 'a block scalar';
+    // An anchor, alias or tag ANYWHERE in the value, not merely at its start:
+    // `a: [&x 1]` fits on one line, and dropping it deletes an anchor that an
+    // alias on some other line binds to — turning a duplicate-key error into
+    // an unresolved-alias error. Token position only, so `a&b` in a plain
+    // scalar is left alone.
+    if (/(^|[\s[{,])[&*!]/.test(v)) return 'an anchor, alias or tag';
+    // A flow collection must open and close on this line.
+    const opens = (v.match(/[[{]/g) ?? []).length;
+    const closes = (v.match(/[\]}]/g) ?? []).length;
+    if (opens !== closes) return 'a flow collection spanning lines';
+    for (let i = h.at + 1; i < nextAt; i++) {
+      const line = lines[i];
+      if (line === undefined) continue;
+      if (line.trim() === '') continue;
+      if (line.trimStart().startsWith('#')) continue;
+      return 'a value spanning more than its own line';
+    }
+    return null;
+  };
+
+  const solo = new Set<number>();
+  const why = new Map<number, string>();
+  for (let n = 0; n < heads.length; n++) {
+    const h = heads[n] as { key: string; at: number; rest: string };
+    const nextAt = n + 1 < heads.length ? (heads[n + 1] as { at: number }).at : lines.length;
+    const reason = blocker(h, nextAt);
+    if (reason === null) solo.add(h.at);
+    else why.set(h.at, reason);
   }
-  const data = parseYaml(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+
+  const seen = new Map<string, number[]>();
+  for (const h of heads) {
+    const at = seen.get(h.key);
+    if (at === undefined) seen.set(h.key, [h.at]);
+    else at.push(h.at);
+  }
+
+  const collapsed: string[] = [];
+  const unsafe: string[] = [];
+  const drop = new Set<number>();
+  for (const [key, hits] of seen) {
+    if (hits.length < 2) continue;
+    if (!hits.every((i) => solo.has(i))) {
+      const reason = hits.map((i) => why.get(i)).find((r) => r !== undefined) ?? 'not a plain one-line value';
+      unsafe.push(`${key} — ${reason}`);
+      continue;
+    }
+    collapsed.push(key);
+    // Keep the LAST occurrence's value at the FIRST occurrence's position, so
+    // the surrounding comments stay attached to the line they document.
+    lines[hits[0] as number] = lines[hits[hits.length - 1] as number] as string;
+    for (let i = 1; i < hits.length; i++) drop.add(hits[i] as number);
+  }
+
+  // Duplicates this pass cannot even SEE, reported rather than skipped.
+  //
+  // `HEAD_RE` recognises the key shapes the repair understands. A key starting
+  // with a digit (`2fa.on`) or a quoted key (`"a:b"`) matches nothing, so a
+  // file duplicating one used to come back with zero collapses AND zero
+  // refusals — and then died on the strict parse with the same opaque "Map keys
+  // must be unique" the whole repair exists to remove, giving the operator no
+  // hint that their key was the part being skipped. Shipping a repair pass
+  // creates the expectation that it either fixes the file or says why it
+  // cannot; silence is neither.
+  //
+  // Detection only. These keys are never collapsed — the shapes are exactly the
+  // ones whose tokenisation this pass does not model, which is why it declines
+  // to rewrite them.
+  const loose = new Map<string, number>();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    if (line.length !== line.trimStart().length) continue;
+    if (HEAD_RE.test(line)) continue;
+    const m = /^("[^"]*"|'[^']*'|[^\s:#][^:]*?)[ \t]*:(?=[ \t]|$)/.exec(line);
+    if (m === null) continue;
+    const key = m[1] as string;
+    loose.set(key, (loose.get(key) ?? 0) + 1);
+  }
+  for (const [key, count] of loose) {
+    if (count < 2) continue;
+    unsafe.push(`${key} — a key shape this repair does not model (quoted, or not starting with a letter)`);
+  }
+
+  if (collapsed.length === 0) {
+    return { text, collapsed, unsafe };
+  }
+  const kept = lines.filter((_, i) => !drop.has(i));
+  return { text: kept.join(eol), collapsed, unsafe };
+}
+
+function loadUserText(raw: string): Record<string, unknown> {
+  const data = parseYaml(raw, { version: '1.1' });
   if (data === null || data === undefined) {
     return {};
   }
@@ -655,10 +845,61 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
   const templatePath = args.template;
   const profileDir = args.profile_dir;
 
+  // Repair BEFORE the first parse. A duplicate mapping key makes the whole
+  // file unreadable, so without this the run dies here and takes the release
+  // with it — see `collapseDuplicateFlatKeys` for why last-wins is safe.
+  const rawText = isFile(target) ? fs.readFileSync(target, 'utf-8') : '';
+  const repair = collapseDuplicateFlatKeys(rawText);
+  if (repair.unsafe.length > 0) {
+    // Each entry carries the reason that key was refused. A single blanket
+    // sentence used to claim "different children" for every refusal — over a
+    // null value, a block scalar or an anchor that has none — which sends the
+    // reader looking for children to merge that are not there.
+    process.stderr.write(
+      `error: ${target} has duplicate mapping keys this tool will not collapse:\n` +
+        repair.unsafe.map((u) => `  - ${u}\n`).join('') +
+        `Keeping one occurrence would change what the file means. Merge them by hand, then re-run.\n`,
+    );
+    return 2;
+  }
+  if (repair.collapsed.length > 0) {
+    // 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
+    // settings file with no trace. `--quiet` suppresses routine success
+    // chatter; "I modified your file" is not that.
+    //
+    // The tense follows the mode. `--check` and `--dry-run` never write, so
+    // announcing a completed collapse there describes a write that did not
+    // happen — and the pre-release probe runs `--dry-run`, which made that the
+    // FIRST thing an operator saw on every release with a corrupted file.
+    const writes = !args.check && !args.dry_run;
+    const verb = writes
+      ? `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;
+
   let profile: string;
   let templateBody: string;
   try {
-    const userData = loadUser(target);
+    const userData = loadUserText(sourceText);
     const personalRaw = userData['personal'];
     const personal =
       personalRaw !== null && typeof personalRaw === 'object' && !Array.isArray(personalRaw)
@@ -706,7 +947,12 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     throw err;
   }
 
-  const existingText = isFile(target) ? fs.readFileSync(target, 'utf-8') : '';
+  // The merge reads the REPAIRED text; every "did anything change" decision
+  // below compares against `rawText`, what is actually on disk. Comparing
+  // against the repaired text instead would report "already in sync" on a
+  // file whose collapse never reached disk — the repair would run on every
+  // invocation and fix nothing.
+  const existingText = sourceText;
 
   let newText: string;
   if (existingText) {
@@ -724,7 +970,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     newText = templateBody;
   }
 
-  if (newText === existingText) {
+  if (newText === rawText) {
     if (!args.quiet) {
       process.stdout.write(`✅  ${target}: already in sync (profile=${profile})\n`);
     }
@@ -732,14 +978,28 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
   }
 
   if (args.check) {
-    const diff = renderDiff(existingText, newText, String(target));
+    const diff = renderDiff(rawText, newText, String(target));
     process.stdout.write(diff);
-    process.stderr.write(`\n❌  ${target}: drift detected (profile=${profile})\n`);
+    // Name WHICH problem, because the two have different remedies and a CI job
+    // reading only "drift detected" cannot tell them apart. A repair-only diff
+    // means the file is corrupt, not out of step with the template; the
+    // discriminator is whether the merge changed anything beyond the collapse.
+    //
+    // Still exit 2 in both cases: the file needs a write either way, and a
+    // `--check` that returned 0 over a file the reader cannot parse would hide
+    // exactly the breakage this whole change exists to surface.
+    const repairOnly = repair.collapsed.length > 0 && newText === sourceText;
+    process.stderr.write(
+      repairOnly
+        ? `\n❌  ${target}: duplicate keys need collapsing — no template drift (profile=${profile})\n` +
+            `    Run \`sync_agent_settings\` without --check to apply the repair.\n`
+        : `\n❌  ${target}: drift detected (profile=${profile})\n`,
+    );
     return 2;
   }
 
   if (args.dry_run) {
-    const diff = renderDiff(existingText, newText, String(target));
+    const diff = renderDiff(rawText, newText, String(target));
     process.stdout.write(diff);
     if (!args.quiet) {
       process.stderr.write(`\n(dry-run) would update ${target} (profile=${profile})\n`);

package/src/server/io/yamlIO.ts

@@ -40,6 +40,25 @@ function formatScalar(value: unknown): string {
     return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
 }
 
+/**
+ * A NESTED mapping key, as both the presence probe and the insertion walk read
+ * one. Shared so the writer and its own existence-probe cannot drift apart —
+ * that drift is the shape this file has now hit four times.
+ *
+ * `-` is in the class because a dashed key is ordinary YAML (`first-name`,
+ * `dry-run`, `retry-count`) and `detectIndentWidth` already accepted one.
+ * While this pattern did not, `findScalarLine` could never find such a key:
+ * `mergeIntoTemplate` then wrote a bogus top-level `x.first-principles:` line
+ * beside the real nested one and the intended value was never written — a save
+ * that silently did nothing — and `upsertScalar` appended another child line on
+ * EVERY call, growing without bound until the file stopped parsing.
+ *
+ * `.` stays OUT, deliberately. A dotted key is the FLAT form, which
+ * `replaceFlatDottedKey` owns; letting this pattern match `a.b:` would make the
+ * nested probe claim a line that is one key literally named "a.b".
+ */
+const NESTED_KEY_RE = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:/;
+
 interface FlatEntry {
     path: string[];
     value: unknown;
@@ -68,6 +87,25 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     const key = dottedPath[dottedPath.length - 1];
 
     const lines = template.split('\n');
+    const at = findScalarLine(lines, sections, key);
+    if (at === -1) return template;
+    const width = detectIndentWidth(lines);
+    lines[at] = `${' '.repeat(width * sections.length)}${key}: ${formatScalar(value)}`;
+    return lines.join('\n');
+}
+
+/**
+ * Index of the line holding the scalar at `sections`/`key`, or -1.
+ *
+ * Split out of `replaceScalar` so that "is this path present?" is answerable
+ * WITHOUT writing. `mergeIntoTemplate` used to infer presence from
+ * `replaceScalar` returning a changed string, which conflates "absent" with
+ * "present and already equal to the value being written" — under that test a
+ * no-op write reads as a miss and the caller appends a duplicate mapping key.
+ * A presence question answered by a mutation's side effect is the shape to
+ * look for here; the file already carries two earlier rounds of it.
+ */
+function findScalarLine(lines: readonly string[], sections: readonly string[], key: string | undefined): number {
     // The document's own width, the same read `upsertScalar` performs.
     //
     // R2 round 5, finding 1, and it is the second half of round 4's finding 7.
@@ -84,9 +122,7 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     // A writer and its own existence-probe disagreeing about the format is the
     // shape to look for whenever one of a pair is taught something new.
     const width = detectIndentWidth(lines);
-    const targetIndent = ' '.repeat(width * sections.length);
     const currentPath: (string | null)[] = new Array<string | null>(sections.length).fill(null);
-    const formatted = formatScalar(value);
 
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -98,7 +134,7 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
         const level = indentLen / width;
         if (level > sections.length) continue;
 
-        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        const m = NESTED_KEY_RE.exec(stripped);
         if (!m) continue;
         const lineKey = m[1];
         if (lineKey === undefined) continue;
@@ -115,10 +151,9 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
         const parentsMatch = sections.every((s, idx) => currentPath[idx] === s);
         if (!parentsMatch) continue;
         if (lineKey !== key) continue;
-        lines[i] = `${targetIndent}${key}: ${formatted}`;
-        return lines.join('\n');
+        return i;
     }
-    return template;
+    return -1;
 }
 
 /**
@@ -182,11 +217,21 @@ export function detectIndentWidth(lines: readonly string[]): number {
  */
 export function upsertScalar(template: string, dottedPath: string[], value: unknown): string {
     if (dottedPath.length === 0) return template;
-    const replaced = replaceScalar(template, dottedPath, value);
-    if (replaced !== template) return replaced;
-
     const sections = dottedPath.slice(0, -1);
     const key = dottedPath[dottedPath.length - 1] as string;
+
+    // Presence is asked, never inferred from the write changing the text. The
+    // string compare that used to stand here read "key already holds this
+    // value" as "key absent" and fell through to the append below — so saving
+    // the wizard's council page twice WITHOUT changing a toggle wrote a second
+    // `api_on_quota:` into the same block, over two `{ok: true}` responses, and
+    // left `.ai-council.yml` rejected by a strict parser. Third instance of one
+    // shape in this file; `findScalarLine` exists to end it, and a fix that
+    // taught only `mergeIntoTemplate` would have left the live path here.
+    if (findScalarLine(template.split('\n'), sections, key) !== -1) {
+        return replaceScalar(template, dottedPath, value);
+    }
+
     const formatted = formatScalar(value);
     const lines = template.split('\n');
     // The document's OWN indent width, not an assumed two.
@@ -228,7 +273,7 @@ export function upsertScalar(template: string, dottedPath: string[], value: unkn
             if (line.trim() === '' || line.trim().startsWith('#')) continue;
             const indentLen = line.length - line.trimStart().length;
             if (indentLen !== indent.length) continue;
-            const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(line.trim());
+            const m = NESTED_KEY_RE.exec(line.trim());
             if (m !== null && m[1] === want) {
                 found = i;
                 break;
@@ -269,23 +314,88 @@ export function upsertScalar(template: string, dottedPath: string[], value: unkn
     return lines.join('\n');
 }
 
+/**
+ * Rewrite an existing top-level `a.b.c: value` line — the FLAT form
+ * `mergeIntoTemplate` itself appends when a path has no template entry.
+ * Returns the template unchanged when no such line exists.
+ *
+ * `replaceScalar` cannot see this line: its key pattern is
+ * `[A-Za-z_][A-Za-z0-9_]*`, with no dot, so a path this module appended on
+ * one pass is invisible to the probe on the next and `mergeIntoTemplate`
+ * appends a SECOND copy. Two wizard saves therefore produce a file carrying
+ * duplicate mapping keys — a strict parser rejects it outright, which is what
+ * wedged `task release`: its `sync` step exits 2 with "Map keys must be
+ * unique" before the release does any git work.
+ *
+ * A pre-existing duplicate run is COLLAPSED, not merely updated: the first
+ * occurrence keeps its position and takes the new value, every later one is
+ * dropped. Collapsing is value-neutral — a lenient reader already resolved
+ * such a run last-wins — and it is the only way a file corrupted by the old
+ * behaviour becomes parseable again through the ordinary write path.
+ *
+ * Deliberately NOT folded into `replaceScalar`: `upsertScalar` calls that
+ * probe and documents the flat form as the WRONG shape for a nested key (a
+ * reader sees one key literally named "a.b"). Teaching the shared probe to
+ * match it would make `upsertScalar` write into that broken line instead of
+ * creating the nesting. The flat form is legitimate only here, where this
+ * function is the one that wrote it.
+ */
+function replaceFlatDottedKey(
+    template: string,
+    dottedPath: string[],
+    value: unknown,
+): { found: boolean; body: string } {
+    if (dottedPath.length < 2) return { found: false, body: template };
+    const flat = dottedPath.join('.');
+    const lines = template.split('\n');
+    const hits: number[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) continue;
+        // Top level only — an indented `a.b:` is somebody else's child key.
+        if (line.length !== line.trimStart().length) continue;
+        const m = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*:/.exec(line);
+        if (m === null || m[1] !== flat) continue;
+        hits.push(i);
+    }
+    if (hits.length === 0) return { found: false, body: template };
+    lines[hits[0] as number] = `${flat}: ${formatScalar(value)}`;
+    // Drop the later copies back-to-front so the earlier indices stay valid.
+    for (let i = hits.length - 1; i >= 1; i--) lines.splice(hits[i] as number, 1);
+    return { found: true, body: lines.join('\n') };
+}
+
 /**
  * Apply every leaf change from `newValues` to `templateBody`. Paths that
  * are not present in the template are appended at the end. Comments are
  * preserved for every key that already exists in the template.
+ *
+ * Idempotent: applying the same values twice yields the same document, so a
+ * second wizard save re-writes the flat block instead of duplicating it.
  */
 export function mergeIntoTemplate(templateBody: string, newValues: Record<string, unknown>): string {
     let body = templateBody;
     const appended: string[] = [];
     for (const entry of flatten(newValues)) {
-        const before = body;
-        body = replaceScalar(body, entry.path, entry.value);
-        if (body === before) {
-            // Path is not in the template — append a flat key=value at EOF.
-            // Form coverage is asserted by parity test, so this branch only
-            // fires on hand-edited templates.
-            appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
+        const sections = entry.path.slice(0, -1);
+        const leaf = entry.path[entry.path.length - 1];
+        // Presence is asked, never inferred from the write changing the text —
+        // see `findScalarLine`. Writing the value it already holds is a hit.
+        if (findScalarLine(body.split('\n'), sections, leaf) !== -1) {
+            body = replaceScalar(body, entry.path, entry.value);
+            continue;
+        }
+        // Not in the template's nested form. It may still be here as a flat
+        // dotted line this function appended on an earlier pass.
+        const flat = replaceFlatDottedKey(body, entry.path, entry.value);
+        if (flat.found) {
+            body = flat.body;
+            continue;
         }
+        // Genuinely absent — append a flat key=value at EOF. Form coverage is
+        // asserted by parity test, so this branch only fires on hand-edited
+        // templates.
+        appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
     }
     if (appended.length > 0) {
         if (!body.endsWith('\n')) body += '\n';