@event4u/agent-config 14.23.0 → 15.0.0

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';

package/src/server/schemas/settings.ts

@@ -173,7 +173,7 @@ export const settingsSchema = z.object({
     }),
     chat_history: z.object({
         enabled: z.boolean().default(true).describe(
-            'Persist a structured log of every chat turn to .agent-config/chat-history/ so /chat-history:show, :import, and :learn can replay sessions. Turn off if you never want chat transcripts on disk.',
+            'Persist a structured log of every chat turn to agents/runtime/.agent-chat-history (JSONL). Recording only — no command in this package replays a session from the file; it is a record on disk that a human or a later tool can read. Turn off if you never want chat transcripts on disk.',
         ),
         frequency: chatFreq.default('per_turn').describe(
             'How often the chat-history writer flushes to disk. per_turn = after every user / agent exchange (default, lowest data loss on crash). per_phase = at phase boundaries (cheaper I/O). per_tool = after every tool call (highest fidelity, noisiest log).',
@@ -247,7 +247,27 @@ export const settingsSchema = z.object({
         fidelity_mode: fidelityMode.default('strict').describe(
             'How strictly the agent must follow a user-provided prototype / mockup / design system (consumed by the design-fidelity rule). strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous.',
         ),
-    }).default({ fidelity_mode: 'strict' }),
+        approximation: z
+            .object({
+                enabled: z.boolean().default(false).describe(
+                    'Whether a value INSIDE the configured tolerance may be replaced by the project\'s own token without a per-value confirmation. Ships false. The distance from the artifact\'s value to the nearest project token is computed and REPORTED on every value row regardless of this switch — what it decides is whether the agent may act on it without asking. Turning it on for a whole install is a consumer-facing default flip and is owner-reserved (agents/roadmaps/stubs/road-to-frontend-power-default-flip.md); design.fidelity_mode: hard-floor overrides it to off.',
+                ),
+                tolerance: z
+                    .object({
+                        color: z.number().nullable().default(null).describe(
+                            'Colour distance below which a value may be reconciled, in OKLab ΔEOK. Ships null, and null means "preserve and report" rather than "reconcile freely". No number is set because none is supported: zero of seven design-to-code benchmarks in the evidence set score token conformance, and a number in a config file — even flagged unmeasured — shapes behavior and acquires the authority of a default. Not an RGB channel delta: RGB distance is not perceptually uniform.',
+                        ),
+                        length: z.number().nullable().default(null).describe(
+                            'Length distance below which a value may be reconciled, in absolute CSS pixels. Ships null, same reasoning as color. GitHub Primer\'s ±1px spacing widening is recorded as an externally observed candidate in src/scripts/_lib/design_tolerance.ts and is deliberately not the shipped value; max(1px, 2%) was rejected for growing more permissive at large dimensions with no evidence that this is wanted.',
+                        ),
+                    })
+                    .default({ color: null, length: null }),
+            })
+            .default({ enabled: false, tolerance: { color: null, length: null } }),
+    }).default({
+        fidelity_mode: 'strict',
+        approximation: { enabled: false, tolerance: { color: null, length: null } },
+    }),
     consistency: z.object({
         cross_source: crossSourceMode.default('on').describe(
             'Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.',
@@ -450,11 +470,11 @@ export const settingsSchema = z.object({
         }),
     }),
     continuity: z.object({
-        auto_record: z.enum(['on', 'off']).default('off').describe(
-            'Deterministic continuity-record writer at session end (road-to-continuity-writer-activation Phase 1). on = the session-eol concern writes the continuity_record capsule variant on Stop for a substantive session that has claimed a roadmap; every field is computed from on-disk state, with no model spend and no subprocess. off (default) = no automatic record — while session:recycle is still the normal path, a second producer on it before the parity evidence is in would be unverified.',
+        auto_record: z.enum(['on', 'off']).default('on').describe(
+            'Deterministic continuity-record writer at session end (road-to-continuity-writer-activation Phase 1). on (default since 2026-09-10) = the session-eol concern writes the continuity_record capsule variant on Stop for a substantive session that has claimed a roadmap; every field is computed from on-disk state, with no model spend and no subprocess. off = no automatic record, and only the explicit agent-config session:recycle writes one. The default flipped once the parity evidence landed, so the normal path carries an automatic writer rather than a remembered command; session:recycle is retained because the automatic writer skips a session that claimed no roadmap and omits the git-status anchors.',
         ),
         run_checkpoints: z.enum(['on', 'off']).default('on').describe(
-            'Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behaviour the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.',
+            'Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behavior the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.',
         ),
     }),
     memory: z.object({

package/src/shared/settingsSurface.ts

@@ -23,7 +23,13 @@ export type JsonLike =
     | { [key: string]: JsonLike };
 
 export interface SurfaceEntry {
-    type: string;
+    /**
+     * JSON-schema type. A STRING for an ordinary key, and an ARRAY for a
+     * nullable one (`["number", "null"]`) — which is what the generator has
+     * always produced for a `z.number().nullable()`, though this field was
+     * declared `string` until the first such key shipped.
+     */
+    type: string | string[];
     default?: JsonLike;
     enum?: Array<string | number>;
     description?: string;
@@ -129,7 +135,12 @@ export function computeSurfaceDelta(oldS: SettingsSurface, newS: SettingsSurface
             continue;
         }
         const o = oldS.entries[key] as SurfaceEntry;
-        if (o.type !== n.type) {
+        // `sameJson`, not `!==`: `type` is an array for a nullable key, and two
+        // structurally equal arrays are never `===`. Left as a strict compare
+        // it reported `type_changed` on EVERY version bump for every nullable
+        // key, forever — caught by the identical-surface test the moment the
+        // first one shipped (`design.approximation.tolerance.*`).
+        if (!sameJson(o.type, n.type)) {
             changes.push({ key, kind: 'type_changed', old: o, new: n });
         }
         if (!sameJson(o.default, n.default)) {

package/src/templates/compact-instructions.md

@@ -1,9 +1,14 @@
 # Compact-instructions template — lose less when you compact anyway
 
 Fallback lane of `road-to-token-economy-recycling` Phase 3.3. The recycle
-envelope (`agent-config session:recycle` + `/clear`) is the primary path —
-validated state, no summarizer. This template is for the user who compacts
-instead: Claude Code honours a `# Compact instructions` section in the
+envelope is the primary path — validated state, no summarizer — and since
+2026-09-10 it is written for you: the `session-eol` concern publishes the
+continuity record at session end by default (`continuity.auto_record`), so
+`/clear` resumes from it with no command to remember.
+`agent-config session:recycle` still exists as an explicit affordance for the
+cases the automatic writer does not cover (a session that claimed no roadmap, or
+a record that should carry the `git status` anchors). This template is for the
+user who compacts instead: Claude Code honours a `# Compact instructions` section in the
 project's `CLAUDE.md` when it summarizes (see the "Manage context
 proactively" section of the host's cost docs), and `/compact <instructions>`
 accepts the same guidance ad hoc.