@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/_lib/release_tag_dispatch.ts

@@ -0,0 +1,63 @@
+/**
+ * The `--ci` fallback dispatch of the three tag-triggered workflows.
+ *
+ * Extracted from `release.ts` as a lowering commit under
+ * `check_source_size_budget`, whose own contract names splitting an
+ * over-ceiling file as the improvement it exists to force. The block is
+ * self-contained — three workflow names, one loop, one warning — and nothing
+ * else in step 10 reads it.
+ *
+ * WHY IT EXISTS. A tag pushed with the default `GITHUB_TOKEN` fires no
+ * tag-triggered workflow: GitHub's recursion guard suppresses the event. All
+ * three workflows accept a `tag` input for exactly this recovery, so under
+ * `--ci` the release dispatches them rather than waiting for an event that will
+ * never arrive. When the tag was pushed with a PAT they already fired and this
+ * is redundant.
+ *
+ * WHY IT NEVER FAILS THE RELEASE. By the time it runs the release is complete —
+ * the tag is pushed, the GitHub Release is created, npm publishes
+ * asynchronously. Dispatching through the API additionally needs the token's
+ * `actions:write` scope, and a 403 for a missing scope must not mark an
+ * already-shipped release as failed. So it warns and continues.
+ */
+
+/** The tag-triggered workflows, in the order the release dispatches them. */
+export const TAG_TRIGGERED_WORKFLOWS = [
+    'release-guard.yml',
+    'publish-npm.yml',
+    'cloud-release.yml',
+] as const;
+
+interface DispatchRunResult {
+    returncode: number;
+}
+
+export interface TagDispatchDeps {
+    run: (argv: string[], opts: { check: boolean }) => DispatchRunResult;
+    /** Where a non-fatal dispatch failure is reported. */
+    warn: (s: string) => void;
+    /** The ref the dispatch runs against — the trunk. */
+    trunk: string;
+}
+
+/** Why one failed dispatch is a warning and not a stop, said to the operator. */
+export function dispatchWarning(workflow: string, code: number, version: string): string {
+    return (
+        `⚠️  Could not dispatch ${workflow} (exit ${code}) — the release ${version} is ` +
+        `already complete (tag + GitHub Release created; npm publishes async). If the tag was ` +
+        `pushed with a PAT, ${workflow} already fired on the tag push. If you rely on the explicit ` +
+        `dispatch, grant RELEASE_PR_TOKEN the "Actions: read and write" scope (fine-grained PAT) ` +
+        `or the "workflow" scope (classic PAT).\n`
+    );
+}
+
+export function dispatchTagWorkflows(deps: TagDispatchDeps, version: string): void {
+    for (const wf of TAG_TRIGGERED_WORKFLOWS) {
+        const r = deps.run(['gh', 'workflow', 'run', wf, '--ref', deps.trunk, '-f', `tag=${version}`], {
+            check: false,
+        });
+        if (r.returncode !== 0) {
+            deps.warn(dispatchWarning(wf, r.returncode, version));
+        }
+    }
+}

package/src/scripts/_lib/review_baseline.ts

@@ -0,0 +1,254 @@
+/**
+ * Session review baseline — the shape, the path, and the subtraction.
+ *
+ * WHY IT EXISTS. `end_review_nudge_hook` measures "did this session mutate
+ * enough to owe a review" as `git diff --numstat HEAD` plus untracked non-doc
+ * files, and its own header records the defect that reading produces: an
+ * uncommitted change that PREDATES the session is charged to the session. The
+ * header also records why it was not fixed — "no such baseline exists anywhere a
+ * `stop` concern can read it (recording one would be new session-wide state, out
+ * of this roadmap phase's one-concern scope)".
+ *
+ * That reason went stale. `session_start` is bound on seven hosts carrying
+ * fourteen concerns (`hook_manifest.yaml`), so a per-session baseline has a slot
+ * to be written from. The measured cost of leaving it: on an accumulator branch
+ * the nudge fired on 1,771 lines of another session's uncommitted work and
+ * became noise, which is worse than silence — an advisory that always fires is
+ * an advisory nobody reads.
+ *
+ * ONE MODULE FOR BOTH SIDES, deliberately. The writer is a `session_start`
+ * concern and the reader is a `stop` concern; if each owned its own idea of the
+ * path or the field names, the reader would silently find nothing and the whole
+ * mechanism would degrade to today's behaviour with no signal. That is the same
+ * argument `turn_end_refusals.ts` makes for its own shared path, and it is why
+ * `BASELINE_STATE_REL` is here rather than in either hook.
+ *
+ * ONE SELF-REFERENCE, named because it is invisible: the file this concern
+ * writes is itself an untracked non-doc file, so in a workspace where
+ * `agents/runtime/` is NOT gitignored it is counted by the very measurement it
+ * feeds — about six lines, once. This repository ignores that path, so the
+ * effect is zero here; a consumer whose ignore file does not cover it sees the
+ * nudge's count six lines high for the session.
+ *
+ * WHAT IT IS NOT. It is not a change set: no paths, no fingerprints, no patch.
+ * It answers exactly the question the nudge asks — how many non-doc lines were
+ * already dirty when this session began — and nothing else. A path-level ledger
+ * is a bigger object with a bigger privacy surface, and nothing in the nudge
+ * consumes one.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * HEAD at this moment, or null.
+ *
+ * It lives HERE rather than in the writer because both sides need it and the
+ * writer already imports from the reader's module: putting it in the hook would
+ * make `end_review_nudge_hook → review_baseline_hook → end_review_nudge_hook` a
+ * cycle. The shared module is the only place with no edge back.
+ *
+ * Null is a real answer and not an error path — a workspace that is not a git
+ * repository, or one with no commit yet, has no HEAD, and `applyBaseline`
+ * compares null to null happily. What it must never do is throw: one caller runs
+ * on session start and the other on the stop path.
+ */
+export function currentHeadSha(cwd: string): string | null {
+    try {
+        const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8' });
+        if (r.status !== 0) return null;
+        const out = (r.stdout ?? '').trim();
+        return out === '' ? null : out;
+    } catch {
+        return null;
+    }
+}
+
+/** State directory, relative to a workspace root. */
+export const BASELINE_STATE_REL = path.join('agents', 'runtime', 'state', 'review-baseline');
+
+export function baselineStateDir(workspaceRoot: string): string {
+    return path.join(workspaceRoot, BASELINE_STATE_REL);
+}
+
+export function baselineStateFile(workspaceRoot: string, sessionKey: string): string {
+    return path.join(baselineStateDir(workspaceRoot), `${sessionKey}.json`);
+}
+
+/**
+ * Whether a line count is an exact sum or the capped, guaranteed-over-threshold
+ * approximation `end_review_nudge_hook` returns past `UNTRACKED_FILE_CAP`.
+ *
+ * Structurally identical to that module's `MutationMeasure` and deliberately
+ * NOT imported from it: this module is the shared floor both hooks sit on, and
+ * importing the consumer would put the cycle back that `currentHeadSha` lives
+ * here to avoid.
+ */
+export type BaselineMeasure = 'exact' | 'capped_approximation';
+
+/** What `session_start` records, and `stop` reads back. */
+export interface ReviewBaseline {
+    /** HEAD at session start, or null where there is no repo / no commit yet. */
+    head_sha: string | null;
+    /** Non-doc mutated lines already present when the session began. */
+    baseline_lines: number;
+    /**
+     * Whether `baseline_lines` is exact or the capped approximation.
+     *
+     * It is recorded because subtracting one kind from the other is arithmetic
+     * over two different quantities — the same defect `head_sha` catches on the
+     * other axis. The capped path returns `THRESHOLD + 1 + tracked`, a synthetic
+     * number chosen to be over the bar rather than to be true, so a session that
+     * starts past the cap and then cleans up would have a real `exact` stop
+     * measurement reduced by a number that never counted anything.
+     *
+     * Optional: a record written before this field existed has no measure, and
+     * defaulting it to `exact` would assert the more permissive of the two on no
+     * evidence. Absent reads as unknown and refuses to subtract.
+     */
+    measure?: BaselineMeasure;
+    written_at: string;
+}
+
+/**
+ * Why a `stop` read could not subtract. Each value is written into the
+ * `review_skipped` telemetry row, because a fallback nobody can see is
+ * indistinguishable from the mechanism never having shipped.
+ */
+export type BaselineFallback =
+    | 'absent' // no file — a host without session_start, or a session older than this
+    | 'unreadable' // present and malformed, or unreadable for any non-ENOENT reason
+    | 'head-moved' // the session committed, so the baseline's denominator is gone
+    | 'mixed-measure'; // one side is a capped approximation and the other is not
+
+export type BaselineOutcome =
+    | { readonly applied: true; readonly baseline: ReviewBaseline; readonly lines: number }
+    | { readonly applied: false; readonly fallback: BaselineFallback; readonly lines: number };
+
+export function parseBaseline(raw: string): ReviewBaseline | null {
+    let decoded: unknown;
+    try {
+        decoded = JSON.parse(raw);
+    } catch {
+        return null;
+    }
+    if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) return null;
+    const o = decoded as Record<string, unknown>;
+    const lines = o['baseline_lines'];
+    if (typeof lines !== 'number' || !Number.isFinite(lines) || lines < 0) return null;
+    const written = o['written_at'];
+    if (typeof written !== 'string') return null;
+    const head = o['head_sha'];
+    const measure = o['measure'];
+    return {
+        head_sha: typeof head === 'string' && head !== '' ? head : null,
+        baseline_lines: lines,
+        ...(measure === 'exact' || measure === 'capped_approximation' ? { measure } : {}),
+        written_at: written,
+    };
+}
+
+/**
+ * The baseline, or WHICH of the two not-found states applies.
+ *
+ * `absent` and `unreadable` are kept apart all the way to the telemetry row,
+ * and collapsing them would have been the easy shape: both mean "cannot
+ * subtract", both fall back identically. They are different findings. `absent`
+ * is the expected steady state on a host with no `session_start` slot and on
+ * every session that started before this shipped; `unreadable` is a corrupt
+ * write, and a rate of it above noise is a defect in this mechanism rather than
+ * a property of the host. A single bucket would hide the second inside the
+ * first, which is the population it is smallest against.
+ */
+export function readBaseline(
+    workspaceRoot: string,
+    sessionKey: string,
+): ReviewBaseline | 'absent' | 'unreadable' {
+    const file = baselineStateFile(workspaceRoot, sessionKey);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    } catch (exc) {
+        // ONLY a genuinely missing file is `absent`. Every other IO failure —
+        // EACCES, EISDIR, EMFILE — is a defect in this mechanism, which is the
+        // population `unreadable` exists to make visible; routing them all to
+        // `absent` would bury them inside the one bucket that is legitimately
+        // large on every host without a session_start slot.
+        const code = (exc as NodeJS.ErrnoException | null)?.code;
+        return code === 'ENOENT' ? 'absent' : 'unreadable';
+    }
+    return parseBaseline(raw) ?? 'unreadable';
+}
+
+/**
+ * Apply the baseline to a measured line count.
+ *
+ * FAIL OPEN, NEVER SILENT — the three not-applied branches all return the
+ * UNSUBTRACTED count, so every failure mode of this mechanism degrades to
+ * exactly the behaviour that shipped before it. The alternative, returning zero
+ * or refusing to fire, would let a missing state file silence a genuine review
+ * obligation, and a safety advisory must not be disarmed by its own
+ * instrumentation failing.
+ *
+ * `head-moved` is the branch worth naming, and worth naming honestly: it is
+ * TERMINAL for the session. A session that committed mid-run moved HEAD, so
+ * `git diff HEAD` now measures against a different base than the baseline did
+ * and the subtraction is arithmetic over two different quantities. It is caught
+ * rather than absorbed, because absorbing it would UNDER-report on exactly the
+ * sessions that did the most work — but the baseline is written once per
+ * session and never refreshed, so from the first commit onward that session is
+ * charged for the whole pre-existing dirty tree again. The mechanism's useful
+ * life is "until this session's first commit", which is stated here rather than
+ * discovered later. Re-baselining after a commit is the obvious repair and is
+ * NOT taken here: a second write has to distinguish "HEAD moved because we
+ * committed our own work" from "a peer session committed underneath us", and
+ * nothing in a stop payload answers that.
+ *
+ * `mixed-measure` is the same defect on the third axis, and it covers the
+ * SYMMETRIC case too. Past `UNTRACKED_FILE_CAP` the measurement is a synthetic
+ * `THRESHOLD + 1 + tracked` chosen to be over the bar rather than to be true, so
+ * subtracting it from — or out of — an exact count is meaningless in both
+ * directions; and subtracting one capped reading from another cancels the
+ * constant, which is worse than meaningless because it silences the nudge. The
+ * name is kept over a more literal `not-both-exact` because the fallback's
+ * subject is the measure, and a telemetry enum is read far more often than it is
+ * renamed.
+ *
+ * The clamp at zero is not cosmetic either: a session that reverts part of a
+ * pre-existing dirty tree measures below its own baseline, and a negative
+ * comparison against the threshold would read as "no mutation" for a session
+ * that deleted a thousand lines.
+ */
+export function applyBaseline(
+    measuredLines: number,
+    baseline: ReviewBaseline | 'absent' | 'unreadable',
+    headSha: () => string | null,
+    measuredMeasure: BaselineMeasure = 'exact',
+): BaselineOutcome {
+    if (baseline === 'absent' || baseline === 'unreadable') {
+        return { applied: false, fallback: baseline, lines: measuredLines };
+    }
+    // The measure check runs BEFORE the HEAD check because it needs no subprocess.
+    // `headSha` is a thunk for the same reason: on the two fallback branches above
+    // — the steady state on every host without the nudge, and on every session
+    // before its first baseline write — the value is discarded, and evaluating it
+    // eagerly spent an 11-14 ms `git rev-parse` on each of those stops.
+    // Refused when the two measures DISAGREE, and equally when both are capped.
+    // The symmetric case is the dangerous one and the first version missed it:
+    // the capped path returns `THRESHOLD + 1 + tracked`, so two capped readings
+    // cancel their synthetic constant and an untracked-only session that started
+    // past the cap subtracts to ZERO — silencing the nudge, which is the one
+    // direction this module's own header forbids. Only `exact` minus `exact` is
+    // arithmetic over two counts of the same thing.
+    if (baseline.measure !== 'exact' || measuredMeasure !== 'exact') {
+        return { applied: false, fallback: 'mixed-measure', lines: measuredLines };
+    }
+    if (baseline.head_sha !== headSha()) {
+        return { applied: false, fallback: 'head-moved', lines: measuredLines };
+    }
+    return {
+        applied: true,
+        baseline,
+        lines: Math.max(0, measuredLines - baseline.baseline_lines),
+    };
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,49 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+/**
+ * Whether `diff_lines` had this session's start-of-session baseline subtracted,
+ * and when it did not, WHY.
+ *
+ * A closed enum, never free text, so the privacy floor below still holds by
+ * construction. It exists because the subtraction's failure modes all fall back
+ * to the unsubtracted count — which is the safe direction and also an invisible
+ * one: without this field, a line reading 1,771 cannot be told apart from a
+ * session that really did mutate 1,771 lines.
+ *
+ * WHAT IT MEASURES, and the half it cannot. This line is written only when the
+ * nudge FIRES, so the distribution here is the fallback rate among firing
+ * sessions. The sessions the subtraction silenced — the mechanism working —
+ * produce no line at all, so the silence rate is NOT observable from this
+ * stream and no clause here should be read as claiming it is. Recording a row
+ * for a nudge that did not fire would put a `review_skipped` event in the audit
+ * log for a session where no review was skipped, which is a worse defect than
+ * the blind spot; measuring it properly needs a counter of its own, and that is
+ * a decision rather than an oversight.
+ *
+ * `absent` is the expected steady state on a host with no `session_start` slot
+ * and on every session that predates the baseline concern; `unreadable` is a
+ * corrupt write and a rate above noise is a defect in the mechanism itself;
+ * `head_moved` is a session that committed mid-run, which moves `git diff
+ * HEAD`'s base and makes the subtraction arithmetic over two different
+ * quantities; `mixed_measure` is the same failure on the capped-approximation
+ * axis, where one side is a synthetic over-threshold number rather than a count.
+ */
+export type BaselineApplication =
+    | 'applied'
+    | 'absent'
+    | 'unreadable'
+    | 'head_moved'
+    | 'mixed_measure';
+
+const BASELINE_APPLICATIONS: readonly BaselineApplication[] = [
+    'applied',
+    'absent',
+    'unreadable',
+    'head_moved',
+    'mixed_measure',
+];
+
 import { appliedIds } from './audit_field_provenance.js';
 import type { NoFreeForm } from './runtime_journal.js';
 import { type PrivacyClass } from './privacy_class.js';
@@ -51,6 +94,13 @@ export interface ReviewSkippedInput {
     diff_lines: number;
     /** Whether `diff_lines` is exact or a capped approximation — see above. */
     mutation_measure: MutationMeasure;
+    /**
+     * Whether the session baseline was subtracted from `diff_lines`, and if not
+     * why. OPTIONAL, and absence is honest rather than a default: a line written
+     * by a producer that predates the baseline mechanism recorded nothing about
+     * it, and writing `absent` for those would assert a measurement nobody made.
+     */
+    baseline?: BaselineApplication | undefined;
     /** ISO-8601 UTC timestamp; caller supplies (keeps this fn pure/deterministic). */
     ts: string;
     /** Stable id (ULID, UUID, or content hash); caller supplies. */
@@ -103,6 +153,9 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
     }
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID, UUID, or content hash) is required');
+    if (input.baseline !== undefined && !BASELINE_APPLICATIONS.includes(input.baseline)) {
+        errors.push(`baseline must be one of ${BASELINE_APPLICATIONS.join(', ')}`);
+    }
 
     if (errors.length) return { line: null, errors };
 
@@ -131,7 +184,14 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         persona: null,
         input_kind: 'prompt',
         type: 'note',
-        review_skipped: { diff_lines: input.diff_lines, mutation_measure: input.mutation_measure },
+        review_skipped: {
+            diff_lines: input.diff_lines,
+            mutation_measure: input.mutation_measure,
+            // Omitted, not defaulted, when the producer recorded nothing —
+            // audit-log-v1's absent-versus-present split is the same one
+            // `skills_applied` uses above, for the same reason.
+            ...(input.baseline === undefined ? {} : { baseline: input.baseline }),
+        },
     };
 
     return { line, errors: [] };

package/src/scripts/_lib/rides_along.ts

@@ -0,0 +1,102 @@
+/**
+ * What rides along during a mission — `road-to-adversarial-verification-and-long-runs`
+ * 6.1.
+ *
+ * `active-remediation`'s ladder is fix-now / note+ask / follow-up PR, and its
+ * middle rung is unavailable inside an autonomous mission: there is nobody to
+ * ask. Without a replacement the rung collapses in one of two bad directions —
+ * every spotted issue becomes a fix (scope creep, which `minimal-safe-diff`
+ * exists to stop) or every one becomes silence (which `active-remediation`
+ * exists to stop). So under a mission the middle rung becomes **emit a follow-up
+ * artefact**, and this module decides which rung a candidate lands on.
+ *
+ * **Six criteria, ALL of which must hold.** They are `AND`-ed rather than scored
+ * because a scored version lets a large change buy its way in with four cheap
+ * yeses, which is the shape that turns a boy-scout rule into a refactor licence.
+ *
+ * Pure: the caller characterises the change, this decides. The characterisation
+ * is a judgement and stays the agent's; the DECISION is mechanical so it is the
+ * same for the same inputs.
+ */
+
+/** What the agent observed about a candidate improvement. */
+export interface Candidate {
+    /** What it is. Used only in the rendered line. */
+    readonly what: string;
+    /** In the same request path / module the mission is already touching. */
+    readonly local: boolean;
+    /** Small: roughly a handful of lines in one production file. */
+    readonly small: boolean;
+    /** Low blast radius — nothing outside this module observes the change. */
+    readonly lowBlastRadius: boolean;
+    /** Clearly correct: a reviewer would not need to be persuaded. */
+    readonly clearlyCorrect: boolean;
+    /** Testable, and the test ships in the same commit. */
+    readonly testable: boolean;
+    /** Carries NO new product decision — nothing about what the thing should do. */
+    readonly noProductDecision: boolean;
+}
+
+/** The kinds of improvement a mission may take at all. */
+export const RIDE_ALONG_KINDS: readonly string[] = [
+    'characterization-test',
+    'regression-test',
+    'small-adjacent-bug',
+    'naming',
+    'types',
+    'robustness',
+    'local-dead-code',
+    'simplify-touched-code',
+    'testability',
+] as const;
+
+export type Disposition = 'ride-along' | 'follow-up-artefact';
+
+export interface Verdict {
+    readonly disposition: Disposition;
+    /** Every criterion that failed, in declaration order. Empty on ride-along. */
+    readonly failed: readonly string[];
+}
+
+const CRITERIA: readonly (readonly [keyof Candidate, string])[] = [
+    ['local', 'not local to the path this mission is already touching'],
+    ['small', 'not small — more than a handful of lines in one file'],
+    ['lowBlastRadius', 'blast radius reaches beyond this module'],
+    ['clearlyCorrect', 'not clearly correct — a reviewer would need persuading'],
+    ['testable', 'not testable in the same commit'],
+    ['noProductDecision', 'carries a new product decision'],
+];
+
+/**
+ * Which rung this candidate lands on.
+ *
+ * Returns EVERY failed criterion rather than the first, because the follow-up
+ * artefact has to say why the change was deferred, and "it failed one of six"
+ * is not a reason a later reader can act on.
+ */
+export function disposition(c: Candidate): Verdict {
+    const failed = CRITERIA.filter(([k]) => c[k] !== true).map(([, why]) => why);
+    return {
+        disposition: failed.length === 0 ? 'ride-along' : 'follow-up-artefact',
+        failed,
+    };
+}
+
+/**
+ * The follow-up artefact's body — what was seen, and why it did not ride along.
+ *
+ * A deferral with no reason is the note-and-forget `active-remediation` already
+ * forbids, one layer out: the artefact exists so the issue is still owed, and an
+ * artefact that does not say why it was deferred cannot be triaged later.
+ */
+export function followUpBody(c: Candidate, v: Verdict): string {
+    if (v.disposition === 'ride-along') return '';
+    return [
+        `Deferred adjacent improvement: ${c.what}`,
+        '',
+        'Did not ride along because:',
+        ...v.failed.map((f) => `  - ${f}`),
+        '',
+        'Spotted during a mission; the code was left alone deliberately.',
+    ].join('\n');
+}

package/src/scripts/_lib/settings_renamed_keys.ts

@@ -0,0 +1,82 @@
+/**
+ * Settings keys this package has RENAMED, old path -> new path.
+ *
+ * Distinct from `REMOVED_KEYS` in the one way that matters to a user: a
+ * removed key's value is DISCARDED, and a renamed key's value is CARRIED.
+ * Putting a rename in the removed map would silently return an installed
+ * `false` to the shipped default, which is the opposite of accepting the old
+ * key — so the two maps stay separate even though both warn once.
+ *
+ * An entry is dropped one minor after it lands. The new key always wins when
+ * one layer carries both: a reader who has already migrated is not overridden
+ * by a stale line they forgot to delete.
+ *
+ * Its own module rather than more lines in `agent_settings.ts`, which sits
+ * three lines under the 1500-line source ceiling — a sixty-line addition there
+ * is sixty units of ratchet, and here it is none.
+ */
+
+export type SettingsLayer = Record<string, unknown>;
+
+export const RENAMED_KEYS: ReadonlyMap<string, string> = new Map([
+    ['planning.challenge_on_create', 'planning.closure_pass'],
+]);
+
+/** Keys already warned about in THIS process — the "once per run" dedupe. */
+const _warned = new Set<string>();
+
+/** Read a dotted path out of a settings tree. `undefined` when absent. */
+function _read(tree: SettingsLayer, dotted: string): unknown {
+    let cur: unknown = tree;
+    for (const part of dotted.split('.')) {
+        if (cur === null || typeof cur !== 'object' || Array.isArray(cur)) return undefined;
+        cur = (cur as SettingsLayer)[part];
+    }
+    return cur;
+}
+
+/** Write a dotted path into a settings tree, creating the intermediate maps. */
+function _write(tree: SettingsLayer, dotted: string, value: unknown): void {
+    const parts = dotted.split('.');
+    let cur: SettingsLayer = tree;
+    for (const part of parts.slice(0, -1)) {
+        const next = cur[part];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) cur[part] = {};
+        cur = cur[part] as SettingsLayer;
+    }
+    cur[parts[parts.length - 1] as string] = value;
+}
+
+/**
+ * Carry every renamed key's value onto its new path within ONE layer, and
+ * return that layer.
+ *
+ * Per LAYER, before the merge, and that ordering is the whole contract: the
+ * shipped template already carries the new key, so a rename applied to the
+ * MERGED tree would always find the target "already set" and drop the user's
+ * value on the floor. Applied per layer, the old key becomes the new key
+ * inside the layer that wrote it, and ordinary precedence does the rest.
+ *
+ * Mutates and returns `layer` so it can wrap an existing merge call without
+ * adding a statement. Never throws: a layer that cannot be walked is a layer
+ * with nothing to migrate.
+ */
+export function applyRenamedKeys<T extends SettingsLayer>(layer: T): T {
+    for (const [oldKey, newKey] of RENAMED_KEYS) {
+        const oldValue = _read(layer, oldKey);
+        if (oldValue === undefined) continue;
+        if (_read(layer, newKey) === undefined) _write(layer, newKey, oldValue);
+        if (_warned.has(oldKey)) continue;
+        _warned.add(oldKey);
+        process.stderr.write(
+            `⚠️  settings: \`${oldKey}\` was renamed to \`${newKey}\`. The old key still ` +
+                `works for one minor; rename it in your .agent-settings.yml.\n`,
+        );
+    }
+    return layer;
+}
+
+/** Test seam — the once-per-process warning dedupe is process state. */
+export function _resetRenameWarnings(): void {
+    _warned.clear();
+}