cawdev-cli 1.0.11-beta → 1.1.1

package/runner/README.md

@@ -158,8 +158,9 @@ served like any added project, and the rest of the console's setup walk —
 rules, members, the CTO Interview — is linked at
 `<url>/projects/<slug>/setup`.
 
-**What takes effect when** (R294). Three settings a running daemon takes
-without a restart — `agentCommands`, `grantable`, `acceptsRulesFromConsole`,
+**What takes effect when** (R294). Four settings a running daemon takes
+without a restart — `agentCommands`, `grantable`, `acceptsRulesFromConsole`
+and `autoWorkspaces`,
 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
@@ -197,7 +198,7 @@ and its copy all work exactly as they always have, and scrolling up reaches the
 start of the session. The only thing pinned is the footer at the bottom, and it
 never scrolls away: which cawdev, who you are signed in as, this machine's
 runner, the per-project session counts against their checkouts and the machine's
-total against `maxSessions` — plus the run you are watching and the keys that
+total — plus the run you are watching and the keys that
 work right now. Anything *stopping* a session sits above all of that, because it
 is the only thing in there waiting on a person.
 
@@ -283,7 +284,7 @@ the shape of the decision, and the whole value of asking a person is that they
 can say the thing that was not on the list — so getting there costs one key, and
 `esc` from it comes back to the list rather than abandoning the answer. A chosen
 option and a typed sentence resolve the same question the same way, through the
-same endpoint the inbox and the run page post to: one record, the same
+same endpoint the Waiting on you page and the run page post to: one record, the same
 `answeredBy`, and the badge clears at once.
 
 A permission request is the same widget — R60's lengths of yes as rows, with the
@@ -694,7 +695,7 @@ it ends.
 A bare path means one workspace, which is what every config meant before this
 existed — nothing changes for a machine that serves one checkout per project.
 
-How many coding runs go at once is `min(workspaces, maxSessions)`. A run that
+How many coding runs go at once is the number of workspaces. A run that
 waits now says **"no free workspace in cawdev (2 here, all busy)"** instead of
 "that project already has a run here", which was a proxy for it.
 
@@ -717,18 +718,16 @@ says about knowing it.
 
 **This number caps coding and nothing else** (R70). `ASK`, `ROADMAP`, `AUDIT`
 and `SCOPE` runs take no workspace, so a project whose checkouts are all busy
-still starts a question, an entry-writing session, an audit and a scoping
-session at once. `INTERVIEW`, `MERGE`
+still starts a question, a card-writing run, an audit and a scoping
+run at once. `INTERVIEW`, `MERGE`
 and `RELEASE` do take one — each commits something — and count against this
 number; what each may *write* in it is far narrower than a coding run's and is
 decided by the profile, not by the prompt: an interview writes `docs/brief/`,
 a merge writes the files git put conflict markers in, and a release (R187)
 writes exactly the version files the platform names on the claim, with `git`,
 `gh pr create`, `gh pr view` and `node` for the exports — no build tools, no
-permission prompt, no `gh pr merge`. What holds the rest back
-is `maxSessions`, which counts every profile — **"at 4 sessions on this machine
-(every profile counts)"** is the other thing a waiting run can say, and the log
-always says which of the two it was.
+permission prompt, no `gh pr merge`. What holds a coding run back
+is a free workspace, and the log says so (R109 removed `maxSessions`).
 
 **One thing this gate cannot express, and does not try to.** It serialises on a
 checkout, so two runs on *the same branch* in two checkouts are, to this daemon,
@@ -797,8 +796,8 @@ whether the browser is allowed. Those five answer nearly every "why did that
 not happen", and they used to be spread across a config file and a shrug.
 
 Attaching adds a second bar row: the URL, each project as **coding sessions over
-checkouts** (`cawdev 1/2`), and the machine's total against `maxSessions`.
-Both gates, on screen, counting what each actually bounds — a question is in the
+checkouts** (`cawdev 1/2`), and the machine's total.
+The gate, on screen, counting what it actually bounds — a question is in the
 total on the right and not in any project's figure, because it took no checkout.
 A run that is waiting is explained by the bar
 above it rather than by reading the source. A narrow terminal drops projects
@@ -849,11 +848,11 @@ than twenty-six. A machine that wants it unattended puts that string in its own
 ### What a person can ask of a checkout
 
 R57. The daemon polls `workspace-requests/claim` every few seconds and does one
-of **ten** things to a checkout it serves. It said six for two entries, and
+of **eleven** things to a checkout it serves. It said six for two entries, and
 `HANDOFF` had been missing from the list since R148 — a table that quietly does
 not describe one of the things a person can ask for is worse than no table. So
 count the rows below against that number before you trust either. `CUT_BRANCH`
-is the ninth, R260's; `OPEN_PR` the tenth, R261's.
+is the ninth, R260's; `OPEN_PR` the tenth, R261's, `CREATE_BRANCH` the eleventh, R379's.
 
 | | |
 |---|---|
@@ -867,6 +866,7 @@ is the ninth, R260's; `OPEN_PR` the tenth, R261's.
 | `TAG` | R156's release: `git ls-remote --tags origin refs/tags/<version>` for the version in `message`. **The remote, not this clone** — a local tag nobody pushed is exactly the state a release is trying to rule out, and `git tag --list` cannot tell the two apart. A read; it fetches nothing and moves no ref. The sha is reported on the result's first line, the way `MERGE` reports its URL, because the platform will not confirm a release on `ok: true` alone. **A tag that is not there yet is `ok: false` with a sentence, and that is a normal answer** — the release procedure pushes the tag last, so the first check correctly finds nothing. Addressed to a **release** rather than to a directory alone, which is why it is asked for from the roadmap board and refused on this channel. |
 | `CUT_BRANCH` | R260's sprint branch: `git push origin origin/<default>:refs/heads/<name>` for the branch in `message`, after a fetch — so the sprint's cards are cut from what everyone else has, not from whatever this checkout was left on. The second kind after `MERGE` whose effect is **not** in the checkout: the push names two refs and this clone's HEAD is not one of them, so any live checkout of the project will do and nothing local moves. **A branch already on origin is `ok: true`** ("already on origin at <sha>") — the sprint wanted one to exist, and one does. The sha is reported on the result's first line, the way `TAG` reports its. Addressed to a **sprint** and asked for from the sprint page by an OWNER, for `MERGE`'s reason — it reaches the remote — and refused on this channel. A `MERGE` of a card's pull request into a sprint branch still runs `--squash --delete-branch`: the card's branch goes, the sprint's stays. Landing the sprint branch itself is `OPEN_PR` then `MERGE` below. |
 | `OPEN_PR` | R261's sprint merge, first half: `gh pr create --head <branch> --base <base> --title <title>` for the branch in `message` — the sprint's — to `baseBranch ?? defaultBranch`, titled as the claim's `title` (*S1 Notifications*). **An existing pull request is `ok: true` with its URL** — the same `gh pr view` lookup the `auto_pr` rule makes, and the reason the platform can ask this every time: it holds no git-host credential and cannot know whether one exists. The URL is reported on the result's first line, and the platform queues the `MERGE` to this same checkout when it reads one. Nothing is pushed: the branch is on origin already, cut there by `CUT_BRANCH` and merged into by every card. Addressed to a **work item** — the sprint's — and asked for by Merge on the development board or *Merge sprint* on the sprint page, by an OWNER; refused on this channel for `MERGE`'s reason. |
+| `CREATE_BRANCH` | R379's New branch from the console: pushes `origin/<fromBranch>` to `refs/heads/<name>` for the name in `message`. Unlike `CUT_BRANCH` a name already on origin is a **refusal**, because the person asked for a new branch and the existing one may be somebody else's work. Touches no working tree; a daemon that knows the kind says `createBranch: true` in its hello. |
 
 **A `MERGE` that fails also says which KIND of failure it was** — R155, in one
 of five words beside `gh`'s own unchanged text:
@@ -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
@@ -1257,12 +1323,9 @@ rest queue.
 
 **Questions are not serialised.** An `ASK` run prepares nothing and writes
 nothing, so it runs alongside whatever else is going on — you can ask about a
-project while an agent is working in it. `maxSessions` (4 by default) bounds how
-many agent processes this machine will host at once, and it is the **only**
-thing bounding a question, a roadmap session or an audit (R70). It counts runs
-this daemon has claimed, not children it has spawned: a claim takes a second or
-two to become a process, and counting processes let one pass of the loop claim
-the whole queue.
+project while an agent is working in it. Nothing bounds a question, a roadmap session or an audit but the platform's
+own queue: `maxSessions` was removed in R109, and the workspace gate above is
+the only one.
 
 ## If the daemon dies mid-run
 
@@ -1343,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
@@ -1391,7 +1467,7 @@ permission stops forever.
 
 - `--permission-mode acceptEdits` lets it write files.
 - `--allowedTools mcp__cawdev__…` lets it use the cawdev tools. **Without this
-  the entire loop is unreachable** — no reading the task, no moving the entry,
+  the entire loop is unreachable** — no reading the task, no moving the card,
   no reporting, no asking. A real session found this by being denied
   `task_current` and stopping rather than guessing, which was the right call
   and a good sign for the prompt.
@@ -1417,7 +1493,7 @@ never asks you anything — an unlisted tool is refused, not raised (i138).
 
 **Anything else stops and asks you** (R51). Rather than being denied in
 silence, a session that needs `mvn` or `npm` posts a request that appears in
-your inbox and on the run, and waits for an answer. Allow it once, or allow it
+your Waiting on you page and on the run, and waits for an answer. Allow it once, or allow it
 always here — which writes a rule on the project that every runner serving it
 inherits.
 
@@ -1548,8 +1624,8 @@ after `--mcp-config` fails with `ENAMETOOLONG`, which names neither the flag nor
 the prompt.
 
 The prompt deliberately teaches the **method**, not the task. The task is in the
-roadmap entry, which the agent reads for itself with `task_current` — putting it
-in the prompt too would be a second copy that can disagree with the entry.
+roadmap card, which the agent reads for itself with `task_current` — putting it
+in the prompt too would be a second copy that can disagree with the card.
 
 ### Codex CLI
 

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,