breakaway 1.0.2-main.2 → 1.0.2-main.20

package/README.md

@@ -171,7 +171,7 @@ pnpm interop    # checks sync against real Taskwarrior 3
 
 breakaway publishes releases and never deploys an install. Every install, the owner's included, deploys a release from its own repository, and this repository holds no Cloudflare credentials. Its website follows the latest stable release: the release moves the `site` branch, and Cloudflare deploys it ([`site/README.md`](https://github.com/TheAnarchoX/breakaway/blob/main/site/README.md#deploy-it)).
 
-- **Every merge to `main`**, once CI passes, publishes a GitHub pre-release `vX.Y.Z-main.N` on the `main` channel. It carries the bundle (`breakaway-bundle.tar.gz`: the Worker's files and the web app's `dist`), a `manifest.json` (version, channel, commit, `manual`, and the lowest version it updates from), and `SHA256SUMS`. The notes list the merged pull requests by title.
+- **Every merge to `main`**, once CI passes, publishes a GitHub pre-release `vX.Y.Z-main.N` on the `main` channel. It carries the bundle (`breakaway-bundle.tar.gz`: the Worker's files and the web app's `dist`), a `manifest.json` (version, channel, commit, `manual`, and the lowest version it updates from), its signature `manifest.json.sig` (Ed25519, made with a key only the release workflow holds; the public key is `src/release-key.js`), and `SHA256SUMS`. The notes list the merged pull requests by title.
 - **A stable release** `vX.Y.Z` is the owner's: they run the **Release** workflow with the pre-release to promote. The bundle is that pre-release's, unchanged, and the notes cover everything since the last stable.
 - **The CLI** is on npm as [`breakaway`](https://www.npmjs.com/package/breakaway), staged on npm by the same workflow, with provenance, and live once the owner approves it there with 2FA. npm's trusted publishing can't yet read the OIDC identity of a repository as new as this one ([npm/cli#9969](https://github.com/npm/cli/issues/9969)), so until it can, a token that can stage but never publish by itself stands in, in an environment only `main` can use. Every pre-release goes out under the `next` dist-tag, and a stable release as `latest`. `npx breakaway <command>` is `node scripts/tasks.mjs <command>`.
 - **A major release** is one where an install has to do something by hand: a config or binding change, a Durable Object class or migration, a route or cron. Its notes have a **Manual steps** section and its manifest says `manual: true`, which an install's deploy stops on. A change that needs it sets `manual` and `manualSteps` in `release.json`, and the pull request that ships the steps clears them. Data the Durable Object stores changes forward-only and additively, so an install can always go back one release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.0.2-main.2",
+  "version": "1.0.2-main.20",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/scripts/tasks/cli.js

@@ -7,6 +7,7 @@ import { CLI_PACKAGE } from './init.js';
 /** The subcommands each command knows. Without one, each lists or shows (horizon needs close). */
 export const SUBCOMMANDS = {
   agents: ['next', 'start', 'refine'],
+  github: ['fix', 'review'],
   repos: ['add', 'init', 'modify', 'remove', 'setup'],
   routines: ['add', 'modify', 'run', 'trigger', 'revoke', 'pause', 'resume'],
   horizon: ['close'],
@@ -18,7 +19,6 @@ export const NO_ARGUMENTS = new Set([
   'list',
   'next',
   'activity',
-  'github',
   'health',
   'connections',
   'export',
@@ -74,6 +74,45 @@ export function githubRequest(repo, { sync = false } = {}) {
   return ['GET', repo ? `github?repo=${encodeURIComponent(repo)}` : 'github', undefined];
 }
 
+/** What `github fix` accepts for --problem: the same three the pull request page offers. */
+export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
+
+/**
+ * The request behind `npx breakaway github fix <n>` and `github review <n>` (BRK-81): the pull request page's "Fix with an
+ * agent" and "Safe to merge?" buttons (`POST github/pulls/<n>/fix` and `/review`). It names the checkout's repository
+ * like `github` does. Returns an error message instead when the number or `problem` can't be right.
+ * @param {'fix' | 'review'} action
+ * @param {string | number | undefined} number
+ * @param {{ repo?: string | null, problem?: string, note?: string }} [options]
+ * @returns {{ error?: string, request?: [string, string, Record<string, string>] }}
+ */
+export function pullAgentRequest(action, number, { repo = null, problem, note } = {}) {
+  const n = String(number ?? '').replace(/^#/u, '');
+  if (!/^[1-9]\d{0,8}$/u.test(n)) return { error: `say which pull request: npx breakaway github ${action} <number>` };
+  if (problem !== undefined && action !== 'fix') return { error: '--problem is for github fix' };
+  if (problem !== undefined && !FIX_PROBLEMS.includes(problem))
+    return { error: `--problem is ${FIX_PROBLEMS.join(', ')}` };
+  const body = {
+    ...(repo ? { repo } : {}),
+    ...(problem ? { problem } : {}),
+    ...(typeof note === 'string' && note.trim() ? { note } : {}),
+  };
+  return { request: ['POST', `github/pulls/${n}/${action}`, body] };
+}
+
+/**
+ * What the CLI says about an answer to those requests: which task and agent took the pull request, or who already has it.
+ * @param {'fix' | 'review'} action
+ * @param {string | number} number
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, already?: string | null }} answer
+ */
+export function pullAgentSummary(action, number, { task, run, already }) {
+  const id = task.wid ?? task.short;
+  if (!run) return `${id} already has it: ${already}.`;
+  const what = action === 'fix' ? `fixing #${number}` : `testing #${number}`;
+  return `Started ${run.agent ? `${run.agent}, ` : 'an agent '}${what} on ${id}${run.url ? `: ${run.url}` : ''}`;
+}
+
 /**
  * The task an idea becomes (`npx breakaway idea`): its first line, kept short, as the title, and the whole text as its
  * description. Like `add`, it lands in the repository of the checkout it was written in (BRK-71): without one, the

package/scripts/tasks/hook-config.js

@@ -3,14 +3,32 @@
  * `tasks claim`) and where the board is, found the same way as the CLI (scripts/tasks/settings.js).
  * Each returns null/undefined rather than throwing when something's missing, because the hooks stay quiet.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { boardUrl, configDir, parseEnvFile, readSetting } from './settings.js';
 
-/** The project's root, as Claude Code gives it to hooks. */
-export function projectRoot() {
-  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+/** The git root of the current folder, or null outside a repository. */
+function gitRoot() {
+  try {
+    return (
+      execFileSync('git', ['rev-parse', '--show-toplevel'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The project's root: as Claude Code gives it to hooks, and where it doesn't (a cloud session can leave
+ * CLAUDE_PROJECT_DIR empty, BRK-88), the git root of the folder the hook runs in, where `tasks claim` marks the task.
+ */
+export function projectRoot(env = process.env, root = gitRoot, cwd = process.cwd()) {
+  return env.CLAUDE_PROJECT_DIR || root() || cwd;
 }
 
 /** A file's text, or null when it can't be read. */
@@ -55,3 +73,13 @@ export function boardConfig(root = projectRoot()) {
   const token = readSetting('TOKEN', { env: process.env, file });
   return { base: url, headers: token ? { Authorization: `Bearer ${token}` } : {} };
 }
+
+/** The board says this checkout's task isn't claimed by its agent any more: drop the marker so later calls post nothing (BRK-87). */
+export function dropClaim(claim, root = projectRoot()) {
+  try {
+    const marker = join(root, '.task-session');
+    if (JSON.parse(readFileSync(marker, 'utf8'))?.uuid === claim.uuid) rmSync(marker);
+  } catch {
+    /* already gone */
+  }
+}

package/scripts/tasks/init.js

@@ -14,10 +14,10 @@ const DEFAULT_DIR = '~/.config/breakaway';
 export { routinePrompt };
 
 /**
- * The CLI on npm (BRK-7), as a repository runs it: `npx breakaway`. Pinned to the `next` channel until the first stable
- * release exists; then this becomes the major (`breakaway@1`), so a breaking change never reaches a repository by itself.
+ * The CLI on npm (BRK-7), as a repository runs it: `npx breakaway`, pinned to the major (BRK-47), so a breaking change
+ * never reaches a repository by itself. It was the `next` channel until the first stable release.
  */
-export const CLI_PACKAGE = 'breakaway@next';
+export const CLI_PACKAGE = 'breakaway@1';
 /**
  * Where the CLI starts: the command, and the two session hooks. repos init no longer copies them (BRK-7): an old copy
  * is replaced by npx, and these still version the CLI and say which files an old copy holds.
@@ -49,6 +49,11 @@ const ADAPTED = ['taskrc', 'scripts/task', SKILL];
  * sit at the root, so the paths `read` takes are the board's; what is written keeps this folder.
  */
 const TARGET_DIR = 'tools/tasks/';
+/**
+ * The record of what repos init wrote into a repository (BRK-79): `--update` replaces a copied file only when it's
+ * listed here, or sits in TARGET_DIR, breakaway's own folder. Anything else at a path it copies to is the repository's.
+ */
+export const MANIFEST = `${TARGET_DIR}copied.json`;
 const GITIGNORE = ['.task/', '.task-session', '.env'];
 /** Pinned to LF so the shell scripts run on a checkout with core.autocrlf=true (BRK-41). */
 const GITATTRIBUTES = ['scripts/task text eol=lf', '.envrc text eol=lf'];
@@ -134,7 +139,10 @@ export function sessionHooks(pkg = CLI_PACKAGE) {
   };
 }
 
-/** settings.json with the session hooks' commands (either form) set to the current one; the rest is untouched. */
+/**
+ * settings.json with the session hooks' commands set to the current one, whichever form they had: the copy's, or npx
+ * with an earlier channel or version of the package (`breakaway@next` before BRK-47). The rest is untouched.
+ */
 export function rewireHooks(text) {
   let out = text;
   for (const name of ['session', 'wait'])
@@ -143,7 +151,28 @@ export function rewireHooks(text) {
       const now = JSON.stringify(hookCommand(name)).slice(1, -1);
       out = out.split(was).join(now);
     }
-  return out;
+  const current = (_, name) => JSON.stringify(hookCommand(name === 'message-wait' ? 'wait' : name)).slice(1, -1);
+  return (
+    out
+      .replace(/npx --yes breakaway(?:@[^\s"\\]+)? hook (session|wait)\b/gu, current)
+      // The old CLI copy's hook scripts, from before BRK-7, quoted or not (BRK-79): its copy is about to go.
+      .replace(
+        /node (\\")?(?:\$CLAUDE_PROJECT_DIR\/)?(?:tools\/tasks\/cli\/)?scripts\/tasks\/(session-hook|message-wait)\.mjs\1/gu,
+        (_, _q, name) => current(_, name === 'session-hook' ? 'session' : name),
+      )
+  );
+}
+
+/**
+ * The paths a repository's AGENTS.md says came from the board, in its "Copied files." bullet as any version of repos
+ * init wrote it; a folder ends in `/`. None when AGENTS.md is the repository's own (BRK-79).
+ */
+export function declaredCopies(agents) {
+  const line = String(agents ?? '')
+    .split('\n')
+    .find((l) => /^- \*\*Copied files\.\*\*/u.test(l));
+  if (!line) return [];
+  return [...line.split(/ come from \[/u)[0].matchAll(/`([^`]+)`/gu)].map((m) => m[1]);
 }
 
 /** A short SHA-256 of `paths` and their text: changes whenever one of them does. */
@@ -261,10 +290,20 @@ export function promptSections(given = {}) {
 }
 
 /** The `tasks` skill for another repository: links into the board's docs point at them on GitHub. */
-export function skillFor(text, board) {
-  return String(text)
+export function skillFor(text, board, repo = null) {
+  const linked = String(text)
     .replace(/\]\((?:\.\.\/)+((?:docs|tools)\/[^)]+)\)/gu, `](https://github.com/${board}/blob/main/$1)`)
     .replace(/\]\(((?:\.\.\/)+)prompts\//gu, ']($1tools/tasks/prompts/');
+  if (!repo) return linked;
+  // The skill is breakaway's own: in another repository it names that repository's work, areas, and prompt (BRK-79).
+  const prompt = promptPathOf(repo);
+  return linked
+    .replace(/breakaway's work is on the board/gu, "This repository's work is on the board")
+    .replace(/breakaway's areas: [^.\n]+\./gu, `This repository's areas: ${areaList(repo)}.`)
+    .replace(
+      /\[`prompts\/breakaway\.md`\]\(((?:\.\.\/)+)tools\/tasks\/prompts\/breakaway\.md\)/gu,
+      (_, up) => `[\`${prompt}\`](${up}${prompt})`,
+    );
 }
 
 /** A starter AGENTS.md: how this repository works with the board. The owner adds how to build here. */
@@ -273,9 +312,9 @@ export function agentsMd(repo, board, dir = DEFAULT_DIR) {
 
 <!-- Started by \`npx breakaway repos init\` (breakaway's task board). Add how to build here: setup, tests, style, and anything agents must never do. -->
 
-- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's copy: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.
+- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.
 - **Agents started by the board** follow [\`${promptPathOf(repo)}\`](${promptPathOf(repo)}), which starts with the board's core, \`tools/tasks/prompts/core.md\`.
-- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, and \`${SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
+- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, and \`${SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
 - **Taskwarrior** (optional): \`scripts/task\`, or plain \`task\` with direnv after \`direnv allow\`, uses the board with this checkout's own \`.task/\` database, in the \`${repo.slug}\` context. \`npx breakaway setup\` connects the machine once.
 - **Changes reach \`${repo.defaultBranch || 'main'}\` through pull requests**, which the owner merges. Never merge, force-push, or rewrite \`${repo.defaultBranch || 'main'}\`.
 - **Never put a secret or token** in a file, task, comment, or pull request. The board's token lives in \`${dir}/tasks.env\` (or \`$BREAKAWAY_HOME/tasks.env\`) or the cloud environment's credentials, never in this repository.
@@ -338,13 +377,46 @@ export function initPlan({
     if (readTarget(path) !== null) skipped.push(path);
     else files.push({ path, content, ...extra });
   };
-  /** A file copied from the board: added when it's missing, and with `update`, replaced when it differs. */
+  // What an earlier run recorded writing (BRK-79): null for a repository set up before the record existed.
+  const recorded = (() => {
+    try {
+      const files = JSON.parse(readTarget(MANIFEST) ?? 'null')?.files;
+      return Array.isArray(files) ? new Set(files) : null;
+    } catch {
+      return null;
+    }
+  })();
+  // Set up before the record: the AGENTS.md repos init wrote says the copied files came from the board, and a
+  // repository's own AGENTS.md doesn't, so only then are files at the copied paths breakaway's.
+  const declared = recorded === null ? declaredCopies(readTarget('AGENTS.md')) : [];
+  /** Whether repos init wrote `path` here: in breakaway's own folder, on the record, or in AGENTS.md's copied files. */
+  const owns = (path) =>
+    path.startsWith(TARGET_DIR) ||
+    Boolean(recorded?.has(path)) ||
+    declared.some((d) => (d.endsWith('/') ? path.startsWith(d) : path === d));
+  const ours = new Set();
+  const theirs = [];
+  /**
+   * A file copied from the board: added when it's missing, and with `update`, replaced when it differs, but only when
+   * repos init wrote it (the record lists it, or it's in breakaway's own folder). A repository's own file at a path
+   * breakaway copies to is left alone (BRK-79).
+   */
   const copy = (path, content, extra = {}) => {
     const there = readTarget(path);
-    if (there === null) files.push({ path, content, ...extra });
-    else if (!update) skipped.push(path);
-    else if (there === content) current.push(path);
-    else files.push({ path, content, ...extra, changed: true });
+    if (there === null) {
+      files.push({ path, content, ...extra });
+      ours.add(path);
+    } else if (there === content) {
+      (update ? current : skipped).push(path);
+      ours.add(path);
+    } else if (!update) skipped.push(path);
+    else if (owns(path)) {
+      files.push({ path, content, ...extra, changed: true });
+      ours.add(path);
+    } else {
+      skipped.push(path);
+      theirs.push(path);
+    }
   };
 
   const prompt = promptPathOf(repo);
@@ -357,7 +429,14 @@ export function initPlan({
   }
   for (const path of COPIED) copy(TARGET_DIR + path, read(path));
   copy(`${TARGET_DIR}taskrc`, withRepoInTaskrc(read('taskrc'), repo.slug, Boolean(repo.isDefault)));
-  for (const path of importClosure(RELEASE_ENTRIES, read)) copy(path, read(path));
+  // A release helper the repository keeps as its own doesn't bring the files breakaway's version imports (BRK-79).
+  const kept = (entry) => {
+    const there = readTarget(entry);
+    return there === null || there === read(entry) || (update && owns(entry));
+  };
+  const needed = new Set(importClosure(RELEASE_ENTRIES.filter(kept), read));
+  for (const path of importClosure(RELEASE_ENTRIES, read))
+    if (needed.has(path) || readTarget(path) !== null) copy(path, read(path));
   if (HOOKS_FROM_COPY) for (const path of importClosure(HOOK_ENTRIES, read)) copy(HOOKS_DIR + path, read(path));
   // An old copy of the CLI is replaced by npx: with update, its files go. The src/ files it imported may be the
   // repository's own by now, so those are only named.
@@ -389,7 +468,7 @@ export function initPlan({
       );
   }
   if (readTarget('.claude/skills') === null) files.push({ path: '.claude/skills', link: '../.agents/skills' });
-  copy(SKILL, skillFor(read(SKILL), board));
+  copy(SKILL, skillFor(read(SKILL), board, repo));
   add('AGENTS.md', agentsMd(repo, board, configDir));
   if (!skipped.includes('AGENTS.md')) todo.push('AGENTS.md: add how to build in this repository');
 
@@ -443,5 +522,43 @@ export function initPlan({
       append: attributes !== null,
     });
   }
+  // A file the repository still runs stays, with the old copy it belongs to (BRK-79): package.json, or settings the
+  // rewiring above couldn't move to npx.
+  const settingsNow =
+    files.find((f) => f.path === '.claude/settings.json')?.content ?? readTarget('.claude/settings.json');
+  const uses = [
+    ['package.json', readTarget('package.json')],
+    ['.claude/settings.json', settingsNow],
+  ];
+  for (const group of [(p) => p.startsWith('scripts/'), (p) => p.startsWith(HOOKS_DIR)]) {
+    const inGroup = removals.filter(group);
+    const used = uses.flatMap(([file, text]) =>
+      inGroup.filter((p) => String(text ?? '').includes(p)).map((p) => `${file} still runs ${p}`),
+    );
+    if (!used.length) continue;
+    for (const p of inGroup) removals.splice(removals.indexOf(p), 1);
+    notes.push(
+      `${used.join('; ')}, so its copy stays: switch it to npx breakaway (\`${hookCommand('session')}\` for the hooks), then run --update again to remove the copy.`,
+    );
+  }
+  if (theirs.length)
+    notes.push(
+      `${theirs.join(', ')} ${theirs.length > 1 ? 'are' : 'is'} at a path breakaway copies to, but repos init has no record of writing ${theirs.length > 1 ? 'them' : 'it'}, so ${theirs.length > 1 ? 'they are left as they are' : 'it is left as it is'}. If one is breakaway's older copy, delete it and run --update again.`,
+    );
+  // The record of what is breakaway's here; a run without --update leaves an existing one alone.
+  const record = `${JSON.stringify(
+    {
+      about: `Files repos init copied from ${board} and keeps in step with it (npx breakaway repos init <slug> --update). A file not listed is this repository's own, even at a path breakaway copies to.`,
+      from: board,
+      files: [...ours].sort(),
+    },
+    null,
+    2,
+  )}\n`;
+  const recordThere = readTarget(MANIFEST);
+  if (recordThere === null) files.push({ path: MANIFEST, content: record });
+  else if (recordThere === record) current.push(MANIFEST);
+  else if (update) files.push({ path: MANIFEST, content: record, changed: true });
+  else skipped.push(MANIFEST);
   return { files, removals, skipped, current, notes, todo };
 }

package/scripts/tasks/message-wait.mjs

@@ -17,7 +17,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { boardConfig, claimedTask, projectRoot } from './hook-config.js';
-import { routeThroughSessionProxy } from './proxy.js';
+import { sessionRequest } from './proxy.js';
 import { waitForMessages } from './session-messages.js';
 
 async function main() {
@@ -43,9 +43,9 @@ async function main() {
   const { base, headers } = boardConfig(root);
   if (!base) return;
   const url = `${base}/api/tasks/${encodeURIComponent(claim.uuid)}/messages/waiting?agent=${encodeURIComponent(claim.agent)}`;
-  routeThroughSessionProxy();
+  // Through curl in a cloud session, so it works on whichever Node runs hooks there (BRK-86).
   const ask = async () => {
-    const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+    const res = await sessionRequest(url, { headers, timeoutMs: 10_000 });
     return res.ok ? res.json() : null;
   };
 

package/scripts/tasks/proxy.js

@@ -7,7 +7,11 @@
  * routeThroughSessionProxy() sends fetch through the proxy and trusts the system's CA store too, which
  * holds the proxy's certificate. Without a proxy in the environment it does nothing.
  */
+import { spawn } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import http from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import tls from 'node:tls';
 
 export function sessionProxy(env = process.env) {
@@ -25,3 +29,89 @@ export function routeThroughSessionProxy(env = process.env) {
   }
   return true;
 }
+
+/** Runs `command` with `args`, `input` on stdin, and resolves with stdout; rejects with stderr when it fails. */
+function runWithInput(command, args, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => {
+      out += d;
+    });
+    child.stderr.on('data', (d) => {
+      err += d;
+    });
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve(out) : reject(Object.assign(new Error(err.trim() || `${command} exited ${code}`), { code })),
+    );
+    child.stdin.end(input ?? '');
+  });
+}
+
+/**
+ * A hook's request to the board (BRK-86). Claude Code runs hooks with the image's default Node, which in a cloud session
+ * can be too old to send fetch through the session proxy (Node 20 has neither http.setGlobalProxyFromEnv nor the CA
+ * calls above), and the sandbox refuses a request that goes around it. So with a proxy the request goes through curl,
+ * which reads HTTPS_PROXY and the system's certificates on any Node; without curl, or without a proxy, through fetch.
+ * Answers like fetch's response: { ok, status, json() }.
+ * @param {string} url
+ * @param {{ method?: string, headers?: Record<string, string>, body?: string, timeoutMs?: number }} [request]
+ */
+export async function sessionRequest(
+  url,
+  { method = 'GET', headers = {}, body, timeoutMs = 4000 } = {},
+  { env = process.env, run = runWithInput, fetch = globalThis.fetch } = {},
+) {
+  if (sessionProxy(env)) {
+    const args = ['-sS', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), '-X', method];
+    for (const [name, value] of Object.entries(headers)) args.push('-H', `${name}: ${value}`);
+    if (body !== undefined) args.push('--data-binary', '@-');
+    args.push('-w', '\n%{http_code}', url);
+    try {
+      const out = await run('curl', args, body);
+      const at = out.lastIndexOf('\n');
+      const status = Number(out.slice(at + 1));
+      const text = out.slice(0, Math.max(0, at));
+      return { ok: status >= 200 && status < 300, status, json: async () => (text.trim() ? JSON.parse(text) : null) };
+    } catch (error) {
+      if (/** @type {any} */ (error)?.code !== 'ENOENT') throw error;
+      // No curl here: fetch, through the proxy if this Node can.
+    }
+  }
+  routeThroughSessionProxy(env);
+  return fetch(url, { method, headers, body, signal: AbortSignal.timeout(timeoutMs) });
+}
+
+/**
+ * Where a hook notes why it couldn't post for a task (BRK-86): the system's temp folder, never the repository, where a
+ * cloud session's Stop check would take a new file as work to commit. The CLI shows it on its next command here.
+ */
+const failurePath = (uuid, dir) => join(dir, `breakaway-hook-${String(uuid).replace(/[^\w-]/gu, '')}.json`);
+
+/** Records that the hook couldn't post for task `uuid`, and why. */
+export function noteHookFailure(uuid, reason, dir = tmpdir(), at = new Date()) {
+  try {
+    writeFileSync(
+      failurePath(uuid, dir),
+      `${JSON.stringify({ at: at.toISOString(), reason: String(reason).slice(0, 300) })}\n`,
+    );
+  } catch {
+    /* nowhere to note it */
+  }
+}
+
+/** Clears that note, after a post that went through. */
+export function clearHookFailure(uuid, dir = tmpdir()) {
+  rmSync(failurePath(uuid, dir), { force: true });
+}
+
+/** The hook's last failure for task `uuid`, or null. */
+export function hookFailure(uuid, dir = tmpdir()) {
+  try {
+    return JSON.parse(readFileSync(failurePath(uuid, dir), 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/scripts/tasks/session-hook.mjs

@@ -7,12 +7,13 @@
  * additionalContext so Claude gets them on its next turn (docs/specs/IDEA-15-message-a-running-agent.md).
  *
  * Quiet by design: without a claimed task (.task-session, written by `tasks claim`), with
- * BREAKAWAY_SESSION_LOG=off (or SAMEWAVE_TASKS_SESSION_LOG=off), or on any error, it does nothing and exits 0.
+ * BREAKAWAY_SESSION_LOG=off (or SAMEWAVE_TASKS_SESSION_LOG=off), or on any error, it does nothing and exits 0. A post
+ * that fails leaves its reason in the temp folder, which the CLI's next command here shows (BRK-86).
  */
-import { boardConfig, claimedTask, projectRoot } from './hook-config.js';
-import { routeThroughSessionProxy } from './proxy.js';
+import { boardConfig, claimedTask, dropClaim, projectRoot } from './hook-config.js';
+import { clearHookFailure, noteHookFailure, sessionRequest } from './proxy.js';
 import { entryFor } from './session-log.js';
-import { CONTEXT_EVENTS, messageOutput } from './session-messages.js';
+import { CONTEXT_EVENTS, messageOutput, releasedOutput } from './session-messages.js';
 
 async function main() {
   const root = projectRoot();
@@ -26,23 +27,36 @@ async function main() {
   if (!entry) return;
 
   const { base, headers } = boardConfig(root);
-  if (!base) return;
-  routeThroughSessionProxy();
-  const res = await fetch(`${base}/api/tasks/${encodeURIComponent(claim.uuid)}/session`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', ...headers },
-    body: JSON.stringify({
-      agent: claim.agent,
-      session: hook.session_id ?? null,
-      remote: process.env.CLAUDE_CODE_REMOTE === 'true',
-      entries: [entry],
-      // A Stop hook's output can't reach Claude, so it leaves the messages for the next event.
-      messages: CONTEXT_EVENTS.has(hook.hook_event_name),
-    }),
-    signal: AbortSignal.timeout(4000),
-  });
-  if (!res.ok) return;
-  const output = messageOutput(await res.json(), hook.hook_event_name);
+  if (!base) return noteHookFailure(claim.uuid, 'no board address: set BREAKAWAY_URL');
+  let res;
+  try {
+    // Through curl in a cloud session, so it works on whichever Node runs hooks there (BRK-86).
+    res = await sessionRequest(`${base}/api/tasks/${encodeURIComponent(claim.uuid)}/session`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify({
+        agent: claim.agent,
+        session: hook.session_id ?? null,
+        remote: process.env.CLAUDE_CODE_REMOTE === 'true',
+        entries: [entry],
+        // A Stop hook's output can't reach Claude, so it leaves the messages for the next event.
+        messages: CONTEXT_EVENTS.has(hook.hook_event_name),
+      }),
+      timeoutMs: 4000,
+    });
+  } catch (error) {
+    return noteHookFailure(claim.uuid, /** @type {Error} */ (error)?.message ?? String(error));
+  }
+  if (!res.ok) return noteHookFailure(claim.uuid, `HTTP ${res.status}`);
+  clearHookFailure(claim.uuid);
+  const answer = await res.json();
+  if (answer?.released) {
+    dropClaim(claim, root);
+    const output = releasedOutput(claim, hook.hook_event_name);
+    if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+  const output = messageOutput(answer, hook.hook_event_name);
   if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
 }
 

package/scripts/tasks/session-messages.js

@@ -27,6 +27,13 @@ export function messageOutput(answer, event) {
   return { hookSpecificOutput: { hookEventName: event, additionalContext: text } };
 }
 
+/** The one line the hook says when the board no longer has this checkout's task claimed by its agent (BRK-87), or null on an event that can't carry it. */
+export function releasedOutput(claim, event) {
+  if (!CONTEXT_EVENTS.has(event)) return null;
+  const text = `${claim.wid ?? 'The task'} is no longer claimed by ${claim.agent ?? 'this agent'} (finished or released), so this checkout stops sending its live output. \`tasks claim\` starts it again on another task.`;
+  return { hookSpecificOutput: { hookEventName: event, additionalContext: text } };
+}
+
 /** The board's answer → the messages as Claude reads them, one paragraph each, or '' when there are none. */
 export function messageText(answer) {
   const messages = Array.isArray(answer?.messages) ? answer.messages : [];

package/scripts/tasks.mjs

@@ -40,11 +40,18 @@ import {
 } from './tasks/structure.js';
 import { looksLikeSecret } from '../src/ping.js';
 import { promptPathOf } from '../src/repos.js';
-import { sessionProxy, routeThroughSessionProxy } from './tasks/proxy.js';
+import { hookFailure, sessionProxy, routeThroughSessionProxy } from './tasks/proxy.js';
 import { githubFromRemote, inRepo, pickRepo } from './tasks/repo.js';
 import { NO_TERMINAL, ask as askIn } from './tasks/ask.js';
 import { CLI_PACKAGE, PROMPT_SECTIONS, initPlan, machineTaskrc, promptSections } from './tasks/init.js';
-import { githubRequest, ideaTask, staleCliWarning, unknownSubcommand } from './tasks/cli.js';
+import {
+  githubRequest,
+  ideaTask,
+  pullAgentRequest,
+  pullAgentSummary,
+  staleCliWarning,
+  unknownSubcommand,
+} from './tasks/cli.js';
 import { CLI_VERSION } from '../src/cli-version.js';
 import { LEGACY, parseInstall, secretName } from '../src/install.js';
 import {
@@ -143,6 +150,8 @@ Reading                (list, next, claim, and add work in this checkout's repos
   routines               saved prompts the owner runs with a button, and their caps
   routines run <slug>    run one now: makes a RUN task and starts an agent on it  [--note <text>]
   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>]
+  github review <n>      start an agent that tests a Dependabot pull request, as Safe to merge? does (owner)  [--note <text>] [--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)
   health                 the server's state
@@ -517,6 +526,20 @@ async function startSessionLog(t) {
     );
 }
 
+/** The session hook couldn't post this checkout's live output: say so where the agent and the owner see it (BRK-86). */
+function warnHookFailure() {
+  try {
+    const claim = JSON.parse(readFileSync(join(REPO, '.task-session'), 'utf8'));
+    const failed = claim?.uuid && hookFailure(claim.uuid);
+    if (failed)
+      console.error(
+        `tasks: the session hook couldn't post ${claim.wid ?? 'this task'}'s live output (${failed.reason}, ${failed.at.slice(0, 16).replace('T', ' ')} UTC), so the board shows none. docs/tasks.md#cloud-agents says what to check.`,
+      );
+  } catch {
+    /* no claim here */
+  }
+}
+
 function unmarkSession(t) {
   try {
     const path = join(REPO, '.task-session');
@@ -1188,6 +1211,18 @@ const commands = {
     );
   },
   async github() {
+    const action = args[0];
+    if (action === 'fix' || action === 'review') {
+      const built = pullAgentRequest(action, args[1], {
+        repo: (await checkoutRepo()).slug,
+        problem: opts.problem,
+        note: opts.note,
+      });
+      if (built.error || !built.request) fail(built.error ?? 'bad request');
+      const answer = await call(...built.request);
+      print(answer, (a) => pullAgentSummary(action, args[1].replace(/^#/u, ''), a));
+      return;
+    }
     const g = await call(...githubRequest((await checkoutRepo()).slug, { sync: Boolean(opts.sync) }));
     print(g, (d) => {
       if (!d.connected) return "GitHub isn't connected yet: open the GitHub view on the board (docs/tasks.md#github).";
@@ -1938,5 +1973,6 @@ if (opts.help || command === 'help') {
 } else if (unknownSubcommand(command, args[0])) {
   fail(unknownSubcommand(command, args[0]));
 } else {
+  if (command !== 'hook') warnHookFailure();
   await commands[command]();
 }

package/src/cli-version.js

@@ -2,8 +2,7 @@
  * The version of the board's CLI and the files repos init copies with it (CLD-193). The board reports it
  * (every API answer's X-Tasks-Cli header, and health), so a copy in another repository can say it's older
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
- * bump CLI_VERSION and set CLI_FINGERPRINT to the value it prints. Constants only: the board's Worker imports it,
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 36;
-export const CLI_FINGERPRINT = '252bee7de1e280f7';
+export const CLI_VERSION = 44;
+export const CLI_FINGERPRINT = 'd89515e35e35eacd';

package/src/install.js

@@ -147,7 +147,7 @@ export const secretName = (inst, key) => `${inst.secretsPrefix}${key}`;
 export const docsLink = (inst, anchor) => (inst.docs ? `${inst.docs}${anchor ? `#${anchor}` : ''}` : null);
 
 /** The routes `run_worker_first` sends to the Worker; everything else is the web app. */
-const WORKER_FIRST = ['/api/*', '/v1/*', '/github/*', '/login', '/logout'];
+export const WORKER_FIRST = ['/api/*', '/v1/*', '/github/*', '/login', '/logout'];
 
 /**
  * The Worker's wrangler config for an install. `local` is for `wrangler dev` (interop): no custom