cawdev-cli 1.0.2-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/runner-config.mjs

@@ -0,0 +1,81 @@
+// R294 — which parts of a runner's config a running daemon can take without a
+// restart, and which it cannot.
+//
+// The daemon reads its config ONCE at boot and threads most of it by value —
+// `projects` and their checkouts, `url`, `name`, the token, the MCP servers.
+// Three keys are the exception: they are read fresh off the live `config`
+// object on every use (a spawn, or the next heartbeat), so a SIGHUP that
+// re-reads the file is enough to apply them. That list was spelled in three
+// places — configure.mjs's header, attach.mjs's `reloadDaemon`, runner.mjs's
+// handler — and nothing pinned that the three agreed. It is spelled HERE and
+// nowhere else now, and the one question everything asks of it is
+// `restartNeededFor`: given what the daemon booted with and what the file says
+// now, which keys would only a restart change?
+//
+// Pure, because the daemon answers it and both config doors repeat the answer,
+// and a function all three share is the only way they cannot disagree.
+//
+// Zero dependencies, like everything in tools/.
+
+/**
+ * The keys runner.mjs's SIGHUP handler applies without a restart.
+ *
+ * Only settings that are genuinely safe to hot-swap belong here: each one
+ * must be read off `config` at the moment it is used, never captured at boot.
+ * Adding a key that IS captured would make the daemon claim it applied
+ * something it did not, which is worse than saying restart.
+ */
+export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole']);
+
+/**
+ * The legacy spelling of one key, read as the current one — so a config that
+ * says `agentCommand: "claude"` is not reported as differing from one that
+ * says `agentCommands: ["claude"]`. runner.mjs's `readConfig` makes the same
+ * move; this is it applied to a raw file rather than a booted config.
+ */
+export function normaliseConfigFile(file) {
+  const { agentCommand, ...rest } = file ?? {};
+  if (agentCommand !== undefined && rest.agentCommands === undefined) {
+    rest.agentCommands = [agentCommand];
+  }
+  return rest;
+}
+
+/**
+ * The keys a restart would change: everything that differs between what the
+ * daemon booted with and what the file says now, minus {@link HOT_SWAPPABLE}.
+ *
+ * Compared against the BOOTED file and not the last one read, so an edit
+ * somebody reverts by hand clears the notice by itself. Values are compared
+ * with a key-sorted stringify, because `{workspaces: [...], name}` and
+ * `{name, workspaces: [...]}` are one config. Names only, never values: the
+ * answer is shown in a footer and logged, and the token is one of the keys.
+ *
+ * @returns {string[]} sorted, empty when nothing needs a restart
+ */
+export function restartNeededFor(booted, file) {
+  const before = normaliseConfigFile(booted);
+  const after = normaliseConfigFile(file);
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  return [...keys]
+    .filter((key) => !HOT_SWAPPABLE.includes(key))
+    .filter((key) => canonical(before[key]) !== canonical(after[key]))
+    .sort();
+}
+
+/** Applied, or would be on a SIGHUP: the hot-swappable keys that differ. */
+export function reloadableFor(booted, file) {
+  const before = normaliseConfigFile(booted);
+  const after = normaliseConfigFile(file);
+  return HOT_SWAPPABLE.filter((key) => canonical(before[key]) !== canonical(after[key]));
+}
+
+/** JSON with object keys in one order, so two spellings of one value agree. */
+function canonical(value) {
+  if (value === undefined) return 'undefined';
+  return JSON.stringify(value, (_, inner) => (
+    inner && typeof inner === 'object' && !Array.isArray(inner)
+      ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+      : inner
+  ));
+}

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.2-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

@@ -138,15 +138,31 @@ travels beside the secret since this card, and a machine set up before it
 falls back to a lookup by label the first time this runs, after which it
 remembers.
 
-Adding a project or a workspace needs a restart to take effect, same as any
-other change to `"projects"` — a live daemon says so. Enabling or disabling an
-agent and turning `rules` on or off do **not**: `cawdev config` — and the `c`
-screen, through the pid the hello names — sends the running daemon a `SIGHUP`,
-which re-reads just those three settings from the file and updates what the
-hello advertises, so the next `c` shows the new state. That is a unix convention asked of a process this operator already
-owns, not a command sent over the control socket in `attach.mjs` — that socket
-is deliberately read-only (see its own header), and a config change is not an
-exception carved into it.
+**What takes effect when** (R294). Three settings a running daemon takes
+without a restart — `agentCommands`, `grantable`, `acceptsRulesFromConsole`,
+the `HOT_SWAPPABLE` list in `tools/lib/runner-config.mjs`, spelled once —
+because the daemon reads them fresh on every use. Everything else in the file
+(`projects` and their workspaces, `url`, `name`, the token, `browser`, the
+tuning) is read once at boot. Every change made by either door ends the same
+way: the running daemon is sent a `SIGHUP` (through the pid the hello names —
+a unix convention asked of a process this operator already owns, not a command
+over the control socket in `attach.mjs`, which is deliberately read-only), it
+re-reads the file, applies what it can, and **says what it could not**: the
+hello carries `restartNeeded`, the keys the file has moved on from since boot
+that only a restart applies, and `configReadAt`. The door waits for that
+re-read and repeats the daemon's own verdict — "applied, no restart needed",
+or "needs a restart to pick up `projects` — q, then cawdev". A daemon too old
+to answer gets the door's own reading of the same function.
+
+While `restartNeeded` is non-empty the attached terminal pins a row in its
+footer — `! config changed: projects — restart to apply (q, then cawdev)` — and
+the `c` screen names what is in the file and not yet served ("serves cawdev ·
+dycrypt after a restart", "cawdev: 1, 2 after a restart"). It is compared
+against the file the daemon **booted** with, not the last one it read, so an
+edit reverted by hand clears it. And it is off the file's own mtime, checked
+on every heartbeat: a change made in an editor with nobody signalling anything
+reaches the footer within thirty seconds. A notice, never a restart — the
+daemon says, a person decides.
 
 ### What it shows you
 
@@ -646,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
@@ -658,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
@@ -677,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** —