cawdev-cli 1.0.9-beta → 1.0.10-beta

package/lib/roadmap-format.mjs

@@ -56,11 +56,13 @@ export function statusToDisplay(status) {
  * The file has always grouped these two this way, and deriving them means a
  * declined entry cannot end up filed under a phase it is no longer part of.
  *
- * Two, and REVIEW is deliberately not a third: work waiting to be read is still
+ * Three since R371 — BACKLOG joined — and REVIEW is deliberately not a fourth: work waiting to be read is still
  * part of the phase it belongs to, and moving it to a section of its own would
  * take it out of its phase for a few days and put it back afterwards.
  */
 export const STATUS_SECTIONS = {
+  // R371: waiting to be brought in, before what is being considered.
+  BACKLOG: 'Backlog — waiting to be brought in',
   CONSIDERING: 'Considering — wanted, not settled',
   DECLINED: 'Declined — decided against, with the reason',
 };
@@ -77,6 +79,8 @@ export const STATUS_SECTIONS = {
 export const ISSUE_SECTIONS = {
   NEW: 'New — filed, not yet triaged',
   CONFIRMED: 'Confirmed — real, waiting for somebody',
+  // R371: an issue waiting to be brought in — after what needs somebody now.
+  BACKLOG: 'Backlog — waiting to be brought in',
   IN_DEVELOPMENT: 'In development — somebody is fixing it',
   MERGED: 'Resolved — the fix landed',
   SHIPPED: 'Released — the fix shipped',

package/lib/runner-config.mjs

@@ -76,7 +76,7 @@ function canonical(value) {
   if (value === undefined) return 'undefined';
   return JSON.stringify(value, (_, inner) => (
     inner && typeof inner === 'object' && !Array.isArray(inner)
-      ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+      ? Object.fromEntries(Object.keys(inner).sort((a, b) => a.localeCompare(b)).map((key) => [key, inner[key]]))
       : inner
   ));
 }

package/mcp/README.md

@@ -81,6 +81,14 @@ commit, or a sha — `SHIPPED` needs a version that is a real git tag, and
 request it would otherwise carry belongs to the run, and a project that reviews
 without opening pull requests has none to give it.
 
+**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
+card or issue an agent files is the backlog: waiting until a person or a sprint
+brings it in, in no sprint and on no board column. Its origin names your
+session and the card your run was on. Name a status (`CONSIDERING`, `NEW`) when
+you mean the pipeline. Giving a backlog card a sprint moves it to the first
+status of its kind; moving a card to `BACKLOG` takes it out of its sprint.
+
 **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.
@@ -165,9 +173,10 @@ what you are allowed to do.
 | `roadmap_create` | Create an entry; the platform allocates its permanent number. |
 | `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), when it is due and how big it is (`due` — R351: an ISO date, `""` clears; `estimate`: a positive number, `0` clears), the version it is meant for (`targetVersion` — R358, `""` clears; since R362 it must be one the project defined under Project settings → Versions, and any other name is refused), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
 | `roadmap_comment` | Say something *beside* an entry rather than inside it. |
+| `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 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). |
+| `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). |
 | `changelog_list` | The changelog, grouped by release, newest first. |
 | `changelog_get` | One entry. |
 | `changelog_add` | Add an entry; no version means `Unreleased`. |

package/mcp/server.mjs

@@ -412,6 +412,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'NEW',
@@ -621,13 +622,70 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'done_when_tick',
+    description:
+      "Tick (or untick) one item of the card's Done-when checklist as built. Items are " +
+      "numbered from 1 as task_current lists them. Call it when you have BUILT the item and " +
+      'CHECKED it, with one line of evidence — a test name, a command, a file:line. Do not ' +
+      'tick what you did not check: the reviewer ticks their own column separately and sees ' +
+      'yours. Defaults to the card this run is working on, and a run cannot tick another.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...PROJECT_ARGUMENT,
+        number: {
+          type: ['string', 'integer'],
+          description:
+            'The card by ref — R91, i91. Optional inside a run: defaults to the run\'s own card.',
+        },
+        item: { type: 'integer', minimum: 1, description: "The item's number, from 1." },
+        done: { type: 'boolean', description: 'false takes the tick back. Default true.' },
+        note: {
+          type: 'string',
+          description: 'One line of evidence: a test name, a command, a file:line.',
+        },
+      },
+      required: ['item'],
+    },
+    handler: async (config, args) => {
+      let slug;
+      let ref = args.number;
+      if (ref === undefined || ref === null || ref === '') {
+        const { runId, project } = await requireRun(config);
+        const run = await api(config, `/api/projects/${project}/runs/${runId}`);
+        ref = run.entryRef ?? run.entryNumber;
+        slug = project;
+      } else {
+        slug = await resolveProject(config, args.project);
+      }
+      if (ref === undefined || ref === null || ref === '') {
+        throw new CawdevError('This run has no card, so there is no Done-when list to tick.');
+      }
+      if (!Number.isInteger(args.item) || args.item < 1) {
+        throw new CawdevError('item must be a whole number from 1, as task_current lists them.');
+      }
+      const done = args.done !== false;
+      const row = await api(config, `/api/projects/${slug}/roadmap/${encodeURIComponent(String(ref))}/done-when/${args.item}/built`, {
+        method: 'PUT',
+        body: { done, note: args.note },
+      });
+      return (
+        `${done ? 'Ticked' : 'Unticked'} item ${row.position} of ${ref} in ${slug} as built: ` +
+        row.text
+      );
+    },
+  },
+
   {
     name: 'roadmap_create',
     description:
       'Create a roadmap entry. The platform allocates its permanent number — written R91 on ' +
       'a roadmap card and i91 on an issue, one sequence across both — and the ' +
-      'platform decides where a card starts — CONSIDERING — unless you say otherwise; ' +
-      'a status that requires something must be given it.',
+      'project decides where a card you file starts — the BACKLOG by default for a card an ' +
+      'agent files, waiting until a person or a sprint brings it in — unless you say ' +
+      'otherwise; a status that requires something must be given it. A card in the BACKLOG ' +
+      'holds no sprint: giving it one moves it to CONSIDERING.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -640,6 +698,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'IN_DEVELOPMENT',
@@ -733,7 +792,7 @@ const TOOLS = [
     description:
       'What is broken in a project, and how badly — R85. The same numbering as the roadmap, ' +
       'written with an i: card 91 filed as an issue is i91, and there is no R91 as well. ' +
-      'Statuses are NEW, CONFIRMED, IN_DEVELOPMENT, MERGED (drawn as ' +
+      'Statuses are BACKLOG, NEW, CONFIRMED, IN_DEVELOPMENT, MERGED (drawn as ' +
       'Resolved) and DECLINED (Won\'t fix).',
     inputSchema: {
       type: 'object',
@@ -741,7 +800,7 @@ const TOOLS = [
         ...PROJECT_ARGUMENT,
         status: {
           type: 'string',
-          enum: ['NEW', 'CONFIRMED', 'IN_DEVELOPMENT', 'MERGED', 'SHIPPED', 'DECLINED'],
+          enum: ['BACKLOG', 'NEW', 'CONFIRMED', 'IN_DEVELOPMENT', 'MERGED', 'SHIPPED', 'DECLINED'],
         },
         assignee: {
           type: 'string',
@@ -768,8 +827,10 @@ const TOOLS = [
   {
     name: 'issue_file',
     description:
-      'File an issue: something that is broken, with how badly. Lands at NEW — filed and not ' +
-      'yet triaged — unless you say CONFIRMED, which claims you have already checked it. The ' +
+      'File an issue: something that is broken, with how badly. Lands where the project says ' +
+      'for an issue an agent files — the BACKLOG by default, waiting to be brought in, or NEW ' +
+      '(filed and not yet triaged) — unless you say NEW, or CONFIRMED, which claims you have ' +
+      'already checked it. The ' +
       'severity is required: it is how the board is ordered. Use `related` to name the card it ' +
       'was found on, by ref (R84). Issues count on their own sequence — R221 — and are ' +
       'written with an i: i91 is the ninety-first issue, and R91 is another card.',
@@ -780,7 +841,7 @@ const TOOLS = [
         title: { type: 'string' },
         body: { type: 'string', description: 'Markdown. What happens, and what should instead.' },
         severity: { type: 'string', enum: ['CRITICAL', 'MEDIUM', 'MINOR'] },
-        status: { type: 'string', enum: ['NEW', 'CONFIRMED'] },
+        status: { type: 'string', enum: ['BACKLOG', 'NEW', 'CONFIRMED'] },
         related: {
           type: 'array',
           items: { type: ['string', 'integer'] },
@@ -833,14 +894,25 @@ const TOOLS = [
         kind: { type: 'string', enum: ['ISSUE', 'FEATURE'] },
         title: { type: 'string' },
         body: { type: 'string', description: 'Markdown. What you noticed, and what should happen instead.' },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Who it came from, beyond you — e.g. "customer" when you are passing on what a user ' +
+            'said. "agent" is always added: you filed it. Same word rule as card tags.',
+        },
       },
       required: ['kind', 'title', 'body'],
     },
     handler: async (config, args) => {
       const slug = await resolveProject(config, args.project);
+      // R372: feedback says who it came from, and an agent filing it is one
+      // of the sources. Added here, at the agent's own door, not by the API:
+      // an application's token files through the same endpoint and is not an agent.
+      const tags = [...new Set([...(Array.isArray(args.tags) ? args.tags : []), 'agent'])];
       const item = await api(config, `/api/projects/${slug}/backlog`, {
         method: 'POST',
-        body: pick(args, ['kind', 'title', 'body']),
+        body: { ...pick(args, ['kind', 'title', 'body']), tags },
       });
       return `Filed in ${slug}'s backlog as pending: "${item.title}". Somebody will accept it ` +
         'as a card or an issue, or refuse it.';
@@ -959,6 +1031,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'NEW',
@@ -1170,6 +1243,12 @@ const TOOLS = [
         config,
         `/api/projects/${project}/roadmap/${cardRef}/plans`,
       ).catch(() => []);
+      // R368. The plan's Done-when list, numbered, with the ticks so far. Its
+      // own try, like the plan above: a platform without it answers 404.
+      const criteria = await api(
+        config,
+        `/api/projects/${project}/roadmap/${cardRef}/done-when`,
+      ).catch(() => []);
 
       const lines = [];
 
@@ -1212,6 +1291,9 @@ const TOOLS = [
         }
       }
       lines.push(formatEntry(entry, { comments, plan: plans?.[0] ?? null }));
+      if (criteria?.length) {
+        lines.push('', formatDoneWhen(criteria));
+      }
 
       // What happened the other times. A session is told the entry and the
       // branch but not that two previous runs on this card failed, which is
@@ -2340,6 +2422,22 @@ function formatPlan(plan) {
   return [`--- the plan (${written}) ---`, plan.body].join('\n');
 }
 
+/**
+ * R368. The Done-when list as an agent reads it: numbered as done_when_tick
+ * takes them, with each tick and its evidence. A reviewer's confirmation is
+ * shown too — it is the other column, and the agent should see it.
+ */
+export function formatDoneWhen(criteria) {
+  const lines = ['--- done when (tick each with done_when_tick once you have checked it) ---'];
+  for (const item of criteria) {
+    const mark = item.built ? '[built]' : '[ ]';
+    const note = item.built && item.builtNote ? ` — ${item.builtNote}` : '';
+    const confirmed = item.confirmed ? ' (confirmed by reviewer)' : '';
+    lines.push(`${String(item.position).padStart(2)}. ${mark} ${item.text}${note}${confirmed}`);
+  }
+  return lines.join('\n');
+}
+
 /**
  * One earlier attempt at this card — R38.
  *

package/package.json

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

package/runner/README.md

@@ -510,6 +510,22 @@ then ↑.
 **`/view`** opens the focused session's page on cawdev — transcript, stages,
 card — in the browser, on the console this terminal signed in to.
 
+**On a session waiting for you** — a question, or a permission such as a stage
+gate whose summary is the whole plan — the prompt only has room for the start
+of it, and says so: `/view reads it all · /open answers it on cawdev`.
+**`/view`** then opens the READER: one window over the whole screen with the
+session's output and, under a rule, the request in full (the question and its
+options; the permission's summary, its input and its keys). It opens on the
+request; `↑`/`↓` (and the wheel), `PgUp`/`PgDn`, `g`/`G` scroll it, `esc`
+closes it, and any other key closes it and does what it always does — `a`
+answers, `y`/`s`/`n` decide. Outside advanced mode `/view` prints the request
+whole into the scrollback. When the question has options its list opens by
+itself and hides the banner; the list's own key line says `/view reads it all`,
+and `/` there leaves the list for the command line (`a` brings it back).
+**`/open`** opens the session's run page on cawdev,
+where the question panel and the decision are. `readerFrame` in split.mjs is
+the window, pure.
+
 **`/view R29`** prints a card here instead: its status, section, tags, branch,
 work item and pull request, who is coding or reviewing it, what it is related
 to, its page on the web, and the first thirty lines of its body (`cardLines`,
@@ -607,6 +623,21 @@ the whole of removing it. A clone and not a `git worktree`, on purpose: the
 daemon's reset checks the default branch out, which git refuses in a second
 worktree. Changed without a restart, like `agentCommands`.
 
+### Where a session with no branch reads: `<first>-read`
+
+A plan, a verify or an ask cuts no branch and takes no checkout, so it used to
+run in the project's first checkout **as that checkout happened to be** — on
+whatever branch the last run left there. A cancelled CTO Interview left
+`cto-interview` checked out, hundreds of commits behind, and every plan after
+it read that code. Such a session now reads `<first>-read`, beside the first
+checkout: a **detached `git worktree`** of it, brought to `origin/<default
+branch>` at the start of a session whenever no other session is reading there.
+The checkout itself is never moved, because a coding run may be working in it.
+One per project rather than one per run, because the CLI keeps a resumable
+conversation by its folder. Detached, so the default branch is never checked
+out twice. If it cannot be made — no remote, not a repository — the session
+reads the first checkout as before, and the log says why.
+
 ### `/reload`
 
 Quitting and starting again, in one word — for when the client's code changed

package/runner/attach.mjs

@@ -60,7 +60,7 @@ import {
 import { clip, keyList, padVisible, painter, stripAnsi, visibleWidth, wrap } from '../lib/ansi.mjs';
 import { restartNeededFor } from '../lib/runner-config.mjs';
 import {
-  BOARD_COLUMNS, MIN_ZONE_HEIGHT, PROMPT_ROWS, SplitScreen, tabsLine, visibleSessions, actionsFor, composeFrame,
+  BOARD_COLUMNS, MIN_ZONE_HEIGHT, PROMPT_ROWS, SplitScreen, readerFrame, tabsLine, visibleSessions, actionsFor, composeFrame,
   carriesOnHere, builtNothing, cardLines, cardTitleFor, commandWords, wordsText, subtitleFor, agentModelFor, wordWrap, isAutoCheckout, isPullRequest, parseNew, roadmapStrip, sessionTag, splitLayout, titleFor, toneFor,
   windowLines,
 } from './split.mjs';
@@ -298,8 +298,14 @@ export function permissionBanner(pending, width, ink = painter(3), machine = {})
     .find((lines) => lines.length <= 2)
     ?? rows(without(short));
 
+  // A stage gate's summary is the whole PLAN, many lines long: one row here,
+  // and how much more there is — `/view` reads it whole. Clipped as one
+  // string, its newlines went through and filled the prompt.
+  const [first = '', ...more] = String(approval.summary ?? '').split('\n');
+  const rest = more.filter((line) => line.trim()).length;
+  const tail = rest ? ` (+${rest} lines)` : '';
   return [
-    `${ink.bold(ink.warn(' permission '))} ${clip(approval.summary, Math.max(8, width - 13))}`,
+    `${ink.bold(ink.warn(' permission '))} ${clip(first, Math.max(8, width - 13 - tail.length))}${ink.muted(tail)}`,
     ink.muted(` ${approval.toolName} · waiting since ${approval.askedAt?.slice(11, 19) ?? ''}`),
     ...keys,
   ];
@@ -832,8 +838,8 @@ const COMMANDS = [
   ['/continue', 'pick a failed or stopped session back up on this machine — the console\'s Carry on'],
   ['/projects', 'which projects advanced mode shows — tick one or several'],
   ['/refresh', "read the cards and their statuses from cawdev again — advanced mode's roadmap"],
-  ['/open', "open the session's pull request in your browser — or, on a finished plan, its card and plan on cawdev"],
-  ['/view', "a card here in the terminal: /view R29, /view <words of its title> (@project), /view card for the session's; /view alone opens the session on cawdev"],
+  ['/open', "open the session's pull request in your browser — on a finished plan, its card and plan; on one waiting for you, its page on cawdev"],
+  ['/view', "a card here in the terminal: /view R29, /view <words of its title> (@project), /view card for the session's; /view alone reads what a session waits on in full, or opens it on cawdev"],
   ['/drop', 'delete the checkout a finished session was made on demand for'],
   ['/close', "close an ended session's window"],
   ['/reload', 'quit and start again on the code on disk — the runner too, when nothing is running'],
@@ -1625,6 +1631,9 @@ export class Attached {
     }
     this.interrupting = false;
 
+    if (this.reader && this.mode === 'keys') {
+      return this.onReaderKey(key);
+    }
     if (this.mode === 'typing') {
       return this.onTyping(key);
     }
@@ -1755,7 +1764,8 @@ export class Attached {
 
   /** Everything open, closed. Returns whether there was anything. */
   closeEverything() {
-    const open = this.mode !== 'keys';
+    const open = this.mode !== 'keys' || Boolean(this.reader);
+    this.reader = null;
     this.mode = 'keys';
     this.select = null;
     this.input = null;
@@ -2082,6 +2092,16 @@ export class Attached {
       this.select = null;
       return this.note('');
     }
+    // A question's or a permission's list holds only the start of what is
+    // asked; `/` leaves it for a command — `/view` reads it whole, `/open`
+    // answers it on cawdev — and `a` (or `y`/`n`) brings the choice back.
+    if (key === '/' && (select.kind === 'question' || select.kind === 'permission')) {
+      this.mode = 'keys';
+      this.select = null;
+      this.answering = null;
+      this.deciding = null;
+      return this.type('command', 'cawdev ▸', '/');
+    }
 
     const outcome = select.key(key);
     if (!outcome) {
@@ -2287,8 +2307,9 @@ export class Attached {
     }
     return this.openPicker(new Select({
       kind: 'question',
-      title: clip(`${this.tagOf(this.current())} asks: ${asking.question.question}`,
+      title: clip(`${this.tagOf(this.current())} asks: ${String(asking.question.question).split('\n')[0]}`,
         Math.max(20, this.screen.width - 2)),
+      hint: '/view reads it all',
       rows: [
         ...options.map((option) => ({ id: option, label: option })),
         // Always last, and always there.
@@ -2316,7 +2337,10 @@ export class Attached {
       kind: 'permission',
       // The call, on the title, as well as printed in full above: the picker
       // may still be on screen when the transcript under it has moved on.
-      title: `${this.tagOf(this.current())} wants ${approval.toolName} · ${approval.summary}`,
+      // The first line only: a stage gate's summary is the whole plan, and
+      // `/view` is where it is read.
+      title: `${this.tagOf(this.current())} wants ${approval.toolName} · ${String(approval.summary ?? '').split('\n')[0]}`,
+      hint: '/view reads it all',
       rows: [
         { id: 'y', label: 'Allow once', hint: 'this call and no more' },
         // R78: the middle grant NAMES what it covers, and it says so in the
@@ -2831,7 +2855,8 @@ export class Attached {
       case 'open':
         return void this.openInBrowser();
       case 'view':
-        return rest.length ? void this.viewCard(rest) : this.viewOnCawdev();
+        if (rest.length) return void this.viewCard(rest);
+        return this.waitingOn(this.commandTarget()) ? this.openReader() : this.viewOnCawdev();
       case 'drop':
         return void this.dropCheckout();
       case 'close':
@@ -3250,6 +3275,9 @@ export class Attached {
   splitFrame() {
     const { width, height } = this.split.screen;
     const ink = this.ink;
+    if (this.reader) {
+      return composeFrame(width, height, [{ rect: { top: 0, left: 0, width, height }, lines: this.readerScreen(width, height) }]);
+    }
     const windows = this.windows();
     const inner = Math.max(8, width - 2);
 
@@ -3269,6 +3297,11 @@ export class Attached {
         + ' · / commands · tab next window');
     // A question or a request on screen says which window it came from.
     const from = banner.length ? [ink.bold(ink.warn(` from ${this.tagOf(current)}`))] : [];
+    // Under the banner and right above the line, so a long one never pushes
+    // it out of the window: the way to read all of it, and the other door.
+    // Also while its list is open, which hides the banner.
+    const whole = banner.length || this.waitingOn(this.commandTarget())
+      ? [ink.muted(' /view reads it all · /open answers it on cawdev')] : [];
     // The commands matching what is typed, above the line as in the footer —
     // advanced mode drew none, so enter took a highlighted command nobody saw.
     const matches = this.mode === 'typing' && this.input?.showing !== false ? this.matching() : { rows: [], at: 0 };
@@ -3278,7 +3311,7 @@ export class Attached {
     const completing = completionLines(
       matches.rows.slice(first, first + SPLIT_COMPLETIONS), matches.at - first, inner, ink,
     );
-    const fixed = [...from, ...banner, ...overlay, ...completing, input];
+    const fixed = [...from, ...banner, ...whole, ...overlay, ...completing, input];
     const promptRows = Math.max(PROMPT_ROWS, fixed.length + 5);
     // The roadmap across the top: as tall as its fullest column needs, never
     // more than a third of the screen, and never so tall that no window fits
@@ -3499,17 +3532,20 @@ export class Attached {
     if (shown.length === 1 && !words.some((word) => word.startsWith('@'))) {
       words = [...words, `@${shown[0]}`];
     }
-    const bare = words.filter((word) => word && !word.startsWith('@') && word !== '--anyway');
+    const bare = words.filter((word) => word && !word.startsWith('@') && word !== '--anyway' && word !== '--again');
     if (bare.length === 1 && ['dev', 'code'].includes(bare[0].toLowerCase())) {
       const named = words.find((word) => word.startsWith('@'));
       await this.pickPlanned(named ? named.slice(1) : null);
       return;
     }
     const anyway = words.includes('--anyway');
+    // R369: the answer to "a session already finished here" — `--anyway`'s
+    // shape, for a different question.
+    const again = words.includes('--again');
     // `--codex`, `--claude`, `--agy`: this session's agent, over `/agent`'s.
     const flagged = words.find((word) => AGENT_FLAGS.has(word));
     let agent = flagged ? flagged.slice(2) : this.agent;
-    const parsed = parseNew(words.filter((word) => word !== '--anyway' && !AGENT_FLAGS.has(word)), {
+    const parsed = parseNew(words.filter((word) => word !== '--anyway' && word !== '--again' && !AGENT_FLAGS.has(word)), {
       // In advanced mode, among the projects it shows.
       projects: this.shownProjects(),
     });
@@ -3557,7 +3593,7 @@ export class Attached {
           // R150: the session writes the card first, then plans it.
           : ['runs/plan', { prompt: parsed.text }, 'a plan — it writes its card first']
         : ['runs', { entryNumber: parsed.ref }, `the development of ${parsed.ref}`];
-    const started = await this.startSession(parsed.slug, path, withAgent(body, agent), withWho(what, agent), anyway);
+    const started = await this.startSession(parsed.slug, path, withAgent(body, agent), withWho(what, agent), anyway, again);
     if (started && plan) {
       this.closeWindowOf(plan);
       this.focusOnArrival = plan.projectSlug;
@@ -3819,9 +3855,10 @@ export class Attached {
    * One POST that starts a session, aimed at THIS machine so its window opens
    * here. A usage window over the machine's threshold is refused by the
    * platform in a sentence; `--anyway` is the same decision the console's
-   * panel asks for.
+   * panel asks for. A card whose last session of that kind finished asks too
+   * (R369), and `--again` answers it.
    */
-  async startSession(slug, path, body, what, anyway) {
+  async startSession(slug, path, body, what, anyway, again = false) {
     try {
       await this.session.request(`/api/projects/${slug}/${path}`, {
         method: 'POST',
@@ -3829,15 +3866,20 @@ export class Attached {
           ...body,
           ...(this.runner?.id ? { targetRunnerId: this.runner.id } : {}),
           ...(anyway ? { acknowledgeUsage: true } : {}),
+          ...(again ? { again: true } : {}),
         },
       });
       this.say(this.ink.success(`  started ${what} on ${slug} — its window opens when this machine takes it`));
       this.note('');
       return true;
     } catch (failure) {
-      this.note(/usage|window/i.test(failure.message)
-        ? `${failure.message} — add --anyway to start it regardless`
-        : failure.message);
+      // R369's sentence is checked first: it is the one that names a session,
+      // and the usage test is loose enough to match words in other sentences.
+      this.note(/session that finished/.test(failure.message)
+        ? `${failure.message} — add --again to start it regardless`
+        : /usage|window/i.test(failure.message)
+          ? `${failure.message} — add --anyway to start it regardless`
+          : failure.message);
       return false;
     }
   }
@@ -3948,6 +3990,16 @@ export class Attached {
     if (!meta) {
       return this.note('/open needs a session — focus one');
     }
+    if (this.waitingOn(meta)) {
+      // Stopped on a question or a permission: the run page on cawdev, where
+      // the question panel and the decision are, whole.
+      const url = this.consoleUrl(meta.projectSlug ?? meta.view?.projectSlug, `runs/${meta.id}`);
+      if (!url) {
+        return this.note('cannot tell where this session is on cawdev');
+      }
+      this.openLink(url);
+      return this.note(`opened ${url}`);
+    }
     if (this.finishedPlan(meta)) {
       const ref = meta.view.entryRef;
       const board = /^i/i.test(ref) ? 'issues' : 'roadmap';
@@ -3989,6 +4041,129 @@ export class Attached {
     opener(url);
   }
 
+  /** What a session is stopped on — a question or a permission request — or null. */
+  waitingOn(meta) {
+    const run = meta ? this.runs.find((each) => each.id === meta.id) : null;
+    if (!run) return null;
+    const pending = this.pendingOn(run);
+    if (pending) return { kind: 'permission', pending };
+    const asking = this.askingOn(run);
+    return asking ? { kind: 'question', asking } : null;
+  }
+
+  /**
+   * `/view` on a session waiting for you: what it is waiting on, in FULL. In
+   * advanced mode the reader — the session's output and the request under
+   * it, over the whole screen, scrolled with the arrows (the wheel arrives as
+   * arrows there), PgUp/PgDn, g/G; esc closes it, and any other key closes it
+   * and does what it does (`a` answers, `y`/`n` decide). In the scrollback
+   * the request is printed whole, where the terminal scrolls it.
+   */
+  openReader() {
+    const meta = this.commandTarget();
+    if (!this.split) {
+      this.say('');
+      for (const line of this.requestLines(this.waitingOn(meta), this.screen.width)) this.say(line);
+      this.say('');
+      return this.note('');
+    }
+    this.reader = { runId: meta.id, top: null, room: 1, max: 0 };
+    this.dirty = true;
+    return this.note('');
+  }
+
+  /** The request a session waits on, every word of it. */
+  requestLines(waiting, width) {
+    const ink = this.ink;
+    if (!waiting) {
+      return [ink.muted('  no longer waiting — answered, decided, or gone')];
+    }
+    const room = Math.max(20, width - 4);
+    if (waiting.kind === 'question') {
+      const { question, yours, waitingOn } = waiting.asking;
+      return [
+        ink.bold(ink.accent(' question ')),
+        ...String(question.question ?? '').split('\n').flatMap((part) => wordWrap(part, room)).map((line) => `  ${line}`),
+        ...(question.options?.length
+          ? ['', ...question.options.map((option, i) => `  ${ink.success(String(i + 1))} ${option}`)]
+          : []),
+        '',
+        yours
+          ? `  ${ink.success('a')} ${ink.muted('answers it here · /open answers it on cawdev')}`
+          : ink.muted(`  waiting on ${waitingOn ?? 'somebody else'} — theirs to answer`),
+      ];
+    }
+    const approval = waiting.pending.approval ?? waiting.pending;
+    return [
+      `${ink.bold(ink.warn(' permission '))} ${ink.muted(`${approval.toolName ?? ''} · waiting since ${approval.askedAt?.slice(11, 19) ?? ''}`)}`,
+      ...String(approval.summary ?? '').split('\n').flatMap((part) => wordWrap(part, room)).map((line) => `  ${line}`),
+      ...(approval.toolInput && approval.toolInput !== approval.summary
+        ? ['', ink.muted('  input'), ...String(approval.toolInput).split('\n').map((line) => `  ${ink.text(line)}`)]
+        : []),
+      '',
+      ...permissionBanner(waiting.pending, width, ink, this.runner ?? {}).slice(2),
+    ];
+  }
+
+  /** The reader, drawn over the whole screen — see `readerFrame` in split.mjs. */
+  readerScreen(width, height) {
+    const ink = this.ink;
+    const meta = this.windows().find((each) => each.id === this.reader.runId)
+      ?? this.sessions.get(this.reader.runId) ?? { id: this.reader.runId };
+    const output = (this.lines.get(this.reader.runId) ?? []).map((line) => this.render(line));
+    const waiting = this.waitingOn(meta);
+    const request = this.requestLines(waiting, width - 2);
+    const n = this.windowNumberOf(meta.id);
+    const keys = waiting?.kind === 'permission'
+      ? 'y once · s session · n refuse'
+      : waiting?.asking?.yours ? 'a answer' : '';
+    const drawn = readerFrame(width, height, {
+      title: `${n ? `${n} ` : ''}${titleFor(meta, waiting ? `waiting for ${waiting.kind === 'question' ? 'an answer' : 'permission'}` : null)}`,
+      lines: [...output, ink.muted('─'.repeat(Math.min(40, width - 2))), ...request],
+      requestAt: output.length,
+      top: this.reader.top,
+      footer: keyList(['↑↓ scroll', 'PgUp/PgDn page', 'g/G top/end', 'esc close',
+        ...(keys ? [keys] : []), '/open on cawdev'], '', width - 2, ink),
+    }, ink);
+    Object.assign(this.reader, { top: drawn.top, max: drawn.max, room: drawn.room });
+    return drawn.lines;
+  }
+
+  /** Keys while the reader is open. */
+  onReaderKey(key) {
+    const reader = this.reader;
+    const move = (to) => {
+      reader.top = Math.min(Math.max(0, to), reader.max);
+      this.dirty = true;
+      return undefined;
+    };
+    const at = reader.top ?? 0;
+    switch (key) {
+      case `${ESC}[A`: case `${ESC}OA`: case 'k':
+        return move(at - 1);
+      case `${ESC}[B`: case `${ESC}OB`: case 'j':
+        return move(at + 1);
+      case `${ESC}[5~`: case 'b':
+        return move(at - reader.room);
+      case `${ESC}[6~`: case ' ':
+        return move(at + reader.room);
+      case `${ESC}[H`: case `${ESC}[1~`: case 'g':
+        return move(0);
+      case `${ESC}[F`: case `${ESC}[4~`: case 'G':
+        return move(reader.max);
+      case ESC: case 'q':
+        this.reader = null;
+        this.dirty = true;
+        return this.note('');
+      default:
+        // Anything else is what it always is — `a` answers, `y`/`n` decide,
+        // `/` a command — with the reader closed first.
+        this.reader = null;
+        this.dirty = true;
+        return this.onKey(key);
+    }
+  }
+
   /**
    * `/view` alone — the focused session's page on cawdev (its transcript,
    * stages, card and checkout). On the console this terminal signed in to:

package/runner/runner.mjs

@@ -219,6 +219,10 @@ const DEFAULTS = {
     // and is not sure it deserves one. A writer, like issue_file: a read-only
     // stage is refused it by shape and not by this list.
     'mcp__cawdev__backlog_file',
+    // R368. Ticks one item of the card's Done-when checklist as built. A
+    // writer, like the three above: it is not in CAWDEV_READS, so a read-only
+    // stage is refused it by shape and not by this list.
+    'mcp__cawdev__done_when_tick',
     // R96's rounds. An interview is the one profile that cannot work without
     // these, and they were missing for the same reason as the two above.
     'mcp__cawdev__ask_group',
@@ -1632,6 +1636,59 @@ async function stashAfterCancel(config, run, cwd) {
  * request will target the wrong place with nothing saying so. With no
  * `baseBranch` every path here is byte for byte what it was before R260.
  */
+/** Read-only copies in use: path → how many sessions are reading in it. */
+const reading = new Map();
+
+/**
+ * Where a session with no branch reads the code — a plan, a verify, an ask.
+ *
+ * It takes no checkout (R70), so it used to run in the project's FIRST
+ * checkout as that checkout happened to be: on whatever branch the last run
+ * left there, however old — a cancelled CTO Interview left `cto-interview`
+ * checked out two hundred commits behind, and every plan after it read that
+ * code. Moving that checkout is not the answer: a coding run may be working
+ * in it this minute. So a session with no branch reads a copy of its own:
+ * `<first checkout>-read`, a DETACHED worktree of it — sharing its objects,
+ * touching neither its branch nor its tree — brought to origin's default
+ * branch whenever nobody is reading in it. One per project rather than one
+ * per run, because the CLI keys a resumable conversation on its directory
+ * (R69) and an ASK carried on in a different folder would start over.
+ * Detached, because `resetToOrigin` checks the default branch out in the
+ * checkout and git refuses a branch checked out twice. Anything failing here
+ * leaves the session where it always ran, and says why.
+ */
+async function readingCopy(source, defaultBranch) {
+  const main = defaultBranch || 'main';
+  const tip = `origin/${main}`;
+  const read = `${source.replace(/\/+$/, '')}-read`;
+  const inUse = reading.get(read) ?? 0;
+  try {
+    const there = await access(join(read, '.git')).then(() => true, () => false);
+    await git(source, ['fetch', '--quiet', 'origin', main]).catch(() => undefined);
+    if (!there) {
+      await git(source, ['worktree', 'prune']).catch(() => undefined);
+      await git(source, ['worktree', 'add', '--quiet', '--detach', read, tip]);
+    } else if (!inUse) {
+      await git(read, ['checkout', '--quiet', '--force', '--detach', tip]);
+    }
+    reading.set(read, inUse + 1);
+    const at = (await git(read, ['rev-parse', '--short', 'HEAD'])).trim();
+    return {
+      path: read,
+      said: inUse
+        ? `reading ${read} at ${at} — another session is reading there, so it was not moved`
+        : `reading ${tip} at ${at}, in ${read}`,
+      release: () => reading.set(read, Math.max(0, (reading.get(read) ?? 1) - 1)),
+    };
+  } catch (failure) {
+    return {
+      path: source,
+      said: `reading ${source} as it is — no reading copy: ${failure.message.split('\n')[0]}`,
+      release: () => undefined,
+    };
+  }
+}
+
 async function prepareWorkingCopy(path, branch, defaultBranch, allowDirty, baseBranch = null) {
   await access(join(path, '.git')).catch(() => {
     throw new Error(`${path} is not a git repository.`);
@@ -4492,6 +4549,63 @@ async function askGitHub(cwd, branch, prUrl) {
   };
 }
 
+/**
+ * What `gh` says about a hand-taken branch's pull request — R346.
+ *
+ * `pr list --head`, not `pr view <branch>`: the latter stops finding the pull
+ * request once the branch is deleted, and this matches on the pull request's own
+ * head branch name, which does not change. Fork pull requests are dropped: a
+ * fork's branch of the same name is not this branch.
+ *
+ * A merged pull request opened-after `openedAt` wins (latest merge first); a
+ * reused branch name can bring back an older one, which the platform also
+ * refuses. Otherwise the highest-numbered row speaks.
+ */
+async function askGitHubForBranch(cwd, branch, openedAt) {
+  if (!branch) {
+    return null;
+  }
+  const out = await new Promise((resolvePromise) => {
+    const child = spawn(
+      'gh',
+      ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '10', '--json',
+        'number,url,state,mergedAt,mergeCommit,baseRefName,headRefName,isCrossRepository'],
+      { cwd, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    let text = '';
+    child.stdout.on('data', (chunk) => (text += chunk));
+    child.on('error', () => resolvePromise(null));
+    child.on('close', (code) => resolvePromise(code === 0 ? text.trim() : null));
+  });
+  const parsed = out ? safeJson(out) : null;
+  if (!Array.isArray(parsed)) {
+    return null;
+  }
+  const own = parsed.filter((row) => row && !row.isCrossRepository && row.headRefName === branch);
+  if (!own.length) {
+    return null;
+  }
+  const since = openedAt ? Date.parse(openedAt) : Number.NEGATIVE_INFINITY;
+  const merged = own
+    .filter((row) => row.state === 'MERGED' && Date.parse(row.mergedAt) >= since)
+    .sort((a, b) => Date.parse(b.mergedAt) - Date.parse(a.mergedAt));
+  const chosen = merged[0] ?? [...own].sort((a, b) => b.number - a.number)[0];
+  if (chosen.state === 'MERGED' && !merged.length) {
+    return null; // Only a merge from before the item existed: not this item's.
+  }
+  const state = { OPEN: 'OPEN', MERGED: 'MERGED', CLOSED: 'CLOSED' }[chosen.state];
+  if (!state) {
+    return null;
+  }
+  return {
+    state,
+    prUrl: chosen.url ?? null,
+    mergeCommit: chosen.mergeCommit?.oid ?? null,
+    mergedAt: chosen.mergedAt ?? null,
+    baseRefName: chosen.baseRefName ?? null,
+  };
+}
+
 /**
  * Whether the run's head is on the default branch, for any remote at all.
  *
@@ -4609,13 +4723,18 @@ async function checkMerges(config) {
     log(`could not ask which branches to check: ${failure.message}`);
     return null;
   });
-  if (!pending?.length) {
-    return;
-  }
-
   // One fetch per project, not one per branch: twenty-five branches in one
   // repository are twenty-five questions about the same set of refs.
   const fetched = new Set();
+  if (pending?.length) {
+    await checkRunMerges(config, pending, fetched);
+  }
+  // R346: the hand-taken items, even when no run is pending.
+  await checkWorkItemMerges(config, fetched);
+}
+
+/** The run pass of `checkMerges`: one reading per pending run branch. */
+async function checkRunMerges(config, pending, fetched) {
   const readings = [];
 
   for (const branch of pending) {
@@ -4666,6 +4785,64 @@ async function checkMerges(config) {
   }
 }
 
+/**
+ * R346: the hand-taken items. A squash or rebase merge leaves no head on the
+ * default branch for the git reading to find, so ask `gh` about the pull
+ * request. An older platform answers 404 and this returns in silence.
+ */
+async function checkWorkItemMerges(config, fetched) {
+  const pending = await api(config, `/api/runners/${config.runnerId}/work-item-branches`)
+    .catch(() => null);
+  if (!Array.isArray(pending) || !pending.length) {
+    return;
+  }
+  const readings = [];
+  for (const item of pending) {
+    const project = config.projects[item.projectSlug];
+    if (!project) {
+      // Not ours, but say so: an UNKNOWN only stamps the platform's rotation,
+      // and silence would leave these rows first in the queue for ever.
+      readings.push({ workItemId: item.workItemId, state: 'UNKNOWN' });
+      continue;
+    }
+    const heldNow = heldWorkspaces();
+    const cwd = project.workspaces.find((candidate) => !heldNow.has(candidate))
+      ?? resolve(project.path);
+    try {
+      await access(join(cwd, '.git'));
+    } catch {
+      readings.push({ workItemId: item.workItemId, state: 'UNKNOWN' });
+      continue;
+    }
+    if (!fetched.has(cwd)) {
+      fetched.add(cwd);
+      await git(cwd, ['fetch', '--prune', 'origin']).catch(() => null);
+    }
+    const reading = await askGitHubForBranch(cwd, item.branch, item.openedAt).catch(() => null);
+    readings.push({
+      workItemId: item.workItemId,
+      state: reading?.state ?? 'UNKNOWN',
+      prUrl: reading?.prUrl ?? null,
+      mergeCommit: reading?.mergeCommit ?? null,
+      mergedAt: reading?.mergedAt ?? null,
+      baseRefName: reading?.baseRefName ?? null,
+    });
+  }
+  if (!readings.length) {
+    return;
+  }
+  const recorded = await api(config, `/api/runners/${config.runnerId}/work-item-merges`, {
+    method: 'POST',
+    body: { readings },
+  }).catch((failure) => {
+    log(`could not record what became of the hand-taken branches: ${failure.message}`);
+    return null;
+  });
+  if (recorded?.merged?.length) {
+    log(`${recorded.merged.length} hand-taken branch(es) have merged`);
+  }
+}
+
 /** Reads the run's history out of git and tells the platform. */
 async function reportCommits(config, run, cwd, base) {
   const commits = await readCommits(cwd, base).catch((failure) => {
@@ -5197,6 +5374,19 @@ function argsForProfile(agentArgs, profile, run, expertAgents = [], skills = [])
 /** Longer than ask_user's own ten-minute wait — see the cawdev server of spawnCodex. */
 const CAWDEV_TOOL_TIMEOUT_SEC = 660;
 
+/**
+ * R368. cawdev reads a plan's `**Done when:**` list into the card's review
+ * checklist, numbered in order, so a plan has to end in one that can be ticked.
+ */
+const DONE_WHEN_PLAN = 'End the plan with a `**Done when:**` list of `- [ ]` items, each one '
+  + 'condition somebody could check on its own — cawdev turns that list into the card\'s '
+  + 'review checklist, numbered in order.';
+
+/** R368. The other half: the session that builds it says which items it built. */
+const DONE_WHEN_TICK = 'When an item under the plan\'s **Done when** is built and you have '
+  + 'checked it, call `done_when_tick` with its number and one line of evidence. Do not tick '
+  + 'what you did not check.';
+
 /**
  * A decision that is the person's is ASKED, and the stage goes on with the
  * answer. R19 and R24 (Codex) each met one — a plan the code had moved away
@@ -5230,7 +5420,8 @@ function stagePrompt(stage, carried, hasPlan = true) {
       + 'concretely: which files, what change in each, and how you will know it worked. '
       + 'What you report becomes the card\'s plan, and a DIFFERENT session — another '
       + 'process, with none of your context — will be handed it and told to carry it out. '
-      + 'Write it for them — with every decision in it already made. ' + ASK_DONT_STOP,
+      + 'Write it for them — with every decision in it already made. ' + DONE_WHEN_PLAN + ' '
+      + ASK_DONT_STOP,
     VERIFY: 'Check the plan against what is actually there. Does every file it names exist? '
       + 'Does every interface it assumes still look like that? You cannot change anything — '
       + 'say what is wrong with the plan, or say plainly that it holds.',
@@ -5242,7 +5433,7 @@ function stagePrompt(stage, carried, hasPlan = true) {
       ? 'Do the work in the plan — it is under "The plan for this card" above, '
         + 'written by the plan phase and agreed. Do not quietly improvise a different change: '
         + 'somebody approved that plan. If it turns out to be wrong or incomplete, ask what to '
-        + 'do instead of stopping — and stop only if the answer is to stop. '
+        + 'do instead of stopping — and stop only if the answer is to stop. ' + DONE_WHEN_TICK + ' '
       : 'This card has no plan, and it does not need one: it was started straight into '
         + 'development, so the CARD\'s text is the task. Work out what it asks — read the code '
         + 'it touches first — build it, and commit it on this branch. Never stop because a plan '
@@ -5267,7 +5458,8 @@ function stagePrompt(stage, carried, hasPlan = true) {
         + 'is one call away — `quality_get`, which reads this run\'s branch by default; a red '
         + 'gate with new vulnerabilities is a finding to report with the output, not a failure '
         + 'to hide. ' + WAIT_FOR_COMMANDS + ' Then commit the branch\'s changes — no stage '
-        + 'after this one writes code, and work left uncommitted is work nothing can push.',
+        + 'after this one writes code, and work left uncommitted is work nothing can push. '
+        + DONE_WHEN_TICK,
     MEMORY: 'Write what the NEXT session on this branch needs to know: what was done, what was '
       + 'tried and rejected and why, and anything that turned out to matter and would not be '
       + 'obvious from the diff. Be brief and concrete. This is saved as this branch\'s '
@@ -5681,6 +5873,8 @@ card you created a moment ago. cawdev stores what you report as the card's plan
 record when this phase ends, and that is the only copy anybody wants: two plans in
 two places is how one of them goes stale.
 
+**End with a Done-when list.** ${DONE_WHEN_PLAN}
+
 Then \`report\` kind "done" with the plan itself.${asked}`;
   }
 
@@ -6395,13 +6589,22 @@ async function startRun(config, offered, workspace) {
     return;
   }
 
+  // Where the session runs: the checkout, or for a session with no branch
+  // the project's reading copy (`readingCopy`).
+  let cwd = path ? resolve(path) : path;
+  let reader = null;
   try {
     let branch = run.branch;
     if (!writesCodeProfile(run)) {
       // Nothing is prepared. It cuts no branch, and a dirty tree does not stop
       // it, because it is not going to write to one — refusing here would make
       // "what is R12 about?" unanswerable while somebody has edits open.
-      log(`  a ${run.profile.toLowerCase()} session: no branch, nothing prepared`);
+      log(`  a ${run.profile.toLowerCase()} session: no branch, nothing cut`);
+      if (path) {
+        reader = await readingCopy(resolve(path), defaultBranch);
+        cwd = reader.path;
+        log(`  ${reader.said}`);
+      }
     } else {
       // Cleared BEFORE the checkout, and never when somebody deliberately
       // started on top of their own uncommitted work — there the untracked
@@ -6439,7 +6642,7 @@ async function startRun(config, offered, workspace) {
         }).catch((failure) => log(`  could not report the merge: ${failure.message}`));
       }
     }
-    log(`  working copy ${path} is on ${branch}`);
+    log(`  working copy ${cwd ?? path} is on ${branch ?? 'no branch of its own'}`);
 
     await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/transition`, {
       method: 'POST',
@@ -6461,7 +6664,7 @@ async function startRun(config, offered, workspace) {
       return;
     }
 
-    const said = await walkLifecycle(config, run, runToken, resolve(path), baseCommit, workspace,
+    const said = await walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
         resume, mcpServers, expertAgents, skills, instincts, briefing, plan, lifecycle, shield);
 
     if (merge) {
@@ -6480,6 +6683,7 @@ async function startRun(config, offered, workspace) {
       body: { state: 'FAILED', summary: failure.message },
     }).catch((second) => log(`  could not record the failure: ${second.message}`));
   } finally {
+    reader?.release();
     running.delete(run.id);
     taken.delete(run.id);
     // The transcript of a run that is over is on the platform, where it belongs.

package/runner/split.mjs

@@ -168,6 +168,38 @@ export function tailOf(lines, width, rows) {
   return out.reverse();
 }
 
+/**
+ * The reader — `/view` on a session waiting for an answer or a permission.
+ *
+ * A window's body is the TAIL of what was said and a question's banner fits
+ * the prompt's rows, so a long plan or a long question was cut and could not
+ * be scrolled. The reader is one window over the whole screen, showing
+ * `lines` from row `top` (wrapped to its width), with where it is in the
+ * title. `top` null means "start where the request starts" (`requestAt`);
+ * whatever is asked for is clamped, and the answer says what was used so the
+ * keys can page from it.
+ */
+export function readerFrame(width, height, { title = '', lines = [], requestAt = 0, top = null, footer = '' }, ink) {
+  const inner = Math.max(1, width - 2);
+  const rows = [];
+  let requestRow = 0;
+  lines.forEach((line, i) => {
+    if (i === requestAt) requestRow = rows.length;
+    rows.push(...wrap(String(line ?? ''), inner));
+  });
+  const room = Math.max(1, height - 2 - (footer ? 1 : 0));
+  const max = Math.max(0, rows.length - room);
+  const at = Math.min(Math.max(0, top ?? requestRow), max);
+  const shown = rows.slice(at, at + room);
+  const where = rows.length > room ? ` · ${at + 1}–${at + shown.length} of ${rows.length}` : '';
+  return {
+    lines: windowLines({ width, height }, { title: `${title}${where}`, body: shown, footer, focused: true }, ink),
+    top: at,
+    max,
+    room,
+  };
+}
+
 /**
  * The whole screen, from placed pieces: `height` rows, each the pieces that
  * cross it laid left to right, and blank where nothing is.