@ngockhoale/ukit 3.4.31 → 3.4.33

package/src/core/ompProjectConfig.js

@@ -0,0 +1,462 @@
+import YAML, { Alias, Pair, Scalar, YAMLMap, YAMLSeq, parseDocument } from 'yaml';
+
+// OMP project config lifecycle (.omp/config.yml compaction block) — pure text
+// module, no fs. Callers own reading/writing files and persisting the ownership
+// record in install.json.
+//
+// mergeOmpProjectConfig(existingText, defaultsText, ownership):
+//   Surgically adds missing `compaction` defaults using yaml CST ranges so every
+//   other byte (comments, BOM, CRLF, unrelated keys) survives untouched. The
+//   only value ever REWRITTEN is a legacy `thresholdTokens: 350000`, and only
+//   when the ownership record proves ukit itself installed that same value
+//   (ownership.installedText parses to the same thresholdTokens). Everything
+//   else the user set stays.
+//
+// cleanupOmpProjectConfig(currentText, ownership):
+//   Uninstall counterpart. Unchanged file → restore originalText (delete, i.e.
+//   text null, when the file was fresh). User-edited file → keep every user
+//   modification and only remove/revert the owned scalar compaction keys that
+//   still carry the installed value AND were originally absent or different.
+//
+// Conservative no-write: if the compaction subtree uses flow collections,
+// anchors, aliases or merge keys (`<<`), the functions refuse to splice and
+// return the original text plus a warning — surgical edits are only proven
+// safe on plain block mappings. Invalid YAML throws instead.
+
+// The scalar compaction keys ukit owns and may remove on cleanup. Extra keys
+// the user added under compaction are never owned, only these four.
+export const OWNED_COMPACTION_KEYS = ['enabled', 'thresholdTokens', 'midTurnEnabled', 'keepRecentTokens'];
+
+// Pre-90000 ukit default. Migrating it requires ownership proof; a hand-set
+// 350000 (no ownership record, or installedText disagrees) is preserved.
+export const LEGACY_THRESHOLD_TOKENS = 350000;
+
+const COMPACTION_KEY = 'compaction';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function firstError(doc) {
+  return doc.errors[0]?.message ?? 'unknown parse error';
+}
+
+// parseDocument keeps CST ranges pointing into the ORIGINAL string (BOM
+// inclusive), which is what makes byte-exact splicing possible. Parse errors
+// are collected on the document instead of thrown, so we reject them here.
+function parseDocOrThrow(text, label) {
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) {
+    throw new Error(`${label}: invalid YAML — ${firstError(doc)}`);
+  }
+  return doc;
+}
+
+function parseDataOrThrow(text, label) {
+  try {
+    return YAML.parse(text);
+  } catch (error) {
+    throw new Error(`${label}: invalid YAML — ${error?.message ?? error}`);
+  }
+}
+
+function detectEol(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+// Render a value the way it is spliced into the document: block YAML, trailing
+// newline trimmed. Scalars render single-line; collections render nested lines.
+function formatYamlValue(value) {
+  return YAML.stringify(value).replace(/\n+$/, '');
+}
+
+function lineStartBefore(text, offset) {
+  const i = text.lastIndexOf('\n', Math.max(offset - 1, 0));
+  return i + 1;
+}
+
+// Index just past the newline that terminates the line containing `offset`
+// (or text length at EOF without a trailing newline).
+function lineEndAfter(text, offset) {
+  const i = text.indexOf('\n', offset);
+  return i === -1 ? text.length : i + 1;
+}
+
+function indentOfLine(text, offset) {
+  const start = lineStartBefore(text, offset);
+  const match = /^[ ]*/.exec(text.slice(start));
+  return match ? match[0] : '';
+}
+
+function findCompactionPair(mapNode) {
+  return mapNode.items.find(
+    (pair) => pair.key instanceof Scalar && pair.key.value === COMPACTION_KEY,
+  );
+}
+
+// Reason string when the subtree carries a construct we refuse to edit
+// surgically: flow collections, anchors, aliases, merge keys.
+function unsafeReason(node, depth = 0) {
+  if (!node || depth > 64) return null;
+  if (node instanceof Alias) return 'an alias';
+  if (node.anchor) return 'an anchor';
+  if (node instanceof YAMLMap || node instanceof YAMLSeq) {
+    if (node.flow) return 'flow style';
+    for (const item of node.items) {
+      if (item instanceof Pair) {
+        if (item.key instanceof Scalar && item.key.value === '<<') return 'a merge key';
+        const reason = unsafeReason(item.key, depth + 1) ?? unsafeReason(item.value, depth + 1);
+        if (reason) return reason;
+      } else {
+        const reason = unsafeReason(item, depth + 1);
+        if (reason) return reason;
+      }
+    }
+  }
+  return null;
+}
+
+function noWrite(text, ownership, warning) {
+  return { text, ownership: ownership ?? null, warning };
+}
+
+function applyEdits(text, edits) {
+  let out = text;
+  for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, edit.start) + edit.replacement + out.slice(edit.end);
+  }
+  return out;
+}
+
+// One `key: value` line (or block for collection values) at the given indent.
+function renderEntry(key, value, indent, eol) {
+  const parts = formatYamlValue(value).split('\n');
+  const lines = [`${indent}${key}: ${parts[0]}`, ...parts.slice(1).map((line) => (line === '' ? '' : indent + line))];
+  return lines.join(eol);
+}
+
+// Edit appending the full compaction block at end of file.
+function appendBlockEdit(text, compaction, eol) {
+  const lines = [
+    `${COMPACTION_KEY}:`,
+    ...Object.entries(compaction).map(([k, v]) => renderEntry(k, v, '  ', eol)),
+  ];
+  const prefix = text.length > 0 && !text.endsWith('\n') ? eol : '';
+  return { start: text.length, end: text.length, replacement: prefix + lines.join(eol) + eol };
+}
+
+// Edit inserting entries after the compaction map's last item (or right after
+// the `compaction:` line when the map is empty), matching existing indent.
+function insertEntriesEdit(text, pair, entries, eol) {
+  const map = pair.value;
+  let insertAt;
+  let indent;
+  if (map.items.length > 0) {
+    insertAt = map.range[1];
+    indent = indentOfLine(text, map.range[0]);
+  } else {
+    insertAt = lineEndAfter(text, pair.key.range[0]);
+    indent = `${indentOfLine(text, pair.key.range[0])}  `;
+  }
+  const lines = entries.map(([k, v]) => renderEntry(k, v, indent, eol));
+  // When the insertion point does not start a fresh line (EOF without a
+  // trailing newline), open one first.
+  const prefix = insertAt > 0 && text[insertAt - 1] !== '\n' ? eol : '';
+  return { start: insertAt, end: insertAt, replacement: prefix + lines.join(eol) + eol };
+}
+
+// Proof that ukit itself installed `value` as compaction.thresholdTokens: the
+// ownership record's installedText (latest content ukit ensured) must parse to
+// that same value.
+function ownershipProvesThreshold(ownership, value) {
+  if (!isPlainObject(ownership) || typeof ownership.installedText !== 'string') return false;
+  try {
+    const data = YAML.parse(ownership.installedText);
+    return isPlainObject(data?.compaction) && data.compaction.thresholdTokens === value;
+  } catch {
+    return false;
+  }
+}
+
+export function mergeOmpProjectConfig(existingText, defaultsText, ownership) {
+  if (typeof defaultsText !== 'string') {
+    throw new TypeError('mergeOmpProjectConfig: defaultsText must be a string');
+  }
+  if (existingText != null && typeof existingText !== 'string') {
+    throw new TypeError('mergeOmpProjectConfig: existingText must be a string or null');
+  }
+
+  const defaultsData = parseDataOrThrow(defaultsText, 'defaultsText');
+  const defaultsCompaction = defaultsData?.compaction;
+  if (!isPlainObject(defaultsCompaction)) {
+    throw new Error('defaultsText: must define a top-level `compaction` mapping');
+  }
+
+  // Fresh install — nothing to preserve; the defaults text ships verbatim.
+  if (existingText == null) {
+    return {
+      text: defaultsText,
+      ownership: { originalText: null, installedText: defaultsText },
+      warning: null,
+    };
+  }
+
+  const doc = parseDocOrThrow(existingText, 'existing omp project config');
+
+  // Empty file: appending the block keeps it valid YAML, so treat it as
+  // "no compaction" rather than refusing.
+  if (doc.contents != null && !(doc.contents instanceof YAMLMap)) {
+    return noWrite(existingText, ownership, 'merge skipped: top-level YAML document is not a mapping');
+  }
+  const pair = doc.contents ? findCompactionPair(doc.contents) : undefined;
+  const eol = detectEol(existingText);
+  const edits = [];
+  let warning = null;
+
+  if (!pair) {
+    edits.push(appendBlockEdit(existingText, defaultsCompaction, eol));
+  } else {
+    const unsafe = unsafeReason(pair.key) ?? unsafeReason(pair.value);
+    if (unsafe) {
+      return noWrite(existingText, ownership, `merge skipped: compaction uses ${unsafe} — surgical edit refused`);
+    }
+    if (!(pair.value instanceof YAMLMap)) {
+      return noWrite(existingText, ownership, 'merge skipped: compaction is not a block mapping');
+    }
+
+    const missing = [];
+    for (const [defaultKey, defaultValue] of Object.entries(defaultsCompaction)) {
+      const existingPair = pair.value.items.find(
+        (item) => item.key instanceof Scalar && item.key.value === defaultKey,
+      );
+      if (!existingPair) {
+        // Missing key: added. Present keys are user state and never touched
+        // (with the single legacy exception below).
+        missing.push([defaultKey, defaultValue]);
+        continue;
+      }
+      if (
+        defaultKey === 'thresholdTokens' &&
+        existingPair.value instanceof Scalar &&
+        existingPair.value.value === LEGACY_THRESHOLD_TOKENS &&
+        defaultValue !== LEGACY_THRESHOLD_TOKENS
+      ) {
+        if (ownershipProvesThreshold(ownership, LEGACY_THRESHOLD_TOKENS)) {
+          edits.push({
+            start: existingPair.value.range[0],
+            end: existingPair.value.range[1],
+            replacement: formatYamlValue(defaultValue),
+          });
+        } else {
+          // Unknown old config: ukit cannot prove 350000 was installed, so the
+          // value may be deliberate — preserved with a warning.
+          warning = `compaction.thresholdTokens=${LEGACY_THRESHOLD_TOKENS} kept — ownership does not prove ukit installed this value (legacy migration skipped)`;
+        }
+      }
+    }
+    if (missing.length > 0) {
+      edits.push(insertEntriesEdit(existingText, pair, missing, eol));
+    }
+  }
+
+  const text = applyEdits(existingText, edits);
+  const changed = text !== existingText;
+  return {
+    text,
+    ownership: {
+      // originalText is recorded exactly once — the first merge that sees the
+      // file captures it; later merges keep the original provenance.
+      originalText: isPlainObject(ownership) && 'originalText' in ownership ? ownership.originalText : existingText,
+      // installedText always reflects the latest content this module ensured.
+      installedText: changed ? text : isPlainObject(ownership) && ownership.installedText != null ? ownership.installedText : text,
+    },
+    warning,
+  };
+}
+
+function sameValue(a, b) {
+  return a === b;
+}
+
+function originalCompactionOf(ownership) {
+  if (!isPlainObject(ownership) || typeof ownership.originalText !== 'string') return null;
+  try {
+    const data = YAML.parse(ownership.originalText);
+    return isPlainObject(data?.compaction) ? data.compaction : null;
+  } catch {
+    // Unparseable original: no per-key provenance — owned keys are treated as
+    // originally absent (they are only removed when they still match what
+    // ukit installed, so user values remain safe either way).
+    return null;
+  }
+}
+
+function cleanupCompaction(currentText, ownership) {
+  if (currentText == null) {
+    return { text: null, ownership: ownership ?? null, warning: null };
+  }
+  if (typeof currentText !== 'string') {
+    throw new TypeError('cleanupOmpProjectConfig: currentText must be a string or null');
+  }
+  if (!isPlainObject(ownership)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: no ownership record — cannot prove which settings ukit installed');
+  }
+  if (typeof ownership.installedText !== 'string') {
+    return noWrite(currentText, ownership, 'cleanup skipped: ownership record has no installedText');
+  }
+
+  // Unchanged since install: hand the file back exactly as ukit found it
+  // (null = the file did not exist before ukit created it → delete).
+  if (currentText === ownership.installedText) {
+    return { text: ownership.originalText ?? null, ownership, warning: null };
+  }
+
+  // User edited the file: keep every modification, surgically remove/revert
+  // only what ukit owns.
+  const doc = parseDocOrThrow(currentText, 'current omp project config');
+  if (!(doc.contents instanceof YAMLMap)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: top-level YAML document is not a mapping');
+  }
+  const pair = findCompactionPair(doc.contents);
+  if (!pair) {
+    return { text: currentText, ownership, warning: null };
+  }
+  const unsafe = unsafeReason(pair.key) ?? unsafeReason(pair.value);
+  if (unsafe) {
+    return noWrite(currentText, ownership, `cleanup skipped: compaction uses ${unsafe} — surgical edit refused`);
+  }
+  if (!(pair.value instanceof YAMLMap)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: compaction is not a block mapping');
+  }
+
+  let installedCompaction;
+  try {
+    const data = YAML.parse(ownership.installedText);
+    if (!isPlainObject(data?.compaction)) {
+      return noWrite(currentText, ownership, 'cleanup skipped: installedText has no compaction mapping');
+    }
+    installedCompaction = data.compaction;
+  } catch (error) {
+    return noWrite(currentText, ownership, `cleanup skipped: installedText is not valid YAML — ${error?.message ?? error}`);
+  }
+
+  const originalCompaction = originalCompactionOf(ownership);
+  const eol = detectEol(currentText);
+  const edits = [];
+  let removedCount = 0;
+
+  for (const key of OWNED_COMPACTION_KEYS) {
+    if (!(key in installedCompaction)) continue;
+    const ownedPair = pair.value.items.find(
+      (item) => item.key instanceof Scalar && item.key.value === key,
+    );
+    if (!ownedPair || !(ownedPair.value instanceof Scalar)) continue;
+
+    const installedValue = installedCompaction[key];
+    if (!sameValue(ownedPair.value.value, installedValue)) continue; // user changed it — keep
+
+    const hasOriginal = originalCompaction !== null && key in originalCompaction;
+    if (!hasOriginal) {
+      // ukit added this key (fresh file or key absent pre-install): remove the
+      // whole line — from line start (node ranges begin after the indent) to
+      // the end of the value's line, including any trailing comment/break.
+      const start = lineStartBefore(currentText, ownedPair.key.range[0]);
+      const end = Math.max(ownedPair.value.range[2], lineEndAfter(currentText, ownedPair.value.range[1]));
+      edits.push({ start, end, replacement: '' });
+      removedCount += 1;
+    } else if (!sameValue(originalCompaction[key], installedValue)) {
+      // ukit changed a pre-existing value: restore the original one in place.
+      edits.push({
+        start: ownedPair.value.range[0],
+        end: ownedPair.value.range[1],
+        replacement: formatYamlValue(originalCompaction[key]),
+      });
+    }
+    // Originally present with the installed value: ukit never altered it — keep.
+  }
+
+  // If every remaining compaction entry was ukit-added and got removed, the
+  // `compaction:` parent line goes too (fresh files end up compaction-free
+  // again). Only the key's own line is removed — the child lines above were
+  // spliced by their own edits, and the map's range end already sits past the
+  // last child's newline, so extending further would swallow foreign lines.
+  if (removedCount > 0 && removedCount === pair.value.items.length) {
+    edits.push({
+      start: lineStartBefore(currentText, pair.key.range[0]),
+      end: lineEndAfter(currentText, pair.key.range[0]),
+      replacement: '',
+    });
+  }
+
+  if (edits.length === 0) {
+    return { text: currentText, ownership, warning: null };
+  }
+  return { text: applyEdits(currentText, edits), ownership, warning: null };
+}
+
+// --- task.agentCompactionThresholdOverrides (per-agent soft compaction targets) ---
+// Same ownership rule as the compaction keys: an agent entry is removed (or restored)
+// only when it still carries the value UKit installed; user-set values and every other
+// `task` key stay. Empty parents UKit created are removed with their last child.
+function taskOverridesOf(text) {
+  try {
+    const data = YAML.parse(text);
+    const map = data?.task?.agentCompactionThresholdOverrides;
+    return isPlainObject(map) ? map : null;
+  } catch {
+    return null;
+  }
+}
+
+function cleanupTaskOverrides(currentText, ownership) {
+  const installed = taskOverridesOf(ownership.installedText);
+  if (!installed) return currentText;
+  let doc;
+  try {
+    doc = parseDocOrThrow(currentText, 'current omp project config');
+  } catch {
+    return currentText;
+  }
+  if (!(doc.contents instanceof YAMLMap)) return currentText;
+  const taskPair = doc.contents.items.find((p) => p.key instanceof Scalar && p.key.value === 'task');
+  if (!taskPair || !(taskPair.value instanceof YAMLMap) || unsafeReason(taskPair)) return currentText;
+  const ovPair = taskPair.value.items.find((p) => p.key instanceof Scalar && p.key.value === 'agentCompactionThresholdOverrides');
+  if (!ovPair || !(ovPair.value instanceof YAMLMap)) return currentText;
+  const original = taskOverridesOf(typeof ownership.originalText === 'string' ? ownership.originalText : '') ?? {};
+  const edits = [];
+  let removed = 0;
+  for (const [agent, value] of Object.entries(installed)) {
+    const entry = ovPair.value.items.find((p) => p.key instanceof Scalar && p.key.value === agent);
+    if (!entry || !(entry.value instanceof Scalar) || entry.value.value !== value) continue;
+    if (!(agent in original)) {
+      const start = lineStartBefore(currentText, entry.key.range[0]);
+      const end = Math.max(entry.value.range[2], lineEndAfter(currentText, entry.value.range[1]));
+      edits.push({ start, end, replacement: '' });
+      removed += 1;
+    } else if (original[agent] !== value) {
+      edits.push({ start: entry.value.range[0], end: entry.value.range[1], replacement: formatYamlValue(original[agent]) });
+    }
+  }
+  if (removed > 0 && removed === ovPair.value.items.length) {
+    edits.push({ start: lineStartBefore(currentText, ovPair.key.range[0]), end: lineEndAfter(currentText, ovPair.key.range[0]), replacement: '' });
+    if (taskPair.value.items.length === 1) {
+      edits.push({ start: lineStartBefore(currentText, taskPair.key.range[0]), end: lineEndAfter(currentText, taskPair.key.range[0]), replacement: '' });
+    }
+  }
+  return edits.length > 0 ? applyEdits(currentText, edits) : currentText;
+}
+
+export function cleanupOmpProjectConfig(currentText, ownership) {
+  const result = cleanupCompaction(currentText, ownership);
+  if (
+    typeof currentText !== 'string'
+    || !isPlainObject(ownership)
+    || typeof ownership.installedText !== 'string'
+    || currentText === ownership.installedText
+    || typeof result.text !== 'string'
+  ) {
+    return result;
+  }
+  const text = cleanupTaskOverrides(result.text, ownership);
+  return text === result.text ? result : { ...result, text };
+}

package/src/core/runInstallPipeline.js

@@ -432,7 +432,14 @@ export async function runInstallPipeline({
     });
   }
 
-  const diffResults = await diffInstallPlan(plan);
+  // Ownership proof for .omp/config.yml: the ledger record, or — for installs that
+  // predate it — a synthetic proof that UKit shipped the legacy 350000 default
+  // (only when UKit tracked the file). Never touches the user's other values.
+  const trackedOmpConfig = (Array.isArray(installMetaData?.files) ? installMetaData.files : [])
+    .some((e) => (typeof e === 'string' ? e : e?.p) === '.omp/config.yml');
+  const ompOwnership = installMetaData?.ompConfigOwnership
+    ?? (trackedOmpConfig ? { originalText: null, installedText: 'compaction:\n  thresholdTokens: 350000\n' } : null);
+  const diffResults = await diffInstallPlan(plan, { ompOwnership });
   const plannedSummary = summarizeDiff(diffResults);
 
   if (!dryRun) {
@@ -441,6 +448,22 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
     });
 
+    for (const entry of diffResults) {
+      const parseError = entry?.migrationReport?.parseError;
+      if (!parseError || !/\.omp\/config\.yml$/.test(String(entry.targetPath).replace(/\\/g, '/'))) continue;
+      console.warn(`[UKit] Warning: .omp/config.yml was left untouched (cannot merge: ${parseError}). Fix the YAML and rerun \`ukit install\` to apply UKit's OMP settings.`);
+    }
+
+    let ompConfigOwnership = null;
+    for (const entry of diffResults) {
+      if (!entry.ompOwnership) continue;
+      if (entry.ompOwnershipWarning) console.warn(`[UKit] .omp/config.yml: ${entry.ompOwnershipWarning}`);
+      if (entry.action === 'create' || entry.action === 'update' || entry.action === 'unchanged') {
+        const written = writes.some((w) => w.targetPath === entry.targetPath);
+        if (written || entry.action === 'unchanged') ompConfigOwnership = entry.ompOwnership;
+      }
+    }
+
     // SPEC §7 step 9: surface the .omp/config.yml unattended migration result.
     for (const entry of diffResults) {
       const report = entry?.migrationReport;
@@ -522,6 +545,7 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
       managedRelativePaths: [...trackedManagedRelativePaths],
       retainedManagedRelativePaths,
+      ompConfigOwnership,
     });
 
     // 3.3.0: hooks spawn the CLI (episodes, self-improve) from a GUI-launched

package/src/core/uninstall.js

@@ -9,6 +9,7 @@ import {
   resolveProjectRelativePath,
 } from './fileOps.js';
 import { readInstallMetadata } from './metadata.js';
+import { cleanupOmpProjectConfig } from './ompProjectConfig.js';
 import { removeGitignoreBlock } from './ensureGitignore.js';
 import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
 
@@ -424,6 +425,29 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
   }
 
 
+  // .omp/config.yml is user-shared: revert only what UKit owns instead of deleting it.
+  const ompConfigAbs = path.join(projectRoot, '.omp', 'config.yml');
+  let ompConfigRewrite = null;
+  const ompIdx = regularPaths.findIndex((p) => p.abs === ompConfigAbs);
+  if (ompIdx !== -1) {
+    const currentText = await fs.readFile(ompConfigAbs, 'utf8').catch(() => null);
+    if (currentText !== null) {
+      let outcome;
+      try {
+        outcome = cleanupOmpProjectConfig(currentText, installData.ompConfigOwnership ?? null);
+      } catch (error) {
+        outcome = { text: currentText, warning: `cleanup skipped: ${error?.message ?? error}` };
+      }
+      if (outcome.warning) {
+        console.warn(`[UKit] .omp/config.yml kept: ${outcome.warning}`);
+      }
+      if (outcome.text !== null) {
+        regularPaths.splice(ompIdx, 1); // not deleted: rewritten (or kept) below
+        if (outcome.text !== currentText) ompConfigRewrite = outcome.text;
+      }
+    }
+  }
+
   const allEntries = [
     ...regularPaths.map(({ abs, recursive }) => ({ abs, useLink: false, recursive })),
     ...linkPaths.map((abs) => ({ abs, useLink: true, recursive: false })),
@@ -485,7 +509,10 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     backupPaths.push(importantPlan.backupPath); // existing byte-identical backup
   }
 
-  // Remove all paths in parallel
+  if (ompConfigRewrite !== null) {
+    await fs.writeFile(ompConfigAbs, ompConfigRewrite, 'utf8');
+  }
+
   // Remove all paths in parallel. Tracked file entries use removeFileOrLinkOnly:
   // a real directory at a tracked path is user content (the user replaced the
   // managed file) and is refused — same protection link entries already had.

package/src/decision/reviewVerdict.js

@@ -135,7 +135,7 @@ function stableBatchId(findings) {
  *            findings: object[], verdictDecisionKey: string}}
  *          Never throws — garbage input sanitizes to an empty finding list.
  */
-export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
+export function buildReviewVerdictBatch({ findings = [], mode = 'solo', maxQuestions = Infinity } = {}) {
   const usedIds = new Set();
   // Sanitize the FULL finding set — MAX_FINDINGS is a display/transport bound
   // for the batch, not a verdict bound. The deterministic verdict and the
@@ -145,6 +145,19 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
   const batchFindings = sanitized.slice(0, MAX_FINDINGS);
   const truncated = sanitized.length > batchFindings.length;
 
+  // Request-cap handling (no extra call): when verdict + one bucket question per
+  // finding would exceed `maxQuestions`, ask only findings whose bucket the model
+  // can actually change. `Act on` is a deterministic floor the model cannot
+  // lower, so critical/important/unknown findings carry no semantic value in the
+  // batch; the rest keep their deterministic bucket and are reported as skipped.
+  const slots = Number.isInteger(maxQuestions) && maxQuestions > 0
+    ? maxQuestions - 1 : Infinity;
+  const askedFindings = batchFindings.length <= slots
+    ? batchFindings
+    : batchFindings.filter((f) => deriveDeterministicBucket(f) !== 'Act on').slice(0, slots);
+  const askedIds = new Set(askedFindings.map((f) => f.id));
+  const skippedFindingIds = batchFindings.filter((f) => !askedIds.has(f.id)).map((f) => f.id);
+
   const verdictDecisionKey = mode === 'panel'
     ? REVIEW_VERDICT_KEYS.panel
     : REVIEW_VERDICT_KEYS.solo;
@@ -169,7 +182,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
   // One bucket question per finding. The shared registered key cannot repeat
   // in one batch (name-based reconciliation), so each wire name carries
   // `#<findingId>`; parseVerdictAnswer splits it back off.
-  const bucketQuestions = batchFindings.map((f) => ({
+  const bucketQuestions = askedFindings.map((f) => ({
     decisionKey: `${REVIEW_VERDICT_KEYS.bucket}#${f.id}`,
     schemaVersion: 1,
     family: 'review',
@@ -207,6 +220,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
     findings: batchFindings,
     fullFindings: sanitized,
     truncated,
+    skippedFindingIds,
     verdictDecisionKey,
   };
 }

package/src/index/fixLoopEscalation.js

@@ -394,14 +394,20 @@ export async function applyFixLoopEscalation({
     : null;
   // A model lane that refuses to deepen is not an escalation answer — the
   // deterministic deeper lane wins so the loop actually exits its lane.
-  const usableModelLane = modelLane && modelLane !== currentLane ? modelLane : null;
-  const lane = usableModelLane ?? deterministicLane;
+  // Lanes are capabilities, not an ordinal ladder. Without a validated policy
+  // relation only the deterministic destination is admissible.
+  const usableModelLane = planeStage !== 'shadow' && modelLane === deterministicLane
+    ? modelLane : null;
+  const lane = deterministicLane;
   const endpointDown = batchResult !== null
     && batchResult.status !== 'accepted'
     && batchResult.status !== 'partial'
     && !usableModelLane;
-  const depth = (modelDepth && modelDepth !== 'none' ? modelDepth : null)
-    ?? resolveEscalationVerificationDepth({ routeSummary, config });
+  const depthFloor = resolveEscalationVerificationDepth({ routeSummary, config });
+  const depthOrder = ['none', 'runnable', 'review-round', 'escalate'];
+  const depth = planeStage !== 'shadow'
+    && depthOrder.indexOf(modelDepth) > depthOrder.indexOf(depthFloor)
+    ? modelDepth : depthFloor;
 
   const reason = [
     `fix-loop: fixLoopCount=${fixLoopCount} threshold=${settings.debugLoopThreshold} fingerprint-joined`,

package/src/render/buildVariables.js

@@ -1,5 +1,8 @@
 import { loadShippedCompactBudget } from '../core/compact/contextBudget.js';
 
+// Starting omp compaction threshold; capped by the shared auto-compact window above.
+const OMP_COMPACTION_THRESHOLD_TOKENS = 90_000;
+
 const CODEGRAPH_SECTION = `
 ## CodeGraph Integration (active)
 
@@ -76,6 +79,7 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
     },
     omp: {
       evalApproval,
+      compactionThresholdTokens: String(Math.min(OMP_COMPACTION_THRESHOLD_TOKENS, autoCompactWindow)),
     },
     codegraphSection: withCodegraph ? CODEGRAPH_SECTION : '',
   };