@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.7 → 0.1.8

package/packages/agent-settings/src/deploy/lean-ctx-merge.ts

@@ -0,0 +1,580 @@
+/**
+ * The merge contract for a repo-local lean-ctx file, corrected by a
+ * SECOND independent review (2026-09-29) after the marker-region design
+ * itself shipped. Three real bugs found there:
+ *
+ *  3. HIGH — `shell_allowlist_extra` lived INSIDE the managed block, so a
+ *     real `lean-ctx allow <cmd>` writing an entry into it was wiped by
+ *     the very next deploy's self-heal (a whole-block replace). DECISION:
+ *     the array leaves the managed block and becomes a UNION key —
+ *     resolved by a narrow text scan (string literals only), adl's
+ *     required entries inserted before `]` if missing, nothing ever
+ *     removed or reordered.
+ *  4. HIGH — migration required the asset's CURRENT text to be found
+ *     verbatim in the existing file. The asset changing at all (as it
+ *     legitimately does, e.g. this same fix) broke migration for every
+ *     already-enrolled repo, including this one. DECISION: migration now
+ *     classifies the existing (markerless) file LINE BY LINE — a line
+ *     matching a KNOWN adl key (`minimal_overhead`, ..., `mode`) is adl's
+ *     own, replaced by the canonical value regardless of what it used to
+ *     say; a blank line is dropped (formatting only); anything else —
+ *     an unrecognized key, a table header, OR A COMMENT (finding 4-minor,
+ *     independent review 2026-09-30, superseding this bullet's original
+ *     "comments are dropped too" — see `migrateByKnownKeys`'s own doc
+ *     comment for why) — is the user's, kept verbatim, in place, after
+ *     the canonical block. This never depends on the asset's exact prior
+ *     text, so a template change cannot break migration again.
+ *  5. MED — two blind spots: a quoted duplicate key AFTER the block, and
+ *     a user table header BEFORE it (which silently turns adl's own keys
+ *     into `<table>.<key>`), both passed as "unchanged" under pure
+ *     text/region matching. DECISION: after composing (never
+ *     re-serializing — this validates the ACTUAL COMPOSED TEXT, whether
+ *     that text turned out unchanged, self-healed, or migrated), the
+ *     WHOLE file is parsed with a real TOML parser (`Bun.TOML`, not
+ *     `@iarna/toml` — TOML 0.5, rejects valid TOML 1.0) and every adl key
+ *     must resolve AT THE TOP LEVEL to adl's own value; any parse
+ *     failure or mismatch is a conflict, never a silent "unchanged".
+ *     Independent review, 2026-09-30, finding 5-rest: this validation is
+ *     only as good as `scalarValuesOf`'s own coverage — a version that
+ *     recognized only `true`/`false` left layout.toml's own `mode = "xdg"`
+ *     (a string) OUT of `expectedScalars` entirely, so a table header
+ *     before ITS block passed silently. `scalarValuesOf` now parses every
+ *     scalar shape a managed block can carry (bool, number, quoted
+ *     string, simple string array), closing that gap for every target,
+ *     not just config.toml's boolean keys.
+ *
+ * Marker-region mechanics (BEGIN/END, malformed markers, migration) are
+ * shared by every target — config.toml's scalar keys, layout.toml's
+ * whole content, and (with an append-not-migrate variant — see finding 6,
+ * `resolveGitignoreWrite`) the `.agents/.gitignore` block. config.toml
+ * additionally carries the union-key array outside its own block
+ * (`resolveConfigTomlWrite`).
+ */
+
+export const LEAN_CTX_MARKER_START = '# >>> adl managed (do not edit within this block) >>>';
+export const LEAN_CTX_MARKER_END = '# <<< adl managed <<<';
+export const SHELL_ALLOWLIST_KEY = 'shell_allowlist_extra';
+
+interface Region {
+  readonly start: number;
+  /** Exclusive — the index immediately after the closing marker's own text. */
+  readonly end: number;
+}
+type RegionResult = Region | 'missing' | 'malformed';
+
+function findRegion(content: string): RegionResult {
+  const start = content.indexOf(LEAN_CTX_MARKER_START);
+  const stop = content.indexOf(LEAN_CTX_MARKER_END);
+  if (start < 0 && stop < 0) return 'missing';
+  if (start < 0 || stop < 0 || stop < start) return 'malformed';
+  return { start, end: stop + LEAN_CTX_MARKER_END.length };
+}
+
+/** The block's own content between (and including) its markers, no trailing newline. */
+function canonicalBlockOf(assetText: string): string {
+  return assetText.replace(/\n+$/, '');
+}
+
+function spliceRegion(content: string, region: Region, canonicalBlock: string): string {
+  return `${content.slice(0, region.start)}${canonicalBlock}${content.slice(region.end)}`;
+}
+
+/** `key = ...` names declared directly inside `canonicalBlock` — a plain line scan, not a TOML parse (this module never parses to decide what to write; only to VALIDATE the result — see `validateComposedToml`). */
+function declaredKeyNames(canonicalBlock: string): readonly string[] {
+  const names: string[] = [];
+  for (const line of canonicalBlock.split('\n')) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+    if (match) names.push(match[1] as string);
+  }
+  return names;
+}
+
+function duplicateKeyOutsideRegion(content: string, region: Region, canonicalBlock: string): string | undefined {
+  const outside = content.slice(0, region.start) + content.slice(region.end);
+  for (const name of declaredKeyNames(canonicalBlock)) {
+    if (new RegExp(`^\\s*${name}\\s*=`, 'm').test(outside)) return name;
+  }
+  return undefined;
+}
+
+/**
+ * Migration (finding 4): classifies a markerless file the lock already
+ * says adl wrote, line by line, against `knownKeys` for THIS target.
+ * Never depends on the asset's own exact prior text — a `key = value`
+ * line naming a known key is adl's own (dropped; the canonical block
+ * replaces it outright, whatever it used to say); a blank line is
+ * dropped (formatting only); anything else — including a full-line
+ * comment — is kept verbatim, IN ORDER, as the user's.
+ *
+ * A comment is deliberately NOT dropped (independent review, 2026-09-30,
+ * finding 4-minor — this superseded an earlier version that dropped
+ * every comment line as "adl's own old commentary, not reliably told
+ * apart from a user's by text alone"): dropping a genuine user comment
+ * is permanent, silent data loss; keeping an old adl comment as harmless
+ * extra text next to the canonical block (which carries its own fresh
+ * comments regardless) costs nothing. When in doubt, keep it — the same
+ * rule this module already applies to every OTHER unrecognized line.
+ *
+ * `recognizedCount` is how many lines matched a known key — the signal
+ * that decides whether migration is safe AT ALL (`resolveLeanCtxWrite`'s
+ * own caller): a file with at least one recognizable adl key is
+ * plausibly adl's own prior content, whatever else is wrong with it; a
+ * file with NONE (a whole-file clobber — `"tampered\n"`, Tarun 2026-09-29,
+ * D.b: this exact scenario is a conflict, not a guess) has no evidence
+ * left to migrate from at all.
+ */
+function migrateByKnownKeys(content: string, knownKeys: ReadonlySet<string>): { readonly kept: readonly string[]; readonly recognizedCount: number } {
+  const kept: string[] = [];
+  let recognizedCount = 0;
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(trimmed);
+    if (match && knownKeys.has(match[1] as string)) {
+      recognizedCount += 1;
+      continue;
+    }
+    kept.push(line);
+  }
+  return { kept, recognizedCount };
+}
+
+/** One adl-owned scalar whose value differed and was restored to adl's own (2026-09-30, Tarun's merge-contract correction: "adl-owned entries SELF-HEAL" — a differing value is drift, never a conflict). Named on the write outcome so deploy/doctor can report it explicitly, the same way a healed hook is named. */
+export interface RestoredScalar {
+  readonly key: string;
+  readonly value: unknown;
+  readonly previous: unknown;
+}
+
+export type LeanCtxWriteOutcome =
+  | { readonly action: 'unchanged' }
+  | { readonly action: 'write'; readonly text: string; readonly restoredScalars?: readonly RestoredScalar[] }
+  | { readonly action: 'conflict'; readonly reason: string };
+
+/** Real TOML 1.0 parse (Bun's built-in, not `@iarna/toml` — TOML 0.5) — read-only validation, never used to decide what to write. */
+function parseToml(text: string): Record<string, unknown> | 'invalid' {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun global, no @types/bun in this package's own deps
+    const doc = (globalThis as any).Bun.TOML.parse(text);
+    return typeof doc === 'object' && doc !== null && !Array.isArray(doc) ? (doc as Record<string, unknown>) : 'invalid';
+  } catch {
+    return 'invalid';
+  }
+}
+
+/** True iff `actual` matches `expected`, where `expected` may be a scalar (compared by `===`) or an array (compared element-by-element, same length and order). */
+function tomlValueMatches(actual: unknown, expected: unknown): boolean {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && actual.length === expected.length && expected.every((entry, i) => actual[i] === entry);
+  }
+  return actual === expected;
+}
+
+/**
+ * Finding 5's safety net: parses the COMPOSED text (whatever this module
+ * is about to call "unchanged" or "write") and confirms every one of
+ * `expectedScalars` resolves at the TOP LEVEL to its expected value, and
+ * (when `expectedArrayEntries` is given) `arrayKey` resolves to an array
+ * containing every one of them. A duplicate key elsewhere in the file, or
+ * a table header before the managed block turning adl's own keys into
+ * `<table>.<key>`, fails this — a conflict, never a silent pass.
+ */
+function validateComposedToml(
+  text: string,
+  expectedScalars: Readonly<Record<string, unknown>>,
+  arrayKey?: string,
+  expectedArrayEntries?: readonly string[],
+): string | undefined {
+  const doc = parseToml(text);
+  if (doc === 'invalid') return 'the composed file is not valid TOML';
+  for (const [key, value] of Object.entries(expectedScalars)) {
+    if (!tomlValueMatches(doc[key], value)) return `"${key}" does not resolve to adl's value at the top level (a table header before the managed block, or a duplicate key, is shadowing it)`;
+  }
+  if (arrayKey !== undefined && expectedArrayEntries !== undefined) {
+    const actual = doc[arrayKey];
+    if (!Array.isArray(actual)) return `"${arrayKey}" does not resolve to an array at the top level`;
+    const missing = expectedArrayEntries.filter((entry) => !actual.includes(entry));
+    if (missing.length > 0) return `"${arrayKey}" is missing adl-required entries: ${missing.join(', ')}`;
+  }
+  return undefined;
+}
+
+/**
+ * Parses a single-line TOML scalar value — bool, integer/float, quoted
+ * string, or a simple (string-literals-only) inline array — or returns
+ * `undefined` for anything else (a multi-line value, a table, etc.),
+ * which `scalarValuesOf` then simply skips rather than guessing.
+ */
+function parseTomlScalarValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  const stringMatch = /^"((?:[^"\\]|\\.)*)"$/.exec(trimmed);
+  if (stringMatch) return (stringMatch[1] as string).replace(/\\(.)/g, '$1');
+  const arrayMatch = /^\[(.*)\]$/.exec(trimmed);
+  if (arrayMatch) {
+    const entries = parseSimpleStringArrayBody(arrayMatch[1] as string);
+    if (entries !== 'malformed') return entries;
+  }
+  return undefined;
+}
+
+/**
+ * Every `key = value` line's value, parsed generically (finding 5-rest,
+ * independent review 2026-09-30 — this used to recognize `true`/`false`
+ * only, so a STRING-valued key like layout.toml's own `mode = "xdg"` was
+ * silently excluded from `validateComposedToml`'s `expectedScalars`
+ * entirely, leaving that target's own table-header-before-block blind
+ * spot uncaught; see this file's header for the full history). A value
+ * this module cannot parse (a multi-line construct) is simply skipped,
+ * never guessed at.
+ */
+function scalarValuesOf(canonicalBlock: string): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const line of canonicalBlock.split('\n')) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/.exec(line.trim());
+    if (!match) continue;
+    const value = parseTomlScalarValue(match[2] as string);
+    if (value !== undefined) values[match[1] as string] = value;
+  }
+  return values;
+}
+
+/**
+ * Marker-region-only target (layout.toml): the whole file's meaningful
+ * content is inside the block. Callers only reach this once
+ * `currentText !== assetText` — an exact match is always `unchanged`.
+ */
+export function resolveLeanCtxWrite(assetText: string, currentText: string, wasWrittenByUs: boolean): LeanCtxWriteOutcome {
+  const canonicalBlock = canonicalBlockOf(assetText);
+  const region = findRegion(currentText);
+
+  if (region === 'malformed') {
+    return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
+  }
+
+  if (region === 'missing') {
+    if (!wasWrittenByUs) {
+      return { action: 'conflict', reason: 'no adl-managed block found in this file, and it is not recorded as adl-written; left untouched' };
+    }
+    const knownKeys = new Set(declaredKeyNames(canonicalBlock));
+    const { kept, recognizedCount } = migrateByKnownKeys(currentText, knownKeys);
+    if (recognizedCount === 0) {
+      return { action: 'conflict', reason: 'no recognizable adl-owned content found to migrate; left untouched' };
+    }
+    const composed = kept.length > 0 ? `${canonicalBlock}\n\n${kept.join('\n').replace(/\n+$/, '')}\n` : `${canonicalBlock}\n`;
+    const invalid = validateComposedToml(composed, scalarValuesOf(canonicalBlock));
+    if (invalid !== undefined) return { action: 'conflict', reason: `cannot migrate safely: ${invalid}` };
+    return { action: 'write', text: composed };
+  }
+
+  const duplicate = duplicateKeyOutsideRegion(currentText, region, canonicalBlock);
+  if (duplicate !== undefined) {
+    return { action: 'conflict', reason: `"${duplicate}" is declared both inside and outside the adl-managed block; left untouched` };
+  }
+
+  const installed = currentText.slice(region.start, region.end);
+  const composed = installed === canonicalBlock ? currentText : spliceRegion(currentText, region, canonicalBlock);
+  const invalid = validateComposedToml(composed, scalarValuesOf(canonicalBlock));
+  if (invalid !== undefined) return { action: 'conflict', reason: invalid };
+  return installed === canonicalBlock ? { action: 'unchanged' } : { action: 'write', text: composed };
+}
+
+/** A simple (string-literals-only) array's parsed entries, or 'malformed' if it contains anything else (a number, a nested array, a bare identifier). */
+function parseSimpleStringArrayBody(body: string): readonly string[] | 'malformed' {
+  const trimmed = body.trim();
+  if (trimmed.length === 0) return [];
+  const entries: string[] = [];
+  for (const piece of trimmed.split(',').map((p) => p.trim())) {
+    if (piece.length === 0) continue;
+    const match = /^"((?:[^"\\]|\\.)*)"$/.exec(piece);
+    if (!match) return 'malformed';
+    entries.push(match[1] as string);
+  }
+  return entries;
+}
+
+interface ArraySpan {
+  readonly start: number;
+  readonly end: number;
+  readonly body: string;
+}
+function findArray(text: string, key: string): ArraySpan | 'missing' | 'malformed' {
+  const startMatch = new RegExp(`^${key}\\s*=\\s*\\[`, 'm').exec(text);
+  if (!startMatch) return 'missing';
+  const openBracket = startMatch.index + startMatch[0].length - 1;
+  const closeBracket = text.indexOf(']', openBracket);
+  if (closeBracket === -1) return 'malformed';
+  const body = text.slice(openBracket + 1, closeBracket);
+  if (body.includes('[')) return 'malformed'; // a nested array -- not "a simple string array"
+  return { start: startMatch.index, end: closeBracket + 1, body };
+}
+
+/** Text-splices `missingEntries` into an existing simple array's body, right before its closing `]`, never touching what is already there. */
+function insertMissingEntries(text: string, array: ArraySpan, missingEntries: readonly string[]): string {
+  const closeBracketIndex = array.end - 1; // position of ']'
+  const bodyTrimmedEnd = text.slice(array.start, closeBracketIndex).replace(/\s+$/, '');
+  const needsLeadingComma = /[^\s[]$/.test(bodyTrimmedEnd) && !bodyTrimmedEnd.endsWith(',');
+  const insertion = `${needsLeadingComma ? ',' : ''}\n${missingEntries.map((e) => `    "${e}",`).join('\n')}\n`;
+  return `${text.slice(0, closeBracketIndex)}${insertion}${text.slice(closeBracketIndex)}`;
+}
+
+/**
+ * The portion of `text` that TOML grammar guarantees is ALL bare
+ * (top-level) key/value pairs — everything up to (not including) the
+ * first `[table]` or `[[array-of-tables]]` header. A key/value LINE
+ * found inside this prefix is unambiguously top-level; the same key name
+ * appearing after a table header belongs to that table instead
+ * (`table.key`, a completely different key), which a pure line/regex
+ * scan cannot tell apart from a top-level line on its own — this keeps
+ * that distinction correct without needing to track table context.
+ */
+function topLevelPrefixEnd(text: string): number {
+  const match = /^\[/m.exec(text);
+  return match ? match.index : text.length;
+}
+
+/**
+ * Removes the (top-level-only, see `topLevelPrefixEnd`) `key = value`
+ * line for each key in `keys` from `text` — used for every adl-owned
+ * scalar key the current file ALREADY declares at the top level, whether
+ * its value matches adl's canonical one or not: the FULL canonical block
+ * (always inserted whole, never partial — every other reader of this
+ * module assumes the managed block IS the complete canonical text) is
+ * about to declare it again, and TOML forbids a duplicate top-level key
+ * regardless of whether the two values agree. This is not "deleting a
+ * user's line" in the sense the merge decision forbids — a matching
+ * value is unchanged and un-lost, merely consolidated into the block
+ * exactly where an ordinary deploy would have put it; a DIFFERING value
+ * is adl-owned drift, and adl's own merge contract ("adl-owned entries
+ * SELF-HEAL") already says adl's value wins — the caller names the
+ * restore (`RestoredScalar`) so it is never silent.
+ */
+function removeTopLevelScalarLines(text: string, keys: ReadonlySet<string>): string {
+  if (keys.size === 0) return text;
+  const prefixEnd = topLevelPrefixEnd(text);
+  const prefix = text.slice(0, prefixEnd);
+  const rest = text.slice(prefixEnd);
+  const keptPrefixLines = prefix.split('\n').filter((line) => {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line.trim());
+    return match === null || !keys.has(match[1] as string);
+  });
+  return `${keptPrefixLines.join('\n')}${rest}`;
+}
+
+/**
+ * config.toml specifically (finding 3 + 4 + 5, and MERGED entirely,
+ * Tarun 2026-09-30 — see this function's own migration branch, below,
+ * and the describe block in lean-ctx-merge-contract.test.ts headed
+ * "config.toml's allow list is MERGED entry-by-entry" for the full
+ * decision): its own scalar keys live in the marker-region block exactly
+ * like `resolveLeanCtxWrite`, but `shell_allowlist_extra` lives OUTSIDE
+ * the markers as a UNION key — located anywhere in the file by a narrow
+ * text scan, adl's required entries inserted before `]` if missing,
+ * nothing ever removed/reordered. A non-simple array (anything but
+ * string literals) is a conflict.
+ */
+export function resolveConfigTomlWrite(assetText: string, currentText: string, wasWrittenByUs: boolean): LeanCtxWriteOutcome {
+  const assetArray = findArray(assetText, SHELL_ALLOWLIST_KEY);
+  if (assetArray === 'missing' || assetArray === 'malformed') {
+    throw new Error(`agent-settings lean-ctx config.toml asset itself has no valid "${SHELL_ALLOWLIST_KEY}" array — this is a packaging bug, not a target-repo conflict`);
+  }
+  const requiredEntries = parseSimpleStringArrayBody(assetArray.body);
+  if (requiredEntries === 'malformed') {
+    throw new Error(`agent-settings lean-ctx config.toml asset's own "${SHELL_ALLOWLIST_KEY}" array is not a simple string array — this is a packaging bug, not a target-repo conflict`);
+  }
+  const canonicalBlock = canonicalBlockOf(assetText.slice(0, assetArray.start));
+  const scalarValues = scalarValuesOf(canonicalBlock);
+
+  let working = currentText;
+  const region = findRegion(working);
+  if (region === 'malformed') return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
+
+  if (region === 'missing') {
+    if (!wasWrittenByUs) return { action: 'conflict', reason: 'no adl-managed block found in this file, and it is not recorded as adl-written; left untouched' };
+
+    // Tarun, 2026-09-30 (corrected the same day — Tarun's merge contract
+    // is "adl-owned entries SELF-HEAL; user additions are kept"): "Merge
+    // the allow list in config.toml, the standard allow list must be
+    // checked entry by entry, missing should be added, user entries must
+    // not be removed." A markerless file is a MERGE target whenever it
+    // is valid TOML at all — even a WHOLE-FILE overwrite with the user's
+    // own unrelated content — never a conflict. An adl-owned scalar
+    // already present at the top level ALWAYS self-heals to adl's own
+    // value (an older asset default, or a user edit, is drift, not a
+    // conflict — otherwise every already-enrolled repo carrying an older
+    // adl default would conflict on upgrade); the restore is named
+    // (`restoredScalars`, below) so it is never silent. Conflict remains
+    // ONLY where merging is genuinely unsafe: invalid TOML (nowhere to
+    // safely place a block), or an allow-list value that isn't a simple
+    // string array. Nothing of the user's is ever deleted or reordered.
+    const parsedCurrent = parseToml(currentText);
+    if (parsedCurrent === 'invalid') {
+      return { action: 'conflict', reason: 'current file is not valid TOML; cannot place the managed block safely' };
+    }
+    if (Object.prototype.hasOwnProperty.call(parsedCurrent, SHELL_ALLOWLIST_KEY) && !Array.isArray(parsedCurrent[SHELL_ALLOWLIST_KEY])) {
+      return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
+    }
+
+    // Every adl-owned scalar key the current file ALREADY declares at
+    // the top level — matching value or not — is removed from its
+    // original line: the FULL canonical block (always inserted whole; a
+    // "partial" block would make the managed-region invariant every
+    // other code path relies on unstable across repeated runs) is about
+    // to declare it again, and TOML forbids a duplicate top-level key
+    // regardless of whether the two values agree. A DIFFERING value is
+    // named in `restoredScalars` — adl's own value always wins.
+    const presentKeys = new Set(Object.keys(scalarValues).filter((key) => Object.prototype.hasOwnProperty.call(parsedCurrent, key)));
+    const restoredScalars: RestoredScalar[] = [...presentKeys]
+      .filter((key) => !tomlValueMatches(parsedCurrent[key], scalarValues[key]))
+      .map((key) => ({ key, value: scalarValues[key], previous: parsedCurrent[key] }));
+    const restOfFile = removeTopLevelScalarLines(currentText, presentKeys).replace(/^\n+/, '');
+
+    // Insert AT THE TOP, before any table header — always syntactically
+    // safe for valid TOML (bare key/value pairs may appear anywhere
+    // before the first table), and scalar collisions are already ruled
+    // out above.
+    let composed = restOfFile.length > 0 ? `${canonicalBlock}\n\n${restOfFile}` : `${canonicalBlock}\n`;
+
+    const arraySpan = findArray(composed, SHELL_ALLOWLIST_KEY);
+    if (arraySpan === 'malformed') {
+      return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
+    }
+    if (arraySpan === 'missing') {
+      // The user has no such array at all -- create it, with just the
+      // standard entries, right after the inserted block.
+      const arrayText = `${SHELL_ALLOWLIST_KEY} = [\n${requiredEntries.map((e) => `    "${e}",`).join('\n')}\n]\n`;
+      composed = `${canonicalBlock}\n${arrayText}\n${restOfFile}`;
+    } else {
+      const currentEntries = parseSimpleStringArrayBody(arraySpan.body);
+      if (currentEntries === 'malformed') {
+        return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
+      }
+      // Entry by entry: only the STANDARD entries missing from the
+      // user's OWN array are appended, at the end, byte-for-byte -- the
+      // user's own entries, and their order, are never touched.
+      const missingEntries = requiredEntries.filter((entry) => !currentEntries.includes(entry));
+      if (missingEntries.length > 0) composed = insertMissingEntries(composed, arraySpan, missingEntries);
+    }
+
+    const invalid = validateComposedToml(composed, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
+    if (invalid !== undefined) return { action: 'conflict', reason: `cannot merge safely: ${invalid}` };
+    return restoredScalars.length > 0 ? { action: 'write', text: composed, restoredScalars } : { action: 'write', text: composed };
+  }
+
+  const duplicate = duplicateKeyOutsideRegion(working, region, canonicalBlock);
+  if (duplicate !== undefined) return { action: 'conflict', reason: `"${duplicate}" is declared both inside and outside the adl-managed block; left untouched` };
+
+  const installedBlock = working.slice(region.start, region.end);
+  if (installedBlock !== canonicalBlock) working = spliceRegion(working, region, canonicalBlock);
+
+  // Step 2: the union array, resolved fresh against the (possibly just-healed) text.
+  const currentArray = findArray(working, SHELL_ALLOWLIST_KEY);
+  if (currentArray === 'missing') return { action: 'conflict', reason: `expected "${SHELL_ALLOWLIST_KEY}" array not found` };
+  if (currentArray === 'malformed') return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array (contains something other than string literals)` };
+  const currentEntries = parseSimpleStringArrayBody(currentArray.body);
+  if (currentEntries === 'malformed') return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array (contains something other than string literals)` };
+  const missing = requiredEntries.filter((entry) => !currentEntries.includes(entry));
+  if (missing.length > 0) working = insertMissingEntries(working, currentArray, missing);
+
+  if (working === currentText) {
+    const invalid = validateComposedToml(working, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
+    if (invalid !== undefined) return { action: 'conflict', reason: invalid };
+    return { action: 'unchanged' };
+  }
+  const invalid = validateComposedToml(working, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
+  if (invalid !== undefined) return { action: 'conflict', reason: invalid };
+  return { action: 'write', text: working };
+}
+
+/** The block's own ignore-pattern lines (no markers, no comments) — what "already present" is checked against: a negation of one of these BEFORE an existing block is a conflict (round 5), and a bare duplicate of one of these OUTSIDE an existing block is ambiguous and stays a conflict too. Round 5 (Tarun, 2026-09-30) stopped using this to DROP lines during migration — see `resolveGitignoreWrite`'s own header for why. */
+function gitignorePatternLines(canonicalBlock: string): readonly string[] {
+  return canonicalBlock
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && l !== LEAN_CTX_MARKER_START && l !== LEAN_CTX_MARKER_END && !l.startsWith('#'));
+}
+
+/**
+ * `.agents/.gitignore` (finding 6, REDECIDED 2026-09-30 — a real repro
+ * showed the round-3 fix never actually ran: `lean-ctx-deploy.ts`'s own
+ * top-level `exists && !managedByUs` guard short-circuited to a hard
+ * conflict before this function was even called, and this function's
+ * OWN `!wasWrittenByUs` check would have refused it too). A markerless
+ * `.gitignore` is no longer a hard conflict EITHER WAY — written by adl
+ * before, or a plain user file that has simply never been touched.
+ *
+ * ROUND 5 (fourth independent review, same day) found the FIRST fix's
+ * own ordering bug: it deleted any existing line that happened to match
+ * one of adl's own patterns, then appended the canonical block at the
+ * END. A user's `*.bak` (redundant with adl's own pattern) followed by
+ * their OWN deliberate `!keep.bak` override got the `*.bak` line
+ * deleted, and adl's later copy of it (inside the appended block) then
+ * silently outranked `!keep.bak` — gitignore's last-match-wins rule
+ * turned the user's override backwards.
+ *
+ * DECISION (Tarun, 2026-09-30): never delete or reorder a user's own
+ * line, full stop — not even one that looks exactly like adl's own
+ * pattern (the cosmetic cost of a harmless duplicate line is strictly
+ * better than ever risking a real one). For a markerless file, the
+ * canonical block is PREPENDED instead of appended: every existing line
+ * (all of them, unmodified, in their original order) then comes AFTER
+ * the block and keeps winning, including any negation — exactly
+ * gitignore's own "last match wins" semantics, by construction, with no
+ * special-casing needed for negations in this branch at all (a
+ * pre-existing negation is now IMPOSSIBLE to place before the block,
+ * since the block is always first).
+ *
+ * For an EXISTING marked file, the block never moves from wherever it
+ * already sits — but a NEW negation added BEFORE it (which the block's
+ * own later copy of that pattern would silently override) is its own
+ * conflict, reported rather than silently accepted. A negation added
+ * AFTER the block already wins correctly and is not a conflict.
+ *
+ * The "bare duplicate outside the block" check (below) is scoped to
+ * BEFORE the block only — found while verifying this very fix against
+ * this repo's own REAL data, not asked for by name: a markerless
+ * migration keeps every existing line, including ones that happen to be
+ * adl's own canonical patterns (this repo's own actual pre-marker
+ * `.agents/.gitignore` is exactly that shape), and those necessarily end
+ * up AFTER the newly-prepended block. A duplicate AFTER the block is
+ * provably inert (gitignore's last-match-wins rule makes a trailing
+ * repeat of the same pattern a no-op), so checking it unscoped turned
+ * every such migration into a conflict on EVERY subsequent deploy
+ * forever. A duplicate BEFORE the block is the one that still matters:
+ * it is exactly the negation risk above, generalized to a bare
+ * (non-negated) repeat that could still be reordered or edited later in
+ * a way the block's own later copy would silently shadow.
+ */
+export function resolveGitignoreWrite(assetText: string, currentText: string, _wasWrittenByUs: boolean): LeanCtxWriteOutcome {
+  const canonicalBlock = canonicalBlockOf(assetText);
+  const region = findRegion(currentText);
+  if (region === 'malformed') return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
+
+  const patternLines = new Set(gitignorePatternLines(canonicalBlock));
+
+  if (region === 'missing') {
+    const trimmed = currentText.replace(/\n+$/, '');
+    return { action: 'write', text: trimmed.length > 0 ? `${canonicalBlock}\n\n${trimmed}\n` : `${canonicalBlock}\n` };
+  }
+
+  const beforeLines = new Set(
+    currentText
+      .slice(0, region.start)
+      .split('\n')
+      .map((l) => l.trim()),
+  );
+  for (const pattern of patternLines) {
+    if (beforeLines.has(`!${pattern}`)) {
+      return { action: 'conflict', reason: `"!${pattern}" appears before the managed block and would be silently overridden by the block's own later "${pattern}"; left untouched` };
+    }
+    if (beforeLines.has(pattern)) {
+      return { action: 'conflict', reason: `"${pattern}" already appears before the managed block; left untouched` };
+    }
+  }
+
+  const installed = currentText.slice(region.start, region.end);
+  if (installed === canonicalBlock) return { action: 'unchanged' };
+  return { action: 'write', text: spliceRegion(currentText, region, canonicalBlock) };
+}

package/packages/agent-settings/src/deploy/lock.ts

@@ -89,10 +89,13 @@ export function readLock(targetRepo: string): SettingsLock {
   };
 }
 
+/** Skips the write entirely when the serialized content is already byte-identical (independent review, 2026-09-29, finding 8: a genuine no-op run must not touch the lock file's mtime either). */
 export function writeLock(targetRepo: string, lock: SettingsLock): void {
   const path = lockPathFor(targetRepo);
+  const next = `${JSON.stringify({ schema: LOCK_SCHEMA, mcp: lock.mcp, agents: lock.agents, leanCtx: lock.leanCtx }, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, "utf8") === next) return;
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify({ schema: LOCK_SCHEMA, mcp: lock.mcp, agents: lock.agents, leanCtx: lock.leanCtx }, null, 2)}\n`);
+  writeFileSync(path, next);
 }
 
 /** True iff the lock records `serverName` as owned in `file`'s json-merge entry. */

package/packages/agent-settings/src/deploy/mcp-deploy.ts

@@ -36,6 +36,8 @@ export interface DeployMcpOptions {
   readonly profile?: DeployProfile;
   /** Defaults to loading `profile.mcp.source` relative to the package root. */
   readonly servers?: readonly McpServerSpec[];
+  /** Computes the exact same written/unchanged/conflicts result without writing anything (independent review, 2026-09-29, finding 6). */
+  readonly dryRun?: boolean;
 }
 
 export interface McpFileConflict {
@@ -65,8 +67,8 @@ function readExistingJson(path: string): Record<string, unknown> | undefined {
   return doc as Record<string, unknown>;
 }
 
-function writeIfChanged(path: string, content: string, changed: boolean): void {
-  if (!changed) return;
+function writeIfChanged(path: string, content: string, changed: boolean, dryRun: boolean): void {
+  if (!changed || dryRun) return;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, content);
 }
@@ -77,6 +79,7 @@ function serializeJsonStyle(jsonStyle: "width-aware" | "expanded", value: Record
 
 export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
   const { targetRepo } = options;
+  const dryRun = options.dryRun === true;
   if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
     throw new Error(`deploy target is not a directory: ${targetRepo}`);
   }
@@ -118,7 +121,7 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
 
       const rendered = renderCodexManagedBlock(servers, marker, surface.tableKey as string, surface.entry, allowedTopLevel);
       const { fileContent, changed } = mergeCodexBlock(existingText, rendered);
-      writeIfChanged(targetAbs, fileContent, changed);
+      writeIfChanged(targetAbs, fileContent, changed, dryRun);
       (changed ? written : unchanged).push(surface.file);
       newMcpEntries[surface.file] = { kind: "block", owned: true };
       // The managed block is always regenerated (M3) regardless of prior
@@ -147,12 +150,12 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
     const { fileContent, ownedServers, conflicts: serverConflicts, changed } = mergeServerMap(existingRaw, topKey, desired, effectivePreviousOwned);
     for (const c of serverConflicts) conflicts.push({ file: surface.file, server: c.server, reason: c.reason });
 
-    writeIfChanged(targetAbs, `${serializeJsonStyle(surface.jsonStyle as "width-aware" | "expanded", fileContent)}\n`, changed);
+    writeIfChanged(targetAbs, `${serializeJsonStyle(surface.jsonStyle as "width-aware" | "expanded", fileContent)}\n`, changed, dryRun);
     (changed ? written : unchanged).push(surface.file);
     newMcpEntries[surface.file] = { kind: "json", servers: ownedServers };
   }
 
-  writeLock(targetRepo, { schema: 1, mcp: newMcpEntries, agents: lock.agents, leanCtx: lock.leanCtx });
+  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: newMcpEntries, agents: lock.agents, leanCtx: lock.leanCtx });
 
   // Once anything was actually taken over, this package's own footprint in
   // the legacy lock (the four MCP `merged` sections and the codex `toml`
@@ -160,7 +163,7 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
   // .agents/agent-settings.lock.json just written above. A legacy lock
   // present but untouched by any takeover (no hash matched, or this repo
   // never had one) is left exactly as found.
-  if (anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
+  if (!dryRun && anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
     stripLegacyOwnership(legacyDoc, legacyLockPath, { mergedEntries: legacyMergedRemovals, toml: legacyTomlRemovals });
   }