cawdev-cli 1.0.3-beta → 1.0.4-beta

package/runner/runner.mjs

@@ -33,7 +33,8 @@ 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';
@@ -164,6 +165,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',
@@ -463,6 +471,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
@@ -508,11 +522,51 @@ 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. An operator opts into that; nothing opts in for them.
+ */
+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}".`);
+  }
+  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.
@@ -1305,10 +1359,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 };
 }
@@ -2239,6 +2300,189 @@ 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.
+ */
+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.` });
+  }
+
+  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 };
+
+    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 !== '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.',
+          });
+        }
+        // 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 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,
+    });
+  } catch (failure) {
+    await report({ headSha, error: failure.message.split('\n')[0] });
+  } finally {
+    if (workDir) {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/** `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.
  *
@@ -3091,7 +3335,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, {
@@ -3361,8 +3609,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');
   }
 }
 
@@ -3514,7 +3764,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 +3793,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 +3819,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 +4569,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 +4820,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 +5250,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
@@ -5043,8 +5348,9 @@ 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'
+    + '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.**';
 }
@@ -5412,6 +5718,14 @@ 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;
     // 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 +5966,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 +5985,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 +6021,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 +6150,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 +6269,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.
@@ -5955,7 +6320,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
     const agyCmd = config.agentCommands.find((each) => each.endsWith('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 +6438,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 +6602,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
@@ -6345,6 +6739,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.
@@ -6453,7 +6850,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 +6861,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 +6893,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,
     };
@@ -6578,7 +6977,7 @@ 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));
+            const missing = [...mustUse].filter((entry) => !used.has(entry)).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
@@ -6635,10 +7034,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 +7090,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 +7223,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 +7521,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 +7641,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, {
@@ -7312,10 +7729,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 +7795,9 @@ 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);
     });
   });
 }
@@ -7399,6 +7831,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',
@@ -7617,6 +8062,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);