cawdev-cli 1.0.3-beta → 1.0.4-beta

package/lib/harness-prompt.mjs

@@ -33,7 +33,7 @@ const MAX_CONFIG_BYTES = 32 * 1024;
  * two halves meet in this function and nowhere else.
  */
 export function harnessPrompt({
-  instincts, briefing, plan, lifecycle, repoConfig, experts, skills, cannotDelegate,
+  instincts, briefing, plan, lifecycle, repoConfig, experts, skills, mcpServers, cannotDelegate,
 }) {
   const parts = [];
 
@@ -86,6 +86,17 @@ export function harnessPrompt({
       + 'work its description covers.\n'
       + lines(maySkills));
   }
+
+  // R303. An MCP server the project REQUIRES gets the same heading. Nothing
+  // at all for an as-needed one — a server reaches a session through the CLI's
+  // own tool listing, and this function said nothing about servers before the
+  // entry, so a project that requires none gets byte-for-byte what it got.
+  const mustServers = requiredOf(mcpServers);
+  if (mustServers.length) {
+    reach.push('**MCP servers you MUST use** — this project requires each of these. Call at '
+      + 'least one tool under the prefix, before this stage is finished.\n'
+      + mustServers.map((each) => `- \`${each.prefix}__…\` — ${each.name}`).join('\n'));
+  }
   if (reach.length) {
     parts.push(`## What this session may reach\n\n${reach.join('\n\n')}`);
   }

package/lib/stage-tools.mjs

@@ -70,6 +70,9 @@ export const CAWDEV_READS = new Set([
   'roadmap_where',
   'code_map',
   'file_deps',
+  // R302. What SonarQube made of the project and of a branch: a read of rows
+  // other things wrote, and nothing on its endpoint a token could write.
+  'quality_get',
   'roadmap_statuses',
   'roadmap_list',
   'roadmap_get',
@@ -109,6 +112,30 @@ const REPORT = `${CAWDEV}report`;
  */
 export const CARD_WRITE = `${CAWDEV}roadmap_create`;
 
+/**
+ * Reads that only mean something once the work exists — R302.
+ *
+ * <p>The first list here that narrows by NEED rather than by what a tool can
+ * change, and the reason it is a named list rather than a line in each arm: it
+ * is read in two places — `toolsForStage` for a walk's PLAN and IMPLEMENT, and
+ * `runner.mjs`'s `PROFILE_TOOLS.PLAN` for a plan run spawned as one process —
+ * and a name in one place and a literal in the other is how the two drift.
+ * Keep it to names a stage before the code exists has no use for: a branch's
+ * SonarQube gate is a fact about a tree that PLAN has not written and IMPLEMENT
+ * is still writing. The smallest tool list is the rule, and this is the list.
+ *
+ * <p>Two readers, not three: an Antigravity spawn (`spawnAntigravity`) builds
+ * no tool list at all — it cannot narrow, by its own comment — so a PLAN run
+ * on that agent holds this read with everything else the server exposes. A
+ * pre-existing gap, named here so nobody counts this list as closing it.
+ */
+export const AFTER_THE_WORK_EXISTS = [`${CAWDEV}quality_get`];
+
+/** The profile's list less what `AFTER_THE_WORK_EXISTS` names — the narrowing above, as a step. */
+export function beforeTheWorkExists(tools) {
+  return tools.filter((tool) => !AFTER_THE_WORK_EXISTS.includes(tool));
+}
+
 /** The tool a session delegates with, and what an older CLI called it. */
 const DELEGATES = /^(Agent|Task)\b/;
 
@@ -284,7 +311,9 @@ export function toolsForStage(stage, profileTools, testMode, options = {}) {
       // second place deciding what a profile may do. That subsetting is what
       // makes the card write safe to allow here — the profile has to have
       // handed it over first, and only a cardless plan run's does.
-      return readOnly(writesItsOwnCard);
+      // R302. And less the reads that need the work to exist — the narrowing
+      // by NEED rather than by capability, and the only one; see the list.
+      return beforeTheWorkExists(readOnly(writesItsOwnCard));
     case 'VERIFY':
     case 'MEMORY':
       return readOnly(false);
@@ -299,7 +328,9 @@ export function toolsForStage(stage, profileTools, testMode, options = {}) {
       }
       return allowed;
     case 'IMPLEMENT':
-      return allowed;
+      // R302. The profile's list less the reads that need the work to exist:
+      // the branch this stage is writing has no gate until TEST scans it.
+      return beforeTheWorkExists(allowed);
     default:
       // A stage this version does not know is given the profile's own tools —
       // the same as no lifecycle at all. Refusing everything would turn a

package/lib/tool-line.mjs

@@ -72,21 +72,32 @@ export function describeInput(input) {
 /**
  * Which capability a TOOL line named, if it named one — R161.
  *
- * <p>The reader for the two shapes {@link describeCall} writes: `Skill(<key>)`
- * and `Agent(<key>)`. The daemon asks it "has this stage used the thing the
- * project requires", which is a question about a string, so it belongs beside
- * the code that wrote the string and in `lib/` with it — answering it should
- * not need a daemon, a platform and a spawned agent.
+ * <p>The reader for the three shapes a transcript holds: `Skill(<key>)` and
+ * `Agent(<key>)`, which {@link describeCall} writes, and `mcp__<server>__<tool>`,
+ * which is the CLI's own name for an MCP server's tool and reaches the
+ * transcript through the ordinary `${name} ${input}` path — R303 brought this
+ * reader level with `CapabilityUse.java` and `capability-tag.ts`, which both
+ * read that shape already. The daemon asks it "has this stage used the thing
+ * the project requires", which is a question about a string, so it belongs
+ * beside the code that wrote the string and in `lib/` with it — answering it
+ * should not need a daemon, a platform and a spawned agent.
  *
  * <p>Third reader of the contract this file's header describes. `Task(` is not
  * matched because `describeCall` normalises it away before anything is written:
- * what reaches a transcript is always `Agent(`.
+ * what reaches a transcript is always `Agent(`. cawdev's own server is not a
+ * capability — every session has it and nobody chose it — so `mcp__cawdev__…`
+ * is null here as it is in the platform's reader.
  *
  * @returns `{kind, key}`, or null for anything that is not a capability call.
  */
 export function capabilityIn(line) {
   if (typeof line !== 'string') return null;
   const found = /^(Skill|Agent)\(([^)]+)\)/.exec(line);
-  if (!found) return null;
-  return { kind: found[1] === 'Skill' ? 'SKILL' : 'EXPERT', key: found[2] };
+  if (found) return { kind: found[1] === 'Skill' ? 'SKILL' : 'EXPERT', key: found[2] };
+  const server = /^mcp__([A-Za-z0-9_-]+)__/.exec(line);
+  if (server && server[1] !== OUR_SERVER) return { kind: 'MCP_SERVER', key: server[1] };
+  return null;
 }
+
+/** `CapabilityUse.OURS`: the run's own MCP server, machinery rather than a capability. */
+const OUR_SERVER = 'cawdev';

package/mcp/README.md

@@ -172,6 +172,7 @@ what you are allowed to do.
 | `changelog_get` | One entry. |
 | `changelog_add` | Add an entry; no version means `Unreleased`. |
 | `changelog_update` | Edit one, including moving it to a release when it ships. |
+| `quality_get` | The SonarQube reading — the default branch's gate, a named branch's gate and new problems (inside a run, this run's branch by default), and the open findings with links. Read-only: nothing here refreshes, scans or files (R302). |
 
 ### Inside a run
 

package/mcp/server.mjs

@@ -536,6 +536,52 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'quality_get',
+    description:
+      "The SonarQube reading of this project — the default branch's gate and its counts — and, " +
+      "if you name a branch, that branch's gate and how many NEW bugs, vulnerabilities, hotspots " +
+      "and smells it adds, with the SonarQube link. Inside a run, the branch defaults to this " +
+      "run's. A branch nobody has scanned yet says so. A red gate with new vulnerabilities is a " +
+      'finding to report, not a failure to hide. Read-only: nothing here refreshes, scans or files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...PROJECT_ARGUMENT,
+        branch: {
+          type: 'string',
+          description:
+            "A branch name. Omit inside a run to read this run's branch; omit outside one for " +
+            'the default branch only.',
+        },
+      },
+    },
+    handler: async (config, args) => {
+      const slug = await resolveProject(config, args.project);
+      // R302. The run's own branch when none was named — the TEST stage that
+      // calls this is asking about the branch it just tested, and should not
+      // have to know its name. Its own try: a plain `cawd_` token has no run,
+      // and `requireRun` refuses it with a sentence about orchestration tools
+      // that would be wrong here — outside a run, the default branch alone is
+      // the ordinary answer, not a refusal.
+      const branch = args.branch
+        ?? await requireRun(config)
+          .then(({ runId, project }) => api(config, `/api/projects/${project}/runs/${runId}`))
+          .then((run) => run?.branch ?? null)
+          .catch(() => null);
+      const reading = await api(
+        config,
+        `/api/projects/${slug}/quality/reading${branch ? `?branch=${encodeURIComponent(branch)}` : ''}`,
+      );
+      // A 204 has no body, and `api` hands that back as null.
+      if (!reading) {
+        return `${slug} is not on SonarQube — no server, token or project key set on it. `
+          + 'Work as you would have anyway.';
+      }
+      return formatQualityReading(reading, branch);
+    },
+  },
+
   {
     name: 'roadmap_comment',
     description:
@@ -1907,6 +1953,107 @@ function formatFileDeps(map, path) {
   return lines.join('\n');
 }
 
+/** How many finding lines a reading prints before saying "and N more" — R302. */
+const FINDING_LINES = 50;
+
+/**
+ * The reading as a session should read it — R302: one line for the default
+ * branch, one for the branch asked about, then the open findings.
+ *
+ * <p>The branch line comes SECOND and not first, though it is the one the
+ * caller asked about: the default branch's gate is what a person sees on the
+ * project's door, and "your branch is red" means something different under a
+ * green main than under a red one. The findings are the default branch's,
+ * and the last line says so, because a session that read "2 new
+ * vulnerabilities" and then a list of twelve will otherwise look for the two
+ * among the twelve.
+ */
+function formatQualityReading(reading, branch) {
+  const lines = [];
+  const project = reading.project;
+  if (!project) {
+    lines.push('Default branch: connected to SonarQube, but nothing has read it yet — the timer '
+      + 'has not fired since the connection was set.');
+  } else {
+    // A failed read is the headline, not a clause after the gate: a session
+    // skimming for the verdict stops at the first token, and `gate OK · the
+    // last read failed` reads as OK. The numbers are a dated echo and say so.
+    const parts = project.error
+      ? [`the last read failed: ${project.error}`, `before that: gate ${project.gate ?? 'NONE'}`]
+      : [`gate ${project.gate ?? 'NONE'}`];
+    parts.push(
+      `${count(project.bugs)} bugs`,
+      `${count(project.vulnerabilities)} vulnerabilities`,
+      `${count(project.securityHotspots)} hotspots`,
+      `${count(project.codeSmells)} smells`,
+      `coverage ${percent(project.coverage)}`,
+    );
+    if (project.analysedAt) parts.push(`analysed ${project.analysedAt}`);
+    if (project.dashboardUrl) parts.push(project.dashboardUrl);
+    lines.push(`Default branch: ${parts.join(' · ')}`);
+  }
+
+  const asked = reading.branch;
+  if (asked) {
+    if (!asked.scanned) {
+      lines.push(`Branch ${asked.branch}: no machine has scanned it yet. A coding run's TEST stage `
+        + 'is when a scan happens; until then the default branch above is all there is.');
+    } else if (asked.reading?.error) {
+      lines.push(`Branch ${asked.branch}: the scan could not run — ${asked.reading.error}`);
+    } else {
+      const row = asked.reading;
+      const parts = [
+        `gate ${row.gate ?? 'NONE'}`,
+        `new: ${count(row.newBugs)} bugs`,
+        `${count(row.newVulnerabilities)} vulnerabilities`,
+        `${count(row.newSecurityHotspots)} hotspots`,
+        `${count(row.newCodeSmells)} smells`,
+        `new coverage ${percent(row.newCoverage)}`,
+      ];
+      if (row.analysedAs === 'MAIN') parts.push('analysed as the main branch, not under its own name');
+      if (row.headSha) parts.push(`at ${row.headSha.slice(0, 7)}`);
+      if (row.dashboardUrl) parts.push(row.dashboardUrl);
+      lines.push(`Branch ${asked.branch}: ${parts.join(' · ')}`);
+      if (row.warning) lines.push(`  ${row.warning}`);
+    }
+  } else if (branch === null) {
+    lines.push('No branch was read: outside a run, name one to see its gate and new problems.');
+  }
+
+  const findings = reading.findings ?? [];
+  lines.push('');
+  if (!findings.length) {
+    lines.push('Open findings: none.');
+  } else {
+    lines.push(`Open findings (${findings.length}, worst first):`);
+    for (const finding of findings.slice(0, FINDING_LINES)) {
+      const where = finding.path
+        ? ` ${finding.path}${finding.line != null ? `:${finding.line}` : ''}`
+        : '';
+      const filed = finding.became?.ref ? ` (filed as ${finding.became.ref})` : '';
+      lines.push(`  ${finding.type} ${finding.severity} ${finding.rule}${where} — ${finding.message}`
+        + ` — ${finding.url}${filed}`);
+    }
+    if (findings.length > FINDING_LINES) {
+      lines.push(`  … and ${findings.length - FINDING_LINES} more in SonarQube.`);
+    }
+  }
+  lines.push('');
+  lines.push("These findings are the default branch's; SonarQube's per-branch issue list is not "
+    + "read here, so a branch's new problems are counts and a link.");
+  return lines.join('\n');
+}
+
+/** A count as a reading prints it: the number, or a dash for one SonarQube did not report. */
+function count(value) {
+  return value == null ? '–' : String(value);
+}
+
+/** A percentage as a reading prints it: `71.2%`, or a dash for none reported. */
+function percent(value) {
+  return value == null ? '–' : `${value}%`;
+}
+
 /**
  * What to call a card — R127. The server says, in `ref`; this is the fallback
  * for anything that predates it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.3-beta",
+  "version": "1.0.4-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {
@@ -16,8 +16,5 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "UNLICENSED",
-  "dependencies": {
-    "cawdev-cli": "^1.0.0-beta"
-  }
+  "license": "UNLICENSED"
 }

package/runner/README.md

@@ -662,9 +662,93 @@ files at all. R47 removes the need for this by giving each run a workspace.
 8. **Reports the lifecycle back** and, if the session dies without saying
    anything, ends the run rather than leaving it `RUNNING` forever.
 
+   **What each stage used, and what the run used** (R76, R305). Every `result`
+   event the CLI prints carries the process's cumulative token counts, and the
+   daemon files two absolute readings off each: the *stage's* (`POST
+   …/stages/{stage}/usage` — the stage's own processes, across its attempts,
+   so a stage re-run after a refused gate keeps adding to the first attempt's
+   total) and the *run's* (`POST …/usage`). Each stage is its own process
+   counting from zero, so the daemon keeps the run's running total itself and
+   adds each child's figure to it: **the run's total is the sum of its stages'
+   processes**, and a resumed run starts from whatever the claim already
+   carried. The platform keeps the larger reading on both, so a lost report is
+   healed by the next one. Tokens, never money, and cache reads are not
+   counted — `tools/lib/usage.mjs` says why. A daemon older than R305 reports
+   the run and never a stage, and every stage after the first on a staged run
+   was ignored as a reading that went backwards; restart the daemon to get
+   the per-stage figures and the summed total.
+
 Cancelling a run reaches the daemon on its next poll and takes down the child's
 whole process group — an agent that started a build should not leave it running.
 
+### Scanning every branch (R300)
+
+A project with a `quality` block has its branch scanned with SonarQube
+**after a coding run's TEST stage settles and before the next stage begins**,
+on the tree the tests just ran against:
+
+```json
+"cawdev": {
+  "workspaces": ["/Users/you/code/cawdev"],
+  "quality": { "command": "sonar-scanner", "tokenEnv": "SONAR_TOKEN" }
+}
+```
+
+Both keys have those defaults, so `"quality": {}` is enough. `cawdev config
+quality on <slug>` writes the block (and `off` removes it), as does the
+`c` screen inside the attached terminal. The block is read once at boot
+like the rest of `projects`, so **restart the daemon** after adding or
+changing it — the daemon says so itself when it is signalled.
+
+**It is the daemon that scans, not the session.** The scanner is a subprocess
+this process starts and nothing the spawned agent can call — a session that
+reported its own gate could lie about it. It runs in the run's checkout with
+the project's key and the branch's name from the claim
+(`-Dsonar.projectKey=`, `-Dsonar.branch.name=`), the repository's own
+`sonar-project.properties` for everything else, and a working directory in the
+daemon's temp dir rather than `.scannerwork/` inside the checkout, which the
+next reset would otherwise clean and the working-copy watcher report. Then it
+waits for the server to finish the analysis, reads the branch's quality gate
+and its new-code measures, and tells the platform:
+`POST /api/runners/{id}/quality/{slug}`, on the machine's `runner:operate`
+token, the same door as the git survey. The run page and the development
+board show the result — *Quality gate: failed · 3 new problems · Open in
+SonarQube* — found by the branch's name.
+
+**The token stays on this machine.** `tokenEnv` names the environment variable
+the daemon reads the scanner token from — export it where the daemon runs;
+it is never written to the config file, never sent to the platform, and goes
+to the scanner in its environment, never on its command line. It is **not**
+the token the project's owner entered under the project's Settings →
+SonarQube: that one is the platform's reader credential and never leaves the
+platform. Two credentials, two custodians. The scanner has to read
+`SONAR_TOKEN` from its environment, which `sonar-scanner` does from 4.7 on;
+older scanners want `-Dsonar.login`, which would put the token in `ps`, so
+this daemon does not offer it. The block may also name `url`, for a machine
+that reaches the server by another name than the platform does (a LAN
+hostname), and `timeoutSeconds` (600) bounding the scan and the wait.
+
+**Community Edition.** A server that refuses `sonar.branch.name` — every
+Community Edition — is *skipped by default*: the reading carries an error
+saying so, and nothing is analysed. `"whenBranchesRefused": "main"` in the
+block opts into the fallback, which analyses the branch as the project's
+**main** analysis and marks the reading `MAIN` with a warning. Understand what
+that trades: the project's own dashboard, and the platform's project reading
+with it, then describe whichever branch scanned last. Nothing opts in for you.
+
+**A failed scan never fails a run.** A machine with no block scans nothing and
+says nothing. A machine with a block and a project with no key logs `not
+scanned` and reports nothing. Everything after that reports *something*: no
+scanner on this machine, no token exported, no server, a server that refused —
+each is an `error` reading with the sentence on it, so the run page says the
+scan could not run rather than showing a branch nobody looked at, and the
+run goes on to its next stage exactly as it would have. Only a staged run
+with a TEST stage is scanned: a lifecycle without one, an unstaged run, a run
+whose gate refused TEST twice or one that reported done inside TEST has no
+settled TEST stage to scan after. The log line is
+`quality: <branch> gate OK · 0 new problems`, or `quality: could not scan
+<branch>: <why>`.
+
 ## What a project's rules can ask of it (R40)
 
 A project may decide that a finished run **pushes its branch**, **opens a pull
@@ -674,11 +758,18 @@ with the claim, and the daemon logs them when it takes a run, so you find out
 what is going to happen before it happens rather than afterwards. `auto_merge`
 gets a shouted line of its own.
 
-The daemon does not decide any of this. The platform queues `PUSH`, `OPEN_PR`
-and `MERGE` on the same `run_action` queue the console's *Commit* button uses,
+The daemon does not decide any of this. The platform queues `PUSH` and
+`OPEN_PR` on the same `run_action` queue the console's *Commit* button uses,
 and the daemon performs them in `settleActions` — one pass right after the
 session ends, because the working-copy watcher stopped with the child and the
-rules queue their work at exactly that moment.
+rules queue their work at exactly that moment. `auto_merge` is asked for
+later, when the branch reaches Done on the development board (R306): the
+platform queues a `MERGE` **workspace request** attributed to the rule —
+`requestedByRule: "auto_merge"` on the claim — to the machine that wrote the
+branch, and the daemon logs `MERGING <branch> — by auto_merge, nobody is
+reading this diff` when it takes it. It is the same `gh pr merge` the board's
+button runs. (A platform older than R306 still queues a `MERGE` run action,
+and the daemon still performs it.)
 
 **cawdev still holds no git-host credential.** This machine does, which is why
 the work happens here and why R19 and R25's division is unchanged. All that is
@@ -693,6 +784,11 @@ What it actually runs:
   conflict — the rule wanted one to exist and one does.
 - `gh pr merge <url> --squash --delete-branch`, and only if a real pull request
   is found. A `/compare/` URL is not one, and it refuses rather than guessing.
+  Before merging it asks `gh pr view --json mergeable,mergeStateStatus` and,
+  while the host answers `UNKNOWN` — mergeability is computed lazily, and a
+  merge seconds after `gh pr create` used to fail for no reason a person could
+  act on — waits up to six times five seconds (R306). Any other answer merges
+  at once; the merge is what says whether it could.
 
 Every one of them reports a result or a reason, and a machine with no `gh`, no
 remote or no credentials simply says so. **A rule is a request, not a grant** —

package/runner/attach.mjs

@@ -51,7 +51,7 @@ import { basename, dirname } from 'node:path';
 import { listSockets, socketPathFor } from './control.mjs';
 import {
   RESTART_FROM_ATTACH, addProject, addWorkspace, agentsOf, pathsOf, readConfigFile, reloadIfRunning,
-  setAcceptsRulesFromConsole, setAgentEnabled, slugsOf,
+  setAcceptsRulesFromConsole, setAgentEnabled, setQuality, slugsOf,
 } from './configure.mjs';
 import {
   TYPE_A_PATH, absolute, completePath, describe, inspectPath, listDirectories,
@@ -705,6 +705,11 @@ const KNOWN_AGENTS = ['claude', 'agy'];
  * "enable" would ask the person to remember what the file says. The hint is
  * where the current value lives; the label is the change.
  */
+/** A project entry's `quality` block, whatever shape the entry is — R300. */
+function qualityOf(entry) {
+  return entry && typeof entry === 'object' && entry.quality ? entry.quality : null;
+}
+
 export function configMenu(file, runner = {}) {
   const slugs = slugsOf(file);
   const agents = agentsOf(file);
@@ -737,6 +742,11 @@ export function configMenu(file, runner = {}) {
       rulesOn
         ? { id: 'rules', label: 'Stop accepting permission rules from the console', hint: 'on now' }
         : { id: 'rules', label: 'Accept permission rules from the console', hint: 'off now' },
+      // R300: one row per served project, saying whether its branches are
+      // scanned here now — the state the row would change, R288's rule.
+      ...slugs.map((slug) => (qualityOf(file.projects[slug])
+        ? { id: `quality:${slug}`, label: `Stop scanning ${slug} with SonarQube`, hint: `${qualityOf(file.projects[slug]).command ?? 'sonar-scanner'} after TEST now` }
+        : { id: `quality:${slug}`, label: `Scan ${slug} with SonarQube after TEST`, hint: 'not scanned here' })),
       { id: 'show', label: "Show this machine's config", hint: runner.configPath ?? '' },
     ],
   });
@@ -2187,6 +2197,13 @@ export class Attached {
       this.runner.agents = agentsOf(next);
       return this.reloadDaemon(file, next);
     }
+    if (chosen.id.startsWith('quality:')) {
+      const slug = chosen.id.slice('quality:'.length);
+      const next = await setQuality({
+        file, configPath, ask, say, ink, slug, enabled: !qualityOf(file.projects?.[slug]),
+      });
+      return this.reloadDaemon(file, next);
+    }
     if (chosen.id === 'rules') {
       const next = await setAcceptsRulesFromConsole({
         file, configPath, ask, say, ink, enabled: file.acceptsRulesFromConsole !== true,

package/runner/cawdev.mjs

@@ -29,7 +29,7 @@ import { attach, urlFrom, valueOf } from './attach.mjs';
 import { asker, askOne, mintForThisMachine, setUpThisMachine } from './bootstrap.mjs';
 import { liveSockets, probeSocket, socketPathFor } from './control.mjs';
 import {
-  addProject, addWorkspace, readConfigFile, reloadIfRunning, setAcceptsRulesFromConsole,
+  addProject, addWorkspace, readConfigFile, reloadIfRunning, setAcceptsRulesFromConsole, setQuality,
   setAgentEnabled,
 } from './configure.mjs';
 import { restartNeededFor } from '../lib/runner-config.mjs';
@@ -64,6 +64,8 @@ const USAGE = `
                                           already serve — R47's concurrency
   cawdev config agent enable|disable <claude|agy>
   cawdev config rules on|off             accept permission rules from the console
+  cawdev config quality on|off <slug>    scan that project's branches with
+                                         SonarQube after a run's TEST stage
   cawdev config show                     this machine's config, token redacted
 
   On a machine with no config, cawdev sets one up: it signs you in through the
@@ -405,7 +407,8 @@ async function runVersion(argv, ink) {
 /**
  * `cawdev config` — R283's granular half of the setup walk, on a machine
  * already configured. A direct subcommand (`add-project`, `add-workspace`,
- * `agent enable|disable <command>`, `rules on|off`, `show`) or, with none, a
+ * `agent enable|disable <command>`, `rules on|off`, `quality on|off <slug>`,
+ * `show`) or, with none, a
  * menu — the same `Select` widget everything that offers a choice uses.
  */
 async function runConfig(args, ink) {
@@ -449,6 +452,8 @@ export async function pickAction(ask, say, pick = askOne) {
       { id: 'agent-disable', label: 'Disable an agent' },
       { id: 'rules-on', label: 'Accept permission rules from the console' },
       { id: 'rules-off', label: 'Stop accepting rules from the console' },
+      { id: 'quality-on', label: 'Scan a project\'s branches with SonarQube after TEST' },
+      { id: 'quality-off', label: 'Stop scanning a project\'s branches' },
       { id: 'show', label: 'Show this machine\'s config' },
     ],
   }));
@@ -459,6 +464,10 @@ export async function pickAction(ask, say, pick = askOne) {
   }
   if (id === 'rules-on') return ['rules', 'on'];
   if (id === 'rules-off') return ['rules', 'off'];
+  if (id === 'quality-on' || id === 'quality-off') {
+    const slug = (await ask.line('  Which project (slug)? ')).trim();
+    return ['quality', id === 'quality-on' ? 'on' : 'off', slug];
+  }
   return [id];
 }
 
@@ -498,6 +507,16 @@ export async function runAction([verb, ...rest], { configPath, file, url, sessio
     await reload(await setAcceptsRulesFromConsole({ file, configPath, ask, say, ink, enabled: sub === 'on' }));
     return;
   }
+  if (verb === 'quality') {
+    // R300. The block is captured per project at boot, so the daemon's own
+    // verdict here is always "restart" — and it is the daemon that says so.
+    const [sub, slug] = rest;
+    if (!['on', 'off'].includes(sub) || !slug) {
+      throw new Error('Name a project: cawdev config quality on|off <slug>');
+    }
+    await reload(await setQuality({ file, configPath, ask, say, ink, slug, enabled: sub === 'on' }));
+    return;
+  }
   throw new Error(`Not a cawdev config command: ${verb}. See cawdev --help.`);
 }
 

package/runner/configure.mjs

@@ -361,6 +361,64 @@ export async function setAcceptsRulesFromConsole({
   return next;
 }
 
+/**
+ * Turn a project's SonarQube scan on or off — R300.
+ *
+ * On writes a `quality` block into the project's entry (`{ command, tokenEnv }`,
+ * the two things the daemon needs; `runner.mjs`'s `qualityBlockOf` fills in
+ * the rest), asking for each with its default offered — Enter keeps it. Off
+ * deletes the block and leaves every other key of the entry as it was. A bare
+ * path entry is promoted to `{workspaces}` on the way, R47's third form, the
+ * way `addWorkspace` promotes one.
+ *
+ * Nothing here checks the scanner is installed: unlike an agent, the scanner
+ * can be missing on a machine that will be told so per run — the daemon
+ * reports "not installed" as an error reading, which is the page saying it
+ * — and a check here would refuse a config somebody is about to complete.
+ * The token is NOT asked for: it is an environment variable this machine
+ * exports, never a value in a file people commit.
+ */
+export async function setQuality({
+  file, configPath, slug, enabled,
+  command, tokenEnv,
+  ask, say, ink = painter(3),
+  write = writeRunnerConfig,
+} = {}) {
+  const projects = file.projects ?? {};
+  if (!slug || !(slug in projects)) {
+    throw new Error(`This machine does not serve ${slug || 'that project'}. `
+      + `It serves: ${Object.keys(projects).join(', ') || 'nothing yet'}.`);
+  }
+  const entry = typeof projects[slug] === 'string'
+    ? { workspaces: [projects[slug]] }
+    : { ...projects[slug] };
+
+  let next;
+  if (enabled) {
+    const chosenCommand = command
+      ?? (String(await ask.line('  Scanner command [sonar-scanner]: ')).trim() || 'sonar-scanner');
+    const chosenTokenEnv = tokenEnv
+      ?? (String(await ask.line('  Environment variable holding the scanner token [SONAR_TOKEN]: ')).trim()
+        || 'SONAR_TOKEN');
+    entry.quality = { ...(entry.quality ?? {}), command: chosenCommand, tokenEnv: chosenTokenEnv };
+    next = { ...file, projects: { ...projects, [slug]: entry } };
+    await write(configPath, next);
+    say(`  ${ink.success('✓')} ${ink.muted(`${slug} scans its branches with`)} ${ink.text(chosenCommand)}`
+      + ` ${ink.muted('after TEST, token from')} ${ink.text('$' + chosenTokenEnv)}`);
+    say(`  ${ink.muted(`Export ${chosenTokenEnv} where the daemon runs. It is never written to this file.`)}`);
+  } else {
+    if (!entry.quality) {
+      say(`  ${ink.muted(`${slug} was already not scanned here.`)}`);
+      return file;
+    }
+    delete entry.quality;
+    next = { ...file, projects: { ...projects, [slug]: entry } };
+    await write(configPath, next);
+    say(`  ${ink.success('✓')} ${ink.muted(`${slug} is no longer scanned on this machine.`)}`);
+  }
+  return next;
+}
+
 /**
  * The hello of a daemon running on this exact config, or null.
  *