@codedology/code-forge 0.5.1 → 0.6.1

package/src/cli/spawn.mjs

@@ -10,12 +10,11 @@
 
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { loadProjectConfig } from '../config/load.mjs';
+import { loadProjectConfig, projectRootFor, slugFor } from '../config/load.mjs';
 import { ROLES, runRootFor, SessionError, spawnSession } from '../session/spawn.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
 import { writeSafe } from '../util/redact.mjs';
-import { slugFor } from './run.mjs';
 
 /**
  * @param {string} file @param {string} flag
@@ -61,7 +60,9 @@ export async function runSpawn(args, deps = {}) {
       writeSafe(stderr, USAGE);
       return 2;
     }
-    const loaded = await loadProjectConfig(process.cwd());
+    // B50: the project root's config and ledger slug, also from a subfolder
+    const root = projectRootFor(process.cwd());
+    const loaded = await loadProjectConfig(root);
     if (!loaded.ok) {
       writeSafe(stderr, `spawn: ${loaded.message}\n`);
       return 2;
@@ -82,7 +83,7 @@ export async function runSpawn(args, deps = {}) {
         runRoot: typeof flags.run === 'string' ? runRootFor(flags.run, cfg?.tmp?.root) : undefined,
         run: typeof flags.run === 'string' ? flags.run : undefined,
         block: typeof flags.block === 'string' ? flags.block : undefined,
-        slug: slugFor(cfg, process.cwd()),
+        slug: slugFor(cfg, root),
       },
       { ...deps, stderr },
     );

package/src/config/closed-book.mjs

@@ -13,6 +13,11 @@
  *
  * Opt-in (default off): `review.allow_open_book_codex: true` lets Codex run those roles with its
  * read-only argv; every surface then shows {@link OPEN_BOOK_CODEX_WARNING} instead of refusing.
+ *
+ * B46: the autopilot `delegate` is closed-book too, and the opt-in does NOT open it
+ * ({@link NEVER_OPEN_BOOK_ROLES}): the delegate decides FOR the owner while the owner is away, so
+ * a delegate that could read files on this machine (a coder-written note, a planted "the owner
+ * says yes") would be deciding on material nobody vetted. Codex is refused for it, always.
  */
 
 /** The text every refusal prints: the builder, the spawner, `doctor`, `validate`, `resolve`. */
@@ -36,7 +41,13 @@ export function openBookCodexAllowed(cfg) {
 export const NO_CLOSED_BOOK_PROVIDER = 'openai';
 
 /** Roles that must run with no tools (facts is not one: it has read-only tools by design). */
-export const NO_TOOL_ROLES = Object.freeze(['reviewer', 'judge', 's2', 'author']);
+export const NO_TOOL_ROLES = Object.freeze(['reviewer', 'judge', 's2', 'author', 'delegate']);
+
+/**
+ * No-tools roles that `review.allow_open_book_codex` never opens (B46): the autopilot delegate
+ * decides for the owner, so it only ever runs with no tools at all.
+ */
+export const NEVER_OPEN_BOOK_ROLES = Object.freeze(['delegate']);
 
 /** Levels whose sessions are closed-book: L2 (reviewers), L3 (judge, S2, author). */
 export const CLOSED_BOOK_LEVELS = Object.freeze(['L2', 'L3']);
@@ -56,6 +67,11 @@ export function isNoToolRole(role) {
   return NO_TOOL_ROLES.includes(norm(role));
 }
 
+/** @param {unknown} role @returns {boolean} true when `role` (any case) is never opened by the opt-in. */
+export function isNeverOpenBookRole(role) {
+  return NEVER_OPEN_BOOK_ROLES.includes(norm(role));
+}
+
 /**
  * @param {unknown} provider @param {unknown} role - compared lowercased and trimmed.
  * @returns {boolean} true when `provider` cannot run `role` closed-book.
@@ -68,8 +84,9 @@ export function needsClosedBook(provider, role) {
  * @param {unknown} provider @param {unknown} role @param {boolean} openBookAllowed - the config's
  *   opt-in, read once by the caller with {@link openBookCodexAllowed}.
  * @returns {boolean} true when the session must be refused: `provider` cannot run `role`
- *   closed-book and the config has not opted in to open-book Codex.
+ *   closed-book and the config has not opted in to open-book Codex — or the role is one the
+ *   opt-in never opens (the delegate, B46).
  */
 export function closedBookRefused(provider, role, openBookAllowed) {
-  return needsClosedBook(provider, role) && openBookAllowed !== true;
+  return needsClosedBook(provider, role) && (openBookAllowed !== true || isNeverOpenBookRole(role));
 }

package/src/config/load.mjs

@@ -15,7 +15,9 @@
  * (`err.pos`) and the source string — never from anything the `yaml` package formats for display.
  */
 
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { parse as parseYAML } from 'yaml';
 import { migrateConfig } from './migrate.mjs';
@@ -131,5 +133,115 @@ export async function loadConfigFile(filePath) {
  * @returns {Promise<LoadResult>}
  */
 export async function loadProjectConfig(cwd = process.cwd()) {
-  return loadConfigFile(path.join(cwd, DEFAULT_CONFIG_FILENAME));
+  // B50: always the PROJECT ROOT's config ({@link projectRootFor}; idempotent when `cwd` is the
+  // root). A symlinked `.code-forge.yml` (dotfiles) loads like a file; a directory there is a `read-error`.
+  return loadConfigFile(path.join(projectRootFor(cwd), DEFAULT_CONFIG_FILENAME));
+}
+
+/**
+ * The nearest ancestor of `start` (itself included) that holds `marker`, or null.
+ * @param {string} start @param {string} marker
+ * @returns {string | null}
+ */
+function nearestWith(start, marker) {
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, marker))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** @param {string} p @returns {boolean} true when `p` is (or links to) a regular file — a symlinked config (dotfiles) counts, a directory never. */
+function isRegularFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} p @returns {string} `p` realpath'd, or resolved as given when it cannot be. */
+function realOrResolved(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * The project root a verb run from `start` belongs to (B50). The git top level is found first
+ * (the nearest ancestor holding a `.git` directory or worktree file — a filesystem walk, no child
+ * `git`); the root is then the nearest folder from `start` up to AND INCLUDING that top level whose
+ * `.code-forge.yml` is a regular file (a symlink to one counts; a directory never), else the top
+ * level itself — a config above the repository never counts. Outside git, the same search runs
+ * from `start` up to the home directory (never past it) when `start` is under it, and looks at
+ * `start` alone when it is not (`/tmp/x`, `/opt/ci`: a stray config higher up never counts); found
+ * nothing ⇒ the root is `start`. Every walk runs on realpaths; the root comes back in the caller's
+ * spelling when an ancestor of the start as given resolves to it ({@link inCallerSpelling}). A verb
+ * run from a subfolder thus finds the project's config and ledger slug. Synchronous (no child process).
+ * @param {string} [start] - defaults to `process.cwd()`.
+ * @returns {string} absolute.
+ */
+export function projectRootFor(start = process.cwd()) {
+  return inCallerSpelling(start, resolvedRootFor(realOrResolved(start)));
+}
+
+/**
+ * The root on realpaths: the git walk, the config walk and the HOME check all run on the resolved
+ * start, so a symlink into a repository finds its `.git`.
+ * @param {string} from - the realpath of the start.
+ * @returns {string} a realpath.
+ */
+function resolvedRootFor(from) {
+  const home = realOrResolved(os.homedir());
+  // a `.git` at HOME itself (a dotfiles repository) never makes HOME the project: outside git
+  const gitRoot = nearestWith(from, '.git');
+  if (gitRoot !== null && gitRoot !== home) return nearestConfigUpTo(from, gitRoot) ?? gitRoot;
+  const underHome = from === home || from.startsWith(`${home}${path.sep}`);
+  if (!underHome) return from; // the start alone: its own config (if any) or not, the root is the start
+  return nearestConfigUpTo(from, home) ?? from;
+}
+
+/**
+ * The root in the caller's spelling when it can be: the ancestor of `path.resolve(start)` (itself
+ * included) whose realpath IS the resolved root (`~/work/app` → `/data/app-v2` keeps `app`, and its
+ * slug); none ⇒ the realpath itself.
+ * @param {string} start @param {string} realRoot
+ * @returns {string}
+ */
+function inCallerSpelling(start, realRoot) {
+  for (let dir = path.resolve(start); ; dir = path.dirname(dir)) {
+    if (realOrResolved(dir) === realRoot) return dir;
+    if (path.dirname(dir) === dir) return realRoot;
+  }
+}
+
+/**
+ * The nearest folder from `from` up to and including `stop` whose `.code-forge.yml` is a regular file.
+ * @param {string} from @param {string} stop - an ancestor of `from` (or `from` itself).
+ * @returns {string | null}
+ */
+function nearestConfigUpTo(from, stop) {
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    if (isRegularFile(path.join(dir, DEFAULT_CONFIG_FILENAME))) return dir;
+    if (dir === stop || path.dirname(dir) === dir) return null;
+  }
+}
+
+/**
+ * `project.slug` from config, else the PROJECT ROOT's directory name ({@link projectRootFor} of
+ * `workspace`, B50: a subfolder never names the ledger) as a ledger slug. The configured
+ * value is NOT trusted here: `startRun` refuses any slug outside `/^[a-z0-9][a-z0-9-]*$/`
+ * (`bad-project`) before anything is written, so `../x` never reaches the ledger path. Run ids
+ * are checked the same way by the state layer (`assertRunId`, `bad-run-id`).
+ * `cfg` MUST be the config loaded from `projectRootFor(workspace)` (never the cwd's), or a
+ * configured `project.slug` is lost from a subfolder and the ledger splits.
+ * @param {Record<string, any>} cfg @param {string} workspace
+ * @returns {string}
+ */
+export function slugFor(cfg, workspace) {
+  const configured = cfg?.project?.slug;
+  if (typeof configured === 'string' && configured.length > 0) return configured;
+  const derived = path.basename(projectRootFor(workspace)).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return derived || 'project';
 }

package/src/doctor/probes.mjs

@@ -2,7 +2,9 @@
  * Doctor rows that run the provider CLIs (plan §2.3, §0.6; block B13b):
  *  - per CLI: present + version + `--help` flag probe (B4 `probeHelpText`; a missing flag FAILs);
  *  - one real call per role builder (coder, reviewer, s2 with the compiled S2 schema, facts) through
- *    B9a `spawnSession` — an HTTP 402 is `ping=skipped(402)` WARN, never FAIL (§0.6.1);
+ *    B9a `spawnSession` — an HTTP 402 is `ping=skipped(402)` WARN, never FAIL (§0.6.1); when the
+ *    config has an `autopilot` section (B46), one `delegate` ping per delegate level (L2, L3) with
+ *    the delegate schema — an openai level FAILs unrun whatever `review.allow_open_book_codex` says;
  *  - the isolation probe (O4, §0.6.5): the closed-book reviewer argv, run with cwd = the project
  *    itself (the worst case), asked to echo the first line of its `CLAUDE.md`/`AGENTS.md` — the
  *    line appearing in its answer FAILs; the CLI rejecting the closed-book flag combination FAILs;
@@ -33,6 +35,8 @@ import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { commandOnPath } from '../install/detect.mjs';
 import { classifyUnavailable, readAnswer, spawnSession } from '../session/spawn.mjs';
 import { S2_SCHEMA } from '../session/s2.mjs';
+import { DELEGATE_SCHEMA } from '../autopilot/delegate.mjs';
+import { DELEGATE_LEVELS } from '../autopilot/scopes.mjs';
 import { runsDir } from '../state/paths.mjs';
 import { exec } from '../util/exec.mjs';
 import { gitChildEnv } from '../worker/ticket.mjs';
@@ -48,6 +52,23 @@ export const PING_ROLES = Object.freeze([
   { role: 's2', level: 'L3' },
 ]);
 
+/**
+ * B46: the delegate pings, one per level a grant may name — run only when the config has an
+ * `autopilot` section (a project that never uses autopilot pays for no extra call).
+ * @param {Record<string, any>} cfg @returns {Array<{role: string, level: string, id: string}>}
+ */
+export function delegatePings(cfg) {
+  const on = cfg?.autopilot !== null && typeof cfg?.autopilot === 'object';
+  return on ? DELEGATE_LEVELS.map((level) => ({ role: 'delegate', level, id: `ping.delegate.${level}` })) : [];
+}
+
+/** What each schema'd ping is told to answer, so a working CLI matches the schema. */
+const PING_ANSWER = Object.freeze({
+  s2: 'Answer with decision "proceed", confidence 1, reason "ping", overrule false, ask_human false, human_question null.\n',
+  delegate: 'Answer with decision "proceed", within_scope true, confidence 1, reason "ping", escalate false.\n',
+});
+const PING_SCHEMA = Object.freeze({ s2: S2_SCHEMA, delegate: DELEGATE_SCHEMA });
+
 const LEVELS = Object.freeze(['L0', 'L1', 'L2', 'L3']);
 const PROBE_TIMEOUT_MS = 180000;
 const PROBE_BUDGET_USD = 0.5;
@@ -196,28 +217,30 @@ function levelName(cfg, level) {
  */
 export async function pingRoles(ctx, missingProviders) {
   const rows = [];
-  for (const { role, level } of PING_ROLES) {
-    const label = `ping ${role} (${levelName(ctx.cfg, level)})`;
+  const pings = [...PING_ROLES.map((p) => ({ ...p, id: `ping.${p.role}` })), ...delegatePings(ctx.cfg)];
+  for (const { role, level, id } of pings) {
+    const label = role === 'delegate' ? `ping delegate ${level} (${levelName(ctx.cfg, level)})` : `ping ${role} (${levelName(ctx.cfg, level)})`;
     const provider = ctx.cfg.levels?.[level]?.provider ?? ctx.cfg.provider;
     if (missingProviders.has(provider)) {
-      rows.push(row(`ping.${role}`, 'FAIL', label, 'ping=skipped(cli-missing)'));
+      rows.push(row(id, 'FAIL', label, 'ping=skipped(cli-missing)'));
       continue;
     }
     if (closedBookRefused(resolvedProvider(ctx.cfg, /** @type {'L0'|'L1'|'L2'|'L3'} */ (level)), role, openBookCodexAllowed(ctx.cfg))) {
-      rows.push(row(`ping.${role}`, 'FAIL', label, CODEX_CLOSED_BOOK_REFUSAL)); // B32: the spawner would refuse it
+      rows.push(row(id, 'FAIL', label, CODEX_CLOSED_BOOK_REFUSAL)); // B32/B46: the spawner would refuse it
       continue;
     }
+    const schemaRole = /** @type {'s2' | 'delegate' | null} */ (role === 's2' || role === 'delegate' ? role : null);
     const res = await session(ctx, {
       role,
       level,
-      prompt: role === 's2' ? `${PING_TEXT}Answer with decision "proceed", confidence 1, reason "ping", overrule false, ask_human false, human_question null.\n` : PING_TEXT,
-      ...(role === 's2' ? { schema: S2_SCHEMA } : {}),
+      prompt: schemaRole ? `${PING_TEXT}${PING_ANSWER[schemaRole]}` : PING_TEXT,
+      ...(schemaRole ? { schema: PING_SCHEMA[schemaRole] } : {}),
       ...(role === 'coder' ? { cwd: await tempRepo(ctx) } : {}),
     });
-    if (skipped402(res)) rows.push(row(`ping.${role}`, 'WARN', label, 'ping=skipped(402)'));
-    else if (res.status === 'ok') rows.push(row(`ping.${role}`, 'OK', label, 'ping=ok'));
-    else if (res.status === 'invalid-output') rows.push(row(`ping.${role}`, 'WARN', label, 'ping=answered (schema mismatch)'));
-    else rows.push(row(`ping.${role}`, 'FAIL', label, `ping=${res.status}(${res.reason ?? 'unknown'})`));
+    if (skipped402(res)) rows.push(row(id, 'WARN', label, 'ping=skipped(402)'));
+    else if (res.status === 'ok') rows.push(row(id, 'OK', label, 'ping=ok'));
+    else if (res.status === 'invalid-output') rows.push(row(id, 'WARN', label, 'ping=answered (schema mismatch)'));
+    else rows.push(row(id, 'FAIL', label, `ping=${res.status}(${res.reason ?? 'unknown'})`));
   }
   return rows;
 }

package/src/engines/builders/claude.mjs

@@ -57,7 +57,7 @@ export const CLI = 'claude';
 
 /**
  * @typedef {object} ClaudeBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model - the resolved model id (already picked by `resolveLevel`, B1).
  * @property {string} [effort] - one of `PROVIDER_EFFORTS.anthropic` (`../efforts.mjs`) when given.
  * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
@@ -86,7 +86,7 @@ export const CLI = 'claude';
 /**
  * @typedef {object} BuiltClosedBook
  * @property {"claude"} cli
- * @property {"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string[]} argv - no prompt positional.
  * @property {string} cwd
  * @property {string} stdinFile - the packet file the spawner pipes to stdin.
@@ -190,7 +190,7 @@ function buildClosedBookArgv(params) {
   assertValidBudget(maxBudgetUsd, 'buildClaudeArgv');
   // The dispatch in `buildClaudeArgv` never reaches this branch with role 'coder' — a runtime
   // invariant the parameter type alone cannot prove, so the narrowing is explicit.
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const isFacts = role === 'facts';
   if (isFacts && !hasAnyRenderedRule(renderedForbidden)) {
     throw new Error('buildClaudeArgv: facts role requires a non-empty forbidden-list render (got 0 usable rules)');

package/src/engines/builders/codex.mjs

@@ -65,7 +65,7 @@ import { CODEX_RULES_FILE_NAME, defaultCodexHome, isInside, prepareCodexHome } f
 import { hasAnyRenderedRule } from '../render-rules.mjs';
 import { assertEffortForProvider, PROVIDER_EFFORTS } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
-import { CODEX_CLOSED_BOOK_REFUSAL, isNoToolRole } from '../../config/closed-book.mjs';
+import { CODEX_CLOSED_BOOK_REFUSAL, isNeverOpenBookRole, isNoToolRole } from '../../config/closed-book.mjs';
 
 export const CLI = 'codex';
 
@@ -104,7 +104,7 @@ export const VALID_EFFORTS = PROVIDER_EFFORTS.openai;
 
 /**
  * @typedef {object} CodexBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model
  * @property {string} [effort] - one of {@link VALID_EFFORTS} when given.
  * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
@@ -217,14 +217,14 @@ function buildCoderArgv(params) {
 
 /**
  * @param {CodexBuildParams} params
- * @returns {{cli: "codex", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string, outPath: string, stdinFile: string}}
+ * @returns {{cli: "codex", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string, outPath: string, stdinFile: string}}
  */
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schemaPath } = params;
   assertValidEffort(effort);
   // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch with
   // role 'coder'; a no-tools role reaches it only with `allowOpenBook: true` (B32).
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const outPath = effectiveOutPath(params.outPath, role);
   const argv = ['codex', 'exec', '-m', model];
   if (effort) argv.push('-c', `model_reasoning_effort=${effort}`);
@@ -248,9 +248,10 @@ function buildClosedBookArgv(params) {
  */
 export function buildCodexArgv(params) {
   assertBaseParams('buildCodexArgv', params);
-  if (isNoToolRole(params.role) && params.allowOpenBook !== true) {
+  if (isNoToolRole(params.role) && (params.allowOpenBook !== true || isNeverOpenBookRole(params.role))) {
     // B32: no Codex flag removes the shell, so a no-tools role is built only when the caller
     // passes `allowOpenBook: true` (the config's `review.allow_open_book_codex` opt-in).
+    // B46: the autopilot delegate is never built on Codex, opt-in or not.
     throw Object.assign(new Error(CODEX_CLOSED_BOOK_REFUSAL), { code: 'closed-book' });
   }
   return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);

package/src/engines/builders/grok.mjs

@@ -56,7 +56,7 @@ export const GROK_ALL_BUILTIN_TOOLS = Object.freeze(['Bash', 'Read', 'Write', 'E
 
 /**
  * @typedef {object} GrokBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model
  * @property {string} [effort] - a non-empty string when given.
  * @property {string} promptPath - `--prompt-file` value (brief for coder, packet for closed-book).
@@ -100,14 +100,14 @@ function buildCoderArgv(params) {
 
 /**
  * @param {GrokBuildParams} params
- * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string}}
+ * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string}}
  */
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schema, systemPromptText } = params;
   assertValidEffort(effort);
   // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch
   // with role 'coder', but that is a runtime invariant, not provable from the parameter type.
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const argv = ['grok', '--prompt-file', promptPath, '-m', model];
   if (effort) argv.push('--reasoning-effort', effort);
   if (schema !== undefined) argv.push('--json-schema', JSON.stringify(schema));

package/src/engines/builders/validate-params.mjs

@@ -7,10 +7,10 @@
  */
 
 /**
- * The six roles the plan's engine adapters section (§5.2) declares.
- * @type {ReadonlyArray<"coder"|"reviewer"|"judge"|"s2"|"author"|"facts">}
+ * The six roles the plan's engine adapters section (§5.2) declares, plus the autopilot `delegate` (B46, closed-book).
+ * @type {ReadonlyArray<"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate">}
  */
-export const VALID_ROLES = Object.freeze(/** @type {const} */ (['coder', 'reviewer', 'judge', 's2', 'author', 'facts']));
+export const VALID_ROLES = Object.freeze(/** @type {const} */ (['coder', 'reviewer', 'judge', 's2', 'author', 'facts', 'delegate']));
 
 /**
  * @param {string} builderName - for the thrown message, e.g. `"buildClaudeArgv"`.

package/src/ledger/report.mjs

@@ -24,6 +24,8 @@ const ROLE_BUCKET = Object.freeze({
   reviewer: 'reviewUsd',
   judge: 'reviewUsd',
   s2: 's1s2Usd',
+  // B46: the autopilot delegate answers one owner-level question per session, like S2
+  delegate: 's1s2Usd',
   facts: 'factsUsd',
 });
 

package/src/review/fixloop.mjs

@@ -33,6 +33,12 @@
  *     new_in_hunks, late, open_after, tokens_in, tokens_out}`; a converged file gets
  *     `review.approved {file, content_hash, round}` (the worker signs every row it writes).
  *
+ * Autopilot extra round (B47): `deps.extraRounds` (from {@link extraRoundsFor}: one per signed
+ * `autopilot.extra_round` row for the file, one per grant) raises the file's cap by that many
+ * rounds — the cap checks here and rule 6 in `escalationAfterAttempt` both use the raised cap. A
+ * file already stopped at `review_cap` is reopened for its extra round by
+ * {@link reopenForExtraRound} (the worker calls it before the round).
+ *
  * Over budget (B12a follow-up, decided here): a recheck packet over `review.budgets.full_in`
  * falls to `contextMode: 'minimal'` (± `min_context_lines` around the SAME fix hunks) exactly as
  * `assemblePacket` does for any packet. The budget is a hard ceiling on what one session reads;
@@ -54,6 +60,8 @@ import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { escalationAfterAttempt, heavyRound, reviewRoundStalled } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
+import { verifyRow } from '../state/signer.mjs';
+import { decisionProblem, grantCoverProblem } from './gate-check.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
 import { assemblePacket, assertPacketPath, readFileDiff } from './packet.mjs';
@@ -103,6 +111,7 @@ import { spawnWithTimeoutRetry } from './session-retry.mjs';
  * @property {(req: {file: string, level: 'L3', open: Finding[]}) => Promise<unknown>} [patch] - the L3 patch rung (≤ 80 lines, owned files only).
  * @property {string | null} [base] - the block base (only for `recheck_scope: file`).
  * @property {string} [rulesDigest] @property {string} [factsExcerpt]
+ * @property {number} [extraRounds] - B47: rounds past `review.max_rounds_per_file` granted by autopilot (`extraRoundsFor`).
  */
 
 /** @param {LoopDeps} deps @param {Record<string, any>} row */
@@ -114,13 +123,68 @@ async function note(deps, row) {
   }
 }
 
-/** @param {Record<string, any> | undefined} cfg */
-function settings(cfg) {
+/** @param {unknown} v @param {number} d @returns {number} `v` when a non-negative integer, else `d`. */
+const int = (v, d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
+
+/**
+ * The file's round cap: `review.max_rounds_per_file` (default 4) plus the autopilot extra rounds.
+ * @param {Record<string, any> | undefined} cfg @param {number} [extraRounds]
+ * @returns {number}
+ */
+export function roundCap(cfg, extraRounds = 0) {
+  return int(cfg?.review?.max_rounds_per_file, 4) + int(extraRounds, 0);
+}
+
+/**
+ * B47: the extra rounds autopilot granted the file — the number of distinct grants with an
+ * `autopilot.extra_round` row of this run for this block and file that holds up as the gate's
+ * waiver check does: its MAC verifies, its grant covered `round:extra` at its `ts`
+ * (`grantCoverProblem`) and its `decision_id` names the delegate's acted decision for that block
+ * and file (`decisionProblem`). A row that fails any check, or whose check throws, counts for nothing.
+ * @param {Array<Record<string, any>>} rows @param {{runId: string, block: string, file: string, key: Buffer}} where
+ * @returns {number}
+ */
+export function extraRoundsFor(rows, { runId, block, file, key }) {
+  const runRows = rows.filter((r) => r?.run === runId);
+  const grants = new Set();
+  for (const r of runRows) {
+    if (r?.event !== 'autopilot.extra_round' || r.block !== block || r.file !== file || typeof r.grant_id !== 'string') continue;
+    try {
+      if (!verifyRow(r, key).ok) continue;
+      const at = typeof r.ts === 'string' ? Date.parse(r.ts) : Number.NaN;
+      if (!Number.isFinite(at)) continue;
+      if (grantCoverProblem(runRows, { grantId: r.grant_id, scope: 'round:extra', at, key, endRows: rows }) !== null) continue;
+      if (decisionProblem(runRows, { decisionId: r.decision_id, grantId: r.grant_id, scope: 'round:extra', subject: { block, file }, decision: 'allow', at, key }) !== null) continue;
+      grants.add(r.grant_id);
+    } catch {
+      // a row the checks cannot read gives no round (fail closed)
+    }
+  }
+  return grants.size;
+}
+
+/**
+ * B47: reopen a file stopped at `review_cap` when its raised cap leaves a round: the state goes
+ * back to `open` with `next: fix` at its level (`trigger: autopilot_extra_round`); the next round
+ * is a recheck. Any other state is left as it is.
+ * @param {FileState} state @param {number} extraRounds @param {Record<string, any> | undefined} cfg
+ * @returns {boolean} whether the state was reopened.
+ */
+export function reopenForExtraRound(state, extraRounds, cfg) {
+  if (state.status !== 'stopped' || state.next?.reason !== 'review_cap') return false;
+  if (state.round >= roundCap(cfg, extraRounds)) return false;
+  state.status = 'open';
+  state.next = { action: 'fix', level: state.level, trigger: 'autopilot_extra_round' };
+  state.pending_kind = null;
+  return true;
+}
+
+/** @param {Record<string, any> | undefined} cfg @param {number} [extraRounds] */
+function settings(cfg, extraRounds = 0) {
   const r = cfg?.review ?? {};
   const e = cfg?.escalation ?? {};
-  const int = (/** @type {unknown} */ v, /** @type {number} */ d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
   return {
-    maxRounds: int(r.max_rounds_per_file, 4),
+    maxRounds: roundCap(cfg, extraRounds),
     scope: r.recheck_scope === 'file' ? 'file' : 'fix_hunks',
     late: r.late_findings === 'block' ? 'block' : 'sweep',
     perLevel: int(e.review_rounds_per_level, 2),
@@ -332,7 +396,7 @@ async function stopBeforeRound(state, deps, kind, file, reason) {
  * @returns {Promise<FileState>}
  */
 export async function runRound(state, deps, opts = {}) {
-  const s = settings(deps.cfg);
+  const s = settings(deps.cfg, deps.extraRounds);
   const kind = opts.kind ?? (state.round === 0 ? 'full' : 'recheck');
   const current = readCurrent(deps.repoRoot, state.file);
   const openBefore = state.open.length;