johns-harness 2026.9.27 → 2026.9.28

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026.9.28
+
+- Family 76: `johnness gateway restart` from inside a gateway's own launchd process group no longer unregisters its supervisor. The old `bootout -> wait -> bootstrap` sequence killed the caller before it could bootstrap, which caused a multi-hour outage when a cron issued the restart. All three service implementations, both internal restart bundles and both updater bundles now share `dist/launchd-lifecycle.js`: a loaded service restarts with `kickstart -k` only (no bootout, unload or bootstrap fallback), a missing service may bootstrap its explicitly selected plist, and real plist replacement (`gateway install --force`) stages validated bytes and hands off to an independently registered, durably armed completer with an fsynced phase journal, retry under launchd, and prior-plist restore after five failed bootstraps. Explicit stop/uninstall cancels any pending completer. Updaters snapshot the helper before npm replaces the installed tree. Success requires a changed launchd-owned PID and, when a port is declared, `/healthz` plus listener ownership by that PID; receipts live in `<stateDir>/lifecycle/<uuid>/`. Ten browser timeout messages now suggest a non-browser alternative instead of a whole-gateway restart. Covered by lifecycle unit, fault-injection, replay and packed-artifact tests plus five real disposable LaunchAgent self-restart/reload cases (`JOHNNESS_TEST_LAUNCHD=1`); verifier check 76.1.
+- Family 75: explicit `johnness migrate --cutover --yes` and forward-only `--resume` activate verified offline copies with a durable fsynced service journal. A detached launchd completer registers a gated native supervisor before disabling or stopping the exact selected legacy job. Gateway runtime imports remain gated until the old process exits; no raw PID killing, legacy service restoration, old-state deletion or old-plist deletion is performed.
+- Success requires launchd running, matching selected state/config/port, a unique listener owned by the supervised PID, no duplicate selected-state writer and HTTP health. Failed health gates keep native KeepAlive and the completer loaded, retain the journal, return nonzero and alert independently via direct Telegram HTTPS and/or macOS notification. Every CLI entrypoint reports incomplete selected-state migrations; completed instances warn about conflicting CLI port/config overrides.
+- Default migration preparation and every dry-run remain nonactivating. Live `--force` snapshots cannot activate. Service recovery is `johnness migrate --resume --to <selected-state>`, never a rollback to the legacy system. See `docs/MIGRATION-CUTOVER.md` for the explicit offline-copy and macOS ownership boundary.
+- Add 40 regression tests, including 25 actual SIGKILL boundaries with isolated service adapters, real gated shell exec, real loopback listener ownership/fleet isolation, CLI preparation/cutover/resume/verification, latency and timeout alerts. The source and installed verifier now run 468 checks. Package and lockfile release versions are aligned.
+
 ## 2026.9.27
 
 - Family 74: the local active-session pressure guard compacts on exactly one trigger, estimated active-context tokens against the active model's declared context window (`ceil(0.7 x window)`, floored at `max(compaction.reserveTokensFloor, 50000)`; undeclared windows fall back to the runtime default, `DEFAULT_CONTEXT_TOKENS`). The fixed 1 MB transcript-bytes, 220-message and 3 GiB heap backstops are removed as triggers, so a session with 221 small messages and 528 KB no longer compacts early while a large context still compacts on real token pressure. The 5-minute cooldown, the 24-message floor and the failed-attempt growth gate remain as anti-thrash throttles, and the emergency compaction path is untouched. `contextRatio`, `minIntervalMs` and `minMessagesAfterCompaction` are the config surface; legacy `transcriptBytes`/`messageCount`/`heapUsedBytes` keys are accepted and ignored.

package/README.md

@@ -15,10 +15,10 @@ Bring your agents, memory, credentials, and scheduled jobs into John's Harness.
 ```sh
 npm i -g johns-harness && johnness migrate
 ```
-The command backs up your state, creates `~/.johnness`, rewrites settings, and checks the result.
-If your gateway is running, it shows the exact stop command before making changes.
-Review any script updates, then follow the printed commands to start the new gateway.
-Your original installation stays intact. Preview with `johnness migrate --dry-run`; undo with `johnness migrate --rollback`.
+Preparation backs up offline state, creates `~/.johnness`, rewrites settings, and verifies the result. It does not change services; `--force` is a nonactivating live-snapshot rehearsal only.
+On macOS, review attention items, then use `johnness migrate --cutover --to ~/.johnness --yes`. The detached completer registers a gated native LaunchAgent before stopping the exact selected old job, then requires supervisor, listener PID and HTTP health agreement.
+Interrupted cutovers resume forward with `johnness migrate --resume --to ~/.johnness`. Every CLI entrypoint reports an incomplete journal. No service cutover rolls back or deletes the old plist/state.
+Preview without writes using `--dry-run`. See [migration cutover](docs/MIGRATION-CUTOVER.md) for ownership requirements, limitations and recovery.
 
 ## Quick start
 
@@ -85,8 +85,8 @@ node johnness.mjs --help
 ### Verify
 
 ```bash
-npm test                        # 915 tests against the installed dependency tree
-bash scripts/verify-patches.sh  # 459 checks across every patch family
+npm test                        # 990 tests against the installed dependency tree
+bash scripts/verify-patches.sh  # 468 checks across every patch family
 ```
 
 ## Launch a swarm with one command
@@ -132,7 +132,7 @@ Coding agents today run as isolated processes. Two agents on the same repository
 - **Memory built for production.** Tiered recall that traces from consolidated reflections down to the verbatim record, surviving compaction and shared across the swarm. Installed and enabled by default.
 - **Production authority per commit.** Promotion is granted to an exact SHA, never to a branch name, so one worker's authorization never covers another worker's commits.
 - **An append-only action log.** Agents record every consequential action to `ACTION_LOG.md` and read it before acting.
-- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 74 patch families, each with a regression test and a rollback path.
+- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 76 patch families, each with a regression test and an explicit recovery path.
 - **Reliability with a definition.** Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, and supervised gateway recovery.
 - **Coding first, phone optional.** Direct the work at a high level from a chat channel while agents plan, implement, test, coordinate, and stage releases unattended.
 - **Local voice.** Optional native Whisper transcription of inbound audio, entirely on your machine. Off by default. [Setup](docs/NATIVE-WHISPER-MUSE.md).
@@ -199,7 +199,7 @@ The log is a [`RULES.md`](RULES.md) workspace convention enforced through the ac
 
 ## Patch families
 
-The runtime carries 74 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 459 checks against the package tree and installed dependencies, and 915 tests run against the installed dependency tree.
+The runtime carries 76 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and an explicit recovery path. A verifier runs 468 checks against the package tree and installed dependencies, and 990 tests run against the installed dependency tree.
 
 Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: [`docs/PATCHES.md`](docs/PATCHES.md).
 
@@ -218,7 +218,7 @@ Every family follows the same six steps: reproduce the failure, trace the exact
 ## Documentation
 
 - [`docs/index.md`](docs/index.md): runtime docs, from gateway and channels to plugins, nodes, and CLI reference.
-- [`docs/PATCHES.md`](docs/PATCHES.md): the 74 patch families, one record each.
+- [`docs/PATCHES.md`](docs/PATCHES.md): the 76 patch families, one record each.
 - [`docs/NATIVE-WHISPER-MUSE.md`](docs/NATIVE-WHISPER-MUSE.md): local Whisper transcription setup.
 - [`RULES.md`](RULES.md): the default operating rules, including Rule Zero on production authorization.
 

package/dist/compact-B247y5Qt.js

@@ -43943,7 +43943,8 @@ function withLoopbackBrowserAuth(url, init) {
 }
 const BROWSER_TOOL_MODEL_HINT = "Do NOT retry the browser tool — it will keep failing. Use an alternative approach or inform the user that the browser is currently unavailable.";
 function resolveBrowserFetchOperatorHint(url) {
-	return !isAbsoluteHttp(url) ? `Restart the Johnness gateway (Johnness.app menubar, or \`${formatCliCommand("johnness gateway")}\`).` : "If this is a sandboxed session, ensure the sandbox browser is running.";
+	// JOHNNESS_PATCH_LAUNCHD_SAFE_RESTART_76: browser failures are not gateway failures.
+	return !isAbsoluteHttp(url) ? "The browser control operation failed. Report the browser blocker or use a non-browser alternative. Do not restart the gateway for a browser timeout." : "If this is a sandboxed session, ensure the sandbox browser is running.";
 }
 function normalizeErrorMessage(err) {
 	if (err instanceof Error && err.message.trim().length > 0) return err.message.trim();

package/dist/daemon-cli.js

@@ -1,3 +1,4 @@
+import { requestLaunchdOperation, waitForLaunchdOperation, cancelLaunchdOperations, lifecycleIdentity, writeLaunchdPlist, prepareLaunchdRestart, runPreparedLaunchdRestart } from "./launchd-lifecycle.js"; // JOHNNESS_PATCH_LAUNCHD_SAFE_RESTART_76
 // JOHNNESS_PATCH_CATALOG_REFRESH_65
 // JOHNNESS_PATCH_NATIVE_STATE_MIGRATION_59
 import { createRequire } from "node:module";
@@ -17364,6 +17365,7 @@ async function readLaunchAgentRuntime(env) {
 	};
 }
 async function uninstallLaunchAgent({ env, stdout }) {
+	cancelLaunchdOperations({ domain: resolveGuiDomain(), label: resolveLaunchAgentLabel({ env }), stateDir: resolveGatewayStateDir(env) });
 	const domain = resolveGuiDomain();
 	const label = resolveLaunchAgentLabel({ env });
 	const plistPath = resolveLaunchAgentPlistPath(env);
@@ -17420,6 +17422,7 @@ async function waitForPidExit(pid) {
 	}
 }
 async function stopLaunchAgent({ stdout, env }) {
+	cancelLaunchdOperations({ domain: resolveGuiDomain(), label: resolveLaunchAgentLabel({ env }), stateDir: resolveGatewayStateDir(env) });
 	const domain = resolveGuiDomain();
 	const label = resolveLaunchAgentLabel({ env });
 	const res = await execLaunchctl(["bootout", `${domain}/${label}`]);
@@ -17431,18 +17434,6 @@ async function installLaunchAgent({ env, stdout, programArguments, workingDirect
 	await fs.mkdir(logDir, { recursive: true });
 	const domain = resolveGuiDomain();
 	const label = resolveLaunchAgentLabel({ env });
-	for (const legacyLabel of resolveLegacyGatewayLaunchAgentLabels(env.JOHNNESS_PROFILE)) {
-		const legacyPlistPath = resolveLaunchAgentPlistPathForLabel(env, legacyLabel);
-		await execLaunchctl([
-			"bootout",
-			domain,
-			legacyPlistPath
-		]);
-		await execLaunchctl(["unload", legacyPlistPath]);
-		try {
-			await fs.unlink(legacyPlistPath);
-		} catch {}
-	}
 	const plistPath = resolveLaunchAgentPlistPathForLabel(env, label);
 	await fs.mkdir(path.dirname(plistPath), { recursive: true });
 	const plist = buildLaunchAgentPlist({
@@ -17458,35 +17449,8 @@ async function installLaunchAgent({ env, stdout, programArguments, workingDirect
 		stderrPath,
 		environment
 	});
-	await fs.writeFile(plistPath, plist, "utf8");
-	await execLaunchctl([
-		"bootout",
-		domain,
-		plistPath
-	]);
-	await execLaunchctl(["unload", plistPath]);
-	await execLaunchctl(["enable", `${domain}/${label}`]);
-	const boot = await execLaunchctl([
-		"bootstrap",
-		domain,
-		plistPath
-	]);
-	if (boot.code !== 0) {
-		const detail = (boot.stderr || boot.stdout).trim();
-		if (isUnsupportedGuiDomain(detail)) throw new Error([
-			`launchctl bootstrap failed: ${detail}`,
-			`LaunchAgent install requires a logged-in macOS GUI session for this user (${domain}).`,
-			"This usually means you are running from SSH/headless context or as the wrong user (including sudo).",
-			"Fix: sign in to the macOS desktop as the target user and rerun `johnness gateway install --force`.",
-			"Headless deployments should use a dedicated logged-in user session or a custom LaunchDaemon (not shipped): https://docs.openclaw.ai/gateway"
-		].join("\n"));
-		throw new Error(`launchctl bootstrap failed: ${detail}`);
-	}
-	await execLaunchctl([
-		"kickstart",
-		"-k",
-		`${domain}/${label}`
-	]);
+	const receipt = requestLaunchdOperation({ domain, label, plistPath, stateDir: resolveGatewayStateDir(env), mode: "reload", plist });
+	await waitForLaunchdOperation(receipt);
 	writeFormattedLines(stdout, [{
 		label: "Installed LaunchAgent",
 		value: plistPath
@@ -17498,41 +17462,13 @@ async function installLaunchAgent({ env, stdout, programArguments, workingDirect
 }
 async function restartLaunchAgent({ stdout, env }) {
 	const serviceEnv = env ?? process.env;
-	const domain = resolveGuiDomain();
-	const label = resolveLaunchAgentLabel({ env: serviceEnv });
-	const plistPath = resolveLaunchAgentPlistPath(serviceEnv);
-	const runtime = await execLaunchctl(["print", `${domain}/${label}`]);
-	const previousPid = runtime.code === 0 ? parseLaunchctlPrint(runtime.stdout || runtime.stderr || "").pid : void 0;
-	const stop = await execLaunchctl(["bootout", `${domain}/${label}`]);
-	if (stop.code !== 0 && !isLaunchctlNotLoaded(stop)) throw new Error(`launchctl bootout failed: ${stop.stderr || stop.stdout}`.trim());
-	if (typeof previousPid === "number") await waitForPidExit(previousPid);
-	const boot = await execLaunchctl([
-		"bootstrap",
-		domain,
-		plistPath
-	]);
-	if (boot.code !== 0) {
-		const detail = (boot.stderr || boot.stdout).trim();
-		if (isUnsupportedGuiDomain(detail)) throw new Error([
-			`launchctl bootstrap failed: ${detail}`,
-			`LaunchAgent restart requires a logged-in macOS GUI session for this user (${domain}).`,
-			"This usually means you are running from SSH/headless context or as the wrong user (including sudo).",
-			"Fix: sign in to the macOS desktop as the target user and rerun `johnness gateway restart`.",
-			"Headless deployments should use a dedicated logged-in user session or a custom LaunchDaemon (not shipped): https://docs.openclaw.ai/gateway"
-		].join("\n"));
-		throw new Error(`launchctl bootstrap failed: ${detail}`);
-	}
-	const start = await execLaunchctl([
-		"kickstart",
-		"-k",
-		`${domain}/${label}`
-	]);
-	if (start.code !== 0) throw new Error(`launchctl kickstart failed: ${start.stderr || start.stdout}`.trim());
-	try {
-		stdout.write(`${formatLine("Restarted LaunchAgent", `${domain}/${label}`)}\n`);
-	} catch (err) {
-		if (err?.code !== "EPIPE") throw err;
-	}
+	const receipt = requestLaunchdOperation({
+		domain: resolveGuiDomain(), label: resolveLaunchAgentLabel({ env: serviceEnv }),
+		plistPath: resolveLaunchAgentPlistPath(serviceEnv), stateDir: resolveGatewayStateDir(serviceEnv), mode: "restart"
+	});
+	try { stdout.write(`LaunchAgent restart requested; durable receipt: ${receipt}\n`); } catch (err) { if (err?.code !== "EPIPE") throw err; }
+	await waitForLaunchdOperation(receipt);
+	try { stdout.write(`${formatLine("Restarted LaunchAgent", resolveLaunchAgentLabel({ env: serviceEnv }))}\n`); } catch (err) { if (err?.code !== "EPIPE") throw err; }
 }
 //#endregion
 //#region src/daemon/arg-split.ts

package/dist/launchd-lifecycle.js

@@ -0,0 +1,281 @@
+// JOHNNESS_PATCH_LAUNCHD_SAFE_RESTART_76
+// This package is dist-first. Copied verbatim into each independent launchd worker.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const escapeXml = (s) => String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+const missing = (r) => /could not find service|no such process|service .*not found/i.test(r.stderr || r.stdout || "");
+export function launchctl(args) {
+  const r = spawnSync("/bin/launchctl", args, { encoding: "utf8", timeout: 15000, maxBuffer: 1024 * 1024 });
+  return { code: r.status ?? 1, stdout: r.stdout || "", stderr: r.stderr || r.error?.code || "" };
+}
+export function writeLaunchdPlist(file, text) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  const fd = fs.openSync(tmp, "w", 0o600);
+  try { fs.writeFileSync(fd, text); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  fs.renameSync(tmp, file);
+  const parent = fs.openSync(path.dirname(file), "r");
+  try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+}
+export function atomicJson(file, value) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  const fd = fs.openSync(tmp, "w", 0o600);
+  try { fs.writeFileSync(fd, JSON.stringify(value)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  fs.renameSync(tmp, file);
+  const parent = fs.openSync(path.dirname(file), "r");
+  try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+}
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+export function lifecycleIdentity(env = process.env) {
+  const home = env.HOME?.trim() || env.USERPROFILE?.trim() || os.homedir();
+  const rawProfile = env.JOHNNESS_PROFILE?.trim();
+  const profile = rawProfile?.toLowerCase() === "default" ? "" : rawProfile;
+  const label = env.JOHNNESS_LAUNCHD_LABEL?.trim() || (profile && profile !== "default" ? `ai.johnness.${profile}` : "ai.johnness.gateway");
+  return { domain: `gui/${process.getuid()}`, label, plistPath: path.join(home, "Library", "LaunchAgents", `${label}.plist`), stateDir: env.JOHNNESS_STATE_DIR?.trim() ? path.resolve(env.JOHNNESS_STATE_DIR.trim().replace(/^~(?=$|[\\/])/, home)) : path.join(home, profile ? `.johnness-${profile}` : ".johnness") };
+}
+function validate(p) {
+  if (!/^gui\/\d+$/.test(p.domain) || !/^[A-Za-z0-9_.-]+$/.test(p.label) || !path.isAbsolute(p.plistPath) || !path.isAbsolute(p.stateDir)) throw new Error("Invalid launchd lifecycle identity");
+  if (!["restart", "reload"].includes(p.mode)) throw new Error("Invalid launchd lifecycle operation");
+}
+function runtime(run, target) {
+  const r = run(["print", target]);
+  if (r.code && !missing(r)) throw new Error(`launchctl print failed (${r.code}); refusing lifecycle mutation`);
+  return { loaded: r.code === 0, pid: Number(r.stdout.match(/^\s*pid = (\d+)\s*$/m)?.[1]) || null };
+}
+function plistPort(file) {
+  const r = spawnSync("/usr/bin/plutil", ["-convert", "json", "-o", "-", file], { encoding: "utf8", timeout: 5000 });
+  if (r.status !== 0) throw new Error("Invalid target LaunchAgent plist");
+  const p = JSON.parse(r.stdout), args = p.ProgramArguments || [];
+  const i = args.indexOf("--port");
+  const port = Number(i >= 0 ? args[i + 1] : p.EnvironmentVariables?.JOHNNESS_GATEWAY_PORT);
+  return { label: p.Label, port: Number.isInteger(port) && port > 0 && port < 65536 ? port : null };
+}
+function workerPlist(p, file) {
+  return `<?xml version="1.0"?><plist version="1.0"><dict><key>Label</key><string>${p.workerLabel}</string><key>ProgramArguments</key><array><string>${escapeXml(process.execPath)}</string><string>--max-old-space-size=256</string><string>${escapeXml(path.join(path.dirname(file), "worker.mjs"))}</string><string>--worker</string><string>${escapeXml(file)}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>2</integer><key>EnvironmentVariables</key><dict><key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin</string><key>HOME</key><string>${escapeXml(os.homedir())}</string></dict><key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string></dict></plist>`;
+}
+/** Register and verify an independent job BEFORE granting permission for any effect.
+ * Death before arming leaves the target untouched. Death afterwards is irrelevant.
+ * No detached child, AbandonProcessGroup, inherited secrets or gateway imports. */
+export function requestLaunchdOperation(params, deps = {}) {
+  const p = { ...params, mode: params.mode || "restart" };
+  validate(p);
+  const run = deps.run || launchctl;
+  const target = `${p.domain}/${p.label}`;
+  const initial = runtime(run, target);
+  const operations = path.join(p.stateDir, "lifecycle");
+  fs.mkdirSync(operations, { recursive: true, mode: 0o700 });
+  // Coalesce an already armed operation for this exact target. Never stack reloads.
+  for (const name of fs.readdirSync(operations)) {
+    const file = path.join(operations, name, "request.json");
+    try {
+      const old = read(file), receipt = read(path.join(path.dirname(file), "receipt.json"));
+      if (old.target === target && !["complete", "failed", "cancelled"].includes(receipt.status) && fs.existsSync(path.join(path.dirname(file), "armed")) && run(["print", `${p.domain}/${old.workerLabel}`]).code === 0) throw new Error("A launchd lifecycle operation is already pending for this service");
+    } catch (e) { if (e.message.startsWith("A launchd")) throw e; }
+  }
+  const lock = path.join(operations, `${p.label}.lock`);
+  try { fs.mkdirSync(lock, { mode: 0o700 }); } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    let owner; try { owner = read(path.join(lock, "owner.json")); } catch {}
+    // Never steal an armed job's ownership while its independently supervised completer exists.
+    if (Date.now() - fs.statSync(lock).mtimeMs < 30000 || (owner && run(["print", `${p.domain}/${owner.workerLabel}`]).code === 0)) throw new Error("A launchd lifecycle operation is already pending for this service");
+    fs.rmSync(lock, { recursive: true }); fs.mkdirSync(lock, { mode: 0o700 });
+  }
+  const id = randomUUID(), dir = path.join(operations, id);
+  fs.mkdirSync(dir, { mode: 0o700 });
+  const file = path.join(dir, "request.json");
+  try {
+  // Validate staged bytes before granting permission to unload; keep the old plist for recovery.
+  if (p.mode === "reload") {
+    if (typeof p.plist !== "string") throw new Error("Reload requires staged plist bytes");
+    p.stagedPlist = path.join(dir, "next.plist");
+    fs.writeFileSync(p.stagedPlist, p.plist, { mode: 0o600 }); delete p.plist;
+    if (fs.existsSync(p.plistPath)) {
+      p.previousPlist = path.join(dir, "previous.plist"); fs.copyFileSync(p.plistPath, p.previousPlist); fs.chmodSync(p.previousPlist, 0o600);
+    }
+  }
+  const plist = plistPort(p.stagedPlist || p.plistPath);
+  if (plist.label !== p.label) throw new Error("LaunchAgent plist label does not match selected service");
+  Object.assign(p, { lock, id, target, previousPid: initial.pid, initiallyLoaded: initial.loaded, port: plist.port || p.port, workerLabel: `ai.johnness.lifecycle.${id}`, createdAt: Date.now() });
+  atomicJson(path.join(lock, "owner.json"), { workerLabel: p.workerLabel });
+  p.workerPlist = path.join(dir, "worker.plist");
+  atomicJson(file, p);
+  atomicJson(path.join(dir, "receipt.json"), { status: "prepared", target, previousPid: p.previousPid, createdAt: p.createdAt });
+  fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "worker.mjs"));
+  fs.writeFileSync(p.workerPlist, workerPlist(p, file), { mode: 0o600 });
+  for (const f of ["worker.mjs", "worker.plist", ...(p.stagedPlist ? ["next.plist"] : []), ...(p.previousPlist ? ["previous.plist"] : [])]) { const fd = fs.openSync(path.join(dir, f), "r"); fs.fsyncSync(fd); fs.closeSync(fd); }
+  const boot = run(["bootstrap", p.domain, p.workerPlist]);
+  if (boot.code) throw new Error(`Could not register independent lifecycle worker (${boot.code}); target unchanged`);
+  const deadline = Date.now() + 10000;
+  while (!fs.existsSync(path.join(dir, "ready")) && Date.now() < deadline) pauseSync(25);
+  if (!fs.existsSync(path.join(dir, "ready")) || run(["print", `${p.domain}/${p.workerLabel}`]).code !== 0) throw new Error("Lifecycle worker not ready; target unchanged");
+  // This fsynced permission record is the ownership handoff, not a success receipt.
+  atomicJson(path.join(dir, "armed"), { at: Date.now() });
+  return path.join(dir, "receipt.json");
+  } catch (error) {
+    if (!fs.existsSync(path.join(dir, "armed"))) {
+      if (p.workerLabel) run(["bootout", `${p.domain}/${p.workerLabel}`]);
+      fs.rmSync(lock, { recursive: true, force: true });
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+export async function waitForLaunchdOperation(file, timeoutMs = 100000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const receipt = read(file);
+    if (receipt.status === "complete") return receipt;
+    if (["failed", "cancelled"].includes(receipt.status)) throw new Error(`LaunchAgent lifecycle ${receipt.status}: ${receipt.detail || "see receipt"} (${file})`);
+    await pause(100);
+  }
+  throw new Error(`LaunchAgent lifecycle still pending; independent worker owns recovery (${file})`);
+}
+export function cancelLaunchdOperations(params) {
+  const operations = path.join(params.stateDir, "lifecycle"), target = `${params.domain}/${params.label}`;
+  if (!fs.existsSync(operations)) return;
+  for (const id of fs.readdirSync(operations)) {
+    const dir = path.join(operations, id);
+    let p; try { p = read(path.join(dir, "request.json")); } catch { continue; }
+    if (p.target !== target) continue;
+    if (["complete", "failed", "cancelled"].includes(read(path.join(dir, "receipt.json")).status)) continue;
+    // Remove the completer first. An explicit stop/uninstall must never resurrect.
+    const r = launchctl(["bootout", `${p.domain}/${p.workerLabel}`]);
+    if (r.code && !missing(r)) throw new Error("Cannot cancel lifecycle worker; target not stopped");
+    atomicJson(path.join(dir, "receipt.json"), { status: "cancelled", target, at: Date.now() });
+    fs.rmSync(p.workerPlist, { force: true });
+    if (p.lock) fs.rmSync(p.lock, { recursive: true, force: true });
+  }
+}
+function descendant(pid, ancestor) {
+  for (let n = 0; n < 12 && pid > 1; n++) {
+    if (pid === ancestor) return true;
+    const r = spawnSync("/bin/ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 });
+    pid = Number(r.stdout?.trim());
+  }
+  return false;
+}
+async function healthy(p, current, deps) {
+  if (!current.loaded || !current.pid || (p.previousPid && p.previousPid === current.pid)) return false;
+  if (!p.port) return true; // Non-gateway/node services: supervised replacement, not HTTP health.
+  if (deps.health) return deps.health(p, current);
+  const r = spawnSync("/usr/sbin/lsof", ["-nP", `-iTCP:${p.port}`, "-sTCP:LISTEN", "-Fp"], { encoding: "utf8", timeout: 5000 });
+  const pids = [...new Set([...String(r.stdout).matchAll(/^p(\d+)$/gm)].map((m) => Number(m[1])))];
+  if (!pids.length || !pids.every((pid) => descendant(pid, current.pid))) return false;
+  try { return (await fetch(`http://127.0.0.1:${p.port}/healthz`, { signal: AbortSignal.timeout(2000) })).ok; } catch { return false; }
+}
+/** Restartable state machine. Checkpoints precede effects; real supervisor state
+ * reconciles a missing effect acknowledgement after SIGKILL. Exported for fault tests. */
+export async function executeLaunchdOperation(p, receiptFile, deps = {}) {
+  const run = deps.run || launchctl;
+  const save = (status, extra = {}) => { atomicJson(receiptFile, { ...read(receiptFile), status, ...extra, at: Date.now() }); deps.checkpoint?.(status); };
+  const effect = (args) => { const r = run(args); deps.effect?.(args); return r; };
+  let receipt = read(receiptFile);
+  if (["complete", "failed", "cancelled"].includes(receipt.status)) return;
+  let current = runtime(run, p.target);
+  if (receipt.status === "prepared" || receipt.status === "ready") {
+    if (p.mode === "reload") {
+      const r = effect(["enable", p.target]);
+      if (r.code) throw new Error(`launchctl enable failed (${r.code})`);
+    }
+    save(p.mode === "reload" ? "publish-intent" : "restart-intent");
+    receipt = read(receiptFile);
+  }
+  if (receipt.status === "publish-intent") {
+    writeLaunchdPlist(p.plistPath, fs.readFileSync(p.stagedPlist, "utf8"));
+    save("unload-intent"); receipt = read(receiptFile);
+  }
+  if (receipt.status === "unload-intent") {
+    if (current.loaded) {
+      const r = effect(["bootout", p.target]);
+      if (r.code && !missing(r)) throw new Error(`launchctl bootout failed (${r.code})`);
+    }
+    save("bootstrap-intent"); receipt = read(receiptFile);
+    current = runtime(run, p.target);
+  }
+  if (receipt.status === "restart-intent") {
+    if (!current.loaded) {
+      if (p.initiallyLoaded) { save("failed", { detail: "Service was explicitly removed; refusing to resurrect it" }); return; }
+      save("bootstrap-intent"); receipt = read(receiptFile);
+    } else if (!p.previousPid || current.pid === p.previousPid) {
+      const r = effect(["kickstart", "-k", p.target]);
+      if (r.code) { save("failed", { detail: `launchctl kickstart failed (${r.code}); registration preserved` }); return; }
+      save("health-pending", { healthStartedAt: Date.now() }); receipt = read(receiptFile);
+    } else { save("health-pending", { healthStartedAt: Date.now() }); receipt = read(receiptFile); }
+  }
+  if (receipt.status === "rollback-intent") {
+    if (p.previousPlist) {
+      writeLaunchdPlist(p.plistPath, fs.readFileSync(p.previousPlist, "utf8"));
+    }
+    current = runtime(run, p.target);
+    if (!current.loaded) {
+      const r = effect(["bootstrap", p.domain, p.plistPath]);
+      if (r.code && !runtime(run, p.target).loaded) throw new Error("Rollback bootstrap failed; independent worker retains recovery ownership");
+    }
+    save("health-pending", { rolledBack: true, healthStartedAt: Date.now() }); receipt = read(receiptFile);
+  }
+  if (receipt.status === "bootstrap-intent") {
+    current = runtime(run, p.target);
+    if (!current.loaded) {
+      const r = effect(["bootstrap", p.domain, p.plistPath]);
+      if (r.code && !runtime(run, p.target).loaded) {
+        const attempts = (receipt.bootstrapAttempts || 0) + 1;
+        save(attempts >= 5 && p.previousPlist ? "rollback-intent" : "bootstrap-intent", { bootstrapAttempts: attempts });
+        throw new Error(`launchctl bootstrap failed (${r.code}); independent worker will retry`);
+      }
+    }
+    // bootstrap already starts RunAtLoad jobs. Never kill the newly booted process.
+    save("health-pending", { healthStartedAt: Date.now() }); receipt = read(receiptFile);
+  }
+  const deadline = (receipt.healthStartedAt || Date.now()) + (deps.healthTimeoutMs ?? 90000);
+  do {
+    current = runtime(run, p.target);
+    if (await healthy(p, current, deps)) { save(receipt.rolledBack ? "failed" : "complete", { ...(receipt.rolledBack ? { detail: "New plist failed to bootstrap; previous plist restored and healthy" } : {}), pid: current.pid, health: p.port ? "http-and-supervised-listener" : "supervised-process" }); return; }
+    if (!current.loaded) { save("failed", { detail: "Service removed while waiting for health; not resurrected" }); return; }
+    await (deps.pause || pause)(200);
+  } while (Date.now() < deadline);
+  save("failed", { detail: "Replacement health timeout; target remains supervised" });
+}
+async function worker(file) {
+  const p = read(file); validate(p);
+  const dir = path.dirname(file), receipt = path.join(dir, "receipt.json");
+  // Readiness proves code can execute independently before the parent arms it.
+  atomicJson(path.join(dir, "ready"), { pid: process.pid });
+  while (!fs.existsSync(path.join(dir, "armed"))) {
+    if (Date.now() - p.createdAt > 15000) { atomicJson(receipt, { status: "cancelled", detail: "Requester disappeared before arming; target untouched" }); break; }
+    await pause(25);
+  }
+  if (fs.existsSync(path.join(dir, "armed"))) await executeLaunchdOperation(p, receipt);
+  // Terminal receipt is durable before removing this worker's registration.
+  fs.rmSync(p.workerPlist, { force: true });
+  for (const f of [p.stagedPlist, p.previousPlist]) if (f) fs.rmSync(f, { force: true });
+  if (p.lock) fs.rmSync(p.lock, { recursive: true, force: true });
+  launchctl(["bootout", `${p.domain}/${p.workerLabel}`]);
+}
+/** Snapshot the dependency-free implementation BEFORE npm replaces the package. */
+export function prepareLaunchdRestart(env = process.env, port) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "johnness-launchd-update-"));
+  fs.chmodSync(dir, 0o700);
+  fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "lifecycle.mjs"));
+  const file = path.join(dir, "restart.json");
+  atomicJson(file, { ...lifecycleIdentity(env), mode: "restart", port });
+  return file;
+}
+export async function runPreparedLaunchdRestart(file) {
+  const dir = path.dirname(file);
+  const isolated = await import(pathToFileURL(path.join(dir, "lifecycle.mjs")).href);
+  const receipt = isolated.requestLaunchdOperation(read(file));
+  fs.rmSync(dir, { recursive: true, force: true });
+  return receipt; // Handed off, not a claim of health.
+}
+if (process.argv[2] === "--worker" && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  worker(process.argv[3]).catch((err) => {
+    try { const f = path.join(path.dirname(process.argv[3]), "receipt.json"); atomicJson(f, { ...read(f), lastError: err.message, retryAt: Date.now() }); } catch {}
+    process.exitCode = 1;
+  }); // launchd retries; never dump config or commands.
+}

package/dist/migrate-cutover-worker.js

@@ -0,0 +1,15 @@
+// JOHNNESS_PATCH_NATIVE_STATE_MIGRATION_59
+// JOHNNESS_PATCH_CRASH_SAFE_CUTOVER_75
+import { resumeCutover, waitForActivation } from './migrate-cutover.js';
+const [mode, target, id] = process.argv.slice(2);
+try {
+  if (mode === 'gate' && target && id) await waitForActivation(target, id);
+  else if (mode === 'resume' && target) {
+    // Let the submitting CLI release its intent lock. launchd retries nonzero exits.
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    await resumeCutover(target);
+  } else throw new Error('Invalid worker command');
+} catch {
+  process.stderr.write('JOHNNESS MIGRATION INCOMPLETE: run johnness migrate --resume. Forward recovery only.\n');
+  process.exitCode = 6;
+}