feat(runner): persist disableVersionHandoff opt-out in settings.json

The HAPI_DISABLE_VERSION_HANDOFF=1 env-var contract introduced by
feat/runner-skip-version-handoff-flag relies on every CLI invocation
inheriting the flag. That works for the systemd unit (drop-in sets it
once) but leaks badly: any terminal that runs `hapi runner start-sync`
without exporting the var sees mtime drift, kills the live runner, then
gets SIGTERM'd itself - leaving the machine offline. Today's 22:40 BST
incident reproduced exactly this pattern (operator-launched start-sync
at PID 65341, env dump shows no HAPI_DISABLE_VERSION_HANDOFF, fell
through to the mtime block, killed live runner PID 24935).

Add a persisted fallback: settings.runnerDisableVersionHandoff:true in
~/.hapi/settings.json gets the same effect as the env var. Once written
once, every CLI invocation from any context honors it without relying
on environment inheritance.

Env var still wins when set (operator override). Default off (npm
consumers see no behavior change).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: heavygee

cli/src/persistence.ts

@@ -21,6 +21,15 @@ interface Settings {
   apiUrl?: string
   // Legacy field name (for migration, read-only)
   serverUrl?: string
+  /**
+   * Persisted equivalent of HAPI_DISABLE_VERSION_HANDOFF=1. When true, the
+   * mtime-driven self-restart paths (heartbeat watcher AND fresh-invocation
+   * version check) are skipped regardless of how the runner was launched.
+   * Use this when an environment variable is too fragile (e.g. operators
+   * regularly invoke the CLI from terminals without exporting the flag).
+   * The env var still wins when set; this is the fallback.
+   */
+  runnerDisableVersionHandoff?: boolean
 }
 
 const defaultSettings: Settings = {}

cli/src/runner/controlClient.ts

@@ -185,12 +185,17 @@ export async function isRunnerRunningCurrentlyInstalledHappyVersion(): Promise<b
   const currentMachineId = settings.machineId;
 
   try {
-    // When HAPI_DISABLE_VERSION_HANDOFF=1 is set on the live runner (operator
-    // owns supervision via systemd/tmux/soup), a fresh CLI invocation must NOT
-    // treat the running runner as stale just because source mtimes shifted.
-    // Otherwise `hapi runner start` would kill the live runner mid-rebuild.
-    if (process.env.HAPI_DISABLE_VERSION_HANDOFF === '1') {
-      logger.debug('[RUNNER CONTROL] HAPI_DISABLE_VERSION_HANDOFF=1 set, skipping mtime/version drift check');
+    // When the version-handoff opt-out is in effect (env var OR persisted
+    // setting), a fresh CLI invocation must NOT treat the running runner as
+    // stale just because source mtimes shifted. Otherwise `hapi runner start`
+    // would kill the live runner mid-rebuild. The env var is the operator
+    // contract; the persisted setting is the safety net for terminals or
+    // scripts that forget to export it. See 2026-05-31 22:40 incident
+    // retrospective in docs/plans/2026-05-31-runner-self-restart-bluedeploy-fix.md.
+    const handoffDisabledByEnv = process.env.HAPI_DISABLE_VERSION_HANDOFF === '1';
+    const handoffDisabledBySetting = settings.runnerDisableVersionHandoff === true;
+    if (handoffDisabledByEnv || handoffDisabledBySetting) {
+      logger.debug(`[RUNNER CONTROL] Version-handoff disabled (env=${handoffDisabledByEnv}, setting=${handoffDisabledBySetting}); skipping mtime/version drift check`);
     } else {
       const currentCliMtimeMs = getInstalledCliMtimeMs();
       if (typeof currentCliMtimeMs === 'number' && typeof state.startedWithCliMtimeMs === 'number') {

cli/src/runner/run.ts

@@ -11,7 +11,7 @@ import { configuration } from '@/configuration';
 import packageJson from '../../package.json';
 import { getEnvironmentInfo } from '@/ui/doctor';
 import { spawnHappyCLI } from '@/utils/spawnHappyCLI';
-import { writeRunnerState, RunnerLocallyPersistedState, readRunnerState, acquireRunnerLock, releaseRunnerLock } from '@/persistence';
+import { writeRunnerState, RunnerLocallyPersistedState, readRunnerState, readSettings, acquireRunnerLock, releaseRunnerLock } from '@/persistence';
 import { isProcessAlive, isWindows, killProcess, killProcessByChildProcess } from '@/utils/process';
 import { PERMISSION_MODES } from '@hapi/protocol/modes';
 import { withRetry } from '@/utils/time';
@@ -808,11 +808,20 @@ export async function startRunner(options: { workspaceRoots?: string[] } = {}):
       // Check if runner needs update.
       // Skip entirely when the operator owns process supervision (systemd, tmux,
       // soup rebuilds, etc.) and source mtimes change for reasons unrelated to
-      // an actual npm upgrade. HAPI_DISABLE_VERSION_HANDOFF=1 keeps the rest of
-      // the heartbeat (session pruning, state file persistence) intact.
-      if (process.env.HAPI_DISABLE_VERSION_HANDOFF === '1') {
+      // an actual npm upgrade. The opt-out is honored via either:
+      //   * HAPI_DISABLE_VERSION_HANDOFF=1 in the runner's environment, OR
+      //   * runnerDisableVersionHandoff:true in ~/.hapi/settings.json
+      // The persisted setting exists so terminals/scripts that forget to
+      // export the env var still inherit the opt-out (2026-05-31 22:40 BST
+      // incident retrospective; see docs/plans/2026-05-31-runner-self-restart-bluedeploy-fix.md).
+      // Either path keeps the rest of the heartbeat (session pruning, state
+      // file persistence) intact.
+      const handoffDisabledByEnv = process.env.HAPI_DISABLE_VERSION_HANDOFF === '1';
+      const heartbeatSettings = await readSettings();
+      const handoffDisabledBySetting = heartbeatSettings.runnerDisableVersionHandoff === true;
+      if (handoffDisabledByEnv || handoffDisabledBySetting) {
         if (process.env.DEBUG) {
-          logger.debug('[RUNNER RUN] HAPI_DISABLE_VERSION_HANDOFF=1 set, skipping mtime/version drift self-restart');
+          logger.debug(`[RUNNER RUN] Version-handoff disabled (env=${handoffDisabledByEnv}, setting=${handoffDisabledBySetting}); skipping mtime/version drift self-restart`);
         }
       } else {
         const installedCliMtimeMs = getInstalledCliMtimeMs();