breakaway 2.0.2-main.1 → 2.0.2-main.3

package/scripts/tasks.mjs

@@ -42,6 +42,7 @@ import {
 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';
@@ -87,6 +88,7 @@ import {
   staleCliWarning,
   releaseBehind,
   removedRepoByHand,
+  needsOwner,
   unknownSubcommand,
 } from './tasks/cli.js';
 import { InfraReadError, infraRead } from './tasks/infra-read.js';
@@ -111,6 +113,8 @@ import { cwdOf, parentOf, sessionDir } from './tasks/session-dir.js';
 import { parseInstall, secretName } from '../src/install.js';
 import {
   NAMES,
+  RUN_KEY,
+  authHeaders,
   boardUrl,
   configDir,
   parseEnvFile,
@@ -240,10 +244,11 @@ const HELP = `npx breakaway <command> [options]
 
 Reading                (list, next, claim, and add work in this checkout's repository; see Repositories below)
   list                   open tasks, best first (the default command)
-    --ready --blocked --active --mine --owner   narrow it down
+    --ready --blocked --active --mine   narrow it down
+    --who agent|person|decision --assignee <handle|owner>   who does it (--owner: decisions, and people's tasks for the owner or anyone)
     --project <p> --tag <t> --horizon <h> --status pending|completed|deleted|all
   show <ref>             one task: description, done when, related, comments, dependencies, and what it blocks
-  next                   the best ready task for an agent (+agent, not +decide, unclaimed)
+  next                   the best ready task for an agent (who: agent, unclaimed)
     --claim              …and claim it in the same step
     --project <p> --horizon <h> --tag <t>
   activity               recent changes, newest first  [--limit <n>]
@@ -253,7 +258,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>]
@@ -288,7 +293,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
@@ -303,13 +308,17 @@ Reading                (list, next, claim, and add work in this checkout's repos
 Working
   claim <ref>            take a task (atomic: fails if someone else has it)  [--force]
                          refuses another repository's task unless --repo names it
+  run-key <key>          a run on a routine the owner lends: save the Run key from its payload in tasks.env, so this
+                         CLI, its hooks, and mcp --headers send it in its own header (BRK-324). It's the run's only
+                         credential, with its person's rights, until its claim ends  [--forget] drops 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>]
+                         hold, or, as a chase's road captain, a task of your chase: 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
@@ -318,11 +327,13 @@ Working
   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
+    --who agent|person|decision   who does it: an agent builds it, a person does it, or the owner decides first
+    --assignee <handle|owner>   on a person's task, who it's for (without one, any member of the repository)
     --repo <slug>        the repository it belongs to (default: the checkout's; its areas decide the prefix)
     --depends <ref,…> --related <ref,…> --spec <path> --due <date> --wait <date>
     --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
+    --decision <file.json>   questions for the owner to answer on the board (makes it a decision); 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)
@@ -332,7 +343,15 @@ 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
@@ -364,6 +383,7 @@ Working
     --done-when <text>   change what has to be true to call it done
     --decision <file.json>   set the decision's questions (answers to questions that still exist are kept)
     --related <ref> --unrelated <ref>   add or remove a "see also" link (repeatable; it doesn't block)
+    --who agent|person|decision --assignee <handle|owner>   who does it (--assignee "" removes it)
     --tag <t> --untag <t> --depends <ref> --undepends <ref>   (repeatable)
     --autostart yes|no   start a cloud agent by itself when the task is ready
 
@@ -530,6 +550,7 @@ const REPEATABLE = new Set([
   'unrelated',
   'area',
   'remove-area',
+  'files',
 ]);
 const FLAGS = new Set([
   'json',
@@ -556,9 +577,13 @@ const FLAGS = new Set([
   'captain',
   'no-captain',
   'handover',
+  'anyway',
+  'forget',
 ]);
 /** 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 = [];
@@ -571,7 +596,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;
     }
@@ -597,14 +626,15 @@ function fail(message) {
  */
 async function call(method, path, body, { soft = false, raw = false } = {}) {
   // Without a token the request still goes out: in a Claude cloud environment with an API
-  // credential for this host, the agent proxy adds the Authorization header on the way.
+  // credential for this host, the agent proxy adds the Authorization header on the way. A lent run's key goes in its
+  // own header, which the proxy leaves alone (BRK-324).
   const token = setting('TOKEN');
   let res;
   try {
     res = await fetch(`${BASE}/api/${path}`, {
       method,
       headers: {
-        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...authHeaders(token, setting('RUN_KEY')),
         ...(body ? { 'Content-Type': 'application/json' } : {}),
       },
       body: body ? JSON.stringify(body) : undefined,
@@ -616,7 +646,7 @@ async function call(method, path, body, { soft = false, raw = false } = {}) {
     );
   }
   warnIfStale(res.headers.get('X-Tasks-Cli'), res.headers.get('X-Tasks-Release'));
-  if (res.status === 401 && !token)
+  if (res.status === 401 && !token && !setting('RUN_KEY'))
     fail(
       `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, set it in the breakaway plugin's settings, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
     );
@@ -688,7 +718,7 @@ async function upload(taskRef, file, alt = '') {
     res = await fetch(`${BASE}/api/tasks/${enc(taskRef)}/attachments`, {
       method: 'POST',
       headers: {
-        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...authHeaders(token, setting('RUN_KEY')),
         'Content-Type': 'application/octet-stream',
         'X-Attachment-Name': enc(basename(file)),
         'X-Attachment-Alt': enc(alt),
@@ -782,7 +812,7 @@ async function startSessionLog(t) {
   try {
     const res = await fetch(`${BASE}/api/tasks/${enc(t.uuid)}/session`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      headers: { 'Content-Type': 'application/json', ...authHeaders(token, setting('RUN_KEY')) },
       body: JSON.stringify({
         agent: t.claim,
         remote: process.env.CLAUDE_CODE_REMOTE === 'true',
@@ -844,14 +874,25 @@ function line(t) {
     t.description,
   ];
   const extra = [];
+  if (t.who) extra.push(t.who === 'person' ? `person: ${t.assignee ?? 'anyone'}` : t.who);
   if (t.tags.length) extra.push(t.tags.map((x) => `+${x}`).join(' '));
   if (t.claim) extra.push(`claimed by ${t.claim} ${age(t.start)}`);
-  if (t.blocked) extra.push(`blocked by ${t.blockedBy.length}`);
+  // A person's answer leaves out a blocker in a repository they can't read, but keeps the block (BRK-338).
+  if (t.blocked) extra.push(`blocked by ${t.blockedBy.length || 'a task you can’t see'}`);
   if (t.waiting) extra.push(`waiting until ${t.wait.slice(0, 10)}`);
   if (t.status !== 'pending') extra.push(`${t.status}${t.end ? ` ${t.end.slice(0, 10)}` : ''}`);
   return `${bits.join('  ')}${extra.length ? `  (${extra.join('; ')})` : ''}`;
 }
 
+/** Who does a task (BRK-330), in words: an agent, a person (its assignee, or any member), or a decision. */
+function whoWords(t) {
+  if (t.who === 'person')
+    return `a person: ${!t.assignee ? 'any member' : t.assignee === 'owner' ? 'the owner' : t.assignee}`;
+  if (t.who === 'agent') return 'an agent';
+  if (t.who === 'decision') return 'a decision first';
+  return 'nobody yet';
+}
+
 function detail(t) {
   const said = ownerSaidLines(t);
   const out = [`${ref(t)} · ${t.description}`, '', ...(said.length ? [...said, ''] : [])];
@@ -864,6 +905,7 @@ function detail(t) {
   row('Project', t.project);
   row('Horizon', t.horizon);
   row('Priority', t.priority);
+  row('Who', whoWords(t));
   row('Tags', t.tags.map((x) => `+${x}`).join(' '));
   row('Claimed by', t.claim && `${t.claim} (${age(t.start)} ago)`);
   row('Spec', t.spec);
@@ -1021,6 +1063,8 @@ function changesFrom(o) {
   for (const key of ['description', 'project', 'priority', 'horizon', 'spec', 'pr', 'due', 'wait', 'status'])
     if (key in o) c[key] = o[key];
   if (c.priority) c.priority = c.priority.toUpperCase();
+  if (o.who !== undefined) c.who = String(o.who).toLowerCase();
+  if (o.assignee !== undefined) c.assignee = o.assignee === true ? null : String(o.assignee).toLowerCase() || null;
   if (o.tag) c.addTags = o.tag;
   if (o.untag) c.removeTags = o.untag;
   Object.assign(
@@ -1070,7 +1114,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')}`);
@@ -1083,7 +1128,9 @@ const commands = {
         (!opts.blocked || t.blocked) &&
         (!opts.active || t.claim || t.active) &&
         (!opts.mine || t.claim === me) &&
-        (!opts.owner || t.tags.includes('owner') || t.tags.includes('decide')) &&
+        (!opts.owner || needsOwner(t)) &&
+        (!opts.who || t.who === String(opts.who).toLowerCase()) &&
+        (!opts.assignee || t.assignee === String(opts.assignee).toLowerCase()) &&
         (!opts.project || t.project === opts.project) &&
         // The archive is hidden from open work only: --status completed or all lists it too (CLD-193).
         (opts.horizon
@@ -1103,8 +1150,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
@@ -1224,11 +1309,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;
     }
@@ -1722,7 +1823,8 @@ const commands = {
     const body = { agent: agent(), claim: Boolean(opts.claim), project: opts.project, horizon: opts.horizon };
     const repo = await scopedRepo();
     if (repo) body.repo = repo;
-    if (opts.tag) body.tags = ['agent', ...opts.tag];
+    body.who = 'agent';
+    if (opts.tag) body.tags = opts.tag;
     const { task } = await call('POST', 'next', body);
     if (task && opts.claim) {
       markSession(task);
@@ -1924,6 +2026,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)}`, {
@@ -1931,13 +2034,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() {
@@ -1971,7 +2081,7 @@ const commands = {
       const token = setting('TOKEN');
       for (const image of attachments) {
         const res = await fetch(`${BASE}/api/attachments/${image.id}`, {
-          headers: token ? { Authorization: `Bearer ${token}` } : {},
+          headers: authHeaders(token, setting('RUN_KEY')),
         });
         if (!res.ok) fail(`couldn't download ${image.name} (HTTP ${res.status})`);
         const ext = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' }[image.type];
@@ -2128,15 +2238,17 @@ const commands = {
       }
       // Claude Code says which server it's connecting: the plugin's board_url, when the CLI's settings don't name one.
       const server = process.env.CLAUDE_CODE_MCP_SERVER_URL?.replace(/\/mcp\/?$/u, '');
+      const runKey = setting('RUN_KEY') ?? null;
       const repo = await headersRepo({
         base: BASE ?? (server?.startsWith('http') ? server : null),
         token,
+        runKey,
         named: opts.repo ?? setting('REPO'),
         remote,
         fetch,
       });
       // Standard output is Claude Code's, and only the headers go there: never --json's wrapping, never a line of text.
-      console.log(JSON.stringify(mcpHeaders({ token, named, agent: name, repo })));
+      console.log(JSON.stringify(mcpHeaders({ token, runKey, named, agent: name, repo })));
       return;
     }
     const tokenVar = envName('TOKEN');
@@ -2148,6 +2260,7 @@ const commands = {
     const checked = await checkMcp({
       endpoint: config.endpoint,
       token: setting('TOKEN'),
+      runKey: setting('RUN_KEY') ?? null,
       agent: name,
       repo: slug,
       fetch,
@@ -2155,6 +2268,37 @@ const commands = {
     print(checked, (c) => c.lines.join('\n'));
     if (!checked.ok) process.exitCode = 1;
   },
+  /**
+   * A lent run's key (BRK-324), saved in tasks.env (0600, outside the checkout) because the hooks don't share the
+   * agent's shell: an exported variable never reaches them. --forget drops it.
+   */
+  async 'run-key'() {
+    const name = envName('RUN_KEY');
+    const env = readEnvFile();
+    if (opts.forget) {
+      if (!(name in env)) return print({ forgotten: false }, () => `There's no run key in ${ENV_FILE}.`);
+      const { [name]: _gone, ...rest } = env;
+      writePrivate(`${ENV_FILE}.next`, envFile(rest));
+      renameSync(`${ENV_FILE}.next`, ENV_FILE);
+      return print({ forgotten: true }, () => `Dropped the run key from ${ENV_FILE}.`);
+    }
+    const key = String(need(args[0], 'run key')).trim();
+    if (!RUN_KEY.test(key))
+      fail('that isn’t a run key: copy the whole Run key line’s value from your payload (bkr_…).');
+    writePrivate(`${ENV_FILE}.next`, envFile({ ...env, [name]: key }));
+    renameSync(`${ENV_FILE}.next`, ENV_FILE);
+    process.env[name] = key;
+    const session = await call('GET', 'session', undefined, { raw: true });
+    if (!session.ok) fail(`saved, but the board refused it: ${session.data?.error ?? `HTTP ${session.status}`}`);
+    print({ saved: true, person: session.data.person ?? null }, (d) =>
+      [
+        `Saved the run key in ${ENV_FILE}. This CLI, its hooks, and mcp --headers send it from now on.`,
+        d.person ? `The board knows it: you act for ${d.person.name ?? d.person.handle}, with their rights.` : '',
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    );
+  },
   async health() {
     const settings = settingSources();
     print({ ...(await call('GET', 'health')), settings }, (h) =>

package/src/decision.js

@@ -228,8 +228,11 @@ function show(q, answer) {
   return String(value);
 }
 
-/** The plain comment the board adds when a decision is submitted. Nothing reads it back. */
-export function summarize(questions, answers) {
+/**
+ * The plain comment the board adds when a decision is submitted. Nothing reads it back. `by` is who answered
+ * (BRK-303): the owner, or the maintainer who did, by handle.
+ */
+export function summarize(questions, answers, by = 'owner') {
   const parts = questions.map((q) => {
     const answer = answers[q.id];
     const body = answer
@@ -237,11 +240,11 @@ export function summarize(questions, answers) {
       : 'no answer';
     return `${clip(text(q.prompt).replace(/\s+/gu, ' '), 60)} = ${body}`;
   });
-  return `Decided by the owner: ${parts.join('; ')}`;
+  return `Decided by ${!by || by === 'owner' ? 'the owner' : by}: ${parts.join('; ')}`;
 }
 
 /** Tags that aren't a feature's (IDEA-28 section 1): the board's own, horizons, and release tags. */
-const NOT_FEATURES = new Set(['agent', 'owner', 'decide', 'idea', 'general', 'version']);
+const NOT_FEATURES = new Set(['idea', 'general', 'version']);
 export const featureTags = (tags) =>
   (tags ?? []).filter((t) => !NOT_FEATURES.has(t) && !t.startsWith('horizon-') && !/^v\d/u.test(t));
 
@@ -267,18 +270,21 @@ const MAX_BRIEF = 10000;
  * agent that brings the work waiting for an answered decision in line with its answers. `decision` is the decision's
  * task (its `ref` is its work ID or short ID), `waiting` the open tasks that depend on it, and `note` the owner's,
  * which goes under the board's prompt. Returns the task's title and description.
- * @param {{ ref: string, description: string, spec?: string | null, questions: any[], answers: Record<string, any> }} decision
+ * `by` is who answered (BRK-303): the owner, or a maintainer's handle.
+ * @param {{ ref: string, description: string, spec?: string | null, questions: any[], answers: Record<string, any>,
+ *   by?: string | null }} decision
  * @param {{ ref: string, description: string, tags?: string[], spec?: string | null }[]} waiting
  * @param {string | null} [note]
  */
 export function refinePrompt(decision, waiting, note = null) {
+  const who = !decision.by || decision.by === 'owner' ? 'the owner' : decision.by;
   const title = clip(`Refine from the answers to ${decision.ref}: ${decision.description}`, 200);
   const questions = decision.questions.flatMap((q, i) => {
     const answer = decision.answers[q.id];
     return [
       `${i + 1}. ${q.prompt.trim()}`,
       `   Answer: ${spell(q, answer)}`,
-      ...(answer?.comment ? [`   The owner's note: ${answer.comment.trim()}`] : []),
+      ...(answer?.comment ? [`   ${who === 'the owner' ? 'The owner' : who}'s note: ${answer.comment.trim()}`] : []),
     ];
   });
   const specs = [...new Set([decision.spec, ...waiting.map((t) => t.spec)].filter(Boolean))];
@@ -296,7 +302,7 @@ export function refinePrompt(decision, waiting, note = null) {
     '- If nothing in the repository needs to change, comment what you changed on the board, task by task, and release your task.',
     ...(note && String(note).trim() ? ['', 'Note from the owner:', String(note).trim().slice(0, 4000)] : []),
   ];
-  const intro = `The owner answered the decision on ${decision.ref} (${decision.description}). Bring the work waiting for it in line with the answers.`;
+  const intro = `${who === 'the owner' ? 'The owner' : who} answered the decision on ${decision.ref} (${decision.description}). Bring the work waiting for it in line with the answers.`;
   const rest = [
     '',
     `Waiting for ${decision.ref}`,

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;
+}