breakaway 1.0.2-main.2 → 1.0.2-main.21

package/README.md

@@ -171,10 +171,10 @@ 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.
+- **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. When the only step is `wrangler deploy` (a new Durable Object class, a cron, a route), it also sets `wranglerDeploy: true`, and an install whose Deploy may run `wrangler deploy` does it itself (the install template's README says when). Data the Durable Object stores changes forward-only and additively, so an install can always go back one release, except across a new Durable Object class, which Cloudflare doesn't roll back.
 - **The version** is `package.json`'s; the release workflow sets it to the pre-release's before it builds. `GET /api/ping` and `GET /api/health` report it as `release`. An install that deploys a stable passes it as the `BREAKAWAY_VERSION` variable, since the bundle was built as the pre-release.
 
 </details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.0.2-main.2",
+  "version": "1.0.2-main.21",
   "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/prompts/install.md

@@ -54,6 +54,12 @@ The Cloudflare API token is theirs to make. On Cloudflare: My Profile, API Token
 gh secret set CLOUDFLARE_API_TOKEN --env production --repo <owner>/<name>
 ```
 
+That token can run `wrangler deploy`, so Deploy can apply a new address, cron triggers, or a new Durable Object class by itself instead of stopping for them. That's theirs to turn on; after a yes:
+
+```sh
+gh variable set BREAKAWAY_DEPLOY_CHANGES --body true --repo <owner>/<name>
+```
+
 **Check:** `gh api repos/<owner>/<name>/environments/production/secrets --jq '.secrets[].name'` lists both secrets, and the workflows are on `main`.
 
 ## 2. The board's secrets

package/scripts/install/cli.js

@@ -11,14 +11,12 @@ import { ask } from '../tasks/ask.js';
 import { QUESTIONS, configFrom, stateFrom, writeInstall } from './init.js';
 import {
   bumpBody,
-  checkManifest,
-  configStop,
+  deployPlan,
   deployTarget,
   isHealthy,
   latestReleases,
   parseState,
   previousVersionId,
-  shapeChanges,
   shapeOf,
   updatePlan,
   workerMissing,
@@ -72,6 +70,28 @@ const configIn = (path) => {
   }
 };
 
+/** A file's JSON, or null when it's missing or isn't JSON. */
+const jsonIn = (path) => {
+  try {
+    return path ? JSON.parse(readFileSync(path, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The running Worker's shape for `check`, or null when nothing says what it is. */
+function runningShape(opts) {
+  const running = jsonIn(opts['running-config']);
+  if (running && typeof running === 'object') return shapeOf(running);
+  const before = jsonIn(opts.before);
+  if (!before) return null; // no earlier config (the first deploy, or a dispatch): nothing to compare with
+  try {
+    return shapeOf(wranglerConfig(parseInstall(before)));
+  } catch {
+    return null;
+  }
+}
+
 /** The Worker's wrangler config for a downloaded release: the install's config, with the code and web app where the bundle put them. */
 export function bundleConfig(config, bundle) {
   const out = wranglerConfig(config);
@@ -99,20 +119,17 @@ export async function runStep(step, opts, io) {
     const version = opts.version;
     if (!version) throw new Stop('check needs --version, the release being deployed.');
     const manifest = readJson(opts.manifest ?? 'release/manifest.json', 'the release’s manifest');
-    const verdict = checkManifest(manifest, { version, running: opts.running || null });
-    if (verdict.ok === false) throw new Stop(verdict.message, 2);
-    if (opts.before) {
-      let before = null;
-      try {
-        before = parseInstall(JSON.parse(readFileSync(opts.before, 'utf8')));
-      } catch {
-        before = null; // no earlier config (the first deploy, or a dispatch): nothing to compare with
-      }
-      const now = configIn(join(dir, 'breakaway.config.json'));
-      const stop = before && configStop(shapeChanges(shapeOf(wranglerConfig(before)), shapeOf(wranglerConfig(now))));
-      if (stop) throw new Stop(stop, 2);
-    }
+    // The Worker as it runs: the config the running release's own CLI made (--running-config), else this release's code
+    // with the config from before this push (--before). Neither (a first deploy, or a dispatch): nothing to compare.
+    const before = runningShape(opts);
+    const after = before && shapeOf(wranglerConfig(configIn(join(dir, 'breakaway.config.json'))));
+    const apply = opts['deploy-changes'] === true || opts['deploy-changes'] === 'true';
+    const plan = deployPlan(manifest, { version, running: opts.running || null, before, after, apply });
+    if (plan.ok === false) throw new Stop(plan.message, 2);
     io.out('ok=true');
+    io.out(`deploy=${plan.deploy}`);
+    io.out(`changes=${plan.changes.join(', ')}`);
+    io.out(`address_changed=${plan.addressChanged}`);
     return 0;
   }
   if (step === 'config') {

package/scripts/install/lib.js

@@ -78,13 +78,19 @@ export function deployTarget(state, releases) {
   return { version: latest.version, tag: tagOf(latest.version), channel: 'main' };
 }
 
+/** How Deploy is allowed to run wrangler deploy, for the messages that stop it. */
+const LET_DEPLOY =
+  "give CLOUDFLARE_API_TOKEN the scopes this repository's README lists for it and set the repository variable BREAKAWAY_DEPLOY_CHANGES to true";
+
 /**
  * Whether a downloaded release may be deployed by the workflow. A release that needs hands, or one the running version
- * can't update from, stops with the message the workflow prints.
- * @param {{ version?: string, manual?: boolean, manualSteps?: string[], updatesFrom?: string }} manifest
- * @returns {{ ok: true } | { ok: false, message: string }}
+ * can't update from, stops with the message the workflow prints. A manual release whose only step is wrangler deploy
+ * (`wranglerDeploy`, BRK-62) passes when the install lets Deploy run it (`apply`), and says it needs wrangler deploy.
+ * @param {{ version?: string, manual?: boolean, manualSteps?: string[], wranglerDeploy?: boolean, updatesFrom?: string }} manifest
+ * @param {{ version: string, running?: string | null, apply?: boolean }} options
+ * @returns {{ ok: true, wrangler?: true } | { ok: false, message: string }}
  */
-export function checkManifest(manifest, { version, running = null }) {
+export function checkManifest(manifest, { version, running = null, apply = false }) {
   if (!manifest || typeof manifest !== 'object')
     return { ok: false, message: 'the release’s manifest.json isn’t readable, so nothing was deployed.' };
   if (manifest.version !== version)
@@ -92,13 +98,6 @@ export function checkManifest(manifest, { version, running = null }) {
       ok: false,
       message: `the manifest is for ${manifest.version}, not ${version}, so nothing was deployed. Try again; if it persists, the release was published wrongly.`,
     };
-  if (manifest.manual === true) {
-    const steps = (manifest.manualSteps ?? []).map((s) => `\n  - ${s}`).join('');
-    return {
-      ok: false,
-      message: `breakaway ${version} needs steps by hand, so the workflow didn't deploy it. Do these, then deploy it yourself with wrangler:${steps}`,
-    };
-  }
   if (
     running &&
     manifest.updatesFrom &&
@@ -110,40 +109,131 @@ export function checkManifest(manifest, { version, running = null }) {
       ok: false,
       message: `breakaway ${version} updates from ${manifest.updatesFrom} or newer, and this install runs ${running}. Update to ${manifest.updatesFrom} first (set it in breakaway.json), then to ${version}.`,
     };
+  if (manifest.manual === true) {
+    const byWrangler = manifest.wranglerDeploy === true;
+    if (byWrangler && apply) return { ok: true, wrangler: true };
+    const steps = (manifest.manualSteps ?? []).map((s) => `\n  - ${s}`).join('');
+    const hint = byWrangler
+      ? `\nThese steps are what wrangler deploy does, so Deploy can do them itself: ${LET_DEPLOY}, then run Deploy again.`
+      : '';
+    return {
+      ok: false,
+      message: `breakaway ${version} needs steps by hand, so the workflow didn't deploy it. Do these, then deploy it yourself with wrangler:${steps}${hint}`,
+    };
+  }
   return { ok: true };
 }
 
-/** What a deploy by the workflow can't change: routes, crons, the Durable Object classes, and their migrations. */
+/**
+ * What a version upload can't change (BRK-62): the Worker and its Durable Object, its routes and crons, and the Durable
+ * Object classes and their migrations. Made from the Worker's wrangler config.
+ */
 export function shapeOf(wrangler) {
+  const inst = wrangler.vars?.TASKS_INSTALL;
   return {
+    worker: wrangler.name ?? null,
+    store: (inst && typeof inst === 'object' ? inst.store : null) ?? null,
+    jurisdiction: wrangler.vars?.TASKS_JURISDICTION ?? null,
     routes: wrangler.routes ?? [],
     workers_dev: Boolean(wrangler.workers_dev),
     crons: wrangler.triggers?.crons ?? [],
     durable_objects: wrangler.durable_objects?.bindings ?? [],
     migrations: wrangler.migrations ?? [],
-    jurisdiction: wrangler.vars?.TASKS_JURISDICTION ?? null,
   };
 }
 
-/** What differs between two installs' shapes, as phrases for the message; empty when a deploy may go ahead. */
+const json = (value) => JSON.stringify(value);
+/** A migration that only makes classes, which wrangler deploy applies; any other kind deletes, renames, or moves one. */
+const CREATES = new Set(['tag', 'new_sqlite_classes', 'new_classes']);
+
+/**
+ * The classes `after` adds, when adding is all its Durable Object change does: its migrations are `before`'s with only
+ * new classes after them, and it keeps every binding `before` has. Null for anything else.
+ */
+function addedClasses(before, after) {
+  const kept = before.migrations.every((m, i) => json(m) === json(after.migrations[i]));
+  const added = after.migrations.slice(before.migrations.length);
+  if (!kept || !added.every((m) => Object.keys(m).every((key) => CREATES.has(key)))) return null;
+  if (!before.durable_objects.every((b) => after.durable_objects.some((a) => json(a) === json(b)))) return null;
+  return added.flatMap((m) => [...(m.new_sqlite_classes ?? []), ...(m.new_classes ?? [])]);
+}
+
+/**
+ * What differs between the Worker's shape as it runs and as this deploy makes it, each with whether wrangler deploy may
+ * apply it (BRK-62): an address, cron triggers, and new Durable Object classes, yes. Another Worker, another Durable
+ * Object, or a class deleted, renamed, or moved, never: the first two open an empty board, and the last is a release's
+ * manual step. Empty when a version upload carries the whole deploy.
+ * @returns {{ change: string, apply: boolean, why?: string, address?: true }[]}
+ */
 export function shapeChanges(before, after) {
-  const names = {
-    routes: 'its address (routes)',
-    workers_dev: 'its workers.dev address',
-    crons: 'its cron triggers',
-    durable_objects: 'its Durable Object classes',
-    migrations: 'its Durable Object migrations',
-    jurisdiction: 'its jurisdiction',
-  };
-  return Object.keys(names)
-    .filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]))
-    .map((key) => names[key]);
+  const differs = (key) => json(before[key]) !== json(after[key]);
+  const out = [];
+  const empty = 'another Durable Object is an empty board';
+  if (differs('worker'))
+    out.push({
+      change: 'its Worker’s name (worker)',
+      apply: false,
+      why: 'a new name makes a new Worker, with an empty board',
+    });
+  if (differs('store')) out.push({ change: 'its Durable Object (store)', apply: false, why: empty });
+  if (differs('jurisdiction')) out.push({ change: 'its jurisdiction', apply: false, why: empty });
+  if (differs('routes')) out.push({ change: 'its address (routes)', apply: true, address: true });
+  if (differs('workers_dev')) out.push({ change: 'its workers.dev address', apply: true, address: true });
+  if (differs('crons')) out.push({ change: 'its cron triggers', apply: true });
+  if (differs('durable_objects') || differs('migrations')) {
+    const added = addedClasses(before, after);
+    if (added === null)
+      out.push({
+        change: 'its Durable Object classes: it deletes, renames, or moves one',
+        apply: false,
+        why: 'that is a release’s manual step, and it can lose a board',
+      });
+    else
+      out.push({
+        change: added.length
+          ? `its Durable Object classes: it adds ${added.join(', ')}`
+          : 'its Durable Object bindings',
+        apply: true,
+      });
+  }
+  return out;
 }
 
-/** The message that stops a deploy when the install's config changed what the workflow can't deploy, or null. */
+/** The message that stops a deploy whose changes need wrangler deploy when the install hasn't allowed it, or null. */
 export function configStop(changes) {
   if (!changes.length) return null;
-  return `breakaway.config.json changed ${changes.join(', ')}, which the workflow doesn't deploy. Apply it yourself with wrangler (npx wrangler deploy, with the config npx breakaway install config makes), then run the workflow again.`;
+  return `This deploy changes ${changes.join(', ')}, which a version upload can't carry, so nothing was deployed. To let Deploy run wrangler deploy for it, ${LET_DEPLOY}, then run Deploy again. Or apply it yourself with wrangler (npx wrangler deploy, with the config npx breakaway install config makes), then run Deploy again.`;
+}
+
+/** The message that stops a deploy with a change Deploy never makes. */
+function neverStop(changes) {
+  const why = [...new Set(changes.map((c) => c.why))].join('; ');
+  return `This deploy changes ${changes.map((c) => c.change).join(', ')}, which Deploy never does, so nothing was deployed: ${why}. If breakaway.config.json changed it, put it back as it was. If the release did, its notes say what to do by hand.`;
+}
+
+/**
+ * What Deploy does with a release (BRK-62): stop with a message, upload a version (`versions`), or run wrangler deploy
+ * (`wrangler`) for what a version can't carry. `before` and `after` are the Worker's shapes as it runs and as this deploy
+ * makes it; `before` is null when there is nothing to compare with (a first deploy, or a dispatch with no running release
+ * to ask). `apply` is whether the install lets Deploy run wrangler deploy: BREAKAWAY_DEPLOY_CHANGES, set for a token that
+ * can. `addressChanged` tells the health check to wait for a new custom domain.
+ * @returns {{ ok: false, message: string } | { ok: true, deploy: 'versions' | 'wrangler', changes: string[], addressChanged: boolean }}
+ */
+export function deployPlan(manifest, { version, running = null, before = null, after = null, apply = false }) {
+  const verdict = checkManifest(manifest, { version, running, apply });
+  if (verdict.ok === false) return verdict;
+  const found = before && after ? shapeChanges(before, after) : [];
+  const never = found.filter((c) => !c.apply);
+  if (never.length) return { ok: false, message: neverStop(never) };
+  const changes = found.map((c) => c.change);
+  const byWrangler = changes.length > 0 || verdict.wrangler === true;
+  if (byWrangler && !apply) return { ok: false, message: configStop(changes) };
+  return {
+    ok: true,
+    deploy: byWrangler ? 'wrangler' : 'versions',
+    changes,
+    addressChanged: found.some((c) => c.address === true),
+  };
 }
 
 /**

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 = 45;
+export const CLI_FINGERPRINT = '947c6296a0dd677e';

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

package/template/.github/workflows/deploy.yml

@@ -1,7 +1,9 @@
 # Deploys a breakaway release to this install's Worker: the release breakaway.json pins (stable), or the latest
 # pre-release (main). Runs on a push to main, which is how a merged update pull request deploys, and by hand.
-# It stops with a plain message when the release needs steps by hand, or when breakaway.config.json changed
-# something it can't deploy (the address, cron triggers, or Durable Object classes): those are yours to deploy.
+# A deploy uploads a version of the Worker. A change a version can't carry (the address, cron triggers, or a new
+# Durable Object class) needs wrangler deploy: Deploy runs it when the repository variable BREAKAWAY_DEPLOY_CHANGES is
+# true, for a token that can (the README says which), and otherwise stops with a plain message, as it does for a release
+# that needs steps by hand. It never changes the Worker's name or its Durable Object, which would open an empty board.
 name: Deploy
 
 on:
@@ -40,6 +42,8 @@ jobs:
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
       DRY_RUN: ${{ inputs.dry-run }}
+      # true lets Deploy run wrangler deploy for an address, cron triggers, or a new Durable Object class (BRK-62).
+      DEPLOY_CHANGES: ${{ vars.BREAKAWAY_DEPLOY_CHANGES }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -91,6 +95,7 @@ jobs:
           (cd release && sha256sum --check SHA256SUMS)
 
       - name: Check it can deploy by itself
+        id: check
         env:
           CLI: ${{ steps.release.outputs.cli }}
           VERSION: ${{ steps.release.outputs.version }}
@@ -98,15 +103,34 @@ jobs:
           ADDRESS: ${{ vars.BREAKAWAY_URL }}
         run: |
           set -euo pipefail
-          # Nothing is deployed yet on the first run, so there is no running release to compare with.
-          address=${ADDRESS:-$(node -p "require('./breakaway.config.json').url || ''")}
+          # The config as it was before this push, to see whether it changed what a version upload can't carry.
+          rm -f before.json running.wrangler.json
+          case "$BEFORE" in ''|0000000000000000000000000000000000000000) ;; *) git show "$BEFORE:breakaway.config.json" > before.json 2>/dev/null || rm -f before.json ;; esac
+          was=breakaway.config.json
+          if [ -f before.json ]; then was=before.json; fi
+          # Where the running board answers: the address from before this push, if the push changes it.
+          address=${ADDRESS:-$(node -p "require('./$was').url || ''")}
           running=""
-          # A board that doesn't say its release (one from before BRK-10) runs none this check knows.
+          # A board that doesn't say its release (one from before BRK-10) runs none this check knows. Nothing is deployed
+          # yet on the first run, so there is no running release to compare with.
           if [ -n "$address" ]; then running=$(curl -fsS --max-time 20 "$address/api/ping" | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).release ?? ''" 2>/dev/null || true); fi
-          # The config as it was before this push, to see whether it changed what a deploy can't.
-          rm -f before.json
-          case "$BEFORE" in ''|0000000000000000000000000000000000000000) ;; *) git show "$BEFORE:breakaway.config.json" > before.json 2>/dev/null || rm -f before.json ;; esac
-          node "$CLI" install check --version "$VERSION" --manifest release/manifest.json --running "$running" --before before.json
+          # The Worker as it runs: the config the running release's own CLI makes from the config it was deployed with, so
+          # a release that changes the cron triggers or the Durable Object classes shows as a change too. Without it (the
+          # same release, or one that can't be read), the check compares the configs with this release's code.
+          if [ -n "$running" ] && [ "$running" != "$VERSION" ]; then
+            dir="$RUNNER_TEMP/running"
+            mkdir -p "$dir/src"
+            if gh release download "v$running" --repo "$BREAKAWAY_REPO" --archive tar.gz -O - 2>/dev/null | tar -xz -C "$dir/src" --strip-components 1 2>/dev/null; then
+              cp "$was" "$dir/breakaway.config.json"
+              (cd "$dir" && node src/scripts/tasks.mjs install config --out "$GITHUB_WORKSPACE/running.wrangler.json" > /dev/null 2>&1) || rm -f running.wrangler.json
+            fi
+          fi
+          status=0
+          node "$CLI" install check --version "$VERSION" --manifest release/manifest.json --running "$running" \
+            --before before.json --running-config running.wrangler.json --deploy-changes "${DEPLOY_CHANGES:-false}" > check.out || status=$?
+          cat check.out
+          if [ "$status" -ne 0 ]; then exit "$status"; fi
+          cat check.out >> "$GITHUB_OUTPUT"
 
       - name: Make the Worker config
         env:
@@ -127,7 +151,15 @@ jobs:
 
       - name: Dry run
         if: ${{ inputs.dry-run }}
-        run: npx --yes wrangler@4 deploy --dry-run --outdir "$RUNNER_TEMP/dry" -c wrangler.generated.json
+        env:
+          DEPLOY: ${{ steps.check.outputs.deploy }}
+          CHANGES: ${{ steps.check.outputs.changes }}
+        run: |
+          set -euo pipefail
+          npx --yes wrangler@4 deploy --dry-run --outdir "$RUNNER_TEMP/dry" -c wrangler.generated.json
+          if [ "$DEPLOY" != wrangler ]; then echo "A deploy would upload a version."
+          elif [ -n "$CHANGES" ]; then echo "A deploy would run wrangler deploy for $CHANGES."
+          else echo "A deploy would run wrangler deploy, the release's manual step."; fi
 
       - name: Upload and deploy
         if: ${{ !inputs.dry-run }}
@@ -135,6 +167,9 @@ jobs:
           CLI: ${{ steps.release.outputs.cli }}
           VERSION: ${{ steps.release.outputs.version }}
           ADDRESS: ${{ vars.BREAKAWAY_URL }}
+          DEPLOY: ${{ steps.check.outputs.deploy }}
+          CHANGES: ${{ steps.check.outputs.changes }}
+          ADDRESS_CHANGED: ${{ steps.check.outputs.address_changed }}
         run: |
           set -euo pipefail
           wrangler() { npx --yes wrangler@4 "$@" -c wrangler.generated.json; }
@@ -150,6 +185,11 @@ jobs:
           fi
           if [ -z "$previous" ]; then
             wrangler deploy --var "BREAKAWAY_VERSION:$VERSION"
+          elif [ "$DEPLOY" = wrangler ]; then
+            # What a version can't carry (BRK-62): wrangler deploy applies the address, cron triggers, and new Durable
+            # Object classes with the code, and the Worker can still go back to $previous unless a class was added.
+            if [ -n "$CHANGES" ]; then echo "This deploy changes $CHANGES, so it runs wrangler deploy."; else echo "breakaway $VERSION's manual step is wrangler deploy, so this deploy runs it."; fi
+            wrangler deploy --var "BREAKAWAY_VERSION:$VERSION" --message "breakaway $VERSION"
           else
             export WRANGLER_OUTPUT_FILE_PATH="$RUNNER_TEMP/wrangler-output.ndjson"
             wrangler versions upload --var "BREAKAWAY_VERSION:$VERSION" --message "breakaway $VERSION"
@@ -157,22 +197,33 @@ jobs:
             wrangler versions deploy "$uploaded@100%" --yes
           fi
           # Health check: the new release answers /api/ping. Without it, go back to the previous version.
-          address=${ADDRESS:-$(node -p "require('./breakaway.config.json').url || ''")}
+          url=$(node -p "require('./breakaway.config.json').url || ''")
+          address=${ADDRESS:-$url}
+          tries=12
+          if [ "$ADDRESS_CHANGED" = true ]; then
+            # A new address: check it, not the old one, and give its custom domain five minutes for its certificate.
+            address=${url:-$ADDRESS}
+            tries=60
+          fi
           if [ -z "$address" ]; then
             echo "::warning title=Not checked::There is no address to check. Set the repository variable BREAKAWAY_URL to where the board answers (a workers.dev address, say) and the next deploy checks it."
             exit 0
           fi
-          for attempt in $(seq 1 12); do
+          for attempt in $(seq 1 "$tries"); do
             if curl -fsS --max-time 15 "$address/api/ping" | node "$CLI" install healthy --version "$VERSION"; then
               echo "breakaway $VERSION is running at $address."
               exit 0
             fi
             sleep 5
           done
-          if [ -n "$previous" ]; then
-            wrangler rollback "$previous" --message "breakaway $VERSION failed its check" --yes
-            echo "::error title=Rolled back::breakaway $VERSION didn't answer $address/api/ping within a minute, so the Worker went back to its previous version. Nothing is lost; read the Worker's logs on Cloudflare."
+          waited=$([ "$tries" -gt 12 ] && echo "five minutes" || echo "a minute")
+          if [ -z "$previous" ]; then
+            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping within $waited, and this was the first deploy, so there is no version to go back to. Read the Worker's logs on Cloudflare."
+          elif wrangler rollback "$previous" --message "breakaway $VERSION failed its check" --yes; then
+            kept=""
+            if [ "$DEPLOY" = wrangler ]; then kept=" Rolling back brings back the code only: what wrangler deploy changed${CHANGES:+ ($CHANGES)} stays as it left it."; fi
+            echo "::error title=Rolled back::breakaway $VERSION didn't answer $address/api/ping within $waited, so the Worker went back to its previous version.$kept Nothing is lost; read the Worker's logs on Cloudflare."
           else
-            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping within a minute, and this was the first deploy, so there is no version to go back to. Read the Worker's logs on Cloudflare."
+            echo "::error title=Couldn't roll back::breakaway $VERSION didn't answer $address/api/ping within $waited, and the Worker couldn't go back to its previous version: Cloudflare doesn't roll back across a new Durable Object class. The board's data is still in its Durable Object. Read the Worker's logs on Cloudflare, then deploy a fix."
           fi
           exit 1

package/template/README.md

@@ -17,7 +17,7 @@ The board answers at {{address}}.
 ## Set it up once
 
 1. **Push this to a private GitHub repository.**
-2. **Make a GitHub environment named `production`** (Settings, Environments) with two secrets: `CLOUDFLARE_API_TOKEN`, a token that can edit Workers on your account, and `CLOUDFLARE_ACCOUNT_ID`.
+2. **Make a GitHub environment named `production`** (Settings, Environments) with two secrets: `CLOUDFLARE_API_TOKEN`, a Cloudflare API token ([which token does what](#which-token-does-what)), and `CLOUDFLARE_ACCOUNT_ID`.
 3. **Allow the update workflow to open pull requests:** Settings, Actions, General, "Allow GitHub Actions to create and approve pull requests".
 4. **Set the board's secrets** (`npx breakaway init-secrets`, then the Worker's secrets or your Secrets Store: see `.dev.vars.example`).
 5. **Run the Deploy workflow** from the Actions tab. Choose "dry-run" first to check everything up to the Worker without changing it.
@@ -32,7 +32,25 @@ Both workflows run breakaway's CLI from the release's own source on GitHub, with
 
 If Deploy stops with "Couldn't list the Worker's deployments", it changed nothing: only a Worker that doesn't exist yet counts as a first deploy. Check that `CLOUDFLARE_ACCOUNT_ID` is your account's ID (32 hex characters) and that `CLOUDFLARE_API_TOKEN` can read and edit Workers on it, then run Deploy again.
 
-A release can need steps by hand (a change to the Durable Object classes, say). The workflow stops with those steps in its message and deploys nothing; do them, then deploy with `wrangler`. The same stop happens when you change something in `breakaway.config.json` the workflow can't deploy: the address, cron triggers, or Durable Object classes. Apply that change yourself (`npx breakaway install config` makes the Worker config), then run Deploy again.
+A release can need steps by hand (a Durable Object class deleted or renamed, say). The workflow stops with those steps in its message and deploys nothing; do them, then deploy with `wrangler`. A release whose only step is `wrangler deploy` says so in its notes, and Deploy runs it itself when it may ([below](#which-token-does-what)). The same goes for a new address in `breakaway.config.json`, which a version upload can't carry: without that, apply it yourself (`npx breakaway install config` makes the Worker config), then run Deploy again.
+
+## Which token does what
+
+`CLOUDFLARE_API_TOKEN` decides what Deploy can do by itself. Most deploys only upload a new version of the Worker. A deploy that changes the address, the cron triggers, or the Durable Object classes needs `wrangler deploy`, and so a token that can run it:
+
+| Token | What Deploy does |
+| --- | --- |
+| **Workers Editor on this Worker** | Uploads each release, checks it, and goes back if it fails. It stops on an address, cron, or Durable Object class change, and you apply that yourself. |
+| **Workers Editor on every Worker**, and **Zone, Workers Routes, Write** on the board's zone | The same, and with the repository variable `BREAKAWAY_DEPLOY_CHANGES` set to `true`, it runs `wrangler deploy` for those changes too. Custom domains don't support per-Worker roles yet, so Editor has to cover every Worker. |
+
+Either token also needs **Account, Secrets Store, Edit** when the board has a Secrets Store: every deploy binds its secrets. The very first deploy makes the Worker, which takes **Workers Admin**; after that, Editor is enough.
+
+Whatever the token, Deploy never changes the Worker's name, its Durable Object (`store`), or its jurisdiction: each opens an empty board, so it stops instead.
+
+With `wrangler deploy`:
+
+- **A new address replaces the old one.** The Worker answers only on the addresses in its config, so the old one stops answering, and in a workflow `wrangler deploy` takes over the new hostname's DNS record, or another Worker's domain on it, without asking. Moving to another zone needs Workers Routes, Write on both zones. The check after the deploy asks the new address, for up to five minutes while its certificate is issued. If you set `BREAKAWAY_URL`, change it with the address.
+- **Going back brings back the code only.** The address and cron triggers stay as `wrangler deploy` left them, and Cloudflare doesn't roll back across a new Durable Object class, so after one the only way is forward.
 
 ## Change the install