cawdev-cli 1.0.3-beta → 1.0.5-beta

package/runner/runner.mjs

@@ -12,12 +12,14 @@
 // against your working copies; it should be a file you can read first.
 
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import {
   access, copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile,
 } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 
 import { join, resolve } from 'node:path';
+import { changedLines } from './changed-lines.mjs';
 import { describeTurn, totalsOf } from '../lib/usage.mjs';
 import { withinCeiling } from '../lib/tool-rules.mjs';
 import { serveControl } from './control.mjs';
@@ -33,12 +35,18 @@ import {
 import { AI_CONFIG, harnessPrompt, readRepoConfig } from '../lib/harness-prompt.mjs';
 import { loadToken, storedUrls } from './token-store.mjs';
 import {
-  CARD_WRITE, CAWDEV_READS, GIT_READS, driftedFrom, readOnlyExpert, toolsForStage,
+  CARD_WRITE, CAWDEV_READS, GIT_READS, beforeTheWorkExists, driftedFrom, readOnlyExpert,
+  toolsForStage,
 } from '../lib/stage-tools.mjs';
 import { capabilityIn, describeCall } from '../lib/tool-line.mjs';
 import { findSecret } from '../lib/secrets.mjs';
 import { cliVersion, isBelow } from '../lib/version.mjs';
 import { reloadableFor, restartNeededFor } from '../lib/runner-config.mjs';
+import {
+  createAutoWorkspace, discoverAutoWorkspaces, isAutoWorkspace,
+} from './auto-workspaces.mjs';
+import { agentOfCommand } from '../lib/agents.mjs';
+import { cawdevToolNames, codexArgs, translateCodexEvent } from '../lib/codex.mjs';
 
 // --- configuration -----------------------------------------------------------
 
@@ -164,6 +172,13 @@ const DEFAULTS = {
     // would be a question with one sensible answer.
     'mcp__cawdev__code_map',
     'mcp__cawdev__file_deps',
+    // R302. The SonarQube reading — a read, allowed by default like the map.
+    // Through READ_ONLY_CAWDEV this reaches REVIEW and AUDIT as the card
+    // asks, and ASK, SCOPE, MERGE, RELEASE and INTERVIEW as well: it is a
+    // read and harmless there, and subtracting it from five lists would be
+    // five lists to keep in step. PLAN is the one profile that drops it —
+    // `beforeTheWorkExists`, below — because the card says so.
+    'mcp__cawdev__quality_get',
     'mcp__cawdev__roadmap_statuses',
     'mcp__cawdev__roadmap_list',
     'mcp__cawdev__roadmap_get',
@@ -397,6 +412,13 @@ async function readConfig() {
       file.acceptsRulesFromConsole ?? DEFAULTS.acceptsRulesFromConsole,
     /** Whether a run here may reach the operator's browser. Per project too. */
     browser: file.browser ?? DEFAULTS.browser,
+    /**
+     * How many checkouts per project this machine may CLONE by itself when a
+     * coding run would otherwise wait for a free one — see auto-workspaces.mjs.
+     * Absent is none: an actuator that spends disk and a clone's time is
+     * switched on, never on by default.
+     */
+    autoWorkspaces: autoWorkspacesOf(file.autoWorkspaces),
     skillCache: file.skillCache ?? DEFAULTS.skillCache,
     skillPrepareSeconds: file.skillPrepareSeconds ?? DEFAULTS.skillPrepareSeconds,
     idleSeconds: file.idleSeconds ?? DEFAULTS.idleSeconds,
@@ -463,6 +485,12 @@ async function readConfig() {
  *   "dycrypt": "/Users/you/code/dycrypt"
  *   "dycrypt": { "path": "…", "allowedTools": ["Bash(mvn *)", "mcp__roadmap"] }
  *   "cawdev":  { "workspaces": ["/…/ws-1", "/…/ws-2", "/…/ws-3"] }
+ *   "cawdev":  { "workspaces": [...], "quality": { "command": "sonar-scanner", "tokenEnv": "SONAR_TOKEN" } }
+ *
+ * R300: the fourth form adds a `quality` block — see `qualityBlockOf` — and a
+ * project with one has its branches scanned after a coding run's TEST stage.
+ * Captured here at boot, not hot-swapped: adding or changing the block needs
+ * a restart, and `restartNeededFor` says so.
  *
  * R47: a bare path means ONE workspace, which is what every config meant
  * before workspaces existed. Concurrency for a project is
@@ -471,6 +499,32 @@ async function readConfig() {
  * which is the truth rather than "that project already has a run here" standing
  * in for it.
  */
+/** `autoWorkspaces` as a count: a whole number from 0, anything else is 0. */
+function autoWorkspacesOf(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : 0;
+}
+
+/**
+ * The on-demand checkouts beside each project's first one, joined to its list
+ * — at boot, and again on SIGHUP, when one may have been made or dropped by
+ * somebody else. A checkout gone from disk leaves the list unless a run holds
+ * it; one that appeared joins it. The configured checkouts are never touched.
+ */
+async function syncAutoWorkspaces(projects, held = new Set()) {
+  for (const [slug, project] of Object.entries(projects)) {
+    const first = project.workspaces[0];
+    const found = await discoverAutoWorkspaces(first);
+    const kept = project.workspaces.filter((path) => !isAutoWorkspace(first, path)
+      || found.includes(path) || held.has(path));
+    const added = found.filter((path) => !kept.includes(path));
+    const dropped = project.workspaces.filter((path) => !kept.includes(path));
+    project.workspaces = [...kept, ...added];
+    for (const path of added) log(`  ${slug}: serving the checkout made on demand at ${path}`);
+    for (const path of dropped) log(`  ${slug}: ${path} is gone — no longer serving it`);
+  }
+}
+
 function normaliseProjects(projects) {
   const normalised = {};
   for (const [slug, value] of Object.entries(projects)) {
@@ -508,11 +562,58 @@ function normaliseProjects(projects) {
       // falls through to the machine's answer; `false` here refuses it for one
       // project on a machine that otherwise allows it.
       browser: settings.browser,
+      // R300: whether, and how, this project's branches are scanned with
+      // SonarQube after TEST. Null is the ordinary case and means never.
+      quality: qualityBlockOf(slug, settings.quality),
     };
   }
   return normalised;
 }
 
+/**
+ * A project's `quality` block, normalised — R300.
+ *
+ * The scan is opt-in TWICE: here, on the machine, and on the project, which
+ * must have a SonarQube key (the claim carries it). A machine with no block
+ * never scans and never says so; a machine with one and no scanner on its
+ * PATH reports an `error` reading rather than nothing, so the page says the
+ * scan could not run instead of showing a branch nobody looked at.
+ *
+ * `tokenEnv` names the variable this machine holds the scanner token in. The
+ * platform never sends one: the project's SonarQube token (R304) is the
+ * platform's reader credential and stays there; the scanner's is the
+ * operator's and stays here. `url` overrides the platform's `sonarUrl` for
+ * a machine that reaches the server by another name (a LAN hostname).
+ *
+ * `whenBranchesRefused` is what to do on a server that refuses
+ * `sonar.branch.name` — Community Edition. The default, `skip`, reports an
+ * error saying so; `main` re-runs the scan as the project's MAIN analysis,
+ * which overwrites the project's dashboard with this branch's code and so
+ * makes the platform's project reading describe whichever branch scanned
+ * last; `project` — R316 — analyses the branch as its own scratch SonarQube
+ * project instead, `<key>:branch:<branch>-<hash>`, overwritten on each run,
+ * with "new" meaning a line the branch changed. Both are an operator's own
+ * opt-in — nothing opts in for them — and `project` additionally needs the
+ * scanner token to hold *Create Projects* on the server, and for the
+ * server's default project visibility to not be public (or this publishes
+ * the code).
+ */
+function qualityBlockOf(slug, block) {
+  if (!block) return null;
+  const when = block.whenBranchesRefused ?? 'skip';
+  if (when !== 'skip' && when !== 'main' && when !== 'project') {
+    throw new Error(
+      `Project "${slug}": quality.whenBranchesRefused must be "skip", "main" or "project", not "${when}".`);
+  }
+  return {
+    command: block.command ?? 'sonar-scanner',
+    tokenEnv: block.tokenEnv ?? 'SONAR_TOKEN',
+    url: block.url ?? null,
+    whenBranchesRefused: when,
+    timeoutSeconds: block.timeoutSeconds ?? 600,
+  };
+}
+
 
 /**
  * What THIS daemon knows about a skill, beyond what the platform sent — R76.
@@ -814,6 +915,11 @@ async function readUsage(config) {
   const allWindows = [];
   
   for (const agentCommand of config.agentCommands) {
+    // Codex has no `-p /usage`: its `-p` is a PROFILE, and the bare command is
+    // an interactive terminal. It reports no windows rather than a guess.
+    if (agentOfCommand(agentCommand) === 'codex') {
+      continue;
+    }
     const said = await new Promise((resolve) => {
       let out = '';
       const child = spawn(agentCommand, ['-p', '/usage', '--output-format', 'text'], {
@@ -843,7 +949,7 @@ async function readUsage(config) {
     const windows = parseUsage(said);
     for (const each of windows) {
       allWindows.push({
-        provider: agentCommand.endsWith('agy') ? 'agy' : 'claude',
+        provider: agentOfCommand(agentCommand),
         window: each.kind,
         model: each.model,
         percentUsed: each.percent,
@@ -1305,10 +1411,17 @@ async function resolveSkills(config, run, cwd, baseCommit, asked) {
       notes.push(await prepareSkillIndex(config, skill, local, run, cwd, baseCommit));
     }
     attached.push({ skill, local });
+    // R303. A required server says so where the person is looking, as the
+    // expert line does. Whether a STAGE is actually asked for it is decided at
+    // spawn — a read-only stage cannot call it and is not nudged for it.
+    const must = skill.mode === 'REQUIRED'
+      ? ' This project REQUIRES it: if a stage finishes without calling one of its tools, the '
+        + 'session will be told.'
+      : '';
     notes.push(`${skill.name ?? skill.key} is available to this session as `
       + `${skill.toolPrefix ?? `mcp__${skill.serverName}`}. The first call still asks a person — `
       + `allow ${skill.toolPrefix ?? `mcp__${skill.serverName}`} for the session to cover the `
-      + 'rest.');
+      + `rest.${must}`);
   }
   return { attached, notes };
 }
@@ -1333,9 +1446,13 @@ async function resolveSkills(config, run, cwd, baseCommit, asked) {
  * It does not reproduce on macOS at any output size, so this is not something
  * a local run will ever warn about. Do not put `exit` back.
  */
-function git(cwd, args) {
+function git(cwd, args, { timeoutMs = 0 } = {}) {
   return new Promise((resolvePromise, reject) => {
-    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(timeoutMs ? { timeout: timeoutMs } : {}),
+    });
     let out = '';
     let err = '';
     child.stdout.on('data', (chunk) => (out += chunk));
@@ -1768,11 +1885,12 @@ const SURVEY_FILE_CAP = 20;
  * arrive at the console as the same answer.
  *
  * **The order of this list matters, and it is `project.workspaces` order.**
- * R71 has the console work out which checkout a run would be given by taking
- * the first entry here that nothing is holding — the queue gate's
- * `workspaces.find((path) => !held.has(path))`, read from the other side of
- * the wire. Sorting or de-duplicating this on the way out would move the
- * warning onto a checkout the run is not headed for, and nothing would fail.
+ * R71/i258 has the console work out which checkout a run would be given by
+ * taking the first free entry here whose `dirty` is 0, falling back to the
+ * first free entry if none is known clean — the queue gate's `pickWorkspace`,
+ * read from the other side of the wire. Sorting or de-duplicating this on the
+ * way out would move the warning onto a checkout the run is not headed for,
+ * and nothing would fail.
  */
 /**
  * One porcelain line, split into its status and its path.
@@ -1826,6 +1944,31 @@ async function surveyWorkingCopies(config) {
   return survey;
 }
 
+/** Bounds the claim-time `git status` probe — see `looksClean`. */
+const CLEAN_PROBE_MS = 5000;
+
+/**
+ * Is `path`'s tree clean, read fresh, right now — i258.
+ *
+ * Three-valued on purpose: `true` clean, `false` dirty, `null` could not
+ * tell (no `.git`, a timeout, any failure). `null` is grouped with dirty by
+ * every caller — "I could not look" is not "it was clean" — so a probe that
+ * cannot answer degrades to the old first-free behaviour rather than
+ * starving the queue on a wedged filesystem.
+ *
+ * This does not reuse `surveyWorkingCopies`'s reading. That one runs on the
+ * heartbeat and is not kept anywhere; caching it here would add a second
+ * source of truth for a fact `pickWorkspace` is about to establish anyway,
+ * and a 30-second-old reading reproduces R71/i258 in a smaller window.
+ * `prepareWorkingCopy` runs the identical `git status --porcelain` seconds
+ * after this one.
+ */
+async function looksClean(path) {
+  const porcelain = await git(path, ['status', '--porcelain'], { timeoutMs: CLEAN_PROBE_MS })
+    .catch(() => null);
+  return porcelain === null ? null : porcelain === '';
+}
+
 /**
  * What every checkout on this machine holds — R87.
  *
@@ -2239,6 +2382,376 @@ async function surveyGit(config) {
   }
 }
 
+/**
+ * Scans the run's branch with SonarQube and tells the platform — R300.
+ *
+ * Runs AFTER the TEST stage settles and BEFORE the next stage begins, on the
+ * workspace the run just wrote, and it is the DAEMON that runs it: a session
+ * that reported its own gate could lie about it (RunnerLimit's argument), so
+ * the scanner is a subprocess this process starts and nothing the spawned
+ * `claude` can call. Only a staged run with a TEST stage gets here — a
+ * lifecycle without one, an unstaged run, a run whose gate refused TEST twice
+ * or one that reported done inside TEST is not scanned, because there was no
+ * settled TEST stage to scan after.
+ *
+ * The shape is `surveyGit`'s: every failure is CAUGHT and reported as an
+ * `error` reading, never thrown to the walk — a failed scan never fails a
+ * run. The two silent exits are the two ways the feature is off: no `quality`
+ * block on this machine (nothing is logged; the operator never asked), and no
+ * key on the project (logged, because the machine did ask and the project is
+ * what is missing). Everything after that reports SOMETHING, so that "could
+ * not scan" and "did not scan" never reach the page as the same answer.
+ *
+ * What is scanned is the WORKING TREE, which after TEST may hold edits the
+ * session had not committed; `headSha` is HEAD, and says where the tree
+ * started rather than that the tree equals it.
+ *
+ * The scanner's working directory is a temp dir OUTSIDE the checkout,
+ * passed as `-Dsonar.working.directory=`: `.scannerwork/` inside it would
+ * show up in the working-copy watcher and in `resetWorkspace`'s `git clean`
+ * list — R76's `.codegraph` lesson, see `excludeLocally`. The token goes in
+ * the child's ENVIRONMENT and never on its argv, which `ps` would show.
+ *
+ * R316: when the project SAYS its server refuses branches (`run.sonarBranches
+ * === 'REFUSED'`, and only when this machine scans the same server the claim
+ * names — see `trimSlash`), the branch attempt is skipped outright and the
+ * machine's `whenBranchesRefused` runs straight away. Otherwise the branch
+ * attempt still runs first and the refusal is still learnt from its failure,
+ * exactly as before R316 — a project that has not said, or a machine
+ * scanning a different server, gets today's behaviour unchanged.
+ */
+async function scanQuality(config, run, cwd, branch) {
+  const slug = run.projectSlug;
+  const quality = config.projects[slug]?.quality;
+  if (!quality) return;
+  if (!run.sonarProjectKey) {
+    log(`  quality: ${slug} has no SonarQube key — not scanned`);
+    return;
+  }
+  const key = run.sonarProjectKey;
+  const report = async (reading) => {
+    await api(config, `/api/runners/${config.runnerId}/quality/${slug}`, {
+      method: 'POST',
+      body: { runId: run.id, branch, ...reading },
+    }).catch((failure) => log(`  could not report the quality of ${branch}: ${failure.message}`));
+    if (reading.error) {
+      log(`  quality: could not scan ${branch}: ${reading.error}`);
+    } else {
+      const problems = (reading.newBugs ?? 0) + (reading.newVulnerabilities ?? 0)
+        + (reading.newSecurityHotspots ?? 0) + (reading.newCodeSmells ?? 0);
+      log(`  quality: ${branch} gate ${reading.gate ?? 'NONE'} · ${problems} new problem${problems === 1 ? '' : 's'}`
+        + (reading.warning ? ` · ${reading.warning}` : ''));
+    }
+  };
+
+  const url = quality.url ?? run.sonarUrl;
+  if (!url) {
+    return report({ error: 'No SonarQube server: the platform has none configured and the quality block names no url.' });
+  }
+  const token = process.env[quality.tokenEnv];
+  if (!token) {
+    return report({ error: `The scanner token is not set: export ${quality.tokenEnv} on this machine.` });
+  }
+
+  // R316: the project's own word on whether its server refuses branches is
+  // trusted only when this machine scans THAT server — a machine whose own
+  // `quality.url` names a different one (a LAN hostname the platform cannot
+  // reach) knows nothing about what that server does, and tries the branch
+  // scan first, exactly as if the project had said nothing.
+  const claimSpeaks = !quality.url || trimSlash(quality.url) === trimSlash(run.sonarUrl ?? '');
+  const knownRefused = claimSpeaks && run.sonarBranches === 'REFUSED';
+
+  let headSha = null;
+  let workDir = null;
+  try {
+    headSha = await git(cwd, ['rev-parse', 'HEAD']);
+    workDir = await mkdtemp(join(tmpdir(), 'cawdev-sonar-'));
+    const deadline = Date.now() + quality.timeoutSeconds * 1000;
+    const remaining = () => Math.max(1000, deadline - Date.now());
+    const scannerArgs = (withBranch) => [
+      `-Dsonar.host.url=${url}`,
+      `-Dsonar.projectKey=${key}`,
+      ...(withBranch ? [`-Dsonar.branch.name=${branch}`] : []),
+      `-Dsonar.scm.revision=${headSha}`,
+      `-Dsonar.working.directory=${workDir}`,
+    ];
+    const env = { ...process.env, SONAR_TOKEN: token };
+
+    if (knownRefused) {
+      if (quality.whenBranchesRefused === 'skip') {
+        return report({
+          headSha,
+          error: "This project's SonarQube server does not analyse branches (Community Edition, set on the "
+            + 'project). Set "whenBranchesRefused": "project" (a scratch SonarQube project per branch) or '
+            + '"whenBranchesRefused": "main" in this machine\'s quality block.',
+        });
+      }
+      if (quality.whenBranchesRefused === 'project') {
+        // `await`, not `return`: a rejection has to be caught by THIS
+        // function's own try/catch, which `return somePromise` would skip —
+        // control leaves before the promise settles.
+        return await scanAsScratchProject(
+          { quality, run, cwd, branch, key, url, token, headSha, workDir, deadline, report });
+      }
+      // 'main', and known refused: no reason to run the branch scan first.
+      const ran = await runSkillCommand(quality.command, scannerArgs(false), { cwd, env, timeoutMs: remaining() });
+      if (!ran.ok) {
+        if (/ENOENT/.test(ran.said)) {
+          return report({ headSha, error: `${quality.command} is not installed on this machine (spawn ENOENT).` });
+        }
+        return report({ headSha, error: ran.said.split('\n')[0] || 'the scanner failed and said nothing' });
+      }
+      const reportTask = parseProperties(await readFile(join(workDir, 'report-task.txt'), 'utf8'));
+      const askServer = sonarAsker((reportTask.serverUrl ?? url).replace(/\/$/, ''), token);
+      const settled = await waitForAnalysis(askServer, reportTask.ceTaskId, deadline, quality.timeoutSeconds);
+      return await reportBranchReading({
+        ask: askServer, reportTask, settled, key, branch, analysedAs: 'MAIN',
+        warning: "This server does not analyse branches; the branch was analysed as the project's main analysis.",
+        headSha, report,
+      });
+    }
+
+    // Today's behaviour: try the branch first, and learn what the server is
+    // from a failure.
+    let analysedAs = 'BRANCH';
+    let warning = null;
+    let ran = await runSkillCommand(quality.command, scannerArgs(true),
+      { cwd, env, timeoutMs: remaining() });
+    if (!ran.ok) {
+      if (/ENOENT/.test(ran.said)) {
+        return report({ headSha, error: `${quality.command} is not installed on this machine (spawn ENOENT).` });
+      }
+      if (/sonar\.branch\.name.*(Developer Edition|above is required)/is.test(ran.said)) {
+        if (quality.whenBranchesRefused === 'project') {
+          return await scanAsScratchProject(
+            { quality, run, cwd, branch, key, url, token, headSha, workDir, deadline, report });
+        }
+        if (quality.whenBranchesRefused !== 'main') {
+          return report({
+            headSha,
+            error: 'This SonarQube server does not analyse branches (Community Edition). Set '
+              + '"whenBranchesRefused": "project" (a scratch SonarQube project per branch) or '
+              + '"whenBranchesRefused": "main" in the quality block to analyse it as the main analysis instead '
+              + "— or set this project's SonarQube-branches setting under Settings so this is known before the "
+              + 'scan runs.',
+          });
+        }
+        // The operator opted in: once more, as the project's main analysis.
+        analysedAs = 'MAIN';
+        warning = "This server does not analyse branches; the branch was analysed as the project's main analysis.";
+        ran = await runSkillCommand(quality.command, scannerArgs(false),
+          { cwd, env, timeoutMs: remaining() });
+      }
+    }
+    if (!ran.ok) {
+      return report({ headSha, error: ran.said.split('\n')[0] || 'the scanner failed and said nothing' });
+    }
+
+    // What the scanner left behind: where the server queued the analysis.
+    const reportTask = parseProperties(await readFile(join(workDir, 'report-task.txt'), 'utf8'));
+    const askServer = sonarAsker((reportTask.serverUrl ?? url).replace(/\/$/, ''), token);
+    const settled = await waitForAnalysis(askServer, reportTask.ceTaskId, deadline, quality.timeoutSeconds);
+    await reportBranchReading({ ask: askServer, reportTask, settled, key, branch, analysedAs, warning, headSha, report });
+  } catch (failure) {
+    await report({ headSha, error: failure.message.split('\n')[0] });
+  } finally {
+    if (workDir) {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/** Without a trailing slash, so two URLs that differ only by one still compare equal. */
+function trimSlash(url) {
+  return url.replace(/\/$/, '');
+}
+
+/** A GET against the SonarQube server a scan just reported to, authorised with the scanner's own token. */
+function sonarAsker(serverUrl, token) {
+  return async (path) => {
+    const response = await fetch(`${serverUrl}${path}`, { headers: { authorization: `Bearer ${token}` } });
+    if (!response.ok) {
+      throw new Error(`SonarQube answered ${response.status} to ${path.split('?')[0]}`);
+    }
+    return response.json();
+  };
+}
+
+/**
+ * Waits for a queued analysis to settle — shared by every scan path, BRANCH,
+ * MAIN and PROJECT alike. Throws rather than reports: every caller runs
+ * inside `scanQuality`'s own try/catch, which turns it into an error reading.
+ */
+async function waitForAnalysis(ask, ceTaskId, deadline, timeoutSeconds) {
+  let settled = null;
+  while (Date.now() < deadline) {
+    const { task: current } = await ask(`/api/ce/task?id=${encodeURIComponent(ceTaskId)}`);
+    if (['SUCCESS', 'FAILED', 'CANCELED'].includes(current?.status)) {
+      settled = current;
+      break;
+    }
+    await new Promise((wake) => setTimeout(wake, 3000));
+  }
+  if (!settled) {
+    throw new Error(`SonarQube had not finished analysing after ${timeoutSeconds}s.`);
+  }
+  if (settled.status !== 'SUCCESS') {
+    throw new Error(settled.errorMessage ?? `SonarQube ${settled.status.toLowerCase()} the analysis.`);
+  }
+  return settled;
+}
+
+/** The gate and the new-code measures, for a BRANCH or MAIN reading — never for PROJECT, which has neither. */
+async function reportBranchReading({ ask, reportTask, settled, key, branch, analysedAs, warning, headSha, report }) {
+  const { projectStatus } = await ask(`/api/qualitygates/project_status?analysisId=${encodeURIComponent(settled.analysisId)}`);
+  const metrics = 'new_bugs,new_vulnerabilities,new_security_hotspots,new_code_smells,new_coverage';
+  const { component } = await ask(`/api/measures/component?component=${encodeURIComponent(key)}`
+    + `&metricKeys=${metrics}${analysedAs === 'BRANCH' ? `&branch=${encodeURIComponent(branch)}` : ''}`);
+  const measure = (metric) => {
+    const found = (component?.measures ?? []).find((each) => each.metric === metric);
+    // New-code values sit in `period.value` — `periods[0].value` on older servers.
+    const value = found?.period?.value ?? found?.periods?.[0]?.value ?? found?.value;
+    return value === undefined || value === null || value === '' ? null : Number(value);
+  };
+  const integer = (metric) => {
+    const value = measure(metric);
+    return value === null ? null : Math.round(value);
+  };
+
+  await report({
+    headSha,
+    gate: projectStatus?.status ?? 'NONE',
+    analysedAs,
+    newBugs: integer('new_bugs'),
+    newVulnerabilities: integer('new_vulnerabilities'),
+    newSecurityHotspots: integer('new_security_hotspots'),
+    newCodeSmells: integer('new_code_smells'),
+    newCoverage: measure('new_coverage'),
+    dashboardUrl: reportTask.dashboardUrl ?? null,
+    warning,
+  });
+}
+
+/**
+ * SonarQube's own pages, `ps=500` at a time, up to the server's `p × ps`
+ * ceiling worth trying — R313's `LIST_PAGES` argument, in the scanner
+ * instead of the reader. `paging.total` (hotspots) or `total` (issues) is
+ * wherever the server put it.
+ */
+async function pagedSearch(ask, pathWithQuery, itemsKey) {
+  const items = [];
+  for (let page = 1; page <= 20; page += 1) {
+    const body = await ask(`${pathWithQuery}&ps=500&p=${page}`);
+    const list = body[itemsKey] ?? [];
+    items.push(...list);
+    const total = body.paging?.total ?? body.total ?? items.length;
+    if (items.length >= total || list.length === 0) {
+      break;
+    }
+  }
+  return items;
+}
+
+/** `sha1(text)`'s first six hex characters — enough to keep a scratch key readable and still collision-free per branch. */
+function shortHash(text) {
+  return createHash('sha1').update(text).digest('hex').slice(0, 6);
+}
+
+/**
+ * The Community Edition fallback that never touches the project's own
+ * dashboard — R316: the branch is analysed as its own scratch SonarQube
+ * project, `<key>:branch:<branch>-<hash>`, overwritten on each run of the
+ * branch. A fresh project has no new-code period to compare against, so
+ * "new" is redefined as "on a line this branch changed since it left its
+ * base" — {@link changedLines} against the merge-base — and the gate is
+ * always `NONE`: a quality gate over a whole scratch project would judge
+ * code this branch did not write.
+ */
+async function scanAsScratchProject({ quality, run, cwd, branch, key, url, token, headSha, workDir, deadline, report }) {
+  const baseName = run.baseBranch ?? run.defaultBranch ?? 'main';
+  const ref = await firstRef(cwd, [`origin/${baseName}`, baseName]);
+  const mergeBase = ref ? await git(cwd, ['merge-base', 'HEAD', ref]).catch(() => null) : null;
+  if (!mergeBase) {
+    return report({ headSha, error: `could not find where ${branch} left ${baseName}` });
+  }
+
+  const scratchKey = `${key}:branch:${branch.replace(/[^A-Za-z0-9_.-]/g, '_')}-${shortHash(branch)}`;
+  const env = { ...process.env, SONAR_TOKEN: token };
+  const args = [
+    `-Dsonar.host.url=${url}`,
+    `-Dsonar.projectKey=${scratchKey}`,
+    `-Dsonar.projectName=${key} · ${branch}`,
+    `-Dsonar.scm.revision=${headSha}`,
+    `-Dsonar.working.directory=${workDir}`,
+  ];
+  const ran = await runSkillCommand(quality.command, args,
+    { cwd, env, timeoutMs: Math.max(1000, deadline - Date.now()) });
+  if (!ran.ok) {
+    if (/ENOENT/.test(ran.said)) {
+      throw new Error(`${quality.command} is not installed on this machine (spawn ENOENT).`);
+    }
+    throw new Error(ran.said.split('\n')[0] || 'the scanner failed and said nothing');
+  }
+
+  const reportTask = parseProperties(await readFile(join(workDir, 'report-task.txt'), 'utf8'));
+  const ask = sonarAsker((reportTask.serverUrl ?? url).replace(/\/$/, ''), token);
+  await waitForAnalysis(ask, reportTask.ceTaskId, deadline, quality.timeoutSeconds);
+
+  const changed = await changedLines(cwd, mergeBase);
+  const counted = (component, line) => {
+    const path = component.slice(scratchKey.length + 1);
+    const entry = changed.get(path);
+    if (!entry) return false;
+    if (entry === 'ALL') return true;
+    // A file-level finding (no line) counts when the file itself changed.
+    if (line === undefined || line === null) return true;
+    return entry.has(line);
+  };
+
+  const encodedKey = encodeURIComponent(scratchKey);
+  const issues = await pagedSearch(ask,
+    `/api/issues/search?componentKeys=${encodedKey}&resolved=false&types=BUG,VULNERABILITY,CODE_SMELL`, 'issues');
+  const hotspots = await pagedSearch(ask,
+    `/api/hotspots/search?projectKey=${encodedKey}&status=TO_REVIEW`, 'hotspots');
+
+  let newBugs = 0;
+  let newVulnerabilities = 0;
+  let newCodeSmells = 0;
+  for (const issue of issues) {
+    if (!counted(issue.component, issue.line)) continue;
+    if (issue.type === 'BUG') newBugs += 1;
+    else if (issue.type === 'VULNERABILITY') newVulnerabilities += 1;
+    else if (issue.type === 'CODE_SMELL') newCodeSmells += 1;
+  }
+  const newSecurityHotspots = hotspots.filter((hotspot) => counted(hotspot.component, hotspot.line)).length;
+
+  await report({
+    headSha,
+    gate: 'NONE',
+    analysedAs: 'PROJECT',
+    newBugs,
+    newVulnerabilities,
+    newSecurityHotspots,
+    newCodeSmells,
+    newCoverage: null,
+    dashboardUrl: reportTask.dashboardUrl ?? null,
+    warning: 'This server does not analyse branches; the branch was analysed as its own SonarQube project, '
+      + 'counting problems on the lines it changed. No gate was computed.',
+  });
+}
+
+/** `key=value` lines — the shape of the scanner's `report-task.txt`. */
+function parseProperties(text) {
+  const parsed = {};
+  for (const line of text.split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) {
+      parsed[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+    }
+  }
+  return parsed;
+}
+
 /**
  * Reads and reports the code map, unless it would say the same thing again.
  *
@@ -2445,7 +2958,10 @@ at what they might want next.
 ${briefLine(run)}
 If a decision is genuinely theirs, use the cawdev MCP tool \`ask_user\` and wait.
 
-Their instruction:
+${run.branch ? `When what they asked is done, commit it on ${run.branch} — work left
+uncommitted is work nothing can push or propose. Never commit to or push main.
+
+` : ''}Their instruction:
 
 ${run.openingPrompt}`;
   }
@@ -3091,7 +3607,11 @@ async function performWorkspaceRequest(config, request, afterTheTreeMoved = null
     if (!branch) {
       result = 'A merge has to name a branch. Nothing was merged.';
     } else {
-      log(`  MERGING ${branch} — asked for from the console`);
+      // R306: whose idea it was. A rule's merge lands with nobody reading
+      // the diff, and the log is where an operator sees that happen.
+      log(`  MERGING ${branch} — ${request.requestedByRule
+        ? `by ${request.requestedByRule}, nobody is reading this diff`
+        : 'asked for from the console'}`);
       // R261. A sprint's branch lands with a merge commit; every other branch
       // squashes as it always did. The claim says which.
       ({ ok, result, failure: failureKind } = await mergePullRequest(cwd, branch, {
@@ -3123,13 +3643,35 @@ async function performWorkspaceRequest(config, request, afterTheTreeMoved = null
     } else {
       const base = request.baseBranch ?? request.defaultBranch ?? 'main';
       log(`  OPENING a pull request for ${branch} → ${base} — asked for from the console`);
-      ({ ok, result } = await openPullRequestFor(cwd, {
-        branch,
-        base,
-        title: request.title?.trim() || branch,
-        body: `Opened by cawdev for the sprint branch \`${branch}\`${request.title ? ` — ${request.title.trim()}` : ''}.\n\n`
-          + `Merging it lands every card of the sprint on ${base}.`,
-      }));
+      // A card's branch may never have left this machine — a session whose
+      // project does not push, which is why somebody is asking for the pull
+      // request by hand. A sprint's is on origin already and this is a no-op.
+      const empty = await nothingToPropose(cwd, branch, base);
+      if (empty) {
+        ok = false;
+        result = empty;
+      }
+      const pushed = empty ? { failed: empty } : await pushIfOriginLacks(cwd, branch);
+      if (pushed.failed) {
+        ok = false;
+        result = pushed.failed;
+      } else {
+        ({ ok, result } = await openPullRequestFor(cwd, {
+          branch,
+          base,
+          title: request.title?.trim() || branch,
+          // A sprint's title is its ref and name ("S1 Notifications"); a
+          // card's is "R3 — …" (RunnerController reads either at claim).
+          body: /^S\d+ /.test(request.title ?? '')
+            ? `Opened by cawdev for the sprint branch \`${branch}\` — ${request.title.trim()}.\n\n`
+              + `Merging it lands every card of the sprint on ${base}.`
+            : `Opened by cawdev for \`${branch}\`${request.title ? ` — ${request.title.trim()}` : ''}.`,
+        }));
+        // The URL stays the FIRST line: the platform reads it off there.
+        if (ok && pushed.said) {
+          result = `${result}\n${pushed.said}`;
+        }
+      }
     }
   } else if (request.kind === 'CUT_BRANCH') {
     // R260. Put the sprint's branch on origin, from the default's tip. A branch
@@ -3188,8 +3730,12 @@ function reportWorkspaceRequest(config, request, ok, result, failure = null) {
  * platform holds the tree as it now is by the time the console hears "done".
  */
 function watchWorkspaceRequests(config, { afterTheTreeMoved = null } = {}) {
-  const served = new Set(
-    Object.values(config.projects).flatMap((project) => project.workspaces),
+  // Read on EVERY request, never captured once: a checkout cloned on demand
+  // (`autoWorkspaces`) joins `project.workspaces` long after this started, and
+  // a set taken at boot refused every request about one — `/pr` on a session
+  // that ran in `saasng-auto-2` came back "This runner does not serve …".
+  const served = () => new Set(
+    Object.values(config.projects).flatMap((project) => project.workspaces ?? []),
   );
 
   const poll = async () => {
@@ -3205,7 +3751,7 @@ function watchWorkspaceRequests(config, { afterTheTreeMoved = null } = {}) {
     // The same guard, for the same reason: this poll is on an interval, so a
     // throw becomes an unhandled rejection and the daemon stops.
     for (const request of Array.isArray(requests) ? requests : []) {
-      if (!served.has(request.path)) {
+      if (!served().has(request.path)) {
         await reportWorkspaceRequest(config, request, false,
           `This runner does not serve ${request.path}.`);
         continue;
@@ -3361,8 +3907,10 @@ function announceRules(rules) {
   if (!on.length) return;
   log(`  this project's rules: ${on.join(', ')}`);
   if (rules.autoMerge) {
-    log('  !! auto_merge is ON: when this run finishes, its branch will be merged '
-      + 'with nobody reading it');
+    // R306: not "when this run finishes" any more — the platform asks for the
+    // merge when the branch reaches Done on the development board.
+    log('  !! auto_merge is ON: its branch will be merged when it reaches Done on the '
+      + 'board, with nobody reading it');
   }
 }
 
@@ -3428,6 +3976,35 @@ async function pushBranch(cwd, branch) {
  * An existing pull request is a success, not a conflict — the rule wanted one
  * to exist, and one does.
  */
+/**
+ * Why there is nothing to open a pull request FOR, or null when there is.
+ *
+ * A branch with no commit beyond its base is not a pull request — GitHub says
+ * "There isn't anything to compare" — and before this `/pr` pushed it anyway
+ * and handed back the compare link, so the person went to GitHub to learn
+ * what this machine already knew. The usual reason is work sitting
+ * UNCOMMITTED in the checkout, so that is counted and said, with where.
+ *
+ * Asked BEFORE anything is pushed, on the OPEN_PR a person asks for (`/pr`).
+ * Not on the `auto_pr` rule: a finished run that committed nothing gets gh's
+ * own refusal there, as it always has. A count that cannot be made (no such
+ * ref, no origin) is not a verdict: null, and the old path decides as it did.
+ */
+async function nothingToPropose(cwd, branch, base) {
+  const has = (ref) => git(cwd, ['rev-parse', '--verify', '--quiet', ref]).then(() => true, () => false);
+  const tip = (await has(branch)) ? branch : (await has(`origin/${branch}`)) ? `origin/${branch}` : null;
+  const against = base ? `origin/${base}` : 'origin/HEAD';
+  if (!tip || !(await has(against))) return null;
+  const ahead = Number(await git(cwd, ['rev-list', '--count', `${against}..${tip}`]).catch(() => 'x'));
+  if (!Number.isFinite(ahead) || ahead > 0) return null;
+  const dirty = (await git(cwd, ['status', '--porcelain']).catch(() => '')).split('\n').filter(Boolean).length;
+  const onIt = (await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => '')) === branch;
+  return `${branch} has no commit beyond ${against.replace(/^origin\//, '')}, so there is nothing to propose.`
+    + (dirty && onIt
+      ? ` ${dirty} file(s) are uncommitted in ${cwd} — commit them, then ask again.`
+      : ' Nothing was pushed.');
+}
+
 async function openPullRequest(cwd, run, title) {
   const state = await readPushState(cwd, run.branch).catch(() => null);
   if (state === 'NO_REMOTE') {
@@ -3466,6 +4043,51 @@ async function openPullRequest(cwd, run, title) {
  * `--base` only when one is given: with no base the argv is byte for byte what
  * it was before R260 and the host picks its own default.
  */
+/**
+ * Pushes `branch` to origin when origin does not have it, or has an older
+ * commit of it — and never otherwise.
+ *
+ * Before a pull request is opened for a branch a session wrote on this
+ * machine: `gh pr create --head` names a branch on the HOST, and one that only
+ * exists here fails with a message about the head that says nothing of why.
+ * Only a fast-forward is pushed. Origin ahead, or diverged, is somebody else's
+ * work on the branch, and pushing over it is not what "open the pull request"
+ * asked for — that case goes to gh as it is and gh says what is wrong. Nothing
+ * here moves the checkout: it is `<branch>:<branch>`, not the current HEAD.
+ *
+ * @returns `{ said }` when it pushed, `{}` when there was nothing to push, and
+ *   `{ failed }` when a push was needed and git refused it.
+ */
+async function pushIfOriginLacks(cwd, branch) {
+  const local = await git(cwd, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
+    .catch(() => null);
+  if (!local) {
+    return {};
+  }
+  const listed = await git(cwd, ['ls-remote', '--heads', 'origin', branch]).catch(() => null);
+  if (listed === null) {
+    return {};
+  }
+  const remote = listed.split(/\s+/)[0] || null;
+  if (remote === local) {
+    return {};
+  }
+  if (remote) {
+    const behind = await git(cwd, ['merge-base', '--is-ancestor', remote, local])
+      .then(() => true, () => false);
+    if (!behind) {
+      return {};
+    }
+  }
+  try {
+    await git(cwd, ['push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`], { timeoutMs: 120_000 });
+    log(`  pushed ${branch} to origin first`);
+    return { said: `pushed ${branch} to origin first` };
+  } catch (failure) {
+    return { failed: `Could not push ${branch} before opening its pull request: ${failure.message}` };
+  }
+}
+
 async function openPullRequestFor(cwd, { branch, base, title, body }) {
   const existing = await findPullRequest(cwd, branch).catch(() => null);
   if (existing && !existing.includes('/compare/')) {
@@ -3480,8 +4102,28 @@ async function openPullRequestFor(cwd, { branch, base, title, body }) {
     '--body', body,
   ]);
   if (opened.code === 0 && opened.out) {
-    // gh prints the URL and nothing else on success.
-    return { ok: true, result: opened.out.split('\n').pop().trim() };
+    // gh prints the URL and nothing else on success — and then the host is
+    // asked whether it is really there, because "asked for" is not "made",
+    // and a URL on the card that 404s is worse than an honest failure.
+    const printed = opened.out.split('\n').pop().trim();
+    const confirmed = await findPullRequest(cwd, branch).catch(() => null);
+    if (confirmed && !confirmed.includes('/compare/')) {
+      return { ok: true, result: confirmed };
+    }
+    return {
+      ok: false,
+      result: `gh said it opened ${printed}, but the host does not show a pull request for ${branch}.`,
+    };
+  }
+  // The one failure somebody can fix in a minute, said with the fix — and the
+  // link to open it by hand meanwhile, which `findPullRequest` builds without gh.
+  if (opened.code === -1 && /not installed/.test(opened.err)) {
+    const compare = await findPullRequest(cwd, branch).catch(() => null);
+    return {
+      ok: false,
+      result: `${opened.err} Install it and sign in (brew install gh && gh auth login), `
+        + `then ask again${compare ? ` — or open it yourself: ${compare}` : '.'}`,
+    };
   }
   return { ok: false, result: opened.err || opened.out || 'gh pr create failed without saying why.' };
 }
@@ -3514,7 +4156,26 @@ async function openPullRequestFor(cwd, { branch, base, title, body }) {
  * convention wants a merge commit for a release branch too, for the same
  * reason; release branches are not worked through the development board
  * today, and if that changes this is the line that has to change with it.)
+ *
+ * **It waits out GitHub's not-yet-computed mergeability — R306.** The host
+ * computes whether a pull request can merge lazily, and `gh pr merge` seconds
+ * after `gh pr create` — which is exactly when a rule's merge arrives on a
+ * project nobody reads first — can fail for no reason a person can act on.
+ * So before merging, `gh pr view --json mergeable` is asked, and while it says
+ * `UNKNOWN` this waits, bounded (`MERGEABILITY_POLLS` × `mergeabilityWaitMs()`),
+ * for the rule, the board's button and a person's press alike. Any other
+ * answer — `MERGEABLE`, `CONFLICTING`, an error, something that is not JSON —
+ * proceeds at once: the merge itself is what says whether it could, and
+ * `classifyMergeFailure` is unchanged.
  */
+const MERGEABILITY_POLLS = 6;
+
+/** Between two mergeability questions. Five seconds, unless the environment says otherwise — `gateTimeoutSeconds`'s shape. */
+function mergeabilityWaitMs() {
+  const configured = Number(process.env.CAWDEV_MERGEABILITY_WAIT_MS);
+  return Number.isFinite(configured) && configured > 0 ? configured : 5000;
+}
+
 async function mergePullRequest(cwd, branch, { method = null } = {}) {
   const url = await findPullRequest(cwd, branch).catch(() => null);
   if (!url || url.includes('/compare/')) {
@@ -3524,6 +4185,7 @@ async function mergePullRequest(cwd, branch, { method = null } = {}) {
       result: 'There is no pull request for this branch to merge. Nothing was merged.',
     };
   }
+  await waitOutUnknownMergeability(cwd, url, branch);
   const mergeCommit = method === 'MERGE_COMMIT';
   const merged = await gh(cwd, ['pr', 'merge', url, mergeCommit ? '--merge' : '--squash', '--delete-branch']);
   if (merged.code === 0) {
@@ -3549,6 +4211,33 @@ async function mergePullRequest(cwd, branch, { method = null } = {}) {
   };
 }
 
+/**
+ * While the host has not yet said whether the pull request can merge, wait —
+ * bounded. See `mergePullRequest`. One log line if it waited at all, so a
+ * merge that took thirty seconds says why.
+ */
+async function waitOutUnknownMergeability(cwd, url, branch) {
+  let waited = 0;
+  for (let poll = 0; poll < MERGEABILITY_POLLS; poll++) {
+    const asked = await gh(cwd, ['pr', 'view', url, '--json', 'mergeable,mergeStateStatus']);
+    if (asked.code !== 0) return;
+    let view;
+    try {
+      view = JSON.parse(asked.out || '{}');
+    } catch {
+      // Not JSON — a gh that answered something else. Nothing to wait for.
+      return;
+    }
+    if (view.mergeable !== 'UNKNOWN') {
+      if (waited) log(`  ${branch}: mergeability known after ${waited}s`);
+      return;
+    }
+    await sleep(mergeabilityWaitMs());
+    waited += mergeabilityWaitMs() / 1000;
+  }
+  log(`  ${branch}: the host still has not computed mergeability after ${waited}s; merging anyway`);
+}
+
 /**
  * Whether a tag exists ON THE REMOTE — R156.
  *
@@ -4272,8 +4961,11 @@ const PROFILE_TOOLS = {
   // R198: a plan run on an ISSUE (a confirm) is handed exactly this list. What
   // differs is one paragraph of prompt, not a tool — the "ended without a plan"
   // note on the issue is the platform's to write, for the reason above.
+  // R302. Less the reads that need the work to exist — `quality_get` — the
+  // same narrowing `toolsForStage` applies to a walk's PLAN stage, by the same
+  // name: a plan run spawned as one process comes through here and not there.
   PLAN: (run) => [
-    ...READ_ONLY_CAWDEV,
+    ...beforeTheWorkExists(READ_ONLY_CAWDEV),
     ...READ_FILES,
     ...GIT_READS,
     ...(run?.entryNumber ? [] : [CARD_WRITE]),
@@ -4520,7 +5212,10 @@ function stagePrompt(stage, carried) {
         + '`git diff` to find out what the work actually changed. A test you could not run is '
         + 'a line in the testbook, not a failure of this stage.'
       : 'Run what proves the work. Report what passed and what did not, with the output. A '
-        + 'failing test is a result, not a failure of this stage.',
+        + 'failing test is a result, not a failure of this stage. The branch\'s SonarQube gate '
+        + 'is one call away — `quality_get`, which reads this run\'s branch by default; a red '
+        + 'gate with new vulnerabilities is a finding to report with the output, not a failure '
+        + 'to hide.',
     MEMORY: 'Write what the NEXT session on this branch needs to know: what was done, what was '
       + 'tried and rejected and why, and anything that turned out to matter and would not be '
       + 'obvious from the diff. Be brief and concrete. This is saved as this branch\'s '
@@ -4947,7 +5642,9 @@ matters — and stop there. Do not decide the verdict. That is the person's.
 The findings go on the card and the person decides Done or Not done.
 
 **Read the code.** Start with \`code_map\` and \`file_deps\` — cawdev has already
-mapped this repository. Then read the work with \`git_reads\` tools.
+mapped this repository. Then read the work with \`git_reads\` tools. \`quality_get\`
+gives the branch's SonarQube gate and the project's open findings; a new
+vulnerability belongs in your comment.
 
 **Check against the Build: and Done when:.** Use \`roadmap_get\` to read the
 card's own words, then check the code against them. Point at what is done and
@@ -5038,13 +5735,39 @@ function writeUserMessage(child, text) {
  * and the qualified name is the one thing that must be exact. R147 was five
  * bugs' worth of evidence that a name a session cannot use is a capability it
  * does not have.
+ *
+ * <p>i257. `stillBackgrounded` names the ones that WERE delegated to but only
+ * with a backgrounded `Agent` call — so "has not used it" would be false and
+ * the fix would be wrong: telling a session to call something again that it
+ * already called would read as broken, not as a nudge. Those get the specific
+ * reason instead, because the generic "use it now" is the wrong instruction —
+ * it already did, and doing it the same way again loses the result the same
+ * way.
  */
-function nudgeText(stage, missing) {
-  const names = missing.map((each) => `\`${each}\``).join(', ');
-  return `cawdev: this project requires ${names}, and this ${stage.stage} stage has not `
-    + 'used it.\n\n'
-    + 'Use it now — `Skill` with `skill: "<name>"`, or `Agent` with `subagent_type: "<name>"` '
-    + '— and then say what it changed about your answer.\n\n'
+function nudgeText(stage, missing, stillBackgrounded = []) {
+  const neverUsed = missing.filter((each) => !stillBackgrounded.includes(each));
+  const clauses = [
+    neverUsed.length
+      ? `has not used ${neverUsed.map((each) => `\`${each}\``).join(', ')}`
+      : null,
+  ].filter(Boolean);
+  const opening = clauses.length
+    ? `cawdev: this project requires ${missing.map((each) => `\`${each}\``).join(', ')}, and `
+      + `this ${stage.stage} stage ${clauses.join(', and ')}.`
+    : `cawdev: this project requires ${missing.map((each) => `\`${each}\``).join(', ')}.`;
+  const backgroundedNames = stillBackgrounded.map((each) => `\`${each}\``).join(', ');
+  const backgroundedNote = stillBackgrounded.length
+    ? `\n\n${backgroundedNames} ${stillBackgrounded.length > 1 ? 'were' : 'was'} delegated to `
+      + 'with `Agent`, but in the background, and its result has not come back. This stage is '
+      + 'one process (R112): your turn ending is indistinguishable, to the daemon, from being '
+      + 'finished, so a backgrounded delegation still in flight when that happens is lost along '
+      + 'with anything gated on it. Call it again with `run_in_background: false` and wait for '
+      + 'it in this same turn before finishing.'
+    : '';
+  return `${opening}${backgroundedNote}\n\n`
+    + 'Use it now — `Skill` with `skill: "<name>"`, `Agent` with `subagent_type: "<name>"`, or '
+    + 'for an MCP server a call to one of its tools (`mcp__<server>__…`) — and then say what it '
+    + 'changed about your answer.\n\n'
     + 'If it genuinely does not apply to this work, say so in one sentence and stop. '
     + '**You will not be asked again.**';
 }
@@ -5271,6 +5994,120 @@ function heldWorkspaces() {
   return held;
 }
 
+/**
+ * Which checkout an offered coding run gets, or why it must keep waiting —
+ * R71/i258.
+ *
+ * In order: a NAMED checkout (`offered.workspace`) is the only answer once
+ * the branch is bound to it — served or busy, nothing else is considered. A
+ * PREFERRED checkout (`offered.preferredWorkspace`) is taken when free,
+ * dirty or not: it is the checkout the branch last ran in, so uncommitted
+ * work there is plausibly that branch's own leftovers, and routing away from
+ * it risks abandoning work rather than protecting it. That is pin-shaped
+ * reasoning, and it is deliberate that cleanliness plays no part in this
+ * rung — do not "fix" it in passing.
+ *
+ * The one exception is `offered.waitForClean` — R270. Once the person has
+ * said "don't touch dirty", the idea that the leftovers are probably this
+ * branch's own no longer applies: the preferred checkout is taken only when
+ * it reads clean, and otherwise the run falls through to the free scan below
+ * exactly as if it had no preference at all.
+ *
+ * Below that, a checkout is free game and cleanliness finally matters: the
+ * first free path that reads CLEAN wins, and only when nothing free is known
+ * clean does the first free path win regardless — today's behaviour,
+ * unchanged, so the existing refusal in `prepareWorkingCopy` and the
+ * console's *Start anyway* flow still work exactly as they did. With
+ * `waitForClean` set, that last fallback does not happen: the run keeps
+ * waiting instead of taking a dirty checkout.
+ *
+ * Cleanliness is read fresh, right here, rather than from
+ * `surveyWorkingCopies`'s heartbeat reading — see `looksClean`. `probed` is a
+ * `Map` the caller creates once per poll pass, so several offers of one
+ * project only ask each checkout once.
+ *
+ * `surveyGit` and `checkMerges` use the same `workspaces.find((path) =>
+ * !held.has(path))` idiom this replaces, and must NOT be unified with this:
+ * they read refs, never the tree, so which checkout they pick is a different
+ * question and dirtiness does not bear on it.
+ */
+async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0) {
+  const pinned = offered.workspace ?? null;
+  if (pinned) {
+    if (!project.workspaces.includes(pinned)) {
+      // Not one of ours. The platform pins a machine as well as a path, so
+      // this means the config changed under a live branch — which is a
+      // thing to say out loud rather than quietly ignore.
+      return { workspace: null, why: `its branch is in ${pinned}, which this machine does not serve` };
+    }
+    if (held.has(pinned)) {
+      return {
+        workspace: null,
+        why: `waiting for ${pinned}, which is busy — the branch has work only that checkout holds`,
+      };
+    }
+    return { workspace: pinned, why: null };
+  }
+
+  const waitForClean = offered.waitForClean === true;
+  const preferred = offered.preferredWorkspace ?? null;
+  if (preferred && project.workspaces.includes(preferred) && !held.has(preferred)) {
+    if (!waitForClean) {
+      return { workspace: preferred, why: null };
+    }
+    if (!probed.has(preferred)) probed.set(preferred, await looksClean(preferred));
+    if (probed.get(preferred) === true) return { workspace: preferred, why: null };
+  }
+
+  const free = project.workspaces.filter((path) => !held.has(path));
+  if (!free.length) {
+    // Every checkout is busy. Where the machine allows it, make one more
+    // rather than wait — the second coding session on a project starting at
+    // once is the whole point of `autoWorkspaces`.
+    const first = project.workspaces[0];
+    const made = project.workspaces.filter((path) => isAutoWorkspace(first, path));
+    if (made.length < autoMax) {
+      try {
+        log(`every checkout of ${slug} is busy — cloning another beside ${first}`);
+        const path = await createAutoWorkspace(first, project.workspaces);
+        project.workspaces.push(path);
+        log(`  made ${path} (${made.length + 1} of ${autoMax} on demand)`);
+        return { workspace: path, why: null };
+      } catch (failure) {
+        log(`  could not make another checkout of ${slug}: ${failure.message}`);
+        return { workspace: null, why: `no free workspace in ${slug}, and cloning another failed` };
+      }
+    }
+    return {
+      workspace: null,
+      why: autoMax
+        ? `no free workspace in ${slug} (${project.workspaces.length} here, all busy, `
+          + `and the ${autoMax} this machine may make are made)`
+        : `no free workspace in ${slug} (${project.workspaces.length} here, all busy)`,
+    };
+  }
+  for (const path of free) {
+    if (!probed.has(path)) probed.set(path, await looksClean(path));
+    if (probed.get(path) === true) return { workspace: path, why: null };
+  }
+  // Nothing free reads clean — including anything `looksClean` could not read
+  // at all, which groups with dirty rather than clean.
+  if (waitForClean) {
+    // R270: the person said to wait rather than go ahead on top of somebody
+    // else's work. Keep waiting instead of falling back to the old
+    // first-free rule below.
+    return {
+      workspace: null,
+      why: `waiting for a clean checkout in ${slug} — every free one has uncommitted work or `
+        + 'could not be read; stash or commit in one, or wait for a running session to finish',
+    };
+  }
+  // Fall back to the old first-free rule verbatim, so the refusal and *Start
+  // anyway* flow still apply to exactly this workspace.
+  log(`every free checkout in ${slug} has uncommitted work — taking ${free[0]}`);
+  return { workspace: free[0], why: null };
+}
+
 function noteQueued(run, why) {
   // Once per REASON, not once per run — R70, now that there are two gates a run
   // can be held by. A run refused by the machine's cap and then, when a session
@@ -5312,6 +6149,10 @@ function snapshotRuns() {
       // Which checkout it is in — R47. On a machine serving three, the label
       // alone no longer says where the work is.
       workspace: child.cawdevWorkspace ?? null,
+      // Which CLI, and which model it is on — per STAGE on a walked run,
+      // since each stage is its own process with its own model (R112).
+      agent: child.cawdevAgent ?? null,
+      model: child.cawdevModel ?? null,
       startedAt: child.cawdevStartedAt ?? null,
     });
   }
@@ -5392,6 +6233,19 @@ async function startRun(config, offered, workspace) {
     defaultBranch = claimed.defaultBranch;
     // Whether somebody was shown the uncommitted work and started anyway.
     allowDirty = claimed.allowDirty === true;
+    // Or whether the uncommitted work is THIS BRANCH'S OWN: the platform named
+    // the checkout (R86/R87 — a carried-on run's held workspace, or the next
+    // run of a pinned work item) and it is already on the run's branch. R80
+    // holds a failed run's checkout precisely so its work survives, and
+    // refusing that work as "yours, commit it first" turned every Carry on
+    // into a second failure with nothing in the console able to break the loop.
+    if (!allowDirty && offered.workspace && path && writesCodeProfile(run) && run.branch) {
+      const on = await git(resolve(path), ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => '');
+      if (on.trim() === run.branch) {
+        allowDirty = true;
+        log(`  ${path} is on ${run.branch} already — its uncommitted work is this branch's, kept`);
+      }
+    }
     // And what this project has decided happens when the run ends — R40. The
     // daemon does not act on this: the platform queues the push, the pull
     // request and the merge as actions and `settleActions` performs them. It is
@@ -5412,6 +6266,17 @@ async function startRun(config, offered, workspace) {
     if (run.baseBranch) {
       log(`  cut from ${run.baseBranch} (the sprint's branch)`);
     }
+    // R300. Which SonarQube project this is and where — two FACTS the
+    // scanner needs on its command line, learnt with the claim because
+    // reading a project is session-only. No token comes with them; the
+    // scanner runs with this machine's own, from the variable the `quality`
+    // block names. Stored on the run the way `baseBranch` is, so the walk
+    // reads them off `run` after TEST rather than through another parameter.
+    run.sonarProjectKey = claimed.sonarProjectKey ?? null;
+    run.sonarUrl = claimed.sonarUrl ?? null;
+    // R316. Whether the project SAYS its server refuses branches — null is
+    // "not sure, try the branch scan first", today's behaviour.
+    run.sonarBranches = claimed.sonarBranches ?? null;
     // R69. Whether this is the same conversation picked back up, and which one.
     // Null on an ordinary claim, which is nearly all of them.
     resume = claimed.resume ?? null;
@@ -5652,9 +6517,9 @@ async function skipRest(config, run, lifecycle, from, why) {
 
 async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace, resume,
     projectServers, expertAgents, skills, instincts, briefing, plan, lifecycle, shield) {
-  const spawn = (stage, carried) => spawnAgent(config, run, runToken, cwd, baseCommit, workspace,
-    resume, projectServers, expertAgents, skills, instincts, briefing, plan, lifecycle, shield,
-    stage, carried);
+  const spawn = (stage, carried, usage) => spawnAgent(config, run, runToken, cwd, baseCommit,
+    workspace, resume, projectServers, expertAgents, skills, instincts, briefing, plan, lifecycle,
+    shield, stage, carried, usage);
 
   // No lifecycle, or a resume: one process, exactly as before.
   //
@@ -5671,8 +6536,34 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
   const carried = {};
   let last = null;
 
+  // R305. What the RUN has been credited with so far. Each stage is its own
+  // process with its own cumulative counter, so the base the next child adds
+  // to must move — read once from the claim, it stayed at zero and the platform
+  // ignored every stage after the first as a reading that went backwards, so a
+  // five-stage run's stored total was its largest stage rather than the sum.
+  const spent = { tokensIn: Number(run.tokensIn) || 0, tokensOut: Number(run.tokensOut) || 0 };
+  // And what each STAGE was already credited with, for the same reason. A run
+  // walked a second time in a fresh session — handed off to another machine,
+  // or one that died before the CLI said its session id — re-walks the same
+  // `run_stage` rows, and the claim's total already holds the first walk; a
+  // stage counted from zero here would be kept as max(walk) by the platform
+  // while the run kept the sum. Read once; an older platform, or a stub,
+  // answers without the fields and the base is zero, which is today's number.
+  const stored = await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/stages`)
+    .catch(() => []);
+  const creditedTo = (name) => {
+    const row = Array.isArray(stored) ? stored.find((each) => each?.stage === name) : null;
+    return { tokensIn: Number(row?.tokensIn) || 0, tokensOut: Number(row?.tokensOut) || 0 };
+  };
+
   for (let at = 0; at < lifecycle.length; at++) {
     const stage = lifecycle[at];
+    // R305. What THIS stage's processes have used, across its attempts. Outside
+    // the attempt loop on purpose: `run_stage` is one row per stage and keeps
+    // the larger reading, so a second attempt after a refused gate must report
+    // the first attempt's total plus its own, or the row would show
+    // max(attempt) and the stages would no longer sum to the run.
+    const stageSpent = creditedTo(stage.stage);
     // Two attempts at most, and the second only exists because a REFUSED gate
     // should cost one cheap stage rather than a whole run. A third would be a
     // loop nobody asked for.
@@ -5681,7 +6572,19 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
       log(`  ${stage.stage}${stage.model ? ` on ${stage.model}` : ''}`
         + `${attempt ? ' (again, after the gate refused it)' : ''}`);
 
-      last = await spawn(stage, carried);
+      // Both handed BY REFERENCE and moved below once the child is over. Safe
+      // only because stages run one at a time: the child reads them at each
+      // `result` event, and nothing else touches them while it lives.
+      last = await spawn(stage, carried, { run: spent, stage: stageSpent });
+
+      // Credited before the exit is judged, so a stage that was killed or
+      // skipped still counts what its `result` events said it used.
+      if (last?.usage) {
+        spent.tokensIn += last.usage.input;
+        spent.tokensOut += last.usage.output;
+        stageSpent.tokensIn += last.usage.input;
+        stageSpent.tokensOut += last.usage.output;
+      }
 
       // A clean exit, OR a turn that ended. The second half is the half that
       // matters now: `endSession` closes a stage's input when its turn is over
@@ -5798,6 +6701,15 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
 
     carried[stage.stage] = last.text;
 
+    // R300. The scanner, after TEST settles and before the next stage — on
+    // the tree the tests just ran against, by the daemon and not the session.
+    // AWAITED: the workspace is released in `perform`'s finally, and a
+    // scanner still reading files when the next run's reset runs is the
+    // hazard; the block's `timeoutSeconds` bounds the wait. It never throws.
+    if (stage.stage === 'TEST' && run.branch && writesAnythingProfile(run)) {
+      await scanQuality(config, run, cwd, run.branch);
+    }
+
     // R108. The MEMORY stage's output IS the briefing, saved by the DAEMON
     // rather than by the session calling a tool. One less thing to trust, and
     // one less tool to hand a stage that should not be writing.
@@ -5908,7 +6820,11 @@ function gateTimeoutSeconds() {
 async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, resume,
     projectServers, expertAgents, skills, instincts, briefing, plan, lifecycle, shield,
     stage = null,
-    carried = null) {
+    carried = null,
+    // R305. `{ run, stage }`: what the run and this stage had already used
+    // before this child, as the walk counted them. Null on an unstaged run or
+    // a resume, where the claim's own figure is the base and there is no stage.
+    usage = null) {
   // R51: what this machine will let a STORED rule cover. The project's rules
   // are filtered through it before they go anywhere near a spawn, so the
   // platform can narrow what runs here and never widen it.
@@ -5951,11 +6867,19 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
   // checked against the real CLI by hand) that it is not this function's
   // Claude-specific machinery with a different binary name; it is
   // `spawnAntigravity`, entirely.
+  // Codex's own shape — a real sandbox and a per-server tool list, but no
+  // allow-list for the shell — is `spawnCodex`, for the same reason.
+  if ((stage?.agent ?? run.agent) === 'codex') {
+    const codexCmd = config.agentCommands.find((each) => agentOfCommand(each) === 'codex') ?? 'codex';
+    return spawnCodex(config, run, runToken, cwd, baseCommit, resume, projectServers,
+      skills, stageExperts, readOnlyStage, instincts, briefing, plan, lifecycle, stage, carried,
+      codexCmd, granted, shield, usage);
+  }
   if ((stage?.agent ?? run.agent) === 'agy') {
-    const agyCmd = config.agentCommands.find((each) => each.endsWith('agy')) ?? 'agy';
+    const agyCmd = config.agentCommands.find((each) => agentOfCommand(each) === 'agy') ?? 'agy';
     return spawnAntigravity(config, run, runToken, cwd, baseCommit, resume, projectServers,
       skills, stageExperts, cannotDelegate, instincts, briefing, plan, lifecycle, stage, carried,
-      agyCmd, granted);
+      agyCmd, granted, usage);
   }
 
   const ceiling = [
@@ -6073,10 +6997,31 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
   // required HERE: requiring what the stage was deliberately not given is how
   // this would come to widen what a run may do, which is the one thing it must
   // not do. The mode is read after the narrowing, always.
+  //
+  // R303. An MCP server can be required too, and the entry comes from
+  // `attached` — what this machine actually spawned — and NEVER from the
+  // claim's list, for exactly the reason above: a server the machine refused
+  // cannot be required of a session that has no such tool. And only when the
+  // stage can reach it: a read-only stage is spawned with `listOnly`, which
+  // strips the permission prompt, and `mcp__<server>__*` is never on its list —
+  // so a PLAN stage told it MUST call `mcp__codegraph__…` would be nudged for
+  // something it was deliberately not given. IMPLEMENT and TEST, and a run
+  // with no lifecycle, keep the prompt and can answer the first call.
+  //
+  // Keyed `<kind>:<name>` on both sides — here and where `used` is filled —
+  // so a server named like a skill cannot satisfy the other's requirement.
+  const serversCanBeReached = !readOnlyStage;
   const mustUse = new Set([
-    ...stageExperts.filter((each) => each.mode === 'REQUIRED').map((each) => qualified(each.key)),
-    ...skills.filter((each) => each.mode === 'REQUIRED').map((each) => qualified(each.key)),
+    ...stageExperts.filter((each) => each.mode === 'REQUIRED')
+      .map((each) => `EXPERT:${qualified(each.key)}`),
+    ...skills.filter((each) => each.mode === 'REQUIRED')
+      .map((each) => `SKILL:${qualified(each.key)}`),
+    ...(serversCanBeReached ? attached : [])
+      .filter(({ skill }) => skill.mode === 'REQUIRED')
+      .map(({ skill }) => `MCP_SERVER:${skill.serverName}`),
   ]);
+  /** The transcript's name for a requirement — what the nudge and the log say. */
+  const nameOf = (entry) => entry.slice(entry.indexOf(':') + 1);
 
   // R104/R105. The experts and skills the project turned on, as one plugin in
   // the daemon's own directory — see writeRunPlugin for why not the checkout.
@@ -6216,6 +7161,14 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
       description: each.description ?? each.name ?? each.key,
       required: each.mode === 'REQUIRED',
     })),
+    // R303. Only a REQUIRED server changes the prompt, and only where the
+    // stage can reach it — the same gate `mustUse` applies, so the prompt and
+    // the nudge never disagree about what a stage owes.
+    mcpServers: attached.map(({ skill }) => ({
+      name: skill.name ?? skill.key,
+      prefix: skill.toolPrefix ?? `mcp__${skill.serverName}`,
+      required: serversCanBeReached && skill.mode === 'REQUIRED',
+    })),
     cannotDelegate,
     // R124. Null on everything but an implementation phase whose card has been
     // planned, which the PLATFORM decides — the runner does not work out which
@@ -6260,10 +7213,10 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
   // Reaching here at all means Claude Code answers this run — the branch at
   // the top of this function sent Antigravity to spawnAntigravity instead.
   // Matched against what this machine actually lists (`config.agentCommands`)
-  // by the same suffix rule `readUsage` uses the other way around, so a
-  // machine whose list is agy-first still gets Claude Code's own command.
-  const agentCmd = config.agentCommands.find((each) => !each.endsWith('agy'))
-    ?? config.agentCommands[0] ?? 'claude';
+  // by `agentOfCommand`, the rule `readUsage` uses too, so a machine whose list
+  // is agy- or codex-first still gets Claude Code's own command.
+  const agentCmd = config.agentCommands.find((each) => agentOfCommand(each) === 'claude')
+    ?? 'claude';
 
   const args = [
     '--mcp-config',
@@ -6298,6 +7251,11 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
     });
 
     child.cawdevProjectSlug = run.projectSlug;
+    // Which CLI and which model — what advanced mode puts in a window's title.
+    // The model asked for now; the one the CLI says it is on replaces it at
+    // `init` (below), which is also the only answer when none was asked.
+    child.cawdevAgent = 'claude';
+    child.cawdevModel = model ?? null;
     // The checkout this child holds, and what the queue serialises on. Null for
     // a run that took none, which is what lets an ASK session run alongside
     // three coding ones.
@@ -6345,6 +7303,9 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
       ?? (promptFor(run) + harness + (stage ? stagePrompt(stage, carried) : '')));
 
     let lastText = '';
+    // R305. This child's own last reading, handed back to the walk so the next
+    // stage's base can move.
+    let childTotals = null;
     // Whether the CLI ever said its turn was over. This, and not the exit code,
     // is what says a STAGE did its work — see the failure branch in
     // walkLifecycle, and endSession above for why the two came apart.
@@ -6354,6 +7315,17 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
     // asked of the platform: the answer is needed at the `result` event, and a
     // question that has to cross the network cannot be answered in time.
     const used = new Set();
+    // i257. A required expert's `Agent(...)` line is written the instant the
+    // call is MADE (R130), not when its result comes back — so `used` alone
+    // cannot tell "delegated and waited" from "delegated and moved on". This
+    // holds the qualified name of every required expert whose most recent
+    // `Agent`/`Task` call was NOT `run_in_background: false` — added on that
+    // call, and removed the moment the same name is called again WITH it. A
+    // stage is one process and gets one turn (R112); a session that ends its
+    // turn with a name still in here dispatched the delegation and did not
+    // wait for it, which is exactly the shape that loses it when `endSession`
+    // closes stdin below.
+    const backgrounded = new Set();
     // The last of what the CLI said on stderr, for the exit decision below.
     // The usage-limit notice is written there, and a decision made on stdout
     // alone would call every window a crash.
@@ -6453,7 +7425,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
       // R161. A required one says so where the person is looking. Only when the
       // stage can actually reach it: `cannot` and this are mutually exclusive
       // by construction, because `mustUse` is built from `stageExperts`.
-      const must = mustUse.has(qualified(agent.key))
+      const must = mustUse.has(`EXPERT:${qualified(agent.key)}`)
         ? ' This project REQUIRES it: if this stage finishes without using it, the session '
           + 'will be told.'
         : '';
@@ -6464,7 +7436,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
     }
 
     for (const skill of skills) {
-      const must = mustUse.has(qualified(skill.key))
+      const must = mustUse.has(`SKILL:${qualified(skill.key)}`)
         ? ' This project REQUIRES it: if this stage finishes without using it, the session '
           + 'will be told.'
         : '';
@@ -6496,8 +7468,10 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
 
     // R76. What this run had already used before this child started. Zero on an
     // ordinary run; on a resume it is what the earlier session spent, which the
-    // claim carries on the run itself.
-    const usageBase = {
+    // claim carries on the run itself. R305: on a staged run the walk keeps the
+    // count, because the claim's figure never moves and every stage after the
+    // first would otherwise report from zero again.
+    const usageBase = usage?.run ?? {
       tokensIn: Number(run.tokensIn) || 0,
       tokensOut: Number(run.tokensOut) || 0,
     };
@@ -6513,6 +7487,70 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
         buffer = buffer.slice(newline + 1);
         if (!line) continue;
         const event = safeJson(line);
+
+        // i257. Read off the RAW event, before `linesOf` flattens it to a
+        // string: `describeCall` (`../lib/tool-line.mjs`) never carries
+        // `run_in_background` into the TOOL line it writes — deliberately not
+        // extended for it, because that line is a parsing contract three
+        // implementations share (`CapabilityUse.java`, `capability-tag.ts`),
+        // and this is a daemon-internal question none of the three need
+        // answered. So this is the one place that can still see the field.
+        // Record-then-decide, ahead of the loop below that reacts to
+        // `result`, so a `result` on this same line always sees this line's
+        // own dispatches first.
+        //
+        // Only tracked for a REQUIRED expert. An optional one backgrounded is
+        // the session's own call and nothing here gates on it.
+        //
+        // Known consequence of not extending the shared line: the platform's
+        // own ledger (`RunCapabilityService.used`, called from
+        // `RunService.appendOutput` on the same TOOL line and read by the run
+        // panel) increments `RunCapability.uses` the instant the line is
+        // written, exactly like `used` below — it has no way to learn a
+        // dispatch was backgrounded, so a stage this nudge caught and that
+        // then corrected itself still reads as an ordinary "required,
+        // delegated to 1×" on the panel afterwards. That is this card's
+        // trade-off, made on purpose: the daemon is the one place that can
+        // still leave with the delegation unfinished, so it is the one place
+        // that has to catch it before it does. Making the panel say so too is
+        // a different card, not a reason to read it as ground truth here.
+        //
+        // The default-background assumption this rests on is not a guess:
+        // i249 and i250 are both a `Agent(...)` call with no
+        // `run_in_background` at all whose result never came back — this
+        // project's own Agent tool backgrounds unless told `false`. If a
+        // spawned CLI's `Agent` were ever synchronous by default, this would
+        // nudge a stage that did nothing wrong — loud, not silent, and capped
+        // at one wasted turn by `child.cawdevNudged` below.
+        //
+        // Keyed `EXPERT:<name>`, matching `mustUse`/`used`: a Set of bare
+        // names would let a REQUIRED skill and a REQUIRED expert that share a
+        // qualified name mark each other's requirement backgrounded.
+        //
+        // The last call to a name wins. A session that is awaited once and
+        // backgrounded again later is reported missing on the second call —
+        // "requirement met" and "something is in flight" are conflated on
+        // purpose, because the second call is the one whose result this
+        // stage's turn is actually at risk of losing.
+        if (event?.type === 'assistant') {
+          for (const part of event.message?.content ?? []) {
+            if (part?.type !== 'tool_use' || (part.name !== 'Agent' && part.name !== 'Task')) {
+              continue;
+            }
+            const who = typeof part.input?.subagent_type === 'string'
+              ? part.input.subagent_type : null;
+            const entry = who ? `EXPERT:${who}` : null;
+            if (!entry || !mustUse.has(entry)) {
+              continue;
+            }
+            if (part.input?.run_in_background === false) {
+              backgrounded.delete(entry);
+            } else {
+              backgrounded.add(entry);
+            }
+          }
+        }
+
         if (event?.type === 'result') {
           if (typeof event.result === 'string') {
             lastText = event.result;
@@ -6578,7 +7616,18 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
             // lifecycle never reaches here — `endSession` is deliberately not
             // called for one — so REQUIRED is prompt wording and a console row
             // on ASK, ROADMAP and AUDIT, and nothing more.
-            const missing = [...mustUse].filter((name) => !used.has(name));
+            // i257. `used` alone says "the name appeared in a TOOL line",
+            // which is true the instant a required expert is DISPATCHED —
+            // backgrounded or not. An entry still in `backgrounded` was
+            // delegated but never waited for, so it counts as missing here
+            // too. `stillBackgroundedEntries` keeps the `EXPERT:` prefix so it
+            // can only ever match the Set it was built from; only its NAMES
+            // (`nameOf`) are for display.
+            const stillBackgroundedEntries = [...mustUse].filter((entry) => backgrounded.has(entry));
+            const trulyMissingEntries = [...mustUse].filter((entry) => !used.has(entry));
+            const missing = [...new Set([...trulyMissingEntries, ...stillBackgroundedEntries])]
+              .map(nameOf);
+            const stillBackgrounded = stillBackgroundedEntries.map(nameOf);
             // Whether the input stays open for one more turn. NOT an early
             // return out of this handler, which the obvious shape would be:
             // this is the stdout reader's `while`, and returning from it would
@@ -6589,8 +7638,24 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
               // Once per process. A model that has decided cannot be looped:
               // this is a nudge, not an argument.
               child.cawdevNudged = true;
-              const line = `cawdev: this stage has not used ${missing.join(', ')}, `
-                + 'which this project requires. Asking it once.';
+              // i257. "has not used" is not true of `stillBackgrounded` — it
+              // WAS called, just not waited for — and this line is the half
+              // of the nudge a person actually reads (`nudgeText` below goes
+              // to the child's stdin, never to the transcript). This card
+              // exists because a run once said nothing was done when work
+              // really happened; a nudge that misdescribes its own trigger
+              // would be the same mistake at smaller scale.
+              const trulyMissingNames = trulyMissingEntries.filter((entry) => !backgrounded.has(entry))
+                .map(nameOf);
+              const clauses = [
+                trulyMissingNames.length ? `has not used ${trulyMissingNames.join(', ')}` : null,
+                stillBackgrounded.length
+                  ? `delegated to ${stillBackgrounded.join(', ')} only in the background and never `
+                    + 'waited for it'
+                  : null,
+              ].filter(Boolean);
+              const line = `cawdev: this stage ${clauses.join(', and ')}, which this project `
+                + 'requires. Asking it once.';
               log(`  ${line}`);
               transcript.push({ kind: 'SYSTEM', body: line });
               // The return value is load-bearing. It is false when stdin is
@@ -6598,7 +7663,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
               // through to `endSession` is what stops a dead session from never
               // being dismissed. That is R22's forty-three minutes arriving
               // through a new door.
-              nudged = writeUserMessage(child, nudgeText(stage, missing));
+              nudged = writeUserMessage(child, nudgeText(stage, missing, stillBackgrounded));
               if (nudged) {
                 // The turn runs again and the next `result` closes the input.
                 // This timer is the whole defence against the one deadlock this
@@ -6623,6 +7688,9 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
         if (event?.type === 'system' && event.subtype === 'init' && event.session_id) {
           reportSessionId(config, run, event.session_id);
         }
+        if (event?.type === 'system' && event.subtype === 'init' && event.model) {
+          child.cawdevModel = event.model;
+        }
         // R76. What the session has consumed, recorded rather than only
         // printed. Caught here for the reason the session id is: the CLI says
         // it on a `result` event and nowhere else.
@@ -6635,10 +7703,19 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
         if (event?.type === 'result') {
           const totals = totalsOf(event);
           if (totals) {
+            childTotals = totals;
             reportUsage(config, run, {
               tokensIn: usageBase.tokensIn + totals.input,
               tokensOut: usageBase.tokensOut + totals.output,
             });
+            // R305. The same reading, filed on the stage: its own base plus
+            // this child, absolute for the stage across its attempts.
+            if (stage && usage?.stage) {
+              reportStageUsage(config, run, stage.stage, {
+                tokensIn: usage.stage.tokensIn + totals.input,
+                tokensOut: usage.stage.tokensOut + totals.output,
+              });
+            }
           }
         }
         // R113. Anything at all counts as alive.
@@ -6682,7 +7759,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
             // already being walked. See ../lib/tool-line.mjs.
             const reached = capabilityIn(recorded.body);
             if (reached) {
-              used.add(reached.key);
+              used.add(`${reached.kind}:${reached.key}`);
             }
           }
           if (stage && recorded.kind === 'TOOL') {
@@ -6815,7 +7892,9 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
       // R112. A stage hands its result back so the loop can store the plan,
       // gate on it, and carry it into the next stage. A run with no lifecycle
       // resolves with nothing, exactly as it always did.
-      resolvePromise(stage ? { code, signal, text: lastText, turnEnded } : undefined);
+      resolvePromise(stage
+        ? { code, signal, text: lastText, turnEnded, usage: childTotals }
+        : undefined);
     });
   });
 }
@@ -7111,7 +8190,7 @@ function inlinedSkillsFor(skills) {
  */
 async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume, projectServers,
     skills, stageExperts, cannotDelegate, instincts, briefing, plan, lifecycle, stage, carried,
-    agyCmd, granted) {
+    agyCmd, granted, usage = null) {
   if (!granted.everything) {
     const summary = 'This machine has not allowed everything, and Antigravity has no narrower '
       + 'permission mode — no per-tool allow-list exists on it, and even reading needs it. Turn '
@@ -7231,6 +8310,13 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
 
   return new Promise((resolvePromise) => {
     let result = null;
+    // R76 / R305: what the run had already used before this process, and what
+    // this process itself reported — see the same pair on the Claude Code path.
+    const usageBase = usage?.run ?? {
+      tokensIn: Number(run.tokensIn) || 0,
+      tokensOut: Number(run.tokensOut) || 0,
+    };
+    let childTotals = null;
     let err = '';
     let buffer = '';
     const child = spawn(agyCmd, args, {
@@ -7240,6 +8326,8 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     child.cawdevProjectSlug = run.projectSlug;
+    child.cawdevAgent = 'agy';
+    child.cawdevModel = run.model ?? null;
     // The existing cancellation sweep (`reapCancelled`) reads this map by
     // run id and SIGTERMs whatever is in it — true for any child, so a
     // cancelled Antigravity run stops exactly the way a cancelled Claude
@@ -7312,10 +8400,23 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
         } else if (event.event === 'result') {
           result = event.result;
           if (result?.usage) {
+            // R305. On the same base as the Claude Code path: what the run had
+            // already used before this process. Reported with no base until
+            // now, so a resume or a second stage here counted from zero.
+            childTotals = {
+              input: Number(result.usage.input_tokens) || 0,
+              output: Number(result.usage.output_tokens) || 0,
+            };
             reportUsage(config, run, {
-              tokensIn: Number(result.usage.input_tokens) || 0,
-              tokensOut: Number(result.usage.output_tokens) || 0,
+              tokensIn: usageBase.tokensIn + childTotals.input,
+              tokensOut: usageBase.tokensOut + childTotals.output,
             });
+            if (stage && usage?.stage) {
+              reportStageUsage(config, run, stage.stage, {
+                tokensIn: usage.stage.tokensIn + childTotals.input,
+                tokensOut: usage.stage.tokensOut + childTotals.output,
+              });
+            }
           }
         }
       }
@@ -7365,7 +8466,293 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
       if (!stage) {
         await settleActions(config, run, cwd);
       }
-      resolvePromise(stage ? { code, signal: null, text, turnEnded } : undefined);
+      resolvePromise(stage
+        ? { code, signal: null, text, turnEnded, usage: childTotals }
+        : undefined);
+    });
+  });
+}
+
+/**
+ * The cawdev tools a Codex process may call — the SAME list Claude Code's
+ * `--allowedTools` would hold for this run and stage, without the prefix.
+ *
+ * <p>`enabled_tools` on cawdev's server is the one narrowing this CLI does as
+ * precisely as Claude Code: a tool left out is not offered at all (checked by
+ * hand). So the list is derived from `PROFILE_TOOLS` and `toolsForStage`
+ * rather than chosen here — a second place deciding what a profile may do is
+ * how the two agents would drift. Above all, `toolsForStage` takes `report`
+ * away from every STAGE, whose "done" would end the run in the middle of the
+ * walk.
+ *
+ * <p>Null — every tool the server has — only for a coding run with no
+ * lifecycle, which can only be spawned where the machine allowed everything.
+ */
+function codexCawdevTools(run, stage, mayWrite) {
+  const profile = PROFILE_TOOLS[run.profile];
+  const profileList = profile ? (typeof profile === 'function' ? profile(run) : profile) : null;
+  if (stage) {
+    return cawdevToolNames(toolsForStage(stage.stage, profileList ?? CAWDEV_TOOLS, stage.testMode,
+      { writesItsOwnCard: writesItsOwnCard(run) }));
+  }
+  if (profileList) {
+    return cawdevToolNames(profileList);
+  }
+  return mayWrite ? null : cawdevToolNames(READ_ONLY_CAWDEV);
+}
+
+/**
+ * OpenAI's Codex CLI — one `codex exec` per turn, like Antigravity, and the
+ * command line, the stream and every flag's behaviour are `../lib/codex.mjs`,
+ * checked against the real CLI.
+ *
+ * <p>What it has that Antigravity lacks is a SANDBOX the operating system
+ * enforces, and that decides the permission question:
+ *
+ * <ul>
+ * <li>A session that must change nothing — every profile but the coding
+ *   ones, and PLAN, VERIFY and MEMORY of any run — is spawned with
+ *   `--sandbox read-only`. Its shell can read and cannot write, and it does
+ *   not need the machine to have allowed anything: "cannot" is the kernel's
+ *   word here, not the prompt's. Only cawdev's server is attached, narrowed
+ *   to the profile's list by `codexCawdevTools`.
+ * <li>A session that writes — CODE, INTERVIEW, MERGE, RELEASE, and their
+ *   IMPLEMENT and TEST — has to commit and push, which the workspace sandbox
+ *   refuses (`.git` and the network are outside it). There is no allow-list
+ *   for the shell on this CLI, so it runs with the sandbox bypassed, and
+ *   ONLY where the machine allowed everything (R126) — Antigravity's rule.
+ * </ul>
+ *
+ * <p>Not reached: experts (nothing on this CLI loads cawdev's `agents/*.md`,
+ * so the session is told it cannot delegate rather than shown names it cannot
+ * call), R51's permission prompt and R110's command shield (both live in
+ * `approve`, which Codex never calls) and R22's live prompting (the process
+ * ends with its turn; a follow-up is a resume). Skills are inlined whole, as
+ * for Antigravity. The transcript half of R110 — secrets taken out of a tool
+ * result — does apply, since it runs here and not in the CLI.
+ */
+async function spawnCodex(config, run, runToken, cwd, baseCommit, resume, projectServers,
+    skills, stageExperts, readOnlyStage, instincts, briefing, plan, lifecycle, stage, carried,
+    codexCmd, granted, shield, usage = null) {
+  const failedBeforeSpawn = async (summary) => {
+    log(`  ${summary}`);
+    await finish(config, run, 'FAILED', summary);
+    return stage ? { code: -1, signal: null, text: summary, turnEnded: false } : undefined;
+  };
+
+  const mayWrite = writesCodeProfile(run) && !readOnlyStage;
+  if (mayWrite && !granted.everything) {
+    return failedBeforeSpawn('This machine has not allowed everything, and a Codex session that '
+      + 'writes has no narrower mode — it must commit and push, which its sandbox refuses, and '
+      + 'there is no allow-list for its shell. Turn on "allow everything" for this machine, or use '
+      + 'Claude Code for this run. (Read-only runs and stages need nothing.)');
+  }
+  if (mayWrite) {
+    log('  !! this machine allows EVERYTHING: this Codex session runs without a sandbox');
+  }
+
+  const transcript = new Transcript(config, run);
+  const serverPath = config.mcpServerPath ?? new URL('../mcp/server.mjs', import.meta.url).pathname;
+
+  // The token reaches cawdev's server through `env_vars` — from Codex's own
+  // environment, never its command line — and is blanked for the shell.
+  const cawdevEnv = { CAWDEV_URL: config.url, CAWDEV_TOKEN: runToken, CAWDEV_PROJECT: run.projectSlug };
+  const childEnv = { ...process.env, ...cawdevEnv };
+
+  // By name, so a later server replaces an earlier one whole — the ordering
+  // argument of the Claude Code path: the repository's own first, then R76's
+  // registry, then cawdev's LAST, so nothing can shadow it and take its token.
+  const servers = new Map();
+  if (mayWrite) {
+    for (const [name, server] of Object.entries(await projectMcpServers(cwd))) {
+      if (!server?.command) {
+        transcript.push({ kind: 'SYSTEM',
+          body: `The project's MCP server "${name}" is not a command, and Codex is handed commands only — skipped.` });
+        continue;
+      }
+      servers.set(name, { name, command: server.command, args: server.args, env: server.env });
+    }
+    const { attached, notes } = await resolveSkills(config, run, cwd, baseCommit, projectServers);
+    for (const line of notes) {
+      log(`  ${line}`);
+      transcript.push({ kind: 'SYSTEM', body: line });
+    }
+    for (const { skill, local } of attached) {
+      Object.assign(childEnv, local.env ?? {});
+      servers.set(skill.serverName, {
+        name: skill.serverName, command: skill.command, args: skill.args,
+        envVars: Object.keys(local.env ?? {}),
+      });
+    }
+  }
+  servers.set('cawdev', {
+    name: 'cawdev',
+    command: process.execPath,
+    args: [serverPath],
+    envVars: Object.keys(cawdevEnv),
+    enabledTools: codexCawdevTools(run, stage, mayWrite),
+  });
+
+  const cannotDelegate = stageExperts.length
+    ? ["This project has experts, and Codex has no way to be handed them: nothing on this CLI "
+      + "loads cawdev's expert agents. Do the work yourself; they are reached from Claude Code "
+      + 'and Antigravity runs.']
+    : undefined;
+  if (cannotDelegate) {
+    transcript.push({ kind: 'SYSTEM', body: cannotDelegate[0] });
+  }
+
+  const resuming = Boolean(resume?.agentSessionId);
+  const promptText = resuming
+    ? (resume.prompt ?? '')
+    : (promptFor(run)
+      + harnessPrompt({
+        instincts, briefing, experts: [], skills: [], plan, lifecycle,
+        repoConfig: await readRepoConfig(cwd),
+      })
+      + inlinedSkillsFor(skills)
+      + expertsBlockFor([], cannotDelegate)
+      + (stage ? stagePrompt(stage, carried) : ''));
+
+  const model = stage?.model ?? run.model;
+  const args = codexArgs({
+    model,
+    effort: run.effort,
+    sandbox: mayWrite ? 'bypass' : 'read-only',
+    resumeId: resuming ? resume.agentSessionId : null,
+    servers: [...servers.values()],
+    hideFromShell: Object.keys(cawdevEnv),
+  });
+  log(`  spawning: ${codexCmd} ${args.join(' ')} <prompt on stdin, ${promptText.length} chars>`);
+
+  return new Promise((resolvePromise) => {
+    // R76 / R305: what the run had already used before this process — see the
+    // same pair on the Claude Code path.
+    const usageBase = usage?.run ?? {
+      tokensIn: Number(run.tokensIn) || 0,
+      tokensOut: Number(run.tokensOut) || 0,
+    };
+    let childTotals = null;
+    let ended = false;
+    let failed = null;
+    let lastError = null;
+    let lastSaid = null;
+    let err = '';
+    let buffer = '';
+    const child = spawn(codexCmd, args, {
+      cwd,
+      // Its own process group — see the same choice on the Claude Code path.
+      detached: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: childEnv,
+    });
+    child.cawdevProjectSlug = run.projectSlug;
+    child.cawdevAgent = 'codex';
+    child.cawdevModel = model ?? null;
+    // `reapCancelled` SIGTERMs whatever is here, whichever CLI it is.
+    running.set(run.id, child);
+    child.stdin.on('error', () => {
+      // A CLI that died before reading its prompt says why on stderr.
+    });
+    child.stdin.end(promptText);
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk;
+      let newline;
+      while ((newline = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (!line.trim()) continue;
+        let event;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          transcript.push({ kind: 'SYSTEM', body: line.slice(0, 4000) });
+          continue;
+        }
+        const read = translateCodexEvent(event);
+        if (read.sessionId) {
+          reportSessionId(config, run, read.sessionId);
+          transcript.push({
+            kind: 'SYSTEM',
+            body: `session ${short(read.sessionId)} started${model ? ` on ${model}` : ''}`
+              + (mayWrite ? '' : ' (read-only sandbox)'),
+          });
+        }
+        for (const recorded of read.lines) {
+          // R110's transcript half, as on the Claude Code path: a credential
+          // that came back from a command is replaced before it is stored.
+          if (shield?.blockSecrets !== false && recorded.kind === 'TOOL_RESULT') {
+            const found = findSecret(recorded.body);
+            if (found) {
+              recorded.body = `[cawdev removed ${found.name} from this result] ${found.redacted}`;
+              api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/blocks`, {
+                method: 'POST',
+                body: { kind: 'SECRET', detail: `${found.name}: ${found.redacted}` },
+              }).catch(() => {});
+            }
+          }
+          if (recorded.kind === 'ASSISTANT') {
+            lastSaid = recorded.body;
+          }
+          transcript.push(recorded);
+        }
+        if (read.error) {
+          lastError = read.error;
+        }
+        if (read.failed) {
+          failed = read.failed;
+        }
+        if (read.ended) {
+          ended = true;
+          childTotals = read.usage;
+          reportUsage(config, run, {
+            tokensIn: usageBase.tokensIn + childTotals.input,
+            tokensOut: usageBase.tokensOut + childTotals.output,
+          });
+          if (stage && usage?.stage) {
+            reportStageUsage(config, run, stage.stage, {
+              tokensIn: usage.stage.tokensIn + childTotals.input,
+              tokensOut: usage.stage.tokensOut + childTotals.output,
+            });
+          }
+        }
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk).trim();
+      if (text) {
+        log(`  agent stderr: ${text.slice(0, 400)}`);
+      }
+      err += chunk;
+    });
+
+    child.on('error', async (failure) => {
+      running.delete(run.id);
+      const summary = `Could not spawn Codex: ${failure.message}`;
+      await transcript.flush();
+      await finish(config, run, 'FAILED', summary);
+      resolvePromise(stage ? { code: -1, signal: null, text: summary, turnEnded: false } : undefined);
+    });
+
+    child.on('close', async (code) => {
+      running.delete(run.id);
+      await transcript.flush();
+      const text = failed ?? lastSaid ?? lastError ?? (err.trim() || 'Codex produced no output.');
+      // The agent normally ends the run itself with report(done|blocked); this
+      // only catches a turn that produced nothing report could act on.
+      const current = await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}`)
+        .catch(() => null);
+      if (current?.live && !stage) {
+        await finish(config, run, code === 0 && ended && !failed ? 'FINISHED' : 'FAILED', text);
+      }
+      // R112: not between stages — see the same line on the Claude Code path.
+      if (!stage) {
+        await settleActions(config, run, cwd);
+      }
+      resolvePromise(stage
+        ? { code, signal: null, text, turnEnded: ended && !failed, usage: childTotals }
+        : undefined);
     });
   });
 }
@@ -7399,6 +8786,19 @@ function reportUsage(config, run, totals) {
   }).catch((failure) => log(`  could not record what the session used: ${failure.message}`));
 }
 
+/**
+ * The same reading, for one STAGE — R305. Absolute for the stage across its
+ * attempts, fire and forget for the reason `reportUsage` is, and the platform
+ * keeps the largest reading here too.
+ */
+function reportStageUsage(config, run, stageName, totals) {
+  api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/stages/${stageName}/usage`, {
+    method: 'POST',
+    body: totals,
+  }).catch((failure) =>
+    log(`  could not record what the ${stageName} stage used: ${failure.message}`));
+}
+
 async function finish(config, run, state, summary) {
   await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/transition`, {
     method: 'POST',
@@ -7480,6 +8880,14 @@ function capabilities(config) {
     // offered only to a machine that says this, and a machine that does not
     // is told why on the queue rather than handed a base it would ignore.
     baseBranches: true,
+    // R270. This daemon knows an offer can carry `waitForClean`, and honours it
+    // in `pickWorkspace` — taking the preferred checkout only when clean, and
+    // refusing to fall back to a dirty one at all. The same shape as
+    // `baseBranches`: an older daemon that ignored the flag would take the
+    // dirty checkout and fail a run the person explicitly queued to avoid
+    // that, so the platform tells it apart rather than letting one behave
+    // like the other.
+    waitForClean: true,
   });
 }
 
@@ -7499,6 +8907,11 @@ function capabilities(config) {
 async function probePermissionPrompt(config) {
   let allGood = true;
   for (const agentCommand of config.agentCommands) {
+    // A Claude Code flag. Codex never calls a permission prompt — see
+    // `spawnCodex` — and offering it this one would start its terminal UI.
+    if (agentOfCommand(agentCommand) === 'codex') {
+      continue;
+    }
     const said = await new Promise((done) => {
       let text = '';
       let child;
@@ -7558,6 +8971,9 @@ async function main() {
   quiet = attaching;
 
   const config = await readConfig();
+  // The checkouts made on demand by an earlier run of this daemon, found
+  // again by their name — nothing about them is in the config.
+  await syncAutoWorkspaces(config.projects);
   const myVersion = await cliVersion();
 
   // R283. Checked before registering — a daemon too old to be safe should not
@@ -7617,6 +9033,11 @@ async function main() {
     // The paths still go to the log — the banner says how many, this says
     // which, and "which" is what you need when one of them is wrong.
     log(`serving ${slug}: ${project.workspaces.join(', ')}`);
+    // R300. Said before the first run, so the log says the feature is on
+    // — and which variable the token is read from — before a scan is missed.
+    if (project.quality) {
+      log(`quality: ${slug} scans with ${project.quality.command} after TEST, token from $${project.quality.tokenEnv}`);
+    }
   }
   await sayWhichServedProjectsTheTokenCannotReach(config);
 
@@ -7718,6 +9139,7 @@ async function main() {
       const resolved = {
         acceptsRulesFromConsole: file.acceptsRulesFromConsole ?? DEFAULTS.acceptsRulesFromConsole,
         grantable: file.grantable ?? DEFAULTS.grantable,
+        autoWorkspaces: autoWorkspacesOf(file.autoWorkspaces),
         agentCommands: file.agentCommands
           ?? (file.agentCommand ? [file.agentCommand] : null)
           ?? DEFAULTS.agentCommands,
@@ -7726,7 +9148,11 @@ async function main() {
         agentCommands: config.agentCommands,
         grantable: config.grantable,
         acceptsRulesFromConsole: config.acceptsRulesFromConsole,
+        autoWorkspaces: config.autoWorkspaces,
       }, resolved);
+      // A checkout made on demand may have been dropped — the attached
+      // terminal's `/drop` deletes the directory and sends this signal.
+      await syncAutoWorkspaces(config.projects, heldWorkspaces());
       Object.assign(config, resolved);
       // R288: the hello describes the current state, not the booted one — an
       // attach opened after a toggle would otherwise offer to turn on what is
@@ -7963,8 +9389,13 @@ async function main() {
   // to lose three hours of work by leaning on the keyboard.
   if (attaching) {
     const { attach } = await import('./attach.mjs');
-    void attach(process.argv.slice(2), {
+    const argv = process.argv.slice(2);
+    const typed = argv.includes('--url') ? argv[argv.indexOf('--url') + 1] : null;
+    void attach(argv, {
       socketPath: control?.path,
+      // Where the person signs in: `--url`, else what this daemon is called —
+      // `cawdev.mjs`'s `signInUrl` order. `urlFrom` alone never sees the config.
+      url: (typed ?? config.url).replace(/\/+$/, ''),
       // Its own daemon, so quitting means stopping: raised as a signal rather
       // than an exit, so the run goes through the same goodbye and the same
       // termination of children as a Ctrl-C would.
@@ -7997,6 +9428,22 @@ async function main() {
         `/api/runners/${config.runnerId}/queue?wait=${config.pollSeconds}`,
       );
 
+      // Checked again HERE, not only at the top. The poll blocks for up to
+      // pollSeconds, and a Ctrl-C during it flips `stopping` and begins the
+      // goodbye — which is bounded but not instant. A poll that returns inside
+      // that window would otherwise walk on to claim a run and spawn a
+      // detached agent that outlives the exiting daemon, orphaned with a live
+      // claim. The gap after this point is startRun's own: it reads `stopping`
+      // nowhere, and a Ctrl-C between its claim and its spawn is still open.
+      //
+      // Also the loop's exit an analyser can see. The header's condition IS one
+      // at runtime — `stopping` is a closed-over `let` read every iteration —
+      // but its only writer is the signal handler, and i247 (S2189) is what a
+      // loop with no visible way out looks like from outside.
+      if (stopping) {
+        break;
+      }
+
       // ONE gate — R109. There were two; `maxSessions` bounded this machine
       // and is gone, for the reason written where it used to be applied.
       //
@@ -8019,6 +9466,10 @@ async function main() {
       // was when the wait began — and a run that started during the wait was
       // invisible. Two agents went into one checkout that way.
       const held = heldWorkspaces();
+      // One `git status` per checkout per pass, not per offer — i258.
+      // Several offers of one project ask `looksClean` on a shared checkout
+      // only once.
+      const probed = new Map();
 
       let claimable = 0;
       let skipped = 0;
@@ -8077,47 +9528,24 @@ async function main() {
         // the local ref already is. Taken when free, passed over when not: a
         // busy preferred checkout is not worth waiting for, because origin has
         // everything and prepareWorkingCopy brings a stale ref up to it.
+        //
+        // Below pinned and preferred, which checkout a free-for-the-taking
+        // run gets now also weighs whether its tree is clean — R71/i258. The
+        // `await` here can only make `held` more conservative while it waits:
+        // claims are added by this loop alone, sequentially, and a run
+        // finishing only frees a path. The one optimistic case — a heartbeat
+        // adding to `told.heldWorkspaces` mid-loop — is the same window that
+        // already exists between this poll and `startRun`'s own claim.
         let workspace = null;
         if (writes) {
-          const pinned = offered.workspace ?? null;
-          if (pinned) {
-            if (!config.projects[slug].workspaces.includes(pinned)) {
-              // Not one of ours. The platform pins a machine as well as a
-              // path, so this means the config changed under a live branch —
-              // which is a thing to say out loud rather than quietly ignore.
-              noteQueued(
-                offered.run,
-                `its branch is in ${pinned}, which this machine does not serve`,
-              );
-              skipped += 1;
-              continue;
-            }
-            if (held.has(pinned)) {
-              noteQueued(
-                offered.run,
-                `waiting for ${pinned}, which is busy — the branch has work only that checkout holds`,
-              );
-              skipped += 1;
-              continue;
-            }
-            workspace = pinned;
-          } else {
-            const preferred = offered.preferredWorkspace ?? null;
-            if (preferred && config.projects[slug].workspaces.includes(preferred) && !held.has(preferred)) {
-              workspace = preferred;
-            } else {
-              workspace = config.projects[slug].workspaces.find((path) => !held.has(path)) ?? null;
-            }
-            if (!workspace) {
-              const total = config.projects[slug].workspaces.length;
-              noteQueued(
-                offered.run,
-                `no free workspace in ${slug} (${total} here, all busy)`,
-              );
-              skipped += 1;
-              continue;
-            }
+          const picked = await pickWorkspace(slug, config.projects[slug], offered, held, probed,
+            config.autoWorkspaces);
+          if (picked.why) {
+            noteQueued(offered.run, picked.why);
+            skipped += 1;
+            continue;
           }
+          workspace = picked.workspace;
         }
         if (workspace) {
           held.add(workspace);