@agentpulselabs/cli-plugin-pulse 1.1.2 → 1.1.5

package/README.md

@@ -89,6 +89,15 @@ These need your team's Pulse cloud-first flag on, set by a team owner or admin,
 
 Everything sent goes through the same secret and path filter as the mirror, and the cloud filters it again.
 
+## Cutover through the daemon (1.1.3)
+
+`agentpulse pulse cutover` and `--rollback` ask the running Pulse daemon to do the work, so the command itself never needs `launchctl` or a permission prompt. Only `--dry-run`, which only reads, runs in the command.
+
+- The command writes an owner-only `cutover.request` (`id`, `mode`, `requestedAt`, `requestedBy`), one at a time. It then follows `cutover.json`, printing each step as an in-process run would, and exits with the run's result: 0 when it is done, or 1 with the run's error code when the run fails, the daemon refuses the request, or nobody takes it within 2 minutes (the request is then withdrawn). It exits 2 when it cannot tell how the run ended: the daemon stopped, or 2 hours passed.
+- The daemon takes one request at a time, and runs it beside its heartbeat. It refuses a request that is more than 10 minutes old, a duplicate, a malformed request, or a rollback with nothing to roll back; the reason is listed under `refusals` in `cutover.json`. It unloads only the old hub's LaunchAgents (`com.agentpulse.agents-hub`, `com.agentpulse.keepawake`), never its own, and then serves 127.0.0.1:8890 itself. `daemon-health.json` shows `cutover: { state, step, requestId }`. A restart asked for while a cutover runs waits until the cutover ends.
+- If the daemon stops in the middle of a request, it finishes the request when it starts again, and records what it did under `recovery`. A cutover that had begun is rolled back, including one stopped after its last check passed. A rollback is run again unless it had begun loading the old hub. In that case the daemon only checks that the old hub holds the port, and otherwise leaves it to you, because restoring `hub.db` again could lose what the old hub has written since.
+- With a daemon older than 1.1.3, or with `--in-process`, the command runs the cutover itself as 1.1.2 did, which needs `launchctl`.
+
 ## Bus identity and delivery states (1.1.1)
 
 After cutover the runner hosts the bus, and `hub.mjs bus` works as before with these additions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpulselabs/cli-plugin-pulse",
-  "version": "1.1.2",
+  "version": "1.1.5",
   "description": "AgentPulse CLI plugin for installing and operating the Pulse local connector (replaces the deprecated build-discipline Pulse plugin).",
   "type": "module",
   "license": "MIT",
@@ -21,8 +21,9 @@
   "scripts": {
     "test": "node --import ./test/support/register-loader.mjs --test \"test/*.test.js\" \"test/hub/*.test.js\"",
     "contract:check": "node scripts/sync-contract.mjs --local",
-    "check": "node --check src/commands/pulse/install.js && node --check src/commands/pulse/pair.js && node --check src/commands/pulse/login.js && node --check src/commands/pulse/start.js && node --check src/commands/pulse/status.js && node --check src/commands/pulse/doctor.js && node --check src/commands/pulse/stop.js && node --check src/commands/pulse/restart.js && node --check src/lib/selfRestart.js && node --check src/lib/subprocess.js && node --check src/lib/daemonProcess.js && node --check src/commands/pulse/mirror.js && node --check src/commands/pulse/hub-write.js && node --check src/lib/localHubWriter.js && node --check src/lib/hubActions.js && node --check src/lib/localHub.js && node --check src/lib/pathRedaction.js && node --check src/lib/rulePacks.js && node --check src/lib/mirrorContract.js && node --check src/lib/graphWindows.js && node --check src/lib/mirrorSource.js && node --check src/lib/mirrorSync.js && node --check src/lib/mirrorService.js && node --check src/lib/mirrorDaemon.js && node --check src/lib/daemonComposition.js && node --check src/lib/daemonRuntime.js && node --check src/lib/daemonLoop.js && node --check src/daemon/main.js && node --check src/lib/sqlite.js && node --check src/lib/nodeFloor.js && node --check src/lib/runnerStore.js && node --check src/lib/hubDbReader.js && node --check src/lib/channelScanner.js && node --check src/lib/uploadRedactor.js && node --check src/lib/hubScan.js && node --check src/lib/outboxFlusher.js && node --check src/lib/hubSnapshot.js && node --check src/lib/reconcileView.js && node --check src/lib/reconcile.js && node --check src/lib/shadowService.js && node --check src/lib/cloudFirstCommands.js && node --check src/commands/pulse/import.js && node --check src/commands/pulse/shadow.js && node --check src/commands/pulse/parity.js && node --check src/runner/main.js && node --check src/runner/runnerProcess.js && node --check src/runner/facade.js && node --check src/runner/bridge.js && node --check src/runner/runnerChild.js && node --check src/runner/applier.js && node --check src/runner/capture.js && node --check src/runner/hubCapture.js && node --check src/clients/hub.mjs && node --check src/clients/hub-bridge.mjs && node --check src/runner/busIdentity.js && node --check src/runner/deliveryStates.js && node --check src/lib/doctorWarnings.js && node --check src/hub/lib/closure.mjs && node --check src/runner/channelDiscipline.js",
+    "check": "node --check src/commands/pulse/install.js && node --check src/commands/pulse/pair.js && node --check src/commands/pulse/login.js && node --check src/commands/pulse/start.js && node --check src/commands/pulse/status.js && node --check src/commands/pulse/doctor.js && node --check src/commands/pulse/stop.js && node --check src/commands/pulse/restart.js && node --check src/lib/selfRestart.js && node --check src/lib/subprocess.js && node --check src/lib/daemonProcess.js && node --check src/commands/pulse/mirror.js && node --check src/commands/pulse/hub-write.js && node --check src/lib/localHubWriter.js && node --check src/lib/hubActions.js && node --check src/lib/localHub.js && node --check src/lib/pathRedaction.js && node --check src/lib/rulePacks.js && node --check src/lib/mirrorContract.js && node --check src/lib/graphWindows.js && node --check src/lib/mirrorSource.js && node --check src/lib/mirrorSync.js && node --check src/lib/mirrorService.js && node --check src/lib/mirrorDaemon.js && node --check src/lib/daemonComposition.js && node --check src/lib/daemonRuntime.js && node --check src/lib/daemonLoop.js && node --check src/daemon/main.js && node --check src/lib/sqlite.js && node --check src/lib/nodeFloor.js && node --check src/lib/runnerStore.js && node --check src/lib/hubDbReader.js && node --check src/lib/channelScanner.js && node --check src/lib/uploadRedactor.js && node --check src/lib/hubScan.js && node --check src/lib/outboxFlusher.js && node --check src/lib/hubSnapshot.js && node --check src/lib/reconcileView.js && node --check src/lib/reconcile.js && node --check src/lib/shadowService.js && node --check src/lib/cutover.js && node --check src/lib/cutoverWiring.js && node --check src/lib/cutoverRequest.js && node --check src/commands/pulse/cutover.js && node --check src/lib/cloudFirstCommands.js && node --check src/commands/pulse/import.js && node --check src/commands/pulse/shadow.js && node --check src/commands/pulse/parity.js && node --check src/runner/main.js && node --check src/runner/runnerProcess.js && node --check src/runner/facade.js && node --check src/runner/bridge.js && node --check src/runner/runnerChild.js && node --check src/runner/applier.js && node --check src/runner/capture.js && node --check src/runner/loopMonitor.js && node --check src/runner/channelWalk.js && node --check src/runner/serial.js && node --check src/runner/directoryCache.js && node --check src/runner/hubCapture.js && node --check src/clients/hub.mjs && node --check src/clients/hub-bridge.mjs && node --check src/runner/busIdentity.js && node --check src/runner/deliveryStates.js && node --check src/lib/doctorWarnings.js && node --check src/hub/lib/closure.mjs && node --check src/runner/channelDiscipline.js",
     "test:t2": "node --import ./test/support/register-loader.mjs --test --test-timeout=120000 \"test/t2/*.test.js\"",
+    "test:perf": "node --import ./test/support/register-loader.mjs --test --test-concurrency=1 --test-timeout=900000 \"test/perf/*.test.js\"",
     "test:t3": "node --import ./test/support/register-loader.mjs --test --test-concurrency=1 --test-timeout=240000 \"test/t3/*.test.js\""
   },
   "engines": {

package/src/commands/pulse/cutover.js

@@ -1,10 +1,13 @@
+import path from 'node:path';
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../lib/BaseCommand.js';
 import { defaultConfigDirectory } from '../../lib/application.js';
+import { FOLLOW_UNKNOWN_EXIT, followCutoverRequest, takesCutoverRequests, writeCutoverRequest } from '../../lib/cutoverRequest.js';
 import { createCutover } from '../../lib/cutoverWiring.js';
+import { readOwnerOnlyJson } from '../../lib/storage.js';
 
 export default class PulseCutover extends BaseCommand {
-  static description = 'Move this machine\'s local Agent Hub into the Pulse daemon (a short freeze, a backup kept), check first with --dry-run, or go back with --rollback (restores the backup; loses only what was written after the switch).';
+  static description = 'Move this machine\'s local Agent Hub into the Pulse daemon (a short freeze, a backup kept), check first with --dry-run, or go back with --rollback (restores the backup; loses only what was written after the switch). The running daemon does the work, so no launchctl or permission prompt is needed here; --in-process runs it in this process instead.';
   static examples = [
     '<%= config.bin %> pulse cutover --dry-run',
     '<%= config.bin %> pulse cutover --smoke-channel agentpulse-agent-hub/cf-phase3',
@@ -14,26 +17,47 @@ export default class PulseCutover extends BaseCommand {
     'dry-run': Flags.boolean({ description: 'Check everything and say what would change; change nothing', default: false }),
     rollback: Flags.boolean({ description: 'Back to the local hub from the backup', default: false, exclusive: ['dry-run'] }),
     'smoke-channel': Flags.string({ description: 'A task channel (<repo>/<task>) for the smoke test\'s one channel post' }),
+    'in-process': Flags.boolean({ description: 'Run the cutover in this process, as Pulse 1.1.2 did, instead of asking the daemon (needs launchctl)', default: false }),
   };
 
   async run() {
     const { flags } = await this.parse(PulseCutover);
-    const cutover = this.cutover || await createCutover({ configDir: defaultConfigDirectory(), log: (event, details) => this.log(`${event} ${JSON.stringify(details)}`) });
+    const configDir = this.configDir || defaultConfigDirectory();
+    const log = (event, details) => this.log(`${event} ${JSON.stringify(details)}`);
+    const inProcess = async () => this.cutover || createCutover({ configDir, log });
     if (flags['dry-run']) {
-      const report = await cutover.dryRun();
+      const report = await (await inProcess()).dryRun();
       for (const check of report.checks) this.log(`${check.ok ? 'ok  ' : 'FAIL'} ${check.name}${check.detail ? `: ${check.detail}` : ''}${!check.ok && check.fix ? ` (fix: ${check.fix})` : ''}`);
       this.log(`Outage while it runs: ${report.outage.what}; at most ${Math.round(report.outage.boundMs / 60_000)} min.`);
       this.log(report.message);
       if (!report.ok) process.exitCode = 1;
       return report;
     }
-    if (flags.rollback) {
-      const report = await cutover.rollback();
-      this.log(report.message);
-      return report;
+    const health = await readOwnerOnlyJson(path.join(configDir, 'daemon-health.json')).catch(() => null);
+    const viaDaemon = !flags['in-process'] && takesCutoverRequests(health);
+    if (!viaDaemon && !flags['in-process']) {
+      this.log(`The Pulse daemon ${health?.connectorVersion ? `(connector ${health.connectorVersion}) ` : ''}does not take cutover requests or is not running; running it in this process.`);
+    }
+    const mode = flags.rollback ? 'rollback' : 'cutover';
+    let result;
+    if (viaDaemon) {
+      const request = await writeCutoverRequest({ configDir, mode, smokeChannel: mode === 'cutover' ? flags['smoke-channel'] ?? null : null, health });
+      this.log(`Asked the Pulse daemon (pid ${health.pid}) to ${mode === 'rollback' ? 'roll back' : 'cut over'}: request ${request.id}.`);
+      try {
+        result = await followCutoverRequest({ configDir, request, log, ...this.follow });
+      } catch (error) {
+        if (error.exit === FOLLOW_UNKNOWN_EXIT) this.fail(error.code, error.message, error.exit);
+        throw error;
+      }
+    } else {
+      const cutover = await inProcess();
+      result = mode === 'rollback' ? await cutover.rollback() : await cutover.run({ smokeChannel: flags['smoke-channel'] ?? null });
+    }
+    if (mode === 'rollback') {
+      this.log(result.message);
+      return result;
     }
-    const journal = await cutover.run({ smokeChannel: flags['smoke-channel'] ?? null });
-    this.log(`Cut over: the Pulse daemon serves 127.0.0.1:${journal.port}. The backup is ${journal.backup.file}. Go back any time with \`agentpulse pulse cutover --rollback\`.`);
-    return journal;
+    this.log(`Cut over: the Pulse daemon serves 127.0.0.1:${result.port}. The backup is ${result.backup.file}. Go back any time with \`agentpulse pulse cutover --rollback\`.`);
+    return result;
   }
 }

package/src/daemon/main.js

@@ -10,6 +10,7 @@ const MIRROR_FAILURES = new Set(['mirror_failed', 'mirror_blocked', 'mirror_stre
 const ERROR_EVENTS = new Set([
   'job_failed', 'job_refused', 'job_settle_failed', 'cycle_stalled', 'drain_timed_out', 'daemon_start_failed',
   'daemon_shutdown_failed', 'source_watch_refused', 'source_watch_failed',
+  'cutover_failed', 'cutover_request_failed', 'cutover_request_refused', 'cutover_interrupted', 'cutover_service_failed',
 ]);
 
 /** One redacted line per job, local hub or restart event; failures go to daemon-error.log, the rest to daemon.log. */

package/src/hub/core/db.mjs

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { isBusy } from './ticks.mjs';
 
 export const SCHEMA_VERSION = 1;
 
@@ -231,22 +232,37 @@ export function withTx(db, fn, label = null) {
 }
 
 const pause = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+/** How long a busy chunk of writeInChunks waits before each new try; the wait blocks its thread, the collect worker's. */
+const BUSY_PAUSES_MS = [250, 500, 1000, 2000];
 
 /**
  * Runs `steps` (functions) in as many short write transactions as it takes for none to hold the lock past `budgetMs`,
  * pausing `pauseMs` between them so writers on other connections get in. Inside an open transaction it simply joins it.
- * Returns how many transactions it used.
+ * A chunk that finds the database busy past busy_timeout is rolled back and run again from its first step, after
+ * `busyPausesMs`, so another writer's long transaction delays a pass instead of failing it. Returns how many
+ * transactions it used.
  */
-export function writeInChunks(db, steps, { budgetMs = 50, pauseMs = 15, label = 'chunked write', onPause = null } = {}) {
+export function writeInChunks(db, steps, { budgetMs = 50, pauseMs = 15, label = 'chunked write', onPause = null, busyPausesMs = BUSY_PAUSES_MS } = {}) {
   if (TX.get(db)) { for (const step of steps) step(); return 0; }
   let i = 0;
   let chunks = 0;
+  let busy = 0;
   while (i < steps.length) {
     if (chunks) { pause(pauseMs); if (onPause) onPause(); }
     const started = performance.now();
-    withTx(db, () => {
-      do steps[i++](); while (i < steps.length && performance.now() - started < budgetMs);
-    }, `${label} (chunk ${chunks + 1})`);
+    const first = i;
+    try {
+      withTx(db, () => {
+        do steps[i++](); while (i < steps.length && performance.now() - started < budgetMs);
+      }, `${label} (chunk ${chunks + 1})`);
+    } catch (e) {
+      if (!isBusy(e) || busy >= busyPausesMs.length) throw e;
+      txTiming.log(`${label}: database busy, chunk ${chunks + 1} again in ${busyPausesMs[busy]} ms`);
+      pause(busyPausesMs[busy++]);
+      i = first;
+      continue;
+    }
+    busy = 0;
     chunks++;
   }
   return chunks;

package/src/hub/workers/manager.mjs

@@ -20,6 +20,10 @@ const MAX_OUTPUT = 2 * 1024 * 1024;
 /** Answers took 0.7-9.8 min in one chat resumed for two days; a fresh, small chat answers well inside this. */
 export const RUN_TIMEOUT_MS = 5 * 60e3;
 const MAX_ATTEMPTS = 3;
+/** Claims also count a run's own lapsed claim taken back after a stall; past this many, a message no run finishes is given up. */
+const MAX_CLAIMS = 10;
+/** A run that ends while the lease is away (a stalled runner lapses it for a moment) waits this long for it to come back. */
+export const HELD_WAIT_MS = 60e3;
 /** Runs cut off by restarts do not use up attempts; past this many restarts a message is given up, not looped on. */
 export const MAX_RESTARTS = 3;
 /** Runs at once, one chat each. One, as before: a second question waits one run at most, FYIs none. */
@@ -129,10 +133,19 @@ ${voice || ''}`.trim();
 const topicOf = (sender) => (sender === 'user' ? 'user' : `agent/${sender}`);
 const errorText = (error) => String(error && error.message ? error.message : error);
 
+/** Why a cursor-agent run failed (exit, signal, stderr), never its command line: that holds the whole prompt. */
+function runError(error) {
+  if (!error || !String(error.message || '').startsWith('Command failed:')) return errorText(error);
+  const how = error.killed ? `timed out (${error.signal})` : error.code != null ? `exit ${error.code}` : `signal ${error.signal}`;
+  const said = String(error.stderr || error.stdout || '').trim().split('\n').slice(-3).join(' ').slice(0, 300);
+  return `cursor-agent ${how}${said ? `: ${said}` : ''}`;
+}
+
 export function createManager({
   hub, state, run = runFile, onChange = () => {}, parallel = PARALLEL, now = Date.now, log = console.error, ackRetryMs = RETRY_MS,
   held = () => true,
   fyi = null,
+  heldWaitMs = HELD_WAIT_MS,
 }) {
   const configFile = path.join(state, 'manager.json');
   const statusFile = path.join(state, 'manager-status.json');
@@ -143,6 +156,8 @@ export function createManager({
   const { messaging, registry, leases } = hub;
   /** message id → { message, leaseToken, slot, startedAt, abort } */
   const inflight = new Map();
+  /** message id → { count, error } of its runs that failed; claims alone are no attempts. */
+  const failures = new Map();
   const runs = new Set();
   let lastHeartbeat = 0;
   let timer = null;
@@ -222,6 +237,15 @@ export function createManager({
     }, 'manager answer'), { delaysMs: ackRetryMs, label: `manager answer to ${m.id}`, log });
   }
 
+  /** Only the lease holder settles; a stall that lapsed the lease here gets it back moments later. */
+  async function heldAgain(signal) {
+    for (let waited = 0; !held(); waited += 250) {
+      if (signal.aborted || waited >= heldWaitMs) return false;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return !signal.aborted;
+  }
+
   async function answer(f) {
     const { message: m, slot, abort } = f;
     const chat = await chatFor(slot, abort.signal);
@@ -236,6 +260,10 @@ export function createManager({
     if (envelope && envelope.is_error) throw new Error(`cursor-agent failed: ${String(textOf(envelope) || 'error').slice(0, 300)}`);
     const actions = parseManagerActions(stdout);
     if (!actions.reply) throw new Error('manager returned no reply');
+    if (!(await heldAgain(abort.signal))) {
+      if (!abort.signal.aborted) log(`manager answer to ${m.id} held back: the manager lease is not held here`);
+      return null;
+    }
     await settle(m, actions);
     recordTurn(slot, chat.chatId, m, prompt, actions.reply);
     if (registry.fact('manager-restart', m.id)) registry.dropFact('manager-restart', m.id);
@@ -252,11 +280,16 @@ export function createManager({
     const done = answer(f).then((replied) => ({ replied }), (error) => ({ error })).then(({ replied, error }) => {
       inflight.delete(m.id);
       runs.delete(done);
-      if (f.abort.signal.aborted) return;
-      if (error) log(`manager failed for ${m.id}: ${errorText(error)}`);
+      if (f.abort.signal.aborted) { log(`manager run for ${m.id} was stopped before it finished; it is not counted as a try`); return; }
+      const why = error ? runError(error).slice(0, 500) : null;
+      if (error) {
+        const failed = { count: ((failures.get(m.id) || {}).count || 0) + 1, error: why };
+        failures.set(m.id, failed);
+        log(`manager failed for ${m.id} (try ${failed.count} of ${MAX_ATTEMPTS}): ${why}`);
+      } else if (replied) failures.delete(m.id);
       status({
         ...(replied || {}), state: error ? 'error' : inflight.size ? 'working' : 'online', messageId: error ? m.id : null,
-        error: error ? errorText(error).slice(0, 500) : null, inflight: inflightView(),
+        error: why, inflight: inflightView(), ...(error ? { lastFailure: { id: m.id, from: m.from, error: why, at: now() } } : {}),
       });
     }).catch((e) => log(`manager status after ${m.id} failed: ${errorText(e)}`));
     runs.add(done);
@@ -315,9 +348,14 @@ export function createManager({
       const own = inflight.get(message.id);
       if (own) { own.leaseToken = message.leaseToken; continue; }
       if (isFyi(message)) { if (!(fyi && fyi(message))) messaging.ack('manager', message.id, {}, registry.directory()); continue; }
-      if (message.attempts > MAX_ATTEMPTS) {
-        const last = readJson(statusFile, {}).error || 'unknown error';
-        messaging.ack('manager', message.id, { reply: `I could not answer this after ${MAX_ATTEMPTS} tries, so I stopped retrying. Last error: ${last}`, fromName: 'Manager' }, registry.directory());
+      const failed = failures.get(message.id);
+      if ((failed && failed.count >= MAX_ATTEMPTS) || message.attempts > MAX_CLAIMS) {
+        const tries = failed ? failed.count : message.attempts - 1;
+        const last = failed ? failed.error : `none of its ${tries} runs finished (each was cut off by a restart or a lost lease)`;
+        messaging.ack('manager', message.id, { reply: `I could not answer this after ${tries} tries, so I stopped retrying. Last error: ${last}`, fromName: 'Manager' }, registry.directory());
+        failures.delete(message.id);
+        log(`manager gave up on ${message.id} after ${tries} tries: ${last}`);
+        status({ gaveUp: { id: message.id, from: message.from, tries, error: last, at: t } });
         continue;
       }
       dispatch(message);

package/src/lib/contract.sha256

@@ -1,2 +1,2 @@
-ce1142e1e133c8aff45a999d0d4b67faa6177f420ddcd1b449af81f8e806d8d0  connector-contract.json
+c9db92b38d0c978d4fa18d8a731fadbf3013a19659b524d615583ad099a8fafc  connector-contract.json
 7b7a59c08797c100b46436123dfcb09b517730357fa90cd0890da9b80308faf3  mirror-contract.json

package/src/lib/cutover.js

@@ -5,6 +5,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { clientState, installClients, restoreClients } from './clientInstaller.js';
 import { HubError } from './errors.js';
 import { RunnerStore, SEED_META } from './runnerStore.js';
+import { SERVICE_LABEL } from './serviceManager.js';
 import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
 
 export const CUTOVER_FILE = 'cutover.json';
@@ -20,6 +21,9 @@ export const STEPS = Object.freeze(['sign_in_moved', 'shims_offline', 'hub_unloa
 
 const sha256File = async (file) => createHash('sha256').update(await readFile(file)).digest('hex');
 
+/** What a fresh journal keeps from the last one: the daemon's request history (CUT-03). */
+const carried = (previous) => Object.fromEntries(['requests', 'refusals'].filter((key) => previous?.[key]).map((key) => [key, previous[key]]));
+
 /** `version >= floor` on the numeric x.y.z core; anything unparsable is older. */
 function atLeast(version, floor) {
   const parse = (v) => String(v ?? '').match(/^(\d+)\.(\d+)\.(\d+)/)?.slice(1).map(Number) ?? null;
@@ -34,20 +38,23 @@ function atLeast(version, floor) {
  * a backup kept; `--rollback` restores that backup and the old hub. Every effect goes through an injected seam:
  * `services` (launchd, by label), `probe` (who holds hub.db), `cloudFirst` (Phase 2's final import and reconcile),
  * `daemon` (the facade's health and the old hub's), `smoke`, `backupDb`, `applySpool` and `signIn` (the TokenStore). Each step is journaled in
- * cutover.json before the next starts; a failure at any step after the freeze began rolls back by itself.
+ * cutover.json before the next starts; a failure at any step after the freeze began rolls back by itself. `serve` is
+ * called after each change of `cloudFirst.mode`: run inside the daemon (CUT-03) it starts or stops the daemon's own
+ * runner at once instead of on its next heartbeat.
  */
 export class Cutover {
   constructor({
-    configDir, hubHome, port = 8890, services, probe, cloudFirst, daemon, smoke, backupDb, applySpool, signIn,
+    configDir, hubHome, port = 8890, services, probe, cloudFirst, daemon, smoke, backupDb, applySpool, signIn, serve = async () => {},
     labels = OLD_HUB_LABELS, holderWaitMs = 120_000, facadeWaitMs = 90_000, pollMs = 1_000, now = Date.now, wait = sleep, log = () => {},
   }) {
+    if (labels.includes(SERVICE_LABEL)) throw new HubError('HUB_CUTOVER_LABELS', `The cutover never unloads the Pulse daemon itself (${SERVICE_LABEL})`);
     this.configDir = configDir;
     this.configFile = path.join(configDir, 'config.json');
     this.journalFile = path.join(configDir, CUTOVER_FILE);
     this.hubHome = hubHome;
     this.hubDb = path.join(hubHome, 'state', 'hub.db');
     this.backupFile = `${this.hubDb}${BACKUP_SUFFIX}`;
-    Object.assign(this, { port, services, probe, cloudFirst, daemon, smoke, backupDb, applySpool, signIn, labels, holderWaitMs, facadeWaitMs, pollMs, now, wait, log });
+    Object.assign(this, { port, services, probe, cloudFirst, daemon, smoke, backupDb, applySpool, signIn, serve, labels, holderWaitMs, facadeWaitMs, pollMs, now, wait, log });
   }
 
   async journal() {
@@ -188,11 +195,17 @@ export class Cutover {
     };
   }
 
-  /** The cutover. Resolves with the journal; a failure after the freeze began rolls back and rethrows. */
-  async run({ smokeChannel = null } = {}) {
+  /**
+   * The cutover. Resolves with the journal; a failure after the freeze began rolls back and rethrows. `request` is the
+   * daemon's accepted cutover.request (CUT-03), kept on the journal so its CLI can follow it.
+   */
+  async run({ smokeChannel = null, request = null } = {}) {
     const preflight = await this.dryRun();
     if (!preflight.ok) throw new HubError('HUB_CUTOVER_NOT_READY', preflight.message, { details: { checks: preflight.checks.filter((c) => !c.ok) } });
-    const journal = { state: 'running', startedAt: new Date(this.now()).toISOString(), hubHome: this.hubHome, port: this.port, steps: {}, loadedBefore: [] };
+    const journal = {
+      state: 'running', startedAt: new Date(this.now()).toISOString(), hubHome: this.hubHome, port: this.port, steps: {}, loadedBefore: [],
+      runBy: request ? 'daemon' : 'cli', pid: process.pid, ...carried(await this.journal()), ...(request ? { request } : {}),
+    };
     await writeOwnerOnlyJson(this.journalFile, journal);
     try {
       // Before the freeze: the sign-in moves to this config's own Keychain item (the 12:52 DECISION); no outage.
@@ -240,6 +253,7 @@ export class Cutover {
         cloudFirst: { ...(config.cloudFirst || {}), mode: 'runner', hubHome: this.hubHome, port: this.port, cutoverSeq, seedFrom: this.backupFile, seedSha256: journal.backup.sha256, shadow: false },
       });
       journal.cutoverSeq = cutoverSeq;
+      await this.serve();
       const serving = this.now() + this.facadeWaitMs;
       while (!(await this.daemon.facadeUp(this.port))) {
         if (this.now() >= serving) throw new HubError('HUB_CUTOVER_FACADE', `the Pulse daemon did not serve 127.0.0.1:${this.port} within ${this.facadeWaitMs} ms`);
@@ -271,27 +285,33 @@ export class Cutover {
    */
   async rollback({ reason = 'asked' } = {}) {
     const journal = await this.journal();
-    const report = { command: 'cutover', rollback: true, reason, steps: [] };
-    const step = (name, detail = {}) => { report.steps.push({ name, ...detail }); this.log('rollback_step', { name, ...detail }); };
+    const report = { command: 'cutover', rollback: true, reason, startedAt: new Date(this.now()).toISOString(), steps: [] };
+    // Each step is journaled as it ends, so a CLI following a daemon's rollback (CUT-03) prints it.
+    const step = async (name, detail = {}) => {
+      report.steps.push({ name, ...detail });
+      await writeOwnerOnlyJson(this.journalFile, { ...journal, rollback: report });
+      this.log('rollback_step', { name, ...detail });
+    };
     const config = await this.#config();
     if (config.cloudFirst?.mode === 'runner') {
       await writeOwnerOnlyJson(this.configFile, { ...config, cloudFirst: { ...config.cloudFirst, mode: 'rolled_back' } });
+      await this.serve();
       const deadline = this.now() + this.facadeWaitMs;
       while (await this.daemon.facadeUp(this.port)) {
         if (this.now() >= deadline) throw new HubError('HUB_ROLLBACK_FACADE', `the Pulse daemon still serves 127.0.0.1:${this.port}`);
         await this.wait(this.pollMs);
       }
-      step('daemon_left_port');
+      await step('daemon_left_port');
     }
     if (journal.cutoverAt) {
       const lost = await this.#exportLost(journal.cutoverAt);
       report.lost = lost;
-      step('lost_exported', lost);
+      await step('lost_exported', lost);
     }
     const marked = await this.#markSeedRolledBack();
-    if (marked) step('runner_db_marked', marked);
+    if (marked) await step('runner_db_marked', marked);
     await restoreClients({ hubHome: this.hubHome });
-    step('entry_points_restored');
+    await step('entry_points_restored');
     if (journal.steps?.backed_up && (await stat(this.backupFile).catch(() => null))) {
       for (const suffix of ['-wal', '-shm']) await rm(`${this.hubDb}${suffix}`, { force: true });
       const restored = `${this.hubDb}.pulse-restore`;
@@ -300,13 +320,15 @@ export class Cutover {
       await rm(this.hubDb, { force: true });
       await copyFile(restored, this.hubDb);
       await rm(restored, { force: true });
-      step('hub_db_restored', { from: this.backupFile, sha256: await sha256File(this.backupFile) });
+      await step('hub_db_restored', { from: this.backupFile, sha256: await sha256File(this.backupFile) });
     }
     const spool = await this.applySpool(this.hubDb);
-    step('spool_applied', spool);
+    await step('spool_applied', spool);
     const loadedBefore = journal.loadedBefore?.length ? journal.loadedBefore : this.labels;
+    // Journaled before the first load: from here the old hub may have hub.db open, so it is never restored again.
+    await step('hub_loading', { labels: loadedBefore });
     for (const label of loadedBefore) await this.services.restoreLabel(label);
-    step('hub_loaded', { labels: loadedBefore });
+    await step('hub_loaded', { labels: loadedBefore });
     const deadline = this.now() + this.facadeWaitMs;
     while (!(await this.daemon.oldHubUp(this.port, { timeoutMs: ROLLBACK_PROBE_MS }))) {
       if (this.now() >= deadline) {
@@ -317,7 +339,7 @@ export class Cutover {
       }
       await this.wait(this.pollMs);
     }
-    step('hub_serving');
+    await step('hub_serving');
     report.message = report.lost?.count
       ? `Rolled back to the local hub. ${report.lost.count} write(s) made after the switch (${Object.entries(report.lost.kinds).map(([kind, n]) => `${kind} ${n}`).join(', ')}) are not in hub.db; they are listed in ${report.lost.file}.`
       : 'Rolled back to the local hub. Nothing written after the switch was lost.';
@@ -325,6 +347,19 @@ export class Cutover {
     return report;
   }
 
+  /**
+   * CUT-03 boot recovery of a rollback that had begun loading the old hub: whether the old hub holds the port again
+   * (it answers, or it is hung but owned by its job), waiting up to facadeWaitMs. Reads only.
+   */
+  async verifyRolledBack() {
+    const deadline = this.now() + this.facadeWaitMs;
+    for (;;) {
+      const onPort = await this.#oldHubOnPort();
+      if (onPort.ok || this.now() >= deadline) return onPort;
+      await this.wait(this.pollMs);
+    }
+  }
+
   /**
    * After the runner left the port: the seed is marked rolled back, so the next cutover replaces it with its own
    * backup instead of serving this attempt's state (B1). Null when runner.db was never seeded.