cawdev-cli 1.1.0 → 1.2.0

package/mcp/README.md

@@ -67,7 +67,8 @@ The sequence is fixed, and the second step is the one people skip:
    "what is being worked on right now" without asking anyone.
 3. Build to the card's "Done when" list.
 4. Finish with a PR. Never push to `main`. As your session ends the platform
-   moves the *branch* on the development board, not the card: to `REVIEW` where
+   moves the *branch* on the development board, not the card: to `TEST` (the board
+   column, not the TEST stage of a run) where
    the project runs `require_review` and somebody is going to read it, and to
    `DONE` where it does not — a finish nobody was asked about (R132), because
    there is no reviewer coming.
@@ -79,9 +80,7 @@ The sequence is fixed, and the second step is the one people skip:
 `roadmap_statuses` will tell you, and it is worth reading rather than guessing:
 `IN_DEVELOPMENT` needs a branch, `MERGED` needs the merge — a pull request, a merge
 commit, or a sha — `SHIPPED` needs a version that is a real git tag, and
-`DECLINED` needs a reason. `REVIEW` needs nothing, deliberately: the pull
-request it would otherwise carry belongs to the run, and a project that reviews
-without opening pull requests has none to give it.
+`DECLINED` needs a reason.
 
 **A card you file may land in the `BACKLOG`** (R371). Where a new card goes
 when you name no status is the project's rule, per door, and the default for a
@@ -190,12 +189,12 @@ what you are allowed to do.
 | `done_when_tick` | Tick (or untick) one numbered item of the card's Done-when checklist as built, with one line of evidence (R368). `task_current` lists the items. Defaults to the run's own card and refuses another; the reviewer's column is a person's and no token can set it. |
 | `roadmap_set_status` | Move a card, carrying whatever the status requires. |
 | `roadmap_decline` | Decline with a reason. The only exit. |
-| `backlog_file` | File **feedback**, not a card — something a person should decide about. A WRITER accepts it as a card or an issue, or refuses it (R199). Tagged `agent` as a source, plus any `tags` you pass — `customer` when you relay what a user said (R372). |
+| `backlog_file` | File **feedback**, not a card — something a person should decide about. A WRITER accepts it as a card or an issue, or refuses it (R199). Tagged `agent` as a source, plus any `tags` you pass — `customer` when you relay what a user said (R372). Inside a run, what you find that is **not this card's** goes here, one item per suggestion: the platform stamps the item with the run, so the feedback page links the run and its card, and accepting it relates the new card to yours (R572). Every stage holds it, read-only ones included. |
 | `changelog_list` | The changelog, grouped by release, newest first. |
 | `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). |
+| `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 (not those a person dismissed, R467). Read-only: nothing here refreshes, scans or files (R302). |
 
 ### Inside a run
 

package/mcp/server.mjs

@@ -21,7 +21,11 @@ import {
   summaryOf,
   withinCeiling,
 } from '../lib/tool-rules.mjs';
+import {
+  isProtected, notAllowed, protectedChanges, protectedPolicy, protectedRefusal, relativeTo,
+} from '../lib/protected.mjs';
 import { findDestructive, withinScope } from '../lib/secrets.mjs';
+import { byCodeUnit } from '../lib/order.mjs';
 import { COMMITS_ITS_WORK, isUnfinished, leftOver, notDoneYet } from '../lib/finish-check.mjs';
 
 const NAME = 'cawdev';
@@ -929,7 +933,9 @@ const TOOLS = [
       'person should decide about: `kind` is your opinion, ISSUE (broken) or FEATURE (should ' +
       'also do / do better). A WRITER later accepts it as a roadmap card, accepts it as an ' +
       'issue, or refuses it with a reason. Use this when you are not sure it deserves a card; ' +
-      'use roadmap_create or issue_file when you are.',
+      'use roadmap_create or issue_file when you are. Inside a run, this is where something you ' +
+      'found that is NOT this card\'s goes — one item per suggestion: cawdev links it to this run ' +
+      'and its card, so you need not write either into the body.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1444,6 +1450,14 @@ const TOOLS = [
             return notDoneYet(left);
           }
         }
+        // R562. The diff gate: the branch against the commit it was cut from,
+        // so a shell `git checkout main -- pom.xml` is caught as an Edit is.
+        if (run && COMMITS_ITS_WORK.has(run.profile)) {
+          const refusal = await protectedGate(config, project, runId);
+          if (refusal) {
+            return refusal;
+          }
+        }
       }
 
       const message = await api(config, `/api/projects/${project}/runs/${runId}/messages`, {
@@ -1820,7 +1834,49 @@ async function decide(config, args) {
     // R110. The shield FIRST, and the ordering is the point — see shieldSays.
     // A hit does not deny; it skips the rules and goes straight to a person,
     // and it is recorded so somebody can see what was stopped.
-    const stopped = shieldSays(shieldPolicy(), toolName, input);
+    const policy = shieldPolicy();
+
+    // R562. A protected file, BEFORE the shield and the rules: no stored rule
+    // may cover it, and no session grant either. A path already allowed on this
+    // branch goes straight through; otherwise REFUSE denies and ASK raises a
+    // request that says plainly it is about a protected file.
+    const target = input.file_path ?? input.path ?? input.notebook_path;
+    if (target && policy.protected.globs.length && WRITE_TOOLS.has(toolName)
+      && isProtected(String(target), policy.root, policy.protected.globs)) {
+      const relative = relativeTo(String(target), policy.root) ?? String(target);
+      const allowed = await protectedAllowedNow(config, project, runId, policy.protected);
+      if (allowed.has(relative)) {
+        return allow(input, 'a person allowed this protected file');
+      }
+      await api(config, `/api/projects/${project}/runs/${runId}/blocks`, {
+        method: 'POST',
+        body: { kind: 'PROTECTED', detail: `${toolName} ${relative}` },
+      }).catch(() => {
+        // Bookkeeping, as for the shield below.
+      });
+      if (policy.protected.mode !== 'ASK') {
+        return deny(
+          `${relative} is protected in this project: an agent never changes it. Do not work ` +
+            `around it (no shell, no git checkout). Report blocked if the work needs it.`,
+        );
+      }
+      const asked = await api(config, `/api/projects/${project}/runs/${runId}/approvals`, {
+        method: 'POST',
+        body: {
+          toolName,
+          toolInput: JSON.stringify(input),
+          summary: `PROTECTED FILE — ${summaryOf(toolName, input)}`,
+          suggestion: null,
+          exactPattern: null,
+          exactWithinCeiling: false,
+          toolUseId: args.tool_use_id,
+          protectedPaths: [relative],
+        },
+      });
+      return await answerOf(config, project, runId, asked.id, input);
+    }
+
+    const stopped = shieldSays(policy, toolName, input);
     if (stopped) {
       await api(config, `/api/projects/${project}/runs/${runId}/blocks`, {
         method: 'POST',
@@ -1893,26 +1949,7 @@ async function decide(config, args) {
       },
     });
 
-    const decided = await pollForDecision(config, project, runId, asked.id);
-    if (decided?.state === 'ALLOWED') {
-      return allow(input, decided.reason ?? 'allowed by a person');
-    }
-    if (decided?.state === 'DENIED') {
-      return deny(
-        `${decided.reason ?? 'A person refused this.'} Do not try to work around it — report ` +
-          `blocked and say what you needed, or ask for a different approach.`,
-      );
-    }
-    // EXPIRED, or the poll gave up before the platform expired it. Same answer
-    // either way, and the difference is on the run for whoever reads it later.
-    // R339: a person may still allow it late, and if they do the session is
-    // sent a message saying so — so this says to carry on, not to stop.
-    return deny(
-      `Nobody answered this permission request in time. Do not retry it in a loop. Carry on ` +
-        `with whatever does not need it; if a person allows it later you will be sent a ` +
-        `message saying so, and may run it then. If nothing else can be done without it, ` +
-        `report blocked and say exactly what you needed to run and why.`,
-    );
+    return await answerOf(config, project, runId, asked.id, input);
   } catch (failure) {
     return deny(
       `cawdev could not be asked whether this is allowed (${failure.message}). Treating that as ` +
@@ -1921,6 +1958,104 @@ async function decide(config, args) {
   }
 }
 
+/** The tools whose path is a file they change; Read, Grep and Glob carry a path too. */
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/** Waits for the person and turns the decision into the answer the CLI reads. */
+async function answerOf(config, project, runId, approvalId, input) {
+  const decided = await pollForDecision(config, project, runId, approvalId);
+  if (decided?.state === 'ALLOWED') {
+    return allow(input, decided.reason ?? 'allowed by a person');
+  }
+  if (decided?.state === 'DENIED') {
+    return deny(
+      `${decided.reason ?? 'A person refused this.'} Do not try to work around it — report ` +
+        `blocked and say what you needed, or ask for a different approach.`,
+    );
+  }
+  // EXPIRED, or the poll gave up before the platform expired it. Same answer
+  // either way, and the difference is on the run for whoever reads it later.
+  // R339: a person may still allow it late, and if they do the session is
+  // sent a message saying so — so this says to carry on, not to stop.
+  return deny(
+    `Nobody answered this permission request in time. Do not retry it in a loop. Carry on ` +
+      `with whatever does not need it; if a person allows it later you will be sent a ` +
+      `message saying so, and may run it then. If nothing else can be done without it, ` +
+      `report blocked and say exactly what you needed to run and why.`,
+  );
+}
+
+/**
+ * The protected paths a person has allowed on this branch — the claim's list
+ * plus this run's own ALLOWED protected requests, read fresh (R562). Never
+ * throws: not knowing what was allowed means nothing was.
+ */
+async function protectedAllowedNow(config, project, runId, policy) {
+  const allowed = new Set(policy.allowed ?? []);
+  try {
+    const asked = await api(config, `/api/projects/${project}/runs/${runId}/approvals`);
+    for (const approval of asked ?? []) {
+      if (approval?.state === 'ALLOWED' && Array.isArray(approval.protectedPaths)) {
+        approval.protectedPaths.forEach((path) => allowed.add(path));
+      }
+    }
+  } catch {
+    // The claim's list stands.
+  }
+  return allowed;
+}
+
+/**
+ * The protected-file gate on `report done` — R562. Null when the branch is
+ * clean of unallowed protected changes (or nothing can be judged), else the
+ * refusal the session reads. In ASK mode a person is asked once, for all of
+ * them, and ALLOWED lets the run finish.
+ */
+async function protectedGate(config, project, runId) {
+  const policy = shieldPolicy().protected;
+  const base = process.env.CAWDEV_PROTECTED_BASE || null;
+  if (!policy.globs.length || !base) {
+    return null;
+  }
+  const root = process.env.CAWDEV_WORKSPACE ?? process.cwd();
+  const changed = await protectedChanges(root, base, policy.globs);
+  const allowed = await protectedAllowedNow(config, project, runId, policy);
+  const held = notAllowed(changed, [...allowed]);
+  if (!held.length) {
+    return null;
+  }
+  const list = held.join(', ');
+  await api(config, `/api/projects/${project}/runs/${runId}/blocks`, {
+    method: 'POST',
+    body: { kind: 'PROTECTED', detail: `branch changes ${list}` },
+  }).catch(() => {
+    // Bookkeeping.
+  });
+  const refusal = protectedRefusal(held, base);
+  if (policy.mode !== 'ASK') {
+    return refusal;
+  }
+  const asked = await api(config, `/api/projects/${project}/runs/${runId}/approvals`, {
+    method: 'POST',
+    body: {
+      toolName: 'ProtectedChange',
+      toolInput: JSON.stringify({ paths: held }),
+      summary: `Changes protected file(s): ${list}`,
+      suggestion: null,
+      exactPattern: null,
+      exactWithinCeiling: false,
+      protectedPaths: held,
+    },
+  });
+  const decided = await pollForDecision(config, project, runId, asked.id);
+  if (decided?.state === 'ALLOWED') {
+    return null;
+  }
+  return decided?.state === 'DENIED' && decided.reason
+    ? `${refusal} A person refused: ${decided.reason}`
+    : refusal;
+}
+
 function allow(updatedInput, reason) {
   // `updatedInput` echoed back unchanged. The hook exists to say yes or no,
   // not to rewrite what the agent was about to do behind its back.
@@ -2013,10 +2148,18 @@ function shieldPolicy() {
       blockSecrets: parsed.blockSecrets !== false,
       blockDestructive: parsed.blockDestructive !== false,
       pathScope: Array.isArray(parsed.pathScope) ? parsed.pathScope : null,
+      // R562. Unreadable is REFUSE with no globs — never a way of allowing.
+      protected: protectedPolicy(parsed),
       root: process.env.CAWDEV_WORKSPACE ?? process.cwd(),
     };
   } catch {
-    return { blockSecrets: true, blockDestructive: true, pathScope: null, root: process.cwd() };
+    return {
+      blockSecrets: true,
+      blockDestructive: true,
+      pathScope: null,
+      protected: protectedPolicy(null),
+      root: process.cwd(),
+    };
   }
 }
 
@@ -2247,6 +2390,14 @@ function formatFileDeps(map, path) {
 /** How many finding lines a reading prints before saying "and N more" — R302. */
 const FINDING_LINES = 50;
 
+/** One failed gate condition, as SonarQube words it: `new_violations 1287 > 0`. A rating's step is its letter. */
+function describeCondition({ metric, comparator, threshold, actual }) {
+  const letter = (step) => ('12345'.includes(step) && step.length === 1 ? 'ABCDE'['12345'.indexOf(step)] : step);
+  if (metric.endsWith('_rating')) return `${metric} ${letter(actual)} worse than ${letter(threshold)}`;
+  const symbol = { GT: '>', LT: '<', EQ: '=', NE: '!=' }[comparator] ?? comparator;
+  return `${metric} ${actual} ${symbol} ${threshold}`;
+}
+
 /**
  * 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.
@@ -2272,6 +2423,12 @@ function formatQualityReading(reading, branch) {
     const parts = project.error
       ? [`the last read failed: ${project.error}`, `before that: gate ${project.gate ?? 'NONE'}`]
       : [`gate ${project.gate ?? 'NONE'}`];
+    // R587: which version was analysed, right after the verdict it belongs to.
+    if (project.analysedVersion) parts.push(`v${project.analysedVersion.replace(/^v/i, '')}`);
+    // R587: the conditions the gate failed on, the cause a session would otherwise guess at.
+    if (project.gateConditions?.length) {
+      parts.push(`failing: ${project.gateConditions.map(describeCondition).join(', ')}`);
+    }
     parts.push(
       `${count(project.bugs)} bugs`,
       `${count(project.vulnerabilities)} vulnerabilities`,
@@ -2280,6 +2437,7 @@ function formatQualityReading(reading, branch) {
       `coverage ${percent(project.coverage)}`,
     );
     if (project.analysedAt) parts.push(`analysed ${project.analysedAt}`);
+    if (project.newCodeSince) parts.push(`new code since ${project.newCodeSince}`);
     if (project.dashboardUrl) parts.push(project.dashboardUrl);
     lines.push(`Default branch: ${parts.join(' · ')}`);
   }
@@ -2366,7 +2524,7 @@ function originWord(origin) {
   if (!origin || origin.kind === 'NONE') return null;
   switch (origin.kind) {
     case 'SONARQUBE': return 'SonarQube';
-    case 'FEEDBACK': return 'Feedback';
+    case 'FEEDBACK': return origin.label ? `Feedback (from ${origin.label})` : 'Feedback';
     case 'APPLICATION': return origin.label ? `an application (${origin.label})` : 'an application';
     case 'SESSION': return origin.label ? `a session (${origin.label})` : 'a session';
     default: return null;
@@ -2391,7 +2549,7 @@ function formatEntry(entry, { brief, comments, plan }) {
   if (entry.section) lines.push(`  section: ${entry.section}`);
   // R315. Sorted for the same reason the export is: a reader's shape must not
   // depend on the set's own insertion order.
-  if (entry.tags?.length) lines.push(`  tags: ${[...entry.tags].sort().map((t) => `#${t}`).join(' ')}`);
+  if (entry.tags?.length) lines.push(`  tags: ${[...entry.tags].sort(byCodeUnit).map((t) => `#${t}`).join(' ')}`);
   // R331. A username, never the email.
   if (entry.assignee) lines.push(`  assignee: ${entry.assignee.username}`);
   // R335. Not printed at MEDIUM, as the export does not write it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -970,6 +970,15 @@ files at all. R47 removes the need for this by giving each run a workspace.
    — the branch rewrote the same lines — the run fails **naming the stash and
    the command to recover it**, because work parked somewhere nobody was told
    about is work lost.
+
+   **A refused move to RUNNING is never the run's failure** (i267). The move
+   can be refused only when the platform no longer holds this claim: the run
+   was cancelled while the checkout was prepared, or put back in the queue. The
+   daemon then logs `the platform did not let this run start`, posts nothing,
+   and leaves the run exactly as the platform has it; if it is QUEUED, the next
+   poll offers it again and it is claimed properly. Only 400, 404, 409 and 410
+   count as a refusal; any other status (401, 403, 408, 429), a network error or
+   a 5xx still fails the run.
 3. **Spawns the agent** in that directory, in its own process group, with the
    run token in its environment and an `.mcp.json` pointing at cawdev's MCP
    server. **Your own token never reaches the child.**
@@ -1167,6 +1176,63 @@ Before this, R325's run finished with a file modified and nothing pushed, and
 the next run in that checkout refused to start on top of it. A checkout with no
 remote commits what is left and asks nothing of a push.
 
+## Git hosts: GitHub, GitLab and Bitbucket — and what the agent may push (R565)
+
+Branches, pull requests and merges are opened **from cawdev** and performed by
+this daemon, with credentials that live on this machine. The platform never
+holds one. A project says which host it is on (`/projects/*/settings`, "Git
+host"), or the daemon works it out from `origin`.
+
+| Host | How the daemon talks to it |
+|---|---|
+| GitHub | `gh`, signed in (`gh auth login`) |
+| GitLab | `glab`, signed in (`glab auth login --hostname <host>`) |
+| Bitbucket Cloud (bitbucket.org) | its REST API, with a token this machine keeps |
+
+Bitbucket Server / Data Center is not supported.
+
+**Bitbucket's token** goes in the environment, and the config names the
+variable — never the token itself:
+
+```json
+{
+  "bitbucket": { "email": "you@example.com", "tokenEnv": "BITBUCKET_TOKEN" }
+}
+```
+
+With `email`, the token is an Atlassian API token and is sent as Basic
+`email:token`. Without it, it is a workspace or repository access token, sent
+as a Bearer token. `tokenEnv` defaults to `BITBUCKET_TOKEN`. The daemon logs,
+once at boot, where it reads the token from (or that it is missing). That
+variable is **removed from the environment of every agent session** it starts;
+`GH_TOKEN` and `GITLAB_TOKEN` are not, because `git push` may authenticate
+through them.
+
+**After updating, restart the daemon.** A daemon that predates this does not
+advertise `bitbucket` in its `gitHosts`, and cawdev will not address a
+Bitbucket project's pull request or merge to it: the button says "No machine of
+yours runs a cawdev runner that speaks Bitbucket. Restart the daemon to update
+it."
+
+### What the agent may push
+
+A coding session may commit on its card's branch and push **that branch and
+nothing else**. For Claude Code the daemon passes a `PreToolUse` hook
+(`push-guard.mjs`) and disallows `gh` and `glab`: a host CLI, a force, a delete,
+`--mirror`, `--all`, a `+` refspec, or a push to any other branch is refused
+with a reason the session reads. A release session may also push its own tag.
+
+After **any** writing session, for Claude, Codex and Antigravity alike, the
+daemon compares the remote with what it held before and, if the session pushed a
+ref other than its branch, says so on the run: *"This session pushed `<ref>`,
+which is outside its branch …"*. Deletions cannot be attributed to a session and
+are not flagged.
+
+**This is a guard against mistakes, not a security boundary.** An agent with a
+shell and your credentials can get round a pattern match (`git -c alias.x='!…'`,
+a host CLI called through a script). **The real wall is branch protection on the
+host: protect the default branch and require a pull request.** Do that.
+
 ## What a project's rules can ask of it (R40)
 
 A project may decide that a finished run **pushes its branch**, **opens a pull
@@ -1340,6 +1406,19 @@ bound to it state the numbers first. There is nothing to configure here and
 nothing to upgrade: the platform sets the same `paused` flag a person's click
 sets, and this daemon already obeys it on the next beat.
 
+**A queued run says why a paused machine leaves it queued (R571).** The daemon
+logs and shows one of two lines, from `pause-note.mjs` (pure, tested):
+`this machine is paused from the console (resume it on Settings → Machines, or
+press c)` for a person's pause, and `cawdev paused this machine for usage: its
+five-hour window is at 92%, back in 1h 20m — it resumes by itself` for the
+platform's. The attached terminal's `c` menu has a **Pause this machine** /
+**Resume this machine** row, which makes the first line's "press c" true: it
+writes the platform through `POST /api/runners/{id}/pause` (`setPaused` in
+`configure.mjs`), never the config file, and the daemon reads it off its next
+heartbeat. A running daemon needs a **restart** to show these lines and to tell
+attached terminals about a pause; an older one keeps saying *paused from the
+console* and has no pause row in `c`.
+
 ## Trying it without spending Claude usage
 
 `stub-agent.mjs` stands in for `claude`. It is spawned the same way, talks to

package/runner/attach.mjs

@@ -52,7 +52,7 @@ import { basename, dirname } from 'node:path';
 import { listSockets, socketPathFor } from './control.mjs';
 import {
   RESTART_FROM_ATTACH, addProject, addWorkspace, agentsOf, pathsOf, readConfigFile, reloadIfRunning,
-  removeProject, setAcceptsRulesFromConsole, setAgentEnabled, setQuality, slugsOf,
+  removeProject, setAcceptsRulesFromConsole, setAgentEnabled, setMaxPlanningRuns, setPaused, setQuality, slugsOf,
 } from './configure.mjs';
 import {
   TYPE_A_PATH, absolute, completePath, describe, inspectPath, listDirectories,
@@ -779,6 +779,25 @@ export function configMenu(file, runner = {}, gone = new Set()) {
       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' },
+      // R577: a number on the platform, not a switch in the file — the hello
+      // carries what the daemon was last told, so the row reads the live value.
+      // R571: the row that makes a queued line's "or press c" true. R288: the
+      // label is the change, the hint the current value.
+      {
+        id: 'pause',
+        // A usage pause has no toggle: the sweep would pause it again within a minute.
+        label: runner.pausedByUsage
+          ? 'Paused by cawdev for usage'
+          : runner.paused ? 'Resume this machine — claim new runs again' : 'Pause this machine — claim nothing new',
+        hint: runner.pausedByUsage
+          ? 'resumes by itself when the window resets; change the threshold on Settings → Machines'
+          : runner.paused ? 'paused now' : 'claiming now',
+      },
+      {
+        id: 'planning-limit',
+        label: 'Limit planning runs at once',
+        hint: runner.maxPlanningRuns ? `${runner.maxPlanningRuns} at once now` : 'no limit 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])
@@ -2573,6 +2592,32 @@ export class Attached {
       this.planned = this.planned.filter((card) => card.slug !== slug);
       return this.reloadDaemon(file, next);
     }
+    if (chosen.id === 'pause') {
+      if (this.runner.pausedByUsage) {
+        this.say(`  ${ink.muted('cawdev paused this machine for usage; it resumes by itself. Change the threshold on Settings → Machines.')}`);
+        return this.note('');
+      }
+      // Writes the platform, which only a person may do, and not the file.
+      if (!this.requireSignIn('pause or resume this machine')) return undefined;
+      const runner = await setPaused({
+        session: this.session, runnerId: this.runner.id, paused: this.runner.paused !== true, say, ink,
+      });
+      this.runner.paused = runner?.paused === true;
+      this.runner.pausedByUsage = runner?.pausedByUsage === true;
+      return this.note('');
+    }
+    if (chosen.id === 'planning-limit') {
+      // Writes the platform, which only a person may do, and not the file — so
+      // no reload: the daemon reads the number off its next heartbeat.
+      if (!this.requireSignIn('limit planning runs at once')) return undefined;
+      const answer = (await ask.line('  How many at once (0 for no limit)? ')).trim();
+      const limit = answer === '' ? NaN : Number(answer);
+      const runner = await setMaxPlanningRuns({
+        session: this.session, runnerId: this.runner.id, limit, say, ink,
+      });
+      this.runner.maxPlanningRuns = runner?.maxPlanningRuns ?? null;
+      return this.note('');
+    }
     if (chosen.id === 'rules') {
       const next = await setAcceptsRulesFromConsole({
         file, configPath, ask, say, ink, enabled: file.acceptsRulesFromConsole !== true,

package/runner/cawdev.mjs

@@ -30,9 +30,9 @@ import { asker, askOne, mintForThisMachine, setUpThisMachine } from './bootstrap
 import { liveSockets, probeSocket, socketPathFor } from './control.mjs';
 import {
   addProject, addWorkspace, readConfigFile, reloadIfRunning, removeProject, setAcceptsRulesFromConsole,
-  setQuality, setAgentEnabled,
+  setMaxPlanningRuns, setQuality, setAgentEnabled, thisRunnerId,
 } from './configure.mjs';
-import { restartNeededFor } from '../lib/runner-config.mjs';
+import { restartNeededFor, runnerNameOf } from '../lib/runner-config.mjs';
 import { Select } from './select.mjs';
 import { storedSession } from './sign-in.mjs';
 import { loadToken } from './token-store.mjs';
@@ -69,6 +69,7 @@ const USAGE = `
   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 planning-limit <n>       how many planning runs (PLAN, SCOPE, AUDIT, REVIEW) run here at once; 0 is no limit
   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
@@ -473,6 +474,7 @@ export async function pickAction(ask, say, pick = askOne) {
       { 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: 'planning-limit', label: 'Limit planning runs at once' },
       { id: 'show', label: 'Show this machine\'s config' },
     ],
   }));
@@ -484,6 +486,9 @@ export async function pickAction(ask, say, pick = askOne) {
   if (id === 'remove-project') {
     return ['remove-project', (await ask.line('  Which project (slug)? ')).trim()];
   }
+  if (id === 'planning-limit') {
+    return ['planning-limit', (await ask.line('  How many at once (0 for no limit)? ')).trim()];
+  }
   if (id === 'rules-on') return ['rules', 'on'];
   if (id === 'rules-off') return ['rules', 'off'];
   if (id === 'quality-on' || id === 'quality-off') {
@@ -547,6 +552,19 @@ export async function runAction([verb, ...rest], { configPath, file, url, sessio
     await reload(await setQuality({ file, configPath, ask, say, ink, slug, enabled: sub === 'on' }));
     return;
   }
+  if (verb === 'planning-limit') {
+    // R577. Written to the PLATFORM, not the file, so no `reload`: there is no
+    // key for a daemon to re-read, and it learns the number from its heartbeat.
+    const [raw] = rest;
+    const limit = raw === undefined || String(raw).trim() === '' ? NaN : Number(raw);
+    if (!Number.isInteger(limit) || limit < 0 || limit > 50) {
+      throw new Error('Name a number: cawdev config planning-limit <0-50>');
+    }
+    await setMaxPlanningRuns({
+      session, runnerId: await thisRunnerId(session, runnerNameOf(file)), limit, say, ink,
+    });
+    return;
+  }
   throw new Error(`Not a cawdev config command: ${verb}. See cawdev --help.`);
 }
 

package/runner/configure.mjs

@@ -18,6 +18,11 @@
 // the hello — applied, or these keys need a restart — never this file's guess
 // about which keys the daemon can take.
 //
+// R577: `setMaxPlanningRuns` is the one setting here that writes the PLATFORM
+// and not the file — a limit on planning runs is a per-machine value the
+// console also edits, so it lives where both can reach it. It therefore never
+// goes through `reloadIfRunning`: the daemon reads it off its next heartbeat.
+//
 // R288: the same functions have a SECOND door — the attached terminal's `c`
 // key — and that is why every question here comes in through a parameter.
 // `ask.line` and `pick` are the two shapes a question takes (a line, or one
@@ -457,6 +462,63 @@ export async function removeProject({
   return next;
 }
 
+/**
+ * The id the platform knows this machine by — R577.
+ *
+ * Looked up by the name the daemon registers under (`runnerNameOf`), among the
+ * machines that are yours: the config file does not hold the id, and two
+ * people's laptops may both be called `laptop`.
+ */
+export async function thisRunnerId(session, name) {
+  const runners = await session.request('/api/runners');
+  const mine = (Array.isArray(runners) ? runners : [])
+    .filter((each) => each.yours && each.name === name);
+  if (mine.length === 0) {
+    throw new Error(`cawdev has no machine of yours called "${name}" — has its daemon run once?`);
+  }
+  if (mine.length > 1) {
+    throw new Error(`More than one machine of yours is called "${name}" (${mine.map((each) => each.id).join(', ')}) — set it on the Runners page.`);
+  }
+  return mine[0].id;
+}
+
+/**
+ * How many planning runs this machine runs at once — R577. 0 is no limit.
+ *
+ * Posted to the owner-only pause endpoint, whose "absent leaves it alone"
+ * means nothing else about the machine moves. Refused before any request when
+ * the number is not one, so a typo costs no round trip.
+ */
+export async function setMaxPlanningRuns({ session, runnerId, limit, say, ink = painter(3) }) {
+  if (!Number.isInteger(limit) || limit < 0 || limit > 50) {
+    throw new Error('A planning limit is a whole number from 0 (no limit) to 50.');
+  }
+  const runner = await session.request(`/api/runners/${runnerId}/pause`, {
+    method: 'POST',
+    body: { maxPlanningRuns: limit },
+  });
+  say(`  ${ink.success('✓')} ${ink.muted('planning runs at once:')} ${ink.text(limit ? String(limit) : 'no limit')}`
+    + ` ${ink.muted('— the daemon applies it on its next heartbeat')}`);
+  return runner;
+}
+
+/**
+ * Pause this machine or resume it — R73, offered in the attached terminal's `c`
+ * menu by R571 so the queued line's "press c" is true. Writes the platform,
+ * like `setMaxPlanningRuns`, through the call Settings → Machines makes; the
+ * daemon reads it off its next heartbeat and no file is touched.
+ */
+export async function setPaused({ session, runnerId, paused, say, ink = painter(3) }) {
+  const runner = await session.request(`/api/runners/${runnerId}/pause`, {
+    method: 'POST',
+    body: { paused: paused === true },
+  });
+  say(`  ${ink.success('✓')} ${ink.muted(paused ? 'paused:' : 'resumed:')} `
+    + `${ink.text(paused ? 'claiming nothing new' : 'claiming again')}`
+    + ` ${ink.muted('— the daemon applies it on its next heartbeat')}`);
+  return runner;
+}
+
 /** Turn `acceptsRulesFromConsole` on or off — R126. */
 export async function setAcceptsRulesFromConsole({
   file, configPath, enabled,