@event4u/agent-config 14.2.0 → 14.4.0

package/src/scripts/session_register_hook.ts

@@ -121,6 +121,89 @@ export function roadmap_claim_rel(session_id: string | null | undefined): string
     return norm;
 }
 
+/** Claim directory name, beside the session register in the git common dir. */
+export const CLAIM_DIRNAME = 'agent-claims';
+
+/**
+ * Where a roadmap claim lives: the git COMMON dir, which every worktree shares.
+ *
+ * ## The defect this fixes, measured 2026-08-19
+ *
+ * The run contract had two halves that resolved DIFFERENT roots.
+ * `sessions_cli.cmd_claim` joined the relative path below against
+ * `process.cwd()` — the worktree the operator stands in. The stop-slot concern
+ * joined it against `envelope.workspace_root`, which the dispatcher sets from
+ * `--project-dir`, i.e. the host's `CLAUDE_PROJECT_DIR` — the parent checkout.
+ * In a worktree those are different trees, so the concern found no contract,
+ * took its `contract absent -> no-op` rung, and wrote NO event.
+ *
+ * That last part is why it went unnoticed for a release: the ledger built to
+ * make `run-continuation` auditable is empty exactly when it never ran, and
+ * empty is also what a healthy idle run looks like. The dispatch integration
+ * test could not see it either — it passes the same root to writer and reader,
+ * the one arrangement in which the two agree. Two independent symptoms pointed
+ * at it: `run-continuation.jsonl` never appeared, and `run:supervise` listed a
+ * session as `roadmap=-` minutes after that session had claimed.
+ *
+ * ## Why the common dir, and not "make the hook resolve the worktree"
+ *
+ * A roadmap claim is repo-global BY INTENT — `sessions:claim` tells the
+ * operator it "becomes visible to other sessions", and the whole point is that
+ * a peer in another worktree sees it. `register_dir` already puts the session
+ * register in the common dir for exactly that reason, and the claim is the
+ * register's other half. The alternative — teaching every concern to distrust
+ * `--project-dir` — is a change to every concern rather than to one path.
+ *
+ * `null` when git cannot be read at all; the caller then falls back to the
+ * per-tree path, which is the pre-fix behaviour rather than a new failure.
+ */
+export function claim_dir(workspace_root: string): string | null {
+    const common = git_common_dir(workspace_root);
+    return common === null ? null : path.join(common, CLAIM_DIRNAME);
+}
+
+/**
+ * Absolute path this session's claim is WRITTEN to.
+ *
+ * Shared-dir when git resolves, per-tree otherwise. One function for both
+ * halves of the contract — the writer and the reader call this, so they cannot
+ * disagree about the tree again.
+ */
+export function claim_file(workspace_root: string, session_id: string | null | undefined): string {
+    const dir = claim_dir(workspace_root);
+    const rel = roadmap_claim_rel(session_id);
+    if (dir === null) return path.join(workspace_root, rel);
+    return path.join(dir, path.basename(rel));
+}
+
+/**
+ * Every path a claim may be READ from, newest convention first.
+ *
+ * The per-tree paths stay readable so a claim written before this change is
+ * not lost — measured at 17 such files in the main checkout on the day of the
+ * fix. A read-only fallback, never a write target: writing both would recreate
+ * the two-trees problem with extra steps.
+ */
+export function claim_read_paths(
+    workspace_root: string,
+    session_id: string | null | undefined,
+): string[] {
+    const rel = roadmap_claim_rel(session_id);
+    const dir = claim_dir(workspace_root);
+    const out: string[] = [];
+    if (dir !== null) {
+        out.push(path.join(dir, path.basename(rel)));
+        if (rel !== ROADMAP_CLAIM_REL) {
+            out.push(path.join(dir, path.basename(ROADMAP_CLAIM_REL)));
+        }
+    }
+    out.push(path.join(workspace_root, rel));
+    if (rel !== ROADMAP_CLAIM_REL) {
+        out.push(path.join(workspace_root, ROADMAP_CLAIM_REL));
+    }
+    return out;
+}
+
 /** The shape `sessions:claim` writes. `session_id` is absent on legacy files. */
 export interface RoadmapClaim {
     slug: string;
@@ -173,12 +256,23 @@ export function read_claimed_slug(
 ): string | null {
     const own = roadmap_claim_rel(session_id);
     if (own !== ROADMAP_CLAIM_REL) {
-        const mine = _read_claim_file(path.join(workspace_root, own));
-        if (mine !== null) {
-            return mine.slug;
+        // Per-session, shared dir first, then the pre-fix per-tree path. The
+        // ORDER carries the migration: a session that has re-claimed since the
+        // fix wins over its own stale per-tree file.
+        for (const p of claim_read_paths(workspace_root, session_id)) {
+            if (path.basename(p) === path.basename(ROADMAP_CLAIM_REL)) continue;
+            const mine = _read_claim_file(p);
+            if (mine !== null) return mine.slug;
         }
     }
-    const legacy = _read_claim_file(path.join(workspace_root, ROADMAP_CLAIM_REL));
+    // The legacy per-WORKTREE file, in the same two locations. Unchanged in
+    // meaning: it is a claim on the checkout, not on a session.
+    let legacy: RoadmapClaim | null = null;
+    for (const p of claim_read_paths(workspace_root, session_id)) {
+        if (path.basename(p) !== path.basename(ROADMAP_CLAIM_REL)) continue;
+        legacy = _read_claim_file(p);
+        if (legacy !== null) break;
+    }
     if (legacy === null) {
         return null;
     }
@@ -578,10 +672,16 @@ export function main(): number {
             // upgrade, unbounded. An id-less session owns that file by construction,
             // so its end is the honest moment to drop it. An identified session still
             // leaves it alone: it may be a peer's.
-            try {
-                fs.unlinkSync(path.join(root, roadmap_claim_rel(session_id)));
-            } catch {
-                /* absent or unwritable — a leftover claim expires with its record */
+            // Both locations: the shared dir a claim is written to now, and the
+            // per-tree path a pre-fix claim still sits at. Dropping only one
+            // would leave the other readable and reinstate the claim.
+            for (const p of claim_read_paths(root, session_id)) {
+                if (path.basename(p) !== path.basename(roadmap_claim_rel(session_id))) continue;
+                try {
+                    fs.unlinkSync(p);
+                } catch {
+                    /* absent or unwritable — a leftover claim expires with its record */
+                }
             }
             return 0;
         }

package/src/scripts/sessions_cli.ts

@@ -52,7 +52,7 @@ import {
     ttl_is_measured,
     ttl_seconds_for,
 } from './_lib/session_register.js';
-import { claim_is_stale, roadmap_claim_rel } from './session_register_hook.js';
+import { claim_file, claim_is_stale, claim_read_paths } from './session_register_hook.js';
 
 function usage(): number {
     process.stderr.write(
@@ -401,17 +401,29 @@ export function claim_conflicts(
 
 function cmd_claim(argv: string[], root: string): number {
     const sid = env_session_id();
-    const target = path.join(root, roadmap_claim_rel(sid));
+    // The claim lives in the git COMMON dir, so the writer here and the stop-slot
+    // reader agree on one tree even when they start from different ones. Before
+    // this, the CLI joined against `process.cwd()` (the operator's worktree) and
+    // the hook against `--project-dir` (the parent checkout) — in a worktree,
+    // two different files, and `run-continuation` silently never engaged. See
+    // `claim_dir` in session_register_hook.ts for the full account.
+    const target = claim_file(root, sid);
     if (argv.includes('--release')) {
         // Release only what this session could have written. An identified session
         // never writes the legacy file, so unlinking it would delete a PEER's claim
         // in a mixed-host checkout and leave that peer reporting nothing, with no
         // notice to either side (R2 finding 10). An unidentified session shares that
         // file by construction and releasing it is the only release available.
-        try {
-            fs.unlinkSync(target);
-        } catch {
-            /* nothing to release */
+        //
+        // Both locations — the shared dir and the pre-fix per-tree path — because
+        // a release that clears one and leaves the other readable does not release.
+        for (const p of claim_read_paths(root, sid)) {
+            if (path.basename(p) !== path.basename(target)) continue;
+            try {
+                fs.unlinkSync(p);
+            } catch {
+                /* nothing to release */
+            }
         }
         process.stdout.write(
             sid === null

package/src/scripts/telemetry_disclosure_hook.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Org-telemetry disclosure — `session_start` concern.
+ *
+ * `road-to-org-telemetry` Phase 3, step 2, and the compensating control
+ * ADR-233 § D5 accepts in exchange for the `org-pack` consent class.
+ *
+ * WHY IT IS NOT OPTIONAL. Every other consent in this suite is given by the
+ * person it binds: `jit-answer` is a question they answered, `gui` is a human
+ * at the settings editor, `manual` is their own hand-edit. `org-pack` is the
+ * one grant made by somebody else — a human org administrator deciding for
+ * every install the pack reaches. That is a legitimate consent only if the
+ * person whose usage is being described can see that it was given. Without
+ * this line, an install would report on a user who was never told, which is
+ * the shape "a public repository that phones home reads as spyware" names in
+ * the roadmap's Risk 3, regardless of how content-free the payload is.
+ *
+ * WHAT IT SAYS AND WHAT IT DOES NOT. The line names the fact (pseudonymous
+ * usage data is reported), the recipient (`org_id`, and the endpoint host so
+ * "to whom" is answerable rather than gestured at), and where to read the
+ * local records. It carries no salt, no user hash, and no full endpoint URL
+ * with credentials — see the redaction in `_endpointHost`.
+ *
+ * ONCE, NOT EVERY SESSION — and re-disclosed when the fact changes. The step
+ * asks for the line "at first session start", so the concern records what it
+ * disclosed in `agents/runtime/state/telemetry-disclosure.json` and stays
+ * silent afterwards. The recorded key is the (org_id, endpoint) pair rather
+ * than a bare flag: a new sink or a new org is a NEW disclosure, and a design
+ * that showed the line once and then silently followed the data somewhere
+ * else would be worse than one that never showed it. A state file that cannot
+ * be written is treated as "not yet disclosed", so the failure mode is a
+ * repeated line rather than a suppressed one.
+ *
+ * SILENT ON EVERY INACTIVE SHAPE. `read_remote_settings` is fail-closed on
+ * each axis, and this concern adds nothing to it: no settings file, no
+ * section, `enabled: false`, or any of `endpoint` / `org_id` / `salt` missing
+ * all mean `active === false`, and an inactive install prints nothing and
+ * writes nothing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { readHookStdin } from './hooks/hook_stdin.js';
+import { is_replay_mode } from './hooks/state_io.js';
+import { _resolveRoot, resolveSettingsPath } from './hooks/telemetry_usage_hook.js';
+import { read_remote_settings } from '../agent-src/templates/scripts/telemetry/settings.js';
+
+const EXIT_ALLOW = 0;
+
+/**
+ * Longest interpolated field the disclosure will print, per field.
+ *
+ * The per-concern injection budget is 1024 bytes and three settings-supplied
+ * values are interpolated into a fixed frame, one of them twice. Those values
+ * come from a settings file, so their length is an operator's choice rather
+ * than a bound this concern can assume — an over-budget line is dropped by the
+ * dispatcher, which would silently remove the disclosure. Truncating keeps the
+ * line and keeps it legible; the settings file remains the full record.
+ */
+export const MAX_FIELD_CHARS = 120;
+
+/** Clamp one interpolated field, marking the cut so it does not read as the value. */
+export function _clamp(value: string): string {
+    return value.length <= MAX_FIELD_CHARS ? value : `${value.slice(0, MAX_FIELD_CHARS - 1)}…`;
+}
+
+/** Where the "already disclosed" note lives, relative to the project root. */
+export const DISCLOSURE_STATE_REL = 'agents/runtime/state/telemetry-disclosure.json';
+
+export interface DisclosureFacts {
+    readonly org_id: string;
+    readonly endpoint: string;
+    readonly log_path: string;
+}
+
+/**
+ * Host of the configured endpoint, or the raw value when it does not parse.
+ *
+ * The full URL can legitimately carry a path token, so only the host is
+ * disclosed: it answers "to whom" without turning a disclosure line into a
+ * place a credential can appear.
+ */
+export function _endpointHost(endpoint: string): string {
+    try {
+        return new URL(endpoint).host || endpoint;
+    } catch {
+        return endpoint;
+    }
+}
+
+/** The identity of one disclosure — a change here is a new disclosure. */
+export function disclosureKey(facts: DisclosureFacts): string {
+    return `${facts.org_id}\u0000${facts.endpoint}`;
+}
+
+/**
+ * Has this exact (org, endpoint) pair already been disclosed here?
+ *
+ * Every unreadable shape answers `false`. Re-showing a line the user has seen
+ * costs one line; suppressing one they have not seen costs the property this
+ * concern exists to provide.
+ */
+export function alreadyDisclosed(root: string, facts: DisclosureFacts): boolean {
+    try {
+        const raw = fs.readFileSync(path.join(root, DISCLOSURE_STATE_REL), 'utf-8');
+        const parsed = JSON.parse(raw) as unknown;
+        if (parsed === null || typeof parsed !== 'object') {
+            return false;
+        }
+        return (parsed as Record<string, unknown>)['disclosed'] === disclosureKey(facts);
+    } catch {
+        return false;
+    }
+}
+
+/** Record the disclosure. A write failure is swallowed — see the header. */
+export function recordDisclosure(root: string, facts: DisclosureFacts, at: string): void {
+    try {
+        const p = path.join(root, DISCLOSURE_STATE_REL);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(
+            p,
+            `${JSON.stringify({ disclosed: disclosureKey(facts), at }, null, 2)}\n`,
+            'utf-8',
+        );
+    } catch {
+        // Intentionally silent: see the module header. An undisclosed state is
+        // recoverable (the line shows again); a blocked session start is not.
+    }
+}
+
+/** The disclosure line the user sees. One `<tag>`-wrapped block, no prose. */
+export function buildDisclosure(facts: DisclosureFacts): string {
+    const org = _clamp(facts.org_id);
+    const sink = _clamp(_endpointHost(facts.endpoint));
+    const log = _clamp(facts.log_path);
+    return [
+        '<telemetry-disclosure>',
+        `This install reports pseudonymous usage data to your organisation `
+        + `"${org}" (sink: ${sink}), enabled by an org administrator rather than by you.`,
+        `What is sent: which skill ran, the host, the package version, the discipline `
+        + `profile, and salted digests of your machine+login and session. No prompt `
+        + `text, file path, file content, or project name — the record type has no `
+        + `field able to hold them.`,
+        `The records are readable locally at ${log}. See SECURITY.md § Telemetry.`,
+        '</telemetry-disclosure>',
+    ].join('\n');
+}
+
+export function run(
+    stdin: string,
+    options: { now?: string; settingsFile?: string } = {},
+): number {
+    let envelope: Record<string, unknown> = {};
+    if (stdin.trim() !== '') {
+        try {
+            const parsed = JSON.parse(stdin) as unknown;
+            if (parsed !== null && typeof parsed === 'object') {
+                envelope = parsed as Record<string, unknown>;
+            }
+        } catch {
+            return EXIT_ALLOW; // never act on a malformed envelope
+        }
+    }
+    // Positively matched, never defaulted. An envelope carrying no `event`
+    // used to be treated as a session start on whatever slot invoked it, so a
+    // shape this concern cannot identify would still disclose and write state.
+    // Fail-open on identification is the wrong default for a concern that
+    // mutates a file.
+    if (envelope['event'] !== 'session_start') {
+        return EXIT_ALLOW;
+    }
+
+    // A replayed or benchmarked envelope must not consume the one-shot: it
+    // would write the state note into the target root and spend the real
+    // user's first disclosure on a run they never saw. Same guard, same
+    // reason, as the sibling that writes the records.
+    if (is_replay_mode()) {
+        return EXIT_ALLOW;
+    }
+
+    // One resolver for both concerns of this feature. Reading only the
+    // envelope root made the sibling silently inactive when a host reported a
+    // `cwd` inside a subdirectory — and here the asymmetry was worse than
+    // inactivity: the usage hook walked up and recorded while this one did
+    // not walk up and stayed silent, i.e. telemetry with the disclosure
+    // switched off, which is the single shape ADR-233 § D5 forbids.
+    const settingsFile = options.settingsFile ?? resolveSettingsPath(_resolveRoot(envelope as never));
+    // The state note belongs beside the settings file that decided the
+    // disclosure, not beside the session cwd: otherwise one project discloses
+    // once per subdirectory a session happens to start in.
+    const root = path.dirname(settingsFile);
+
+    let settings;
+    try {
+        settings = read_remote_settings(settingsFile);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!settings.active) {
+        return EXIT_ALLOW;
+    }
+
+    const facts: DisclosureFacts = {
+        org_id: settings.org_id,
+        endpoint: settings.endpoint,
+        log_path: settings.log_path,
+    };
+    if (alreadyDisclosed(root, facts)) {
+        return EXIT_ALLOW;
+    }
+
+    process.stdout.write(
+        `${JSON.stringify({
+            decision: 'allow',
+            reason: `telemetry-disclosure: org "${facts.org_id}"`,
+            context: buildDisclosure(facts),
+        })}\n`,
+    );
+    recordDisclosure(root, facts, options.now ?? new Date().toISOString());
+    return EXIT_ALLOW;
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    void args;
+    return run(readHookStdin());
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/server/io/yamlIO.ts

@@ -66,9 +66,25 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     if (dottedPath.length === 0) return template;
     const sections = dottedPath.slice(0, -1);
     const key = dottedPath[dottedPath.length - 1];
-    const targetIndent = '  '.repeat(sections.length);
 
     const lines = template.split('\n');
+    // 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.
+    // That round taught `upsertScalar` to WRITE at the detected width and left
+    // this function — the probe that answers "does this key already exist?" —
+    // at a hardcoded two, in three places: the emitted indent, the `% 2`
+    // alignment test and the `/ 2` level. On a 4-space file `indentLen` 4
+    // passes `% 2` and computes level 2 for a depth-1 key, so the key is never
+    // found. The wizard then writes a correctly-indented line on the first
+    // toggle and, on the second, cannot see it and appends a DUPLICATE mapping
+    // key in the same block — two POSTs, both `{ok: true}`, and a config the
+    // parser rejects with "Map keys must be unique".
+    //
+    // 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);
 
@@ -78,8 +94,8 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
         const stripped = line.trim();
         if (stripped === '' || stripped.startsWith('#')) continue;
         const indentLen = line.length - line.trimStart().length;
-        if (indentLen % 2 !== 0) continue;
-        const level = indentLen / 2;
+        if (indentLen % width !== 0) continue;
+        const level = indentLen / width;
         if (level > sections.length) continue;
 
         const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
@@ -105,6 +121,154 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     return template;
 }
 
+/**
+ * The indent width this document actually uses, or 2 when it has no nesting.
+ *
+ * The SMALLEST indent of any mapping line, not the first one seen. R2 round 6,
+ * finding 3: reading the first was wrong in two ways at once, and both were
+ * reachable on files this repository ships.
+ *
+ *   - The key pattern excluded `-`, so a dashed key (`first-principles:`, and
+ *     the shipped template has one) was skipped and the next, DEEPER line won:
+ *     a 2-space document read as 4.
+ *   - Even with the pattern fixed, "first" is not "representative" — a
+ *     document whose first indented line sits at depth 3 read as 6.
+ *
+ * Either way every `replaceScalar` probe then misses and `upsertScalar`
+ * appends a duplicate mapping key the parser rejects, over a `{ok: true}`.
+ * The minimum is the width by construction: nesting is a multiple of it, so
+ * the shallowest indented line IS one unit.
+ *
+ * Tabs are not YAML indentation and are ignored. A list item (`- x`) is not a
+ * mapping line and does not vote.
+ */
+export function detectIndentWidth(lines: readonly string[]): number {
+    let min = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('-')) continue;
+        if (line.startsWith('\t')) continue;
+        const indentLen = line.length - line.trimStart().length;
+        if (indentLen === 0) continue;
+        // Hyphens and dots are legal in a YAML key and appear in this repo's
+        // own templates; excluding them is what let a deeper line win.
+        if (!/^[A-Za-z_][\w.-]*\s*:/.test(trimmed)) continue;
+        if (min === 0 || indentLen < min) min = indentLen;
+    }
+    return min === 0 ? 2 : min;
+}
+
+/**
+ * Set the scalar at `dottedPath`, CREATING the nesting when it is absent.
+ *
+ * R2 round 2, finding 6. `replaceScalar` returns the template unchanged when
+ * the path cannot be located, and the wizard's `set` helper never appended —
+ * so on every pre-existing `.ai-council.yml` written before a key existed, the
+ * wizard's toggle for that key returned 200 and wrote nothing. The user flips
+ * a switch, the server reports success, and the file is untouched.
+ *
+ * `mergeIntoTemplate` is not the fix for a NESTED key: its fallback appends a
+ * flat `a.b: value` line, which a YAML reader sees as a top-level key literally
+ * named "a.b" — so `doc['fallback']` stays undefined and the toggle is still
+ * inert, now with a line in the file suggesting otherwise.
+ *
+ * Insertion point is the end of the deepest EXISTING ancestor block, so an
+ * existing `fallback:` section gains a key rather than a second `fallback:`
+ * being appended — a duplicate mapping key is a YAML error in strict parsers
+ * and a silent last-wins in lenient ones.
+ *
+ * Comments and unrelated keys are preserved: nothing is rewritten, only
+ * inserted.
+ */
+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;
+    const formatted = formatScalar(value);
+    const lines = template.split('\n');
+    // The document's OWN indent width, not an assumed two.
+    //
+    // R2 round 4, finding 7. Both the ancestor search and the emitted block
+    // hardcoded `'  '.repeat(depth)`, so on a 4-space file the depth-2 walk
+    // round 3 added matched nothing at depth 1, `matched` stayed 0, and the
+    // whole chain was appended at EOF — producing a SECOND `fallback:` mapping
+    // key beside the existing one. `wizard.ts` writes the result without
+    // re-parsing and reports `{ok: true}`, so the user gets a 200 over a file
+    // a strict parser now rejects and a lenient one reads last-wins.
+    const width = detectIndentWidth(lines);
+    const pad = (depth: number): string => ' '.repeat(width * depth);
+
+    // How deep an existing ancestor chain runs, and where its block ends.
+    let matched = 0;
+    let insertAt = lines.length;
+    // The bounds of the ancestor matched at the previous depth. Each level
+    // searches only INSIDE its parent, so a nested key never binds to a
+    // same-named section under a different parent.
+    let parentStart = -1;
+    let parentEnd = lines.length;
+    for (let depth = 0; depth < sections.length; depth++) {
+        const want = sections[depth];
+        const indent = pad(depth);
+        let found = -1;
+        // R2 round 3, finding 5: this carried `depth === 0 ? 0 : insertAt ===
+        // lines.length ? 0 : 0` — every branch zero, i.e. a comment claiming a
+        // scoped search over an expression that does not scope anything. Made
+        // real: a nested section is searched only INSIDE its parent's block,
+        // so a depth-2 path cannot bind to a same-named key under a different
+        // parent. Latent today (the one caller is depth 1) and fixed rather
+        // than deleted, because the next caller is the one it would bite.
+        const from = depth === 0 ? 0 : parentStart + 1;
+        const until = depth === 0 ? lines.length : parentEnd;
+        for (let i = from; i < until; i++) {
+            const line = lines[i];
+            if (line === undefined) continue;
+            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());
+            if (m !== null && m[1] === want) {
+                found = i;
+                break;
+            }
+        }
+        if (found === -1) break;
+        matched = depth + 1;
+        // End of this block: the next line at or above its own indent level.
+        let end = lines.length;
+        for (let i = found + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined) continue;
+            if (line.trim() === '' || line.trim().startsWith('#')) continue;
+            const indentLen = line.length - line.trimStart().length;
+            if (indentLen <= indent.length) {
+                end = i;
+                break;
+            }
+        }
+        insertAt = end;
+        parentStart = found;
+        parentEnd = end;
+    }
+
+    const block: string[] = [];
+    for (let depth = matched; depth < sections.length; depth++) {
+        block.push(`${pad(depth)}${sections[depth] as string}:`);
+    }
+    block.push(`${pad(sections.length)}${key}: ${formatted}`);
+
+    if (matched === 0) {
+        // No ancestor at all — append at EOF as its own block.
+        let body = template;
+        if (!body.endsWith('\n')) body += '\n';
+        return `${body}${block.join('\n')}\n`;
+    }
+    lines.splice(insertAt, 0, ...block);
+    return 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