cawdev-cli 1.0.3-beta → 1.0.5-beta

package/lib/agents.mjs

@@ -0,0 +1,27 @@
+/**
+ * The coding agents a machine can spawn, spelled once.
+ *
+ * <p>Three CLIs, each a command on the PATH: Claude Code, Antigravity and
+ * Codex. The setup walk, `cawdev config agent`, the config screen and the
+ * daemon all ask "which agent is this command" and "what is it called", and
+ * the answer was a `=== 'agy' ? … : 'Claude Code'` in five places — right for
+ * two agents and silently wrong for a third.
+ */
+
+/** Every agent, in the order they are offered. */
+export const KNOWN_AGENTS = ['claude', 'agy', 'codex'];
+
+const LABELS = { claude: 'Claude Code', agy: 'Antigravity CLI', codex: 'Codex CLI' };
+
+/** Which agent a configured command is — by its name, the rule `agentCommands` always used. */
+export function agentOfCommand(command) {
+  const name = String(command ?? '').split('/').pop();
+  if (name.endsWith('agy')) return 'agy';
+  if (name.endsWith('codex')) return 'codex';
+  return 'claude';
+}
+
+/** What a person calls the agent behind a command. */
+export function agentLabel(command) {
+  return LABELS[agentOfCommand(command)];
+}

package/lib/ansi.mjs

@@ -102,6 +102,8 @@ export function painter(depth = colourDepth()) {
     text: ink([0xd4, 0xd0, 0xcc], 37),
 
     bold: wrap('\x1b[1m'),
+    /** Bold AND underlined — a fact the eye should find first (advanced mode's agent · model). */
+    strong: wrap('\x1b[1;4m'),
     dim: wrap('\x1b[2m'),
     reverse: wrap('\x1b[7m'),
     /** Plain, for a value that should not compete with the label beside it. */

package/lib/codex.mjs

@@ -0,0 +1,214 @@
+/**
+ * OpenAI's Codex CLI as a third agent — the arguments a spawn is given and the
+ * events it prints, and nothing that touches a process.
+ *
+ * In lib/ for `code-map.mjs`'s reason: the hard parts are a command line and a
+ * stream, both testable without a daemon, a platform or a model. The spawn
+ * itself is `spawnCodex` in runner.mjs, beside `spawnAntigravity`.
+ *
+ * <p>Every flag and field here was checked against the real CLI (0.155) by
+ * hand rather than read off documentation:
+ *
+ * <ul>
+ * <li>`codex exec --json` prints JSONL: `thread.started` (carries the id
+ *   `resume` takes), `item.started`/`item.completed` for `agent_message`,
+ *   `command_execution`, `mcp_tool_call`, `file_change`…, then
+ *   `turn.completed` with `usage` or `turn.failed` with `error`.
+ * <li>In `exec` the approval policy is NEVER, so an MCP call is refused
+ *   outright ("requires approval, but approval policy is never") unless its
+ *   server says `default_tools_approval_mode = "approve"`. With it, cawdev's
+ *   own server is reached even under `--sandbox read-only`, network included:
+ *   the sandbox is the SHELL's, not the MCP servers'.
+ * <li>`enabled_tools` really narrows a server — a tool left out is not offered
+ *   at all — and `disabled_tools` takes one away.
+ * <li>`env_vars` forwards named variables from Codex's own environment to a
+ *   server, which keeps the run's token off the command line, where `ps`
+ *   would show it to anybody on the machine.
+ * <li>`shell_environment_policy.set` blanks a variable for every command the
+ *   model runs — and `exclude` does NOT (tried: `echo $CAWDEV_TOKEN` still
+ *   printed it). The token reaches cawdev's server through `env_vars`, which
+ *   reads Codex's own environment and not the shell's, so blanking it for the
+ *   shell costs the server nothing.
+ * <li>`resume` takes the exec-level options BEFORE the subcommand:
+ *   `codex exec --json -s read-only resume <id> -`; after it, `-s` is refused.
+ * <li>`--strict-config` refuses a field it does not know, so a key misspelled
+ *   here fails the spawn out loud instead of being ignored.
+ * </ul>
+ */
+
+/** The `mcp__cawdev__` prefix off a Claude Code tool list, keeping cawdev's own names only. */
+export function cawdevToolNames(tools) {
+  const prefix = 'mcp__cawdev__';
+  return [...new Set((Array.isArray(tools) ? tools : [])
+    .filter((tool) => typeof tool === 'string' && tool.startsWith(prefix))
+    .map((tool) => tool.slice(prefix.length)))];
+}
+
+/**
+ * A value as TOML, which is what `-c key=value` parses.
+ *
+ * <p>A JSON string is a TOML basic string for everything JSON escapes; DEL is
+ * the one control character JSON leaves alone and TOML refuses.
+ */
+export function tomlValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(tomlValue).join(', ')}]`;
+  }
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(([key, each]) => `${tomlKey(key)} = ${tomlValue(each)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  return JSON.stringify(String(value ?? '')).replace(/\u007f/g, '\\u007f');
+}
+
+function tomlKey(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlValue(String(key));
+}
+
+/**
+ * The command line for one Codex turn. The prompt goes on stdin (`-`).
+ *
+ * @param options.sandbox `read-only` — the OS refuses every write the shell
+ *   attempts — or `bypass`, which is `--dangerously-bypass-approvals-and-sandbox`
+ *   and is only ever passed where the machine has allowed everything.
+ * @param options.servers `[{ name, command, args, env, envVars, enabledTools,
+ *   disabledTools }]`, each approved, since nobody is there to approve a call.
+ * @param options.hideFromShell variables blanked for the model's own commands.
+ */
+export function codexArgs({
+  model = null, effort = null, sandbox, resumeId = null, servers = [], hideFromShell = [],
+}) {
+  if (sandbox !== 'read-only' && sandbox !== 'bypass') {
+    throw new Error(`codexArgs: sandbox must be read-only or bypass, not ${sandbox}`);
+  }
+  // `--ignore-user-config` is `--setting-sources ''` for this CLI: the
+  // operator's own ~/.codex/config.toml can add MCP servers, hooks and an
+  // approval reviewer, and none of that may widen what a run was given. The
+  // sign-in is untouched — it is read from CODEX_HOME either way.
+  const args = ['exec', '--json', '--strict-config', '--ignore-user-config'];
+  args.push(...(sandbox === 'bypass'
+    ? ['--dangerously-bypass-approvals-and-sandbox']
+    : ['--sandbox', 'read-only']));
+  if (model) {
+    args.push('--model', model);
+  }
+  if (effort) {
+    args.push('-c', `model_reasoning_effort=${tomlValue(effort)}`);
+  }
+  if (hideFromShell.length) {
+    args.push('-c', `shell_environment_policy.set=${tomlValue(
+      Object.fromEntries(hideFromShell.map((name) => [name, ''])))}`);
+  }
+  for (const server of servers) {
+    const key = `mcp_servers.${tomlKey(server.name)}`;
+    args.push('-c', `${key}.command=${tomlValue(server.command)}`);
+    if (server.args?.length) {
+      args.push('-c', `${key}.args=${tomlValue(server.args)}`);
+    }
+    if (server.env && Object.keys(server.env).length) {
+      args.push('-c', `${key}.env=${tomlValue(server.env)}`);
+    }
+    if (server.envVars?.length) {
+      args.push('-c', `${key}.env_vars=${tomlValue(server.envVars)}`);
+    }
+    if (server.enabledTools) {
+      args.push('-c', `${key}.enabled_tools=${tomlValue(server.enabledTools)}`);
+    }
+    if (server.disabledTools?.length) {
+      args.push('-c', `${key}.disabled_tools=${tomlValue(server.disabledTools)}`);
+    }
+    args.push('-c', `${key}.default_tools_approval_mode="approve"`);
+  }
+  if (resumeId) {
+    args.push('resume', resumeId);
+  }
+  args.push('-');
+  return args;
+}
+
+/** A tool result's text, whatever shape the MCP server gave it. */
+function resultText(result) {
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    const text = content.map((each) => each?.text ?? '').filter(Boolean).join('\n');
+    if (text) return text;
+  }
+  return result == null ? '(no output)' : JSON.stringify(result);
+}
+
+/**
+ * One line of `codex exec --json`, as what the transcript and the run need.
+ *
+ * <p>Returns `{ sessionId?, lines: [{ kind, body }], usage?, failed?, error?, ended? }`.
+ * `ended` is true on `turn.completed` — the turn ending, which is the whole of
+ * what a stage is judged by. `failed` is `turn.failed`'s sentence; `error` a
+ * top-level error's, which may be passing. An event this version does not know
+ * yields nothing.
+ */
+export function translateCodexEvent(event) {
+  const out = { lines: [] };
+  const item = event?.item ?? {};
+  switch (event?.type) {
+    case 'thread.started':
+      out.sessionId = event.thread_id ?? null;
+      break;
+    case 'item.started':
+      if (item.type === 'command_execution') {
+        out.lines.push({ kind: 'TOOL', body: `Bash(${item.command ?? ''})` });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL',
+          body: `mcp__${item.server}__${item.tool}(${JSON.stringify(item.arguments ?? {})})`,
+        });
+      }
+      break;
+    case 'item.completed':
+      if (item.type === 'agent_message' && item.text) {
+        out.lines.push({ kind: 'ASSISTANT', body: item.text });
+      } else if (item.type === 'command_execution') {
+        const output = String(item.aggregated_output ?? '').slice(0, 4000);
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: output || `(exit ${item.exit_code ?? '?'})`,
+        });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: item.error
+            ? `failed: ${item.error.message ?? JSON.stringify(item.error)}`
+            : resultText(item.result).slice(0, 4000),
+        });
+      } else if (item.type === 'file_change') {
+        const changes = (item.changes ?? [])
+          .map((each) => `${each.kind ?? 'update'} ${each.path ?? ''}`.trim());
+        out.lines.push({ kind: 'TOOL', body: `Edit(${changes.join(', ') || 'files'})` });
+      } else if (item.type === 'error' && item.message) {
+        out.lines.push({ kind: 'SYSTEM', body: item.message });
+      }
+      break;
+    case 'turn.completed':
+      out.ended = true;
+      out.usage = {
+        input: Number(event.usage?.input_tokens) || 0,
+        output: Number(event.usage?.output_tokens) || 0,
+      };
+      break;
+    case 'turn.failed':
+      out.failed = event.error?.message ?? 'Codex reported the turn failed.';
+      out.lines.push({ kind: 'SYSTEM', body: out.failed });
+      break;
+    case 'error':
+      // NOT `failed`: a top-level error is also how a retried stream says
+      // "Reconnecting… 2/5". Only `turn.failed` ends a turn badly; this is
+      // kept as the last thing it said, for when nothing better arrives.
+      out.error = event.message ?? 'Codex reported an error.';
+      out.lines.push({ kind: 'SYSTEM', body: out.error });
+      break;
+    default:
+      break;
+  }
+  return out;
+}

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 = [];
 
@@ -48,10 +48,13 @@ export function harnessPrompt({
   //
   // R161. A REQUIRED one is named FIRST and in its own block. Two lists rather
   // than one annotated list, because a `(required)` suffix on a line in a list
-  // of twelve is a detail; a heading is an instruction. The AS_NEEDED wording
-  // below is byte-for-byte what it was — when a project requires nothing, and
-  // that is every project until somebody says otherwise, this function returns
-  // exactly what it returned before the entry.
+  // of twelve is a detail; a heading is an instruction. When a project
+  // requires nothing at all — every project until somebody says otherwise —
+  // this function still returns exactly what it returned before the entry:
+  // the AS_NEEDED wording below has since been extended once, by i257, but a
+  // project with no `mustExperts`/`mustSkills`/`mustServers` never reaches
+  // either block, so the claim is about that project, not about the wording
+  // itself staying fixed forever.
   const reach = [];
   const requiredOf = (list) => (list ?? []).filter((each) => each.required);
   const optionalOf = (list) => (list ?? []).filter((each) => !each.required);
@@ -63,12 +66,17 @@ export function harnessPrompt({
   if (mustExperts.length) {
     reach.push('**Experts you MUST use** — this project requires each of these. Delegate '
       + 'with the `Agent` tool, `subagent_type` exactly as written, before this stage is '
-      + `finished.\n${lines(mustExperts)}`);
+      + 'finished. This stage is one process and ends when your turn does: a backgrounded '
+      + '`Agent` call that has not reported back by then is lost, and so is anything gated on '
+      + 'it. Pass `run_in_background: false` and wait for each of these in the same turn — do '
+      + 'not say "I\'ll report back" and stop.\n'
+      + `${lines(mustExperts)}`);
   }
   if (mayExperts.length) {
     reach.push('**Experts** — delegate with the `Agent` tool, `subagent_type` exactly as '
       + 'written. Use one whenever its description fits the step you are on; they were '
-      + 'chosen for this project.\n'
+      + 'chosen for this project. The same rule applies: a call backgrounded past the end of '
+      + 'your turn never comes back.\n'
       + lines(mayExperts));
   } else if (!mustExperts.length && cannotDelegate?.length) {
     reach.push(`**Experts** — ${cannotDelegate.join(' ')}`);
@@ -86,6 +94,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

@@ -25,7 +25,8 @@
  * 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']);
+export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole',
+  'autoWorkspaces']);
 
 /**
  * The legacy spelling of one key, read as the current one — so a config that
@@ -60,7 +61,7 @@ export function restartNeededFor(booted, file) {
   return [...keys]
     .filter((key) => !HOT_SWAPPABLE.includes(key))
     .filter((key) => canonical(before[key]) !== canonical(after[key]))
-    .sort();
+    .sort((a, b) => a.localeCompare(b));
 }
 
 /** Applied, or would be on a SIGHUP: the hot-swappable keys that differ. */

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,110 @@ 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.analysedAs === 'PROJECT') {
+        parts.push('analysed as its own SonarQube project; new = on lines this branch changed; no gate');
+      }
+      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.5-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"
 }