cawdev-cli 1.0.8-beta → 1.0.10-beta

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.