@agentpulselabs/cli-plugin-pulse 1.1.2 → 1.1.3

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.3",
   "description": "AgentPulse CLI plugin for installing and operating the Pulse local connector (replaces the deprecated build-discipline Pulse plugin).",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
   "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/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:t3": "node --import ./test/support/register-loader.mjs --test --test-concurrency=1 --test-timeout=240000 \"test/t3/*.test.js\""
   },

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/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.

package/src/lib/cutoverRequest.js

@@ -0,0 +1,485 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { chmod, link, open, rename, rm, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CUTOVER_FILE, STEPS } from './cutover.js';
+import { HubError } from './errors.js';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+export const CUTOVER_REQUEST_FILE = 'cutover.request';
+/** A request the daemon renamed off the disk to read it; one a crash leaves behind is refused on start, never run. */
+export const CUTOVER_CLAIMED_FILE = 'cutover.request.claimed';
+/** The request protocol a daemon serves, in every heartbeat; a daemon without it gets the cutover run in-process. */
+export const CUTOVER_PROTOCOL = 1;
+export const REQUEST_STALE_MS = 10 * 60_000;
+/** The exit code of a follow that cannot tell how the request ended (timed out, or the daemon stopped). */
+export const FOLLOW_UNKNOWN_EXIT = 2;
+const FUTURE_SLACK_MS = 60_000;
+const HEALTH_FRESH_MS = 60_000;
+const MODES = new Set(['cutover', 'rollback']);
+const SMOKE_CHANNEL = /^[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/;
+const HISTORY = 50;
+const TICK_MS = 2_000;
+const ACCEPT_MS = 2 * 60_000;
+// The worst case of one request: holders (2 min), the final import (its 60 min wait), the reconcile (10 min), the
+// facade (90 s) and smoke, then the rollback that follows a failure (facade 90 s, spool 2 min, hub 90 s): about 80 min.
+const FOLLOW_MS = 2 * 3_600_000;
+const POLL_MS = 1_000;
+
+const iso = (ms) => new Date(ms).toISOString();
+const atOrAfter = (when, since) => Date.parse(when) >= Date.parse(since);
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** Rollback steps from which the old hub may have hub.db open: a rollback that reached one is never run again. */
+const RELOADING = new Set(['hub_loading', 'hub_loaded', 'hub_serving']);
+
+/** The steps of the rollback journaled since `since` (this request's), by name. */
+function rollbackProgress(journal, since) {
+  const rollback = journal.rollback;
+  return rollback?.startedAt && atOrAfter(rollback.startedAt, since) ? rollback.steps.map((entry) => entry.name) : [];
+}
+
+/** The health state a finished request left. */
+function endState(request) {
+  const { outcome } = request;
+  if (outcome.state === 'done') return request.mode === 'cutover' ? 'serving' : 'rolled_back';
+  return outcome.rolledBack ? 'rolled_back' : 'failed';
+}
+
+/**
+ * The daemon's side of `pulse cutover` (CUT-03). It serves cutover.request on its own timer, beside the heartbeat, so
+ * the runner a cutover switches on can start while the cutover waits for it. One request runs at a time, in this
+ * process, with the real Cutover from `createCutover({ log })`, and only while `canTake()` (no restart is pending).
+ * A request is claimed by renaming it off the disk, checked, then recorded in cutover.json (`request`, and its id in
+ * `requests`) before the claimed file is deleted, so a crash never runs it twice; a stale, duplicate, malformed or
+ * pointless one is refused into `refusals`. On start, a request a crash cut off is finished as 1.1.2 would after a
+ * failure (the 20:05:57 DECISION): a cutover that had begun rolls back, a rollback runs again, unless either had begun
+ * loading the old hub (`hub_loading`): restoring hub.db under it would lose its writes, so boot only checks that the old
+ * hub holds the port and records rolled_back, or HUB_ROLLBACK_INTERRUPTED for a human. Each boot action is recorded in
+ * the journal's `recovery` and in health.
+ */
+export class CutoverService {
+  constructor({ directory, createCutover, canTake = () => true, now = Date.now, tickMs = TICK_MS, log = () => {} }) {
+    this.directory = directory;
+    this.createCutover = createCutover;
+    this.canTake = canTake;
+    this.now = now;
+    this.tickMs = tickMs;
+    this.log = log;
+    this.journalFile = path.join(directory, CUTOVER_FILE);
+    this.requestFile = path.join(directory, CUTOVER_REQUEST_FILE);
+    this.claimedFile = path.join(directory, CUTOVER_CLAIMED_FILE);
+    this.timer = null;
+    this.running = null;
+    this.recovered = false;
+    this.stopped = false;
+    this.active = false;
+    this.state = null;
+  }
+
+  start() {
+    this.stopped = false;
+    this.#schedule(0);
+  }
+
+  /** Stops taking requests. A cutover running now is not waited for: one cut off is finished by the next start. */
+  async stop() {
+    this.stopped = true;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  /** Whether a request is running: the daemon holds any restart until it ends. */
+  busy() {
+    return this.active;
+  }
+
+  /** `{ state, step, requestId }` for daemon-health.json, or null before any request. */
+  health() {
+    return this.state;
+  }
+
+  #schedule(waitMs) {
+    clearTimeout(this.timer);
+    if (this.stopped) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.tick().finally(() => this.#schedule(this.tickMs));
+    }, waitMs);
+    this.timer.unref?.();
+  }
+
+  /** One pass: finish what a crash cut off (first pass only), then take one request if there is one. Never rejects. */
+  tick() {
+    this.running ??= this.#pass().finally(() => {
+      this.running = null;
+    });
+    return this.running;
+  }
+
+  async #pass() {
+    try {
+      if (!this.recovered) {
+        this.recovered = true;
+        await this.#recover();
+      }
+      if (this.stopped || !this.canTake()) return;
+      try {
+        await rename(this.requestFile, this.claimedFile);
+      } catch (error) {
+        if (error.code === 'ENOENT') return;
+        throw error;
+      }
+      await this.#take();
+    } catch (error) {
+      this.log('cutover_service_failed', { code: error.code || 'HUB_CUTOVER_SERVICE_FAILED', message: String(error.message).slice(0, 200) });
+    }
+  }
+
+  async #journal() {
+    return (await readOwnerOnlyJson(this.journalFile)) || { state: 'none', steps: {} };
+  }
+
+  async #claimed() {
+    try {
+      return { request: await readOwnerOnlyJson(this.claimedFile) };
+    } catch (error) {
+      return { request: null, unreadable: error.code === 'HUB_INVALID_CONFIG' ? 'not JSON' : `${error.code || 'unreadable'}: ${String(error.message).slice(0, 120)}` };
+    }
+  }
+
+  /** Why this request is refused, or null. */
+  #refusal(request, journal) {
+    if (!request || typeof request !== 'object') return 'invalid: not a JSON object';
+    if (typeof request.id !== 'string' || !/^[A-Za-z0-9._:-]{1,100}$/.test(request.id)) return 'invalid: no usable id';
+    if (!MODES.has(request.mode)) return `invalid: mode ${JSON.stringify(request.mode ?? null)} is neither cutover nor rollback`;
+    if (request.smokeChannel != null && !(typeof request.smokeChannel === 'string' && SMOKE_CHANNEL.test(request.smokeChannel))) {
+      return 'invalid: smokeChannel is not <repo>/<task>';
+    }
+    const at = Date.parse(request.requestedAt);
+    if (!Number.isFinite(at)) return 'invalid: no requestedAt';
+    if (at - this.now() > FUTURE_SLACK_MS) return `invalid: requestedAt ${request.requestedAt} is in the future`;
+    const ageMs = this.now() - at;
+    if (ageMs > REQUEST_STALE_MS) return `stale: requested ${Math.round(ageMs / 60_000)} min ago, more than ${REQUEST_STALE_MS / 60_000} min`;
+    if (journal.request?.id === request.id || (journal.requests || []).includes(request.id)) return `duplicate: request ${request.id} was already taken`;
+    const ended = journal.request?.outcome?.at;
+    if (ended && at < Date.parse(ended)) return `arrived while another request ran: requested ${request.requestedAt}, before request ${journal.request.id} ended at ${ended}`;
+    if (journal.state === 'running' && journal.runBy === 'cli' && Number.isInteger(journal.pid) && pidAlive(journal.pid)) {
+      return `busy: pid ${journal.pid} is running a cutover in-process (started ${journal.startedAt})`;
+    }
+    if (request.mode === 'rollback') {
+      if (journal.state === 'none' || journal.state === 'rolled_back') return `nothing to roll back: cutover.json is ${journal.state}`;
+      if ((journal.rollback?.steps || []).some((entry) => RELOADING.has(entry.name))) {
+        return 'a rollback already loaded the old hub again: another would restore hub.db under it; check it by hand';
+      }
+    }
+    return null;
+  }
+
+  async #take() {
+    const { request, unreadable } = await this.#claimed();
+    const journal = await this.#journal();
+    const reason = unreadable ? `invalid: ${unreadable}` : this.#refusal(request, journal);
+    if (reason) {
+      await this.#refuse(request, reason, journal);
+      await rm(this.claimedFile, { force: true });
+      return;
+    }
+    // A restart requested while this was read: the request goes back for the next process, or is refused if it can't.
+    if (this.stopped || !this.canTake()) {
+      const back = await link(this.claimedFile, this.requestFile).then(() => true, () => false);
+      if (!back) await this.#refuse(request, 'the Pulse daemon is restarting; ask again once it is back', journal);
+      await rm(this.claimedFile, { force: true });
+      return;
+    }
+    this.active = true;
+    try {
+      const accepted = {
+        id: request.id, mode: request.mode, requestedAt: request.requestedAt, requestedBy: request.requestedBy ?? null,
+        ...(request.mode === 'cutover' && request.smokeChannel ? { smokeChannel: request.smokeChannel } : {}),
+        acceptedAt: iso(this.now()),
+      };
+      await writeOwnerOnlyJson(this.journalFile, { ...journal, request: accepted, requests: [...(journal.requests || []), accepted.id].slice(-HISTORY) });
+      await rm(this.claimedFile, { force: true });
+      this.log('cutover_request_accepted', { id: accepted.id, mode: accepted.mode });
+      await this.#perform(accepted, accepted.mode);
+    } finally {
+      this.active = false;
+    }
+  }
+
+  async #refuse(request, reason, journal) {
+    const refusal = {
+      id: typeof request?.id === 'string' ? request.id : null, mode: request?.mode ?? null, requestedAt: request?.requestedAt ?? null,
+      reason, at: iso(this.now()),
+    };
+    await writeOwnerOnlyJson(this.journalFile, { ...journal, refusals: [...(journal.refusals || []), refusal].slice(-HISTORY) });
+    this.state = { state: 'refused', requestId: refusal.id, reason };
+    this.log('cutover_request_refused', { id: refusal.id, reason });
+  }
+
+  /**
+   * Runs `action` (cutover or rollback) for an accepted request and records its outcome on the journal. `asOutcome`
+   * is what a rollback that finishes a cut-off cutover reports, rolled back, instead of a plain done; `recovered` names
+   * the boot action that started it, for health.
+   */
+  async #perform(request, action, { asOutcome = null, recovered = null } = {}) {
+    const tag = recovered ? { recovered } : {};
+    this.state = { state: 'running', mode: action, step: null, requestId: request.id, since: iso(this.now()), ...tag };
+    const log = (event, details = {}) => {
+      if (event === 'cutover_step') this.state = { ...this.state, step: details.step };
+      if (event === 'rollback_step') this.state = { ...this.state, phase: 'rollback', step: details.name };
+      this.log(event, details);
+    };
+    // Health says how it ended before the journal does, so whoever sees the outcome sees the same in health.
+    try {
+      const cutover = await this.createCutover({ log });
+      if (action === 'cutover') {
+        await cutover.run({ smokeChannel: request.smokeChannel ?? null, request });
+        this.state = { state: 'serving', step: this.state.step, requestId: request.id, ...tag };
+        await this.#finish(request.id, { state: 'done' });
+        return;
+      }
+      const report = await cutover.rollback({ reason: asOutcome?.code ?? 'asked' });
+      this.state = { state: 'rolled_back', step: this.state.step, requestId: request.id, ...tag };
+      await this.#finish(request.id, asOutcome ? { ...asOutcome, rolledBack: true } : { state: 'done', message: report.message });
+    } catch (error) {
+      const code = error.code || 'HUB_CUTOVER_FAILED';
+      this.state = { state: error.rollback ? 'rolled_back' : 'failed', step: this.state.step, requestId: request.id, code, ...tag };
+      this.log('cutover_request_failed', { id: request.id, code });
+      await this.#finish(request.id, {
+        state: 'failed', code, message: String(error.message).slice(0, 500), rolledBack: Boolean(error.rollback),
+        ...(error.details?.checks ? { checks: error.details.checks } : {}),
+      });
+    }
+  }
+
+  /** Records the request's outcome on the journal, with `extra` journal fields (a boot recovery's). */
+  async #finish(id, outcome, extra = {}) {
+    const journal = await this.#journal();
+    const request = journal.request?.id === id ? journal.request : { id };
+    await writeOwnerOnlyJson(this.journalFile, { ...journal, ...extra, request: { ...request, outcome: { ...outcome, at: iso(this.now()) } } });
+  }
+
+  /** A boot recovery that ends the request without running anything: the outcome and what boot did, in both files. */
+  async #recovered(request, action, outcome, state, extra = {}) {
+    const recovery = { at: iso(this.now()), requestId: request.id, action };
+    this.state = { state, requestId: request.id, recovered: action, ...(outcome.code ? { code: outcome.code } : {}) };
+    this.log('cutover_recovered', { id: request.id, action });
+    await this.#finish(request.id, outcome, { ...extra, recovery });
+  }
+
+  /** On start: a claim a crash left is refused; a request that was running is finished (see the class). */
+  async #recover() {
+    const claimed = await this.#claimed();
+    if (claimed.request || claimed.unreadable) {
+      const journal = await this.#journal();
+      if (!(claimed.request && (journal.requests || []).includes(claimed.request.id))) {
+        await this.#refuse(claimed.request, 'interrupted: the daemon stopped while it was reading this request', journal);
+      }
+      await rm(this.claimedFile, { force: true });
+    }
+    const journal = await this.#journal();
+    const request = journal.request;
+    if (!request?.id) return;
+    if (request.outcome) {
+      this.state = { state: endState(request), requestId: request.id, ...(request.outcome.code ? { code: request.outcome.code } : {}) };
+      return;
+    }
+    const since = request.acceptedAt;
+    const began = Boolean(journal.startedAt) && atOrAfter(journal.startedAt, since);
+    const rolledBack = journal.state === 'rolled_back' && atOrAfter(journal.rolledBackAt, since);
+    const reloading = rollbackProgress(journal, since).some((name) => RELOADING.has(name));
+    const failure = journal.failure ?? { code: 'HUB_CUTOVER_INTERRUPTED', message: 'The Pulse daemon stopped while it ran this cutover.' };
+    // What a cutover that ended rolled back reports; a rollback request that ended so is simply done.
+    const rolledBackOutcome = (message) => (request.mode === 'rollback'
+      ? { state: 'done', message }
+      : { state: 'failed', code: failure.code, message: failure.message, rolledBack: true });
+    this.active = true;
+    try {
+      if (request.mode === 'cutover' && journal.state === 'done' && began) return await this.#recovered(request, 'finished_before_stop', { state: 'done' }, 'serving');
+      if (rolledBack) return await this.#recovered(request, 'rolled_back_before_stop', rolledBackOutcome(journal.rollback?.message ?? null), 'rolled_back');
+      if (request.mode === 'cutover' && !(journal.state === 'running' && began)) {
+        return await this.#recovered(request, 'never_began', {
+          state: 'failed', code: 'HUB_CUTOVER_INTERRUPTED', message: 'The Pulse daemon stopped before this cutover began; nothing was changed.', rolledBack: false,
+        }, 'failed');
+      }
+      if (reloading) return await this.#verifyReloaded(request, journal, rolledBackOutcome);
+      if (request.mode === 'cutover') {
+        const cutFailure = journal.failure ?? {
+          step: STEPS.find((name) => !journal.steps?.[name]) ?? null, code: 'HUB_CUTOVER_INTERRUPTED',
+          message: 'The Pulse daemon stopped while it ran this cutover; it rolled back on start.',
+        };
+        const recovery = { at: iso(this.now()), requestId: request.id, action: 'rolled_back_on_start' };
+        await writeOwnerOnlyJson(this.journalFile, { ...journal, failure: cutFailure, recovery });
+        this.log('cutover_interrupted', { id: request.id, mode: 'cutover', step: cutFailure.step });
+        return await this.#perform(request, 'rollback', { asOutcome: { state: 'failed', code: 'HUB_CUTOVER_INTERRUPTED', message: cutFailure.message }, recovered: 'rolled_back_on_start' });
+      }
+      await writeOwnerOnlyJson(this.journalFile, { ...journal, recovery: { at: iso(this.now()), requestId: request.id, action: 'rollback_run_again' } });
+      this.log('cutover_interrupted', { id: request.id, mode: 'rollback' });
+      return await this.#perform(request, 'rollback', { recovered: 'rollback_run_again' });
+    } finally {
+      this.active = false;
+    }
+  }
+
+  /**
+   * The 20:05:57 DECISION: a rollback that had begun loading the old hub is never run again (it would restore hub.db
+   * under the running hub). Boot only checks that the old hub holds the port, and records rolled_back if it does.
+   */
+  async #verifyReloaded(request, journal, rolledBackOutcome) {
+    this.state = { state: 'running', mode: 'verify', step: 'hub_loading', requestId: request.id, since: iso(this.now()) };
+    let onPort;
+    try {
+      onPort = await (await this.createCutover({ log: this.log })).verifyRolledBack();
+    } catch (error) {
+      onPort = { ok: false, detail: `the check failed: ${error.code || 'error'}: ${String(error.message).slice(0, 200)}` };
+    }
+    if (onPort.ok) {
+      const at = iso(this.now());
+      const message = `Rolled back to the local hub: the Pulse daemon restarted after the old hub was loaded again, and found it on the port (${onPort.detail}).`;
+      return this.#recovered(request, 'verified_old_hub', rolledBackOutcome(message), 'rolled_back', {
+        state: 'rolled_back', rolledBackAt: at, rollback: { ...journal.rollback, recoveredOnBoot: true, verified: onPort.detail, message },
+      });
+    }
+    return this.#recovered(request, 'old_hub_not_serving', {
+      state: 'failed', code: 'HUB_ROLLBACK_INTERRUPTED', rolledBack: false,
+      message: `The Pulse daemon stopped after its rollback began loading the old hub, and the old hub does not hold the port now (${onPort.detail}). It is not rolled back twice, which would restore hub.db under a hub that may have it open: check the hub by hand.`,
+    }, 'failed');
+  }
+}
+
+/** Whether the daemon behind this health file is alive and serves cutover.request. */
+export function takesCutoverRequests(health, now = Date.now()) {
+  const ageMs = now - Date.parse(health?.heartbeatAt);
+  return ageMs <= HEALTH_FRESH_MS && Number(health?.cutoverProtocol) >= CUTOVER_PROTOCOL;
+}
+
+/** Creates `file` owner-only with `value`, whole or not at all, and only if it does not exist yet. */
+async function createExclusive(file, value) {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  const handle = await open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await chmod(temporary, 0o600);
+    await link(temporary, file);
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw error;
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+/** Writes an owner-only cutover.request for the daemon, exclusively: one request at a time. */
+export async function writeCutoverRequest({ configDir, mode, smokeChannel = null, health = null, now = Date.now, id = randomUUID(), requestedBy = null }) {
+  const pending = (detail) => new HubError('HUB_CUTOVER_PENDING', `Another cutover request is ${detail}; wait for it to finish (see ${path.join(configDir, CUTOVER_FILE)}).`);
+  if (health?.cutover?.state === 'running') throw pending(`running in the Pulse daemon (${health.cutover.requestId}${health.cutover.step ? `, at ${health.cutover.step}` : ''})`);
+  const request = {
+    id, mode, requestedAt: iso(now()),
+    requestedBy: requestedBy ?? { pid: process.pid, session: process.env.CURSOR_CONVERSATION_ID || null },
+    ...(smokeChannel ? { smokeChannel } : {}),
+  };
+  if (!(await createExclusive(path.join(configDir, CUTOVER_REQUEST_FILE), request))) throw pending('waiting for the Pulse daemon');
+  return request;
+}
+
+/**
+ * Follows a request through cutover.json, printing each step as `log(event, details)` exactly as an in-process run
+ * logs it. It resolves with the journal (a cutover) or the rollback report, or throws: the journal's code for a run
+ * that failed (or rolled back), HUB_CUTOVER_REFUSED, or HUB_CUTOVER_NOT_ACCEPTED when nobody took it within
+ * `acceptMs` (it is withdrawn). It ends without an outcome, with `exit` FOLLOW_UNKNOWN_EXIT, when the daemon's heartbeat
+ * goes stale (it finishes the request when it starts again) or after `timeoutMs`, the worst case of a run.
+ */
+export async function followCutoverRequest({
+  configDir, request, log = () => {}, now = Date.now, wait = sleep, pollMs = POLL_MS, acceptMs = ACCEPT_MS, timeoutMs = FOLLOW_MS,
+  healthFreshMs = HEALTH_FRESH_MS,
+}) {
+  const journalFile = path.join(configDir, CUTOVER_FILE);
+  const requestFile = path.join(configDir, CUTOVER_REQUEST_FILE);
+  const healthFile = path.join(configDir, 'daemon-health.json');
+  const started = now();
+  const printed = { steps: new Set(), failure: false, rollback: 0 };
+  let withDaemon = false;
+  const print = (journal) => {
+    const since = journal.request.acceptedAt;
+    if (request.mode === 'cutover' && journal.startedAt && atOrAfter(journal.startedAt, since)) {
+      for (const name of STEPS) {
+        if (!journal.steps?.[name] || printed.steps.has(name)) continue;
+        printed.steps.add(name);
+        const { at: _at, ...detail } = journal.steps[name];
+        log('cutover_step', { step: name, ...detail });
+      }
+      if (journal.failure && !printed.failure) {
+        printed.failure = true;
+        log('cutover_failed', journal.failure);
+      }
+    }
+    if (rollbackProgress(journal, since).length) {
+      for (const entry of journal.rollback.steps.slice(printed.rollback)) log('rollback_step', entry);
+      printed.rollback = journal.rollback.steps.length;
+    }
+  };
+  const unknown = (code, message) => new HubError(code, message, { exit: FOLLOW_UNKNOWN_EXIT });
+  for (;;) {
+    const journal = await readOwnerOnlyJson(journalFile).catch(() => null);
+    const refused = journal?.refusals?.find((entry) => entry.id === request.id);
+    if (refused) throw new HubError('HUB_CUTOVER_REFUSED', `The Pulse daemon refused request ${request.id}: ${refused.reason}`, { details: { refused } });
+    const health = await readOwnerOnlyJson(healthFile).catch(() => null);
+    // A long synchronous stretch (a rescan) can delay a heartbeat; a daemon whose pid is alive gets three windows.
+    const ageMs = now() - Date.parse(health?.heartbeatAt);
+    const stale = !(ageMs <= healthFreshMs) && (!(ageMs <= 3 * healthFreshMs) || !(Number.isInteger(health?.pid) && pidAlive(health.pid)));
+    if (journal?.request?.id === request.id) {
+      print(journal);
+      const outcome = journal.request.outcome;
+      if (outcome?.state === 'done') return request.mode === 'cutover' ? journal : journal.rollback;
+      if (outcome) {
+        throw Object.assign(
+          new HubError(outcome.code || 'HUB_CUTOVER_FAILED', outcome.message || 'the cutover failed', { details: { ...(outcome.checks ? { checks: outcome.checks } : {}), rolledBack: Boolean(outcome.rolledBack) } }),
+          outcome.rolledBack ? { rollback: journal.rollback ?? null } : {},
+        );
+      }
+      if (stale) {
+        throw unknown('HUB_CUTOVER_DAEMON_STOPPED', `The Pulse daemon stopped (last heartbeat ${health?.heartbeatAt ?? 'never'}) while it ran request ${request.id}. When it starts again it finishes the request (a cutover that had begun rolls back); follow it in ${journalFile}.`);
+      }
+    } else if (!withDaemon && (stale || now() - started >= acceptMs)) {
+      // Withdrawn only while it is still ours on the disk: gone means the daemon claimed it, so it is followed.
+      const pending = await readOwnerOnlyJson(requestFile).catch(() => null);
+      let withdrawn = false;
+      if (pending?.id === request.id) {
+        try {
+          await unlink(requestFile);
+          withdrawn = true;
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+      }
+      if (withdrawn) {
+        throw new HubError('HUB_CUTOVER_NOT_ACCEPTED', stale
+          ? `The Pulse daemon is not running (last heartbeat ${health?.heartbeatAt ?? 'never'}), so request ${request.id} was withdrawn. Start it with \`agentpulse pulse start\`.`
+          : `The Pulse daemon did not take request ${request.id} within ${Math.round(acceptMs / 1000)} s, so it was withdrawn. Check it with \`agentpulse pulse status\`.`);
+      }
+      withDaemon = true;
+    } else if (withDaemon && stale) {
+      throw unknown('HUB_CUTOVER_DAEMON_STOPPED', `The Pulse daemon stopped (last heartbeat ${health?.heartbeatAt ?? 'never'}) after it claimed request ${request.id}; when it starts again it refuses or finishes it. Follow it in ${journalFile}.`);
+    }
+    if (now() - started >= timeoutMs) {
+      throw unknown('HUB_CUTOVER_FOLLOW_TIMEOUT', `Request ${request.id} is still running in the Pulse daemon after ${Math.round(timeoutMs / 60_000)} min; follow it in ${journalFile} or with \`agentpulse pulse status\`.`);
+    }
+    await wait(pollMs);
+  }
+}

package/src/lib/cutoverWiring.js

@@ -109,14 +109,17 @@ export function portProbes(tokenFor) {
   };
 }
 
-/** The production seams of `pulse cutover`: launchd, lsof, the Phase 2 import and reconcile, and the local port. */
-export async function createCutover({ configDir, log = () => {}, port = 8890 }) {
+/**
+ * The production seams of `pulse cutover`: launchd, lsof, the Phase 2 import and reconcile, and the local port.
+ * `serve` is the daemon's own runner switch when the daemon runs it (CUT-03); in-process it is left to the heartbeat.
+ */
+export async function createCutover({ configDir, log = () => {}, port = 8890, serve = undefined }) {
   const config = await readOwnerOnlyJson(path.join(configDir, 'config.json'));
   if (!config) throw new HubError('HUB_NOT_INSTALLED', 'Pulse is not installed here; run `agentpulse pulse install`');
   const hubHome = config.cloudFirst?.hubHome || config.mirror?.hub?.dir || (await discoverLocalHub({ config })).dir;
   const tokenFor = () => hubToken(hubHome);
   return new Cutover({
-    configDir, hubHome, port, log,
+    configDir, hubHome, port, log, serve,
     services: new ServiceManager({}),
     probe: { holders: (files) => lsofHolders(files), portOwners: (p) => lsofPortOwners(p) },
     cloudFirst: new CloudFirstCommands({ configDir }),

package/src/lib/daemonProcess.js

@@ -1,4 +1,6 @@
 import path from 'node:path';
+import { CUTOVER_PROTOCOL, CutoverService } from './cutoverRequest.js';
+import { createCutover } from './cutoverWiring.js';
 import { createProductionDependencies } from './daemonComposition.js';
 import { DaemonLock } from './daemonLock.js';
 import { createHeartbeat, MIRROR_UPDATE_STEP, TERMINAL_STATES } from './daemonLoop.js';
@@ -60,7 +62,8 @@ const inside = (child, parent) => {
  * - start_failed: it could not start while it was holding restarts back.
  * A code or request restart drains (no new claim; running jobs finish and settle) for up to drainMs; a stall aborts at
  * once. Every trigger goes through one check that runs each tickMs. While the daemon has restarted too often it holds
- * the restart (health says restart_loop) until the window clears. SIGTERM always wins and exits 0.
+ * the restart (health says restart_loop) until the window clears, and while it runs a cutover request (CUT-03) it holds
+ * it until the cutover ends, whose own deadlines bound it. SIGTERM always wins and exits 0.
  */
 export async function runDaemon({
   directory,
@@ -74,6 +77,8 @@ export async function runDaemon({
   createMirror = (options) => new MirrorController(options),
   createShadow = (options) => new ShadowService(options),
   createRunner = (options) => new RunnerService(options),
+  createCutoverService = (options) => new CutoverService(options),
+  cutoverFactory = createCutover,
   dependencyOptions = {},
   runtimeOptions = {},
   lockOptions = {},
@@ -85,7 +90,7 @@ export async function runDaemon({
   const lock = new DaemonLock({ directory, ...lockOptions });
   await lock.acquire();
   // The first cycle (token exchange, reconnect, claim) can outlast `pulse start`'s wait; say we are up before it.
-  await lock.heartbeat({ state: 'starting' });
+  await lock.heartbeat({ state: 'starting', cutoverProtocol: CUTOVER_PROTOCOL });
   let startingHealthAt = Date.now();
   const guard = new RestartGuard({ directory, now });
   await guard.recordStart();
@@ -99,6 +104,11 @@ export async function runDaemon({
   let runtime = null;
   let shadow = null;
   let runnerService = null;
+  let cutoverService = null;
+  let cutoverDeferralLogged = false;
+  // Every read of config.json is numbered, so the runner never applies one older than it already has (CUT-03).
+  let configGeneration = 0;
+  let heartbeatGeneration = 0;
   let stopServices = async () => {};
   let timer = null;
   let watcher = null;
@@ -207,6 +217,14 @@ export async function runDaemon({
       const requestedAt = await consumeRestartRequest(directory);
       if (requestedAt !== null && requestedAt < bootedAt) log('restart_request_satisfied', { requestedAt: new Date(requestedAt).toISOString() });
       else if (requestedAt !== null) pending ??= { reason: 'request' };
+      if (pending && cutoverService?.busy()) {
+        if (!cutoverDeferralLogged) {
+          cutoverDeferralLogged = true;
+          log('restart_deferred', { reason: pending.reason, cutover: cutoverService.health()?.requestId ?? null });
+        }
+        return;
+      }
+      cutoverDeferralLogged = false;
       if (pending) restart(pending.reason);
     } catch (error) {
       log('restart_check_failed', { code: error.code || 'HUB_RESTART_CHECK_FAILED' });
@@ -217,11 +235,15 @@ export async function runDaemon({
 
   const extraHealth = () => {
     const loop = degraded();
+    const cutover = cutoverService?.health();
     return {
       ...(loop ? { degraded: loop } : {}),
       ...(restarting ? { restarting: { ...restarting, draining: runtime?.activeJobIds() ?? [] } } : {}),
+      ...(pending && cutoverService?.busy() ? { restartDeferred: { reason: pending.reason, untilCutoverEnds: cutover?.requestId ?? null } } : {}),
       ...(shadow ? { shadow: shadow.health() } : {}),
       ...(runnerService ? { runner: runnerService.health() } : {}),
+      cutoverProtocol: CUTOVER_PROTOCOL,
+      ...(cutover ? { cutover } : {}),
     };
   };
 
@@ -325,19 +347,34 @@ export async function runDaemon({
     shadow = createShadow({ directory, transportFactory: production.transportFactory, tokenStore: production.tokenStore, log: mirrorLog });
     runnerService = createRunner({ directory, transportFactory: production.transportFactory, log });
     heartbeat = createHeartbeat({
-      readConfig: () => readOwnerOnlyJson(configFile),
+      readConfig: () => {
+        heartbeatGeneration = ++configGeneration;
+        return readOwnerOnlyJson(configFile);
+      },
       runtime,
       mirror,
       shadow,
-      runner: runnerService,
+      runner: { update: (config) => runnerService.update(config, { generation: heartbeatGeneration }) },
       lock,
       ledger,
       ownerStore,
       progress: cycleProgress,
       extraHealth,
     });
+    // A cutover request runs here, beside the heartbeat; its facade step starts this daemon's runner at once.
+    const serve = async () => {
+      const generation = ++configGeneration;
+      runnerService.update(await readOwnerOnlyJson(configFile), { generation });
+    };
+    cutoverService = createCutoverService({
+      directory,
+      log,
+      canTake: () => !exiting && !restarting && !pending,
+      createCutover: ({ log: stepLog }) => cutoverFactory({ configDir: directory, log: stepLog, serve }),
+    });
+    cutoverService.start();
     stopServices = async ({ abortCode }) => {
-      const results = await Promise.allSettled([mirror.stop(), shadow.stop(), runnerService.stop(), runtime.shutdown({ abortCode })]);
+      const results = await Promise.allSettled([cutoverService.stop(), mirror.stop(), shadow.stop(), runnerService.stop(), runtime.shutdown({ abortCode })]);
       const failed = results.find((result) => result.status === 'rejected');
       if (failed) throw failed.reason;
     };
@@ -367,7 +404,7 @@ export async function runDaemon({
       // A cycle that ends after shutdown released the lock has no health left to report.
       if (exiting) return;
       await Promise.resolve()
-        .then(() => lock.heartbeat({ state: 'error', code: error.code || 'HUB_DAEMON_LOOP_FAILED' }))
+        .then(() => lock.heartbeat({ state: 'error', code: error.code || 'HUB_DAEMON_LOOP_FAILED', ...extraHealth() }))
         .catch(() => {});
       wait = t.errorRetryMs;
     } finally {

package/src/lib/serviceManager.js

@@ -10,7 +10,9 @@ import {
 } from './storage.js';
 import { execFileBounded as execFile } from './subprocess.js';
 
-const LABEL = 'com.agentpulse.hub';
+/** The Pulse daemon's own service label; the cutover that runs inside it must never retire it. */
+export const SERVICE_LABEL = 'com.agentpulse.hub';
+const LABEL = SERVICE_LABEL;
 const SYSTEMD_UNIT = 'agentpulse-hub.service';
 const START_ATTEMPTS = 6;
 const START_RETRY_MS = 250;

package/src/runner/runnerService.js

@@ -38,13 +38,22 @@ export class RunnerService {
     this.log = log;
     this.now = now;
     this.key = null;
+    this.generation = -Infinity;
     this.current = null;
     this.restarts = 0;
     this.state = { state: 'off' };
   }
 
-  /** Start, keep or stop the runner for this config. Never waits on the runner. */
-  update(config) {
+  /**
+   * Start, keep or stop the runner for this config. Never waits on the runner. `generation` orders the reads of
+   * config.json: a config read before the last one applied is ignored, so a heartbeat that read it before a cutover's
+   * `serve` cannot switch the runner back (CUT-03).
+   */
+  update(config, { generation = null } = {}) {
+    if (generation !== null) {
+      if (generation < this.generation) return this.state;
+      this.generation = generation;
+    }
     const on = runnerMode(config) && pairedStatus(config).ok;
     const key = on ? JSON.stringify({ c: config.cloudFirst, m: config.paired.machineId, v: config.paired.policyVersion }) : null;
     if (key === this.key) return this.state;