toolroll 0.9.98 → 0.9.99

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.9.99 — 2026-11-09
+
+- **A Toolroll update interrupted while the new service was starting no longer gets stuck.** Before, an update killed in that short window left new work paused until someone edited a file by hand. Running the release again now finishes the update when the new service is running, and puts the previous service back once the new one is proved gone. Nothing is stopped on a guess: a new service that is loaded but never answers is left alone, and the message names the one command that stops it.
+- **Update steps are one list.** The 17 steps an update records, and what a stopped update at each step needs, now live in one file that every part of Toolroll reads. A step name this version doesn't know is refused instead of being treated as "roll back".
+
 ## 0.9.98 — 2026-11-09
 
 - **Start a small task from chat in one step.** Ask the lead for one small, clear change ("just fix the typo in the footer") in web chat, Telegram, Slack, Discord or Teams, and it drafts a Start work card. Your own tap (then "Yes, start work") files and approves it under the same rules as the New task form's Build: small changes only, Toolroll's size check must agree, your chat approval setting and limits apply, it must start within 30 minutes, and you still accept the result before it's finished or published. On web chat the card opens the full terms to confirm. On Telegram you can also reply yes to the card, and the reply links the task it started. In Teams, and in Slack when a word in the request would show as an emoji, approval cards open the review page instead of taking a tap, so what you approve is always shown exactly as written. Anything bigger becomes an ordinary task card, and the lead can never start work itself.

package/dist/checkout-cleanup.js

@@ -27,6 +27,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { isDeployed } from "./deploy-phase.js";
 import { taskBranches } from "./names.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { CLEANUP_CHOICES, IDLE_CHOICES, bytesWords, diskBytes, diskBytesAsync } from "./storage.js";
@@ -59,7 +60,7 @@ export function deployedRelease(stateDir) {
         catch {
             continue;
         }
-        if (journal["phase"] !== "deployed")
+        if (!isDeployed(journal["phase"]))
             continue;
         const at = typeof journal["deployedAt"] === "string" ? journal["deployedAt"] : typeof journal["updatedAt"] === "string" ? journal["updatedAt"] : "";
         if (newest !== null && newest.at >= at)

package/dist/deploy-phase-data.json

@@ -0,0 +1,21 @@
+{
+  "phases": [
+    { "phase": "preparing", "action": "lift-pause", "flags": ["beforeSwap", "beforePause"] },
+    { "phase": "admission-paused", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "frozen", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "backup-verified", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "rehearsed", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "stopping", "action": "roll-back", "flags": [] },
+    { "phase": "stopped", "action": "roll-back", "flags": ["restartable"] },
+    { "phase": "migrating", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "migrated", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "starting", "action": "forward", "flags": [] },
+    { "phase": "started", "action": "forward", "flags": [] },
+    { "phase": "healthy", "action": "forward", "flags": [] },
+    { "phase": "start-failed", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "backup-restored", "action": "roll-back", "flags": ["restartable"] },
+    { "phase": "restored", "action": "roll-back", "flags": [] },
+    { "phase": "released", "action": "none", "flags": [] },
+    { "phase": "deployed", "action": "none", "flags": ["deployed"] }
+  ]
+}

package/dist/deploy-phase.d.ts

@@ -0,0 +1,37 @@
+/** What `toolroll release` does with a deployment that stopped at a phase; "refuse" for a word that is no phase. */
+export type DeployAction = "none" | "lift-pause" | "forward" | "roll-back" | "refuse";
+type RowAction = Exclude<DeployAction, "refuse">;
+type Flag = "beforeSwap" | "beforePause" | "migrationStarted" | "restartable" | "deployed";
+type Row = {
+    readonly phase: string;
+    readonly action: RowAction;
+    readonly flags: readonly Flag[];
+};
+/** The rows of a parsed data file, or an Error naming what is wrong with it. Never a partial table. */
+export declare function deployPhaseRows(data: unknown): readonly Row[];
+/** Every phase, in journal order. */
+export declare const DEPLOY_PHASES: readonly string[];
+export declare const isDeployPhase: (phase: unknown) => phase is string;
+/** The one action a journal's phase calls for; "refuse" for anything that is not a phase. */
+export declare const deployActionOf: (phase: unknown) => DeployAction;
+/** The word itself, or an Error: a journal is never written with a word the table does not hold. */
+export declare function assertDeployPhase(phase: string): string;
+/** The service was never stopped. */
+export declare const BEFORE_SWAP: readonly string[];
+/** Before the swap, with the pause in place. */
+export declare const PAUSED_BEFORE_SWAP: readonly string[];
+/** The candidate's store opened the live database, or the new service ran on it. */
+export declare const MIGRATION_STARTED: readonly string[];
+/** The old service is proved stopped: the previous definition may be started again. */
+export declare const RESTARTABLE: readonly string[];
+/** The new service may be running: never rolled back by a journal alone. */
+export declare const FORWARD_ONLY: readonly string[];
+/** Nothing is left to recover. Not the same as deployed: a released deployment never installed its runtime. */
+export declare const NEEDS_NO_RECOVERY: readonly string[];
+/** The deployment finished and its runtime is the installed one. */
+export declare const isDeployed: (phase: unknown) => boolean;
+/** Stopped where nothing was changed (before its pause), or with nothing left to do. */
+export declare const stoppedWhereNothingChanged: (phase: unknown) => boolean;
+/** The phase a lifted pause leaves behind (release-gate.ts). */
+export declare const RELEASED: string;
+export {};

package/dist/deploy-phase.js

@@ -0,0 +1,64 @@
+/**
+ * The phases of a browser deployment's journal, and what a stopped deployment at each one calls for.
+ *
+ * The rows are data: deploy-phase-data.json beside this file, the one authored list (the build copies it into dist,
+ * scripts/postbuild.mjs). The deploy scripts read the same file through scripts/deploy-phase-table.mjs, where each
+ * column is described. Both sides check its shape the same way; deploy-phase.test.ts holds them to each other and to
+ * its own hand-written expectations.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const ACTIONS = ["none", "lift-pause", "forward", "roll-back"];
+const FLAGS = ["beforeSwap", "beforePause", "migrationStarted", "restartable", "deployed"];
+/** The rows of a parsed data file, or an Error naming what is wrong with it. Never a partial table. */
+export function deployPhaseRows(data) {
+    const rows = data?.phases;
+    if (!Array.isArray(rows) || rows.length === 0)
+        throw new Error("The deployment phase table has no rows.");
+    const seen = new Set();
+    return Object.freeze(rows.map((row) => {
+        const { phase, action, flags } = (row ?? {});
+        if (typeof phase !== "string" || !/^[a-z]+(-[a-z]+)*$/.test(phase) || seen.has(phase))
+            throw new Error(`The deployment phase table has a bad or repeated phase: ${String(phase)}.`);
+        if (typeof action !== "string" || !ACTIONS.includes(action))
+            throw new Error(`The deployment phase ${phase} has no known action.`);
+        if (!Array.isArray(flags) || flags.some(flag => typeof flag !== "string" || !FLAGS.includes(flag)) || new Set(flags).size !== flags.length)
+            throw new Error(`The deployment phase ${phase} has an unknown or repeated flag.`);
+        seen.add(phase);
+        return Object.freeze({ phase, action: action, flags: Object.freeze([...flags]) });
+    }));
+}
+// By path, not by URL: a test environment that stands in for a browser replaces the global URL.
+const ROWS = deployPhaseRows(JSON.parse(readFileSync(join(import.meta.dirname, "deploy-phase-data.json"), "utf8")));
+const rowOf = (phase) => typeof phase === "string" ? ROWS.find(row => row.phase === phase) : undefined;
+const withFlag = (flag) => Object.freeze(ROWS.filter(row => row.flags.includes(flag)).map(row => row.phase));
+const withAction = (action) => Object.freeze(ROWS.filter(row => row.action === action).map(row => row.phase));
+/** Every phase, in journal order. */
+export const DEPLOY_PHASES = Object.freeze(ROWS.map(row => row.phase));
+export const isDeployPhase = (phase) => rowOf(phase) !== undefined;
+/** The one action a journal's phase calls for; "refuse" for anything that is not a phase. */
+export const deployActionOf = (phase) => rowOf(phase)?.action ?? "refuse";
+/** The word itself, or an Error: a journal is never written with a word the table does not hold. */
+export function assertDeployPhase(phase) {
+    if (!isDeployPhase(phase))
+        throw new Error(`"${String(phase)}" is not a deployment phase; the journal was not written.`);
+    return phase;
+}
+/** The service was never stopped. */
+export const BEFORE_SWAP = withFlag("beforeSwap");
+/** Before the swap, with the pause in place. */
+export const PAUSED_BEFORE_SWAP = Object.freeze(ROWS.filter(row => row.flags.includes("beforeSwap") && !row.flags.includes("beforePause")).map(row => row.phase));
+/** The candidate's store opened the live database, or the new service ran on it. */
+export const MIGRATION_STARTED = withFlag("migrationStarted");
+/** The old service is proved stopped: the previous definition may be started again. */
+export const RESTARTABLE = withFlag("restartable");
+/** The new service may be running: never rolled back by a journal alone. */
+export const FORWARD_ONLY = withAction("forward");
+/** Nothing is left to recover. Not the same as deployed: a released deployment never installed its runtime. */
+export const NEEDS_NO_RECOVERY = withAction("none");
+/** The deployment finished and its runtime is the installed one. */
+export const isDeployed = (phase) => rowOf(phase)?.flags.includes("deployed") === true;
+/** Stopped where nothing was changed (before its pause), or with nothing left to do. */
+export const stoppedWhereNothingChanged = (phase) => { const row = rowOf(phase); return row !== undefined && (row.flags.includes("beforePause") || row.action === "none"); };
+/** The phase a lifted pause leaves behind (release-gate.ts). */
+export const RELEASED = assertDeployPhase("released");

package/dist/deploy-rescue.d.ts

@@ -1,5 +1,6 @@
+import { FORWARD_ONLY } from "./deploy-phase.js";
 /** Phases where the new service may be running: recovery leaves them to the release, which resumes forward. */
-export declare const FORWARD_ONLY: readonly string[];
+export { FORWARD_ONLY };
 export type RescueWorld = {
     /** The live database. */
     database: string;

package/dist/deploy-rescue.js

@@ -18,10 +18,9 @@
  */
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
-import { BEFORE_SWAP } from "./release-gate.js";
+import { BEFORE_SWAP, FORWARD_ONLY, MIGRATION_STARTED, NEEDS_NO_RECOVERY, RESTARTABLE } from "./deploy-phase.js";
 /** Phases where the new service may be running: recovery leaves them to the release, which resumes forward. */
-export const FORWARD_ONLY = Object.freeze(["starting", "started", "healthy"]);
-const FINISHED = Object.freeze(["released", "deployed"]);
+export { FORWARD_ONLY };
 const real = (path) => { try {
     return realpathSync(path);
 }
@@ -39,8 +38,8 @@ export function rescuePlan(phase, journal) {
     if (phase === "stopping") {
         words.push("The old service must already be stopped. Recovery checks for remaining processes and refuses while any may still be running. Stop them through the service owner, then rerun recovery.");
     }
-    if (["stopping", "stopped", "migrating", "migrated", "start-failed", "backup-restored"].includes(phase)) {
-        if (["migrating", "migrated", "start-failed"].includes(phase))
+    if (phase === "stopping" || RESTARTABLE.includes(phase)) {
+        if (MIGRATION_STARTED.includes(phase))
             words.push("Puts the verified backup back first when the previous runtime can't read the migrated database.");
         words.push(`Starts the previous service (${prior}) again and waits for it to answer, past a stopped worker's heartbeat window; then lifts update pause ${id}.`);
     }
@@ -56,7 +55,7 @@ export async function rescueDeployment(stageArg, yes, world) {
             return { ok: false, reason: "usage", message: `${stageArg} is not a deployment stage of this installation (under ${join(world.stateDir, "staged-upgrades")}).` };
     }
     else {
-        const open = all.filter(one => one.journal === null || !FINISHED.includes(String(one.journal["phase"])));
+        const open = all.filter(one => one.journal === null || !NEEDS_NO_RECOVERY.includes(String(one.journal["phase"])));
         if (open.length === 0)
             return { ok: true, acted: false, stage: null, phase: null, words: ["Nothing to recover: every deployment finished or was already put back."] };
         if (open.length > 1)
@@ -74,7 +73,7 @@ export async function rescueDeployment(stageArg, yes, world) {
         return { ok: false, reason: "conflict", message: `That deployment ran on ${String(journal["database"])}, not ${world.database}; nothing was changed.` };
     if (!Number.isSafeInteger(run) || run < 1)
         return { ok: false, reason: "damaged", message: `${join(stage, "deployment.json")} names no builder run, so its commit's recovery can't be found; nothing was changed.` };
-    if (FINISHED.includes(phase))
+    if (NEEDS_NO_RECOVERY.includes(phase))
         return { ok: true, acted: false, stage, phase, words: [`Nothing to recover: that deployment is ${phase}.`] };
     if (FORWARD_ONLY.includes(phase)) {
         return { ok: false, reason: "forward", message: `That deployment is at ${phase}: the new service may be running, so nothing was stopped. Continue it forward with \`toolroll release <branch>\` (it resumes the deployment's finish).` };

package/dist/desktop-update.d.ts

@@ -97,13 +97,13 @@ export declare function sqliteLock(file: string, busyTimeoutMs?: number): Databa
 export declare function lockHeld(file: string): boolean;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;

package/dist/release-adapters.js

@@ -18,7 +18,8 @@ import { callLabel, readOnlyCall, retryCall, retryingExec, writeWithRecheck } fr
 const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { PROTECTION_MINIMUM_CHECKS, PROTECTION_REPORT_ONLY_CHECKS } from "./release.js";
 import { activeUpdateWork } from "./desktop-update-gate.js";
-import { BEFORE_SWAP, gateOwner } from "./release-gate.js";
+import { BEFORE_SWAP, deployActionOf, stoppedWhereNothingChanged } from "./deploy-phase.js";
+import { gateOwner } from "./release-gate.js";
 import { findCliLinks, switchCliLinks } from "./release-links.js";
 import { databasePath, finishReleaseOperation, requireFreshReleaseApproval, openStore, releaseAuthorityOfTask, releaseCarries, releaseOperations, renewReleaseLease, reserveRelease, runReleaseOperation, Store, recordReleaseStep, releaseIssuerGone, takeReleaseLease, } from "./store.js";
 import { acquireDeploymentLock } from "./deploy-lock.js";
@@ -62,8 +63,6 @@ const ownCli = () => {
     const bin = join(dirname(fileURLToPath(import.meta.url)), "bin.js");
     return existsSync(bin) ? [process.execPath, bin] : ["toolroll"];
 };
-/** Journal phases the deployment's finish accepts (scripts/deploy-phases.mjs finish): the new service runs, unproven. */
-const FINISHES_FORWARD = Object.freeze(["started", "healthy"]);
 const cleanEnv = (extra = {}) => {
     const env = { ...process.env, ...extra };
     delete env["NODE_OPTIONS"];
@@ -580,23 +579,40 @@ export function releaseAdapters(options) {
                 const running = (options.processes ?? processes)().filter(one => one.command.includes("deploy-browser.mjs") && one.command.includes(stage));
                 if (running.length > 0)
                     return { ok: false, message: `the deployment is still running (process ${running.map(one => one.pid).join(", ")}); let it finish, then rerun` };
-                // The new service started (deploy-rescue.ts FORWARD_ONLY): recovery refuses to roll it back, so the release
-                // resumes it forward with the deployment's own finish (health, both consoles, leases, then the pause lifted).
+                // The new service was started (the phase table's "forward" rows, deploy-phase.ts): the release resumes it
+                // forward with the deployment's own finish (health, both consoles, leases, then the pause lifted).
                 // Finishing deploys, so the candidate is proven first, as for a deploy.
-                const phase = (() => { try {
+                const journalPhase = () => { try {
                     return object(JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8")))["phase"];
                 }
                 catch {
                     return undefined;
-                } })();
-                if (FINISHES_FORWARD.includes(String(phase))) {
+                } };
+                const phase = journalPhase();
+                if (deployActionOf(phase) === "forward") {
                     const proven = proveCandidate(runId);
-                    if (!proven.ok)
-                        return stopped(stage, proven.message);
-                    const finished = await deployScript(worktree, stage, runId, proven, ["--yes", "--phase", "finish"]);
-                    if (finished.code === 0)
+                    let why;
+                    if (proven.ok) {
+                        const finished = await deployScript(worktree, stage, runId, proven, ["--yes", "--phase", "finish"]);
+                        if (finished.code === 0)
+                            return { ok: true };
+                        why = `${tail(finished)} (the deployment journal is at ${String(phase)}; finishing it forward stopped; ${join(stage, "deployment.json")})`;
+                    }
+                    else
+                        why = proven.message;
+                    // Once the new service was recorded as started, a journal alone never rolls it back: the release stops here.
+                    // Still at "starting" (killed while waiting for the new service; finish only looks, and it did not find it
+                    // running): the deployment's own recovery puts the previous service back, and only when it proves the new
+                    // one gone. That needs no approval of the candidate, exactly as below.
+                    if (journalPhase() !== "starting")
+                        return stopped(stage, why);
+                    const recorded = recordedCommit(runId);
+                    if (recorded === null)
+                        return stopped(stage, why);
+                    const back = await deployScript(worktree, stage, runId, recorded, ["--phase", "recover"]);
+                    if (back.code === 0)
                         return { ok: true };
-                    return stopped(stage, `${tail(finished)} (the deployment journal is at ${String(phase)}; finishing it forward stopped; ${join(stage, "deployment.json")})`);
+                    return stopped(stage, `${why} The previous service was not put back either: ${tail(back)}`);
                 }
                 // Recovery needs no approval, but it runs only the recorded commit's own script, extracted by this runtime.
                 const recorded = recordedCommit(runId);
@@ -642,7 +658,7 @@ export function releaseAdapters(options) {
                 catch {
                     return false;
                 }
-                return phase === "preparing" || phase === "released" || phase === "deployed";
+                return stoppedWhereNothingChanged(phase);
             },
             async cliLinks() { return findCliLinks(); },
             async switchLinks(links, bin, version) {

package/dist/release-gate.d.ts

@@ -18,9 +18,10 @@
  * Anything missing, damaged or contradicting refuses and leaves the pause as it is. Without --yes it only shows the
  * proof; with --yes it lifts that one pause (the owner is checked again inside the same write) and journals it.
  */
+import { BEFORE_SWAP } from "./deploy-phase.js";
 import type { Database } from "./store.js";
-/** The journal phases a deployment passes before it stops the old service (deploy-phases.mjs). */
-export declare const BEFORE_SWAP: readonly string[];
+/** The journal phases a deployment passes before it stops the old service (deploy-phase.ts, the one table). */
+export { BEFORE_SWAP };
 export type GateReleaseWorld = {
     /** The live database file. */
     database: string;
@@ -81,4 +82,3 @@ export type GateReleaseOutcome = {
 };
 /** Prove, then (with `yes`) lift exactly that pause and journal the release in the deployment's own journal. */
 export declare function releaseGate(id: string, world: GateReleaseWorld, yes: boolean): GateReleaseOutcome;
-export {};

package/dist/release-gate.js

@@ -23,8 +23,9 @@ import { join } from "node:path";
 import { durableJson } from "./desktop-update.js";
 import { removeUpdateGate, updateGateOwned } from "./desktop-update-gate.js";
 import { acquireDeploymentLock } from "./deploy-lock.js";
-/** The journal phases a deployment passes before it stops the old service (deploy-phases.mjs). */
-export const BEFORE_SWAP = Object.freeze(["preparing", "admission-paused", "frozen", "backup-verified", "rehearsed"]);
+import { BEFORE_SWAP, RELEASED } from "./deploy-phase.js";
+/** The journal phases a deployment passes before it stops the old service (deploy-phase.ts, the one table). */
+export { BEFORE_SWAP };
 /** Journal fields that only the swap and later phases write. */
 const SWAP_FIELDS = ["stoppingService", "codingBackupBeforeSwap", "migration", "newService", "deployedAt"];
 const GATE_ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
@@ -121,7 +122,9 @@ export function proveBeforeSwap(id, world) {
     if (staged.length > 0)
         return refuse("after-swap", `Process ${staged.map(one => one.pid).join(", ")} runs from the staged runtime ${r.nextRuntime}.`);
     const supervisor = processes.find(one => one.command.includes(`${r.priorRuntime}/controller-service.js`));
-    const worker = processes.find(one => one.command.includes(`${r.priorRuntime}/cli.js up --db ${world.database}`));
+    // The database as a whole argument: an `up` on a path that only begins with this database's is another service's.
+    const upHere = `${r.priorRuntime}/cli.js up --db ${world.database}`;
+    const worker = processes.find(one => one.command.split(upHere).slice(1).some(rest => rest === "" || /^\s/.test(rest)));
     if (supervisor === undefined || worker === undefined)
         return refuse("conflict", `The service is not running from ${r.priorRuntime}, so it can't be shown that the swap never began.`);
     proof.push(`The service runs from ${r.priorRuntime} (process ${supervisor.pid}); nothing runs from the staged runtime, and no deployment is running.`);
@@ -163,7 +166,7 @@ export function releaseGate(id, world, yes) {
             // The owner is checked again within removeUpdateGate's short write transaction.
             removeUpdateGate(db, id);
             durableJson(journalFile, {
-                ...fresh.journal, phase: "released", updatedAt: world.now().toISOString(),
+                ...fresh.journal, phase: RELEASED, updatedAt: world.now().toISOString(),
                 releasedBeforeSwap: { at: world.now().toISOString(), by: "toolroll release --release-gate", from: fresh.journal.phase, proof: fresh.proof },
             });
             return { ok: true, released: true, id, stage: fresh.stage, proof: fresh.proof };

package/dist/release-next.d.ts

@@ -1,3 +1,4 @@
+import { deployActionOf, type DeployAction } from "./deploy-phase.js";
 import { type RescueWorld } from "./deploy-rescue.js";
 import { type GateReleaseWorld } from "./release-gate.js";
 import { type ReleaseJournal } from "./release.js";
@@ -29,9 +30,8 @@ export type SettleWorld = {
     rescue: RescueWorld;
     gate: GateReleaseWorld;
 };
-export type DeployAction = "none" | "lift-pause" | "forward" | "roll-back" | "refuse";
-/** The one action a deployment's journal calls for. */
-export declare function deployActionOf(phase: unknown): DeployAction;
+/** The one action a deployment's journal calls for: a row of the one phase table (deploy-phase.ts). */
+export { deployActionOf, type DeployAction };
 /** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
 export declare function settleDeployment(world: SettleWorld, say: (line: string) => void): Promise<{
     ok: true;

package/dist/release-next.js

@@ -11,8 +11,9 @@
 import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
-import { FORWARD_ONLY, rescueDeployment } from "./deploy-rescue.js";
-import { BEFORE_SWAP, releaseGate } from "./release-gate.js";
+import { deployActionOf } from "./deploy-phase.js";
+import { rescueDeployment } from "./deploy-rescue.js";
+import { releaseGate } from "./release-gate.js";
 import { journalFile, readJournal } from "./release.js";
 import { autoPublishHeld, PUBLISH_ALLOWED_ACTION } from "./release-auto.js";
 import { sameMachineHost } from "./machine-identity.js";
@@ -78,18 +79,8 @@ export async function takeReleaseRun(stateDir, branch, say, seams = {}) {
         await sleep(seams.pollMs ?? 5_000);
     }
 }
-/** The one action a deployment's journal calls for. */
-export function deployActionOf(phase) {
-    if (typeof phase !== "string")
-        return "refuse";
-    if (phase === "released" || phase === "deployed")
-        return "none";
-    if (BEFORE_SWAP.includes(phase))
-        return "lift-pause";
-    if (FORWARD_ONLY.includes(phase))
-        return "forward";
-    return "roll-back";
-}
+/** The one action a deployment's journal calls for: a row of the one phase table (deploy-phase.ts). */
+export { deployActionOf };
 /** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
 export async function settleDeployment(world, say) {
     const open = world.rescue.journals().filter(one => deployActionOf(one.journal?.["phase"]) !== "none");
@@ -99,8 +90,14 @@ export async function settleDeployment(world, say) {
         return { ok: false, message: `${open.length} deployments are unfinished: ${open.map(one => one.stage).join(", ")}. Nothing was changed.` };
     const { stage, journal } = open[0];
     const action = deployActionOf(journal?.["phase"]);
-    if (action === "refuse")
-        return { ok: false, message: `The deployment journal in ${stage} can't be read. Nothing was changed.` };
+    if (action === "refuse") {
+        // A word this version's table does not hold (a newer candidate's, or damage) is never acted on by itself: the
+        // deployment's own recovery knows its own phases, and the person starts it.
+        const phase = journal?.["phase"];
+        return typeof phase === "string"
+            ? { ok: false, message: `The deployment in ${stage} stopped at a step this version doesn't know (${/^[a-z-]{1,40}$/.test(phase) ? phase : "not a plain word"}). Nothing was changed. Its own recovery can decide: \`toolroll release --recover-deploy --yes\`.` }
+            : { ok: false, message: `The deployment journal in ${stage} can't be read. Nothing was changed.` };
+    }
     if (action === "forward") {
         say("Finishing the deployment that was under way.");
         return { ok: true };

package/dist/staged-runtimes.js

@@ -12,6 +12,7 @@ import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSyn
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
+import { isDeployed } from "./deploy-phase.js";
 import { quarantine, quarantineEntries, claimQuarantine, releaseQuarantine, restoreQuarantine, deleteQuarantineSync } from "./sweep-quarantine.js";
 import { processCensus } from "./run-closeout.js";
 const DAY_MS = 86_400_000;
@@ -84,7 +85,7 @@ function readStage(path, name, fallbackAt) {
             at = 0;
         }
     }
-    const finished = deploy !== null ? deploy["phase"] === "deployed" : update !== null ? typeof update["finishedAt"] === "string" : false;
+    const finished = deploy !== null ? isDeployed(deploy["phase"]) : update !== null ? typeof update["finishedAt"] === "string" : false;
     const from = update?.["from"];
     const prior = typeof deploy?.["priorRuntime"] === "string" ? deploy["priorRuntime"] : typeof from?.dist === "string" ? from.dist : null;
     let keptAside = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.98",
+  "version": "0.9.99",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"