@codedology/code-forge 0.15.2 → 0.15.4

package/src/config/validate.mjs

@@ -66,7 +66,9 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import schema from '../../schema/code-forge.schema.json' with { type: 'json' };
 import { redact } from '../util/redact.mjs';
+import { packageVersion } from '../util/error-log.mjs';
 import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
+import { BLOCK_KINDS } from '../decide/escalation.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
@@ -75,6 +77,7 @@ import { isKnownId, resolveLevel } from './known-ids.mjs';
 import { ROUTE_LEVELS, ruleProvider } from '../review/route.mjs';
 import { DEFAULT_SANDBOX_PROFILE, SANDBOX_PROFILES, sandboxDirRefusals, SANDBOX_DIR_REFUSED } from '../engines/sandbox-dirs.mjs';
 import { tmpBase } from '../util/tmp.mjs';
+import { expandBraces, globMatch } from '../state/registry.mjs';
 import { looksLikeSecret, maskSecretTokens, SECRET_MASK, secretTokensIn } from './secret-patterns.mjs';
 
 /**
@@ -211,7 +214,7 @@ function runSchemaValidation(cfg) {
       if (err.keyword === 'propertyNames' && typeof err.params?.propertyName === 'string') {
         detail = `property name "${safeSegment(err.params.propertyName)}" is not allowed (propertyNames)`;
       } else if (err.keyword === 'additionalProperties' && typeof err.params?.additionalProperty === 'string') {
-        detail = `must NOT have additional property "${safeSegment(err.params.additionalProperty)}"`;
+        detail = `must NOT have additional property "${safeSegment(err.params.additionalProperty)}" (unknown key; if it comes from a newer code-forge, upgrade: this is code-forge ${packageVersion()})`;
       }
       return {
         rule: 'schema',
@@ -512,12 +515,76 @@ function gateMessages(key, value) {
   return messages;
 }
 
+/** Custom gate refusals are also checked before running commands or reading evidence.
+ * @param {unknown} custom @returns {string[]}
+ */
+export function customGateMessages(custom) {
+  if (custom === undefined) return [];
+  if (!Array.isArray(custom)) return ['gates.custom must be an array of at most 20 named object gates'];
+  const messages = custom.length > 20 ? ['gates.custom must contain at most 20 entries'] : [];
+  const names = new Set();
+  for (const [i, value] of custom.entries()) {
+    const key = `custom[${i}]`;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      messages.push(`gates.${key} must be a named object gate`);
+      continue;
+    }
+    const { name, evidence, ...command } = value;
+    const label = `${key}${typeof name === 'string' ? ` (${safeSegment(name)})` : ''}`;
+    if (typeof name !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(name)) messages.push(`gates.${label}.name must match ^[a-z][a-z0-9_-]{0,31}$`);
+    if (GATE_KEYS.includes(name)) messages.push(`gates.${label}.name must not be a fixed gate name`);
+    if (names.has(name)) messages.push(`gates.${label}.name must be unique`);
+    names.add(name);
+    messages.push(...gateMessages(label, command));
+    if (Array.isArray(command.argv) && command.argv.some((arg) => typeof arg === 'string' && [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].some((token) => arg.includes(token)))) {
+      messages.push(`gates.${label}.argv: {test_files} and {changed_files} are refused in custom gates`);
+    }
+    if (evidence !== undefined) {
+      if (!Array.isArray(evidence)) messages.push(`gates.${label}.evidence must be an array of safe relative paths or simple globs`);
+      else for (const [j, pattern] of evidence.entries()) {
+        // Backslashes are refused as well so a Windows absolute/traversal path is never
+        // interpreted differently by validation and the POSIX evidence matcher.
+        if (typeof pattern !== 'string' || pattern.length === 0 || pattern.startsWith('/') || /[\\\0]/.test(pattern) || pattern.split('/').some((segment) => segment === '..' || /^[A-Za-z]:/.test(segment))) {
+          messages.push(`gates.${label}.evidence[${j}] must be a non-empty relative path or glob without absolute paths or a .. segment`);
+        }
+      }
+    }
+  }
+  return messages;
+}
+
+/** Gate names in a kind set must resolve to an available configured or detected gate.
+ * @param {Record<string, any> | undefined} gates @returns {string[]}
+ */
+export function kindGateMessages(gates) {
+  const custom = new Set(Array.isArray(gates?.custom) ? gates.custom.map((gate) => gate?.name) : []);
+  const messages = [];
+  for (const kind of BLOCK_KINDS) {
+    const names = gates?.kinds?.[kind];
+    if (!Array.isArray(names)) continue; // The schema handles invalid shapes.
+    for (const name of names) {
+      if (typeof name !== 'string') continue;
+      const label = `gates.kinds.${kind}: ${safeSegment(name)}`;
+      const fixed = GATE_KEYS.some((key) => key === name);
+      if (!fixed && !custom.has(name)) messages.push(`${label} is an unknown gate name`);
+      else if (fixed && gates[name] === null) messages.push(`${label} is a null fixed gate`);
+    }
+  }
+  return messages;
+}
+
 function checkGatesNotArgvArray(cfg) {
   const messages = GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]));
+  messages.push(...customGateMessages(cfg?.gates?.custom));
+  messages.push(...kindGateMessages(cfg?.gates));
   if (Object.hasOwn(cfg?.gates ?? {}, 'repeat_new_tests')) {
     const n = cfg.gates.repeat_new_tests;
     if (!Number.isInteger(n) || n < 2 || n > 10) messages.push('gates.repeat_new_tests must be an integer 2..10');
   }
+  if (Object.hasOwn(cfg?.gates ?? {}, 'timeout_s')) {
+    const n = cfg.gates.timeout_s;
+    if (!Number.isInteger(n) || n < 30 || n > 7200) messages.push('gates.timeout_s must be an integer 30..7200');
+  }
   return messages.map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message }));
 }
 
@@ -1181,3 +1248,18 @@ export function reviewFileLoop(cfg) {
 export function reviewWorkers(cfg) {
   return cfg?.review?.workers ?? 1;
 }
+
+/** Common generated lock files, matched at the root and at any depth. */
+export const DEFAULT_REVIEW_EXCLUDE = Object.freeze([
+  'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb',
+  'composer.lock', 'Cargo.lock', 'Gemfile.lock', 'poetry.lock', 'uv.lock', 'go.sum',
+  'Package.resolved', 'Podfile.lock', 'pubspec.lock', 'mix.lock', 'flake.lock',
+].map((name) => `**/${name}`));
+
+/** The first matching repo-relative rule, or null. A supplied list replaces the defaults.
+ * @param {Record<string, any> | null} cfg @param {string} file @returns {string | null}
+ */
+export function reviewExcludeRule(cfg, file) {
+  const rules = cfg?.review?.exclude ?? DEFAULT_REVIEW_EXCLUDE;
+  return rules.find((rule) => expandBraces(rule).some((pattern) => globMatch(file, pattern))) ?? null;
+}

package/src/context/pack.mjs

@@ -11,12 +11,13 @@
  *     require_coder_tests: false                B63b: close needs the coder's `TESTS … exit=0` line
  *
  * `assemblePack` turns it into ONE pack for a block, in this order: the header (run, block, level,
- * owned files, test files when the block has them, worktree path and branch when it has one), the
+ * owned files, test files when the block has them, worktree path and branch when it has one,
+ * code-forge command and version when supplied), the
  * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), the
- * built-in proof rule, each rules file, then the lessons file — every file section headed by its
+ * built-in proof rule, block brief and acceptance, each rules file, then the lessons file — every file section headed by its
  * source path (an empty file: the heading alone). Over `max_lines` the lessons are cut first, then the
  * rules from the last file backwards, each cut section ending in `[cut: N lines dropped]`; the
- * header, commands and proof rule are never cut; all count toward the budget.
+ * header, commands, proof rule, brief and acceptance are never cut; all count toward the budget.
  *
  * `reviewDigest` is the ONE builder of the review packets' rules digest (`## project rules`, ≤ 60
  * lines, `packet.mjs`): the rules files' text, then a `### lessons` subheading and the lessons.
@@ -238,6 +239,41 @@ const argvToken = (token) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(token) ? token : `
 /** @param {string[]} argv @returns {string} */
 export const argvText = (argv) => argv.map(argvToken).join(' ');
 
+/**
+ * Read a block's saved brief from the main tree with the same path checks as other context.
+ * Older blocks and blocks opened without --brief have no brief.
+ * @param {string} repoRoot @param {Record<string, any>} block
+ * @returns {{path: string, text: string} | null}
+ */
+export function readBlockBrief(repoRoot, block) {
+  if (typeof block.brief?.path !== 'string') return null;
+  return { path: block.brief.path, text: readLines(repoRoot, block.brief.path, 'block.brief').join('\n') };
+}
+
+/**
+ * The task sections shared by packs and coder prompts. A supplied prompt suppresses sections
+ * whose contents it already carries, independently of their Markdown formatting.
+ * @param {{brief?: {path: string, text: string} | null, acceptance?: import('../gates/acceptance.mjs').AcceptanceClause[]}} block
+ * @param {string} [prompt]
+ * @returns {string[]}
+ */
+export function blockTaskLines(block, prompt = '') {
+  const normalized = prompt.replace(/\s+/g, ' ').trim();
+  const contains = (/** @type {string} */ text) => normalized.includes(text.replace(/\s+/g, ' ').trim());
+  const lines = [];
+  if (block.brief && (!prompt || !contains(block.brief.text))) lines.push(`## brief: ${block.brief.path}`, ...splitLines(block.brief.text));
+  const missing = (block.acceptance ?? []).filter((clause) => !prompt || !contains(clause.clause)
+    || (clause.kind === 'human_check' ? !contains('human_check') : !clause.tests.every(contains)));
+  if (missing.length > 0) {
+    lines.push('## acceptance');
+    for (const clause of missing) {
+      lines.push(`- ${clause.clause}`);
+      lines.push(clause.kind === 'human_check' ? '  kind: human_check' : `  tests: ${clause.tests.join(', ')}`);
+    }
+  }
+  return lines.length === 0 ? [] : splitLines(/** @type {string} */ (redact(lines.join('\n'))));
+}
+
 /**
  * @typedef {object} PackBlock
  * @property {string} run
@@ -246,6 +282,9 @@ export const argvText = (argv) => argv.map(argvToken).join(' ');
  * @property {string[]} [owned]
  * @property {string[] | null} [tests]
  * @property {{path: string, branch: string} | null} [worktree]
+ * @property {{node: string, bin: string, version: string} | null} [codeForge]
+ * @property {{path: string, text: string} | null} [brief]
+ * @property {import('../gates/acceptance.mjs').AcceptanceClause[]} [acceptance]
  */
 
 /**
@@ -259,6 +298,7 @@ export function assemblePack({ settings, sources, block }) {
   /** @type {Array<[string, unknown]>} */
   const values = [['level', block.level], ...(block.owned ?? []).map((f) => /** @type {[string, unknown]} */ (['owned file', f])), ...(block.tests ?? []).map((f) => /** @type {[string, unknown]} */ (['test file', f]))];
   if (block.worktree) values.push(['worktree path', block.worktree.path], ['worktree branch', block.worktree.branch]);
+  if (block.codeForge) values.push(['code-forge node', block.codeForge.node], ['code-forge bin', block.codeForge.bin], ['code-forge version', block.codeForge.version]);
   for (const [label, v] of values) {
     if (typeof v === 'string' && CONTROL.test(v)) throw new ContextError('control-character', `block ${block.block}: ${label} ${JSON.stringify(v)} contains a control character`);
   }
@@ -269,6 +309,14 @@ export function assemblePack({ settings, sources, block }) {
     for (const f of block.tests) header.push(`- ${f}`);
   }
   if (block.worktree) header.push(`worktree: ${block.worktree.path}`, `branch: ${block.worktree.branch}`);
+  if (block.codeForge) {
+    header.push(
+      '## code-forge',
+      `run code-forge verbs with exactly: ${argvText([block.codeForge.node, block.codeForge.bin])}`,
+      `version: ${block.codeForge.version}`,
+      'do not use another code-forge from PATH',
+    );
+  }
   if (settings !== null) {
     header.push('## commands (never run by code-forge)');
     const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
@@ -278,6 +326,8 @@ export function assemblePack({ settings, sources, block }) {
   }
 
   header.push(...splitLines(PROOF_RULE));
+  // The actual task is protected from the optional rules/lessons line budget too.
+  header.push(...blockTaskLines(block));
 
   /** @type {Array<{heading: string, body: string[], dropped: number}>} */
   const sections = sources.rules.map((r) => ({ heading: `## rules: ${r.path}`, body: [...r.lines], dropped: 0 }));

package/src/doctor/index.mjs

@@ -11,6 +11,8 @@ import { mkdirSync, rmSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+import { modelStats, reviewerLines } from '../review/model-stats.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
 import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkLocks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
@@ -53,6 +55,15 @@ export async function runDoctor(opts = {}, deps = {}) {
   const keys = await checkKeys(cfg, { env, store: deps.store, opRead: deps.opRead });
   /** @type {Row[]} */
   const rows = [...checked.rows, ...links, ...keys.rows];
+  if (cfg?.project?.slug) {
+    try {
+      const lines = reviewerLines(modelStats(await readAllRows(cfg.project.slug), cfg.review?.adaptive));
+      rows.push(...lines.map((line, i) => {
+        const at = line.indexOf(': ');
+        return row(`reviewer.${i}`, 'INFO', line.slice(0, at), line.slice(at + 2));
+      }));
+    } catch { /* a corrupt ledger is diagnosed by the existing ledger check */ }
+  }
   if (opts.quick) return rows;
 
   if (cfg) {

package/src/doctor/local.mjs

@@ -24,7 +24,7 @@ import { snapshotFor } from '../state/config-snapshot.mjs';
 import { assertRunId, runsDir } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { loadKey } from '../state/signer.mjs';
-import { listEntries } from '../util/reaper.mjs';
+import { listEntries, sweepProcesses } from '../util/reaper.mjs';
 import { listBadLocks } from '../util/file-locks.mjs';
 import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
@@ -257,14 +257,15 @@ export const LISTED_MAX = 10;
  * @returns {Promise<Row[]>}
  */
 export async function checkReviewState(cfg) {
+  // This awaited local-check slot also supplies process hygiene and memory rows. All are
+  // observational; doctor never applies a sweep.
+  const rows = await checkSweep(cfg);
   let names = [];
   try {
     names = readdirSync(runsDir()).filter((n) => n.endsWith('.json'));
   } catch {
-    return [];
+    return rows;
   }
-  /** @type {Row[]} */
-  const rows = [];
   /** @type {Map<string, Array<Record<string, any>>>} the ledger rows per project, read once */
   const ledgers = new Map();
   for (const name of names.sort()) {
@@ -319,6 +320,23 @@ export async function checkReviewState(cfg) {
   return rows;
 }
 
+/** Read-only process hygiene and RSS rows. @param {Record<string,any>|null} cfg @returns {Promise<Row[]>} */
+export async function checkSweep(cfg) {
+  try {
+    const report = await sweepProcesses({ root: typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined });
+    const workers = report.items.filter((p) => p.kind === 'worker').length;
+    const orphans = report.items.filter((p) => p.kind === 'orphan').length;
+    const zombies = report.zombies.reduce((n, group) => n + group.count, 0);
+    const parents = report.zombies.map((group) => `parent ${group.ppid} ${group.command}`).join('; ');
+    const memory = report.memory;
+    return [row('sweep', workers + orphans + zombies ? 'WARN' : 'OK', 'sweep',
+      `${workers} stale workers, ${orphans} orphans, ${zombies} zombies${parents ? ` (${parents})` : ''}`),
+    row('memory', 'INFO', 'memory', `code-forge ${memory.codeForgeMb.toFixed(1)} MB, children ${memory.childrenMb.toFixed(1)} MB, orphans ${memory.orphansMb.toFixed(1)} MB`)];
+  } catch {
+    return [row('sweep', 'WARN', 'sweep', 'process inspection unavailable'), row('memory', 'INFO', 'memory', 'process inspection unavailable')];
+  }
+}
+
 /**
  * B44: the `review concurrency` INFO row — how many review tickets run at once and each provider's
  * session slots, from the effective config (defaults when a key is unset). Never throws.

package/src/doctor/worker-probe.mjs

@@ -69,7 +69,7 @@ function removeRun(runId) {
   } catch {
     return;
   }
-  for (const name of names) if (name === `${runId}.json` || name === `${runId}.key` || name === `${runId}.lock` || name.startsWith(`${runId}.json.`)) rmSync(path.join(runsDir(), name), { recursive: true, force: true });
+  for (const name of names) if (name === runId || name === `${runId}.json` || name === `${runId}.key` || name === `${runId}.lock` || name.startsWith(`${runId}.json.`)) rmSync(path.join(runsDir(), name), { recursive: true, force: true });
 }
 
 /**

package/src/engines/builders/codex.mjs

@@ -60,6 +60,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 import { mergeForbidden, renderForCodex } from '../../util/forbidden.mjs';
 import { CODEX_RULES_FILE_NAME, defaultCodexHome, isInside, prepareCodexHome } from '../codex-home.mjs';
 import { hasAnyRenderedRule } from '../render-rules.mjs';
@@ -129,7 +130,7 @@ export const VALID_EFFORTS = PROVIDER_EFFORTS.openai;
  *   `coder.sandbox` config value. Absent ⇒ today's argv. `toolchain` adds one `--add-dir <abs>`
  *   per checked `add_dirs` entry; `full` builds `-s danger-full-access`. A refused entry throws
  *   a `SandboxDirError` (code `sandbox-dir-refused`) naming the key path, never the value.
- * @property {string} [runRoot] - B93, coder role only: the run temp root, refused as an `add_dirs` tree.
+ * @property {string} [runRoot] - coder role only: owns the session home and is refused as an `add_dirs` tree.
  */
 
 /**
@@ -166,7 +167,8 @@ function assertValidEffort(effort) {
  * The Codex coder argv itself — pure, no I/O, no rules file (B4.2). `buildCoderArgv` uses it, and
  * the doctor's flags probe builds it with placeholder values for its static conflict check.
  * B93: `profile` `full` swaps `-s workspace-write` for `-s danger-full-access`; `addDirs` (already
- * checked and resolved, `toolchain` only) follow `-s workspace-write` as `--add-dir <abs>` pairs.
+ * checked and resolved) follow `-s workspace-write` as `--add-dir <abs>` pairs, including the
+ * private Git directory and shared objects/refs/logs needed to commit from a linked worktree.
  * The tmp exclusions stay in every profile: under `danger-full-access` Codex ignores the
  * `sandbox_workspace_write.*` keys, and one argv shape keeps the forbidden-list check the same.
  * @param {{model: string, effort?: string, cwd: string, outPath: string, promptPath: string, profile?: string, addDirs?: ReadonlyArray<string>}} p
@@ -180,11 +182,11 @@ export function coderFlagArgv({ model, effort, cwd, outPath, promptPath, profile
     argv.push('-s', 'danger-full-access');
   } else {
     argv.push('-s', 'workspace-write');
-    if (profile === 'toolchain') for (const dir of addDirs) argv.push('--add-dir', dir);
+    for (const dir of addDirs) argv.push('--add-dir', dir);
   }
   // INVARIANT (B4.1 fix round 1): the session CODEX_HOME lives under the run temp root, so the
-  // sandbox must not make $TMPDIR or /tmp writable — the project cwd is then the only writable
-  // root, and a home inside the cwd is refused below. See `../codex-home.mjs`.
+  // sandbox must not make $TMPDIR or /tmp writable. The project cwd and added directories are
+  // writable roots; a home inside the cwd is refused below. See `../codex-home.mjs`.
   argv.push(...SANDBOX_TMP_EXCLUSIONS);
   // B4.2: NO `--approve-for-me` (Codex 0.155.1 refuses it next to `-s`); see CODER_APPROVAL_POLICY.
   argv.push(...CODER_APPROVAL_POLICY);
@@ -215,6 +217,23 @@ function coderSandbox(sandbox, extra) {
   return { profile, addDirs: profile === 'toolchain' ? checked.dirs : [] };
 }
 
+/**
+ * A linked worktree needs its private gitdir and the shared objects/refs/logs writable.
+ * Never grant the common dir itself: its config and hooks can execute code on the host.
+ * Normal checkouts (equal Git dirs), non-repositories and placeholder cwds need no extra root.
+ * @param {string} cwd @returns {string[]}
+ */
+function worktreeGitDirs(cwd) {
+  try {
+    const [gitDir, commonDir] = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000,
+    }).trim().split('\n');
+    return gitDir !== commonDir ? [gitDir, ...['objects', 'refs', 'logs'].map((name) => path.join(commonDir, name))] : [];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * @param {CodexBuildParams} params
  * @returns {{cli: "codex", role: "coder", argv: string[], cwd: string, outPath: string, env: {CODEX_HOME: string}, forbiddenRendered: ReadonlyArray<RenderedCodexEntry>, rulesFile: {fileName: string, path: string, content: string, count: number}}}
@@ -226,7 +245,7 @@ function buildCoderArgv(params) {
   if (!hasAnyRenderedRule(renderedForbidden)) {
     throw new Error('buildCodexArgv: coder role requires a non-empty forbidden-list render (got 0 usable patterns)');
   }
-  const codexHome = params.codexHome ?? defaultCodexHome();
+  const codexHome = params.codexHome ?? defaultCodexHome(params.runRoot);
   // Fix round 4: a non-absolute home is refused here, before any I/O, and the containment check
   // below then runs EVERY time (no `isAbsolute` short-circuit that could skip it).
   if (typeof codexHome !== 'string' || !path.isAbsolute(codexHome)) {
@@ -241,8 +260,9 @@ function buildCoderArgv(params) {
   // B93 (fix round 1): the sandbox dirs are checked only after the home is known to be absolute
   // and outside the cwd, so the home they are checked against is the one the session will use.
   const sandbox = coderSandbox(params.sandbox, [codexHome, params.runRoot, tmpBase()]);
+  if (sandbox.profile !== 'full') sandbox.addDirs = [...new Set([...sandbox.addDirs, ...worktreeGitDirs(cwd)])];
   const argv = coderFlagArgv({ model, effort, cwd, outPath, promptPath, ...sandbox });
-  const home = prepareCodexHome(codexHome, renderedForbidden);
+  const home = prepareCodexHome(codexHome, renderedForbidden, { runRoot: params.runRoot });
   return {
     cli: CLI,
     role: 'coder',

package/src/engines/builders/grok.mjs

@@ -17,7 +17,7 @@
  * swallow risk the way `claude.mjs`'s BLOCKER fix had to guard against, since each `--deny`
  * occurrence's value slot is exactly one token wide.
  *
- * **Return contract (fix round 3):** `{cli, role, argv, cwd, forbiddenRendered?}` — never a
+ * **Return contract (fix round 3):** `{cli, role, argv, cwd, env, forbiddenRendered?}` — never a
  * `stdinFile`. Unlike Claude/Codex closed-book runs, Grok's `--prompt-file <PATH>` ("Single-turn
  * prompt from a file", pinned help) makes the CLI itself read the packet and send its CONTENT as
  * the prompt, so even a closed-book run with every tool denied receives the packet text; the
@@ -41,6 +41,12 @@ import { assertBaseParams } from './validate-params.mjs';
 
 export const CLI = 'grok';
 
+/** Disable automatic loading of Cursor and Claude compatibility MCP servers for every role. */
+export const GROK_NO_COMPAT_MCP_ENV = Object.freeze({
+  GROK_CURSOR_MCPS_ENABLED: 'false',
+  GROK_CLAUDE_MCPS_ENABLED: 'false',
+});
+
 /**
  * Built-in tool names the closed-book command denies wholesale via `--disallowed-tools` (in
  * addition to the wildcard `--deny "*"`, per plan §5.2). Not independently verified against a
@@ -78,7 +84,7 @@ function assertValidEffort(effort) {
 
 /**
  * @param {GrokBuildParams} params
- * @returns {{cli: "grok", role: "coder", argv: string[], cwd: string, forbiddenRendered: ReadonlyArray<RenderedGrokEntry>}}
+ * @returns {{cli: "grok", role: "coder", argv: string[], cwd: string, env: typeof GROK_NO_COMPAT_MCP_ENV, forbiddenRendered: ReadonlyArray<RenderedGrokEntry>}}
  */
 function buildCoderArgv(params) {
   // B4.2: the coder's deny list is `mergeForbidden()` (FORBIDDEN + the coder-only entries). A
@@ -95,12 +101,12 @@ function buildCoderArgv(params) {
   for (const rule of flattenRuleStrings(renderedForbidden)) {
     argv.push('--deny', rule);
   }
-  return { cli: CLI, role: 'coder', argv, cwd, forbiddenRendered: renderedForbidden };
+  return { cli: CLI, role: 'coder', argv, cwd, env: GROK_NO_COMPAT_MCP_ENV, forbiddenRendered: renderedForbidden };
 }
 
 /**
  * @param {GrokBuildParams} params
- * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string}}
+ * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string, env: typeof GROK_NO_COMPAT_MCP_ENV}}
  */
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schema, systemPromptText } = params;
@@ -119,7 +125,7 @@ function buildClosedBookArgv(params) {
   argv.push('--permission-mode', 'dontAsk');
   argv.push('--cwd', cwd);
   if (systemPromptText !== undefined) argv.push('--system-prompt-override', systemPromptText);
-  return { cli: CLI, role, argv, cwd };
+  return { cli: CLI, role, argv, cwd, env: GROK_NO_COMPAT_MCP_ENV };
 }
 
 /**

package/src/engines/codex-home.mjs

@@ -30,7 +30,8 @@
  * under the run temp root; the builder runs the coder with `-s workspace-write` PLUS
  * `-c sandbox_workspace_write.exclude_tmpdir_env_var=true` and
  * `-c sandbox_workspace_write.exclude_slash_tmp=true` (both keys are in the 0.155.1 binary), so the
- * only writable root is the project `-C <cwd>` — and a home inside that cwd is refused. On top, the
+ * writable roots are the project `-C <cwd>` and added sandbox directories (including a linked
+ * worktree's common Git directory) — and a home inside that cwd is refused. On top, the
  * rules file is 0444. The directories stay 0700, not 0555: a 0555 directory makes the run-root
  * sweep's `rmSync(…, {recursive, force})` fail (ENOTEMPTY, checked on this Mac), which would leave
  * the whole run root — the auth copy included — behind. Tradeoff of the tmp exclusion: the coder's
@@ -113,29 +114,30 @@ export function renderCodexRules(rendered) {
 /** The name of the run-root directory every session home lives in. */
 export const CODEX_HOMES_DIR_NAME = 'codex-homes';
 
-/** @returns {string} `<currentRunRoot()>/codex-homes`, the one parent of every session home. */
-export function sessionCodexHomesDir() {
-  return path.join(currentRunRoot(), CODEX_HOMES_DIR_NAME);
+/** @param {string} [runRoot] @returns {string} `<runRoot>/codex-homes`, the parent of the run's session homes. */
+export function sessionCodexHomesDir(runRoot = currentRunRoot()) {
+  return path.join(runRoot, CODEX_HOMES_DIR_NAME);
 }
 
 /**
- * Whether `candidate` is STRICTLY inside `<currentRunRoot()>/codex-homes/` (both sides
+ * Whether `candidate` is STRICTLY inside `<runRoot>/codex-homes/` (both sides
  * symlink-resolved through their nearest existing ancestor). The directory itself, the run root,
  * the real Codex home, `$HOME` and any sibling are all outside.
- * @param {string} candidate @returns {boolean}
+ * @param {string} candidate @param {string} [runRoot] @returns {boolean}
  */
-export function isSessionCodexHome(candidate) {
+export function isSessionCodexHome(candidate, runRoot = currentRunRoot()) {
   if (typeof candidate !== 'string' || !path.isAbsolute(candidate)) return false;
-  const rel = path.relative(resolveExisting(sessionCodexHomesDir()), resolveExisting(candidate));
+  const rel = path.relative(resolveExisting(sessionCodexHomesDir(runRoot)), resolveExisting(candidate));
   return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
 /**
  * A fresh per-session Codex home path under the run temp root.
+ * @param {string} [runRoot]
  * @returns {string}
  */
-export function defaultCodexHome() {
-  return path.join(sessionCodexHomesDir(), `coder-${randomBytes(6).toString('hex')}`);
+export function defaultCodexHome(runRoot = currentRunRoot()) {
+  return path.join(sessionCodexHomesDir(runRoot), `coder-${randomBytes(6).toString('hex')}`);
 }
 
 /**
@@ -143,7 +145,7 @@ export function defaultCodexHome() {
  * `auth.json` (0600) when it exists.
  * @param {string} codexHome - absolute; never the real Codex home or inside it.
  * @param {ReadonlyArray<CodexRenderedEntry>} rendered
- * @param {{env?: NodeJS.ProcessEnv}} [opts]
+ * @param {{env?: NodeJS.ProcessEnv, runRoot?: string}} [opts]
  * @returns {{codexHome: string, rulesPath: string, count: number, content: string}}
  * @throws {Error} when `codexHome` is relative, is (or is inside) the real Codex home, or the
  *   render yields 0 rules.
@@ -159,7 +161,7 @@ export function prepareCodexHome(codexHome, rendered, opts = {}) {
   // Fix round 4: an ANCESTOR of the real home (`$HOME`, `/`) is not "inside" it, yet a home there
   // would put `rules/` and an auth copy where the user lives. The only place a session home may be
   // is strictly inside `<run root>/codex-homes/` — the same confinement `removeCodexHome` enforces.
-  if (!isSessionCodexHome(codexHome)) {
+  if (!isSessionCodexHome(codexHome, opts.runRoot)) {
     throw new Error(`prepareCodexHome: codexHome must be strictly inside <run root>/${CODEX_HOMES_DIR_NAME}/`);
   }
   const { content, count } = renderCodexRules(rendered);
@@ -215,15 +217,16 @@ function writeFreshFile(dest, bytes, mode) {
 
 /**
  * Remove a session home (the auth copy with it). The ONLY recursive delete of this module, and it
- * is confined (fix round 3): `codexHome` must be strictly inside `<currentRunRoot()>/codex-homes/`
+ * is confined (fix round 3): `codexHome` must be strictly inside `<runRoot>/codex-homes/`
  * after realpath resolution, or this throws and deletes nothing — the real `~/.codex`, `$HOME`,
  * the run root itself and any sibling directory are refused. No-op when the (confined) path does
  * not exist.
  * @param {string} codexHome
+ * @param {string} [runRoot] - the same run root used to prepare the home.
  * @throws {Error} when `codexHome` is not strictly inside the run root's `codex-homes/`.
  */
-export function removeCodexHome(codexHome) {
-  if (!isSessionCodexHome(codexHome)) {
+export function removeCodexHome(codexHome, runRoot = currentRunRoot()) {
+  if (!isSessionCodexHome(codexHome, runRoot)) {
     throw new Error(`removeCodexHome: refusing to delete a path outside <run root>/${CODEX_HOMES_DIR_NAME}/`);
   }
   rmSync(resolveExisting(codexHome), { recursive: true, force: true });

package/src/engines/sentinel.mjs

@@ -53,6 +53,17 @@ export function parseSentinel(output, blockId) {
   if (typeof output !== 'string') {
     throw new TypeError('parseSentinel: output must be a string');
   }
+  // CLI reports can contain the answer as a JSON string or as a string field in an envelope.
+  // Decode real JSON only: replacing literal \\n would also change ordinary prose and paths.
+  try {
+    const decoded = JSON.parse(output);
+    if (typeof decoded === 'string') output = decoded;
+    else if (decoded !== null && typeof decoded === 'object' && !Array.isArray(decoded)) {
+      output = Object.values(decoded).filter((value) => typeof value === 'string').join('\n');
+    }
+  } catch {
+    // A plain transcript (or malformed JSON) keeps the existing whole-line parser.
+  }
   /** @type {SentinelResult | null} */
   let last = null;
   /** @type {TestsLine | null} */

package/src/gates/detect.mjs

@@ -20,7 +20,9 @@ import path from 'node:path';
  * `run.mjs` treats non-empty stdout as red too, since a bare exit-code check can never fail.
  * B60: a configured gate may be `{argv, env}` — `env` adds variables to the gate's environment
  * (the values are never printed, `run.mjs`).
- * @typedef {string[] | {argv: string[], failOnStdout?: true, env?: Record<string, string>}} GateCommand
+ * `formatter` marks detected defaults that require an explicit Git file set. Configured
+ * commands have no such marker and retain their own arguments and scope.
+ * @typedef {string[] | {argv: string[], failOnStdout?: true, env?: Record<string, string>, formatter?: 'pint'|'prettier'}} GateCommand
  * @typedef {GateCommand | null} Gate
  */
 /**
@@ -69,7 +71,8 @@ function detectPhp(root) {
   if (runner === null) return null;
   const test = has(root, 'artisan') ? ['php', 'artisan', 'test', '--compact'] : [`vendor/bin/${runner}`];
   const types = has(root, 'phpstan.neon') || has(root, 'phpstan.neon.dist') ? ['vendor/bin/phpstan'] : null;
-  const format = has(root, 'pint.json') || has(root, 'vendor/bin/pint') ? ['vendor/bin/pint', '--test'] : null;
+  const format = has(root, 'pint.json') || has(root, 'vendor/bin/pint')
+    ? { argv: ['vendor/bin/pint', '--test'], formatter: /** @type {const} */ ('pint') } : null;
   return { stack: `php-${runner}`, test, lint: null, types, format };
 }
 
@@ -123,7 +126,7 @@ function detectNode(root) {
   let format = null;
   if (typeof scripts['format:check'] === 'string') format = [pm, 'run', 'format:check'];
   else if (has(root, '.prettierrc') || has(root, '.prettierrc.json') || has(root, '.prettierrc.js') || hasDependency(pkg, 'prettier')) {
-    format = ['npx', 'prettier', '--check', '.'];
+    format = { argv: ['npx', 'prettier', '--check', '--ignore-unknown'], formatter: /** @type {const} */ ('prettier') };
   }
 
   return { stack: 'node', test, lint, types, format };