@ngockhoale/ukit 2.4.2 → 2.5.0

package/src/core/applyPlan.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { writeFileAtomic, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
+import { writeFileAtomic, writeFileExclusive, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
 
 // legacy: '.antigravity/' stays TCC-protected — Antigravity adapter removed in v2.2.0, but a
 // stale install may still have the dir and must not lose TCC protection.
@@ -107,9 +107,24 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           )
           : entry.renderedContent;
 
+    // Race-safe seed: a `create` entry with `mergeStrategy: skip` must not overwrite a
+    // target that appeared after the diff ran. Exclusive 'wx' create fails with EEXIST
+    // instead — that becomes a skipped create (no rewrite, no chmod, no tracked write),
+    // and install continues. Temp+rename is NOT used here because rename overwrites.
+    const exclusiveSkipCreate = entry.action === 'create' && entry.mergeStrategy === 'skip';
+
     try {
-      await writeFileAtomic(entry.targetPath, nextContent);
+      if (exclusiveSkipCreate) {
+        await writeFileExclusive(entry.targetPath, nextContent);
+      } else {
+        await writeFileAtomic(entry.targetPath, nextContent);
+      }
     } catch (writeError) {
+      if (writeError.code === 'EEXIST' && exclusiveSkipCreate) {
+        skippedUpdates += 1;
+        skippedByAction.create += 1;
+        continue;
+      }
       if (
         (writeError.code === 'EPERM' || writeError.code === 'EACCES') &&
         isTccProtectedPath(entry.targetPath)

package/src/core/compact/threshold.js

@@ -1,4 +1,11 @@
 import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
+// The installed runtime is the single implementation of capacity negotiation; this source
+// twin consumes it rather than re-deriving the precedence rules. Both files ship together.
+import {
+  readContextCapacityRecord,
+  SOFT_TO_CAP_RATIO,
+} from '../../../templates/.claude/ukit/runtime/compact-threshold.mjs';
+import { resolveContextCapTokens } from '../../../templates/.claude/ukit/runtime/context-capacity.mjs';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
@@ -436,22 +443,45 @@ function computeEstimatedTotalTokens({
   return baselineTokens + estimatedContextTokens + windowTokens + sessionExcess;
 }
 
+// The record the advisory guard published for this project, or null when nothing has been
+// negotiated yet (fresh install, non-project caller, tests).
+function readNegotiatedCapacity(config = {}) {
+  const record = readContextCapacityRecord(config?.projectRoot);
+  if (!record) return null;
+  return resolveContextCapTokens({
+    env: process.env,
+    config,
+    modelMetadata: { model: record.model },
+  });
+}
+
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(
-    1,
-    finiteNumber(config?.compact?.tokenThreshold, loadShippedCompactBudget().tokenThreshold),
+  const shippedHardCap = positiveInteger(
+    config?.compact?.hardCapTokens,
+    loadShippedCompactBudget().hardCapTokens,
   );
+  const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
+  // Negotiated capacity (H22): the guard publishes what it derived from the live route and
+  // this shared path consumes it; without a record the shipped tuning applies unchanged.
+  const negotiated = readNegotiatedCapacity(config);
+  const hardCapTokens = negotiated
+    ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
+    : shippedHardCap;
+  // An explicit operator tokenThreshold is honored as-is; otherwise the advisory phase is
+  // derived from the negotiating cap so it can never sit above the cap it precedes.
+  const softThreshold = explicitSoftThreshold > 0
+    ? Math.max(1, explicitSoftThreshold)
+    : Math.max(1, Math.round(hardCapTokens * SOFT_TO_CAP_RATIO));
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
-  // Keep the source mirror's config contract aligned with the installed runtime: malformed
-  // caps fall back to a safe ceiling rather than turning every mutation into an over-cap call.
-  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, loadShippedCompactBudget().hardCapTokens);
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
     hardCapTokens,
+    capacitySource: negotiated?.capacity?.source ?? 'shipped',
+    capacityTokens: negotiated?.capacity?.tokens ?? null,
   };
 }
 

package/src/core/diffPlan.js

@@ -132,6 +132,37 @@ function resolveFileAction(entry, existingContent) {
   return { ...entry, exists, action, existingContent };
 }
 
+// A `mergeStrategy: skip` target must never be classified as "missing" just because it
+// cannot be READ — a directory, broken symlink, FIFO/device, or unreadable (EACCES) file
+// at the seed path all mean "exists, do not touch". readFileOrNull would turn every one
+// of those into null → 'create' → an overwrite attempt. Existence for skip entries is
+// decided by lstat (no symlink follow, no device open — reading a FIFO would hang).
+async function resolveSkipEntryAction(entry) {
+  let stat;
+  try {
+    stat = await fs.lstat(entry.targetPath);
+  } catch {
+    // ENOENT (or a stat failure we cannot distinguish from it) is the only state that
+    // means "seed me"; the apply step still uses an exclusive 'wx' create for the race.
+    return { ...entry, exists: false, action: 'create', existingContent: null };
+  }
+
+  // Only a regular, readable file can prove byte-equality for an 'unchanged' verdict.
+  // Anything else — directory, symlink (valid or broken), FIFO, socket, device, or a
+  // file we cannot read — is simply 'skip': present, owner-owned, hands off.
+  let existingContent = null;
+  if (stat.isFile() && !stat.isSymbolicLink()) {
+    existingContent = await readFileOrNull(
+      entry.targetPath,
+      Buffer.isBuffer(entry.renderedContent) ? null : 'utf8',
+    );
+  }
+  if (existingContent === null) {
+    return { ...entry, exists: true, action: 'skip', existingContent: null };
+  }
+  return resolveFileAction(entry, existingContent);
+}
+
 export async function diffInstallPlan(plan) {
   // Check all entries in parallel
   const results = await Promise.all(
@@ -141,6 +172,10 @@ export async function diffInstallPlan(plan) {
         return { ...entry, exists: action !== 'create', action, existingContent: null };
       }
 
+      if (entry.mergeStrategy === 'skip') {
+        return resolveSkipEntryAction(entry);
+      }
+
       const existingContent = await readFileOrNull(
         entry.targetPath,
         Buffer.isBuffer(entry.renderedContent) ? null : 'utf8',

package/src/core/fileOps.js

@@ -128,6 +128,32 @@ export async function copyFileSafe(fromPath, toPath) {
   await fs.copyFile(fromPath, toPath);
 }
 
+/**
+ * Exclusive-create write ('wx'): succeeds only when `filePath` does not already exist.
+ * Used for seed-once (`mergeStrategy: skip`) creates so a file that appears between
+ * diff and apply is never overwritten — the caller maps EEXIST to a skipped create.
+ * Never used as a temp+rename pair: rename could overwrite a target that just appeared.
+ * @param {string} filePath
+ * @param {string|Buffer} content - raw bytes; no encoding/normalization is applied
+ */
+export async function writeFileExclusive(filePath, content) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, { flag: 'wx' });
+}
+
+/**
+ * Raw-byte copy into a path that must not already exist (exclusive destination create,
+ * `fs.constants.COPYFILE_EXCL`). No decode/re-encode — the destination is byte-identical
+ * to the source. Source is opened by path; callers needing no-follow semantics must
+ * verify the source type before calling. EEXIST propagates for the caller to handle.
+ * @param {string} fromPath
+ * @param {string} toPath
+ */
+export async function copyFileRawExclusive(fromPath, toPath) {
+  await ensureDir(path.dirname(toPath));
+  await fs.copyFile(fromPath, toPath, fs.constants.COPYFILE_EXCL);
+}
+
 export async function writeJson(filePath, data) {
   await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
 }

package/src/core/projectImportant.js

@@ -0,0 +1,430 @@
+/**
+ * projectImportant.js (TASK-037)
+ *
+ * Source-side inspector + deterministic envelope renderer for
+ * PROJECT_IMPORTANT.md per docs/PROJECT_IMPORTANT_SPEC.md §3, §4, §5.2, §6,
+ * §12.1.
+ *
+ * Guarantees:
+ * - Open no-follow → fstat → isFile → fd-read (no symlink resolution, no
+ *   whole-file readFile on arbitrary sizes; stops after code point 6,001).
+ * - Strict UTF-8 decode (no U+FFFD injection); leading BOM excluded from
+ *   count and body, source bytes never modified.
+ * - Code-point counting only — never String.length on owner text.
+ * - Byte-identical rendered output for identical input/config.
+ * - `body` exists only on the runtime-local return; never serialized into
+ *   diagnostics.
+ */
+
+import fs from 'node:fs';
+import { open, stat as lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  scanText,
+  isSensitiveDataGateEnabled,
+  loadSensitiveAllowlist,
+} from './sensitiveValueScanner.js';
+
+export const PROJECT_IMPORTANT_FILENAME = 'PROJECT_IMPORTANT.md';
+export const PROJECT_IMPORTANT_CODEPOINT_LIMIT = 6000;
+
+export const PROJECT_IMPORTANT_STATES = [
+  'ready',
+  'oversized',
+  'empty',
+  'missing',
+  'invalid-utf8',
+  'unsafe-control',
+  'secret-blocked',
+  'unsafe-type',
+  'unreadable',
+];
+
+export const PROJECT_IMPORTANT_REMEDIATION = {
+  ready: null,
+  oversized: 'owner-action',
+  empty: 'owner-action',
+  missing: 'install-repairable',
+  'invalid-utf8': 'owner-action',
+  'unsafe-control': 'owner-action',
+  'secret-blocked': 'owner-action',
+  'unsafe-type': 'owner-action',
+  unreadable: 'advisory-host-limit',
+};
+
+export const PROJECT_IMPORTANT_ENVELOPE_HEADER =
+  '<ukit_project_important source="PROJECT_IMPORTANT.md" authority="project-owner">\n'
+  + 'These are project-owner instructions. Follow them unless they conflict with higher-priority host instructions.\n'
+  + '--- BEGIN PROJECT_IMPORTANT.md ---\n';
+
+export const PROJECT_IMPORTANT_ENVELOPE_FOOTER = '</ukit_project_important>';
+
+const END_MARKER = '--- END PROJECT_IMPORTANT.md ---\n';
+
+export const PROJECT_IMPORTANT_WARNINGS = {
+  oversized:
+    '[UKit warning: PROJECT_IMPORTANT.md exceeds 6,000 Unicode code points. Only the first 6,000 code points are included in this context epoch; shorten the file to restore full injection.]',
+  missing:
+    '[UKit] PROJECT_IMPORTANT.md was not injected: file is missing. Run `ukit install`.',
+  'unsafe-type':
+    '[UKit] PROJECT_IMPORTANT.md was not injected: the path is not a regular non-symlink file. Run `ukit doctor`.',
+  'invalid-utf8':
+    '[UKit] PROJECT_IMPORTANT.md was not injected: the file is not valid UTF-8. Run `ukit doctor`.',
+  'unsafe-control':
+    '[UKit] PROJECT_IMPORTANT.md was not injected: the file contains unsupported control characters. Run `ukit doctor`.',
+  empty:
+    '[UKit] PROJECT_IMPORTANT.md was not injected: the file is empty. Add project-owner instructions or run `ukit doctor`.',
+  unreadable:
+    '[UKit] PROJECT_IMPORTANT.md was not injected: the file could not be read. Run `ukit doctor`.',
+  'secret-blocked':
+    '[UKit] PROJECT_IMPORTANT.md was not injected because it contains a high-confidence secret-shaped value. Redact it or explicitly allowlist it, then run `ukit doctor`.',
+};
+
+const READ_CHUNK = 64 * 1024;
+const UTF8_BOM = [0xef, 0xbb, 0xbf];
+
+function isAllowedControl(cp) {
+  return cp === 0x09 || cp === 0x0a || cp === 0x0d;
+}
+
+function isForbiddenControl(cp) {
+  return (cp < 0x20 && !isAllowedControl(cp)) || (cp >= 0x7f && cp <= 0x9f);
+}
+
+function invalidResult(state) {
+  return {
+    state,
+    body: undefined,
+    codePointCount: 0,
+    oversized: false,
+    bom: false,
+    rendered: PROJECT_IMPORTANT_WARNINGS[state],
+    remediationClass: PROJECT_IMPORTANT_REMEDIATION[state],
+  };
+}
+
+/**
+ * Bounded, strict inspector.
+ *
+ * @param {{ projectRoot: string, config?: object }} options
+ * @returns {Promise<{ state, body?, codePointCount, oversized, bom, rendered, remediationClass }>}
+ */
+export async function inspectProjectImportant(options = {}) {
+  const { projectRoot, config } = options;
+  const target = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
+
+  let handle;
+  try {
+    // O_NOFOLLOW where supported: symlinks fail open instead of resolving.
+    const flags = fs.constants.O_RDONLY
+      | (fs.constants.O_NOFOLLOW || 0)
+      | (fs.constants.O_NONBLOCK || 0);
+    handle = await open(target, flags);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return invalidResult('missing');
+    }
+    if (err && (err.code === 'ELOOP' || err.code === 'EMLINK')) {
+      return invalidResult('unsafe-type');
+    }
+    // Broken symlink surfaces as ENOENT on some platforms only via lstat —
+    // but O_NOFOLLOW gives ELOOP. ENOENT from a symlinked *path* means the
+    // link target is missing; check whether the entry itself is a symlink.
+    if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+      return invalidResult('unreadable');
+    }
+    // Platforms without O_NOFOLLOW support, or odd errors: distinguish
+    // symlink/type via lstat before declaring unreadable.
+    try {
+      const lst = await lstat(target);
+      if (!lst.isFile()) return invalidResult('unsafe-type');
+    } catch {
+      return invalidResult('missing');
+    }
+    return invalidResult('unreadable');
+  }
+
+  try {
+    const fst = await handle.stat();
+    if (!fst.isFile()) return invalidResult('unsafe-type');
+
+    // Streamed, bounded strict decode: stop at code point 6,001.
+    const decoder = createStrictDecoder();
+    const buf = Buffer.allocUnsafe(READ_CHUNK);
+    const cps = [];
+    let bom = false;
+    let firstChunk = true;
+    let done = false;
+
+    while (!done) {
+      const { bytesRead } = await handle.read(buf, 0, READ_CHUNK, null);
+      let chunk = buf.subarray(0, bytesRead);
+      if (bytesRead === 0) {
+        decoder.flush(); // throws on truncated trailing sequence
+        done = true;
+        break;
+      }
+      if (firstChunk) {
+        firstChunk = false;
+        if (
+          bytesRead >= 3
+          && chunk[0] === UTF8_BOM[0]
+          && chunk[1] === UTF8_BOM[1]
+          && chunk[2] === UTF8_BOM[2]
+        ) {
+          bom = true;
+          chunk = chunk.subarray(3);
+        }
+      }
+      for (const cp of decoder.decode(chunk)) {
+        cps.push(cp);
+        if (cps.length >= PROJECT_IMPORTANT_CODEPOINT_LIMIT + 1) {
+          done = true;
+          break;
+        }
+      }
+    }
+
+    if (cps.length === 0) {
+      return { ...invalidResult('empty'), bom };
+    }
+
+    const oversized = cps.length > PROJECT_IMPORTANT_CODEPOINT_LIMIT;
+    const injected = oversized ? cps.slice(0, PROJECT_IMPORTANT_CODEPOINT_LIMIT) : cps;
+    for (const cp of injected) {
+      if (isForbiddenControl(cp)) {
+        return { ...invalidResult('unsafe-control'), bom, codePointCount: cps.length };
+      }
+    }
+
+    const body = String.fromCodePoint(...injected);
+    const codePointCount = cps.length;
+
+    // Secret gate on the body that would be injected.
+    const gateEnabled = isSensitiveDataGateEnabled(config);
+    const allowlistHashes = loadSensitiveAllowlist(config);
+    const scan = scanText(body, { allowlistHashes, gateEnabled });
+    if (scan.hasSecret) {
+      return {
+        ...invalidResult('secret-blocked'),
+        bom,
+        codePointCount,
+        oversized,
+      };
+    }
+
+    const inspection = {
+      state: oversized ? 'oversized' : 'ready',
+      body,
+      codePointCount,
+      oversized,
+      bom,
+      rendered: undefined,
+      remediationClass: PROJECT_IMPORTANT_REMEDIATION[oversized ? 'oversized' : 'ready'],
+    };
+    inspection.rendered = renderProjectImportant(inspection);
+    return inspection;
+  } catch (err) {
+    if (err && err.message === 'invalid-utf8') {
+      return invalidResult('invalid-utf8');
+    }
+    if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+      return invalidResult('unreadable');
+    }
+    return invalidResult('unreadable');
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * Strict incremental UTF-8 decoder that rejects overlong, surrogate,
+ * >U+10FFFF and truncated sequences; throws Error('invalid-utf8').
+ */
+function createStrictDecoder() {
+  let needed = 0;
+  let value = 0;
+  let min = 0;
+
+  function push(out, cp, seqMin) {
+    if (cp < seqMin || cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff)) {
+      throw new Error('invalid-utf8');
+    }
+    out.push(cp);
+  }
+
+  return {
+    /** @param {Buffer|Uint8Array} chunk @returns {number[]} */
+    decode(chunk) {
+      const out = [];
+      for (let i = 0; i < chunk.length; i += 1) {
+        const b = chunk[i];
+        if (needed > 0) {
+          if (b < 0x80 || b > 0xbf) throw new Error('invalid-utf8');
+          value = (value << 6) | (b & 0x3f);
+          needed -= 1;
+          if (needed === 0) {
+            push(out, value, min);
+          }
+          continue;
+        }
+        if (b < 0x80) {
+          out.push(b);
+        } else if (b >= 0xc2 && b <= 0xdf) {
+          needed = 1; min = 0x80; value = b & 0x1f;
+        } else if (b >= 0xe0 && b <= 0xef) {
+          needed = 2; min = 0x800; value = b & 0x0f;
+        } else if (b >= 0xf0 && b <= 0xf4) {
+          needed = 3; min = 0x10000; value = b & 0x07;
+        } else {
+          throw new Error('invalid-utf8');
+        }
+      }
+      return out;
+    },
+    flush() {
+      if (needed > 0) throw new Error('invalid-utf8');
+    },
+  };
+}
+
+/**
+ * Deterministic envelope renderer. Warning states render as the frozen
+ * warning literal only; ready/oversized render the full envelope.
+ *
+ * @param {{ state: string, body?: string }} inspection
+ * @returns {string}
+ */
+export function renderProjectImportant(inspection) {
+  const { state, body } = inspection || {};
+  if (state !== 'ready' && state !== 'oversized') {
+    return PROJECT_IMPORTANT_WARNINGS[state] || PROJECT_IMPORTANT_WARNINGS.unreadable;
+  }
+  const warning = state === 'oversized'
+    ? PROJECT_IMPORTANT_WARNINGS.oversized + '\n'
+    : '';
+  // Framing newline outside the body: body bytes are preserved verbatim,
+  // the END marker always starts on its own line.
+  const framing = body.endsWith('\n') ? '' : '\n';
+  return (
+    PROJECT_IMPORTANT_ENVELOPE_HEADER
+    + body
+    + framing
+    + END_MARKER
+    + warning
+    + PROJECT_IMPORTANT_ENVELOPE_FOOTER
+  );
+}
+
+/**
+ * Convenience: inspect + ensure `rendered` is populated.
+ *
+ * @param {string} projectRoot
+ * @param {{ config?: object }} [options]
+ */
+export async function renderProjectImportantForProject(projectRoot, options = {}) {
+  const inspection = await inspectProjectImportant({ projectRoot, ...options });
+  if (inspection.rendered === undefined) {
+    inspection.rendered = renderProjectImportant(inspection);
+  }
+  return inspection;
+}
+
+/**
+ * TASK-044 — adapter wiring facts for status/doctor (spec §13/§14).
+ *
+ * Returns install + wiring facts only — never file bodies. Claude wiring is
+ * always expected; omp/Codex/OpenCode are checked only when installed, and an
+ * absent adapter is `installed:false`, never a failure.
+ *
+ * @param {string} projectRoot
+ * @param {{ trackedPaths?: string[] }} [options] install.json file list, if known
+ * @returns {Promise<{claude: object, omp: object, codex: object, opencode: object, agentsFallback: boolean}>}
+ */
+export async function inspectProjectImportantWiring(projectRoot, options = {}) {
+  const trackedPaths = Array.isArray(options.trackedPaths) ? options.trackedPaths : [];
+  const tracked = (prefix) => trackedPaths.some((entry) => entry.startsWith(prefix));
+
+  const runtimeModulePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'project-important.mjs');
+  const hookPath = path.join(projectRoot, '.claude', 'hooks', 'project-important.sh');
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const ompBridgePath = path.join(projectRoot, '.omp', 'hooks', 'pre', 'ukit-bridge.js');
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+
+  const exists = async (p) => {
+    try {
+      await lstat(p);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  // --- Claude wiring (always expected) ---
+  const runtimeModule = await exists(runtimeModulePath);
+  let hookInstalled = false;
+  let hookExecutable = false;
+  try {
+    const st = await lstat(hookPath);
+    hookInstalled = st.isFile();
+    hookExecutable = hookInstalled && (st.mode & 0o111) !== 0;
+  } catch {
+    // absent
+  }
+  let settingsWired = false;
+  try {
+    const raw = await readFile(settingsPath, 'utf8');
+    const settings = JSON.parse(raw);
+    const sessionStart = Array.isArray(settings?.hooks?.SessionStart) ? settings.hooks.SessionStart : [];
+    const commands = sessionStart.flatMap((entry) => (
+      Array.isArray(entry?.hooks) ? entry.hooks.map((h) => String(h?.command ?? '')) : []
+    ));
+    const idx = commands.findIndex((cmd) => cmd.includes('project-important.sh'));
+    settingsWired = idx === 0;
+  } catch {
+    settingsWired = false;
+  }
+  const claude = {
+    installed: true,
+    runtimeModule,
+    hookInstalled,
+    hookExecutable,
+    settingsWired,
+    wired: runtimeModule && hookInstalled && hookExecutable && settingsWired,
+  };
+
+  // --- AGENTS.md owner-instructions pointer (shared Codex/OpenCode fallback) ---
+  let agentsFallback = false;
+  try {
+    const agents = await readFile(agentsPath, 'utf8');
+    agentsFallback = agents.includes('Project Owner Instructions')
+      && agents.includes(PROJECT_IMPORTANT_FILENAME);
+  } catch {
+    agentsFallback = false;
+  }
+
+  // --- omp bridge (only when omp installed/tracked) ---
+  const ompBridgeExists = await exists(ompBridgePath);
+  const ompInstalled = tracked('.omp/') || ompBridgeExists || await exists(path.join(projectRoot, '.omp', 'config.yml'));
+  let ompWired = false;
+  if (ompInstalled && ompBridgeExists) {
+    try {
+      const bridge = await readFile(ompBridgePath, 'utf8');
+      ompWired = /session_start\s*:\s*\[\s*['"]project-important\.sh/.test(bridge);
+    } catch {
+      ompWired = false;
+    }
+  }
+  const omp = { installed: ompInstalled, wired: ompInstalled && ompWired };
+
+  // --- Codex fallback (only when adapter installed) ---
+  const codexInstalled = tracked('.codex/') || await exists(path.join(projectRoot, '.codex', 'settings.json'));
+  const codex = { installed: codexInstalled, wired: codexInstalled && agentsFallback };
+
+  // --- OpenCode fallback (only when opencode.json tracked/installed) ---
+  const opencodeInstalled = tracked('opencode.json') || await exists(path.join(projectRoot, 'opencode.json'));
+  const opencode = { installed: opencodeInstalled, wired: opencodeInstalled && agentsFallback };
+
+  return { claude, omp, codex, opencode, agentsFallback };
+}