breakaway 1.0.2-main.9 → 1.0.2

package/README.md

@@ -174,7 +174,7 @@ breakaway publishes releases and never deploys an install. Every install, the ow
 - **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.9",
+  "version": "1.0.2",
   "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/init.js

@@ -92,8 +92,10 @@ export function writeInstall({ dir, templateDir, config, state }) {
     writeFileSync(target, text);
     written.push(path);
   };
-  // The Worker reads the channel from its config (BRK-10), so it starts the same as breakaway.json's.
-  put('breakaway.config.json', json({ ...config, channel: state.channel }));
+  // The Worker reads the channel from its config (BRK-10), so it starts the same as breakaway.json's. No aliases yet: an
+  // empty list is left out, so a release from before them (BRK-78) still reads the file.
+  const { aliases, ...named } = config;
+  put('breakaway.config.json', json({ ...named, ...(aliases?.length ? { aliases } : {}), channel: state.channel }));
   put('breakaway.json', json(state));
   for (const file of TEMPLATE_FILES) put(file, readFileSync(join(templateDir, file), 'utf8'));
   put('README.md', readmeFor(readFileSync(join(templateDir, 'README.md'), 'utf8'), 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/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. */
@@ -24,7 +42,7 @@ function readOptional(path) {
 
 /** This machine's tasks.env, as `{ NAME: value }`. */
 function envFile() {
-  const dir = configDir({ env: process.env, home: homedir(), exists: existsSync });
+  const dir = configDir({ env: process.env, home: homedir() });
   return parseEnvFile(readOptional(join(dir, 'tasks.env')));
 }
 
@@ -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/message-wait.mjs

@@ -7,7 +7,7 @@
  * quietly, and a message waits for the agent's next turn; its `timeout` (300 s) outlasts the window,
  * because Claude Code kills an async hook at its timeout (CLD-146).
  *
- * Quiet by design: without a claimed task (.task-session), with BREAKAWAY_SESSION_LOG=off (or SAMEWAVE_TASKS_SESSION_LOG=off), or
+ * Quiet by design: without a claimed task (.task-session), with BREAKAWAY_SESSION_LOG=off, or
  * on any error, it exits 0. It writes nothing inside the repository: a cloud session's Stop check
  * would take a dirty file as work to commit.
  */

package/scripts/tasks/repo.js

@@ -1,7 +1,7 @@
 /**
  * Which repository the CLI works in (docs/specs/IDEA-14-multi-repo.md, section 5; CLD-123): the
  * checkout's, from `git remote get-url origin`, matched against the board's registry. `--repo` or
- * BREAKAWAY_REPO (or SAMEWAVE_TASKS_REPO) overrides it. Pure, so it's tested without git or the board.
+ * BREAKAWAY_REPO overrides it. Pure, so it's tested without git or the board.
  */
 
 /**

package/scripts/tasks/session-hook.mjs

@@ -7,13 +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. A post
+ * BREAKAWAY_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 { 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();
@@ -49,7 +49,14 @@ async function main() {
   }
   if (!res.ok) return noteHookFailure(claim.uuid, `HTTP ${res.status}`);
   clearHookFailure(claim.uuid);
-  const output = messageOutput(await res.json(), hook.hook_event_name);
+  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/settings.js

@@ -1,52 +1,38 @@
 /**
  * Which board install the CLI and the session hooks talk to, and the names of their settings (CLD-136,
- * docs/specs/IDEA-13-breakaway.md, section 2). Every setting has a breakaway name (BREAKAWAY_URL) and the
- * name the first install used before breakaway (SAMEWAVE_TASKS_URL), read as a fallback so existing machines,
- * cloud environments, and agents keep working. Pure (the environment, files, and checks come in as arguments),
+ * docs/specs/IDEA-13-breakaway.md, section 2). Pure (the environment, files, and checks come in as arguments),
  * so it's tested without a disk.
  */
-/** Each setting's breakaway name, then the fallback the first install set up. */
+/** Each setting's name, in the environment and in tasks.env (BRK-77 retired the first install's names). */
 export const NAMES = Object.freeze({
-  URL: ['BREAKAWAY_URL', 'SAMEWAVE_TASKS_URL'],
-  TOKEN: ['BREAKAWAY_TOKEN', 'SAMEWAVE_TASKS_TOKEN'],
-  AGENT: ['BREAKAWAY_AGENT', 'SAMEWAVE_AGENT'],
-  REPO: ['BREAKAWAY_REPO', 'SAMEWAVE_TASKS_REPO'],
-  CLIENT_ID: ['BREAKAWAY_CLIENT_ID', 'SAMEWAVE_TASKS_CLIENT_ID'],
-  SECRET: ['BREAKAWAY_SECRET', 'SAMEWAVE_TASKS_SECRET'],
-  SYNC_KEY: ['BREAKAWAY_SYNC_KEY', 'SAMEWAVE_TASKS_SYNC_KEY'],
-  SESSION_LOG: ['BREAKAWAY_SESSION_LOG', 'SAMEWAVE_TASKS_SESSION_LOG'],
+  URL: 'BREAKAWAY_URL',
+  TOKEN: 'BREAKAWAY_TOKEN',
+  AGENT: 'BREAKAWAY_AGENT',
+  REPO: 'BREAKAWAY_REPO',
+  CLIENT_ID: 'BREAKAWAY_CLIENT_ID',
+  SECRET: 'BREAKAWAY_SECRET',
+  SYNC_KEY: 'BREAKAWAY_SYNC_KEY',
+  SESSION_LOG: 'BREAKAWAY_SESSION_LOG',
 });
 
-const LEGACY_NAMES = new Set(Object.values(NAMES).map(([, legacy]) => legacy));
-
 /**
- * A setting's value: from the environment first (either name), then the env file (either name), else
- * `fallback`. The environment always wins, so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere.
+ * A setting's value: from the environment first, then the env file, else `fallback`. The environment always wins,
+ * so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere.
  */
 export function readSetting(key, { env = {}, file = {} }, fallback) {
-  const names = NAMES[key];
-  if (!names) throw new Error(`no setting ${key}`);
-  for (const source of [env, file]) for (const name of names) if (source[name]) return source[name];
-  return fallback;
+  const name = NAMES[key];
+  if (!name) throw new Error(`no setting ${key}`);
+  return env[name] || file[name] || fallback;
 }
 
-/** True when an env file uses the first install's names, so the CLI writes it back with the same ones. */
-export const usesLegacyNames = (file) => Object.keys(file ?? {}).some((name) => LEGACY_NAMES.has(name));
-
-/** A setting's name in an env file the CLI writes: the file's own style, breakaway's for a new one. */
-export const nameFor = (key, legacy) => NAMES[key][legacy ? 1 : 0];
-
 /**
  * This machine's folder for the board (tasks.env, the Taskwarrior credentials, the routines copy):
- * BREAKAWAY_HOME when it's set (one per install, for a machine that uses two), else ~/.config/breakaway,
- * else ~/.config/samewave when only that one exists (a machine set up before breakaway), else ~/.config/breakaway.
+ * BREAKAWAY_HOME when it's set (one per install, for a machine that uses two), else ~/.config/breakaway.
  */
-/** @param {{ env?: Record<string, string | undefined>, home?: string, exists: (path: string) => boolean }} options */
-export function configDir({ env = {}, home, exists }) {
+/** @param {{ env?: Record<string, string | undefined>, home?: string }} options */
+export function configDir({ env = {}, home }) {
   if (env.BREAKAWAY_HOME) return env.BREAKAWAY_HOME.replace(/\/$/u, '');
-  const breakaway = `${home}/.config/breakaway`;
-  const samewave = `${home}/.config/samewave`;
-  return !exists(breakaway) && exists(samewave) ? samewave : breakaway;
+  return `${home}/.config/breakaway`;
 }
 
 /** `path` as a Taskwarrior include line can name it: `~/…` under `home`, else as it is. */
@@ -59,8 +45,7 @@ export function taskrcUrl(text) {
 }
 
 /**
- * The board's base URL, and where it came from: the environment or env file (BREAKAWAY_URL, then
- * SAMEWAVE_TASKS_URL), else the checkout's own .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree),
+ * The board's base URL, and where it came from: the environment or env file (BREAKAWAY_URL), else the checkout's own .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree),
  * else the install's breakaway.config.json (`url`), else null: nothing says which board.
  */
 export function boardUrl({ env = {}, file = {}, taskrc = null, config = null }) {

package/scripts/tasks.mjs

@@ -4,14 +4,13 @@
  * Talks to the board's JSON API; claims there are atomic. See docs/tasks.md.
  *
  * Settings come from the environment, then tasks.env in this machine's folder for the board ($BREAKAWAY_HOME,
- * else ~/.config/breakaway, or ~/.config/samewave where only that one exists). Each has a breakaway name and,
- * as a fallback, the name an install from before breakaway used first (scripts/tasks/settings.js):
- *   BREAKAWAY_TOKEN       SAMEWAVE_TASKS_TOKEN       API token (or the cloud environment's API credential)
- *   BREAKAWAY_URL         SAMEWAVE_TASKS_URL         the board; default: this checkout's .taskrc (sync.server.url),
- *                                                     then breakaway.config.json (tools/tasks/ in a copy), then the legacy install's
- *   BREAKAWAY_AGENT       SAMEWAVE_AGENT             your name on claims (default user@host)
- *   BREAKAWAY_REPO        SAMEWAVE_TASKS_REPO        the repository to work in (default: the checkout's origin)
- *   BREAKAWAY_CLIENT_ID   SAMEWAVE_TASKS_CLIENT_ID   for `setup` (Taskwarrior sync), with BREAKAWAY_SECRET
+ * else ~/.config/breakaway; scripts/tasks/settings.js):
+ *   BREAKAWAY_TOKEN       API token (or the cloud environment's API credential)
+ *   BREAKAWAY_URL         the board; default: this checkout's .taskrc (sync.server.url),
+ *                         then breakaway.config.json (tools/tasks/ in a copy)
+ *   BREAKAWAY_AGENT       your name on claims (default user@host)
+ *   BREAKAWAY_REPO        the repository to work in (default: the checkout's origin)
+ *   BREAKAWAY_CLIENT_ID   for `setup` (Taskwarrior sync), with BREAKAWAY_SECRET
  */
 import { execFileSync, spawnSync } from 'node:child_process';
 import { createPrivateKey, pbkdf2Sync, randomBytes, randomUUID } from 'node:crypto';
@@ -53,19 +52,10 @@ import {
   unknownSubcommand,
 } from './tasks/cli.js';
 import { CLI_VERSION } from '../src/cli-version.js';
-import { LEGACY, parseInstall, secretName } from '../src/install.js';
-import {
-  boardUrl,
-  configDir,
-  nameFor,
-  parseEnvFile,
-  readSetting,
-  taskrcFixes,
-  tildePath,
-  usesLegacyNames,
-} from './tasks/settings.js';
+import { parseInstall, secretName } from '../src/install.js';
+import { NAMES, boardUrl, configDir, parseEnvFile, readSetting, taskrcFixes, tildePath } from './tasks/settings.js';
 
-const CONFIG_DIR = configDir({ env: process.env, home: homedir(), exists: existsSync });
+const CONFIG_DIR = configDir({ env: process.env, home: homedir() });
 const ENV_FILE = join(CONFIG_DIR, 'tasks.env');
 // Every other repository's routine, as agents-connect --repo wrote it to the Secrets Store: the owner's copy,
 // so connecting one more merges instead of dropping the others (the Secrets Store never gives a value back).
@@ -100,12 +90,12 @@ function sharedFile(name) {
 const CONFIG_FILE = sharedFile('breakaway.config.json');
 
 /**
- * The board's install, from breakaway.config.json: its Secrets Store and the prefix of its secrets'
- * names (a legacy install's: SAMEWAVE_TASKS_). Read only by the owner's commands that write secrets; a checkout without
- * the file is a legacy install.
+ * The board's install, from breakaway.config.json: its Secrets Store and the prefix of its secrets' names. Read only by
+ * the owner's commands that write secrets; a checkout without the file gets a new install's defaults, as the package
+ * does (BRK-77 retired the first install's names).
  */
 function installConfig() {
-  if (!existsSync(CONFIG_FILE)) return { ...LEGACY, secretsStore: null };
+  if (!existsSync(CONFIG_FILE)) return parseInstall({});
   try {
     return parseInstall(JSON.parse(readFileSync(CONFIG_FILE, 'utf8')));
   } catch (error) {
@@ -251,7 +241,7 @@ Everywhere: --json for machine-readable output, --as <name> to claim as someone
 Projects: ideas and routines are the board's; repos lists each repository's areas.
 
 Settings: BREAKAWAY_TOKEN, BREAKAWAY_URL, BREAKAWAY_AGENT, BREAKAWAY_REPO, from the environment or tasks.env in
-  $BREAKAWAY_HOME (default ~/.config/breakaway); the first names (SAMEWAVE_TASKS_TOKEN, …) still work.
+  $BREAKAWAY_HOME (default ~/.config/breakaway).
   Without BREAKAWAY_URL the board is this checkout's .taskrc sync.server.url. See docs/tasks.md#another-install.`;
 
 // ---- settings ----------------------------------------------------------------------------
@@ -261,7 +251,7 @@ function readEnvFile() {
 }
 
 const fileEnv = readEnvFile();
-/** A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN, then SAMEWAVE_TASKS_TOKEN. */
+/** A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN. */
 const setting = (key, fallback) => readSetting(key, { env: process.env, file: fileEnv }, fallback);
 const BOARD = boardUrl({
   env: process.env,
@@ -271,9 +261,8 @@ const BOARD = boardUrl({
 });
 /** The board's address, or null when nothing says which board (the commands then ask for one). */
 const BASE = BOARD.url;
-/** The names this machine's tasks.env uses: the first ones in a file that has them, else breakaway's. */
-const LEGACY_ENV = usesLegacyNames(fileEnv);
-const envName = (key) => nameFor(key, LEGACY_ENV);
+/** A setting's name in tasks.env: `TOKEN` is BREAKAWAY_TOKEN. */
+const envName = (key) => NAMES[key];
 // In a cloud session, go through its proxy: that's where the board's API credential is added.
 routeThroughSessionProxy();
 
@@ -442,7 +431,7 @@ const enc = encodeURIComponent;
 
 let repoContext;
 /**
- * {slug, registry}: the repository this checkout works in, from --repo, SAMEWAVE_TASKS_REPO, or the
+ * {slug, registry}: the repository this checkout works in, from --repo, BREAKAWAY_REPO, or the
  * origin remote. slug is null on a board without repositories or in a checkout it doesn't know, and
  * then everything works as before.
  */
@@ -1415,7 +1404,7 @@ const commands = {
   /**
    * Owner, once per repository: its routine's /fire URL and token (asked for here, never on a command line).
    * The default repository's go in its two secrets, as always; `--repo <slug>` puts another's in
-   * the install's ROUTINES secret (SAMEWAVE_TASKS_ROUTINES on an install from before breakaway), JSON keyed by slug, merged with this machine's copy of the others.
+   * the install's ROUTINES secret (BREAKAWAY_ROUTINES with breakaway's prefix), JSON keyed by slug, merged with this machine's copy of the others.
    */
   async 'agents-connect'() {
     const { repos, default: fallback } = await call('GET', 'repos');
@@ -1896,7 +1885,7 @@ function promoteEnvFile() {
 
 /**
  * Pipes each value into `wrangler secrets-store secret update` (never on a command line). `values` are keyed by
- * the part of the secret's name after the install's prefix (`API_TOKEN` is SAMEWAVE_TASKS_API_TOKEN on an install from before breakaway).
+ * the part of the secret's name after the install's prefix (`API_TOKEN` is BREAKAWAY_API_TOKEN with breakaway's prefix).
  * An install without a Secrets Store (the Deploy to Cloudflare button's, CLD-139) keeps them as Worker secrets.
  */
 function updateSecretsStore(values) {

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 = 40;
-export const CLI_FINGERPRINT = '37624c98bbeb5108';
+export const CLI_VERSION = 47;
+export const CLI_FINGERPRINT = 'e779f7d4ae3104e4';

package/src/install.js

@@ -13,6 +13,7 @@ export const DEFAULTS = Object.freeze({
   name: 'breakaway',
   worker: 'breakaway',
   url: null,
+  aliases: [],
   secretsPrefix: 'BREAKAWAY_',
   secretsStore: null,
   store: 'breakaway',
@@ -72,6 +73,26 @@ function origin(url) {
   }
 }
 
+/**
+ * The other addresses a board answers on beside its url, as https origins (BRK-78): while it moves to a new address,
+ * the old one stays an alias until nothing uses it. Each is a custom domain of the Worker, like the url.
+ */
+function aliasesOf(aliases, url) {
+  if (!Array.isArray(aliases))
+    throw new ConfigError('aliases is a list of https origins, like ["https://old.example.com"]');
+  if (aliases.length && url === null)
+    throw new ConfigError('aliases need a url: they are the other addresses the board answers on beside it');
+  const out = aliases.map((a) => {
+    const o = origin(a);
+    if (!o) throw new ConfigError(`aliases: ${a} isn't an https origin, like https://old.example.com`);
+    if (o === url) throw new ConfigError(`aliases: ${o} is already the url`);
+    return o;
+  });
+  const twice = out.find((o, i) => out.indexOf(o) !== i);
+  if (twice) throw new ConfigError(`aliases: ${twice} is there twice`);
+  return out;
+}
+
 /** A breakaway.config.json's contents, checked and with its defaults filled in. Throws ConfigError naming what's wrong. */
 export function parseInstall(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new ConfigError('the config is a JSON object');
@@ -88,6 +109,7 @@ export function parseInstall(raw) {
       'url is where the board answers, an https origin like https://tasks.example.com, or null for workers.dev',
     );
   c.url = c.url === null ? null : origin(c.url);
+  c.aliases = aliasesOf(c.aliases, c.url);
   if (!PREFIX.test(c.secretsPrefix))
     throw new ConfigError('secretsPrefix is uppercase and ends with _, like BREAKAWAY_');
   if (c.secretsStore !== null && !STORE_ID.test(c.secretsStore))
@@ -147,7 +169,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
@@ -179,7 +201,9 @@ export function wranglerConfig(config, { local = false, root = '.' } = {}) {
     name: c.worker,
     main: at('src/worker.js'),
     compatibility_date: COMPATIBILITY_DATE,
-    ...(local || !c.url ? {} : { routes: [{ pattern: new URL(c.url).host, custom_domain: true }] }),
+    ...(local || !c.url
+      ? {}
+      : { routes: [c.url, ...c.aliases].map((u) => ({ pattern: new URL(u).host, custom_domain: true })) }),
     workers_dev: !local && !c.url,
     preview_urls: false,
     ...(local

package/src/redact.js

@@ -6,9 +6,10 @@
 const PATTERNS = [
   // Private keys, whole blocks.
   [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, '[redacted key]'],
-  // An install's own settings (breakaway's prefix and the legacy one): KEY=value where the name says it's secret.
+  // Settings whose name says they're secret, KEY=value, under any prefix: breakaway's, an install's own (it picks its
+  // secrets' prefix), Cloudflare's, GitHub's, and the rest (BRK-77).
   [
-    /\b((?:BREAKAWAY|SAMEWAVE|CLOUDFLARE|GITHUB|ANTHROPIC)_[A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD)[A-Z0-9_]*\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gu,
+    /\b([A-Z][A-Z0-9]*_[A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD)[A-Z0-9_]*\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gu,
     '$1[redacted]',
   ],
   // Anthropic, GitHub, Slack-style tokens.

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,8 +32,28 @@ 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
 
 Edit `breakaway.config.json` and merge it: Deploy runs on every push to `main`.
+
+To move the board to a new address without a gap, add the new one under `aliases` first, so both answer; then swap `url` and the alias; and remove the alias once nothing uses the old address. breakaway's [docs/tasks.md](https://github.com/TheAnarchoX/breakaway/blob/main/docs/tasks.md#moving-to-a-new-address) has the whole list of what names the address.