breakaway 2.0.1 → 2.0.2-main.2

package/scripts/tasks.mjs

@@ -36,11 +36,13 @@ import {
   decisionField,
   proposalField,
   structureLines,
+  ownerSaidLines,
   textFields,
 } from './tasks/structure.js';
 import { looksLikeSecret } from '../src/ping.js';
 import { sessionReport, shortHash, stubText } from '../src/session-report.js';
 import { promptPathOf } from '../src/repos.js';
+import { claimLines, footprintLines } from '../src/footprint-text.js';
 import { hookFailure, sessionProxy, routeThroughSessionProxy } from './tasks/proxy.js';
 import { githubFromRemote, inRepo, pickRepo } from './tasks/repo.js';
 import { appInPlace } from './tasks/github-connect.js';
@@ -58,6 +60,8 @@ import {
   promptSections,
 } from './tasks/init.js';
 import {
+  captainLines,
+  captainRequest,
   chaseRequest,
   chaseSummary,
   featureBody,
@@ -79,6 +83,8 @@ import {
   pullAgentRequest,
   pullAgentSummary,
   reviewRequest,
+  riskAnswerRequest,
+  riskReviewRequest,
   staleCliWarning,
   releaseBehind,
   removedRepoByHand,
@@ -94,6 +100,8 @@ import {
   mergeViews,
   pelotonLines,
   pelotonPost,
+  openLines,
+  handoverComment,
   pickPeloton,
   pickPlanPeloton,
   planRevision,
@@ -246,7 +254,7 @@ Reading                (list, next, claim, and add work in this checkout's repos
   agents new --next minor|major ["<note>"]   start an agent that sets package.json to the next minor or major release; the board writes its prompt  [--repo <slug>] [--force] (owner)
   agents new --spec <path> "<what should change>"   start an agent that changes a spec as you ask and brings the tasks that
                          link it in line; the board writes its prompt  [--repo <slug>] [--force] (owner)
-  agents start <ref>     start a Claude cloud agent on a task  [--note <text>] [--force]
+  agents start <ref>     start a Claude cloud agent on a task; warns when a running agent changes its files  [--note <text>] [--force] [--anyway]
   agents refine <ref>    start an agent that improves a task, not builds it  --note <what to look at or change> [--force]
   agents plan [<plan>]   your Claude plan and what it allows; pro, max5, or max20 picks one (owner) and sets the limits to its defaults
   agents next            start the next few ready tasks, one per area  [--count <n>] [--dry-run] [--repo <slug>]
@@ -259,8 +267,16 @@ Reading                (list, next, claim, and add work in this checkout's repos
   chase <slug>           start a chase (owner): the board starts an agent on every ready task in the feature and on
                          what blocks it, within its limits, until all are done or in review
     --parallel <n>       the most agents at once in one area (default 3); on a running chase, it changes it
+    --review-cap <n>     the most of its pull requests that wait for you before it starts nothing new but fixes
+                         (default 5, from 1 to 50); on a running chase, it changes it
     --dry-run            show what would start now, and start nothing
+    --captain, --no-captain   start a road captain with it, or not (by default, one for more than 10 tasks); on a
+                         running chase, start or stand down its captain
+    --watch <hours>      a road captain's watch before the board starts a fresh one (default 12)
   chase <slug> stop      stop it (owner): nothing new starts; running agents finish
+  captain <slug>         the chase's road captain: who it is, when its watch ends, and its log
+  captain <slug> log --file <path>   the road captain writes its log  [--handover] then the board starts the next one
+  captain <slug> digest --file <path>   the road captain's lines for the owner's next hourly digest of the chase
   horizon close          close now: finished tasks go to the archive, next becomes now, later becomes next  [--dry-run]
   github fix <n>         start an agent on a pull request's conflicts, failing checks, or review comments (owner)  [--problem conflicts|failing|review] [--note <text>] [--repo <slug>] [--force]
   github review <n>      start an agent that reviews a pull request that can merge as it stands, on the task it closes, as
@@ -273,7 +289,7 @@ Reading                (list, next, claim, and add work in this checkout's repos
   specs                  the repository's specs, newest first: each one's status and its tasks  [--repo <slug>]
   specs show <path>      one spec: its status, last change, Markdown, and the tasks that link it  [--repo <slug>]
   github                 the checkout's repository on GitHub: open pull requests, checks, reviews, CI, deploys, alerts  [--sync] [--repo <slug>]
-  hook session|wait      the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
+  hook session|wait|edit the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
   health                 the server's state
   mcp                    print the claude mcp add line and the .mcp.json entry that connect an MCP client to the board's
                          /mcp from this checkout, with the token as $BREAKAWAY_TOKEN, never its value. Writes nothing
@@ -281,6 +297,8 @@ Reading                (list, next, claim, and add work in this checkout's repos
     --headers            …or print the headers Claude Code sends to /mcp as JSON, the token included: the plugin's
                          headersHelper. Only Authorization outside a repository the board tracks
   export                 every task (all repositories, statuses, and horizons) as JSON, checked against health's count  [--out <file>]
+  import <file>          restore an export into an empty board: every task with its work ID and comments, claims cleared
+                         (owner). Refused on a board that has tasks; register the export's repositories first
   connections            is everything the board leans on wired up: GitHub, Cloudflare, Claude, sync, push; the fix for each that isn't
 
 Working
@@ -288,8 +306,16 @@ Working
                          refuses another repository's task unless --repo names it
   release <ref>          give it back  [--force]
   comment <ref> <text>   add a comment (signed with your agent name); note is the same command
+  quote <ref> <words> --from <source>   put the owner's exact words on a task you hold, quoted and marked as yours:
+                         shown first on the task and to every agent that claims it. <source> is where they said it:
+                         message, peloton, ping, decision, or comment, with a pointer if you have one ("peloton #12")
   review <ref> --verdict ready|follow-up|changes <note>   your review of the pull request that closes the task you
                          hold: a comment on it, and the review on the pull request's page (the note is Markdown)  [--pr <n>]
+  risk-review <ref> --file <findings.json>   a risky-path reviewer's findings on the pull request the board started it
+                         for: { "summary", "findings": [{ "severity": "blocking"|"note", "text", "path", "line" }] }
+                         [--pr <n>]; without --file, the task's reviews and their answers
+  risk-answer <ref> <finding> <text>   answer a finding of the review on your pull request: what you changed, or
+                         why it's safe; a blocking one holds Merge when green until you do  [--pr <n>]
   done <ref>             finish it  [--note <text>] [--pr <url>]
   add <description>      new task; gets the next work ID for its project
     --project <p> --tag <t>… --priority H|M|L --horizon now|next|later
@@ -298,6 +324,7 @@ Working
     --brief <text> | --brief-file <path>   the description (--note is the same)
     --done-when <text>   what has to be true to call it done
     --decision <file.json>   questions for the owner to answer on the board (adds +decide); see decision --template
+    --force              add it even though it resembles open tasks the board named (--related links them instead)
   decision <ref> --template   print an example decision file to edit (nothing here answers a decision: the owner does, on the board)
   ping <ref> <message>   tell the owner you need them, in the inbox and as a push (you must hold the task; only when they must act)
     --kind blocked|question|stale|done|fyi   blocked: needs the owner; question: a small question; stale: can't reproduce or already fine; done: looks finished; fyi: inbox only
@@ -306,11 +333,23 @@ Working
   peloton                who else is working (in your repository, and your chase's), the chase's plan and open
                          huddle, and what they posted since you last read: new posts are starred  [--all] every post
   peloton checkin <text> say you're here and what you'll change, the files or areas you'll touch, before your first
-                         change (you must hold a task); posts on your repository's peloton and your chase's too
+                         change (you must hold a task); posts on your repository's peloton and your chase's too,
+                         and claims the paths it names  [--files <pattern,…>] claims these instead
+  paths <ref>            what a task touches: predicted, claimed (and when each claim runs out), changed, or in its
+                         pull request, and the shared files left out
+  paths <ref> --claim <pattern>…   claim a file, a folder/, or a glob (src/**, test/*.test.js) for the task you
+                         hold before you change it; one another task claims is refused, with who holds it. Claims
+                         run out 10 minutes after your session goes quiet, and after 4 hours
+  paths <ref> --release [<pattern>…]   give your claims back (all of them without patterns); the owner, with no
+                         agent name, releases anyone's
   peloton step|note|ask|propose|review <text>   say what you did, talk, ask, propose a change to the plan or the
                          tasks, or ask for a look at your approach; posts on your chase's peloton if your task is in
                          one, else your repository's  [--peloton <name>] picks one
   peloton reply <post> <text>   answer a post, on the peloton it's on
+  peloton open           the posts to you that you haven't answered or handed over: answer or hand over each before
+                         you release your task or stop after its pull request merges  [--task <ref>]
+  peloton handover <post> <text>   hand a post over: a comment on your task naming who or which task follows it up
+                         (works after you've left, too)  [--task <ref>]
   peloton huddle <question>     call a huddle on your chase's peloton: every agent stops to talk one thing through
   peloton in <huddle> [<text>]  join the open huddle (or say why not now)
   peloton outcome <huddle> <text>   close the huddle you called with what was agreed, and who does what
@@ -319,7 +358,8 @@ Working
   peloton listen         wait for what's for you, in the foreground, instead of stopping: returns at once on an urgent
                          post, a message, or a change to your pull request, gathers other posts for 30 seconds, and
                          returns after 9 minutes with nothing; then run it again, unless it says to stop
-                         [--for <minutes>] up to 9  [--task <ref>] the task you listen on, when you hold more than one
+                         [--for <minutes>|<seconds>s] from 10 seconds up to 9 minutes (2, 30s)  [--task <ref>] the
+                         task you listen on, when you hold more than one
   idea <text>            write down an idea for an agent to shape into tasks and a spec (area Ideas, IDEA-n)
     --horizon now|next|later|auto   the horizon for the tasks it makes (default auto: the agent chooses)
     --auto               start its agent by itself when there's room (your choice; off by default here)
@@ -499,6 +539,7 @@ const REPEATABLE = new Set([
   'unrelated',
   'area',
   'remove-area',
+  'files',
 ]);
 const FLAGS = new Set([
   'json',
@@ -522,9 +563,15 @@ const FLAGS = new Set([
   'check',
   'headers',
   'days',
+  'captain',
+  'no-captain',
+  'handover',
+  'anyway',
 ]);
 /** Flags only in repos init (BRK-91): --pipeline takes a file in repos modify, and is a flag there. */
 const INIT_FLAGS = new Set(['pipeline', 'copies']);
+/** Flags only in paths (IDEA-55): the patterns follow the task, and --release takes a version elsewhere. */
+const PATHS_FLAGS = new Set(['claim', 'release']);
 
 function parse(argv) {
   const positional = [];
@@ -537,7 +584,11 @@ function parse(argv) {
       continue;
     }
     const [name, inline] = arg.slice(2).split(/=(.*)/su);
-    if (FLAGS.has(name) || (INIT_FLAGS.has(name) && positional[0] === 'repos' && positional[1] === 'init')) {
+    if (
+      FLAGS.has(name) ||
+      (INIT_FLAGS.has(name) && positional[0] === 'repos' && positional[1] === 'init') ||
+      (PATHS_FLAGS.has(name) && positional[0] === 'paths')
+    ) {
       opts[name] = true;
       continue;
     }
@@ -819,7 +870,8 @@ function line(t) {
 }
 
 function detail(t) {
-  const out = [`${ref(t)} · ${t.description}`, ''];
+  const said = ownerSaidLines(t);
+  const out = [`${ref(t)} · ${t.description}`, '', ...(said.length ? [...said, ''] : [])];
   const row = (k, v) => v && out.push(`  ${k.padEnd(11)} ${v}`);
   const inReview = t.status === 'pending' && (t.github ?? []).some((p) => p.closes && p.state === 'open');
   row(
@@ -878,7 +930,8 @@ function print(data, human) {
 // ---- commands ----------------------------------------------------------------------------
 
 /** A board from before a route answers 404 with "no route for …", or reads `listen` as a peloton's name. */
-const noRoute = (res) => res.status === 404 && /^no route for|no peloton "listen"/u.test(String(res.data?.error ?? ''));
+const noRoute = (res) =>
+  res.status === 404 && /^no route for|no peloton "(?:listen|open)"/u.test(String(res.data?.error ?? ''));
 
 /**
  * `peloton listen`: waits for what's for the agent (IDEA-36 section 3), asking the board every 5 seconds, and prints
@@ -904,6 +957,39 @@ async function pelotonListen(me) {
   print(heard, listenText);
 }
 
+/** The posts to the agent it hasn't answered or handed over (BRK-281), from the board; null on a board without them. */
+async function openPosts(me) {
+  const path = `peloton/open?agent=${enc(me)}${opts.task ? `&task=${enc(opts.task)}` : ''}`;
+  const res = await call('GET', path, undefined, { raw: true });
+  if (noRoute(res)) return null;
+  if (!res.ok) fail(res.data?.error ?? `HTTP ${res.status}`);
+  return res.data;
+}
+
+/** `peloton open`: what's still to answer or hand over before the agent leaves its task (BRK-281). */
+async function pelotonOpen(me) {
+  const open = await openPosts(me);
+  if (!open) fail('this board doesn’t list open posts yet: it runs an older release');
+  print(open, (d) =>
+    d.posts.length
+      ? openLines(d.posts, d.task)
+      : `Nothing to you is unanswered on the peloton${d.task ? ` for ${d.task}` : ''}.`,
+  );
+}
+
+/** `peloton handover <post> <text>`: a comment on the agent's task naming who follows the post up (BRK-281). */
+async function pelotonHandover(me) {
+  const open = await openPosts(me);
+  const id = /^#?(\d+)$/u.exec(String(args[1] ?? ''))?.[1];
+  const post = open?.posts.find((p) => String(p.id) === id) ?? null;
+  const built = handoverComment(args.slice(1), post);
+  if ('error' in built) return fail(built.error);
+  const task = opts.task ?? open?.task;
+  if (!task) fail('say which task it’s on: --task <ref>');
+  const out = await call('POST', `tasks/${enc(task)}/annotate`, { text: built.text, by: me });
+  print(out.task, (t) => `Handed over #${built.post} on ${ref(t)}.`);
+}
+
 /** `peloton plan` prints the chase's plan; with `--file <path> --why <text>`, it revises it (IDEA-36 section 5). */
 async function pelotonPlan(me) {
   if (args.length > 1)
@@ -1001,7 +1087,8 @@ function describeSources({ url, token, agent: name }) {
 const commands = {
   /** The Claude Code session hooks (BRK-7), so a repository's .claude/settings.json runs them through npx. */
   async hook() {
-    await import(args[0] === 'wait' ? './tasks/message-wait.mjs' : './tasks/session-hook.mjs');
+    const file = { wait: 'message-wait', edit: 'edit-hook' }[args[0]] ?? 'session-hook';
+    await import(`./tasks/${file}.mjs`);
   },
   async list() {
     const { tasks } = await call('GET', `tasks?status=${enc(opts.status ?? 'pending')}`);
@@ -1034,8 +1121,46 @@ const commands = {
     );
   },
   async show() {
-    const { task } = await call('GET', `tasks/${enc(need(args[0], 'task'))}`);
-    print(task, detail);
+    const ref = enc(need(args[0], 'task'));
+    const { task } = await call('GET', `tasks/${ref}`);
+    // Its footprint (IDEA-55 section 5), where the board has them; an older board just leaves the section out.
+    const fp = opts.json ? null : await call('GET', `tasks/${ref}/footprint`, undefined, { soft: true });
+    print(task, (t) => [detail(t), ...(fp?.footprint ? ['', ...footprintLines(fp.footprint)] : [])].join('\n'));
+  },
+  /**
+   * A task's footprint and its path claims (IDEA-55 section 1a): with no flag, what it touches; --claim <patterns> for
+   * the task you hold (a refused one exits non-zero, saying who holds it); --release [<patterns>] gives yours back, or
+   * any as the owner (no agent name), and every one without patterns.
+   */
+  async paths() {
+    const ref = enc(need(args[0], 'task'));
+    const patterns = args
+      .slice(1)
+      .flatMap((p) => p.split(','))
+      .map((p) => p.trim())
+      .filter(Boolean);
+    if (opts.claim && opts.release) fail('claim or release, not both at once');
+    if (!opts.claim && !opts.release) {
+      const { footprint } = await call('GET', `tasks/${ref}/footprint`);
+      return print(footprint, (fp) => footprintLines(fp).join('\n'));
+    }
+    if (opts.claim && !patterns.length)
+      fail('say which paths: npx breakaway paths <task> --claim <file, folder/, or glob> …');
+    const name = opts.as ?? setting('AGENT', null);
+    const res = await call(
+      'POST',
+      `tasks/${ref}/paths`,
+      opts.claim
+        ? { agent: agent(), claim: patterns }
+        : { ...(name ? { agent: name } : {}), release: patterns.length ? patterns : true },
+      { raw: true },
+    );
+    if (!res.ok && res.status !== 409) {
+      if (opts.json) console.log(JSON.stringify({ status: res.status, ...res.data }, null, 2));
+      fail(res.data.error ?? `HTTP ${res.status}`);
+    }
+    print(res.data, (d) => claimLines(d).join('\n'));
+    if (res.status === 409) process.exit(1);
   },
   /**
    * Every task on the board, in every repository, status, and horizon, as the board's JSON, checked against the
@@ -1053,6 +1178,30 @@ const commands = {
       );
     console.error(`Exported all ${tasks.length} tasks${opts.out ? ` to ${opts.out}` : ''}; the board has ${total}.`);
   },
+  /**
+   * Restores what export wrote into an empty board (BRK-234): the owner's, so an agent's name is sent and refused.
+   * The board keeps each task's UUID, work ID, and comments, and clears claims and autostart.
+   */
+  async import() {
+    const file = need(args[0], 'file');
+    let data;
+    try {
+      data = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (error) {
+      fail(`couldn't read ${file} as an export (${error.message}): it's the file npx breakaway export --out wrote`);
+    }
+    const signer = opts.as ?? setting('AGENT');
+    const r = await call('POST', 'import', {
+      tasks: data?.tasks,
+      count: data?.count,
+      ...(signer ? { by: signer } : {}),
+    });
+    print(
+      r,
+      (d) =>
+        `Restored ${d.imported} tasks with ${d.comments} comments; the board has ${d.total}.${d.cleared ? ` Cleared the claim or autostart on ${d.cleared}: start agents again from the board.` : ''}`,
+    );
+  },
   async agents() {
     const sub = args[0];
     if (sub === 'next') {
@@ -1131,11 +1280,27 @@ const commands = {
       return;
     }
     if (sub === 'start') {
-      const { task, run } = await call('POST', 'agents/start', {
-        ref: need(args[1], 'task'),
-        note: opts.note,
-        ...forceFields(opts.force, opts.as ?? setting('AGENT')),
-      });
+      const answer = await call(
+        'POST',
+        'agents/start',
+        {
+          ref: need(args[1], 'task'),
+          note: opts.note,
+          ...(opts.anyway ? { anyway: true } : {}),
+          ...forceFields(opts.force, opts.as ?? setting('AGENT')),
+        },
+        { raw: true },
+      );
+      if (!answer.ok) {
+        if (opts.json) console.log(JSON.stringify({ status: answer.status, ...answer.data }, null, 2));
+        // A footprint's overlap is a warning (IDEA-55 section 3): the owner decides, knowing.
+        fail(
+          answer.data?.overlap
+            ? `${answer.data.error}. Start it anyway: npx breakaway agents start ${args[1]} --anyway`
+            : (answer.data?.error ?? `HTTP ${answer.status}`),
+        );
+      }
+      const { task, run } = answer.data;
       print({ task, run }, () => `Started an agent on ${task.wid ?? task.short}: ${run.url}`);
       return;
     }
@@ -1579,8 +1744,11 @@ const commands = {
   async chase() {
     const built = chaseRequest(args[0], args[1], {
       parallel: opts.parallel,
+      reviewCap: opts['review-cap'],
       dryRun: Boolean(opts['dry-run']),
       by: opts.as ?? setting('AGENT'),
+      captain: opts['no-captain'] ? false : opts.captain ? true : undefined,
+      watch: opts.watch,
     });
     if (built.error) fail(built.error);
     const answer = await call(...built.request);
@@ -1591,6 +1759,37 @@ const commands = {
       }),
     );
   },
+  /** The chase's road captain and its log; the captain writes its log, and hands over, with `log` (BRK-275). */
+  async captain() {
+    let text = null;
+    if (opts.file !== undefined) {
+      try {
+        text = readFileSync(opts.file, 'utf8');
+      } catch (error) {
+        fail(`can't read ${opts.file}: ${reasonOf(error)}`);
+      }
+    }
+    const built = captainRequest(args[0], args[1], {
+      text,
+      handover: Boolean(opts.handover),
+      by: opts.as ?? setting('AGENT'),
+    });
+    if (built.error) fail(built.error);
+    const answer = await call(...built.request);
+    if (args[1] === undefined)
+      return print(answer.feature?.chase?.captain ?? null, (c) =>
+        [`${answer.feature.title} (${answer.feature.slug})`, ...captainLines(c, { all: true })].join('\n'),
+      );
+    if (args[1] === 'digest')
+      return print(answer, (d) => `Kept for the owner’s next digest, due ${d.digest.nextAt.slice(11, 16)} UTC.`);
+    print(answer, (d) =>
+      d.successor
+        ? `Logged and handed over: ${d.successor.agent} starts as the road captain and reads your log first. Stop here.`
+        : d.waiting
+          ? `Logged and handed over. The next captain waits to start: ${d.waiting}. Stop here.`
+          : 'Logged.',
+    );
+  },
   async next() {
     const body = { agent: agent(), claim: Boolean(opts.claim), project: opts.project, horizon: opts.horizon };
     const repo = await scopedRepo();
@@ -1617,15 +1816,24 @@ const commands = {
     });
     markSession(task);
     await startSessionLog(task);
-    print(task, (t) => `Claimed ${ref(t)} as ${t.claim}: ${t.description}`);
+    // The owner's words go to every agent that claims the task, before the description (BRK-284).
+    print(task, (t) =>
+      [
+        `Claimed ${ref(t)} as ${t.claim}: ${t.description}`,
+        ...(t.ownerSaid?.length ? ['', ...ownerSaidLines(t)] : []),
+      ].join('\n'),
+    );
   },
   async release() {
-    const { task } = await call('POST', `tasks/${enc(need(args[0], 'task'))}/release`, {
+    const released = await call('POST', `tasks/${enc(need(args[0], 'task'))}/release`, {
       agent: agent(),
       force: Boolean(opts.force),
     });
+    const { task, open = [] } = released;
     unmarkSession(task);
-    print(task, (t) => `Released ${ref(t)}.`);
+    print({ ...task, open }, (t) =>
+      [`Released ${ref(t)}.`, openLines(open, ref(t), { released: true })].filter(Boolean).join('\n\n'),
+    );
   },
   async review() {
     const built = reviewRequest(args[0], opts.verdict, args.slice(1).join(' '), { by: agent(), pr: opts.pr });
@@ -1633,6 +1841,48 @@ const commands = {
     const { review, task } = await call(...built.request);
     print({ review, task }, (r) => `Left your review of #${r.review.pr} on ${ref(r.task)}: ${r.review.label}.`);
   },
+  async 'risk-review'() {
+    let text = null;
+    if (typeof opts.file === 'string') {
+      try {
+        text = readFileSync(opts.file, 'utf8');
+      } catch (error) {
+        fail(`couldn’t read ${opts.file}: ${error.message}`);
+      }
+    }
+    const built = riskReviewRequest(args[0], text, { by: agent(), pr: opts.pr });
+    if (built.error || !built.request) fail(built.error ?? 'bad request');
+    const out = await call(...built.request);
+    if (text === null)
+      return print(out, (r) =>
+        r.reviews.length
+          ? r.reviews
+              .map(
+                (v) =>
+                  `#${v.pr} ${v.state}${v.hold ? ` (holds Merge when green: ${v.hold})` : ''}${v.summary ? `\n  ${v.summary}` : ''}${v.findings
+                    .map((f) => {
+                      const a = v.answers.find((x) => x.finding === f.n);
+                      return `\n  ${f.n}. ${f.severity}${f.path ? ` ${f.path}${f.line ? `:${f.line}` : ''}` : ''}: ${f.text}${a ? `\n     answered by ${a.by}: ${a.text}` : ''}`;
+                    })
+                    .join('')}`,
+              )
+              .join('\n')
+          : 'No risky-path review on its pull requests.',
+      );
+    print(out, (r) =>
+      r.review.hold
+        ? `Posted your review of ${r.review.task}'s pull request: ${r.review.hold}.`
+        : `Posted your review of ${r.review.task}'s pull request: nothing holds it.`,
+    );
+  },
+  async 'risk-answer'() {
+    const built = riskAnswerRequest(args[0], args[1], args.slice(2).join(' '), { by: agent(), pr: opts.pr });
+    if (built.error || !built.request) fail(built.error ?? 'bad request');
+    const out = await call(...built.request);
+    print(out, (r) =>
+      r.review.hold ? `Answered. Still held: ${r.review.hold}.` : 'Answered. Nothing holds Merge when green now.',
+    );
+  },
   // The board's `annotate` route is the comments route's alias; using it keeps this working on a board that hasn't deployed /comments yet.
   async comment() {
     const text = args.slice(1).join(' ');
@@ -1640,6 +1890,20 @@ const commands = {
     const { task } = await call('POST', `tasks/${enc(need(args[0], 'task'))}/annotate`, { text, by: agent() });
     print(task, (t) => `Commented on ${ref(t)}.`);
   },
+  /** Quotes the owner's words on a task you hold (BRK-284), with where they came from. */
+  async quote() {
+    const text = args.slice(1).join(' ').trim();
+    if (!text || !opts.from)
+      fail(
+        `say what the owner said and where: npx breakaway quote <task> "<their words>" --from message|peloton|ping|decision|comment[ <pointer>]`,
+      );
+    const { task } = await call('POST', `tasks/${enc(need(args[0], 'task'))}/said`, {
+      text,
+      from: opts.from,
+      by: agent(),
+    });
+    print(task, (t) => `Quoted the owner on ${ref(t)}: every agent that picks it up reads it first.`);
+  },
   async done() {
     const id = need(args[0], 'task');
     if (opts.pr) await call('PATCH', `tasks/${enc(id)}`, { pr: opts.pr });
@@ -1660,7 +1924,24 @@ const commands = {
     delete body.addDepends;
     delete body.addRelated;
     delete body.removeRelated;
-    const { tasks } = await call('POST', 'tasks', body);
+    if (opts.force) body.force = true;
+    const res = await call('POST', 'tasks', body, { raw: true });
+    // An open task it resembles comes back as a list (BRK-283): say which, and the two ways on.
+    if (res.status === 409 && Array.isArray(res.data.similar)) {
+      if (opts.json) console.log(JSON.stringify({ status: 409, ...res.data }, null, 2));
+      const lines = res.data.similar.map(
+        (t) => `  ${t.wid ?? t.short} ${t.description}${t.claim ? ` (claimed by ${t.claim})` : ''}`,
+      );
+      const ids = res.data.similar.map((t) => t.wid ?? t.short).join(',');
+      fail(
+        `not added: it resembles open tasks\n${lines.join('\n')}\nIf it's one of them, comment there instead. Otherwise add it again with --related ${ids} to link them, or --force if they're unrelated.`,
+      );
+    }
+    if (!res.ok) {
+      if (opts.json) console.log(JSON.stringify({ status: res.status, ...res.data }, null, 2));
+      fail(res.data.error ?? `HTTP ${res.status}`);
+    }
+    const { tasks } = res.data;
     print(tasks[0], (t) => `Added ${ref(t)}: ${t.description}`);
   },
   async decision() {
@@ -1706,6 +1987,8 @@ const commands = {
     }
     if (args[0] === 'listen') return pelotonListen(me);
     if (args[0] === 'plan') return pelotonPlan(me);
+    if (args[0] === 'open') return pelotonOpen(me);
+    if (args[0] === 'handover') return pelotonHandover(me);
     const post = pelotonPost(args[0], args.slice(1));
     if ('error' in post) return fail(post.error);
     // Read first: it says which peloton the post goes to, and which posts were new before it.
@@ -1713,6 +1996,7 @@ const commands = {
     const to = pickPeloton(views, { ...post, chosen: opts.peloton, agent: me });
     if ('error' in to) return fail(to.error);
     const posted = [];
+    let claims = null;
     let after = views;
     for (const peloton of to.pelotons) {
       const out = await call('POST', `peloton/${enc(peloton)}`, {
@@ -1720,13 +2004,20 @@ const commands = {
         kind: post.kind,
         text: post.text,
         ...(post.kind === 'reply' ? { reply_to: post.replyTo } : {}),
+        // A check-in claims --files, or the paths its text names (IDEA-55 section 1a).
+        ...(post.kind === 'checkin' && opts.files?.length ? { files: opts.files } : {}),
       });
       posted.push(out.post);
+      if (out.paths) claims = out.paths;
       after = mergeViews(after, out.peloton);
     }
     const where = posted.map((p) => `#${p.id} on ${p.peloton}`).join(' and ');
-    print({ post: posted[0], posts: posted, pelotons: after }, () =>
-      [`Posted ${where}.`, pelotonLines(after, { agent: me, all: opts.all })].join('\n\n'),
+    print({ post: posted[0], posts: posted, pelotons: after, ...(claims ? { paths: claims } : {}) }, () =>
+      [
+        `Posted ${where}.`,
+        ...(claims ? [claimLines(claims).join('\n')] : []),
+        pelotonLines(after, { agent: me, all: opts.all }),
+      ].join('\n\n'),
     );
   },
   async idea() {

package/src/footprint-text.js

@@ -0,0 +1,93 @@
+/**
+ * A task's footprint in words (docs/specs/IDEA-55-footprints.md, section 5), the same for `tasks show`, `tasks paths`,
+ * and the MCP server's footprint read: each pattern marked predicted, claimed (with when it runs out), changed, or from
+ * the pull request, and the shared files left out. Pure, so the CLI ships it.
+ */
+
+/** @param {string} iso @param {number} now */
+function runsOut(iso, now) {
+  const minutes = Math.max(0, Math.round((Date.parse(iso) - now) / 60_000));
+  return minutes < 1 ? 'runs out now' : `runs out in ${minutes} min`;
+}
+
+/** @param {any} p one path of a footprint @param {number} now */
+function pathNote(p, now) {
+  if (p.state === 'claimed')
+    return `claimed by ${p.agent}${p.source === 'claim' ? '' : ` (${p.source})`}, ${runsOut(p.until, now)}`;
+  if (p.state === 'dirty') return 'changed, not claimed';
+  if (p.state === 'pull') return p.holds === false ? 'pull request, quiet over a day: holds nothing' : 'pull request';
+  return `predicted (${p.source})`;
+}
+
+const HEADS = {
+  unknown: 'unknown: nothing names a path yet, so it’s scheduled by its area',
+  predicted: 'predicted',
+  claimed: 'claimed',
+  actual: 'actual',
+};
+
+/**
+ * The Footprint section's lines, indented like `tasks show`'s other sections.
+ * @param {any} fp the footprint from GET /api/tasks/:id/footprint
+ * @param {number} [now]
+ * @returns {string[]}
+ */
+export function footprintLines(fp, now = Date.now()) {
+  const kind = /** @type {keyof typeof HEADS} */ (fp?.kind ?? 'unknown');
+  const out = [
+    `  Footprint (${HEADS[kind] ?? kind}${kind === 'predicted' && fp.trusted === false ? ', not trusted in this repository' : ''})`,
+  ];
+  const paths = fp?.paths ?? [];
+  const width = Math.min(48, Math.max(0, ...paths.map((/** @type {any} */ p) => p.pattern.length)));
+  for (const p of paths) out.push(`    ${p.pattern.padEnd(width)}  ${pathNote(p, now)}`);
+  if (fp?.pull) out.push(`    from #${fp.pull.number}${fp.pull.partial ? ' (more files than GitHub lists)' : ''}`);
+  for (const c of fp?.conflicts ?? [])
+    out.push(`    conflict: changed ${c.path}, which ${c.agent} claims on ${c.task} (${c.pattern})`);
+  if (fp?.shared?.length) out.push(`    left out, shared: ${fp.shared.join(', ')}`);
+  const rate = fp?.hitRate;
+  if (rate?.count)
+    out.push(
+      `    predictions here covered ${Math.round(rate.rate * 100)}% of the files the last ${rate.count} merged task${rate.count === 1 ? '' : 's'} changed`,
+    );
+  return out;
+}
+
+/**
+ * What a claim answered, in words: what was granted, already held, and refused, with who holds it.
+ * @param {{ granted?: { pattern: string, until: string }[], held?: string[], refused?: { pattern: string, holder: any }[],
+ *   released?: string[] }} result
+ * @param {number} [now]
+ */
+export function claimLines(result, now = Date.now()) {
+  const out = [];
+  for (const g of result.granted ?? [])
+    out.push(`Claimed ${g.pattern} (${runsOut(g.until, now)} without a heartbeat).`);
+  for (const pattern of result.held ?? []) out.push(`Already yours: ${pattern}.`);
+  for (const r of result.refused ?? [])
+    out.push(
+      `Refused ${r.pattern}: ${r.holder.agent} claims ${r.holder.pattern} on ${r.holder.task}, active ${new Date(r.holder.active).toISOString().slice(11, 16)} UTC. Change other files, ask @${r.holder.agent} on the peloton, or comment why and release your task.`,
+    );
+  if (result.released)
+    out.push(result.released.length ? `Released ${result.released.join(', ')}.` : 'Nothing to release.');
+  return out;
+}
+
+/** Riders and patterns a start payload names before "and n more" (section 4). */
+const BESIDE_RIDERS = 8;
+const BESIDE_PATTERNS = 6;
+
+/**
+ * The start payload's "Riding beside you" lines (section 4): one per agent already running in the repository, with
+ * what it's changing. None when nobody with a known footprint is.
+ * @param {{ task: string, agent: string, patterns: string[] }[] | null | undefined} riders
+ * @returns {string[]}
+ */
+export function besideLines(riders) {
+  const list = riders ?? [];
+  const lines = list.slice(0, BESIDE_RIDERS).map((r) => {
+    const more = r.patterns.length - BESIDE_PATTERNS;
+    return `Riding beside you: ${r.task} (${r.agent}) is changing ${r.patterns.slice(0, BESIDE_PATTERNS).join(', ')}${more > 0 ? ` and ${more} more` : ''}`;
+  });
+  if (list.length > BESIDE_RIDERS) lines.push(`Riding beside you: ${list.length - BESIDE_RIDERS} more agents`);
+  return lines;
+}