@starci/hfs 4.7.32 → 4.7.33

package/runtime/scripts/agent/trust.mjs

@@ -0,0 +1,523 @@
+// trust.mjs — prepare provider trust and guard settings for the launch directory.
+//
+// Automatic launch trust requires this installation's explicit launchTrust owner
+// profile and an exact approved repository root. Missing or declined adoption
+// refuses the launch. Existing provider declines are preserved.
+//
+//   ensureLaunchTrust({ agent, cwd })
+//   SCOPE (lead ruling 2026-10-01): the command guard hook and every launch setting of Claude and Devin are written
+//   to the launch worktree's PROJECT files (projectTargets), never to a user-global settings file, so they reach only
+//   the agents the runtime starts in that worktree; each such file is kept out of git status through the repository's
+//   own info/exclude (excludeFromGit). The per-user records are the ones a host keeps nowhere else: its trust of the
+//   directory, and Codex's guard hook with its trusted hash (the guard acts only for a terminal bound to a guard).
+//     claude → ~/.claude.json projects[<cwd>].hasTrustDialogAccepted = true, in
+//              every key form Claude writes (win32: `<drive>:/…` and `<drive>:\…`); in
+//              <cwd>/.claude/settings.local.json: skipDangerousModePermissionPrompt
+//              (set only when missing), each agents/claude.yaml launchEnv key under
+//              env (DISABLE_AUTOUPDATER: Orca composes a worker's command, so its
+//              launch env cannot carry it) and the guard hook.
+//     codex  → [projects."<path>"] trust_level = "trusted" in each Codex home the worker can start in
+//              (CODEX_HOME, else Orca's codex-runtime-home and the system ~/.codex) for the launch
+//              cwd and the git root Codex keys trust by, in the key forms Codex
+//              writes (win32: a '<drive>:\lower\case' literal and a "<DRIVE>:\\exact" basic), plus the
+//              update-check and model-nudge notices; the guard hook as a block in
+//              each home's own config.toml (Codex 0.160.0 lists a project
+//              layer's hooks only for a repository's main checkout, never for a linked
+//              worktree) and the hash Codex trusts it by (codex app-server hooks/list,
+//              then config/batchWrite hooks.state - the way Orca trusts its own hooks).
+//     devin  → <cwd>/.devin/config.local.json (Devin's local project config): the
+//              guard hook only: Devin has no per-worker model pin through Orca.
+//   Returns the receipt the launch event records:
+//     {agent, paths, status: written|already|skipped|failed, written[], already[], …}
+//
+// Both files are rewritten by running agent sessions, so every write is a
+// read-modify-write with an atomic rename, re-read and verified; a lost update
+// is retried a bounded number of times. Only the named project keys change —
+// every other field/table (and TOML comments) is kept. A test process
+// (NODE_TEST_CONTEXT) never touches the real files: it writes only under
+// STARCI_AGENT_TRUST_HOME, or skips.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs'; import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { renameOver } from '../api/fs/rename-over.mjs';
+import { sleepSync } from '../lib/sleep-sync.mjs';
+import { parseJson } from '../lib/json.mjs';
+import { isSpecRun } from '../lib/env.mjs';
+import { isGuardCommand } from '../lib/guard-command.mjs';
+import { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
+import { orcaUserData } from './host-agents.mjs';
+export { codexTrustPaths, launchTrustVerdict } from './launch-trust-policy.mjs';
+import { codexAppServer } from './codex-app-server.mjs';
+export { codexAppServer };
+
+const CLAUDE_CARD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'modules', 'models', 'agents', 'claude.yaml');
+
+const ATTEMPTS = 5;
+
+/* ---------------------------------------------------------------- targets */
+
+/** Orca's CODEX_HOME: <Electron userData>/codex-runtime-home/home, resolved the way Orca does. */
+export function orcaCodexHome({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.STARCI_ORCA_CODEX_HOME) return env.STARCI_ORCA_CODEX_HOME;
+  return path.join(orcaUserData({ env, platform, home }), 'codex-runtime-home', 'home');
+}
+
+/**
+ * The files trust is written to. STARCI_AGENT_TRUST_HOME re-roots every one of
+ * them (specs); otherwise Claude's own CLAUDE_CONFIG_DIR and Codex's CODEX_HOME
+ * are honoured. Returns {claudeJson, codexHomes[], home, skipped?}.
+ */
+export function trustTargets({ env = process.env, platform = process.platform } = {}) {
+  const root = env.STARCI_AGENT_TRUST_HOME || null;
+  if (!root && isSpecRun(env))
+    return { skipped: 'a test process writes agent trust only under STARCI_AGENT_TRUST_HOME' };
+  const home = root || os.homedir();
+  const claudeDir = !root && env.CLAUDE_CONFIG_DIR ? env.CLAUDE_CONFIG_DIR : null;
+  const codexHomes = [];
+  const addHome = (kind, dir) => {
+    if (!dir) return;
+    const key = path.resolve(dir).toLowerCase();
+    if (!codexHomes.some((h) => path.resolve(h.dir).toLowerCase() === key)) codexHomes.push({ kind, dir: path.resolve(dir) });
+  };
+  // The active worker home; the system home joins it in codexLaunchHomes (codex-mirror-source.mjs).
+  addHome('active-codex-home', root ? path.join(root,'.codex') : (env.CODEX_HOME || orcaCodexHome({ env, platform, home })));
+  return {
+    claudeJson: claudeDir ? path.join(claudeDir, '.claude.json') : path.join(home, '.claude.json'),
+    codexHomes, home,
+  };
+}
+
+/**
+ * The PROJECT-scoped files of the launch directory `dir` (never a user-global file): Claude's local project settings
+ * and Devin's local project config. They carry the command guard hook and each host's launch settings, so they
+ * apply only to agents started in that worktree.
+ */
+export const projectTargets = (dir) => ({
+  claudeSettings: path.join(dir, '.claude', 'settings.local.json'),
+  devinConfig: path.join(dir, '.devin', 'config.local.json'),
+});
+
+/**
+ * Keep a project file the runtime wrote out of `git status`: its path (relative to the checkout's top level) goes in
+ * the repository's own info/exclude (`git rev-parse --git-path info/exclude`), never a user-global ignore. A directory
+ * that is no git checkout, or a file git already tracks, is left alone. Returns {file, state} or null.
+ */
+export function excludeFromGit(dir, file) {
+  const topOut = revParseQuery(['--show-toplevel'], { cwd: dir });
+  const excludeOut = revParseQuery(['--path-format=absolute', '--git-path', 'info/exclude'], { cwd: dir });
+  if (topOut?.status !== 0 || excludeOut?.status !== 0) return null;
+  const top = String(topOut.stdout).trim();
+  const rel = path.relative(top, file).split(path.sep).join('/');
+  if (!rel || rel.startsWith('..')) return null;
+  if (lsFiles(['--error-unmatch', '--', rel], { cwd: top })?.status === 0) return { file: rel, state: 'tracked' };
+  const target = String(excludeOut.stdout).trim();
+  const line = '/' + rel;
+  let text = '';
+  try { text = fs.readFileSync(target, 'utf8'); } catch { text = ''; }
+  if (text.split(/\r?\n/).includes(line)) return { file: rel, state: 'already' };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.appendFileSync(target, (text && !text.endsWith('\n') ? '\n' : '') + line + '\n');
+  return { file: rel, state: 'written' };
+}
+
+/* -------------------------------------------------------------- key forms */
+
+const upperDrive = (p) => p.replace(/^([a-z]):/, (m, d) => `${d.toUpperCase()}:`);
+
+/** Claude's project keys for `dir`: win32 writes both `<drive>:/…` and `<drive>:\…`. */
+export function claudeKeyForms(dir, platform = process.platform) {
+  if (platform !== 'win32') return [path.posix.resolve(String(dir))];
+  const abs = upperDrive(path.win32.resolve(String(dir)));
+  return [...new Set([abs.replaceAll('\\', '/'), abs.replaceAll('/', '\\')])];
+}
+
+/** Codex's project keys for `dir`: win32 writes '<drive>:\lower' (its own form) and "<DRIVE>:\\exact". */
+export function codexKeyForms(dir, platform = process.platform) {
+  if (platform !== 'win32') return [path.posix.resolve(String(dir))];
+  const abs = upperDrive(path.win32.resolve(String(dir))).replaceAll('/', '\\');
+  return [...new Set([abs.toLowerCase(), abs])];
+}
+
+/* ------------------------------------------------------ atomic rewriting */
+
+// A transform that wants its input as text: an absent file reads as the empty string.
+const asText = (transform) => (text) => transform(text ?? '');
+export const readText = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') { return null; } throw e; } };
+
+/**
+ * Read-modify-write `file` with an atomic rename, then re-read and verify.
+ *   transform(text|null) → {text: next|null (no change needed), result}
+ *   verify(text) → true when the change is on disk
+ * A concurrent rewrite between read and rename, or one that lands after the
+ * rename and drops the change, is a lost update: retried up to `attempts`.
+ * hooks.beforeRename / hooks.afterRename let specs simulate that writer.
+ */
+function atomicUpdate(file, transform, verify, { attempts = ATTEMPTS, hooks = {} } = {}) {
+  const trail = [];
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const before = readText(file);
+    const { text: next, result } = transform(before);
+    if (next == null) {
+      if (verify(before)) return { ok: true, changed: false, attempts: attempt, trail, result };
+      return { ok: false, error: 'transform produced no change but verification failed', attempts: attempt, trail };
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.starci-trust-${process.pid}-${Date.now()}-${attempt}.tmp`;
+    fs.writeFileSync(tmp, next);
+    try {
+      hooks.beforeRename?.({ attempt, file });
+      if (readText(file) !== before) { trail.push({ attempt, lost: 'rewritten-before-rename' }); continue; }
+      renameOver(tmp, file, { delayMs: (i) => 25 * (i + 1) });
+    } finally { try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort */ } }
+    hooks.afterRename?.({ attempt, file });
+    const onDisk = readText(file);
+    if (onDisk != null && verify(onDisk)) return { ok: true, changed: true, attempts: attempt, trail, result };
+    trail.push({ attempt, lost: 'overwritten-after-rename' });
+    sleepSync(20 * attempt);
+  }
+  return { ok: false, error: `lost update: ${file} was rewritten on each of ${attempts} attempts`, attempts, trail };
+}
+
+/* ------------------------------------------------------------------ claude */
+
+// The project shape Claude itself writes for a new directory.
+const CLAUDE_PROJECT_DEFAULT = () => ({
+  allowedTools: [], mcpContextUris: [], mcpServers: {}, enabledMcpjsonServers: [], disabledMcpjsonServers: [],
+  hasTrustDialogAccepted: true, hasClaudeMdExternalIncludesApproved: false, hasClaudeMdExternalIncludesWarningShown: false,
+});
+
+// JSON.parse → stringify is exact for every value except integers past 2^53.
+// Refuse to rewrite a file whose long number literals would not survive.
+const longNumbers = (text) => (text.match(/(?<![\w."])-?\d{16,}(?:\.\d+)?(?:[eE][+-]?\d+)?(?![\w"])/g) ?? []);
+const numbersSurvive = (before, after) => longNumbers(before).every((n) => after.includes(n));
+
+export const jsonOf = (text) => parseJson(text, undefined);
+
+/** Set projects[key].hasTrustDialogAccepted = true for every key in `file` (~/.claude.json). */
+export function writeClaudeTrust({ file, keys, hooks }) {
+  const verify = (text) => {
+    const doc = text == null ? null : jsonOf(text);
+    return !!doc && keys.every((k) => doc.projects?.[k]?.hasTrustDialogAccepted === true);
+  };
+  const out = { file, written: [], already: [] };
+  const updated = atomicUpdate(file, (text) => {
+    const doc = text == null ? {} : jsonOf(text);
+    if (doc === undefined || !doc || typeof doc !== 'object' || Array.isArray(doc))
+      throw new Error(`${file} is not a JSON object; refusing to rewrite it`);
+    const written = [], already = [];
+    if (!doc.projects || typeof doc.projects !== 'object') doc.projects = {};
+    for (const key of keys) {
+      const existing = doc.projects[key];
+      if (existing?.hasTrustDialogAccepted === true) { already.push(key); continue; }
+      if (existing?.hasTrustDialogAccepted === false) throw new Error(`${file}: owner declined trust for ${key}`);
+      doc.projects[key] = existing && typeof existing === 'object' ? { ...existing, hasTrustDialogAccepted: true } : CLAUDE_PROJECT_DEFAULT();
+      written.push(key);
+    }
+    if (!written.length) return { text: null, result: { written, already } };
+    const next = JSON.stringify(doc, null, 2) + (text?.endsWith('\n') ? '\n' : '');
+    if (text && !numbersSurvive(text, next)) throw new Error(`${file} holds a number JSON cannot round-trip; refusing to rewrite it`);
+    return { text: next, result: { written, already } };
+  }, verify, { hooks });
+  if (!updated.ok) return { ...out, ok: false, error: updated.error, trail: updated.trail };
+  out.written = updated.result.written;
+  out.already = updated.result.already;
+  return { ...out, ok: true, attempts: updated.attempts, ...(updated.trail.length ? { trail: updated.trail } : {}) };
+}
+
+/** Assert skipDangerousModePermissionPrompt in Claude's settings.json; set it only when missing. */
+export function assertClaudeBypassConsent({ file, hooks }) {
+  const current = readText(file);
+  const doc = current == null ? {} : jsonOf(current);
+  if (doc === undefined || !doc || typeof doc !== 'object') return { file, ok: false, state: 'unreadable' };
+  if (doc.skipDangerousModePermissionPrompt === true) return { file, ok: true, state: 'already' };
+  if ('skipDangerousModePermissionPrompt' in doc) return { file, ok: false, state: 'owner-set-false' };
+  const updated = atomicUpdate(file, (text) => {
+    const d = text == null ? {} : jsonOf(text);
+    if (d === undefined || !d || typeof d !== 'object') throw new Error(`${file} is not a JSON object`);
+    if ('skipDangerousModePermissionPrompt' in d) return { text: null, result: null };
+    d.skipDangerousModePermissionPrompt = true;
+    return { text: JSON.stringify(d, null, 2) + (text?.endsWith('\n') ? '\n' : ''), result: null };
+  }, (text) => jsonOf(text ?? '')?.skipDangerousModePermissionPrompt === true, { hooks });
+  return updated.ok ? { file, ok: true, state: updated.changed ? 'written' : 'already' } : { file, ok: false, state: 'failed', error: updated.error };
+}
+
+/** agents/claude.yaml launchEnv: {KEY: 'value'} (string values only), or {} when the card has none. */
+export function claudeLaunchEnv({ file = CLAUDE_CARD } = {}) {
+  try {
+    const vars = parseYaml(fs.readFileSync(file, 'utf8'))?.launchEnv;
+    if (!vars || typeof vars !== 'object' || Array.isArray(vars)) return {};
+    return Object.fromEntries(Object.entries(vars).filter(([k, v]) => /^[A-Z_][A-Z0-9_]*$/.test(k) && v != null).map(([k, v]) => [k, String(v)]));
+  } catch { return {}; }
+}
+
+/**
+ * Assert each `vars` key under settings.json env; set only the keys that are missing (an owner-set value, even a
+ * different one, is kept). Returns {file, ok, state: written|already|owner-set|unreadable|failed, owner?: [keys]}.
+ */
+export function assertClaudeSettingsEnv({ file, vars, hooks }) {
+  const keys = Object.keys(vars ?? {});
+  if (!keys.length) return { file, ok: true, state: 'already' };
+  const current = readText(file);
+  const doc = current == null ? {} : jsonOf(current);
+  if (doc === undefined || !doc || typeof doc !== 'object' || Array.isArray(doc)) return { file, ok: false, state: 'unreadable' };
+  if (doc.env != null && (typeof doc.env !== 'object' || Array.isArray(doc.env))) return { file, ok: false, state: 'unreadable' };
+  const has = (d, k) => d.env && typeof d.env === 'object' && Object.hasOwn(d.env, k);
+  const owner = keys.filter((k) => has(doc, k) && String(doc.env[k]) !== vars[k]);
+  const missing = keys.filter((k) => !has(doc, k));
+  if (!missing.length) return { file, ok: true, state: owner.length ? 'owner-set' : 'already', ...(owner.length ? { owner } : {}) };
+  const updated = atomicUpdate(file, (text) => {
+    const d = text == null ? {} : jsonOf(text);
+    if (d === undefined || !d || typeof d !== 'object' || Array.isArray(d)) throw new Error(`${file} is not a JSON object`);
+    const add = keys.filter((k) => !has(d, k));
+    if (!add.length) return { text: null, result: null };
+    d.env = { ...(d.env && typeof d.env === 'object' ? d.env : {}), ...Object.fromEntries(add.map((k) => [k, vars[k]])) };
+    return { text: JSON.stringify(d, null, 2) + (text?.endsWith('\n') ? '\n' : ''), result: null };
+  }, (text) => { const d = jsonOf(text ?? ''); return !!d && keys.every((k) => has(d, k)); }, { hooks });
+  return updated.ok ? { file, ok: true, state: updated.changed ? 'written' : 'already', ...(owner.length ? { owner } : {}) }
+    : { file, ok: false, state: 'failed', error: updated.error };
+}
+
+/* ------------------------------------------------------------------- codex */
+
+// A TOML key segment: bare, 'literal' or "basic" (with escapes).
+const KEY_SEG = String.raw`(?:[A-Za-z0-9_-]+|'[^'\r\n]*'|"(?:[^"\\\r\n]|\\.)*")`;
+const PROJECT_HEADER = new RegExp(String.raw`^[ \t]*\[[ \t]*projects[ \t]*\.[ \t]*(${KEY_SEG})[ \t]*\][ \t]*(?:#.*)?$`);
+const ANY_HEADER = /^[ \t]*\[/;
+const TRUST_LINE = /^([ \t]*trust_level[ \t]*=[ \t]*)("(?:[^"\\]|\\.)*"|'[^']*')(.*)$/;
+
+const decodeKey = (seg) => {
+  if (seg.startsWith("'")) return seg.slice(1, -1);
+  if (!seg.startsWith('"')) return seg;
+  return seg.slice(1, -1).replace(/\\(u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8}|.)/g, (m, e) => {
+    if (e[0] === 'u' || e[0] === 'U') return String.fromCodePoint(Number.parseInt(e.slice(1), 16));
+    return { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' }[e] ?? e;
+  });
+};
+const decodeValue = (v) => (v.startsWith("'") ? v.slice(1, -1) : decodeKey(v));
+
+const ESCAPED_QUOTE = String.raw`\"`;
+/** A TOML basic-string body: backslash and double quote escaped. */
+const tomlEscaped = (v) => String(v).replaceAll('\\', '\\\\').replaceAll('"', ESCAPED_QUOTE);
+
+/** The header Codex would write for `key`: a literal for its lowercase form, else a basic string. */
+function codexHeader(key) {
+  const literal = !/['\r\n]/.test(key) && key === key.toLowerCase() && key.includes('\\');
+  return literal ? `[projects.'${key}']` : `[projects."${tomlEscaped(key)}"]`;
+}
+
+/** {key → {header line index, trust line index|null, trust value|null, end}} for every [projects.<key>] table. */
+export function codexProjectTables(text) {
+  const lines = String(text ?? '').split('\n');
+  const tables = new Map();
+  let current = null;
+  lines.forEach((line, i) => {
+    const bare = line.replace(/\r$/, '');
+    const m = PROJECT_HEADER.exec(bare);
+    if (m) { current = { key: decodeKey(m[1]), header: i, trustLine: null, trust: null, end: i }; if (!tables.has(current.key)) { tables.set(current.key, current); } return; }
+    if (ANY_HEADER.test(bare)) { current = null; return; }
+    if (!current) return;
+    if (bare.trim()) current.end = i;
+    const t = TRUST_LINE.exec(bare);
+    if (t && current.trustLine === null) { current.trustLine = i; current.trust = decodeValue(t[2]); }
+  });
+  return tables;
+}
+
+const ownerTrustSet = (table) => table?.trust !== null && table?.trust !== undefined;
+
+function trustExistingLine(lines, index) {
+  const cr = lines[index].endsWith('\r') ? '\r' : '';
+  const m = TRUST_LINE.exec(lines[index].replace(/\r$/, ''));
+  lines[index] = `${m[1]}"trusted"${m[3]}${cr}`;
+}
+
+function appendTrustTables(text, keys, eol) {
+  let next = text;
+  if (keys.length && next && !next.endsWith('\n')) next += eol;
+  for (const key of keys) next += `${next ? eol : ''}${codexHeader(key)}${eol}trust_level = "trusted"${eol}`;
+  return next;
+}
+
+/** The edit that trusts every key of a Codex config.toml: `{ text: next|null, result: { written, already } }`. */
+function codexTrustEdit(source, keys, file) {
+  const eol = source.includes('\r\n') ? '\r\n' : '\n';
+  const tables = codexProjectTables(source);
+  const lines = source.split('\n');
+  const written = [], already = [], append = [];
+  const inserts = [];
+  for (const key of keys) {
+    const table = tables.get(key);
+    if (table?.trust === 'trusted') { already.push(key); continue; }
+    if (ownerTrustSet(table)) throw new Error(`${file}: owner set ${key} trust_level=${table.trust}; refusing to override`);
+    written.push(key);
+    if (!table) append.push(key);
+    else if (table.trustLine === null) inserts.push(table.header);
+    else trustExistingLine(lines, table.trustLine);
+  }
+  if (!written.length) return { text: null, result: { written, already } };
+  for (const at of inserts.toSorted((a, b) => b - a)) lines.splice(at + 1, 0, `trust_level = "trusted"${eol === '\r\n' ? '\r' : ''}`);
+  return { text: appendTrustTables(lines.join('\n'), append, eol), result: { written, already } };
+}
+
+/** Ensure trust_level = "trusted" for every key in a Codex config.toml. Appends; edits only an untrusted table's own line. */
+export function writeCodexTrust({ file, keys, hooks }) {
+  const verify = (text) => {
+    const tables = codexProjectTables(text ?? '');
+    return keys.every((k) => tables.get(k)?.trust === 'trusted');
+  };
+  const out = { file, written: [], already: [] };
+  const updated = atomicUpdate(file, asText((source) => codexTrustEdit(source, keys, file)), verify, { hooks });
+  if (!updated.ok) return { ...out, ok: false, error: updated.error, trail: updated.trail };
+  out.written = updated.result.written;
+  out.already = updated.result.already;
+  return { ...out, ok: true, attempts: updated.attempts, ...(updated.trail.length ? { trail: updated.trail } : {}) };
+}
+
+// A new Codex release turned every fresh Codex launch into an interactive
+// "Update available! … Press enter to continue" menu: eighteen op launches in
+// three workflows failed readiness or model attestation in three hours while
+// the kernels, started before the release, kept working. The launch must
+// never wait on it, so the top-level check_for_update_on_startup is pinned
+// false in every Codex home, like trust.
+const UPDATE_CHECK_LINE = /^[ \t]*check_for_update_on_startup[ \t]*=.*$/m;
+const topLevelOf = (text) => { const at = String(text ?? '').search(/^[ \t]*\[/m); return at < 0 ? String(text ?? '') : String(text ?? '').slice(0, at); };
+export function writeCodexNoUpdateCheck({ file, hooks }) {
+  const verify = (text) => /^[ \t]*check_for_update_on_startup[ \t]*=[ \t]*false[ \t]*(?:#.*)?\r?$/m.test(topLevelOf(text));
+  const updated = atomicUpdate(file, asText((source) => {
+    if (verify(source)) return { text: null, result: { written: false } };
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const top = topLevelOf(source);
+    // An existing key is flipped in place; a new one closes the top-level block,
+    // so the owner's own leading keys stay where they were.
+    const head = top && !top.endsWith('\n') ? `${top}${eol}` : top;
+    const next = UPDATE_CHECK_LINE.test(top)
+      ? top.replace(UPDATE_CHECK_LINE, 'check_for_update_on_startup = false') + source.slice(top.length)
+      : `${head}check_for_update_on_startup = false${eol}${source.slice(top.length)}`;
+    return { text: next, result: { written: true } };
+  }), verify, { hooks });
+  if (!updated.ok) return { file, ok: false, error: updated.error };
+  return { file, ok: true, written: updated.result.written };
+}
+
+// Codex's quota nudge ("Approaching rate limits - Switch to <cheaper model>?") stopped a Collab interface.draw op
+// at its menu (2026-09-24). Owner: always keep the current model and never show it again - the answer Codex
+// itself records as [notice] hide_rate_limit_model_nudge = true, pinned in every Codex home.
+const NUDGE_LINE = /^[ \t]*hide_rate_limit_model_nudge[ \t]*=.*$/m;
+const noticeTable = (text) => {
+  const at = text.search(/^[ \t]*\[notice\][ \t]*(?:#.*)?\r?$/m);
+  if (at < 0) return null;
+  const bodyAt = text.indexOf('\n', at) + 1 || text.length;
+  const next = text.slice(bodyAt).search(/^[ \t]*\[/m);
+  return { bodyAt, end: next < 0 ? text.length : bodyAt + next };
+};
+export function writeCodexNoModelNudge({ file, hooks }) {
+  const verify = (text) => {
+    const table = noticeTable(String(text ?? ''));
+    return Boolean(table) && /^[ \t]*hide_rate_limit_model_nudge[ \t]*=[ \t]*true[ \t]*(?:#.*)?\r?$/m.test(String(text).slice(table.bodyAt, table.end));
+  };
+  const updated = atomicUpdate(file, asText((source) => {
+    if (verify(source)) return { text: null, result: { written: false } };
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const table = noticeTable(source);
+    let next;
+    if (table) {
+      const body = source.slice(table.bodyAt, table.end);
+      const fixed = NUDGE_LINE.test(body) ? body.replace(NUDGE_LINE, 'hide_rate_limit_model_nudge = true') : `hide_rate_limit_model_nudge = true${eol}${body}`;
+      next = source.slice(0, table.bodyAt) + fixed + source.slice(table.end);
+    } else {
+      const base = source && !source.endsWith('\n') ? `${source}${eol}` : source;
+      next = `${base}${base ? eol : ''}[notice]${eol}hide_rate_limit_model_nudge = true${eol}`;
+    }
+    return { text: next, result: { written: true } };
+  }), verify, { hooks });
+  if (!updated.ok) return { file, ok: false, error: updated.error };
+  return { file, ok: true, written: updated.result.written };
+}
+
+/* ------------------------------------------------------ the command guard */
+
+export const TOOL_GUARD_MATCHER = 'Bash|PowerShell|Edit|Write|MultiEdit|NotebookEdit';
+const isGuardHandler = (h) => typeof h?.command === 'string' && (isGuardCommand(h.command) || h.command.includes('command-guard.mjs'));
+const isGuardGroup = (g) => Array.isArray(g?.hooks) && g.hooks.some(isGuardHandler);
+
+/**
+ * Ensure hooks.PreToolUse of a Claude-format JSON config (Claude's settings.json, Devin's config.json) holds exactly
+ * one command-guard group: {matcher?, hooks: [{type: command, command, timeout}]}. An older guard group (another
+ * runtime path) is replaced; every other hook is kept.
+ */
+export function assertJsonToolGuard({ file, command, matcher = null, hooks }) {
+  const group = { ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command, timeout: HOOK_INPUT_LIMITS.hookTimeoutSeconds }] };
+  const holds = (d) => {
+    const list = Array.isArray(d?.hooks?.PreToolUse) ? d.hooks.PreToolUse.filter(isGuardGroup) : [];
+    return list.length === 1 && JSON.stringify(list[0]) === JSON.stringify(group);
+  };
+  let updated;
+  try { updated = atomicUpdate(file, (text) => {
+    const d = text == null ? {} : jsonOf(text);
+    if (d === undefined || !d || typeof d !== 'object' || Array.isArray(d)) throw new Error(`${file} is not a JSON object`);
+    if (d.hooks != null && (typeof d.hooks !== 'object' || Array.isArray(d.hooks))) throw new Error(`${file} hooks is not an object`);
+    if (holds(d)) return { text: null, result: null };
+    d.hooks = { ...d.hooks };
+    const others = Array.isArray(d.hooks.PreToolUse) ? d.hooks.PreToolUse.filter((g) => !isGuardGroup(g)) : [];
+    d.hooks.PreToolUse = [...others, group];
+    const next = JSON.stringify(d, null, 2) + (text?.endsWith('\n') ? '\n' : '');
+    if (text && !numbersSurvive(text, next)) throw new Error(`${file} holds a number JSON cannot round-trip; refusing to rewrite it`);
+    return { text: next, result: null };
+  }, (text) => { const d = jsonOf(text ?? ''); return !!d && holds(d); }, { hooks }); }
+  catch (e) { return { file, ok: false, state: 'failed', error: String(e?.message ?? e) }; }
+  return updated.ok ? { file, ok: true, state: updated.changed ? 'written' : 'already' } : { file, ok: false, state: 'failed', error: updated.error };
+}
+
+/** Devin's project config: the command guard only. LIVE E7 (2026-10-02): Devin honours agent.model only in the user config (--config) or DEVIN_MODEL, never in <project>/.devin/config*.json, and Orca refuses a launch-time model for Devin, so no model is written here (an external limitation, see the CHANGELOG). */
+export function writeDevinProfile({ file, command, hooks }) {
+  return assertJsonToolGuard({ file, command, hooks });
+}
+
+// A Codex hook lives in the home's config.toml as an array-of-tables block the runtime owns, marked on its first line.
+const CODEX_GUARD_BEGIN = '# starci-command-guard (scripts/agent/trust.mjs): the op command guard, a PreToolUse hook';
+export function codexGuardBlock(command, eol = '\n') {
+  const q = (v) => `"${tomlEscaped(v)}"`;
+  return [CODEX_GUARD_BEGIN, '[[hooks.PreToolUse]]', 'matcher = "^Bash$"', '', '[[hooks.PreToolUse.hooks]]', 'type = "command"', `command = ${q(command)}`, `timeout = ${HOOK_INPUT_LIMITS.hookTimeoutSeconds}`, ''].join(eol);
+}
+/** Put the guard block in a Codex config.toml: appended, or an older block (another runtime path) replaced in place. */
+export function writeCodexToolGuard({ file, command, hooks }) {
+  const eolOf = (text) => (String(text ?? '').includes('\r\n') ? '\r\n' : '\n');
+  const verify = (text) => String(text ?? '').includes(codexGuardBlock(command, eolOf(text)));
+  const updated = atomicUpdate(file, asText((source) => {
+    if (verify(source)) return { text: null, result: { written: false } };
+    const eol = eolOf(source);
+    const at = source.indexOf(CODEX_GUARD_BEGIN);
+    if (at >= 0) {
+      // The block ends at the first table header that is not its own.
+      const rest = source.slice(at);
+      const end = /^[ \t]*\[(?!\[hooks\.PreToolUse(?:\.hooks)?\]\])/m.exec(rest);
+      return { text: source.slice(0, at) + codexGuardBlock(command, eol) + (end ? eol + rest.slice(end.index) : ''), result: { written: true } };
+    }
+    const base = source && !source.endsWith('\n') ? `${source}${eol}` : source;
+    return { text: `${base}${base ? eol : ''}${codexGuardBlock(command, eol)}`, result: { written: true } };
+  }), verify, { hooks });
+  return updated.ok ? { file, ok: true, written: updated.result.written } : { file, ok: false, error: updated.error };
+}
+
+// The `codex app-server` client lives in codex-app-server.mjs (this file is over its size budget); it is re-exported
+// above so callers of trust.mjs keep their import. A launch that gets no answer throws APP_SERVER_FAILURE with
+// codex's own exit, stderr tail and version - a worker-start strike of the codex circuit (provider-outage.mjs).
+
+/** Trust the guard hook of one Codex home: hooks/list, then hooks.state.<key>.trusted_hash for each untrusted one. */
+export function trustCodexToolGuard({ home, cwd, command, appServer = codexAppServer }) {
+  const listed = (result) => (result?.data ?? []).flatMap((d) => d?.hooks ?? []).filter((h) => h?.command === command && h?.eventName === 'preToolUse');
+  const [before] = appServer({ home, requests: [{ method: 'hooks/list', params: { cwds: [cwd] } }] });
+  const entries = listed(before);
+  if (!entries.length) return { home, ok: false, error: 'codex hooks/list does not show the command guard' };
+  const untrusted = entries.filter((h) => h.trustStatus !== 'trusted');
+  if (!untrusted.length) return { home, ok: true, trusted: 'already' };
+  const value = Object.fromEntries(untrusted.map((h) => [h.key, { trusted_hash: h.currentHash }]));
+  const [, after] = appServer({ home, requests: [
+    { method: 'config/batchWrite', params: { edits: [{ keyPath: 'hooks.state', value, mergeStrategy: 'upsert' }], reloadUserConfig: true } },
+    { method: 'hooks/list', params: { cwds: [cwd] } }] });
+  const still = listed(after).filter((h) => h.trustStatus !== 'trusted');
+  return still.length ? { home, ok: false, error: `codex still reports the guard hook ${still[0].trustStatus ?? 'untrusted'}` } : { home, ok: true, trusted: 'written' };
+}

package/runtime/scripts/api/fs/rename-over.mjs

@@ -0,0 +1,21 @@
+// rename-over.mjs — replacing a file whole through a temp file beside it.
+import fs from 'node:fs';
+import { sleepSync } from '../../lib/sleep-sync.mjs';
+import { FS_BUSY } from './lib.mjs';
+
+/**
+ * Rename `tmp` over `file`. A busy refusal (FS_BUSY of lib.mjs) is retried up to `retries` times, `delayMs(attempt)`
+ * apart. When the rename fails for good, `tmp` is removed and the last error is thrown. `rename` is the seam
+ * a spec injects (default fs.renameSync).
+ */
+export function renameOver(tmp, file, { retries = 20, delayMs = () => 25, sleep = sleepSync, rename = fs.renameSync } = {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    try { rename(tmp, file); return; } catch (error) {
+      if (attempt >= retries || !FS_BUSY.includes(error?.code)) {
+        try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+        throw error;
+      }
+      sleep(delayMs(attempt));
+    }
+  }
+}

package/runtime/scripts/api/fs/temp-path.mjs

@@ -0,0 +1,8 @@
+// temp-path.mjs — a path under the temp root (engine/temp-root.mjs tempRoot, ensured by ensure-temp-root.mjs) whose directory exists: a scratch file or a named subdirectory the caller makes.
+import path from 'node:path';
+import { ensureTempRoot } from './ensure-temp-root.mjs';
+
+/** `parts` joined under the temp root, which is created when it is missing (TEMP_ROOT_UNUSABLE when it cannot be made). */
+export function tempPath(...parts) {
+  return path.join(ensureTempRoot(), ...parts);
+}

package/runtime/scripts/api/fs/write-json-file.mjs

@@ -0,0 +1,10 @@
+// write-json-file.mjs - one JSON document written to a file (the runtime's pretty-printed state files).
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `value` written to `file` as two-space JSON plus a trailing newline (parent directories created). */
+export function writeJsonFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}
+`);
+}

package/runtime/scripts/api/git/diff-names.mjs

@@ -0,0 +1,8 @@
+// diff-names.mjs — `git diff --name-only <from>..<to> -- <paths>`: the files a commit range changed under `paths`.
+import { gitRunner } from './lib.mjs';
+
+/** The changed paths ([] when none), or null when git does not answer. git: the caller's runner or null. */
+export function diffNames(cwd, from, to, { paths = [], git = null } = {}) {
+  const r = gitRunner(git)(['diff', '--name-only', `${from}..${to}`, '--', ...paths], { cwd, timeout: 20_000 });
+  return r.ok ? r.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean) : null;
+}

package/runtime/scripts/api/git/head-time.mjs

@@ -0,0 +1,10 @@
+// head-time.mjs — `git log -1 --format=%ct %h`: the committer time (seconds) and short sha of HEAD, or null.
+import { runGit } from './lib.mjs';
+
+/** {time, sha} of HEAD in the repository at `cwd` (time in seconds); null when `cwd` is not a checkout. */
+export const headTime = (cwd) => {
+  const r = runGit(['log', '-1', '--format=%ct %h'], { cwd, timeout: 5000 });
+  if (r.error || r.status !== 0) return null;
+  const [ct, sha] = String(r.stdout ?? '').trim().split(' ');
+  return /^\d+$/.test(ct) && sha ? { time: Number(ct), sha } : null;
+};