cawdev-cli 0.9.0

package/lib/usage.mjs

@@ -0,0 +1,119 @@
+// What a turn cost, in the unit people actually have.
+//
+// The CLI reports `total_cost_usd`, and it is tempting to show it. **It is a
+// list-price equivalent, not a bill**: the event says so itself with
+// `costBasis: "list"`. Somebody on a Claude subscription pays a flat fee, so
+// "$5.37 so far" tells them a number they will never be charged, and reads as
+// if they have spent it. Tokens are what they actually consumed.
+//
+// Cost belongs in R20, which records it per provider alongside the basis it was
+// quoted on, and leaves it blank when a provider states none. A transcript line
+// is the wrong place to imply an invoice.
+
+/** 1234 → "1.2k", 1234567 → "1.2M". Small numbers stay exact. */
+export function formatTokens(count) {
+  if (typeof count !== 'number' || !Number.isFinite(count) || count < 0) {
+    return '0';
+  }
+  if (count < 1000) {
+    return String(Math.round(count));
+  }
+  if (count < 1_000_000) {
+    const thousands = count / 1000;
+    // 12.4k below a hundred, 124k above: a decimal on a big number is noise.
+    return `${thousands < 100 ? thousands.toFixed(1) : Math.round(thousands)}k`;
+  }
+  return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+/** "45s", "13m", "1h 4m" — a turn's length, at the precision that matters. */
+export function formatDuration(milliseconds) {
+  if (typeof milliseconds !== 'number' || !Number.isFinite(milliseconds) || milliseconds < 0) {
+    return null;
+  }
+  const seconds = Math.round(milliseconds / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+/**
+ * The tokens a `result` event reports.
+ *
+ * `usage` is this turn; `modelUsage` accumulates across the session — which is
+ * what the old line's "so far" was reaching for, and worth keeping now that it
+ * is expressed in something real.
+ *
+ * Cache reads are shown because they are usually the largest number by an order
+ * of magnitude, and a turn that reads 200k of cache and writes 2k of output
+ * looks otherwise inexplicably slow.
+ */
+export function describeUsage(event) {
+  const usage = event?.usage ?? {};
+  const parts = [];
+
+  const input = (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+  if (input) {
+    parts.push(`${formatTokens(input)} in`);
+  }
+  if (usage.output_tokens) {
+    parts.push(`${formatTokens(usage.output_tokens)} out`);
+  }
+  if (usage.cache_read_input_tokens) {
+    parts.push(`${formatTokens(usage.cache_read_input_tokens)} cached`);
+  }
+
+  const session = sessionTotals(event?.modelUsage);
+  if (session) {
+    parts.push(`session ${formatTokens(session.input)} in, ${formatTokens(session.output)} out`);
+  }
+  return parts;
+}
+
+/**
+ * A session's totals so far, or null when the event carries none — R76.
+ *
+ * The same numbers `describeUsage` puts in a transcript line, exported so they
+ * can also be *recorded*. A line is read once by whoever is watching; the point
+ * of R76 is a comparison somebody makes later — the same project with a skill
+ * on and with it off — and a measurement nobody wrote down cannot be taken
+ * afterwards.
+ *
+ * `modelUsage` accumulates across the turns of ONE session, so this is
+ * cumulative for that process and not a delta. What that means for a resumed
+ * run is the runner's problem, and `AgentRun.sawUsage` says how it is handled.
+ */
+export function totalsOf(event) {
+  return sessionTotals(event?.modelUsage);
+}
+
+/** Summed across models: a session that switched models still has one total. */
+function sessionTotals(modelUsage) {
+  if (!modelUsage || typeof modelUsage !== 'object') {
+    return null;
+  }
+  let input = 0;
+  let output = 0;
+  for (const model of Object.values(modelUsage)) {
+    input += (model?.inputTokens ?? 0) + (model?.cacheCreationInputTokens ?? 0);
+    output += model?.outputTokens ?? 0;
+  }
+  return input || output ? { input, output } : null;
+}
+
+/** The whole line: how the turn ended, how long it took, and what it used. */
+export function describeTurn(event) {
+  const bits = [`turn ended (${event?.subtype ?? 'done'})`];
+
+  const duration = formatDuration(event?.duration_ms);
+  if (duration) {
+    bits.push(`in ${duration}`);
+  }
+  const usage = describeUsage(event);
+  return usage.length ? `${bits.join(' ')} · ${usage.join(', ')}` : bits.join(' ');
+}

package/mcp/README.md

@@ -0,0 +1,273 @@
+# cawdev MCP server
+
+Plain Node, zero dependencies, stdio JSON-RPC — `server.mjs`, plus the shared
+rule matcher in `tools/lib/tool-rules.mjs` that the runner uses too. It gives a coding
+agent a project's roadmap and changelog — the same verbs a person gets in the
+console, because the API was built to mirror these tools one-for-one.
+
+## Setting it up in a repository
+
+Mint a token in the cawdev console under **Agent tokens**. Grant it
+`roadmap:write` and `changelog:write` on the project. **You can only grant what
+you hold** — if you are a `READER` there, you get read scopes. A token that
+should only be able to *file feedback* — an application built beside cawdev,
+say — needs just `backlog:write`, which a `READER` may grant and which reaches
+nothing else, not even the roadmap (R199).
+
+Then in the repository the agent works in, add `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cawdev": {
+      "command": "node",
+      "args": ["/path/to/cawdev/tools/mcp/server.mjs"],
+      "env": {
+        "CAWDEV_URL": "http://localhost:4200",
+        "CAWDEV_TOKEN": "cawd_…"
+      }
+    }
+  }
+}
+```
+
+Or leave `env` out and put `CAWDEV_URL` / `CAWDEV_TOKEN` / `CAWDEV_PROJECT` in a
+`.env` at the repository root — **gitignore it.** The server searches upward
+from its working directory.
+
+**Configuration is read on every call, never cached.** Edit `.env` and the next
+call sees it; no restart. That matters more than it sounds: an agent that has
+been writing to the wrong platform for an hour, because the value changed and
+the process was still holding the old one, is a bad afternoon.
+
+### Which project
+
+- A token granted **exactly one** project needs no `project` argument.
+- A multi-project token takes `project` per call, or set `CAWDEV_PROJECT`.
+- Get it wrong and the error lists what the token can actually see.
+
+---
+
+## For the agent reading this
+
+**Run `roadmap_where` first** when anything is surprising. It tells you which
+platform you are talking to, which token you are using, *where each value was
+read from*, and who the platform thinks you are. Most confusion is one of those
+four being different from what you assumed.
+
+### How work starts here
+
+The sequence is fixed, and the second step is the one people skip:
+
+1. Branch off an up-to-date `main`, named after the entry — `r4-roadmap-entries`.
+2. **Move the entry to `CODING` naming the branch, before your first commit**
+   (`roadmap_set_status`). Not after. The roadmap should be able to answer
+   "what is being worked on right now" without asking anyone.
+3. Build to the entry'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
+   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.
+5. When the PR merges, move the entry to `MERGED` naming it. The branch may then
+   be deleted — `CODING` is for work somebody is doing, not work that is done.
+
+### What a status must carry
+
+`roadmap_statuses` will tell you, and it is worth reading rather than guessing:
+`CODING` 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.
+
+**Any status may move to any other.** There is no transition diagram — an entry
+really can go from `CONSIDERING` straight to `SHIPPED` if that is what happened.
+The rules are about what a status *carries*, not the path it took.
+
+### The body is what we want; the plan is how; the comments are the argument
+
+`roadmap_get` gives you all three, and `task_current` gives you them for the
+entry you are working on.
+
+**The plan is the one to read before doing any of the work.** It was written by
+a plan phase and agreed by somebody, and it names the files — R124. If you are
+carrying it out and it turns out to be wrong, say so and stop rather than
+improvising a different change: what was approved was that plan, and a different
+one has not been approved.
+
+You cannot write a plan through this server, and you cannot start a plan phase
+either. The first is the platform's — it stores what a plan phase reports when
+the phase ends, so that a session which must not write is not handed a writer to
+do its own bookkeeping with. The second is refused outright: *an agent cannot
+start another agent*, which is `RunAccess.requireCanStart`'s rule and not an
+omission here. **Read the discussion before you propose anything about an
+entry.** It is where an objection was answered and where an obvious-looking
+approach was ruled out with a reason — and re-proposing what was talked out
+three months ago is precisely what it exists to stop.
+
+Use `roadmap_comment` for the argument: what you measured, what you tried, why
+you did not take the route somebody would expect. Use `roadmap_update` when the
+discussion reaches a conclusion — the body is where a settled answer goes, so
+that the next reader does not have to reconstruct it from the thread.
+
+A comment you write is attributed to your run as well as to the account that
+minted your token, so a person can tell an agent's reading from a colleague's.
+
+### Read what the earlier sessions did before repeating it
+
+`task_current` lists **every run this card has already had** — how each ended,
+on what branch, with what model, whether the work was pushed, and the commits it
+made by subject. A card that failed twice on the same branch is telling you
+something its status does not, and the second attempt is the one that most needs
+to know what the first tried.
+
+No transcripts come with it, deliberately: the terminal log is on the run's own
+page in the console, and nine of them would fill the context this call exists to
+orient. If you need the detail, the discussion under the entry is where a
+previous session should have written down what it learned — and where yours
+should.
+
+### There is no delete
+
+Not in these tools, not in the API. `roadmap_decline` with a reason is the only
+exit an entry has, and the reason is the point: it is what stops the same idea
+being proposed again in six months. Same for changelog entries — correct the
+text, do not remove the record. Same for comments: nothing removes one, and the
+most you can do to your own is correct its wording.
+
+### Ids are permanent, and a card is named by its ref
+
+An entry's number never changes and is never reused. Commit messages and code
+comments point at it. Since R221 a roadmap card and an issue each count on
+their own sequence, so `R91` and `i91` are two cards: wherever a tool takes
+`number`, `related`, `after` or `entryNumber`, pass the ref — `"i91"` for an
+issue — and a bare `91` is read as the roadmap card, which is what it always
+was.
+
+### When a call is refused
+
+The message is the platform's own and it names the rule you hit — a missing
+scope, a status that needs a branch, a project this token cannot see. Read it
+rather than retrying: the refusal is usually telling you something true about
+what you are allowed to do.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `roadmap_where` | Which platform, which token, read from where, and who you are. Start here. |
+| `roadmap_statuses` | The eight statuses, what they mean, what each requires. |
+| `roadmap_list` | Entries, optionally by status. `brief` omits bodies — use it to survey. |
+| `roadmap_get` | One entry in full: its body, **the plan agreed for it**, and the discussion on it. |
+| `roadmap_create` | Create an entry; the platform allocates its permanent number. |
+| `roadmap_update` | Title, body, section, related ids, and the cards it starts coding after (`after` — R181). |
+| `roadmap_comment` | Say something *beside* an entry rather than inside it. |
+| `roadmap_set_status` | Move an entry, 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). |
+| `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. |
+
+### Inside a run
+
+These only work when the token is a **run token** (`cawdr_`), which the runner
+mints when a run starts and hands to the session it spawns. A plain `cawd_`
+token gets a refusal saying so.
+
+| Tool | What it does |
+|---|---|
+| `task_current` | The entry you are working on, its branch, everything already said and asked on this run, **and every earlier run on the same card**. **Call it first**, and again whenever you are unsure where you are. |
+| `report` | `progress` as often as useful; `done` when finished, naming the branch and any PR; `blocked` when a person must resolve something. `done` and `blocked` end the run. |
+| `ask_user` | Ask the person who started the run, and wait. Blocks up to ten minutes, then hands back a `question_id`. |
+| `await_answer` | Resume waiting for a question `ask_user` handed back. |
+| `ask_group` | Ask a **round** — up to twelve questions that belong together, under one title. Blocks until every one of them has been answered, then hands back a `group_id`. |
+| `await_group` | Resume waiting for a round `ask_group` handed back. |
+| `propose_entry` | **Audit and scoping runs only.** Record a finding — or a card cut from a bigger idea (R227) — as a proposal, naming its kind — `issue` with a severity, or `roadmap` without — and, optionally, the `section` it belongs under; a scoping session names one section for every card of the idea. A `roadmap` card **must** say what it starts `after`: `[]` for the first, `"#2"` for the second card proposed in this run (the number the tool answered with — it has to exist already, so file in build order), `"R12"` for a card on the roadmap. A person accepts it as either, or leaves it (R214) — and adds the cards in that order: #2 is refused until #1 is on the roadmap. |
+| `approve` | **Not yours to call.** Claude Code calls it itself, as `--permission-prompt-tool`, when no rule covers a tool call. |
+
+**`ask_user` is for decisions that are genuinely theirs** — an architectural
+choice, a trade-off with no right answer, something the entry does not settle.
+Not for checking work you can check yourself. Every question stops the run and
+costs somebody's attention.
+
+When `ask_user` returns without an answer, **do not guess and carry on.** You
+asked because the decision was not yours. Call `await_answer`, or `report`
+`blocked` and stop.
+
+**`ask_group` is for when you have several questions at once** — R96. One
+question at a time is right for a decision you hit halfway through a piece of
+work; it is wrong when you are trying to understand something, because forty
+separate inbox items arriving over an afternoon is not a conversation, it is an
+interruption repeated forty times. A round arrives as one form under one title,
+the person answers it in one sitting, and you are woken once when all of it is
+answered.
+
+Rounds, then, rather than one enormous list: at most twelve, and the next round
+should be shaped by the answers to this one. Give each round an `intro` saying
+what it is about, and offer `options` where there is a small set of plausible
+answers — they can always write their own.
+
+After `report done` or `report blocked`, the run is over and your token has
+expired with it. There is nothing further to do.
+
+### When something you need is not allowed (R51)
+
+You will not usually notice this happening. When you call a tool no rule covers
+— `mvn`, `npm`, anything outside what the project has granted — Claude Code
+asks `approve` on your behalf, a person is shown the command, and your call
+either goes ahead or comes back refused. From inside the session it looks like a
+tool call that took a while.
+
+Two things to do with the answer:
+
+- **A refusal carries a reason.** Act on it. "Not from an unattended session" is
+  something you can work with — report `blocked` saying what you needed, or find
+  an approach that does not need it. Do not retry the same call hoping for a
+  different person.
+- **An expiry means nobody was there.** Do not loop. Report `blocked`, say
+  exactly what you needed to run and why, and let somebody allow it and start
+  you again.
+
+## Checking it works
+
+Two smoke tests, both driving the server over real stdio.
+
+
+
+```sh
+CAWDEV_URL=http://localhost:4200 CAWDEV_TOKEN=cawd_… node tools/mcp/smoke.mjs scratch-project
+```
+
+**Name a scratch project.** The smoke test creates a roadmap entry and declines
+it, and entries cannot be deleted — so it refuses to guess which project you
+meant. It left two declined entries in cawdev's own roadmap before it did.
+
+It drives the server the way a client does — spawn, write lines to stdin, read
+lines from stdout — rather than importing its functions, because the parts most
+likely to break are the transport and the framing. CI runs it against the
+compose stack.
+
+The orchestration tools, including the case R10 exists for — the agent blocks
+on `ask_user`, something else answers, and the tool call returns the answer:
+
+```sh
+node tools/mcp/orchestration-smoke.mjs scratch-project
+```
+
+It starts a real run (which needs a session, since an agent cannot start another
+agent), drives it through a runner, and exercises the pending path on a
+shortened `CAWDEV_ASK_TIMEOUT_SECONDS`.
+
+A single call, by hand:
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"roadmap_where","arguments":{}}}' \
+  | CAWDEV_TOKEN=cawd_… node tools/mcp/server.mjs
+```

package/mcp/orchestration-smoke.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// R10's "Done when": a scripted JSON-RPC session asks a question, a separate
+// HTTP call answers it, and the tool call returns the answer — plus the
+// ten-minute pending path, on a shortened timeout.
+//
+//   node tools/mcp/orchestration-smoke.mjs <project>
+//
+// Needs a session that can start a run (CAWDEV_BASE, CAWDEV_ADMIN_EMAIL,
+// CAWDEV_ADMIN_PASSWORD), because starting a run is a person's act — an agent
+// cannot start another agent, so this test cannot bootstrap itself from a token.
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BASE = process.env.CAWDEV_BASE ?? 'http://localhost:4200';
+const EMAIL = process.env.CAWDEV_ADMIN_EMAIL ?? 'admin@cawdev.local';
+const PASSWORD = process.env.CAWDEV_ADMIN_PASSWORD ?? 'dev-admin-password';
+
+const project = process.argv[2];
+if (!project) {
+  console.error('Usage: node tools/mcp/orchestration-smoke.mjs <project>');
+  console.error('Use a scratch project: this starts a run and creates a roadmap entry.');
+  process.exit(2);
+}
+
+// --- a session, for the things only a person may do -------------------------
+
+let cookie = '';
+let csrf = '';
+
+function headers(json = true) {
+  return {
+    cookie,
+    ...(json ? { 'content-type': 'application/json' } : {}),
+    ...(csrf ? { 'x-xsrf-token': csrf } : {}),
+  };
+}
+
+function remember(response) {
+  for (const value of response.headers.getSetCookie?.() ?? []) {
+    const [pair] = value.split(';');
+    const [name, ...rest] = pair.split('=');
+    if (name === 'XSRF-TOKEN') csrf = rest.join('=');
+    const others = cookie.split('; ').filter((entry) => entry && !entry.startsWith(`${name}=`));
+    cookie = [...others, pair].join('; ');
+  }
+}
+
+async function session(path, options = {}) {
+  const response = await fetch(`${BASE}${path}`, { ...options, headers: headers() });
+  remember(response);
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`${options.method ?? 'GET'} ${path} -> ${response.status}: ${text}`);
+  }
+  return text ? JSON.parse(text) : null;
+}
+
+await fetch(`${BASE}/api/auth/me`, { headers: headers(false) }).then(remember);
+await session('/api/auth/login', {
+  method: 'POST',
+  body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+});
+
+// A fresh entry and run. Any earlier live run would block this one.
+for (const run of await session(`/api/projects/${project}/runs`)) {
+  if (run.live) {
+    await session(`/api/projects/${project}/runs/${run.id}/transition`, {
+      method: 'POST',
+      body: JSON.stringify({ state: 'CANCELLED', summary: 'Cleared by the orchestration smoke.' }),
+    });
+  }
+}
+
+const entry = await session(`/api/projects/${project}/roadmap`, {
+  method: 'POST',
+  body: JSON.stringify({
+    title: 'orchestration smoke (safe to decline)',
+    body: 'Created by tools/mcp/orchestration-smoke.mjs.\n\n**Build:** nothing, really.',
+  }),
+});
+
+const started = await session(`/api/projects/${project}/runs`, {
+  method: 'POST',
+  body: JSON.stringify({ entryNumber: entry.number, branch: `r${entry.number}-smoke` }),
+});
+const runId = started.id;
+
+// The runner's part: claim it and set it running, so the agent's token is
+// working on a run that is actually going.
+const runnerToken = (
+  await session('/api/tokens', {
+    method: 'POST',
+    body: JSON.stringify({
+      label: `orchestration smoke ${Date.now()}`,
+      grants: { [project]: ['runner:operate'] },
+    }),
+  })
+).secret;
+
+async function asRunner(path, body) {
+  const response = await fetch(`${BASE}${path}`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${runnerToken}`,
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!response.ok) {
+    throw new Error(`${path} -> ${response.status}: ${await response.text()}`);
+  }
+  return response.json();
+}
+
+const runner = await asRunner('/api/runners', { name: `smoke-${Date.now()}` });
+// The claim is where the run token comes from — it goes straight to the runner,
+// never to the person who started the run.
+const claimed = await asRunner(`/api/runners/${runner.id}/claim/${runId}`);
+await asRunner(`/api/projects/${project}/runs/${runId}/transition`, { state: 'RUNNING' });
+
+// --- the agent's side, over real stdio ---------------------------------------
+
+const server = spawn(process.execPath, [join(here, 'server.mjs')], {
+  stdio: ['pipe', 'pipe', 'inherit'],
+  env: {
+    ...process.env,
+    CAWDEV_URL: BASE,
+    CAWDEV_TOKEN: claimed.runToken,
+    // Short, so the pending path can be exercised without waiting ten minutes.
+    CAWDEV_ASK_TIMEOUT_SECONDS: '3',
+  },
+});
+
+let buffer = '';
+const waiting = new Map();
+server.stdout.on('data', (chunk) => {
+  buffer += chunk;
+  let newline;
+  while ((newline = buffer.indexOf('\n')) !== -1) {
+    const line = buffer.slice(0, newline).trim();
+    buffer = buffer.slice(newline + 1);
+    if (!line) continue;
+    const message = JSON.parse(line);
+    const resolve = waiting.get(message.id);
+    if (resolve) {
+      waiting.delete(message.id);
+      resolve(message);
+    }
+  }
+});
+
+let nextId = 1;
+function request(method, params) {
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    waiting.set(id, resolve);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+    setTimeout(() => reject(new Error(`${method} timed out`)), 60_000).unref();
+  });
+}
+const callTool = (name, args = {}) => request('tools/call', { name, arguments: args });
+const textOf = (result) => result?.content?.map((part) => part.text).join('\n') ?? '';
+
+const checks = [];
+function check(description, condition, detail = '') {
+  checks.push(Boolean(condition));
+  console.log(
+    `${condition ? 'ok  ' : 'FAIL'}  ${description}${detail && !condition ? `\n        ${detail}` : ''}`,
+  );
+}
+
+try {
+  await request('initialize', { protocolVersion: '2024-11-05', capabilities: {} });
+
+  const current = await callTool('task_current');
+  check(
+    'task_current re-orients: entry, branch and run state',
+    !current.result?.isError
+      && textOf(current.result).includes(`r${entry.number}-smoke`)
+      && textOf(current.result).includes('orchestration smoke'),
+    textOf(current.result),
+  );
+
+  const progress = await callTool('report', { kind: 'progress', body: 'Read the entry.' });
+  check('report progress keeps the run RUNNING',
+    textOf(progress.result).includes('RUNNING'), textOf(progress.result));
+
+  // The pending path: nobody answers within the shortened timeout.
+  const pending = await callTool('ask_user', { question: 'Nobody will answer this one.' });
+  check(
+    'ask_user hands back a question_id when nobody answers',
+    textOf(pending.result).includes('await_answer')
+      && /question_id [0-9a-f-]{36}/.test(textOf(pending.result)),
+    textOf(pending.result),
+  );
+  const pendingId = /question_id ([0-9a-f-]{36})/.exec(textOf(pending.result))?.[1];
+
+  // R10's headline: the agent asks and blocks; something else answers; the
+  // tool call returns the answer.
+  const asking = callTool('ask_user', {
+    question: 'Postgres or SQLite?',
+    options: ['Postgres', 'SQLite'],
+  });
+
+  // Give the ask time to reach the platform, then answer it from outside.
+  await new Promise((resolve) => setTimeout(resolve, 800));
+  // Three groups since R36, not one list: what is on you, what you passed on,
+  // and what somebody wants your opinion about. Nothing has been passed
+  // anywhere here, so it is in the first.
+  const inbox = await session('/api/inbox');
+  const target = inbox.waitingOnYou.find(
+    (item) => item.question.question === 'Postgres or SQLite?',
+  );
+  check('the question reached the inbox with its run context',
+    target && target.projectSlug === project, JSON.stringify(inbox));
+
+  await session(
+    `/api/projects/${project}/runs/${runId}/questions/${target.question.id}/answer`,
+    { method: 'POST', body: JSON.stringify({ answer: 'Postgres, to match the platform.' }) },
+  );
+
+  const answered = await asking;
+  check(
+    'the waiting ask_user call returns the answer',
+    !answered.result?.isError
+      && textOf(answered.result).includes('Postgres, to match the platform.')
+      && textOf(answered.result).includes(EMAIL),
+    textOf(answered.result),
+  );
+
+  // And await_answer resumes the one left pending.
+  await session(`/api/projects/${project}/runs/${runId}/questions/${pendingId}/answer`, {
+    method: 'POST',
+    body: JSON.stringify({ answer: 'Answered late.' }),
+  });
+  const resumed = await callTool('await_answer', { question_id: pendingId });
+  check('await_answer picks up the question ask_user handed back',
+    textOf(resumed.result).includes('Answered late.'), textOf(resumed.result));
+
+  const done = await callTool('report', {
+    kind: 'done',
+    body: `Nothing to build. Branch r${entry.number}-smoke exists only in this test.`,
+  });
+  check('report done ends the run, and says the token is spent',
+    textOf(done.result).includes('FINISHED') && textOf(done.result).includes('expired'),
+    textOf(done.result));
+
+  // The run is over, so its token is too.
+  const afterwards = await callTool('task_current');
+  check('the run token stops working once the run has ended',
+    afterwards.result?.isError, textOf(afterwards.result));
+} finally {
+  server.stdin.end();
+  // Leave the entry declined rather than lying around as PLANNED — entries
+  // cannot be deleted, so the least noise is an honest reason.
+  await session(`/api/projects/${project}/roadmap/${entry.number}/decline`, {
+    method: 'POST',
+    body: JSON.stringify({ reason: 'A smoke-test entry, declined by the test that made it.' }),
+  }).catch(() => undefined);
+}
+
+const failed = checks.filter((ok) => !ok).length;
+console.log(`\n${checks.length - failed}/${checks.length} checks passed.`);
+process.exit(failed ? 1 : 0);