cawdev-cli 1.0.4-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';
@@ -40,6 +42,11 @@ 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 -----------------------------------------------------------
 
@@ -405,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,
@@ -485,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)) {
@@ -550,13 +590,20 @@ function normaliseProjects(projects) {
  * 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. An operator opts into that; nothing opts in for them.
+ * 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') {
-    throw new Error(`Project "${slug}": quality.whenBranchesRefused must be "skip" or "main", not "${when}".`);
+  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',
@@ -868,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'], {
@@ -897,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,
@@ -1394,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));
@@ -1829,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.
@@ -1887,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.
  *
@@ -2329,6 +2411,14 @@ async function surveyGit(config) {
  * 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;
@@ -2363,6 +2453,14 @@ async function scanQuality(config, run, cwd, branch) {
     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 {
@@ -2379,6 +2477,42 @@ async function scanQuality(config, run, cwd, branch) {
     ];
     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),
@@ -2388,11 +2522,18 @@ async function scanQuality(config, run, cwd, branch) {
         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": "main" in the quality block to analyse it as the main analysis instead.',
+            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.
@@ -2407,61 +2548,10 @@ async function scanQuality(config, run, cwd, branch) {
     }
 
     // What the scanner left behind: where the server queued the analysis.
-    const task = parseProperties(await readFile(join(workDir, 'report-task.txt'), 'utf8'));
-    const serverUrl = (task.serverUrl ?? url).replace(/\/$/, '');
-    const headers = { authorization: `Bearer ${token}` };
-    const ask = async (path) => {
-      const response = await fetch(`${serverUrl}${path}`, { headers });
-      if (!response.ok) {
-        throw new Error(`SonarQube answered ${response.status} to ${path.split('?')[0]}`);
-      }
-      return response.json();
-    };
-
-    // The analysis is queued on the server; wait for it to settle.
-    let settled = null;
-    while (Date.now() < deadline) {
-      const { task: current } = await ask(`/api/ce/task?id=${encodeURIComponent(task.ceTaskId)}`);
-      if (['SUCCESS', 'FAILED', 'CANCELED'].includes(current?.status)) {
-        settled = current;
-        break;
-      }
-      await new Promise((wake) => setTimeout(wake, 3000));
-    }
-    if (!settled) {
-      return report({ headSha, error: `SonarQube had not finished analysing after ${quality.timeoutSeconds}s.` });
-    }
-    if (settled.status !== 'SUCCESS') {
-      return report({ headSha, error: settled.errorMessage ?? `SonarQube ${settled.status.toLowerCase()} the analysis.` });
-    }
-
-    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: task.dashboardUrl ?? null,
-      warning,
-    });
+    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 {
@@ -2471,6 +2561,185 @@ async function scanQuality(config, run, cwd, branch) {
   }
 }
 
+/** 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 = {};
@@ -2689,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}`;
   }
@@ -3371,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
@@ -3436,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 () => {
@@ -3453,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;
@@ -3678,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') {
@@ -3716,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/')) {
@@ -3730,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.' };
 }
@@ -5343,11 +5735,36 @@ 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'
+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'
@@ -5577,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
@@ -5618,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,
     });
   }
@@ -5698,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
@@ -5726,6 +6274,9 @@ async function startRun(config, offered, workspace) {
     // 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;
@@ -6316,8 +6867,16 @@ 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, usage);
@@ -6654,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',
@@ -6692,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.
@@ -6751,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.
@@ -6912,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;
@@ -6977,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((entry) => !used.has(entry)).map(nameOf);
+            // 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
@@ -6988,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
@@ -6997,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
@@ -7022,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.
@@ -7657,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
@@ -7802,6 +8473,290 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
   });
 }
 
+/**
+ * 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);
+    });
+  });
+}
+
 /**
  * Tells the platform what the CLI calls this session — R69.
  *
@@ -7925,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,
   });
 }
 
@@ -7944,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;
@@ -8003,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
@@ -8168,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,
@@ -8176,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
@@ -8413,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.
@@ -8447,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.
       //
@@ -8469,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;
@@ -8527,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);