From 7ff8d07dae2dd5a8476cb727773785c13078ef10 Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:18:51 +0900
Subject: [PATCH 1/9] fix(service): make macOS repair verify, roll back, and
 stop evicting healthy jobs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`ocx service repair` on darwin IS `installLaunchd`, and it evicted the live job with a
domain-explicit `bootout`, re-registered with the domain-IMPLICIT legacy `launchctl load
-w`, and accepted exit-0-with-empty-stderr as proof. One repair took a hub fully offline —
public proxy, management ingress and loopback listener — with no error, no rollback, and no
log line. Recovery needed `launchctl bootstrap gui/$uid <plist>`, which the CLI never
printed. Meanwhile `diagnoseService` derived "loaded" from `launchctl list | grep <label> ||
true`: the caller's own bootstrap domain, every exit code swallowed twice, the label matched
unanchored, and no "unknown" — so a serving gui-domain job read as `installed, not loaded`
and status recommended the command that causes the outage.

installLaunchd now:

- renders the plist first and treats a byte-identical plist + unchanged token file + a job
  loaded from exactly that command as a no-op, touching launchd not at all;
- keeps the previous bytes in memory and at `<plist>.prev` (not `.prev.plist`: launchd globs
  `*.plist` at login) before overwriting;
- reloads with `bootstrap gui/$uid <plist>`, the verb that pairs with the bootout target,
  after a bounded 5 x 200 ms settle while `print` still answers 0 — `bootout` is async, so
  the old back-to-back retry raced the same exiting job twice;
- requires `launchdJobMatchesPlist` to agree before writing install state, comparing the
  command THIS install baked (a fresh install has no state yet, and a lost state file would
  make `expectedLaunchdCommand` call a correct launcher job stale, #3464);
- retries once, routed by the failure: exit 5 / `Bootstrap failed` tries `kickstart -k` and
  then `enable` + bootstrap, because measured on macOS 27.0 exit 5 means EITHER something is
  still bootstrapped OR the label is in the domain's disabled list — the `-w` in `load -w`
  was clearing that flag silently. Exit 0 with a disagreeing `print` is the silent no-op and
  earns one more eviction; anything else throws with the real stderr, undelayed;
- on terminal failure restores the previous plist, tries to bootstrap it back, and throws an
  error saying the job was evicted and is down, naming `launchctl bootstrap gui/$uid
  <plist>` plus `print` and `print-disabled`.

`stableLauncherEntry` prefers the recorded launcher while it is still an absolute executable
file, so a repair from a context without `ocx` on PATH no longer rewrites a working
launcher-form plist into the version-pinned Bun + CLI pair and then evicts the healthy job
to load it.

New `probeLaunchdLoadState` asks `launchctl print` in both `gui/<uid>` and `user/<uid>`,
keeps the 112/113 distinction, and returns loaded-current / loaded-stale / not-loaded /
unknown; `deriveLaunchdServiceDiagnostic` maps it to the diagnostic. `unknown` names no
repair command and keeps `viable` true, because `isServiceViable() === false` is what makes
the update fallback start a competing proxy on the service's own port. `loaded-stale` keeps
its old viability and gains an honest summary. The install-cleanup twin uses the same probe
and `bootout` (legacy `unload` cannot evict a gui-domain job), still failing closed on
`unknown`. `stopLaunchd`/`uninstallLaunchd` use `bootout` with `unload` only when launchctl
could not be spawned at all. The repair branch of `serviceCommand` wraps `repairService` so
`reportServiceServing("repaired")` still runs, and the exit code stays non-zero.

Two pre-existing test-safety holes this uncovered, both hitting the developer's own machine:
`os.homedir()` reads the password database rather than `$HOME`, so the suite's HOME sandbox
never moved `~/Library/LaunchAgents` and the launchd cases rewrote the live
`com.opencodex.proxy.plist` with sandbox paths. `assertNotRealLaunchAgentsUnderTest` plus an
injectable `plistPath` close that. `serviceStatePaths()` also drops its legacy default-home
entry under an armed test process — that entry is the real
`~/.opencodex/service-state.json`, and a sandboxed test was observed replacing the live
record's homes with temp paths.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 src/lib/test-home-guard.ts |  32 +++
 src/service.ts             | 500 ++++++++++++++++++++++++++++++++-----
 2 files changed, 473 insertions(+), 59 deletions(-)

diff --git a/src/lib/test-home-guard.ts b/src/lib/test-home-guard.ts
index 493e7f8297..b19c48c88c 100644
--- a/src/lib/test-home-guard.ts
+++ b/src/lib/test-home-guard.ts
@@ -61,6 +61,16 @@ function canonicalize(path: string): string {
 const REAL_HOME = process.env[REAL_HOME_ENV]?.trim() || homedir();
 const PROTECTED_HOME = canonicalize(join(REAL_HOME, ".opencodex"));
 const PROTECTED_CODEX_HOME = canonicalize(join(REAL_HOME, ".codex"));
+/**
+ * `~/Library/LaunchAgents` needs its own entry because HOME isolation does not reach it:
+ * `os.homedir()` reads the password database, not `$HOME`, so a macOS test that rewrites
+ * HOME still resolves `plistPath()` to the developer's real LaunchAgents directory. The
+ * launchd install tests were doing exactly that — replacing the live
+ * `com.opencodex.proxy.plist` with one whose token file, log path and Bun paths all point
+ * into a temp sandbox, for as long as the case ran. launchd holds its own parsed copy, so
+ * nothing broke until the job next restarted.
+ */
+const PROTECTED_LAUNCH_AGENTS = canonicalize(join(REAL_HOME, "Library", "LaunchAgents"));
 
 /** The production home this process protects. Exported for the guard's own tests. */
 export function protectedHomeForTests(): string {
@@ -94,6 +104,28 @@ export function assertNotRealHomeUnderTest(dir: string): void {
   );
 }
 
+/** The production LaunchAgents directory this process protects. Exported for its tests. */
+export function protectedLaunchAgentsDirForTests(): string {
+  return PROTECTED_LAUNCH_AGENTS;
+}
+
+/**
+ * Throw when an armed test process is about to write the real `~/Library/LaunchAgents`.
+ *
+ * Same contract as {@link assertNotRealHomeUnderTest}: call before any mkdir/write, and
+ * pass a DIRECTORY. A launchd test gives `installLaunchd` an explicit plist path inside its
+ * own fixture directory instead.
+ */
+export function assertNotRealLaunchAgentsUnderTest(dir: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  if (canonicalize(dir) !== PROTECTED_LAUNCH_AGENTS) return;
+  throw new Error(
+    `refusing to write the real LaunchAgents directory (${PROTECTED_LAUNCH_AGENTS}) from a test `
+    + "process: os.homedir() ignores HOME, so rewriting HOME does not move this path. Pass an "
+    + "explicit plist path inside the test's own fixture directory instead.",
+  );
+}
+
 /** Throw when an armed test process is about to write the real native Codex home. */
 export function assertNotRealCodexHomeUnderTest(dir: string): void {
   if (!isTestHomeGuardArmed()) return;
diff --git a/src/service.ts b/src/service.ts
index 12d20fa0bb..59215bf932 100644
--- a/src/service.ts
+++ b/src/service.ts
@@ -63,7 +63,7 @@ import { killWindowsSchedulerWrappers } from "./lib/windows-service-wrappers";
 import { withWindowsServiceMutationLock } from "./lib/windows-service-mutation-lock";
 import { maybeShowStarPrompt } from "./cli/star-prompt";
 import { systemdProperty } from "./service-manager-probe";
-import { isTestHomeGuardArmed } from "./lib/test-home-guard";
+import { assertNotRealLaunchAgentsUnderTest, isTestHomeGuardArmed, protectedHomeForTests } from "./lib/test-home-guard";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -98,11 +98,20 @@ function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: stri
  * Only an absolute path is accepted. A bare `ocx` would be re-resolved through `PATH` on
  * every restart, which turns a service definition into a PATH-hijacking surface; naming
  * one validated absolute file keeps the target fixed at install time.
+ *
+ * The RECORDED launcher wins over a fresh PATH walk. `ocx service repair` runs from
+ * whatever shell the operator (or `ocx update`, or a tray helper) happened to have, and a
+ * context without `ocx` on `PATH` used to resolve null here — rewriting a working
+ * launcher-form plist into the version-pinned Bun + CLI pair and then booting the healthy
+ * job out to load it (#4236, defect 1g). A launcher that is still an executable file is
+ * the thing the installed service already runs, so repair must keep naming it; only a
+ * recorded launcher that has disappeared falls through to discovery.
  */
 export function stableLauncherEntry(deps: {
   env?: NodeJS.ProcessEnv;
   isExecutableFile?: (path: string) => boolean;
   pathDelimiter?: string;
+  state?: ServiceInstallState | null;
 } = {}): string | null {
   const env = deps.env ?? process.env;
   const isExecutableFile = deps.isExecutableFile ?? ((path: string): boolean => {
@@ -114,6 +123,8 @@ export function stableLauncherEntry(deps: {
       return false;
     }
   });
+  const recorded = (deps.state === undefined ? readServiceInstallState() : deps.state)?.launcherPath;
+  if (recorded && isAbsolute(recorded) && isExecutableFile(recorded)) return recorded;
   const entries = (env.PATH ?? "").split(deps.pathDelimiter ?? delimiter);
   for (const entry of entries) {
     if (!entry || !isAbsolute(entry)) continue;
@@ -163,7 +174,19 @@ export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string
 }
 
 function serviceStatePaths(): string[] {
-  return serviceStatePathsForOpenCodexHome(currentOpenCodexHome());
+  const paths = serviceStatePathsForOpenCodexHome(currentOpenCodexHome());
+  if (!isTestHomeGuardArmed()) return paths;
+  /*
+   * Under an armed test process the legacy default-home entry IS the developer's real
+   * `~/.opencodex/service-state.json`. It is there so an install made before
+   * OPENCODEX_HOME was set can still be found, but it means a test whose OPENCODEX_HOME
+   * points at a sandbox still writes their live install state — observed while building
+   * the launchd repair coverage: one case replaced the real record's codexHome and
+   * opencodexHome with temp-directory paths. Drop it rather than deny the write, so the
+   * sandbox path keeps working and the real one is simply not in the list.
+   */
+  const real = normalizePathForCompare(protectedHomeForTests());
+  return paths.filter(path => normalizePathForCompare(dirname(path)) !== real);
 }
 
 function currentCodexHome(deps: CodexHomeDeps = {}): string {
@@ -537,9 +560,7 @@ export function buildPlist(
     ...proxyEnv.map(({ name, value }) =>
       `    <key>${name}</key><string>${plistString(value)}</string>`),
   ].filter((line): line is string => Boolean(line)).join("\n");
-  const command = launcher
-    ? buildServiceLauncherShellCommand(launcher)
-    : buildServiceShellCommand(bun, cli);
+  const command = launchdServiceCommand(launcher, runtime);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -604,6 +625,23 @@ function buildServiceLauncherShellCommand(launcher: string, port = resolveServic
   return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
 }
 
+/**
+ * The exec line {@link buildPlist} bakes, for the launcher and runtime a single install
+ * already resolved. Shared so `installLaunchd` can verify the live job against the exact
+ * string it just wrote instead of re-deriving it from install state that has not been
+ * written yet (a fresh install has no state, so `expectedLaunchdCommand` would hand back
+ * the Bun + CLI pair and call a correctly loaded launcher job stale).
+ */
+function launchdServiceCommand(
+  launcher: string | null,
+  runtime: DurableBunRuntime = durableBunRuntime(),
+  port: number = resolveServiceListenPort(),
+): string {
+  if (launcher) return buildServiceLauncherShellCommand(launcher, port);
+  const { bun, cli } = cliEntry(runtime);
+  return buildServiceShellCommand(bun, cli, port);
+}
+
 /**
  * The exec line the installed launchd plist is expected to carry, derived from the recorded
  * install state rather than rediscovered: a launcher install runs the launcher, a legacy or
@@ -991,6 +1029,107 @@ export function launchdJobMatchesPlist(
   return { loaded: true, matchesPlist: printedText.includes(expectedCommand) };
 }
 
+/** `launchctl print`: the domain answered and holds no such service. */
+const LAUNCHCTL_NO_SUCH_SERVICE = 113;
+/** `launchctl print`: that domain does not exist at all (label-independent). */
+const LAUNCHCTL_NO_SUCH_DOMAIN = 112;
+/** `launchctl bootstrap`: something is already bootstrapped under that label. */
+const LAUNCHCTL_BOOTSTRAP_BUSY = 5;
+/** `launchctl bootout`: nothing was loaded under that label, i.e. already stopped. */
+const LAUNCHCTL_BOOTOUT_NO_SUCH_PROCESS = 3;
+
+/**
+ * Four states, because three of them used to collapse into one bit.
+ *
+ * - `loaded-current` — a domain answers 0 and runs the command we expect.
+ * - `loaded-stale` — a domain answers 0 but runs a different command (an older plist).
+ * - `not-loaded` — every domain answered 112/113, which is proof of absence.
+ * - `unknown` — launchctl could not be asked, or answered something undocumented. NOT
+ *   evidence of a problem, and deliberately not a reason to recommend `ocx service
+ *   repair`: that command evicts the job, so recommending it on a failed probe is how
+ *   #4236 turned a healthy hub into an outage.
+ */
+export type LaunchdLoadState = "loaded-current" | "loaded-stale" | "not-loaded" | "unknown";
+
+export interface LaunchdLoadProbe {
+  state: LaunchdLoadState;
+  /** The domain that answered, when one did. */
+  domain?: string;
+  /** Why the probe is `unknown`. Never carries plist contents or credentials. */
+  detail?: string;
+}
+
+/**
+ * Whether launchd is running our job, and from which plist — asked with `launchctl print`
+ * in BOTH user domains.
+ *
+ * Replaces `launchctl list | grep <label>`, which enumerated the CALLER's bootstrap domain
+ * (so a healthy `gui/$uid` job was invisible from ssh/cron), swallowed every exit code
+ * through `|| true`, and matched the label unanchored anywhere on a line (so
+ * `com.opencodex.proxy.helper` read as ours). `gui/` and `user/` are independent and hold
+ * separate service sets — measured on macOS 27.0: the shipped agent answers 0 under
+ * `gui/<uid>` and 113 under `user/<uid>` — so asking one leaves the other free to hold a
+ * job this probe would then call absent (same reasoning as `inspectLaunchd`).
+ */
+export function probeLaunchdLoadState(deps: {
+  launchctl?: typeof runLaunchctl;
+  expectedCommand?: () => string;
+  uid?: number;
+} = {}): LaunchdLoadProbe {
+  const run = deps.launchctl ?? runLaunchctl;
+  const uid = deps.uid ?? process.getuid?.() ?? 0;
+  for (const domain of [`gui/${uid}`, `user/${uid}`]) {
+    const printed = run(["print", `${domain}/${LABEL}`]);
+    if (printed.status === 0) {
+      const expected = (deps.expectedCommand
+        ?? (() => expectedLaunchdCommand(installedServiceListenPort())))();
+      const printedText = `${printed.stdout}\n${printed.stderr}`;
+      return {
+        state: printedText.includes(expected) ? "loaded-current" : "loaded-stale",
+        domain,
+      };
+    }
+    if (printed.status === LAUNCHCTL_NO_SUCH_SERVICE) continue;
+    // 112 is an answer ABOUT THE DOMAIN and is label-independent, so an unreachable
+    // domain cannot be hiding a job of ours. A headless Mac has no GUI domain and no
+    // installation either; calling that `unknown` would refuse every verdict on it.
+    if (printed.status === LAUNCHCTL_NO_SUCH_DOMAIN) continue;
+    return {
+      state: "unknown",
+      detail: printed.status === null
+        ? `launchctl could not be run: ${printed.stderr || "spawn failed"}`
+        : `launchctl print ${domain}/${LABEL} exited ${String(printed.status)}`,
+    };
+  }
+  return { state: "not-loaded" };
+}
+
+/** Up to ~5 × 200 ms, the launchd twin of the Windows scheduler settle delays. */
+const LAUNCHD_SETTLE_ATTEMPTS = 5;
+const LAUNCHD_SETTLE_DELAY_MS = 200;
+
+/**
+ * Wait for a `bootout` to finish.
+ *
+ * `bootout` is asynchronous: it returns before the job has exited, so an immediate
+ * re-registration races it and gets "Bootstrap failed: 5: Input/output error" — which is
+ * exactly what made the old back-to-back retry useless (#4236, defect 1d). Bounded on
+ * purpose: a genuinely wedged domain must reach the diagnosable throw rather than hang.
+ *
+ * Synchronous because `installLaunchd` is (`ServiceOps.install` / `repairLaunchd` are
+ * `() => void`), so this uses `Bun.sleepSync` and exposes the seam for tests.
+ */
+function settleLaunchdEviction(
+  run: typeof runLaunchctl,
+  target: string,
+  sleepSync: (ms: number) => void,
+): void {
+  for (let attempt = 0; attempt < LAUNCHD_SETTLE_ATTEMPTS; attempt += 1) {
+    if (!run(["print", target]).ok) return;
+    sleepSync(LAUNCHD_SETTLE_DELAY_MS);
+  }
+}
+
 /**
  * Decode schtasks stdout. `/query /xml` emits UTF-16LE (often with BOM) because the
  * registered task document is UTF-16; reading that as UTF-8 makes every health check
@@ -2338,9 +2477,18 @@ export function readWindowsSchedulerXmlState(
 }
 
 // ── macOS (launchd) ──
+/** Read a file as UTF-8, or null when it is absent/unreadable. */
+function readTextOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Deps follow {@link startLaunchd}: `launchctl` replaces the LAYER, returning a
- * {@link runLaunchctl} result, not a spawnSync result. It is optional so this stays
+ * {@link runLaunchctl} result, not a spawnSync result. Every one is optional so this stays
  * assignable to `ServiceOps.install` and `RepairServiceDeps.repairLaunchd`
  * (`() => void`), and so `platformOps` wires the same function the tests exercise.
  *
@@ -2349,60 +2497,173 @@ export function readWindowsSchedulerXmlState(
  * its read-only list, so a test reaching the real runner would fail closed on the guard
  * instead of exercising the sequence.
  *
- * No `matches` dep: unlike `startLaunchd`, this function never consults
- * {@link launchdJobMatchesPlist}. It has just rewritten the plist, so a live job is stale
- * by construction and there is nothing to compare against.
+ * `matches` is a {@link launchdJobMatchesPlist} result, used TWICE and for opposite
+ * reasons: once before touching launchd, to prove a repair has nothing to do, and once
+ * after, because stderr cannot prove a load took.
+ *
+ * Protocol (#4236, defect 1). `ocx service repair` on darwin IS this function, and it
+ * evicts the running job — a public proxy, a management ingress and a loopback listener on
+ * a hub. So:
+ *
+ *  1. Render the plist first and compare it to the live job. Identical plist + unchanged
+ *     token file + a job loaded from exactly that command means there is nothing to
+ *     repair, and a repair of a healthy service must never cause an outage.
+ *  2. Keep the previous plist bytes (in memory and at `<plist>.prev`) before overwriting.
+ *  3. `bootout`, settle, then `bootstrap gui/$uid <plist>` — the verb that PAIRS with the
+ *     bootout target. Legacy `load -w` is domain-implicit: it acts on the caller's own
+ *     bootstrap domain, so from ssh/cron it deleted the gui-domain job and registered
+ *     nothing (defect 1a).
+ *  4. Success is `launchctl print` agreeing, never a stderr regex: measured on macOS 27.0,
+ *     `load -w` over a bootstrapped job exits 0 with "Load failed: 5" and does nothing,
+ *     and `bootstrap` exits 5 with "Bootstrap failed: 5" for the same condition.
+ *  5. On terminal failure restore the previous plist, try to bootstrap it back, and throw
+ *     an error that says the job is DOWN and names the manual remedy.
  */
-export function installLaunchd(deps: { launchctl?: typeof runLaunchctl } = {}): void {
+export function installLaunchd(deps: {
+  launchctl?: typeof runLaunchctl;
+  matches?: typeof launchdJobMatchesPlist;
+  sleepSync?: (ms: number) => void;
+  /**
+   * Where to write the plist. Only tests pass it: `os.homedir()` reads the password
+   * database rather than `$HOME`, so the suite's HOME sandbox does NOT move
+   * `plistPath()`, and a case without this seam rewrites the developer's live
+   * `com.opencodex.proxy.plist`. `assertNotRealLaunchAgentsUnderTest` below makes that
+   * refusal mechanical rather than a convention.
+   */
+  plistPath?: string;
+} = {}): void {
   const run = deps.launchctl ?? runLaunchctl;
-  const dir = join(homedir(), "Library", "LaunchAgents");
+  const matches = deps.matches ?? launchdJobMatchesPlist;
+  const sleepSync = deps.sleepSync ?? ((ms: number) => { Bun.sleepSync(ms); });
+  const p = deps.plistPath ?? plistPath();
+  const dir = dirname(p);
+  assertNotRealLaunchAgentsUnderTest(dir);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
-  writeServiceApiTokenFile();
-  const p = plistPath();
   // Capture this BEFORE writing: the write below makes the plist exist unconditionally,
   // so a post-write existsSync would call every fresh install an "installed" service.
   const wasInstalled = existsSync(p);
+  // The previous definition, kept for rollback. An eviction whose bootstrap fails used to
+  // end with the new plist on disk, nothing in launchd, and nothing listening.
+  const previousPlist = wasInstalled ? readTextOrNull(p) : null;
+  const tokenFile = serviceApiTokenFilePath();
+  const previousToken = readTextOrNull(tokenFile);
+  writeServiceApiTokenFile();
+  // A rotated data token only reaches the job through a restart, so it is part of "is this
+  // repair a no-op?" — the plist `cat`s this file at launch.
+  const tokenUnchanged = readTextOrNull(tokenFile) === previousToken;
   // Resolve the launcher ONCE and hand the same value to the plist and to install state,
   // so the staleness diagnostic judges exactly what launchd runs.
   const launcher = stableLauncherEntry();
-  writeServiceDefinitionFile(p, buildPlist(resolvedProxyEnv(), { launcher }), "utf8");
-  // `unload` is the legacy verb and it does not evict a job bootstrapped into the GUI
-  // domain — which is precisely the state that could not repair itself. Modern launchd
-  // answers `load -w` for an already-bootstrapped job with "Load failed: 5:
-  // Input/output error" AND exits 0, so `ocx update` replaced the binary, ran repair,
-  // and left launchd running the PREVIOUS job while the fresh plist sat unused (#4141).
-  //
-  // This EVICTS the running job. That is the repair being asked for, and it is why it
-  // lives here and nowhere else: `installLaunchd` has already rewritten the plist, so
-  // whatever is loaded is stale by construction. `ocx service start` must never do
-  // this, and `startLaunchd` accordingly still refuses to.
+  const rendered = buildPlist(resolvedProxyEnv(), { launcher });
+  // The command THIS install bakes, not the one install state remembers: on a fresh
+  // install there is no state yet, and after a lost state file `expectedLaunchdCommand`
+  // falls back to the Bun + CLI pair and would call a correct launcher job stale (#3464).
+  const expectedCommand = launchdServiceCommand(launcher);
+  const bootoutTarget = `${launchdGuiDomain()}/${LABEL}`;
+
+  if (previousPlist === rendered && tokenUnchanged) {
+    const live = matches(expectedCommand);
+    if (live.loaded && live.matchesPlist) {
+      // The plist is not rewritten and launchd is not touched; only the owner-only mode
+      // is re-asserted, for a definition an older version may have left at 0644.
+      try { chmodSync(p, 0o600); } catch { /* best-effort */ }
+      // Install state is refreshed because it is what `expectedLaunchdCommand` reads, and
+      // a repair that leaves it stale re-creates the false "OLDER plist" report.
+      writeServiceInstallState("scheduler", launcher);
+      console.log("ℹ️  service is already loaded from the current plist; nothing to do.");
+      return;
+    }
+  }
+
+  if (previousPlist !== null) {
+    // Best-effort: a backup we could not write must not stop the repair, but it is the
+    // only thing that makes the rollback below able to restore bytes rather than guesses.
+    //
+    // `.plist.prev`, not `.prev.plist`: launchd globs `~/Library/LaunchAgents/*.plist` at
+    // login, so a backup ending in `.plist` would be a second registration of the same
+    // Label fighting the real one for the port.
+    try { writeServiceDefinitionFile(`${p}.prev`, previousPlist, "utf8"); } catch { /* best-effort */ }
+  }
+  writeServiceDefinitionFile(p, rendered, "utf8");
+
+  // This EVICTS the running job, and from here until the verification below nothing is
+  // listening. `unload` is the legacy verb and does not evict a job bootstrapped into the
+  // GUI domain — precisely the state that could not repair itself (#4141).
   //
-  // Absence is fine: booting out a job that is not there is a no-op, and a real failure
-  // is reported by the load verification below with a better message than a raw
+  // Absence is fine: booting out a job that is not there exits 3 ("No such process"), and
+  // a real failure is reported by the verification below with a better message than a raw
   // eviction error would carry.
-  const bootoutTarget = `${launchdGuiDomain()}/${LABEL}`;
-  run(["bootout", bootoutTarget]);
-  let loaded = run(["load", "-w", p]);
-  if (launchctlLoadFailed(loaded.stderr)) {
-    // Still bootstrapped after an eviction: the job re-registered between the two calls,
-    // or the first `bootout` raced a job that had not finished exiting. Evict and load
-    // once more — ONCE. A bounded retry recovers the race; a loop would turn a genuinely
-    // wedged domain into a hang instead of the diagnosable throw below.
+  const evictThenBootstrap = (): { ok: boolean; stdout: string; stderr: string; status: number | null } => {
     run(["bootout", bootoutTarget]);
-    loaded = run(["load", "-w", p]);
+    // `bootout` is asynchronous. Without this the retry raced the same exiting job twice
+    // and added nothing.
+    settleLaunchdEviction(run, bootoutTarget, sleepSync);
+    return run(["bootstrap", launchdGuiDomain(), p]);
+  };
+  const loadTook = (): boolean => {
+    const live = matches(expectedCommand);
+    return live.loaded && live.matchesPlist;
+  };
+
+  let loaded = evictThenBootstrap();
+  if (!loadTook()) {
+    // ONE retry. A bounded retry recovers the race; a loop would turn a wedged domain
+    // into a hang instead of the diagnosable throw below.
+    if (loaded.status === LAUNCHCTL_BOOTSTRAP_BUSY || launchctlLoadFailed(loaded.stderr)) {
+      // "Bootstrap failed: 5: Input/output error" has TWO causes, measured on macOS 27.0
+      // with a throwaway label, and they need opposite remedies:
+      //
+      //  - something is still bootstrapped under our label (the job re-registered, or it
+      //    had not finished exiting). `kickstart -k` restarts whatever the domain holds
+      //    from the plist on disk — which is now ours — without opening a second eviction
+      //    window. On an absent job it exits 113 and changes nothing.
+      //  - the label is in the domain's DISABLED list, so `bootstrap` refuses it while
+      //    `launchctl print` reports 113. This is the one thing the legacy `load -w` did
+      //    that plain `bootstrap` does not: `-w` cleared that flag. `enable` is the modern
+      //    spelling of it, and it is idempotent on a job that was never disabled — but it
+      //    runs only here, so an ordinary repair does not quietly undo a deliberate
+      //    `launchctl disable`.
+      const kicked = run(["kickstart", "-k", bootoutTarget]);
+      if (!kicked.ok || !loadTook()) {
+        run(["enable", bootoutTarget]);
+        loaded = evictThenBootstrap();
+      }
+    } else if (loaded.ok) {
+      // Exit 0 while `print` disagrees: the load silently no-op'd. That IS worth evicting
+      // again. A load that failed for any OTHER reason — a malformed plist, EPERM — is not
+      // fixed by evicting a job, so it falls straight through to the throw and the
+      // operator sees the real stderr instead of a delayed copy of it.
+      loaded = evictThenBootstrap();
+    }
   }
-  if (!loaded.ok || launchctlLoadFailed(loaded.stderr)) {
-    // Do NOT write install state for a load that did not take: state describing an
-    // unused plist is what made this failure invisible.
+
+  if (!loadTook()) {
+    // Do NOT write install state for a load that did not take: state describing an unused
+    // plist is what made this failure invisible.
+    let rolledBack: "restored" | "on-disk-only" | "none" = "none";
+    if (previousPlist !== null) {
+      try {
+        writeServiceDefinitionFile(p, previousPlist, "utf8");
+        run(["bootout", bootoutTarget]);
+        settleLaunchdEviction(run, bootoutTarget, sleepSync);
+        run(["bootstrap", launchdGuiDomain(), p]);
+        rolledBack = run(["print", bootoutTarget]).ok ? "restored" : "on-disk-only";
+      } catch {
+        rolledBack = "on-disk-only";
+      }
+    }
     throw new Error(
-      `launchctl could not load ${p}: ${loaded.stderr || "load reported failure"}\n`
-      // The hint used to tell the operator to run `bootout` by hand. It now runs twice
-      // above, so naming it as an untried remedy would send someone to repeat what just
-      // failed. Report what was attempted instead.
-      + `A previous job is still bootstrapped after two attempts to boot it out of ${launchdGuiDomain()}.\n`
-      + `Inspect it with:\n  launchctl print ${bootoutTarget}\n`
+      `launchctl could not bootstrap ${p}: ${loaded.stderr || "bootstrap reported failure"}\n`
+      + `The ${LABEL} job was evicted from ${launchdGuiDomain()} and ${
+        rolledBack === "restored" ? "the PREVIOUS plist was restored and re-bootstrapped" : "IS NOT RUNNING — nothing is listening"
+      }.\n`
+      + (rolledBack === "on-disk-only"
+        ? "The previous plist was restored on disk but could not be bootstrapped either.\n"
+        : "")
+      + `Recover manually with:\n  launchctl bootstrap ${launchdGuiDomain()} ${p}\n`
+      + `Inspect it with:\n  launchctl print ${bootoutTarget}\n  launchctl print-disabled ${launchdGuiDomain()}\n`
       // macOS `service repair` delegates straight to installLaunchd, so this fires for
       // an already-installed service too; repair reloads it without re-registering.
       + `then re-run '${wasInstalled ? "ocx service repair" : "ocx service install"}'.`,
@@ -2445,12 +2706,52 @@ export function startLaunchd(deps: {
       : "The job is not loaded. Run 'ocx service repair' to reload it."),
   );
 }
-function stopLaunchd(): void { try { sh(`launchctl unload "${plistPath()}"`); } catch { /* not loaded */ } }
-function statusLaunchd(): string { try { return sh(`launchctl list | grep ${LABEL} || true`); } catch { return ""; } }
-function uninstallLaunchd(): void {
+/**
+ * Evict the job with the modern, domain-explicit verb; fall back to legacy `unload` only
+ * when `bootout` could not be run at all.
+ *
+ * `unload` cannot evict a job bootstrapped into the GUI domain (the same reason
+ * `installLaunchd` stopped using it), so a stop built on it reported success while the
+ * proxy kept serving. Exit 3 ("Boot-out failed: 3: No such process") is the not-loaded
+ * case and is not a failure here.
+ */
+function stopLaunchd(deps: { launchctl?: typeof runLaunchctl } = {}): void {
+  const run = deps.launchctl ?? runLaunchctl;
+  try {
+    // Any real exit status is final — including 3, which only means the job was not
+    // loaded. `status: null` is "launchctl could not be spawned at all", and only then is
+    // the legacy verb worth one attempt.
+    if (run(["bootout", `${launchdGuiDomain()}/${LABEL}`]).status !== null) return;
+  } catch {
+    // The armed-test guard refuses mutating verbs; retrying through `sh` would only hit it
+    // again.
+    return;
+  }
+  try { sh(`launchctl unload "${plistPath()}"`); } catch { /* not loaded */ }
+}
+
+/**
+ * Registration for `ocx service stop`'s "is anything installed?" guard, as a human string.
+ * Empty means "no job of ours is loaded"; the tri-state lives in
+ * {@link probeLaunchdLoadState}, which `diagnoseService` uses instead of this.
+ */
+function statusLaunchd(deps: { probe?: typeof probeLaunchdLoadState } = {}): string {
+  const probe = (deps.probe ?? probeLaunchdLoadState)();
+  if (probe.state === "loaded-current") return `${LABEL} loaded in ${probe.domain ?? launchdGuiDomain()}`;
+  if (probe.state === "loaded-stale") return `${LABEL} loaded in ${probe.domain ?? launchdGuiDomain()} from an OLDER plist`;
+  if (probe.state === "unknown") return `${LABEL} state unknown: ${probe.detail ?? "launchctl could not be asked"}`;
+  return "";
+}
+
+function uninstallLaunchd(deps: { launchctl?: typeof runLaunchctl } = {}): void {
   const p = plistPath();
-  try { sh(`launchctl unload "${p}" 2>/dev/null`); } catch { /* not loaded */ }
+  // Same reason as `installLaunchd`: HOME isolation does not move this path, so without
+  // the guard an armed test process deletes the developer's live plist.
+  assertNotRealLaunchAgentsUnderTest(dirname(p));
+  stopLaunchd(deps);
   if (existsSync(p)) unlinkSync(p);
+  // The rollback copy is part of the installation, not a user file.
+  if (existsSync(`${p}.prev`)) { try { unlinkSync(`${p}.prev`); } catch { /* best-effort */ } }
 }
 
 /**
@@ -3628,11 +3929,24 @@ function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
 function platformServiceInstallCleanupOps(backend: ServiceBackend): ServiceInstallCleanupOps | null {
   if (process.platform === "darwin") {
     return {
+      // Same probe as `diagnoseService`, so the two answers to one question can no longer
+      // have opposite failure semantics: this one used to throw on a launchctl error while
+      // `statusLaunchd` swallowed it into "absent". Installing over an unverifiable
+      // manager is the unsafe case, so `unknown` fails closed here.
       status: () => {
-        const listing = sh("launchctl list");
-        return listing.split("\n").some(line => line.includes(LABEL)) ? listing : null;
+        const probe = probeLaunchdLoadState();
+        if (probe.state === "unknown") {
+          throw new Error(`launchd job status could not be verified: ${probe.detail ?? "launchctl could not be asked"}`);
+        }
+        return probe.state === "not-loaded" ? null : `${LABEL} loaded in ${probe.domain ?? launchdGuiDomain()}`;
+      },
+      // `unload` is legacy and CANNOT evict a gui-domain job, which is what this cleanup
+      // exists to do before new assets are installed.
+      stop: () => {
+        const booted = runLaunchctl(["bootout", `${launchdGuiDomain()}/${LABEL}`]);
+        if (booted.ok || booted.status === LAUNCHCTL_BOOTOUT_NO_SUCH_PROCESS) return;
+        throw new Error(`launchctl bootout failed: ${booted.stderr || `exit ${String(booted.status)}`}`);
       },
-      stop: () => { sh(`launchctl unload "${plistPath()}"`); },
     };
   }
   if (process.platform === "win32") {
@@ -4310,6 +4624,61 @@ export function deriveWindowsServiceDiagnosticForCurrentUser(
   });
 }
 
+export interface LaunchdServiceDiagnosticInputs {
+  installed: boolean;
+  stale: boolean;
+  load: LaunchdLoadProbe;
+  diagnostics: string;
+}
+
+/**
+ * Turn the launchd tri-state into a {@link ServiceDiagnostic}. Pure, so the four states
+ * are testable without a live launchd.
+ *
+ * `unknown` is the one that used to do damage. The old probe collapsed "launchctl could
+ * not be asked" into "not loaded", which printed `installed, not loaded` for a serving hub
+ * and recommended `ocx service repair` — the command that evicts the job (#4236). So:
+ *
+ * - the summary says the state could not be verified and names NO repair command, and
+ * - `viable` stays true, because `isServiceViable() === false` is what makes
+ *   `src/update/index.ts` and `src/update/job.ts` treat a successful repair as a dead
+ *   supervisor and start a competing proxy on the service's own port. A failed probe is
+ *   not evidence against the service; `startable` is likewise left alone so the tray can
+ *   still hand a start to `ocx service start`, which no-ops on an already-loaded job.
+ *
+ * `loaded-stale` keeps the viability the `launchctl list` era gave it (loaded ⇒ viable, so
+ * the update fallback behaves as before), and only the summary is upgraded — the operator
+ * is told the live job came from an older plist, which is the one case where `repair` is
+ * exactly right.
+ */
+export function deriveLaunchdServiceDiagnostic(inputs: LaunchdServiceDiagnosticInputs): ServiceDiagnostic {
+  const { installed, stale, load, diagnostics } = inputs;
+  const loaded = load.state === "loaded-current" || load.state === "loaded-stale";
+  const running = installed && loaded;
+  const verified = load.state !== "unknown";
+  const viable = installed && !stale && (loaded || !verified);
+  const summary = !installed ? `not installed (${diagnostics})`
+    : stale ? `installed, but stale (launchd; ${diagnostics})`
+      : load.state === "loaded-current" ? `installed and loaded (launchd; ${diagnostics})`
+        : load.state === "loaded-stale"
+          ? `installed and loaded from an OLDER plist (launchd; ${diagnostics})`
+          : load.state === "unknown"
+            ? `installed; launchd state could not be verified — ${load.detail ?? "launchctl could not be asked"} (launchd; ${diagnostics})`
+            : `installed, not loaded (launchd; ${diagnostics})`;
+  return {
+    supported: true,
+    installed,
+    enabled: running,
+    running,
+    viable,
+    startable: installed && !stale,
+    stale,
+    conflict: false,
+    backend: "launchd",
+    summary,
+  };
+}
+
 /**
  * Fail-closed restart diagnostic. Presence alone is never enough: conflicting
  * managers, stale baked paths, disabled registrations, and unknown/stopped
@@ -4319,14 +4688,13 @@ export function diagnoseService(): ServiceDiagnostic {
   const diagnostics = serviceDiagnosticsSummary();
   if (process.platform === "darwin") {
     const installed = existsSync(plistPath());
-    const running = installed && Boolean(statusLaunchd());
     const stale = installed && bakedServicePathsDiagnostic() !== null;
-    const viable = installed && running && !stale;
-    const summary = !installed ? `not installed (${diagnostics})`
-      : stale ? `installed, but stale (launchd; ${diagnostics})`
-        : running ? `installed and loaded (launchd; ${diagnostics})`
-          : `installed, not loaded (launchd; ${diagnostics})`;
-    return { supported: true, installed, enabled: running, running, viable, startable: installed && !stale, stale, conflict: false, backend: "launchd", summary };
+    return deriveLaunchdServiceDiagnostic({
+      installed,
+      stale,
+      load: installed ? probeLaunchdLoadState() : { state: "not-loaded" },
+      diagnostics,
+    });
   }
   if (process.platform === "win32") {
     const schedulerXml = statusWindowsXml();
@@ -4582,12 +4950,26 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
   if (command === "repair") {
     assertServiceEnvironmentMatchesInstall();
     assertServiceAuthEnvironment();
-    await repairService();
+    // A throw used to escape straight to the top level, so the one command that can
+    // leave a macOS hub evicted never reached its own serving check (#4236, defect 1f).
+    // Report the failure, then still ask whether anything is listening: on darwin the
+    // rollback inside installLaunchd may have brought the previous job back, and on
+    // Windows the preserve/restart protocol may have done the same. The operator needs
+    // both halves of that answer, and the exit code stays non-zero either way.
+    let repairError: unknown;
+    try {
+      await repairService();
+    } catch (error) {
+      repairError = error;
+      console.error(`❌ Service repair failed: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
     // All three platforms: a repair that reports success while nothing serves is the
     // defect class this unit exists to close. Windows bakes its port into the
     // scheduler wrapper or the WinSW XML, both of which installedServiceListenPort()
     // now reads.
     await reportServiceServing("repaired");
+    if (repairError !== undefined) process.exitCode = 1;
     return;
   }
   // Non-install subcommands follow the backend recorded at install time (state v2).

From 13ca31d38d0536a84581ef98e6b355f24ea12ebc Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:19:07 +0900
Subject: [PATCH 2/9] test(service): cover the launchd repair protocol and the
 load tri-state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New `tests/service/launchd-repair.test.ts`, registered in both layout maps. The five
`installLaunchd` cases in `service.test.ts` asserted the `load` verb and the stderr success
condition, so they are replaced rather than extended; what they proved about bounded retries
and about not retrying an unrelated failure is preserved in the new file.

Cases: a healthy job loaded from a byte-identical plist makes zero launchctl calls; an
identical plist whose live job runs an older command still reloads; the reload is
domain-explicit `bootstrap` with no `load`/`unload`; the settle loop waits while `print`
answers 0 and stops at 5 x 200 ms; exit 0 with a disagreeing `print` is a failure whatever
stderr says; exit 5 tries `kickstart -k`; a disabled job takes `enable` + bootstrap while an
ordinary repair never runs `enable`; a malformed plist is not retried; terminal failure
restores the previous bytes and names the manual remedy; a fresh install invents no rollback;
the LaunchAgents guard refuses the real directory. Then the probe tri-state from 0/112/113 and
a spawn failure — including "113 in gui is not absence, ask user/ too" — and all four
diagnostic states, with `unknown` producing neither "installed, not loaded" nor a repair
recommendation and not disproving `viable`.

Three source-oracle cases cover what cannot be driven without a live launchd or a whole CLI
process: the repair branch's try/catch ordering, the install-cleanup ops' probe and verb, and
the state-path filter.

Each case injects `plistPath` into a fixture directory. Without it `os.homedir()` resolves to
the real `~/Library/LaunchAgents` regardless of the HOME sandbox, which is what the existing
`withLaunchAgentHome()` helper was silently failing to prevent. The launchctl behaviour the
fixtures encode was measured on this host with a throwaway `com.opencodex.test-probe` label
and is recorded in the file header.

`stableLauncherEntry`'s two discovery cases now pass `state: null`, because the recorded
launcher wins over the PATH walk and the default reads the real install state through the
legacy path; a new case covers the recorded-launcher preference, the fall-through when it has
disappeared, and the refusal of a relative value.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 scripts/test-layout/layout.json          |   1 +
 tests/fixtures/test-layout-expected.json |   1 +
 tests/service/launchd-repair.test.ts     | 558 +++++++++++++++++++++++
 tests/service/service.test.ts            | 181 ++------
 4 files changed, 606 insertions(+), 135 deletions(-)
 create mode 100644 tests/service/launchd-repair.test.ts

diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index 937421370e..4d02cb0ea5 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -794,6 +794,7 @@
     "lab-public-wire-contract.test.ts": "lab",
     "lab-read-filter-validation.test.ts": "lab",
     "lab-read-surfaces.test.ts": "lab",
+    "launchd-repair.test.ts": "service",
     "legacy-shell-compat.test.ts": "responses",
     "live-service-manager-guard.test.ts": "service",
     "local-management-attestation.test.ts": "server",
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 12a4b7f308..2670f61761 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -629,6 +629,7 @@
   "lab-public-wire-contract.test.ts": "lab",
   "lab-read-filter-validation.test.ts": "lab",
   "lab-read-surfaces.test.ts": "lab",
+  "launchd-repair.test.ts": "service",
   "legacy-shell-compat.test.ts": "responses",
   "live-service-manager-guard.test.ts": "service",
   "local-management-attestation.test.ts": "server",
diff --git a/tests/service/launchd-repair.test.ts b/tests/service/launchd-repair.test.ts
new file mode 100644
index 0000000000..8916775935
--- /dev/null
+++ b/tests/service/launchd-repair.test.ts
@@ -0,0 +1,558 @@
+/**
+ * macOS repair/status protocol — issue #4236, defects 1 and 2.
+ *
+ * The reported failure: one `ocx service repair` on a hub took the public proxy, the
+ * management ingress and the loopback listener down at once, printed success, and left
+ * `ocx status` recommending the same repair. On darwin `repair` IS `installLaunchd`, which
+ * evicted the live job with a domain-explicit `bootout`, re-registered with the
+ * domain-IMPLICIT legacy `launchctl load -w`, and accepted exit-0-with-empty-stderr as
+ * proof. Measured on macOS 27.0 (Darwin 27, arm64) with a throwaway
+ * `com.opencodex.test-probe` label:
+ *
+ *   launchctl print gui/$uid/<label>      → 0 loaded | 113 no such service | 112 no such domain
+ *   launchctl bootstrap gui/$uid <plist>  → 0 first time, 5 "Bootstrap failed: 5" when bootstrapped
+ *   launchctl load -w <plist>             → 0 AND "Load failed: 5" when bootstrapped (the no-op)
+ *   launchctl kickstart -k gui/$uid/<l>   → 0 loaded | 113 absent
+ *   launchctl bootout gui/$uid/<label>    → 0 evicted | 3 "Boot-out failed: 3: No such process"
+ *
+ * Every case here drives the injected seam and reaches no real launchd: the
+ * live-service-manager guard refuses `bootout`/`bootstrap` from an armed test process, and
+ * `installLaunchd` is handed an explicit plist path because `os.homedir()` reads the
+ * password database rather than `$HOME` — so the suite's HOME sandbox does NOT move
+ * `~/Library/LaunchAgents`, and a case without that seam rewrites the developer's own live
+ * `com.opencodex.proxy.plist`.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildPlist,
+  deriveLaunchdServiceDiagnostic,
+  installLaunchd,
+  probeLaunchdLoadState,
+  resolvedProxyEnv,
+  runLaunchctl,
+  stableLauncherEntry,
+} from "../../src/service";
+import { protectedLaunchAgentsDirForTests } from "../../src/lib/test-home-guard";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * Pin OPENCODEX_HOME per case. `buildPlist` reads config through `getConfigDir()`, and when
+ * OPENCODEX_HOME is absent that falls back to `join(homedir(), ".opencodex")` — the real
+ * one, because `os.homedir()` ignores `$HOME`. A sibling file in the same Bun worker that
+ * clears or restores the variable would otherwise make these cases fail on the real-home
+ * guard instead of on anything they assert.
+ */
+beforeEach(() => {
+  const home = mkdtempSync(join(tmpdir(), "ocx-launchd-home-"));
+  mkdirSync(join(home, ".opencodex"), { recursive: true });
+  process.env.OPENCODEX_HOME = join(home, ".opencodex");
+});
+
+type LaunchctlResult = { ok: boolean; stdout: string; stderr: string; status: number | null };
+
+function ok(stdout = ""): LaunchctlResult {
+  return { ok: true, stdout, stderr: "", status: 0 };
+}
+function fail(status: number, stderr: string): LaunchctlResult {
+  return { ok: false, stdout: "", stderr, status };
+}
+
+/**
+ * A `runLaunchctl` stand-in that records every argv and answers from a per-verb script.
+ * `bootstrap` consumes its queue; exhausting it is a fixture bug, not a passing case.
+ */
+function recordingLaunchctl(script: {
+  bootstrap?: LaunchctlResult[];
+  print?: LaunchctlResult;
+  kickstart?: LaunchctlResult;
+  bootout?: LaunchctlResult;
+}) {
+  const argv: string[][] = [];
+  let bootstraps = 0;
+  const launchctl = ((args: string[]): LaunchctlResult => {
+    argv.push([...args]);
+    const verb = args[0] ?? "";
+    if (verb === "bootstrap") {
+      const queued = script.bootstrap?.[bootstraps++];
+      if (!queued) throw new Error(`unexpected bootstrap #${bootstraps}: the fixture queued ${script.bootstrap?.length ?? 0}`);
+      return queued;
+    }
+    // Default `print` is 113 so the settle loop sees an evicted domain and returns at once.
+    if (verb === "print") return script.print ?? fail(113, "Could not find service");
+    if (verb === "kickstart") return script.kickstart ?? ok();
+    if (verb === "bootout") return script.bootout ?? ok();
+    return ok();
+  }) as typeof runLaunchctl;
+  return { argv, launchctl };
+}
+
+const verbs = (argv: string[][]): string[] => argv.map(args => args[0] ?? "");
+
+/** A fixture LaunchAgents directory plus the plist path inside it. */
+function fixturePlist(): string {
+  return join(mkdtempSync(join(tmpdir(), "ocx-launchd-repair-")), "com.opencodex.proxy.plist");
+}
+
+/** The plist `installLaunchd` will render in this process, for the byte-identical case. */
+function renderedPlist(): string {
+  return buildPlist(resolvedProxyEnv(), { launcher: stableLauncherEntry() });
+}
+
+describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () => {
+  test("a healthy job loaded from a byte-identical plist is a no-op — launchd is never touched", () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, renderedPlist(), "utf8");
+    const { argv, launchctl } = recordingLaunchctl({});
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: true, matchesPlist: true }),
+      sleepSync: () => {},
+    });
+
+    // THE regression: no bootout, no bootstrap, no kickstart. Repairing a serving hub
+    // used to evict it unconditionally.
+    expect(argv).toEqual([]);
+    // And nothing was backed up, because nothing was overwritten.
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
+  });
+
+  test("an identical plist whose job is loaded from an OLDER command still reloads", () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, renderedPlist(), "utf8");
+    let matchCalls = 0;
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // First call is the no-op pre-check (stale ⇒ do the repair); the second is the
+      // post-bootstrap verification.
+      matches: () => ({ loaded: true, matchesPlist: matchCalls++ > 0 }),
+      sleepSync: () => {},
+    });
+
+    expect(verbs(argv)).toContain("bootstrap");
+  });
+
+  test("the reload is domain-explicit bootstrap, not legacy load -w", () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: true, matchesPlist: true }),
+      sleepSync: () => {},
+    });
+
+    // `load` acts on the CALLER's bootstrap domain, so from ssh/cron it deleted the
+    // gui-domain job and registered nothing (defect 1a).
+    expect(verbs(argv)).not.toContain("load");
+    expect(verbs(argv)).not.toContain("unload");
+    const bootstrap = argv.find(args => args[0] === "bootstrap");
+    expect(bootstrap?.[1]).toMatch(/^gui\/\d+$/);
+    expect(bootstrap?.[2]).toBe(plistPath);
+    const bootout = argv.find(args => args[0] === "bootout");
+    expect(bootout?.[1]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+    // bootout before bootstrap, with the settle probe in between.
+    expect(verbs(argv).indexOf("bootout")).toBeLessThan(verbs(argv).indexOf("bootstrap"));
+  });
+
+  test("the settle loop waits while print still answers 0, and is bounded", () => {
+    const plistPath = fixturePlist();
+    const delays: number[] = [];
+    // `print` keeps answering 0: the job has not finished exiting.
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()], print: ok("live") });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: true, matchesPlist: true }),
+      sleepSync: ms => { delays.push(ms); },
+    });
+
+    // 5 × 200 ms, then give up and try the bootstrap anyway — a wedged domain must reach
+    // the diagnosable throw rather than hang.
+    expect(delays).toEqual([200, 200, 200, 200, 200]);
+    expect(verbs(argv).filter(v => v === "print")).toHaveLength(5);
+  });
+
+  test("a clean bootstrap that did not take is a FAILURE, whatever stderr says", () => {
+    const plistPath = fixturePlist();
+    // Both bootstraps exit 0 with empty stderr — the old success condition exactly.
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok(), ok()] });
+
+    expect(() => installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: false, matchesPlist: false }),
+      sleepSync: () => {},
+    })).toThrow(/could not bootstrap/);
+
+    // Exit 0 + `print` disagreeing is a silent no-op, so it IS worth one more eviction.
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(2);
+  });
+
+  test("'Bootstrap failed: 5' tries kickstart -k before a second eviction", () => {
+    const plistPath = fixturePlist();
+    let matchCalls = 0;
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [fail(5, "Bootstrap failed: 5: Input/output error")],
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // First verification (right after the refused bootstrap) fails; the one after
+      // `kickstart -k` succeeds.
+      matches: () => {
+        const loaded = matchCalls++ >= 1;
+        return { loaded, matchesPlist: loaded };
+      },
+      sleepSync: () => {},
+    });
+
+    expect(verbs(argv)).toContain("kickstart");
+    const kickstart = argv.find(args => args[0] === "kickstart");
+    expect(kickstart?.slice(1)).toEqual(["-k", kickstart?.[2] ?? ""]);
+    expect(kickstart?.[2]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+    // One bootstrap only: kickstart recovered it without a second eviction window.
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(1);
+  });
+
+  /**
+   * The second meaning of exit 5. Measured on macOS 27.0: `launchctl disable gui/$uid/<label>`
+   * makes `bootstrap` fail with the SAME "Bootstrap failed: 5: Input/output error" while
+   * `print` reports 113 and `kickstart -k` reports 113. Legacy `load -w` cleared that flag —
+   * that is what the `-w` meant — so dropping it without `enable` would make a disabled job
+   * permanently unrepairable.
+   */
+  test("a DISABLED job is enabled and bootstrapped, the modern spelling of load -w", () => {
+    const plistPath = fixturePlist();
+    let matchCalls = 0;
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [fail(5, "Bootstrap failed: 5: Input/output error"), ok()],
+      kickstart: fail(113, 'Could not find service "com.opencodex.proxy" in domain for user gui: 501'),
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // Loaded only after the enable + second bootstrap. `kickstart` failing
+      // short-circuits its own verification, so this is asked exactly twice.
+      matches: () => {
+        const loaded = matchCalls++ >= 1;
+        return { loaded, matchesPlist: loaded };
+      },
+      sleepSync: () => {},
+    });
+
+    expect(verbs(argv)).toEqual(["bootout", "print", "bootstrap", "kickstart", "enable", "bootout", "print", "bootstrap"]);
+    const enable = argv.find(args => args[0] === "enable");
+    expect(enable?.[1]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+  });
+
+  test("an ordinary repair never runs enable, so a deliberate disable is not undone", () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: true, matchesPlist: true }),
+      sleepSync: () => {},
+    });
+
+    expect(verbs(argv)).not.toContain("enable");
+  });
+
+  test("a malformed plist is not retried — the real stderr reaches the operator", () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [fail(1, "Could not read plist: invalid XML")],
+    });
+
+    expect(() => installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: false, matchesPlist: false }),
+      sleepSync: () => {},
+    })).toThrow(/invalid XML/);
+
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(1);
+    expect(verbs(argv)).not.toContain("kickstart");
+  });
+
+  test("terminal failure restores the previous plist bytes and names the manual remedy", () => {
+    const plistPath = fixturePlist();
+    const previous = "<plist>the definition that was serving</plist>\n";
+    writeFileSync(plistPath, previous, "utf8");
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok(), ok(), ok()] });
+
+    let thrown: unknown;
+    try {
+      installLaunchd({
+        launchctl,
+        plistPath,
+        matches: () => ({ loaded: false, matchesPlist: false }),
+        sleepSync: () => {},
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    // The operator must be told the job is DOWN — the silent version of this is the outage.
+    expect(message).toMatch(/evicted from gui\/\d+/);
+    // And given the one command that recovered the real host, which `ocx` never printed.
+    expect(message).toMatch(/launchctl bootstrap gui\/\d+ /);
+    expect(message).toContain(plistPath);
+    // Exit 5 can also mean the label sits in the domain's disabled list, so point at it.
+    expect(message).toMatch(/launchctl print-disabled gui\/\d+/);
+    // Rollback: the bytes that were serving are back on disk, and backed up next to it.
+    expect(readFileSync(plistPath, "utf8")).toBe(previous);
+    expect(readFileSync(`${plistPath}.prev`, "utf8")).toBe(previous);
+    // The third bootstrap is the rollback's own re-registration attempt.
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(3);
+  });
+
+  test("a fresh install has nothing to restore and says so without inventing a rollback", () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok(), ok()] });
+
+    expect(() => installLaunchd({
+      launchctl,
+      plistPath,
+      matches: () => ({ loaded: false, matchesPlist: false }),
+      sleepSync: () => {},
+    })).toThrow(/ocx service install/);
+
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(2);
+  });
+
+  test("the armed test guard refuses the developer's real LaunchAgents directory", () => {
+    // Without the seam above, every case in this file rewrote the live plist.
+    expect(() => installLaunchd({
+      plistPath: join(protectedLaunchAgentsDirForTests(), "com.opencodex.proxy.plist"),
+      launchctl: recordingLaunchctl({}).launchctl,
+      matches: () => ({ loaded: true, matchesPlist: true }),
+      sleepSync: () => {},
+    })).toThrow(/real LaunchAgents directory/);
+  });
+});
+
+describe("probeLaunchdLoadState: a tri-state, not one swallowed bit (#4236 defect 2)", () => {
+  const printed = (command: string): LaunchctlResult => ok(`{\n\targuments = {\n\t\t${command}\n\t}\n}`);
+
+  function probeWith(answers: Array<LaunchctlResult>, expected = "exec 'ocx' start --port 10100") {
+    const asked: string[] = [];
+    let call = 0;
+    const launchctl = ((args: string[]) => {
+      asked.push(args[1] ?? "");
+      return answers[call++] ?? fail(113, "Could not find service");
+    }) as typeof runLaunchctl;
+    return { asked, probe: probeLaunchdLoadState({ launchctl, uid: 501, expectedCommand: () => expected }) };
+  }
+
+  test("exit 0 with the expected command is loaded-current", () => {
+    const { asked, probe } = probeWith([printed("exec 'ocx' start --port 10100")]);
+    expect(probe.state).toBe("loaded-current");
+    expect(probe.domain).toBe("gui/501");
+    // The gui domain answered, so the user domain is not asked.
+    expect(asked).toEqual(["gui/501/com.opencodex.proxy"]);
+  });
+
+  test("exit 0 with a different command is loaded-stale", () => {
+    const { probe } = probeWith([printed("exec '/old/bun' /old/cli.ts start --port 10100")]);
+    expect(probe.state).toBe("loaded-stale");
+  });
+
+  test("113 in gui is not absence — the user domain is asked too", () => {
+    const { asked, probe } = probeWith([
+      fail(113, "Could not find service"),
+      printed("exec 'ocx' start --port 10100"),
+    ]);
+    // `gui/` and `user/` are independent and hold separate service sets; asking one left
+    // the other free to hold a job the old `launchctl list | grep` called absent.
+    expect(asked).toEqual(["gui/501/com.opencodex.proxy", "user/501/com.opencodex.proxy"]);
+    expect(probe.state).toBe("loaded-current");
+    expect(probe.domain).toBe("user/501");
+  });
+
+  test("113 from both domains is proof of absence", () => {
+    const { probe } = probeWith([fail(113, "Could not find service"), fail(113, "Could not find service")]);
+    expect(probe.state).toBe("not-loaded");
+  });
+
+  test("112 is an answer about the DOMAIN and cannot hide a job of ours", () => {
+    // A headless Mac has no GUI domain and no installation either; calling that `unknown`
+    // would refuse every verdict on it.
+    const { probe } = probeWith([fail(112, "Could not find domain for"), fail(113, "Could not find service")]);
+    expect(probe.state).toBe("not-loaded");
+  });
+
+  test("a spawn failure is unknown, never absence", () => {
+    const { probe } = probeWith([{ ok: false, stdout: "", stderr: "spawn /bin/launchctl ENOENT", status: null }]);
+    expect(probe.state).toBe("unknown");
+    expect(probe.detail).toContain("launchctl could not be run");
+  });
+
+  test("an undocumented exit status is unknown, never absence", () => {
+    // EPERM from a bootstrap server, a missing grep, an execSync maxBuffer overflow: the
+    // old probe collapsed all of them into the same empty string as genuine absence.
+    const { probe } = probeWith([fail(1, "Operation not permitted")]);
+    expect(probe.state).toBe("unknown");
+    expect(probe.detail).toContain("exited 1");
+  });
+});
+
+describe("deriveLaunchdServiceDiagnostic: what status is allowed to claim", () => {
+  const diagnostics = "paths ok";
+
+  test("loaded-current is loaded and viable", () => {
+    const diag = deriveLaunchdServiceDiagnostic({
+      installed: true, stale: false, load: { state: "loaded-current", domain: "gui/501" }, diagnostics,
+    });
+    expect(diag.summary).toContain("installed and loaded (launchd;");
+    expect(diag.running).toBe(true);
+    expect(diag.viable).toBe(true);
+  });
+
+  test("loaded-stale says which plist, instead of claiming health", () => {
+    const diag = deriveLaunchdServiceDiagnostic({
+      installed: true, stale: false, load: { state: "loaded-stale", domain: "gui/501" }, diagnostics,
+    });
+    expect(diag.summary).toContain("loaded from an OLDER plist");
+    expect(diag.running).toBe(true);
+  });
+
+  test("not-loaded keeps the actionable text", () => {
+    const diag = deriveLaunchdServiceDiagnostic({
+      installed: true, stale: false, load: { state: "not-loaded" }, diagnostics,
+    });
+    expect(diag.summary).toContain("installed, not loaded (launchd;");
+    expect(diag.running).toBe(false);
+    expect(diag.viable).toBe(false);
+  });
+
+  test("unknown never prints 'installed, not loaded' and never recommends repair", () => {
+    const diag = deriveLaunchdServiceDiagnostic({
+      installed: true,
+      stale: false,
+      load: { state: "unknown", detail: "launchctl print gui/501/com.opencodex.proxy exited 1" },
+      diagnostics,
+    });
+    // The reported symptom was `installed, not loaded` above a live proxy, with
+    // `re-run 'ocx service repair'` attached — the command that causes defect 1.
+    expect(diag.summary).not.toContain("not loaded");
+    expect(diag.summary).not.toContain("service repair");
+    expect(diag.summary).toContain("could not be verified");
+    expect(diag.summary).toContain("exited 1");
+    // And `viable` stays true: `isServiceViable() === false` is what makes the update
+    // fallback (src/update/index.ts, src/update/job.ts) treat a successful repair as a
+    // dead supervisor and start a COMPETING proxy on the service's own port. A failed
+    // probe is not evidence against the service.
+    expect(diag.viable).toBe(true);
+    expect(diag.startable).toBe(true);
+  });
+
+  test("stale baked paths still win over every load state", () => {
+    for (const state of ["loaded-current", "loaded-stale", "not-loaded", "unknown"] as const) {
+      const diag = deriveLaunchdServiceDiagnostic({ installed: true, stale: true, load: { state }, diagnostics });
+      expect(diag.summary).toContain("installed, but stale");
+      expect(diag.viable).toBe(false);
+    }
+  });
+
+  test("not installed reports absence whatever the probe says", () => {
+    const diag = deriveLaunchdServiceDiagnostic({
+      installed: false, stale: false, load: { state: "unknown", detail: "x" }, diagnostics,
+    });
+    expect(diag.summary).toBe(`not installed (${diagnostics})`);
+    expect(diag.viable).toBe(false);
+  });
+});
+
+/**
+ * Source-oracle cases. The two remaining defects are shapes of the command dispatcher and
+ * the install-cleanup ops, neither of which can be driven without a live launchd or a whole
+ * CLI process, so assert the shape instead of mocking the world.
+ */
+describe("the surfaces around the repair (#4236 defects 1f, 1h, 2)", () => {
+  const source = readFileSync(repoPath("src", "service.ts"), "utf8");
+
+  function slice(from: string, to: string): string {
+    const start = source.indexOf(from);
+    expect(start).toBeGreaterThan(-1);
+    const end = source.indexOf(to, start + from.length);
+    expect(end).toBeGreaterThan(start);
+    return source.slice(start, end);
+  }
+
+  test("the repair branch still reports serving when repairService throws (1f)", () => {
+    const branch = slice('if (command === "repair") {', "// Non-install subcommands follow");
+    // Without the catch, a throw escaped through src/cli/dispatch.ts to the top level and
+    // the one command that can evict a hub never reached its own serving check.
+    expect(branch).toContain("try {");
+    expect(branch).toContain("await repairService();");
+    expect(branch).toContain("} catch (error) {");
+    expect(branch).toContain('await reportServiceServing("repaired");');
+    expect(branch).toContain("process.exitCode = 1;");
+    // The serving check must not be inside the try, or a throw would still skip it.
+    expect(branch.indexOf("} catch (error) {")).toBeLessThan(branch.indexOf('reportServiceServing("repaired")'));
+  });
+
+  test("install cleanup uses the same probe and the modern evict verb (1h, 2)", () => {
+    const ops = slice("function platformServiceInstallCleanupOps(", 'if (process.platform === "win32") {');
+    // `unload` cannot evict a gui-domain job — the file's own comment on installLaunchd
+    // says so — and `launchctl list` was the other half of defect 2.
+    expect(ops).not.toContain("launchctl unload");
+    expect(ops).not.toContain('sh("launchctl list")');
+    expect(ops).toContain("probeLaunchdLoadState()");
+    expect(ops).toContain('runLaunchctl(["bootout"');
+    // Installing over a manager we could not query is the unsafe direction, so this probe
+    // keeps failing closed on `unknown` even though `diagnoseService` does not.
+    expect(ops).toContain('probe.state === "unknown"');
+  });
+
+  test("diagnoseService no longer grep-matches launchctl list (2)", () => {
+    const branch = slice("export function diagnoseService()", 'if (process.platform === "win32") {');
+    expect(branch).toContain("probeLaunchdLoadState()");
+    expect(branch).toContain("deriveLaunchdServiceDiagnostic(");
+    expect(branch).not.toContain("statusLaunchd");
+    // The executable form is gone; the prose naming what it did deliberately stays.
+    expect(source).not.toContain("sh(`launchctl list | grep");
+  });
+
+  /**
+   * Found while building the cases above: `installLaunchd` writes install state, and
+   * `serviceStatePaths()` deliberately includes a legacy `~/.opencodex/service-state.json`
+   * entry for installs made before OPENCODEX_HOME existed. Under the test sandbox that
+   * entry is the developer's LIVE record — one case replaced its codexHome and
+   * opencodexHome with temp-directory paths before this filter existed.
+   */
+  test("install state never reaches the real home from a test process", () => {
+    const fn = slice("function serviceStatePaths()", "function currentCodexHome(");
+    expect(fn).toContain("isTestHomeGuardArmed()");
+    expect(fn).toContain("protectedHomeForTests()");
+    expect(fn).toContain("paths.filter(");
+  });
+
+  test("stop and uninstall prefer bootout and keep unload only as a fallback (D)", () => {
+    const stop = slice("function stopLaunchd(", "function statusLaunchd(");
+    expect(stop).toContain('run(["bootout"');
+    // The legacy verb survives for exactly one case: launchctl could not be spawned at
+    // all (`status === null`), which is the only state a second attempt can improve.
+    expect(stop).toContain("launchctl unload");
+    expect(stop.indexOf('run(["bootout"')).toBeLessThan(stop.indexOf("launchctl unload"));
+    const uninstall = slice("function uninstallLaunchd(", "/**");
+    expect(uninstall).toContain("stopLaunchd(deps)");
+    expect(uninstall).not.toContain("launchctl unload");
+  });
+});
diff --git a/tests/service/service.test.ts b/tests/service/service.test.ts
index e6362201c8..ed521a0c1d 100644
--- a/tests/service/service.test.ts
+++ b/tests/service/service.test.ts
@@ -9,7 +9,7 @@ import { saveConfig } from "../../src/config";
 import { windowsEnvIndirectBatchValue } from "../../src/lib/win-paths";
 import { assertServiceAuthEnvironment, assertServiceEnvironmentMatchesInstall, bakedServicePathsDiagnostic, confirmServiceServing, launchdListenPort, systemdListenPort, buildPlist, buildUnit, buildWindowsLauncherVbs, buildWindowsSchtasksCreateArgs, buildWindowsSchtasksCreateArgsForXml, buildWindowsServiceScript, buildWindowsTaskXml as buildWindowsTaskXmlProduction, buildWindowsTaskXmlDocument, deriveWindowsServiceDiagnostic, deriveWindowsServiceDiagnosticForCurrentUser, expectedLaunchdCommand, installFreshWindowsSchedulerSafely, installServiceSafely, launchctlLoadFailed, launchdJobMatchesPlist, normalizeServiceSubcommand, parseServiceArgs, parseServiceInstallState, planServiceCommand, prepareServiceInstall, probeServiceInstallation, readWindowsSchedulerXmlState, registerFreshWindowsSchedulerTask, removeNativeWindowsServiceForScheduler, repairService, reportServiceServing, resolveServiceListenPort, runLaunchctl, selectServiceSubcommand, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, serviceLogPath, serviceStartableFromTray, serviceStatusReport, serviceRetryCommand, serviceStatusSummary, stableLauncherEntry, systemdNeedsDaemonReload, systemdServiceInstallCleanupOps, uninstallSystemd, windowsListenPort, winswListenPort, startLaunchd, windowsTaskRegistrationHealthy as windowsTaskRegistrationHealthyProduction } from "../../src/service";
 import type { ServiceDiagnostic } from "../../src/service";
-import { definitionCarriesCredential, installLaunchd, resolvedProxyEnv, writeServiceDefinitionFile } from "../../src/service";
+import { definitionCarriesCredential, resolvedProxyEnv, writeServiceDefinitionFile } from "../../src/service";
 import { buildWinswXml } from "../../src/lib/winsw";
 import { CONFIG_OWNER_FILE, CONFIG_UNINSTALL_MANIFEST, recordOwnedConfigPath, removeOwnedConfigState } from "../../src/lib/config-ownership";
 import { serviceApiTokenFilePath } from "../../src/lib/service-secrets";
@@ -137,6 +137,11 @@ describe("systemd service unit", () => {
     const second = join(TEST_DIR, "second");
     const probes: string[] = [];
     const result = stableLauncherEntry({
+      // `state: null` is what keeps this a PATH-discovery test. The recorded install
+      // launcher now wins over discovery (#4236 defect 1g), and the default reads the real
+      // `~/.opencodex/service-state.json` through the legacy fallback path, so leaving it
+      // out would make this assert the developer's own install instead.
+      state: null,
       env: { PATH: [first, second].join(delimiter) },
       isExecutableFile: candidate => {
         probes.push(candidate);
@@ -160,6 +165,7 @@ describe("systemd service unit", () => {
     writeFileSync(join(executableEntry, "ocx"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
     try {
       expect(stableLauncherEntry({
+        state: null,
         env: { PATH: [directoryEntry, nonExecutableEntry, executableEntry].join(delimiter) },
       })).toBe(join(executableEntry, "ocx"));
     } finally {
@@ -167,6 +173,41 @@ describe("systemd service unit", () => {
     }
   });
 
+  /**
+   * #4236 defect 1g: `ocx service repair` run from a context without `ocx` on PATH — a
+   * tray helper, `ocx update`'s child, a cron/ssh session — resolved null here, rewrote a
+   * working launcher-form plist into the version-pinned Bun + CLI pair, and then booted the
+   * healthy job out to load it. The launcher the install already recorded is what launchd
+   * is running, so repair must keep naming it.
+   */
+  test("a recorded launcher that still exists wins over an empty PATH", () => {
+    const recorded = join(TEST_DIR, "recorded", "ocx");
+    const state = { version: 2, backend: "scheduler", launcherPath: recorded } as never;
+
+    expect(stableLauncherEntry({
+      state,
+      env: { PATH: "" },
+      isExecutableFile: candidate => candidate === recorded,
+    })).toBe(recorded);
+
+    // A recorded launcher that has disappeared falls through to discovery rather than
+    // baking a path launchd cannot resolve.
+    const discovered = join(TEST_DIR, "discovered", "ocx");
+    expect(stableLauncherEntry({
+      state,
+      env: { PATH: join(TEST_DIR, "discovered") },
+      isExecutableFile: candidate => candidate === discovered,
+    })).toBe(discovered);
+
+    // A relative recorded value is refused for the same reason a bare `ocx` is: launchd
+    // would re-resolve it through PATH on every restart.
+    expect(stableLauncherEntry({
+      state: { version: 2, backend: "scheduler", launcherPath: "ocx" } as never,
+      env: { PATH: "" },
+      isExecutableFile: () => true,
+    })).toBe(null);
+  });
+
   test("bare service installs only when absent and otherwise selects no-admin repair", async () => {
     expect(normalizeServiceSubcommand()).toBe("install");
     expect(normalizeServiceSubcommand("restart")).toBe("repair");
@@ -3328,141 +3369,11 @@ describe("launchctl load verification", () => {
   });
 
   /**
-   * #4141: after `ocx update` the job never came back. Repair on darwin is
-   * `installLaunchd`, which best-effort `unload`ed the plist and then threw on any
-   * `Load failed`. But `unload` does not evict a job bootstrapped into the GUI domain,
-   * and that is exactly the state modern launchd reports with "Load failed: 5:
-   * Input/output error" while exiting 0 — so a live-but-stale job was precisely the case
-   * that could not repair itself, and the thrown text carried the `bootout` recipe as a
-   * hint that nothing ever ran.
-   *
-   * These drive the injected seam. They never reach launchd: the live-service-manager
-   * guard refuses `bootout` from an armed test process, so a test on the real runner
-   * would fail closed on the guard rather than exercise anything.
+   * `installLaunchd` coverage lives in `tests/service/launchd-repair.test.ts`. It moved
+   * out of this file when the repair protocol grew a no-op pre-check, a plist backup and
+   * a rollback: those cases need an injected plist path (os.homedir() ignores HOME, so
+   * the suite sandbox does not move `~/Library/LaunchAgents`) and a full fixture per case.
    */
-  describe("installLaunchd", () => {
-    // A runLaunchctl RESULT, not a spawnSync result.
-    function recordingLaunchctl(loadResults: Array<{ ok: boolean; stderr: string }>) {
-      const argv: string[][] = [];
-      let loads = 0;
-      const launchctl = ((args: string[]) => {
-        argv.push([...args]);
-        if (args[0] !== "load") return { ok: true, stdout: "", stderr: "", status: 0 };
-        // Exhausting the queue is a fixture bug, not a passing case. Defaulting a missing
-        // entry to success once hid a retry that never got the failure it was meant to
-        // assert, so make the fixture state its own call count or fail loudly.
-        const next = loadResults[loads++];
-        if (!next) throw new Error(`unexpected load #${loads}: the fixture queued ${loadResults.length}`);
-        return { ok: next.ok, stdout: "", stderr: next.stderr, status: next.ok ? 0 : 1 };
-      }) as typeof runLaunchctl;
-      return { argv, launchctl };
-    }
-
-    const BOOTSTRAPPED = "Load failed: 5: Input/output error";
-
-    /**
-     * installLaunchd writes the plist under `homedir()/Library/LaunchAgents`. The preload
-     * already sandboxes HOME; pinning a fresh one per case keeps these from writing into
-     * whatever another test left there.
-     */
-    function withLaunchAgentHome(run: () => void): void {
-      const previousHome = process.env.HOME;
-      const previousUserProfile = process.env.USERPROFILE;
-      const dir = mkdtempSync(join(tmpdir(), "ocx-launchd-install-"));
-      process.env.HOME = dir;
-      process.env.USERPROFILE = dir;
-      try {
-        run();
-      } finally {
-        if (previousHome === undefined) delete process.env.HOME;
-        else process.env.HOME = previousHome;
-        if (previousUserProfile === undefined) delete process.env.USERPROFILE;
-        else process.env.USERPROFILE = previousUserProfile;
-      }
-    }
-
-    const verbs = (argv: string[][]): string[] => argv.map(args => args[0] ?? "");
-
-    test("evicts a stale job, and recovers on the retried load", () => {
-      const { argv, launchctl } = recordingLaunchctl([
-        { ok: true, stderr: BOOTSTRAPPED },
-        { ok: true, stderr: "" },
-      ]);
-
-      withLaunchAgentHome(() => {
-        expect(() => installLaunchd({ launchctl })).not.toThrow();
-      });
-
-      // The whole repair, in order. Red before the fix: it threw on the first
-      // `Load failed` without ever running `bootout`.
-      expect(verbs(argv)).toEqual(["bootout", "load", "bootout", "load"]);
-      // The legacy verb is gone: it is what failed to evict the job in the first place.
-      expect(verbs(argv)).not.toContain("unload");
-      expect(argv[0]?.[1]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
-      expect(argv[2]?.[1]).toBe(argv[0]?.[1]);
-      expect(argv[1]?.slice(0, 2)).toEqual(["load", "-w"]);
-      expect(argv[3]?.slice(0, 2)).toEqual(["load", "-w"]);
-    });
-
-    test("a clean load is never retried, so a healthy job is evicted once and reloaded", () => {
-      const { argv, launchctl } = recordingLaunchctl([{ ok: true, stderr: "" }]);
-
-      withLaunchAgentHome(() => {
-        expect(() => installLaunchd({ launchctl })).not.toThrow();
-      });
-
-      expect(verbs(argv)).toEqual(["bootout", "load"]);
-    });
-
-    test("still throws when the job survives both evictions", () => {
-      const { argv, launchctl } = recordingLaunchctl([
-        { ok: true, stderr: BOOTSTRAPPED },
-        { ok: true, stderr: BOOTSTRAPPED },
-      ]);
-
-      withLaunchAgentHome(() => {
-        expect(() => installLaunchd({ launchctl })).toThrow(/could not load/);
-      });
-
-      // Bounded: two evictions and two loads, then the diagnosable throw. A loop here
-      // would turn a wedged domain into a hang.
-      expect(verbs(argv)).toEqual(["bootout", "load", "bootout", "load"]);
-    });
-
-    /**
-     * `launchctlLoadFailed` matches "Bootstrap failed" as well as "Load failed", and both
-     * mean the same thing here: something is still bootstrapped in the domain. So this
-     * retries, and the regex itself is left alone — it is the 2026-08-02 silent-success
-     * guard, and the fix is to recover from the condition rather than stop detecting it.
-     */
-    test("a Bootstrap failed load takes the same eviction and retry", () => {
-      const bootstrapFailed = { ok: false, stderr: "Bootstrap failed: 37: Operation already in progress" };
-      const { argv, launchctl } = recordingLaunchctl([bootstrapFailed, bootstrapFailed]);
-
-      withLaunchAgentHome(() => {
-        expect(() => installLaunchd({ launchctl })).toThrow(/could not load/);
-      });
-
-      expect(verbs(argv)).toEqual(["bootout", "load", "bootout", "load"]);
-    });
-
-    /**
-     * The retry is scoped to that signal on purpose. A load that fails for another
-     * reason — a malformed plist, say — is not fixed by evicting a job, so retrying
-     * would only delay the real stderr reaching the operator.
-     */
-    test("a plain non-zero load with unrelated stderr throws without a second eviction", () => {
-      const { argv, launchctl } = recordingLaunchctl([
-        { ok: false, stderr: "Could not read plist: invalid XML" },
-      ]);
-
-      withLaunchAgentHome(() => {
-        expect(() => installLaunchd({ launchctl })).toThrow(/invalid XML/);
-      });
-
-      expect(verbs(argv)).toEqual(["bootout", "load"]);
-    });
-  });
 });
 
 /**

From 1b98b686be6e0661a571e1ea25852993cd96eb36 Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:19:16 +0900
Subject: [PATCH 3/9] docs(devlog): record the launchd repair/status lane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`devlog/_plan/260911_hub_single_port/010_launchd_repair.md`: what shipped for issue #4236
defects 1 and 2, the launchctl exit codes measured on this host with a throwaway label (both
meanings of "Bootstrap failed: 5", which is what put `enable` in the retry path), the
decisions — `unknown` keeping `viable` true so the update fallback cannot start a competing
proxy, `loaded-stale` keeping its old viability, verifying against the command the install
baked rather than recorded state, and why `startLaunchd` keeps `load -w` — and the exact
verification commands with their pass/fail counts, including the 9 pre-existing domain-run
failures that are identical on `dev`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../010_launchd_repair.md                     | 226 ++++++++++++++++++
 1 file changed, 226 insertions(+)
 create mode 100644 devlog/_plan/260911_hub_single_port/010_launchd_repair.md

diff --git a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
new file mode 100644
index 0000000000..21208108f5
--- /dev/null
+++ b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
@@ -0,0 +1,226 @@
+# PR1 — macOS launchd repair/status (issue #4236 defects 1 & 2)
+
+Branch `codex/260911-l4-launchd-repair`, based on `dev` (`babb76449`). First of the four-PR
+hub single-port stack; the others target this branch's head in turn.
+
+Scope: `src/service.ts` macOS path only, plus the two shared test-safety guards the work
+uncovered. Defects 3 and 4 from the issue (secondary-port misdiagnosis, `ocx status` fence
+comparison) are deliberately left to PR2, which owns the loopback listener.
+
+## What shipped
+
+### A — `installLaunchd()` (repair must not be an outage)
+
+1. **No-op pre-check.** The plist is rendered BEFORE anything is written. If the rendered
+   bytes equal the on-disk bytes, the data-token file is unchanged, and
+   `launchdJobMatchesPlist()` reports `{loaded:true, matchesPlist:true}`, the function
+   re-asserts 0600 on the plist, refreshes install state, logs
+   `service is already loaded from the current plist; nothing to do.` and returns. launchd is
+   not touched at all. This is the headline fix: a repair of a healthy hub used to evict it
+   unconditionally.
+2. **Backup + rollback.** The previous plist bytes are held in memory and copied to
+   `<plist>.prev` before the overwrite. On terminal failure the bytes go back, a
+   bootout/settle/bootstrap tries to re-register them, and the thrown error states whether
+   that worked.
+3. **`bootstrap gui/$uid <plist>` replaces `load -w`.** `bootout` was already
+   domain-explicit; `load` acts on the CALLER's bootstrap domain, so from ssh/cron/another
+   bootstrap context the old pair deleted the gui-domain job and registered nothing.
+4. **Bounded settle between bootout and bootstrap** — up to 5 × 200 ms while
+   `launchctl print gui/$uid/<label>` still answers 0, the launchd twin of the Windows
+   `SCHEDULER_SETTLE_DELAYS_MS` idea. `bootout` is asynchronous, so the old back-to-back
+   retry raced the same exiting job twice and added nothing.
+5. **Success is `launchctl print` agreeing, never stderr.** `launchdJobMatchesPlist` is
+   consulted against the command this install actually baked, and `writeServiceInstallState`
+   runs only after it agrees. Stderr regexes are advisory routing signals now.
+6. **One retry, routed by the failure.** Exit 5 / `Bootstrap failed` → `kickstart -k`, then
+   `enable` + a second bootout/bootstrap (see the launchctl findings below). Exit 0 with a
+   disagreeing `print` → one more bootout/bootstrap, because that is the silent no-op. Any
+   other failure (malformed plist, EPERM) throws immediately so the real stderr reaches the
+   operator undelayed — the property the previous code had and kept.
+7. **Error text names the outage and the remedy**: the job was evicted from `gui/<uid>` and
+   is not running, `launchctl bootstrap gui/<uid> <plist>` recovers it, plus
+   `launchctl print` and `launchctl print-disabled` to inspect.
+8. **`stableLauncherEntry()` prefers the recorded launcher** when it is still an absolute
+   executable file, falling back to the PATH walk otherwise (defect 1g). A repair from a
+   context without `ocx` on PATH no longer rewrites a working launcher-form plist into the
+   version-pinned Bun + CLI pair.
+
+### B — `statusLaunchd()` / `diagnoseService()` darwin branch
+
+`launchctl list | grep <label> || true` is gone. New `probeLaunchdLoadState()` asks
+`launchctl print` in BOTH `gui/<uid>` and `user/<uid>` (the way `inspectLaunchd` does), keeps
+the 112/113 distinction, and returns a four-state verdict:
+
+| state | `running` | `viable` | summary |
+|---|---|---|---|
+| `loaded-current` | true | `!stale` | `installed and loaded (launchd; …)` |
+| `loaded-stale` | true | `!stale` | `installed and loaded from an OLDER plist (launchd; …)` |
+| `not-loaded` | false | false | `installed, not loaded (launchd; …)` |
+| `unknown` | false | `!stale` | `installed; launchd state could not be verified — <reason> (launchd; …)` |
+
+`deriveLaunchdServiceDiagnostic()` is a pure function so all four are testable without a live
+launchd. `platformServiceInstallCleanupOps` (the install-cleanup twin) now uses the same probe
+and `bootout` instead of `launchctl list` + legacy `unload`, and keeps failing closed on
+`unknown` — installing new assets over a manager we could not query is the unsafe direction.
+
+### C — `serviceCommand` repair branch
+
+`repairService()` is wrapped, so `reportServiceServing("repaired")` runs even when repair
+throws. The failure is printed and `process.exitCode` is 1 either way. This matters precisely
+because darwin repair can now roll back: the operator needs the "did anything come back?"
+answer, and a throw used to escape to the top level and skip it.
+
+### D — `stopLaunchd` / `uninstallLaunchd`
+
+`bootout gui/<uid>/<label>` first; legacy `unload` survives only for `status === null`, i.e.
+launchctl could not be spawned at all. Exit 3 ("No such process") is the not-loaded case, not
+a failure. `uninstallLaunchd` routes through `stopLaunchd` and also removes `<plist>.prev`.
+
+### Two test-safety guards this work uncovered
+
+Both were pre-existing, and both were hitting this machine.
+
+- **`assertNotRealLaunchAgentsUnderTest`** (`src/lib/test-home-guard.ts`) plus an injectable
+  `plistPath` on `installLaunchd`. `os.homedir()` reads the password database, not `$HOME`, so
+  the suite's HOME sandbox does not move `~/Library/LaunchAgents`. The existing
+  `withLaunchAgentHome()` helper in `service.test.ts` was therefore inert, and every
+  `installLaunchd` case rewrote the developer's live `com.opencodex.proxy.plist` with a
+  definition whose token file, log path and homes pointed into a temp sandbox. launchd holds
+  its own parsed copy, so nothing broke until the job next restarted.
+- **`serviceStatePaths()` drops the legacy default-home entry under an armed test process.**
+  That entry exists so an install made before `OPENCODEX_HOME` was set can still be found, but
+  it is the real `~/.opencodex/service-state.json`, so a sandboxed test still wrote the live
+  record. Observed directly: one run replaced this host's `codexHome`/`opencodexHome` with
+  `/var/folders/...` paths.
+
+Both real files on this machine were restored from the live job's own
+`launchctl print` output and re-verified (`plutil -lint` OK, command identical to the running
+job, 0600, `/healthz` 200). Nothing was left in `~/Library/LaunchAgents` by this work.
+
+## launchctl semantics, measured on this host
+
+macOS 26 / Darwin 27.0.0, arm64, uid 501. Measured with a throwaway
+`com.opencodex.test-probe` label in a temp plist running `/bin/sleep 600`, never against the
+live `com.opencodex.proxy` job (`launchctl print gui/501/com.opencodex.proxy` returned 0
+before and after every probe). The probe was booted out and its files deleted.
+
+```
+launchctl print gui/501/<label>            → 113 absent, 0 loaded
+launchctl print user/501/<label>            → 113 (the shipped agent lives in gui/ only)
+launchctl print gui/99999/<label>           → 112 (no such domain)
+launchctl bootstrap gui/501 <plist>         → 0 first time
+launchctl bootstrap gui/501 <plist> (again) → 5  "Bootstrap failed: 5: Input/output error"
+launchctl load -w <plist> while bootstrapped→ 0  AND "Load failed: 5: Input/output error"   ← the silent no-op
+launchctl kickstart -k gui/501/<label>      → 0 when loaded, 113 when absent
+launchctl bootout gui/501/<label>           → 0 when loaded, 3 "Boot-out failed: 3: No such process"
+```
+
+Second probe, the finding that changed the design:
+
+```
+launchctl disable gui/501/<label>           → 0
+launchctl bootstrap gui/501 <plist>         → 5  "Bootstrap failed: 5: Input/output error"   ← same code, different cause
+launchctl kickstart -k gui/501/<label>      → 113
+launchctl load -w <plist>                   → 0, job loaded, and print-disabled flips to "enabled"
+launchctl enable gui/501/<label>            → 0
+launchctl bootstrap gui/501 <plist>         → 0, job loaded
+```
+
+So **exit 5 is ambiguous**: either something is still bootstrapped under the label, or the
+label sits in the domain's disabled list. The `-w` in the legacy `load -w` was doing the
+second job silently, and dropping it without `enable` would have made a disabled job
+permanently unrepairable. The retry therefore tries `kickstart -k` (live job) and then
+`enable` + bootstrap (disabled list), in that order. `enable` runs ONLY on that retry, so an
+ordinary repair does not quietly undo a deliberate `launchctl disable`.
+
+Residue worth noting: `launchctl enable`/`disable` write a per-uid override database, so
+`launchctl print-disabled gui/501` now carries an inert `"com.opencodex.test-probe" => enabled`
+entry for a label that no longer exists. There is no launchctl verb to remove an override
+record; it references nothing and is harmless.
+
+## Decisions
+
+- **`unknown` keeps `viable` true.** `isServiceViable() === false` is what makes
+  `src/update/index.ts` (after a service refresh exits 0) and `src/update/job.ts:1229` treat a
+  healthy supervisor as dead and start a COMPETING proxy on the service's own port. A probe
+  that could not be run is not evidence against the service, so `unknown` reports honestly in
+  the summary — no "not loaded", no `ocx service repair` — and does not disprove viability.
+  `startable` is likewise untouched, so the tray still hands the start to `ocx service start`,
+  which no-ops on an already-loaded job. `src/cli/status.ts:216`-`222` still appends
+  "registered but NOT serving … re-run 'ocx service repair'" only when `installed && !live`,
+  which stays honest: with `unknown` AND a live proxy it prints the unverified summary under
+  `✅ Proxy: running` and recommends nothing.
+- **`loaded-stale` keeps the viability the grep era gave it** (loaded ⇒ viable). Only the
+  summary is upgraded, so the update fallback behaves exactly as before while the operator
+  finally learns the live job came from an older plist — the one case where `repair` is right.
+- **Verification compares the command THIS install baked**, via a new shared
+  `launchdServiceCommand()` that `buildPlist` also uses, not
+  `expectedLaunchdCommand(installedServiceListenPort())`. A fresh install has no install state
+  yet, and a lost state file makes `expectedLaunchdCommand` fall back to the Bun + CLI pair —
+  which would call a correctly loaded launcher job stale (#3464) and turn every first install
+  into a rollback.
+- **`<plist>.prev`, not `<plist>.prev.plist`.** launchd globs
+  `~/Library/LaunchAgents/*.plist` at login, so a backup ending in `.plist` would be a second
+  registration of the same Label fighting the real one for the port.
+- **`installLaunchd` stays synchronous** (`ServiceOps.install` and
+  `RepairServiceDeps.repairLaunchd` are `() => void`), so the settle loop uses
+  `Bun.sleepSync` behind an injectable `sleepSync` seam rather than making the whole
+  call chain async.
+- **`startLaunchd` still uses `load -w`, deliberately.** Switching it would change
+  `ocx service start` semantics (the `-w` clears the disabled list, `bootstrap` does not), and
+  it already cross-checks with `launchdJobMatchesPlist` before throwing. Out of scope here.
+- **`repairService()` itself still does not consult `diag.running`/`diag.viable`** (issue
+  defect 1c). The no-op now lives inside `installLaunchd`, which is the only function that
+  knows whether the rendered plist differs — a check in `repairService` would have to re-render
+  it to be correct.
+
+## Tests
+
+New `tests/service/launchd-repair.test.ts` (30 cases), registered in
+`scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`. The five
+obsolete `installLaunchd` cases in `tests/service/service.test.ts` (which asserted the `load`
+verb) were removed and replaced by a pointer comment; one new `stableLauncherEntry` case was
+added there, and the two existing launcher-discovery cases now pass `state: null` to stay
+PATH-discovery tests.
+
+Coverage: healthy-and-identical repair is a no-op (zero launchctl calls); identical plist but
+stale live command still reloads; the reload is domain-explicit `bootstrap` with no `load` /
+`unload`; the settle loop waits while `print` answers 0 and is bounded at 5 × 200 ms; exit 0
+with a disagreeing `print` is a failure; exit 5 tries `kickstart -k`; a disabled job takes
+`enable` + bootstrap; an ordinary repair never runs `enable`; a malformed plist is not
+retried; terminal failure restores the previous bytes and names
+`launchctl bootstrap gui/<uid> <plist>` and `print-disabled`; a fresh install invents no
+rollback; the LaunchAgents guard refuses the real directory; the 0/112/113/spawn-failure
+tri-state including "113 in gui is not absence, ask user/ too"; all four diagnostic states
+with `unknown` producing neither "not loaded" nor a repair recommendation; plus source-oracle
+cases for the repair-branch try/catch, the install-cleanup ops, and the state-path filter.
+
+## Verification
+
+Run from the worktree with `node_modules` symlinked.
+
+```
+bun run typecheck                                  → clean (no output)
+bun test tests/service/launchd-repair.test.ts      → 30 pass, 0 fail, 106 expect()
+bun test tests/service/service.test.ts             → 204 pass, 0 fail, 663 expect()
+bun test tests/service                             → 518 pass, 9 fail
+bun test tests/service tests/update \
+  tests/cli/uninstall.test.ts tests/ci-workflows \
+  tests/codex-integration/codex-service-manager-probe.test.ts \
+  tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+                                                   → 1505 pass, 9 fail
+bun run privacy:scan                               → Privacy scan passed
+```
+
+Those 9 failures are pre-existing and identical on `dev`: 8 `winsw` cases plus
+`xAI API-key runtime injects priority while OAuth does not`. They are cross-file
+`OPENCODEX_HOME` pollution inside a single domain-wide `bun test` invocation — each file
+passes alone (`bun test tests/service/winsw.test.ts` → 25 pass,
+`tests/service/service-tier-capability.test.ts` → 35 pass) — and the same 9 fail on a stashed
+working tree at `dev`. The full suite was not run, per the lane instruction; hosted CI is the
+proof.
+
+Host state after the run: `~/Library/LaunchAgents/com.opencodex.proxy.plist` 1985 bytes,
+0600, `plutil -lint` OK, command identical to `launchctl print gui/501/com.opencodex.proxy`;
+`~/.opencodex/service-state.json` 320 bytes with the real homes; `~/.opencodex/service-api-token`
+untouched; `/healthz` on 10100 → 200; no `*.prev` file left behind.

From 6b62524e72d34e5e425e43ffee80c7c250bdb164 Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:51:14 +0900
Subject: [PATCH 4/9] fix(service): repair on the tri-state probe, and evict
 both launchd domains
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review of the first round. `installLaunchd` had the new protocol but was still
asking the OLD two-state `launchdJobMatchesPlist` at both decision points, and
that helper reports `loaded: false` for EVERY non-zero `launchctl print` — EPERM
from a non-Aqua ssh/cron context, an unspawnable launchctl, an undocumented
status. On a healthy serving hub that meant: pre-check says "not loaded" so
evict, verification says the same so evict again and roll back, and the error
ends with "IS NOT RUNNING" about a job that is up. Both checks now go through
`probeLaunchdLoadState`, and `unknown` refuses to act at all — nothing written,
no verb run, and an error naming `launchctl print` in both domains. An `unknown`
AFTER the bootstrap neither retries nor rolls back (a rollback is another
eviction) and never claims the job is down.

Three more from the same review:

- The no-op pre-check compared whole-file bytes while `buildPlist` bakes
  `process.env.PATH`, so a repair from a tray helper, `ocx update`'s child or ssh
  missed it and evicted the healthy hub with its PATH narrowed to the caller's.
  `reusePreviousPlistPathVariable` puts the installed PATH back when PATH is the
  ONLY difference and the live job runs the exec line this install baked. Any
  other difference is a real rewrite, PATH included.
- `kickstart -k` restarts launchd's CACHED definition; it does not re-read the
  plist. With only `EnvironmentVariables` changed the exec line is unchanged, so
  the verification agreed and install state was written while launchd kept the
  old environment. New bytes now skip kickstart and take the eviction, which is
  the only way to publish them. The comment claiming otherwise is gone.
- Every mutating verb addressed `gui/<uid>` alone while the probe also answers
  for `user/<uid>`: `ocx service stop` exited 3 in a domain that never held the
  job and returned as success, the install cleanup laid new assets over a live
  manager, and `installLaunchd` then bootstrapped a SECOND registration of the
  same Label into gui. `launchdEvictionTargets()` is the shared list for all
  three; `bootout` against a label a domain does not hold exits 3 and changes
  nothing, so both are addressed unconditionally.

Also: the error text now says what the probe found (a `loaded-stale` job IS
running, and "nothing is listening" sends that operator to fix the wrong thing);
`<plist>.prev` is removed once the new definition is verified; the
`serviceStatePaths` test filter uses the guard's own canonicalization instead of
a local `resolve()` compare; and `writeServiceInstallState` goes through
`serviceStateWritePaths()`, which throws instead of silently writing nowhere
when the filter leaves no candidate.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 src/lib/test-home-guard.ts |  17 ++
 src/service.ts             | 350 +++++++++++++++++++++++++++++--------
 2 files changed, 291 insertions(+), 76 deletions(-)

diff --git a/src/lib/test-home-guard.ts b/src/lib/test-home-guard.ts
index b19c48c88c..0c1a0ad715 100644
--- a/src/lib/test-home-guard.ts
+++ b/src/lib/test-home-guard.ts
@@ -86,6 +86,23 @@ export function isTestHomeGuardArmed(): boolean {
   return process.env[GUARD_ENV] === "1";
 }
 
+/**
+ * Whether `dir` IS the protected production home, decided with the SAME canonicalization as
+ * {@link assertNotRealHomeUnderTest}.
+ *
+ * For the caller that must FILTER the real home out of a candidate list instead of refusing
+ * one write: `serviceStatePaths()` in `src/service.ts` keeps a legacy
+ * `~/.opencodex/service-state.json` entry so an install made before OPENCODEX_HOME existed
+ * can still be found, and under an armed test process that entry is the developer's live
+ * record. Exported so that filter cannot drift onto a weaker comparison — `resolve()` alone
+ * calls `/var/folders/...` and `/private/var/folders/...` different paths, which is exactly
+ * how a macOS sandbox path slips past a string compare.
+ */
+export function isProtectedHomeUnderTest(dir: string): boolean {
+  if (!isTestHomeGuardArmed()) return false;
+  return canonicalize(dir) === PROTECTED_HOME;
+}
+
 /**
  * Throw when an armed test process is about to write the real OpenCodex home.
  *
diff --git a/src/service.ts b/src/service.ts
index 59215bf932..13b26beb7d 100644
--- a/src/service.ts
+++ b/src/service.ts
@@ -63,7 +63,7 @@ import { killWindowsSchedulerWrappers } from "./lib/windows-service-wrappers";
 import { withWindowsServiceMutationLock } from "./lib/windows-service-mutation-lock";
 import { maybeShowStarPrompt } from "./cli/star-prompt";
 import { systemdProperty } from "./service-manager-probe";
-import { assertNotRealLaunchAgentsUnderTest, isTestHomeGuardArmed, protectedHomeForTests } from "./lib/test-home-guard";
+import { assertNotRealLaunchAgentsUnderTest, isProtectedHomeUnderTest, isTestHomeGuardArmed } from "./lib/test-home-guard";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -106,6 +106,13 @@ function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: stri
  * job out to load it (#4236, defect 1g). A launcher that is still an executable file is
  * the thing the installed service already runs, so repair must keep naming it; only a
  * recorded launcher that has disappeared falls through to discovery.
+ *
+ * That preference is NOT macOS-only: `installSystemd` resolves this same function, so a
+ * Linux `ocx service repair` from a PATH-less context keeps the `ExecStart` the unit
+ * already has instead of rewriting it to the version-pinned pair — the #2898 shape this
+ * function exists to avoid. The failure mode it prevents is milder there (systemd
+ * `daemon-reload` + `restart` does not evict-then-maybe-nothing the way launchd did), but
+ * the rewrite was the same, so the behavior is deliberately shared rather than branched.
  */
 export function stableLauncherEntry(deps: {
   env?: NodeJS.ProcessEnv;
@@ -184,9 +191,34 @@ function serviceStatePaths(): string[] {
    * the launchd repair coverage: one case replaced the real record's codexHome and
    * opencodexHome with temp-directory paths. Drop it rather than deny the write, so the
    * sandbox path keeps working and the real one is simply not in the list.
+   *
+   * The predicate is the guard's own, not a local `resolve()` compare: the guard
+   * canonicalizes through `realpath`, and on macOS a sandbox under `/var/folders/...`
+   * resolves to `/private/var/folders/...`, so two spellings of one directory must not
+   * decide this.
    */
-  const real = normalizePathForCompare(protectedHomeForTests());
-  return paths.filter(path => normalizePathForCompare(dirname(path)) !== real);
+  return paths.filter(path => !isProtectedHomeUnderTest(dirname(path)));
+}
+
+/**
+ * The state paths a WRITE may use. Same list, but an empty one is an error instead of a
+ * silent no-op.
+ *
+ * With OPENCODEX_HOME unset under an armed test process, `currentOpenCodexHome()` falls
+ * back to the real `~/.opencodex` (`os.homedir()` ignores `$HOME`), the filter above then
+ * removes every candidate, and `writeServiceInstallState` wrote NOTHING while reporting
+ * success — a test asserting on install state would read the previous run's record, or
+ * none. Fail the way `assertNotRealHomeUnderTest` does, naming the fix.
+ */
+function serviceStateWritePaths(): string[] {
+  const paths = serviceStatePaths();
+  if (paths.length > 0) return paths;
+  throw new Error(
+    "refusing to write service install state with no writable state path: every candidate "
+    + "resolved to the real OpenCodex home and was filtered out. Point OPENCODEX_HOME at a "
+    + "temp directory for this test (the preload does it for every invocation; something "
+    + "deleted the variable without restoring it).",
+  );
 }
 
 function currentCodexHome(deps: CodexHomeDeps = {}): string {
@@ -277,7 +309,7 @@ function writeServiceInstallState(backend: ServiceBackend = "scheduler", launche
     backend,
     ...(backend === "native" ? { winswVersion: WINSW_VERSION, winswSha256: WINSW_SHA256 } : {}),
   };
-  for (const path of serviceStatePaths()) {
+  for (const path of serviceStateWritePaths()) {
     const dir = dirname(path);
     recordOwnedConfigPath(getConfigDir(), path);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -585,6 +617,46 @@ ${envLines}
 `;
 }
 
+/**
+ * The single `EnvironmentVariables` line {@link buildPlist} fills from the env of whatever
+ * process happens to be repairing.
+ */
+const PLIST_PATH_ENTRY = /^(\s*<key>PATH<\/key><string>)([^\n]*)(<\/string>)$/m;
+
+/**
+ * The rendered plist with the PREVIOUS definition's `PATH` put back — or null when `PATH`
+ * is not the only difference.
+ *
+ * `buildPlist` bakes `process.env.PATH`, and `ocx service repair` is run by whatever has a
+ * shell: a tray helper, `ocx update`'s child, an ssh session, a cron job. Each of those
+ * carries a DIFFERENT PATH from the login shell that installed the service, so comparing
+ * whole-file bytes made the "nothing to repair" pre-check miss almost every time it
+ * mattered: a healthy hub was evicted, and its PATH rewritten to the narrower one, purely
+ * because of who asked (#4236, review finding 2).
+ *
+ * Reuse rather than ignore. A plist that differs only in PATH is not "equal" — dropping the
+ * difference silently would let a repair report a no-op while launchd keeps a PATH the
+ * operator has changed on purpose. Putting the previous value back makes the two files
+ * genuinely identical, so the caller's ordinary byte comparison decides, and the PATH the
+ * service already runs with is the one that survives.
+ *
+ * The caller applies this only when the live job is loaded from exactly the exec line this
+ * install baked: that is the evidence that the running definition is the one on disk, which
+ * is what makes keeping its PATH correct rather than a guess. Whenever anything ELSE about
+ * the definition changed the plist is rewritten in full, PATH included, so a real
+ * re-install still updates it.
+ */
+export function reusePreviousPlistPathVariable(previous: string, rendered: string): string | null {
+  const prev = PLIST_PATH_ENTRY.exec(previous);
+  const next = PLIST_PATH_ENTRY.exec(rendered);
+  if (!prev || !next || prev[2] === next[2]) return null;
+  // A function replacer, not a `$1` template: a PATH entry containing `$&` or `$1` would
+  // otherwise be re-expanded into the file.
+  const adopted = rendered.replace(PLIST_PATH_ENTRY, (_match, open: string, _value: string, close: string) =>
+    `${open}${prev[2] ?? ""}${close}`);
+  return adopted === previous ? adopted : null;
+}
+
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -1038,6 +1110,39 @@ const LAUNCHCTL_BOOTSTRAP_BUSY = 5;
 /** `launchctl bootout`: nothing was loaded under that label, i.e. already stopped. */
 const LAUNCHCTL_BOOTOUT_NO_SUCH_PROCESS = 3;
 
+/**
+ * Every domain target an eviction has to cover.
+ *
+ * {@link probeLaunchdLoadState} asks `gui/<uid>` AND `user/<uid>` because the two domains
+ * are independent and hold separate service sets, while every MUTATING verb in this file
+ * addressed `gui/<uid>` alone. So a `user/`-domain registration of our Label used to:
+ * survive `ocx service stop` (`bootout gui/<uid>/<label>` exits 3, "No such process", which
+ * the stop path correctly reads as "nothing was loaded" — in the wrong domain); survive the
+ * install cleanup whose whole job is evicting a live manager before new assets land, which
+ * then installed over a serving job; and stay registered while `installLaunchd` bootstrapped
+ * a SECOND registration of the same Label into `gui/`, leaving two KeepAlive jobs fighting
+ * for one port.
+ *
+ * Both domains unconditionally rather than the one a probe reports: `bootout` against a
+ * label a domain does not hold exits 3 and changes nothing, so enumerating first would buy
+ * an extra round trip to learn what the verb itself already reports.
+ */
+export function launchdEvictionTargets(uid: number = process.getuid?.() ?? 0): string[] {
+  return [`gui/${uid}/${LABEL}`, `user/${uid}/${LABEL}`];
+}
+
+/**
+ * Whether a `bootout` exit status means "nothing of ours was loaded there" rather than a
+ * failure. 3 is "No such process"; 113/112 answer for the service and the domain, and a
+ * domain that does not exist cannot be holding a job of ours (a headless Mac has no `gui/`).
+ */
+function launchctlBootoutBenign(status: number | null): boolean {
+  return status === 0
+    || status === LAUNCHCTL_BOOTOUT_NO_SUCH_PROCESS
+    || status === LAUNCHCTL_NO_SUCH_SERVICE
+    || status === LAUNCHCTL_NO_SUCH_DOMAIN;
+}
+
 /**
  * Four states, because three of them used to collapse into one bit.
  *
@@ -2497,31 +2602,39 @@ function readTextOrNull(path: string): string | null {
  * its read-only list, so a test reaching the real runner would fail closed on the guard
  * instead of exercising the sequence.
  *
- * `matches` is a {@link launchdJobMatchesPlist} result, used TWICE and for opposite
+ * `probe` is the TRI-STATE {@link probeLaunchdLoadState}, used twice and for opposite
  * reasons: once before touching launchd, to prove a repair has nothing to do, and once
- * after, because stderr cannot prove a load took.
+ * after, because stderr cannot prove a load took. It is deliberately not the two-state
+ * `launchdJobMatchesPlist`, which reports `loaded: false` for every non-zero
+ * `launchctl print` — EPERM from a non-Aqua ssh/cron context, an unspawnable launchctl, an
+ * undocumented status. With that one, a healthy serving hub read as "not loaded" in the
+ * pre-check (so repair evicted it) and again in the verification (so the rollback evicted
+ * it a second time and the error claimed "IS NOT RUNNING" about a job that was up). An
+ * `unknown` probe is not evidence, so it refuses to evict instead.
  *
  * Protocol (#4236, defect 1). `ocx service repair` on darwin IS this function, and it
  * evicts the running job — a public proxy, a management ingress and a loopback listener on
  * a hub. So:
  *
- *  1. Render the plist first and compare it to the live job. Identical plist + unchanged
- *     token file + a job loaded from exactly that command means there is nothing to
- *     repair, and a repair of a healthy service must never cause an outage.
+ *  1. Ask launchd what it is running BEFORE writing anything. `unknown` throws without
+ *     touching a file or a job; `loaded-current` plus an identical plist and an unchanged
+ *     token file means there is nothing to repair, and a repair of a healthy service must
+ *     never cause an outage.
  *  2. Keep the previous plist bytes (in memory and at `<plist>.prev`) before overwriting.
- *  3. `bootout`, settle, then `bootstrap gui/$uid <plist>` — the verb that PAIRS with the
- *     bootout target. Legacy `load -w` is domain-implicit: it acts on the caller's own
- *     bootstrap domain, so from ssh/cron it deleted the gui-domain job and registered
- *     nothing (defect 1a).
+ *  3. `bootout` BOTH user domains, settle, then `bootstrap gui/$uid <plist>` — the verb
+ *     that PAIRS with the bootout target. Legacy `load -w` is domain-implicit: it acts on
+ *     the caller's own bootstrap domain, so from ssh/cron it deleted the gui-domain job and
+ *     registered nothing (defect 1a).
  *  4. Success is `launchctl print` agreeing, never a stderr regex: measured on macOS 27.0,
  *     `load -w` over a bootstrapped job exits 0 with "Load failed: 5" and does nothing,
  *     and `bootstrap` exits 5 with "Bootstrap failed: 5" for the same condition.
  *  5. On terminal failure restore the previous plist, try to bootstrap it back, and throw
- *     an error that says the job is DOWN and names the manual remedy.
+ *     an error that says what the probe actually found — down, or up on a different
+ *     command — and names the manual remedy.
  */
 export function installLaunchd(deps: {
   launchctl?: typeof runLaunchctl;
-  matches?: typeof launchdJobMatchesPlist;
+  probe?: typeof probeLaunchdLoadState;
   sleepSync?: (ms: number) => void;
   /**
    * Where to write the plist. Only tests pass it: `os.homedir()` reads the password
@@ -2533,48 +2646,77 @@ export function installLaunchd(deps: {
   plistPath?: string;
 } = {}): void {
   const run = deps.launchctl ?? runLaunchctl;
-  const matches = deps.matches ?? launchdJobMatchesPlist;
+  const probeLoadState = deps.probe ?? probeLaunchdLoadState;
   const sleepSync = deps.sleepSync ?? ((ms: number) => { Bun.sleepSync(ms); });
   const p = deps.plistPath ?? plistPath();
   const dir = dirname(p);
   assertNotRealLaunchAgentsUnderTest(dir);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
-  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   // Capture this BEFORE writing: the write below makes the plist exist unconditionally,
   // so a post-write existsSync would call every fresh install an "installed" service.
   const wasInstalled = existsSync(p);
   // The previous definition, kept for rollback. An eviction whose bootstrap fails used to
   // end with the new plist on disk, nothing in launchd, and nothing listening.
   const previousPlist = wasInstalled ? readTextOrNull(p) : null;
-  const tokenFile = serviceApiTokenFilePath();
-  const previousToken = readTextOrNull(tokenFile);
-  writeServiceApiTokenFile();
-  // A rotated data token only reaches the job through a restart, so it is part of "is this
-  // repair a no-op?" — the plist `cat`s this file at launch.
-  const tokenUnchanged = readTextOrNull(tokenFile) === previousToken;
   // Resolve the launcher ONCE and hand the same value to the plist and to install state,
   // so the staleness diagnostic judges exactly what launchd runs.
   const launcher = stableLauncherEntry();
-  const rendered = buildPlist(resolvedProxyEnv(), { launcher });
   // The command THIS install bakes, not the one install state remembers: on a fresh
   // install there is no state yet, and after a lost state file `expectedLaunchdCommand`
   // falls back to the Bun + CLI pair and would call a correct launcher job stale (#3464).
   const expectedCommand = launchdServiceCommand(launcher);
-  const bootoutTarget = `${launchdGuiDomain()}/${LABEL}`;
-
-  if (previousPlist === rendered && tokenUnchanged) {
-    const live = matches(expectedCommand);
-    if (live.loaded && live.matchesPlist) {
-      // The plist is not rewritten and launchd is not touched; only the owner-only mode
-      // is re-asserted, for a definition an older version may have left at 0644.
-      try { chmodSync(p, 0o600); } catch { /* best-effort */ }
-      // Install state is refreshed because it is what `expectedLaunchdCommand` reads, and
-      // a repair that leaves it stale re-creates the false "OLDER plist" report.
-      writeServiceInstallState("scheduler", launcher);
-      console.log("ℹ️  service is already loaded from the current plist; nothing to do.");
-      return;
-    }
+  const uid = process.getuid?.() ?? 0;
+  const guiDomain = launchdGuiDomain();
+  const guiTarget = `${guiDomain}/${LABEL}`;
+  const evictionTargets = launchdEvictionTargets(uid);
+  const probeLive = (): LaunchdLoadProbe => probeLoadState({ expectedCommand: () => expectedCommand });
+
+  // Nothing has been written yet, deliberately: a probe that cannot answer must leave the
+  // host exactly as it found it.
+  let verdict = probeLive();
+  if (verdict.state === "unknown") {
+    throw new Error(
+      `refusing to ${wasInstalled ? "repair" : "install"} ${LABEL}: launchd state could not be verified `
+      + `— ${verdict.detail ?? "launchctl could not be asked"}.\n`
+      + "The job may be RUNNING, and this command evicts it, so nothing was changed.\n"
+      + `Check it with:\n  launchctl print ${guiTarget}\n  launchctl print user/${uid}/${LABEL}\n`
+      + "A non-Aqua context (ssh, cron, a launchd daemon) cannot always reach gui/<uid>; re-run "
+      + `'${wasInstalled ? "ocx service repair" : "ocx service install"}' from a GUI login session.`,
+    );
+  }
+
+  let rendered = buildPlist(resolvedProxyEnv(), { launcher });
+  if (previousPlist !== null && previousPlist !== rendered && verdict.state === "loaded-current") {
+    // The live job runs exactly the exec line this install baked, so the definition on disk
+    // IS the one launchd is running: keep the PATH it already carries instead of replacing
+    // it with the repairing process's. See `reusePreviousPlistPathVariable`.
+    const adopted = reusePreviousPlistPathVariable(previousPlist, rendered);
+    if (adopted !== null) rendered = adopted;
+  }
+  // Whether launchd has to be handed NEW BYTES, which is what decides below whether a
+  // `kickstart` can be trusted. `previousPlist === null` (a fresh install) counts: whatever
+  // the label may hold did not come from a definition we can see.
+  const renderedDiffers = previousPlist !== rendered;
+
+  // ── Writes start here. ──
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  const tokenFile = serviceApiTokenFilePath();
+  const previousToken = readTextOrNull(tokenFile);
+  writeServiceApiTokenFile();
+  // A rotated data token only reaches the job through a restart, so it is part of "is this
+  // repair a no-op?" — the plist `cat`s this file at launch.
+  const tokenUnchanged = readTextOrNull(tokenFile) === previousToken;
+
+  if (!renderedDiffers && tokenUnchanged && verdict.state === "loaded-current") {
+    // The plist is not rewritten and launchd is not touched; only the owner-only mode
+    // is re-asserted, for a definition an older version may have left at 0644.
+    try { chmodSync(p, 0o600); } catch { /* best-effort */ }
+    // Install state is refreshed because it is what `expectedLaunchdCommand` reads, and
+    // a repair that leaves it stale re-creates the false "OLDER plist" report.
+    writeServiceInstallState("scheduler", launcher);
+    console.log("ℹ️  service is already loaded from the current plist; nothing to do.");
+    return;
   }
 
   if (previousPlist !== null) {
@@ -2595,20 +2737,24 @@ export function installLaunchd(deps: {
   // Absence is fine: booting out a job that is not there exits 3 ("No such process"), and
   // a real failure is reported by the verification below with a better message than a raw
   // eviction error would carry.
-  const evictThenBootstrap = (): { ok: boolean; stdout: string; stderr: string; status: number | null } => {
-    run(["bootout", bootoutTarget]);
-    // `bootout` is asynchronous. Without this the retry raced the same exiting job twice
-    // and added nothing.
-    settleLaunchdEviction(run, bootoutTarget, sleepSync);
-    return run(["bootstrap", launchdGuiDomain(), p]);
+  const evictEveryDomain = (): void => {
+    for (const target of evictionTargets) {
+      // Settle only where something was actually evicted. `bootout` is asynchronous, so a
+      // job it DID remove needs waiting for; one it never held (exit 3) has nothing to
+      // wait on, and probing it would only add a round trip per install.
+      if (run(["bootout", target]).status === 0) settleLaunchdEviction(run, target, sleepSync);
+    }
   };
-  const loadTook = (): boolean => {
-    const live = matches(expectedCommand);
-    return live.loaded && live.matchesPlist;
+  const evictThenBootstrap = (): { ok: boolean; stdout: string; stderr: string; status: number | null } => {
+    evictEveryDomain();
+    return run(["bootstrap", guiDomain, p]);
   };
 
   let loaded = evictThenBootstrap();
-  if (!loadTook()) {
+  verdict = probeLive();
+  // `unknown` is excluded on purpose: a retry means another eviction, and a probe that
+  // could not answer is not a reason to take the job down again.
+  if (verdict.state === "not-loaded" || verdict.state === "loaded-stale") {
     // ONE retry. A bounded retry recovers the race; a loop would turn a wedged domain
     // into a hang instead of the diagnosable throw below.
     if (loaded.status === LAUNCHCTL_BOOTSTRAP_BUSY || launchctlLoadFailed(loaded.stderr)) {
@@ -2616,19 +2762,26 @@ export function installLaunchd(deps: {
       // with a throwaway label, and they need opposite remedies:
       //
       //  - something is still bootstrapped under our label (the job re-registered, or it
-      //    had not finished exiting). `kickstart -k` restarts whatever the domain holds
-      //    from the plist on disk — which is now ours — without opening a second eviction
-      //    window. On an absent job it exits 113 and changes nothing.
+      //    had not finished exiting). `kickstart -k` restarts what the domain holds without
+      //    opening a second eviction window — but it restarts launchd's CACHED definition
+      //    and does NOT re-read the plist, so it can only settle this when the rendered
+      //    bytes are the ones already on disk. With new bytes it would restart the OLD
+      //    definition, and since the exec line is unchanged whenever only
+      //    `EnvironmentVariables` moved, the verification below would agree and install
+      //    state would be written while launchd kept the stale environment. So: new bytes
+      //    skip kickstart and go to the eviction, which is the only way to publish them.
       //  - the label is in the domain's DISABLED list, so `bootstrap` refuses it while
       //    `launchctl print` reports 113. This is the one thing the legacy `load -w` did
       //    that plain `bootstrap` does not: `-w` cleared that flag. `enable` is the modern
       //    spelling of it, and it is idempotent on a job that was never disabled — but it
       //    runs only here, so an ordinary repair does not quietly undo a deliberate
       //    `launchctl disable`.
-      const kicked = run(["kickstart", "-k", bootoutTarget]);
-      if (!kicked.ok || !loadTook()) {
-        run(["enable", bootoutTarget]);
+      const kicked = renderedDiffers ? null : run(["kickstart", "-k", guiTarget]);
+      if (kicked?.ok) verdict = probeLive();
+      if (verdict.state !== "loaded-current") {
+        run(["enable", guiTarget]);
         loaded = evictThenBootstrap();
+        verdict = probeLive();
       }
     } else if (loaded.ok) {
       // Exit 0 while `print` disagrees: the load silently no-op'd. That IS worth evicting
@@ -2636,40 +2789,72 @@ export function installLaunchd(deps: {
       // fixed by evicting a job, so it falls straight through to the throw and the
       // operator sees the real stderr instead of a delayed copy of it.
       loaded = evictThenBootstrap();
+      verdict = probeLive();
+    }
+  }
+
+  if (verdict.state === "unknown") {
+    // The probe stopped answering between the pre-check and here. Do NOT evict again, do
+    // NOT roll back (a rollback is another eviction) and do NOT claim the job is down: the
+    // bytes we asked launchd to load are the ones on disk either way.
+    if (!loaded.ok) {
+      throw new Error(
+        `launchctl could not bootstrap ${p}: ${loaded.stderr || "bootstrap reported failure"}\n`
+        + `and the state of ${LABEL} could not be verified afterwards — ${verdict.detail ?? "launchctl could not be asked"}.\n`
+        + "The job was NOT evicted again and the plist was left in place, so this says nothing about "
+        + "whether it is running.\n"
+        + `Check it with:\n  launchctl print ${guiTarget}\n  launchctl print user/${uid}/${LABEL}\n`
+        + `and load it if it is absent:\n  launchctl bootstrap ${guiDomain} ${p}`,
+      );
     }
+    console.warn(
+      `⚠️  launchctl accepted the bootstrap but the job state could not be verified — ${
+        verdict.detail ?? "launchctl could not be asked"}. Check: launchctl print ${guiTarget}`,
+    );
+    writeServiceInstallState("scheduler", launcher);
+    return;
   }
 
-  if (!loadTook()) {
+  if (verdict.state !== "loaded-current") {
     // Do NOT write install state for a load that did not take: state describing an unused
     // plist is what made this failure invisible.
     let rolledBack: "restored" | "on-disk-only" | "none" = "none";
     if (previousPlist !== null) {
       try {
         writeServiceDefinitionFile(p, previousPlist, "utf8");
-        run(["bootout", bootoutTarget]);
-        settleLaunchdEviction(run, bootoutTarget, sleepSync);
-        run(["bootstrap", launchdGuiDomain(), p]);
-        rolledBack = run(["print", bootoutTarget]).ok ? "restored" : "on-disk-only";
+        evictEveryDomain();
+        run(["bootstrap", guiDomain, p]);
+        rolledBack = run(["print", guiTarget]).ok ? "restored" : "on-disk-only";
       } catch {
         rolledBack = "on-disk-only";
       }
     }
+    // What the probe actually found, rather than one sentence for both outcomes: a
+    // `loaded-stale` job IS running, and telling its operator "nothing is listening" sends
+    // them to fix the wrong thing.
+    const state = verdict.state === "loaded-stale"
+      ? `is still loaded in ${verdict.domain ?? guiDomain} from a DIFFERENT command than the plist just written`
+      : rolledBack === "restored"
+        ? `was evicted from ${guiDomain}; the PREVIOUS plist was restored and re-bootstrapped`
+        : `was evicted from ${guiDomain} and IS NOT RUNNING — nothing is listening`;
     throw new Error(
       `launchctl could not bootstrap ${p}: ${loaded.stderr || "bootstrap reported failure"}\n`
-      + `The ${LABEL} job was evicted from ${launchdGuiDomain()} and ${
-        rolledBack === "restored" ? "the PREVIOUS plist was restored and re-bootstrapped" : "IS NOT RUNNING — nothing is listening"
-      }.\n`
+      + `The ${LABEL} job ${state}.\n`
       + (rolledBack === "on-disk-only"
         ? "The previous plist was restored on disk but could not be bootstrapped either.\n"
         : "")
-      + `Recover manually with:\n  launchctl bootstrap ${launchdGuiDomain()} ${p}\n`
-      + `Inspect it with:\n  launchctl print ${bootoutTarget}\n  launchctl print-disabled ${launchdGuiDomain()}\n`
+      + `Recover manually with:\n  launchctl bootstrap ${guiDomain} ${p}\n`
+      + `Inspect it with:\n  launchctl print ${guiTarget}\n  launchctl print-disabled ${guiDomain}\n`
       // macOS `service repair` delegates straight to installLaunchd, so this fires for
       // an already-installed service too; repair reloads it without re-registering.
       + `then re-run '${wasInstalled ? "ocx service repair" : "ocx service install"}'.`,
     );
   }
   writeServiceInstallState("scheduler", launcher);
+  // The rollback copy has done its job: the new definition is verified loaded. Leaving it
+  // behind makes the NEXT repair's backup ambiguous (which failure did it come from?) and
+  // `uninstall` the only thing that ever cleaned it up.
+  if (existsSync(`${p}.prev`)) { try { unlinkSync(`${p}.prev`); } catch { /* best-effort */ } }
 }
 /**
  * Deps are named for the layer they replace, not for the process API: `launchctl`
@@ -2707,26 +2892,34 @@ export function startLaunchd(deps: {
   );
 }
 /**
- * Evict the job with the modern, domain-explicit verb; fall back to legacy `unload` only
- * when `bootout` could not be run at all.
+ * Evict the job with the modern, domain-explicit verb, in EVERY domain that can hold it;
+ * fall back to legacy `unload` only when `bootout` could not be run at all.
  *
  * `unload` cannot evict a job bootstrapped into the GUI domain (the same reason
  * `installLaunchd` stopped using it), so a stop built on it reported success while the
  * proxy kept serving. Exit 3 ("Boot-out failed: 3: No such process") is the not-loaded
  * case and is not a failure here.
+ *
+ * `gui/<uid>` alone was the remaining half of that bug: `probeLaunchdLoadState` reports a
+ * `user/<uid>` job too, and against one of those this function exited 3 in the wrong domain
+ * and returned as if it had stopped something. See {@link launchdEvictionTargets}.
  */
 function stopLaunchd(deps: { launchctl?: typeof runLaunchctl } = {}): void {
   const run = deps.launchctl ?? runLaunchctl;
+  let spawnable = true;
   try {
-    // Any real exit status is final — including 3, which only means the job was not
-    // loaded. `status: null` is "launchctl could not be spawned at all", and only then is
-    // the legacy verb worth one attempt.
-    if (run(["bootout", `${launchdGuiDomain()}/${LABEL}`]).status !== null) return;
+    for (const target of launchdEvictionTargets()) {
+      // Any real exit status is final — including 3, which only means the job was not
+      // loaded THERE. `status: null` is "launchctl could not be spawned at all", and only
+      // then is the legacy verb worth one attempt.
+      if (run(["bootout", target]).status === null) spawnable = false;
+    }
   } catch {
     // The armed-test guard refuses mutating verbs; retrying through `sh` would only hit it
     // again.
     return;
   }
+  if (spawnable) return;
   try { sh(`launchctl unload "${plistPath()}"`); } catch { /* not loaded */ }
 }
 
@@ -3941,11 +4134,16 @@ function platformServiceInstallCleanupOps(backend: ServiceBackend): ServiceInsta
         return probe.state === "not-loaded" ? null : `${LABEL} loaded in ${probe.domain ?? launchdGuiDomain()}`;
       },
       // `unload` is legacy and CANNOT evict a gui-domain job, which is what this cleanup
-      // exists to do before new assets are installed.
+      // exists to do before new assets are installed. Both user domains, because the probe
+      // above reports `user/<uid>` too: a gui-only bootout exits 3 against one of those,
+      // which this function would have read as "already stopped" and installed over a live
+      // job (see `launchdEvictionTargets`).
       stop: () => {
-        const booted = runLaunchctl(["bootout", `${launchdGuiDomain()}/${LABEL}`]);
-        if (booted.ok || booted.status === LAUNCHCTL_BOOTOUT_NO_SUCH_PROCESS) return;
-        throw new Error(`launchctl bootout failed: ${booted.stderr || `exit ${String(booted.status)}`}`);
+        for (const target of launchdEvictionTargets()) {
+          const booted = runLaunchctl(["bootout", target]);
+          if (launchctlBootoutBenign(booted.status)) continue;
+          throw new Error(`launchctl bootout ${target} failed: ${booted.stderr || `exit ${String(booted.status)}`}`);
+        }
       },
     };
   }

From cef096db46fd5186329127957bf721063587ad7a Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:51:25 +0900
Subject: [PATCH 5/9] test(service): cover the probe-driven repair, PATH reuse
 and both domains
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every `installLaunchd` case now injects the tri-state `probe` instead of
`matches`, which is what makes the four answers distinguishable at all. New
cases: a plist differing ONLY in the baked PATH is a no-op and keeps the
installed PATH on disk; an env-only change refuses to trust `kickstart -k` and
takes the eviction; an `unknown` pre-check runs no verb, writes no file and names
both `print` commands; an `unknown` after an accepted bootstrap neither retries
nor rolls back; an `unknown` after a refused one throws without "IS NOT RUNNING";
a `loaded-stale` outcome is reported as loaded rather than down; a `bootout` that
evicted nothing is not settled; `<plist>.prev` is gone after a verified load.
Plus unit cases for `reusePreviousPlistPathVariable` (including a PATH carrying
`$&`, which a `$1` replacement template would have re-expanded) and
`launchdEvictionTargets`.

The source-oracle block gains: `installLaunchd` never reaching for
`launchdJobMatchesPlist` while `startLaunchd` deliberately still does, the PATH
pre-check, the eviction-target list in stop and in the install-cleanup ops, the
fail-loud install-state write path, and the launcher resolver shared with
`installSystemd` — whose behavioural half is a new `service.test.ts` case, since
"the recorded launcher wins" changed Linux too.

`beforeEach` set `OPENCODEX_HOME` with no restore, leaking this file's temp home
into the next file in the same Bun worker; it is captured and restored now.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/service/launchd-repair.test.ts | 431 ++++++++++++++++++++++++---
 tests/service/service.test.ts        |  32 ++
 2 files changed, 415 insertions(+), 48 deletions(-)

diff --git a/tests/service/launchd-repair.test.ts b/tests/service/launchd-repair.test.ts
index 8916775935..c1b27bf69e 100644
--- a/tests/service/launchd-repair.test.ts
+++ b/tests/service/launchd-repair.test.ts
@@ -22,7 +22,7 @@
  * `~/Library/LaunchAgents`, and a case without that seam rewrites the developer's own live
  * `com.opencodex.proxy.plist`.
  */
-import { beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -30,11 +30,14 @@ import {
   buildPlist,
   deriveLaunchdServiceDiagnostic,
   installLaunchd,
+  launchdEvictionTargets,
   probeLaunchdLoadState,
   resolvedProxyEnv,
+  reusePreviousPlistPathVariable,
   runLaunchctl,
   stableLauncherEntry,
 } from "../../src/service";
+import type { LaunchdLoadProbe, LaunchdLoadState } from "../../src/service";
 import { protectedLaunchAgentsDirForTests } from "../../src/lib/test-home-guard";
 import { repoPath } from "../helpers/repo-root";
 
@@ -44,12 +47,21 @@ import { repoPath } from "../helpers/repo-root";
  * one, because `os.homedir()` ignores `$HOME`. A sibling file in the same Bun worker that
  * clears or restores the variable would otherwise make these cases fail on the real-home
  * guard instead of on anything they assert.
+ *
+ * Captured and RESTORED, because the pollution runs both ways: the test preload hands every
+ * worker a sandbox home, and a file that leaves its own temp directory in the variable makes
+ * the next file in the same worker read a home this one deleted.
  */
+const previousOpenCodexHome = process.env.OPENCODEX_HOME;
 beforeEach(() => {
   const home = mkdtempSync(join(tmpdir(), "ocx-launchd-home-"));
   mkdirSync(join(home, ".opencodex"), { recursive: true });
   process.env.OPENCODEX_HOME = join(home, ".opencodex");
 });
+afterEach(() => {
+  if (previousOpenCodexHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousOpenCodexHome;
+});
 
 type LaunchctlResult = { ok: boolean; stdout: string; stderr: string; status: number | null };
 
@@ -91,6 +103,31 @@ function recordingLaunchctl(script: {
 
 const verbs = (argv: string[][]): string[] => argv.map(args => args[0] ?? "");
 
+/**
+ * A {@link probeLaunchdLoadState} stand-in answering from a queue, the LAST entry repeating.
+ *
+ * `installLaunchd` asks the tri-state probe rather than the two-state
+ * `launchdJobMatchesPlist` precisely so `unknown` can be distinguished from absence, so the
+ * fixture has to be able to say all four things.
+ */
+function scriptedProbe(...states: Array<LaunchdLoadState | LaunchdLoadProbe>) {
+  const seen: LaunchdLoadState[] = [];
+  let call = 0;
+  const probe = ((): LaunchdLoadProbe => {
+    const next = states[Math.min(call++, states.length - 1)] ?? "not-loaded";
+    const answer: LaunchdLoadProbe = typeof next === "string"
+      ? { state: next, ...(next.startsWith("loaded") ? { domain: "gui/501" } : {}) }
+      : next;
+    seen.push(answer.state);
+    return answer;
+  }) as typeof probeLaunchdLoadState;
+  return { seen, probe };
+}
+
+/** The tri-state answer a healthy hub gives, for the cases that only need one. */
+const loadedCurrent = (): { seen: LaunchdLoadState[]; probe: typeof probeLaunchdLoadState } =>
+  scriptedProbe("loaded-current");
+
 /** A fixture LaunchAgents directory plus the plist path inside it. */
 function fixturePlist(): string {
   return join(mkdtempSync(join(tmpdir(), "ocx-launchd-repair-")), "com.opencodex.proxy.plist");
@@ -107,12 +144,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     writeFileSync(plistPath, renderedPlist(), "utf8");
     const { argv, launchctl } = recordingLaunchctl({});
 
-    installLaunchd({
-      launchctl,
-      plistPath,
-      matches: () => ({ loaded: true, matchesPlist: true }),
-      sleepSync: () => {},
-    });
+    installLaunchd({ launchctl, plistPath, probe: loadedCurrent().probe, sleepSync: () => {} });
 
     // THE regression: no bootout, no bootstrap, no kickstart. Repairing a serving hub
     // used to evict it unconditionally.
@@ -121,32 +153,74 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(existsSync(`${plistPath}.prev`)).toBe(false);
   });
 
+  /**
+   * Review finding 2. `buildPlist` bakes `process.env.PATH`, so the byte comparison above
+   * only holds for a repair run from the same shell that installed the service. From a tray
+   * helper, `ocx update`'s child or an ssh session the PATH line differs, every other byte
+   * is identical, and the healthy hub was evicted anyway — with its PATH rewritten to the
+   * narrower one.
+   */
+  test("a plist that differs ONLY in the baked PATH is still a no-op, and keeps the installed PATH", () => {
+    const plistPath = fixturePlist();
+    const previousPath = process.env.PATH;
+    try {
+      // The login shell that installed the service. The extra entry is deliberately a
+      // directory that cannot exist, so both PATHs resolve the SAME launcher (none) and the
+      // exec line is identical on every host.
+      process.env.PATH = "/opt/ocx-login-shell-only/bin:/usr/bin:/bin";
+      const installedPlist = renderedPlist();
+      // The tray helper / cron context that runs the repair.
+      process.env.PATH = "/usr/bin:/bin";
+      const repairPlist = renderedPlist();
+      // Precondition of the case: PATH is the ONLY difference (neither PATH resolves an
+      // `ocx`, so the exec line is identical).
+      expect(repairPlist).not.toBe(installedPlist);
+      expect(repairPlist.replace(/<key>PATH<\/key><string>[^\n]*<\/string>/, "P"))
+        .toBe(installedPlist.replace(/<key>PATH<\/key><string>[^\n]*<\/string>/, "P"));
+
+      writeFileSync(plistPath, installedPlist, "utf8");
+      const { argv, launchctl } = recordingLaunchctl({});
+
+      installLaunchd({ launchctl, plistPath, probe: loadedCurrent().probe, sleepSync: () => {} });
+
+      expect(argv).toEqual([]);
+      // The installed PATH survived: a repair must not narrow the environment the service
+      // runs in just because of who invoked it.
+      expect(readFileSync(plistPath, "utf8")).toBe(installedPlist);
+    } finally {
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+    }
+  });
+
   test("an identical plist whose job is loaded from an OLDER command still reloads", () => {
     const plistPath = fixturePlist();
     writeFileSync(plistPath, renderedPlist(), "utf8");
-    let matchCalls = 0;
     const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
 
     installLaunchd({
       launchctl,
       plistPath,
-      // First call is the no-op pre-check (stale ⇒ do the repair); the second is the
+      // First answer is the no-op pre-check (stale ⇒ do the repair); the second is the
       // post-bootstrap verification.
-      matches: () => ({ loaded: true, matchesPlist: matchCalls++ > 0 }),
+      probe: scriptedProbe("loaded-stale", "loaded-current").probe,
       sleepSync: () => {},
     });
 
     expect(verbs(argv)).toContain("bootstrap");
+    // Review nit 7: the rollback copy is removed once the new job is verified, so the next
+    // repair's backup cannot be mistaken for this one's.
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
   });
 
-  test("the reload is domain-explicit bootstrap, not legacy load -w", () => {
+  test("the reload is domain-explicit bootstrap in BOTH domains, not legacy load -w", () => {
     const plistPath = fixturePlist();
     const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
 
     installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: true, matchesPlist: true }),
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
       sleepSync: () => {},
     });
 
@@ -157,8 +231,13 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     const bootstrap = argv.find(args => args[0] === "bootstrap");
     expect(bootstrap?.[1]).toMatch(/^gui\/\d+$/);
     expect(bootstrap?.[2]).toBe(plistPath);
-    const bootout = argv.find(args => args[0] === "bootout");
-    expect(bootout?.[1]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+    // Review finding 4: the probe reports `user/<uid>` too, so the eviction covers it.
+    // Evicting gui alone left a user-domain registration of the same Label alive and then
+    // bootstrapped a SECOND one into gui — two KeepAlive jobs for one port.
+    const bootouts = argv.filter(args => args[0] === "bootout").map(args => args[1] ?? "");
+    expect(bootouts).toEqual(launchdEvictionTargets());
+    expect(bootouts[0]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+    expect(bootouts[1]).toMatch(/^user\/\d+\/com\.opencodex\.proxy$/);
     // bootout before bootstrap, with the settle probe in between.
     expect(verbs(argv).indexOf("bootout")).toBeLessThan(verbs(argv).indexOf("bootstrap"));
   });
@@ -172,14 +251,35 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: true, matchesPlist: true }),
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
+      sleepSync: ms => { delays.push(ms); },
+    });
+
+    // 5 × 200 ms per evicted domain, then give up and try the bootstrap anyway — a wedged
+    // domain must reach the diagnosable throw rather than hang.
+    expect(delays).toEqual(Array.from({ length: 10 }, () => 200));
+    expect(verbs(argv).filter(v => v === "print")).toHaveLength(10);
+  });
+
+  test("a bootout that evicted nothing is not settled", () => {
+    const plistPath = fixturePlist();
+    const delays: number[] = [];
+    // Exit 3 in both domains: nothing was loaded, so nothing is exiting to wait for.
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [ok()],
+      bootout: fail(3, "Boot-out failed: 3: No such process"),
+      print: ok("live"),
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
       sleepSync: ms => { delays.push(ms); },
     });
 
-    // 5 × 200 ms, then give up and try the bootstrap anyway — a wedged domain must reach
-    // the diagnosable throw rather than hang.
-    expect(delays).toEqual([200, 200, 200, 200, 200]);
-    expect(verbs(argv).filter(v => v === "print")).toHaveLength(5);
+    expect(delays).toEqual([]);
+    expect(verbs(argv)).toEqual(["bootout", "bootout", "bootstrap"]);
   });
 
   test("a clean bootstrap that did not take is a FAILURE, whatever stderr says", () => {
@@ -190,7 +290,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(() => installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: false, matchesPlist: false }),
+      probe: scriptedProbe("not-loaded").probe,
       sleepSync: () => {},
     })).toThrow(/could not bootstrap/);
 
@@ -200,7 +300,10 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
 
   test("'Bootstrap failed: 5' tries kickstart -k before a second eviction", () => {
     const plistPath = fixturePlist();
-    let matchCalls = 0;
+    // Byte-identical bytes are what makes `kickstart` legitimate here: it restarts the
+    // definition launchd has CACHED, so it can only be trusted when the plist on disk is
+    // unchanged. (The next case covers the other half.)
+    writeFileSync(plistPath, renderedPlist(), "utf8");
     const { argv, launchctl } = recordingLaunchctl({
       bootstrap: [fail(5, "Bootstrap failed: 5: Input/output error")],
     });
@@ -208,12 +311,9 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     installLaunchd({
       launchctl,
       plistPath,
-      // First verification (right after the refused bootstrap) fails; the one after
-      // `kickstart -k` succeeds.
-      matches: () => {
-        const loaded = matchCalls++ >= 1;
-        return { loaded, matchesPlist: loaded };
-      },
+      // Pre-check says the job is gone, the verification right after the refused bootstrap
+      // agrees, and the one after `kickstart -k` finds it.
+      probe: scriptedProbe("not-loaded", "not-loaded", "loaded-current").probe,
       sleepSync: () => {},
     });
 
@@ -225,6 +325,45 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(1);
   });
 
+  /**
+   * Review finding 3. `launchctl kickstart -k` restarts the definition launchd has CACHED;
+   * it does NOT re-read the plist. When only `EnvironmentVariables` changed, the exec line
+   * is identical, so the verification agrees, install state is written, repair reports
+   * success — and launchd keeps serving with the OLD environment. New bytes therefore have
+   * to go through the eviction, which is the only way to hand launchd a new definition.
+   */
+  test("new bytes never trust kickstart: an env-only change still takes the eviction", () => {
+    const plistPath = fixturePlist();
+    const rendered = renderedPlist();
+    const sandboxHome = process.env.OPENCODEX_HOME ?? "";
+    expect(rendered).toContain(sandboxHome);
+    // Differs from the rendered plist in ONE EnvironmentVariables value; the exec line and
+    // every other byte are identical, which is exactly the case kickstart would paper over.
+    const installedPlist = rendered.replace(sandboxHome, join(sandboxHome, "moved"));
+    expect(installedPlist).not.toBe(rendered);
+    writeFileSync(plistPath, installedPlist, "utf8");
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [fail(5, "Bootstrap failed: 5: Input/output error"), ok()],
+      // Would succeed if it were asked — the point is that it is not.
+      kickstart: ok(),
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // The live job runs the command this install bakes (only the env moved), so the
+      // pre-check is `loaded-current` — and must still reload, because PATH is the only
+      // difference a repair is allowed to treat as "nothing to do".
+      probe: scriptedProbe("loaded-current", "not-loaded", "loaded-current").probe,
+      sleepSync: () => {},
+    });
+
+    expect(verbs(argv)).not.toContain("kickstart");
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(2);
+    // The new definition is what is on disk for launchd to read.
+    expect(readFileSync(plistPath, "utf8")).toBe(rendered);
+  });
+
   /**
    * The second meaning of exit 5. Measured on macOS 27.0: `launchctl disable gui/$uid/<label>`
    * makes `bootstrap` fail with the SAME "Bootstrap failed: 5: Input/output error" while
@@ -234,7 +373,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
    */
   test("a DISABLED job is enabled and bootstrapped, the modern spelling of load -w", () => {
     const plistPath = fixturePlist();
-    let matchCalls = 0;
+    writeFileSync(plistPath, renderedPlist(), "utf8");
     const { argv, launchctl } = recordingLaunchctl({
       bootstrap: [fail(5, "Bootstrap failed: 5: Input/output error"), ok()],
       kickstart: fail(113, 'Could not find service "com.opencodex.proxy" in domain for user gui: 501'),
@@ -243,16 +382,17 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     installLaunchd({
       launchctl,
       plistPath,
-      // Loaded only after the enable + second bootstrap. `kickstart` failing
-      // short-circuits its own verification, so this is asked exactly twice.
-      matches: () => {
-        const loaded = matchCalls++ >= 1;
-        return { loaded, matchesPlist: loaded };
-      },
+      // Loaded only after the enable + second bootstrap. A failed `kickstart` skips its own
+      // verification, so the probe is asked exactly three times.
+      probe: scriptedProbe("not-loaded", "not-loaded", "loaded-current").probe,
       sleepSync: () => {},
     });
 
-    expect(verbs(argv)).toEqual(["bootout", "print", "bootstrap", "kickstart", "enable", "bootout", "print", "bootstrap"]);
+    expect(verbs(argv)).toEqual([
+      "bootout", "print", "bootout", "print", "bootstrap",
+      "kickstart", "enable",
+      "bootout", "print", "bootout", "print", "bootstrap",
+    ]);
     const enable = argv.find(args => args[0] === "enable");
     expect(enable?.[1]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
   });
@@ -264,7 +404,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: true, matchesPlist: true }),
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
       sleepSync: () => {},
     });
 
@@ -280,7 +420,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(() => installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: false, matchesPlist: false }),
+      probe: scriptedProbe("not-loaded").probe,
       sleepSync: () => {},
     })).toThrow(/invalid XML/);
 
@@ -299,7 +439,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
       installLaunchd({
         launchctl,
         plistPath,
-        matches: () => ({ loaded: false, matchesPlist: false }),
+        probe: scriptedProbe("not-loaded").probe,
         sleepSync: () => {},
       });
     } catch (error) {
@@ -321,6 +461,24 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(3);
   });
 
+  /**
+   * A job that comes back under a DIFFERENT command is running. Telling its operator
+   * "nothing is listening" sends them to fix the wrong thing — and the two-state
+   * `launchdJobMatchesPlist` this function used could not tell the two apart at all.
+   */
+  test("a job that reloaded from a different command is reported as loaded, not as down", () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, "<plist>previous</plist>\n", "utf8");
+    const { launchctl } = recordingLaunchctl({ bootstrap: [ok(), ok(), ok()] });
+
+    expect(() => installLaunchd({
+      launchctl,
+      plistPath,
+      probe: scriptedProbe("not-loaded", "loaded-stale").probe,
+      sleepSync: () => {},
+    })).toThrow(/is still loaded in gui\/501 from a DIFFERENT command/);
+  });
+
   test("a fresh install has nothing to restore and says so without inventing a rollback", () => {
     const plistPath = fixturePlist();
     const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok(), ok()] });
@@ -328,7 +486,7 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(() => installLaunchd({
       launchctl,
       plistPath,
-      matches: () => ({ loaded: false, matchesPlist: false }),
+      probe: scriptedProbe("not-loaded").probe,
       sleepSync: () => {},
     })).toThrow(/ocx service install/);
 
@@ -336,17 +494,144 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
     expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(2);
   });
 
+  /**
+   * Review finding 1. `launchdJobMatchesPlist` reports `loaded: false` for EVERY non-zero
+   * `launchctl print` — EPERM from a non-Aqua ssh/cron context, an unspawnable launchctl, an
+   * undocumented status. Routed through that, a healthy serving hub failed the pre-check
+   * (evict), failed the verification the same way (evict again, roll back) and was finally
+   * declared "IS NOT RUNNING" while it was up. A probe that could not answer is not evidence.
+   */
+  test("an unverifiable launchd state refuses to evict and changes nothing", () => {
+    const plistPath = fixturePlist();
+    const installedPlist = "<plist>the definition that is serving</plist>\n";
+    writeFileSync(plistPath, installedPlist, "utf8");
+    const { argv, launchctl } = recordingLaunchctl({});
+
+    let thrown: unknown;
+    try {
+      installLaunchd({
+        launchctl,
+        plistPath,
+        probe: scriptedProbe({
+          state: "unknown",
+          detail: "launchctl print gui/501/com.opencodex.proxy exited 1",
+        }).probe,
+        sleepSync: () => {},
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    expect(message).toContain("could not be verified");
+    expect(message).toContain("nothing was changed");
+    // Never the claim that made the outage undiagnosable.
+    expect(message).not.toContain("IS NOT RUNNING");
+    // Named so the operator can ask the question themselves, in both domains.
+    expect(message).toMatch(/launchctl print gui\/\d+\/com\.opencodex\.proxy/);
+    expect(message).toMatch(/launchctl print user\/\d+\/com\.opencodex\.proxy/);
+    // No launchctl verb ran, and the plist on disk is untouched.
+    expect(argv).toEqual([]);
+    expect(readFileSync(plistPath, "utf8")).toBe(installedPlist);
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
+  });
+
+  test("a state that stops answering AFTER an accepted bootstrap is not evicted again", () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, "<plist>previous</plist>\n", "utf8");
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      probe: scriptedProbe("not-loaded", { state: "unknown", detail: "launchctl could not be run: EPERM" }).probe,
+      sleepSync: () => {},
+    });
+
+    // One bootstrap, no retry and no rollback: a retry is another eviction, and the rollback
+    // would evict a job we cannot prove is down.
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(1);
+    expect(readFileSync(plistPath, "utf8")).toBe(renderedPlist());
+  });
+
+  test("a bootstrap that FAILED under an unverifiable state throws without claiming the job is down", () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, "<plist>previous</plist>\n", "utf8");
+    const { argv, launchctl } = recordingLaunchctl({
+      bootstrap: [fail(1, "Bootstrap failed: 1: Operation not permitted")],
+    });
+
+    let thrown: unknown;
+    try {
+      installLaunchd({
+        launchctl,
+        plistPath,
+        probe: scriptedProbe("not-loaded", { state: "unknown", detail: "launchctl could not be run: EPERM" }).probe,
+        sleepSync: () => {},
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    expect(message).toContain("Operation not permitted");
+    expect(message).toContain("could not be verified");
+    expect(message).not.toContain("IS NOT RUNNING");
+    // No rollback bootstrap: restoring means evicting, and nothing here proves the job is
+    // down.
+    expect(verbs(argv).filter(v => v === "bootstrap")).toHaveLength(1);
+  });
+
   test("the armed test guard refuses the developer's real LaunchAgents directory", () => {
     // Without the seam above, every case in this file rewrote the live plist.
     expect(() => installLaunchd({
       plistPath: join(protectedLaunchAgentsDirForTests(), "com.opencodex.proxy.plist"),
       launchctl: recordingLaunchctl({}).launchctl,
-      matches: () => ({ loaded: true, matchesPlist: true }),
+      probe: loadedCurrent().probe,
       sleepSync: () => {},
     })).toThrow(/real LaunchAgents directory/);
   });
 });
 
+describe("reusePreviousPlistPathVariable: PATH is the one difference repair may ignore", () => {
+  const plist = (path: string, port = 10100): string =>
+    `<dict>\n  <key>PATH</key><string>${path}</string>\n  <key>Port</key><string>${port}</string>\n</dict>\n`;
+
+  test("a PATH-only difference yields the previous definition verbatim", () => {
+    const previous = plist("/opt/homebrew/bin:/usr/bin");
+    const adopted = reusePreviousPlistPathVariable(previous, plist("/usr/bin"));
+    expect(adopted).toBe(previous);
+  });
+
+  test("any other difference refuses — the plist must be rewritten in full", () => {
+    // A repair that also changes the port is a real rewrite, and PATH goes with it.
+    expect(reusePreviousPlistPathVariable(plist("/a", 10100), plist("/b", 10101))).toBe(null);
+  });
+
+  test("an identical PATH is not a difference to reuse", () => {
+    expect(reusePreviousPlistPathVariable(plist("/a"), plist("/a"))).toBe(null);
+  });
+
+  test("a PATH holding regex replacement syntax survives verbatim", () => {
+    // A function replacer, not `$1`: `$&` in the previous PATH would otherwise be expanded.
+    const previous = plist("/opt/$&/bin:/usr/bin");
+    expect(reusePreviousPlistPathVariable(previous, plist("/usr/bin"))).toBe(previous);
+  });
+
+  test("a definition with no PATH entry refuses rather than guessing", () => {
+    expect(reusePreviousPlistPathVariable("<dict/>\n", plist("/usr/bin"))).toBe(null);
+  });
+});
+
+describe("launchdEvictionTargets: an eviction covers every domain the probe reports", () => {
+  test("both user domains, in probe order", () => {
+    expect(launchdEvictionTargets(501)).toEqual([
+      "gui/501/com.opencodex.proxy",
+      "user/501/com.opencodex.proxy",
+    ]);
+  });
+});
+
 describe("probeLaunchdLoadState: a tri-state, not one swallowed bit (#4236 defect 2)", () => {
   const printed = (command: string): LaunchctlResult => ok(`{\n\targuments = {\n\t\t${command}\n\t}\n}`);
 
@@ -519,6 +804,45 @@ describe("the surfaces around the repair (#4236 defects 1f, 1h, 2)", () => {
     // Installing over a manager we could not query is the unsafe direction, so this probe
     // keeps failing closed on `unknown` even though `diagnoseService` does not.
     expect(ops).toContain('probe.state === "unknown"');
+    // Review finding 4: the probe answers for `user/<uid>` as well, so a gui-only eviction
+    // exited 3 in the wrong domain and installed new assets over a live job.
+    expect(ops).toContain("for (const target of launchdEvictionTargets())");
+    expect(ops).toContain("launchctlBootoutBenign(booted.status)");
+  });
+
+  /**
+   * Review finding 1. The pre-check and the verification are the two places a two-state
+   * "loaded / not loaded" answer turned one unreadable `launchctl print` into an eviction.
+   */
+  test("installLaunchd asks the tri-state probe, never launchdJobMatchesPlist", () => {
+    const fn = slice("export function installLaunchd(", " * Deps are named for the layer they replace");
+    expect(fn).toContain("probe?: typeof probeLaunchdLoadState;");
+    expect(fn).not.toContain("launchdJobMatchesPlist");
+    // Refuse before any write, and again before any retry or rollback.
+    expect(fn).toContain('if (verdict.state === "unknown") {');
+    expect(fn).toContain("refusing to ${wasInstalled ? \"repair\" : \"install\"}");
+    expect(fn).toContain('verdict.state === "not-loaded" || verdict.state === "loaded-stale"');
+    // `startLaunchd` keeps the two-state helper deliberately: it does not evict anything.
+    expect(slice("export function startLaunchd(", "function stopLaunchd(")).toContain("launchdJobMatchesPlist");
+  });
+
+  test("the no-op pre-check treats a PATH-only difference as identical (finding 2)", () => {
+    const fn = slice("export function installLaunchd(", " * Deps are named for the layer they replace");
+    expect(fn).toContain("reusePreviousPlistPathVariable(previousPlist, rendered)");
+    // Only against a job proven to run the exec line this install baked.
+    expect(fn).toContain('verdict.state === "loaded-current"');
+  });
+
+  test("install state fails loudly instead of writing nowhere (nit 6)", () => {
+    const filter = slice("function serviceStatePaths()", "function currentCodexHome(");
+    expect(filter).toContain("isTestHomeGuardArmed()");
+    // One canonicalization, the guard's own: `resolve()` alone calls /var/... and
+    // /private/var/... different paths on macOS.
+    expect(filter).toContain("isProtectedHomeUnderTest(dirname(path))");
+    expect(filter).toContain("paths.filter(");
+    expect(filter).toContain("refusing to write service install state");
+    expect(slice("function writeServiceInstallState(", "function readServiceInstallState("))
+      .toContain("serviceStateWritePaths()");
   });
 
   test("diagnoseService no longer grep-matches launchctl list (2)", () => {
@@ -537,22 +861,33 @@ describe("the surfaces around the repair (#4236 defects 1f, 1h, 2)", () => {
    * entry is the developer's LIVE record — one case replaced its codexHome and
    * opencodexHome with temp-directory paths before this filter existed.
    */
-  test("install state never reaches the real home from a test process", () => {
-    const fn = slice("function serviceStatePaths()", "function currentCodexHome(");
-    expect(fn).toContain("isTestHomeGuardArmed()");
-    expect(fn).toContain("protectedHomeForTests()");
-    expect(fn).toContain("paths.filter(");
-  });
-
-  test("stop and uninstall prefer bootout and keep unload only as a fallback (D)", () => {
+  test("stop and uninstall prefer bootout, in both domains, and keep unload only as a fallback (D)", () => {
     const stop = slice("function stopLaunchd(", "function statusLaunchd(");
     expect(stop).toContain('run(["bootout"');
+    // Review finding 4: gui-only, a `user/<uid>` job made `ocx service stop` a silent no-op
+    // — `bootout gui/<uid>/<label>` exits 3 in a domain that never held it.
+    expect(stop).toContain("for (const target of launchdEvictionTargets())");
     // The legacy verb survives for exactly one case: launchctl could not be spawned at
     // all (`status === null`), which is the only state a second attempt can improve.
     expect(stop).toContain("launchctl unload");
     expect(stop.indexOf('run(["bootout"')).toBeLessThan(stop.indexOf("launchctl unload"));
     const uninstall = slice("function uninstallLaunchd(", "/**");
+    // Uninstall inherits both domains by routing through stopLaunchd.
     expect(uninstall).toContain("stopLaunchd(deps)");
     expect(uninstall).not.toContain("launchctl unload");
   });
+
+  /**
+   * Review nit 8. `stableLauncherEntry` is shared with `installSystemd`, so "the recorded
+   * launcher wins over a fresh PATH walk" changed Linux too. The behavioural half lives in
+   * `tests/service/service.test.ts`; this pins that the two installers really do call the
+   * same resolver, which is what makes that coverage transferable.
+   */
+  test("the recorded-launcher preference is shared with the systemd installer (nit 8)", () => {
+    const systemd = slice("function installSystemd()", "function startSystemd(");
+    expect(systemd).toContain("stableLauncherEntry()");
+    expect(systemd).toContain("buildUnit(resolvedProxyEnv(), { launcher })");
+    expect(slice("export function installLaunchd(", " * Deps are named for the layer they replace"))
+      .toContain("stableLauncherEntry()");
+  });
 });
diff --git a/tests/service/service.test.ts b/tests/service/service.test.ts
index ed521a0c1d..46ead91c47 100644
--- a/tests/service/service.test.ts
+++ b/tests/service/service.test.ts
@@ -208,6 +208,38 @@ describe("systemd service unit", () => {
     })).toBe(null);
   });
 
+  /**
+   * Review nit 8. `stableLauncherEntry` is shared: `installSystemd` resolves it too, so
+   * "the recorded launcher wins over a fresh PATH walk" is a LINUX change as well as a macOS
+   * one. The unit keeps the `ExecStart` the install recorded instead of rewriting it to the
+   * version-pinned Bun + CLI pair — the #2898 shape launcher mode exists to avoid — when a
+   * repair runs from a context without `ocx` on PATH.
+   */
+  test("a repair without ocx on PATH keeps the recorded launcher in the systemd unit too", async () => {
+    const recorded = join(TEST_DIR, "recorded-systemd", "ocx");
+    const launcher = stableLauncherEntry({
+      state: { version: 2, backend: "scheduler", launcherPath: recorded } as never,
+      env: { PATH: "" },
+      isExecutableFile: candidate => candidate === recorded,
+    });
+    expect(launcher).toBe(recorded);
+
+    const unit = buildUnit(resolvedProxyEnv(), { launcher });
+    expectTextToContainPath(unit, recorded);
+    // Launcher mode means the unit must NOT pin the package-local Bun + CLI pair.
+    expect(unit).not.toContain("OCX_BUN_RUNTIME_PATH");
+
+    // And the installer feeds exactly this resolver into exactly that builder, so the
+    // preference above is the one Linux gets.
+    const service = await readText("src/service.ts");
+    const installSystemd = service.slice(
+      service.indexOf("function installSystemd()"),
+      service.indexOf("function startSystemd()"),
+    );
+    expect(installSystemd).toContain("const launcher = stableLauncherEntry();");
+    expect(installSystemd).toContain("buildUnit(resolvedProxyEnv(), { launcher })");
+  });
+
   test("bare service installs only when absent and otherwise selects no-admin repair", async () => {
     expect(normalizeServiceSubcommand()).toBe("install");
     expect(normalizeServiceSubcommand("restart")).toBe("repair");

From 5a8bffe44aab2a7d16fefd146f74fd0557c3902e Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:51:32 +0900
Subject: [PATCH 6/9] docs(devlog): record the review round of the launchd
 repair lane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each review fix is marked where it belongs rather than appended: the tri-state
probe at both decision points, the PATH-only no-op and its deliberate residual
(PATH stays updatable, so a repair that changes anything else still bakes the
caller's), `kickstart -k` narrowed to bytes already on disk, both user domains in
every eviction, the fail-loud install-state write path, and the shared launcher
preference reaching systemd.

Verification is re-measured and says plainly that the full suite was not run.
Also recorded: the live plist and install state had to be restored again this
round, and not because of this branch's tests — a concurrent session in another
worktree ran the unguarded suite and wrote its sandbox homes into both, which is
the argument for landing these two guards everywhere.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../010_launchd_repair.md                     | 227 +++++++++++++-----
 1 file changed, 173 insertions(+), 54 deletions(-)

diff --git a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
index 21208108f5..8aa0ff9675 100644
--- a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
+++ b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
@@ -7,17 +7,41 @@ Scope: `src/service.ts` macOS path only, plus the two shared test-safety guards
 uncovered. Defects 3 and 4 from the issue (secondary-port misdiagnosis, `ocx status` fence
 comparison) are deliberately left to PR2, which owns the loopback listener.
 
+Two rounds. The first is the three commits below; the second folds in a review of them, and
+every fix it carries is marked in place. In short: the new protocol was still asking the OLD
+two-state `launchdJobMatchesPlist` at both decision points (so an unreadable `launchctl print`
+still evicted a healthy hub, twice), the no-op pre-check compared whole-file bytes while
+`buildPlist` bakes the repairing process's `PATH`, the comment justifying `kickstart -k` was
+wrong about launchd re-reading the plist, and every mutating verb still addressed `gui/<uid>`
+alone while the new probe reports `user/<uid>` too.
+
 ## What shipped
 
 ### A — `installLaunchd()` (repair must not be an outage)
 
-1. **No-op pre-check.** The plist is rendered BEFORE anything is written. If the rendered
-   bytes equal the on-disk bytes, the data-token file is unchanged, and
-   `launchdJobMatchesPlist()` reports `{loaded:true, matchesPlist:true}`, the function
-   re-asserts 0600 on the plist, refreshes install state, logs
+1. **No-op pre-check, on the TRI-STATE probe.** The plist is rendered BEFORE anything is
+   written. If the rendered bytes equal the on-disk bytes, the data-token file is unchanged,
+   and `probeLaunchdLoadState()` answers `loaded-current`, the function re-asserts 0600 on the
+   plist, refreshes install state, logs
    `service is already loaded from the current plist; nothing to do.` and returns. launchd is
    not touched at all. This is the headline fix: a repair of a healthy hub used to evict it
    unconditionally.
+
+   Two things the first round got wrong here, both found in review:
+
+   - It asked `launchdJobMatchesPlist`, which reports `loaded:false` for EVERY non-zero
+     `launchctl print` — EPERM from a non-Aqua ssh/cron context, an unspawnable launchctl, an
+     undocumented status. On a healthy serving hub that read as "not loaded", so the pre-check
+     evicted, the verification failed the same way, the rollback evicted again and the error
+     ended with "IS NOT RUNNING" about a job that was up. Both checks now go through
+     `probeLaunchdLoadState`, and `unknown` refuses to touch launchd at all (item 9).
+   - It compared whole-file bytes, while `buildPlist` bakes `process.env.PATH` from whichever
+     process is repairing. A tray helper, `ocx update`'s child or an ssh session carries a
+     different PATH, so the pre-check missed and the healthy hub was evicted *and* had its
+     PATH narrowed. `reusePreviousPlistPathVariable()` now puts the installed PATH back when
+     PATH is the ONLY difference and the live job runs the exec line this install baked — the
+     two files then compare equal on their own terms, and the PATH the service already runs
+     with survives. Anything else differing means a real rewrite, PATH included.
 2. **Backup + rollback.** The previous plist bytes are held in memory and copied to
    `<plist>.prev` before the overwrite. On terminal failure the bytes go back, a
    bootout/settle/bootstrap tries to re-register them, and the thrown error states whether
@@ -25,26 +49,59 @@ comparison) are deliberately left to PR2, which owns the loopback listener.
 3. **`bootstrap gui/$uid <plist>` replaces `load -w`.** `bootout` was already
    domain-explicit; `load` acts on the CALLER's bootstrap domain, so from ssh/cron/another
    bootstrap context the old pair deleted the gui-domain job and registered nothing.
-4. **Bounded settle between bootout and bootstrap** — up to 5 × 200 ms while
-   `launchctl print gui/$uid/<label>` still answers 0, the launchd twin of the Windows
+4. **Bounded settle after an eviction that evicted something** — up to 5 × 200 ms while
+   `launchctl print <target>` still answers 0, the launchd twin of the Windows
    `SCHEDULER_SETTLE_DELAYS_MS` idea. `bootout` is asynchronous, so the old back-to-back
-   retry raced the same exiting job twice and added nothing.
-5. **Success is `launchctl print` agreeing, never stderr.** `launchdJobMatchesPlist` is
-   consulted against the command this install actually baked, and `writeServiceInstallState`
+   retry raced the same exiting job twice and added nothing. A `bootout` that exited 3 is not
+   settled: nothing is exiting to wait for.
+5. **Success is `probeLaunchdLoadState()` answering `loaded-current`, never stderr.** It is
+   asked against the command this install actually baked, and `writeServiceInstallState`
    runs only after it agrees. Stderr regexes are advisory routing signals now.
-6. **One retry, routed by the failure.** Exit 5 / `Bootstrap failed` → `kickstart -k`, then
-   `enable` + a second bootout/bootstrap (see the launchctl findings below). Exit 0 with a
-   disagreeing `print` → one more bootout/bootstrap, because that is the silent no-op. Any
-   other failure (malformed plist, EPERM) throws immediately so the real stderr reaches the
-   operator undelayed — the property the previous code had and kept.
-7. **Error text names the outage and the remedy**: the job was evicted from `gui/<uid>` and
-   is not running, `launchctl bootstrap gui/<uid> <plist>` recovers it, plus
-   `launchctl print` and `launchctl print-disabled` to inspect.
+6. **One retry, routed by the failure.** Exit 5 / `Bootstrap failed` → `kickstart -k` (only
+   when the rendered bytes are already on disk, see item 10), then `enable` + a second
+   bootout/bootstrap (see the launchctl findings below). Exit 0 with a disagreeing probe →
+   one more bootout/bootstrap, because that is the silent no-op. Any other failure (malformed
+   plist, EPERM) throws immediately so the real stderr reaches the operator undelayed — the
+   property the previous code had and kept. A probe that answered `unknown` is NOT retried: a
+   retry is another eviction.
+7. **Error text names what the probe actually found.** `not-loaded`: the job was evicted from
+   `gui/<uid>` and is not running (or the previous plist was restored and re-bootstrapped).
+   `loaded-stale`: it *is* loaded, from a different command than the plist just written —
+   telling that operator "nothing is listening" sends them to fix the wrong thing. Both name
+   `launchctl bootstrap gui/<uid> <plist>` as the remedy, plus `launchctl print` and
+   `launchctl print-disabled` to inspect.
 8. **`stableLauncherEntry()` prefers the recorded launcher** when it is still an absolute
    executable file, falling back to the PATH walk otherwise (defect 1g). A repair from a
    context without `ocx` on PATH no longer rewrites a working launcher-form plist into the
    version-pinned Bun + CLI pair.
 
+   **This is not a macOS-only change.** `installSystemd` resolves the same function, so a
+   Linux repair from a PATH-less context now keeps the `ExecStart` the unit already has. The
+   failure it prevents there is milder (systemd reloads and restarts; it never evicts into
+   nothing), but the silent rewrite was identical, so the behaviour is deliberately shared
+   rather than branched. `tests/service/service.test.ts` covers the systemd side directly.
+9. **An unverifiable launchd state refuses to act.** `unknown` from the pre-check throws
+   before a single file is written or a single verb is run, saying the job may be RUNNING and
+   naming `launchctl print gui/<uid>/<label>` and `launchctl print user/<uid>/<label>` so the
+   operator can ask it themselves. `unknown` after the bootstrap neither evicts again nor
+   rolls back (a rollback is another eviction) and never claims the job is down: an accepted
+   bootstrap warns and records install state, a refused one throws with the real stderr and
+   an explicit "this says nothing about whether it is running".
+10. **`kickstart -k` is only trusted for bytes already on disk.** launchd restarts the
+   definition it has CACHED; it does not re-read the plist. When only `EnvironmentVariables`
+   changed the exec line is unchanged, so the verification would agree, install state would be
+   written, repair would report success — and launchd would keep the OLD environment. So new
+   bytes skip `kickstart` entirely and go to `enable` + evict/bootstrap, which is the only way
+   to hand launchd a new definition. A fresh install counts as new bytes.
+11. **Both user domains are evicted, and `<plist>.prev` is removed on success.** The probe
+   reports `user/<uid>` as well as `gui/<uid>`, so a gui-only `bootout` left a user-domain
+   registration of the same Label alive and then bootstrapped a SECOND one into `gui/` — two
+   `KeepAlive` jobs fighting for one port. `launchdEvictionTargets()` is the shared list, used
+   by `installLaunchd`, `stopLaunchd` and the install-cleanup `stop`; `bootout` against a
+   label a domain does not hold exits 3 and changes nothing, so both are addressed
+   unconditionally rather than enumerated first. The rollback copy is deleted once the new
+   definition is verified loaded, instead of living until the next `uninstall`.
+
 ### B — `statusLaunchd()` / `diagnoseService()` darwin branch
 
 `launchctl list | grep <label> || true` is gone. New `probeLaunchdLoadState()` asks
@@ -72,9 +129,16 @@ answer, and a throw used to escape to the top level and skip it.
 
 ### D — `stopLaunchd` / `uninstallLaunchd`
 
-`bootout gui/<uid>/<label>` first; legacy `unload` survives only for `status === null`, i.e.
-launchctl could not be spawned at all. Exit 3 ("No such process") is the not-loaded case, not
-a failure. `uninstallLaunchd` routes through `stopLaunchd` and also removes `<plist>.prev`.
+`bootout` in EVERY domain `launchdEvictionTargets()` names (`gui/<uid>` and `user/<uid>`);
+legacy `unload` survives only when launchctl could not be spawned at all (`status === null`).
+Exit 3 ("No such process") is the not-loaded case, not a failure. `uninstallLaunchd` routes
+through `stopLaunchd` and also removes `<plist>.prev`.
+
+Gui-only was the remaining half of the same defect: against a `user/`-domain job
+`ocx service stop` exited 3 in a domain that never held it and returned as though it had
+stopped something, and the install-cleanup `stop` did the same before laying new assets over a
+live manager. The cleanup `stop` now treats 0/3/112/113 as benign per domain
+(`launchctlBootoutBenign`) and throws on anything else, so it still fails closed.
 
 ### Two test-safety guards this work uncovered
 
@@ -93,6 +157,14 @@ Both were pre-existing, and both were hitting this machine.
   record. Observed directly: one run replaced this host's `codexHome`/`opencodexHome` with
   `/var/folders/...` paths.
 
+  Two review fixes on top: the filter asks the guard's own `isProtectedHomeUnderTest()` so one
+  canonicalization decides (a local `resolve()` calls `/var/folders/...` and
+  `/private/var/folders/...` different directories on macOS), and `writeServiceInstallState`
+  goes through `serviceStateWritePaths()`, which THROWS when the filter leaves nothing. With
+  `OPENCODEX_HOME` unset under an armed guard both candidates resolve to the real home, the
+  list went empty, and the writer silently wrote nowhere while reporting success. Reads stay
+  quiet — an empty read list is "no install state", which is true.
+
 Both real files on this machine were restored from the live job's own
 `launchctl print` output and re-verified (`plutil -lint` OK, command identical to the running
 job, 0600, `/healthz` 200). Nothing was left in `~/Library/LaunchAgents` by this work.
@@ -173,54 +245,101 @@ record; it references nothing and is harmless.
   defect 1c). The no-op now lives inside `installLaunchd`, which is the only function that
   knows whether the rendered plist differs — a check in `repairService` would have to re-render
   it to be correct.
+- **PATH is reused only when it is the ONLY difference.** Always preserving the installed
+  PATH would make it un-updatable except through `uninstall` + `install`; never preserving it
+  is the bug. So a plist that differs in PATH *and* something else is rewritten whole, which
+  means a repair that legitimately changes the definition still bakes the repairing process's
+  PATH. That is the accepted residual: at that point the eviction was going to happen anyway,
+  and the operator asked for a new definition. The narrow rule is what keeps the common case —
+  a repair from a tray helper or `ocx update`'s child against an otherwise-identical
+  definition — from being an outage.
+- **`unknown` refuses the whole command, install included.** A repair that cannot read
+  launchd's state cannot prove the hub is down, and evicting on that guess is the original
+  defect. A fresh install refuses for the same reason: the install path's own cleanup ops
+  already fail closed on `unknown`, and the label may be held by a registration we cannot see.
+  The cost is that a repair from a context which genuinely cannot reach `gui/<uid>` (ssh,
+  cron) now fails instead of acting — with an error that says so and names the two `print`
+  commands. That is the direction that keeps a serving hub serving.
+- **Both domains are evicted unconditionally rather than enumerated.** `probeLaunchdLoadState`
+  stops at the first domain that answers, so it cannot report "both"; asking twice more just
+  to learn what `bootout` reports by exiting 3 would add a round trip per install for nothing.
+- **`kickstart -k` kept, but narrowed.** It is still the only recovery that does not open a
+  second eviction window, which is worth having for the busy-label case. It just cannot
+  publish bytes, so it is limited to the case where there are none to publish.
 
 ## Tests
 
-New `tests/service/launchd-repair.test.ts` (30 cases), registered in
+`tests/service/launchd-repair.test.ts` (46 cases), registered in
 `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`. The five
 obsolete `installLaunchd` cases in `tests/service/service.test.ts` (which asserted the `load`
-verb) were removed and replaced by a pointer comment; one new `stableLauncherEntry` case was
-added there, and the two existing launcher-discovery cases now pass `state: null` to stay
-PATH-discovery tests.
-
-Coverage: healthy-and-identical repair is a no-op (zero launchctl calls); identical plist but
-stale live command still reloads; the reload is domain-explicit `bootstrap` with no `load` /
-`unload`; the settle loop waits while `print` answers 0 and is bounded at 5 × 200 ms; exit 0
-with a disagreeing `print` is a failure; exit 5 tries `kickstart -k`; a disabled job takes
-`enable` + bootstrap; an ordinary repair never runs `enable`; a malformed plist is not
+verb) were removed and replaced by a pointer comment; two new `stableLauncherEntry` cases were
+added there (the recorded-launcher preference, and the systemd half of it), and the two
+existing launcher-discovery cases now pass `state: null` to stay PATH-discovery tests.
+
+Every `installLaunchd` case injects `plistPath` into its own fixture directory and a scripted
+tri-state `probe`, so none of them can reach the real LaunchAgents path or a live launchctl.
+`OPENCODEX_HOME` is pinned per case and RESTORED afterwards — the first round set it with no
+`afterEach`, which leaks this file's temp home into the next file in the same Bun worker.
+
+Coverage: healthy-and-identical repair is a no-op (zero launchctl calls); a plist differing
+ONLY in the baked PATH is also a no-op and keeps the installed PATH on disk; identical plist
+but stale live command still reloads, and deletes `<plist>.prev`; the reload is
+domain-explicit `bootstrap` preceded by a `bootout` of BOTH domains, with no `load`/`unload`;
+the settle loop waits while `print` answers 0, is bounded at 5 × 200 ms per evicted domain, and
+is skipped entirely for a `bootout` that exited 3; exit 0 with a disagreeing probe is a
+failure; exit 5 tries `kickstart -k` for unchanged bytes and refuses to trust it for an
+env-only change (two bootstraps, no kickstart); a disabled job takes `enable` + bootstrap in a
+pinned twelve-verb sequence; an ordinary repair never runs `enable`; a malformed plist is not
 retried; terminal failure restores the previous bytes and names
-`launchctl bootstrap gui/<uid> <plist>` and `print-disabled`; a fresh install invents no
-rollback; the LaunchAgents guard refuses the real directory; the 0/112/113/spawn-failure
-tri-state including "113 in gui is not absence, ask user/ too"; all four diagnostic states
-with `unknown` producing neither "not loaded" nor a repair recommendation; plus source-oracle
-cases for the repair-branch try/catch, the install-cleanup ops, and the state-path filter.
+`launchctl bootstrap gui/<uid> <plist>` and `print-disabled`; a `loaded-stale` outcome is
+reported as loaded rather than down; a fresh install invents no rollback; an `unknown`
+pre-check changes nothing at all (no verb, no file, no `.prev`) and names both `print`
+commands; an `unknown` after an accepted bootstrap neither retries nor rolls back; an
+`unknown` after a refused one throws without "IS NOT RUNNING"; the LaunchAgents guard refuses
+the real directory. Plus `reusePreviousPlistPathVariable` (PATH-only, anything-else, identical,
+a PATH containing `$&`, a definition with no PATH entry), `launchdEvictionTargets`, the
+0/112/113/spawn-failure probe tri-state including "113 in gui is not absence, ask user/ too",
+all four diagnostic states, and source-oracle cases for the repair-branch try/catch, the
+install-cleanup ops (both domains, benign statuses), `installLaunchd` never using
+`launchdJobMatchesPlist` while `startLaunchd` still does, the PATH pre-check, the state-path
+filter plus its fail-loud write path, stop/uninstall, and the shared systemd launcher.
 
 ## Verification
 
 Run from the worktree with `node_modules` symlinked.
 
 ```
-bun run typecheck                                  → clean (no output)
-bun test tests/service/launchd-repair.test.ts      → 30 pass, 0 fail, 106 expect()
-bun test tests/service/service.test.ts             → 204 pass, 0 fail, 663 expect()
-bun test tests/service                             → 518 pass, 9 fail
-bun test tests/service tests/update \
-  tests/cli/uninstall.test.ts tests/ci-workflows \
-  tests/codex-integration/codex-service-manager-probe.test.ts \
+bun run typecheck                                    → clean (no output)
+bun test tests/service/launchd-repair.test.ts        → 46 pass, 0 fail, 169 expect()
+bun test tests/service/service.test.ts               → 205 pass, 0 fail, 668 expect()
+bun test tests/service/launchd-repair.test.ts \
+  tests/service/service.test.ts \
   tests/test-layout.test.ts tests/test-layout-tooling.test.ts
-                                                   → 1505 pass, 9 fail
-bun run privacy:scan                               → Privacy scan passed
+                                                     → 268 pass, 0 fail, 1388 expect()
+bun test tests/service tests/update \
+  tests/cli/uninstall.test.ts                        → 765 pass, 9 fail
+bun run privacy:scan                                 → Privacy scan passed
 ```
 
-Those 9 failures are pre-existing and identical on `dev`: 8 `winsw` cases plus
-`xAI API-key runtime injects priority while OAuth does not`. They are cross-file
-`OPENCODEX_HOME` pollution inside a single domain-wide `bun test` invocation — each file
-passes alone (`bun test tests/service/winsw.test.ts` → 25 pass,
-`tests/service/service-tier-capability.test.ts` → 35 pass) — and the same 9 fail on a stashed
-working tree at `dev`. The full suite was not run, per the lane instruction; hosted CI is the
-proof.
+Those 9 failures are pre-existing: 8 `winsw` cases plus `xAI API-key runtime injects priority
+while OAuth does not`. They are cross-file `OPENCODEX_HOME` pollution inside a single
+domain-wide `bun test` invocation — each file passes alone (`bun test
+tests/service/winsw.test.ts` → 25 pass) — and the same 9 failed on `dev` before this branch
+existed. **The full suite was NOT run** (focused files plus typecheck, per the lane
+instruction); hosted CI on the pushed head is the proof.
 
 Host state after the run: `~/Library/LaunchAgents/com.opencodex.proxy.plist` 1985 bytes,
-0600, `plutil -lint` OK, command identical to `launchctl print gui/501/com.opencodex.proxy`;
-`~/.opencodex/service-state.json` 320 bytes with the real homes; `~/.opencodex/service-api-token`
-untouched; `/healthz` on 10100 → 200; no `*.prev` file left behind.
+0600, `plutil -lint` OK, command and `EnvironmentVariables` identical to
+`launchctl print gui/501/com.opencodex.proxy`; `~/.opencodex/service-state.json` 320 bytes with
+the real homes; `~/.opencodex/service-api-token` untouched; `/healthz` on 10100 → 200; no
+`*.prev` file left behind. No `launchctl bootout`/`bootstrap`/`kickstart`/`enable` was run
+against the live label at any point in this round — only `print`.
+
+Both real files had to be restored AGAIN during this round, and not by this branch's tests: a
+concurrent session working out of another worktree (`.claude/worktrees/agent-ae68eb45f20e1f3c6`,
+whose `cliPath` the damaged state file recorded) ran the unguarded suite and rewrote the live
+plist with `/var/folders/.../opencodex-test-*` homes plus the live state record with its own
+sandbox paths. launchd kept serving from its cached definition, so nothing broke — which is
+exactly why it goes unnoticed until the next restart. Restored from the running job's own
+`launchctl print` output, as before. That is the strongest argument for the two guards in this
+PR: until every branch carries them, any worktree's `bun test tests/service` can do this.

From 3d2e9571cfdcd3c7ed1084f2cd2a32f2bbdb39f3 Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 11:52:47 +0900
Subject: [PATCH 7/9] docs(devlog): name both unguarded writers of the live
 launchd assets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live plist and install state were clobbered twice during this round, and the
damaged state record names its writer in `cliPath`: a second worktree, and a
sibling agent's scratchpad checkout, both running the suite from a branch without
`assertNotRealLaunchAgentsUnderTest`. Say so precisely, note that this branch's
own writes are refused by the guard, and record the limit — a guard protects only
the branch that carries it, so the two live files are worth re-checking after any
concurrent session finishes.

Refs #4236

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../010_launchd_repair.md                     | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
index 8aa0ff9675..95424217fa 100644
--- a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
+++ b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
@@ -335,11 +335,18 @@ the real homes; `~/.opencodex/service-api-token` untouched; `/healthz` on 10100
 `*.prev` file left behind. No `launchctl bootout`/`bootstrap`/`kickstart`/`enable` was run
 against the live label at any point in this round — only `print`.
 
-Both real files had to be restored AGAIN during this round, and not by this branch's tests: a
-concurrent session working out of another worktree (`.claude/worktrees/agent-ae68eb45f20e1f3c6`,
-whose `cliPath` the damaged state file recorded) ran the unguarded suite and rewrote the live
-plist with `/var/folders/.../opencodex-test-*` homes plus the live state record with its own
-sandbox paths. launchd kept serving from its cached definition, so nothing broke — which is
-exactly why it goes unnoticed until the next restart. Restored from the running job's own
-`launchctl print` output, as before. That is the strongest argument for the two guards in this
-PR: until every branch carries them, any worktree's `bun test tests/service` can do this.
+Both real files had to be restored TWICE during this round, and neither time by this branch's
+tests — every `installLaunchd` write here is refused by `assertNotRealLaunchAgentsUnderTest`,
+and the only other writer of that path (`uninstallLaunchd`) is guarded the same way.
+Concurrent sessions in OTHER worktrees ran the unguarded suite and rewrote the live plist with
+`/var/folders/.../opencodex-test-*` homes plus the live state record with their own sandbox
+paths. The damaged state file names its writer in `cliPath`: once
+`.claude/worktrees/agent-ae68eb45f20e1f3c6`, once a scratchpad worktree belonging to a sibling
+agent of this very task. launchd keeps serving from its cached definition, so nothing breaks —
+which is exactly why it goes unnoticed until the next restart. Restored both times from the
+running job's own `launchctl print` output (plist 1985 bytes / state 320 bytes, verified).
+
+That is the strongest argument for the two guards in this PR, and also its limit: a guard only
+protects the branch that has it. Until this lands, any worktree's `bun test tests/service` can
+do this again — including after this round was verified, so the live files are worth re-checking
+once the concurrent sessions are finished.

From ee6a20a0e84fc9aef33520a6642b35601b663931 Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 12:28:38 +0900
Subject: [PATCH 8/9] fix(service): make ocx service restart restart a healthy
 launchd job
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`restart` mapped to `repair`, and `repair` on darwin IS `installLaunchd`, which now
returns early when the plist is already current and the probe says the job is loaded
from it (#4236). So `ocx service restart` of a healthy macOS service restarted nothing,
and the operator docs had to tell people to run
`launchctl kickstart -k gui/$(id -u)/com.opencodex.proxy` by hand.

`installLaunchd` now returns `LaunchdInstallOutcome { reloaded }` — false only on that
no-op path — and `repairService` takes the verb. On darwin, `restart` plus
`reloaded: false` runs `restartLaunchdJob()`: `kickstart -k gui/<uid>/<label>`, which
restarts what the domain already holds without opening an eviction window, verified with
`probeLaunchdLoadState` and logged as one line. `unknown` warns (it is not evidence);
absence, a stale command or a refused kickstart throw, and the repair branch still runs
its `reportServiceServing` health wait, now reporting `restarted`.

`repair` keeps the no-op: a repair of a healthy service must not be an outage, and only
the verb that promises a new process costs one. A bare `ocx service` still selects
`repair`. Windows (stop + start) and Linux (`installSystemd` ends in an unconditional
`systemctl --user restart`) already restart whichever verb asked and are unchanged.
`version-skew` advice switches to `restart`, since a skew leaves the definition
byte-identical and repair would no-op over the old process.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../010_launchd_repair.md                     |  75 ++++++-
 src/cli/registry.ts                           |   5 +-
 src/cli/version-skew.ts                       |   5 +-
 src/service.ts                                | 147 ++++++++++--
 tests/cli/cli-version-skew.test.ts            |   2 +-
 tests/service/launchd-repair.test.ts          | 210 +++++++++++++++++-
 tests/service/service.test.ts                 |  26 ++-
 7 files changed, 443 insertions(+), 27 deletions(-)

diff --git a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
index 95424217fa..15d88e421d 100644
--- a/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
+++ b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
@@ -7,8 +7,9 @@ Scope: `src/service.ts` macOS path only, plus the two shared test-safety guards
 uncovered. Defects 3 and 4 from the issue (secondary-port misdiagnosis, `ocx status` fence
 comparison) are deliberately left to PR2, which owns the loopback listener.
 
-Two rounds. The first is the three commits below; the second folds in a review of them, and
-every fix it carries is marked in place. In short: the new protocol was still asking the OLD
+Three rounds. The first is the three commits below; the second folds in a review of them, and
+every fix it carries is marked in place; the third (section E) makes `ocx service restart`
+actually restart, which the second round's no-op had quietly turned into a no-op of its own. In short: the new protocol was still asking the OLD
 two-state `launchdJobMatchesPlist` at both decision points (so an unreadable `launchctl print`
 still evicted a healthy hub, twice), the no-op pre-check compared whole-file bytes while
 `buildPlist` bakes the repairing process's `PATH`, the comment justifying `kickstart -k` was
@@ -140,6 +141,56 @@ stopped something, and the install-cleanup `stop` did the same before laying new
 live manager. The cleanup `stop` now treats 0/3/112/113 as benign per domain
 (`launchctlBootoutBenign`) and throws on anything else, so it still fails closed.
 
+### E — the `restart` verb (follow-up round)
+
+The no-op in A/1 has a second half. `ocx service restart` maps to the repair path, so once
+`installLaunchd` started returning early on a healthy loaded-current job, a restart of a
+healthy macOS service restarted **nothing** — and the operator docs had to tell people to run
+`launchctl kickstart -k gui/$(id -u)/com.opencodex.proxy` themselves, which is the opposite of
+the "simpler commands" goal.
+
+- `installLaunchd` now returns `LaunchdInstallOutcome { reloaded }`. `false` is the no-op path
+  and only that path: the plist was not rewritten, launchd was not touched, the job is the
+  same process it was. `platformOps` wraps the call, because `ServiceOps.install` promises
+  nothing about a return value.
+- `repairService` takes a `verb: "repair" | "restart"`. On darwin, `restart` + `reloaded:
+  false` runs `restartLaunchdJob()`: `launchctl kickstart -k gui/<uid>/<label>`, verified with
+  `probeLaunchdLoadState` against the exec line an install would bake, logging one line —
+  `service restarted (launchctl kickstart -k gui/<uid>/com.opencodex.proxy).` An `unknown`
+  probe warns (it is not evidence); `not-loaded`/`loaded-stale`/a failed kickstart throw with
+  the manual command, and the repair branch still runs its `reportServiceServing` health wait.
+  `kickstart -k` is the right verb here precisely because it opens no eviction window — and it
+  cannot publish bytes, which is irrelevant when there are none to publish.
+- **`repair` keeps the no-op.** A repair of a healthy service must not be an outage; only the
+  verb that promises a new process costs one.
+- `normalizeServiceSubcommand` no longer folds `restart` into `repair`; `serviceCommand`'s
+  repair branch accepts both and passes the verb down, and reports `restarted` rather than
+  `repaired`. A BARE `ocx service` still selects `repair` — it is an idempotent "make it
+  current", not a request to bounce a healthy hub.
+- **Windows and Linux are unchanged.** The scheduler repair already stops then starts the
+  task, WinSW repair restarts the service, and `installSystemd` ends in an unconditional
+  `systemctl --user restart`, so neither platform has a no-op to compensate for and neither
+  reads the verb. Checked rather than assumed — the Linux installer was the one that could
+  have had the same problem.
+- `src/cli/version-skew.ts` now advises `ocx service restart` instead of
+  `ocx service repair (restart is an alias)`: a version skew leaves the definition byte-
+  identical, so repair would no-op and keep the old process serving. `src/cli/registry.ts`
+  describes the two verbs separately; the `service` usage error does too.
+
+Tests (8 new cases in `tests/service/launchd-repair.test.ts`, 54 total): restart of a healthy
+loaded-current job runs exactly `kickstart -k` on the gui domain and no `bootout`/`bootstrap`;
+repair of the same state runs zero launchctl calls and never reaches the restarter; restart of
+a not-loaded job takes the ordinary evict/bootstrap path with no kickstart; `installLaunchd`
+returns `{ reloaded: false }` / `{ reloaded: true }` for the two paths; `restartLaunchdJob`
+prints the one line naming the command, throws when the job is gone afterwards, and only warns
+on `unknown`; a source-oracle case pins the darwin wiring (restart verb only, real default
+restarter) and the unconditional `systemctl --user restart`. `tests/service/service.test.ts`
+covers the verb surviving `normalizeServiceSubcommand`/`planServiceCommand`/
+`selectServiceSubcommand` and the shared dispatch branch. Every case injects `restartLaunchd`
+or the launchctl seam: the default would kickstart the live hub, and `kickstart` is not on the
+live-service-manager guard's read-only list, so a default call from an armed test process
+fails closed.
+
 ### Two test-safety guards this work uncovered
 
 Both were pre-existing, and both were hitting this machine.
@@ -269,7 +320,8 @@ record; it references nothing and is harmless.
 
 ## Tests
 
-`tests/service/launchd-repair.test.ts` (46 cases), registered in
+`tests/service/launchd-repair.test.ts` (54 cases — 46 from the first two rounds plus 8 for the
+restart verb in section E), registered in
 `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`. The five
 obsolete `installLaunchd` cases in `tests/service/service.test.ts` (which asserted the `load`
 verb) were removed and replaced by a pointer comment; two new `stableLauncherEntry` cases were
@@ -308,6 +360,23 @@ filter plus its fail-loud write path, stop/uninstall, and the shared systemd lau
 
 Run from the worktree with `node_modules` symlinked.
 
+Second round (the `restart` verb):
+
+```
+bun run typecheck                                    → clean (no output)
+bun test tests/service/launchd-repair.test.ts        → 54 pass, 0 fail, 195 expect()
+bun test tests/service/service.test.ts               → 205 pass, 0 fail, 674 expect()
+bun test tests/cli/cli-version-skew.test.ts          → 29 pass, 0 fail
+bun test tests/cli/cli-help.test.ts                  → 17 pass, 0 fail
+bun run privacy:scan                                 → Privacy scan passed
+```
+
+Host state re-verified afterwards, read-only: plist 1985 bytes / state 320 bytes (both
+unchanged, same mtime), `/healthz` on 10100 → 200. No `launchctl` mutation of the live label at
+any point — `kickstart` included.
+
+First round:
+
 ```
 bun run typecheck                                    → clean (no output)
 bun test tests/service/launchd-repair.test.ts        → 46 pass, 0 fail, 169 expect()
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index 73bbd68e31..06b0dfaf29 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -64,8 +64,9 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove]",
     summary: "Run as a background service.",
     details: [
-      "With no subcommand, installs when absent or repairs/restarts an existing service.",
-      "`restart` aliases `repair`; healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
+      "With no subcommand, installs when absent or repairs an existing service.",
+      "`repair` refreshes the definition and reloads the manager only when something changed, so repairing a healthy service is not an outage.",
+      "`restart` is the same refresh but always restarts: on macOS an unchanged, already-loaded job is kickstarted in place. Healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
       "Use `ocx service status` to see diagnostics and log paths.",
     ],
   },
diff --git a/src/cli/version-skew.ts b/src/cli/version-skew.ts
index 48b71a51ee..7acd5177b3 100644
--- a/src/cli/version-skew.ts
+++ b/src/cli/version-skew.ts
@@ -66,7 +66,10 @@ export function computeVersionSkew(cliVersion: string, proxyVersion: string | un
   const order = cliSemver && proxySemver ? compareVersions(cliSemver, proxySemver) : 0;
   const advice = order > 0
     ? "the running proxy is older than this CLI. Restart the proxy using the intended current installation. "
-      + "For a background service, run ocx service repair (ocx service restart is an alias)."
+      // `restart`, not `repair`: a version skew leaves the service DEFINITION unchanged, and
+      // repair reloads only when something changed, so it would no-op and keep the old
+      // process serving (#4249).
+      + "For a background service, run ocx service restart (repair reloads only a changed definition)."
     : order < 0
       ? "this ocx on PATH is older than the running proxy. Upgrade the CLI or resolve PATH to the intended installation."
       : "the versions differ, but neither can be identified as older. Check which installations the CLI and proxy use.";
diff --git a/src/service.ts b/src/service.ts
index 13b26beb7d..1a678e7438 100644
--- a/src/service.ts
+++ b/src/service.ts
@@ -898,7 +898,7 @@ export async function confirmServiceServing(
  * dead port.
  */
 export async function reportServiceServing(
-  verb: "installed" | "started" | "repaired",
+  verb: "installed" | "started" | "repaired" | "restarted",
   deps: Parameters<typeof confirmServiceServing>[0] = {},
 ): Promise<void> {
   const healthBudgetMs = deps.timeoutMs ?? serviceInstallHealthMs();
@@ -2591,6 +2591,20 @@ function readTextOrNull(path: string): string | null {
   }
 }
 
+/**
+ * What an install or repair actually DID to launchd.
+ *
+ * `reloaded: false` means the no-op path was taken — the plist on disk was already the
+ * rendered one, the data token was unchanged, and the probe answered `loaded-current` — so
+ * launchd was never asked for anything and the job is still the same process it was. That
+ * is the right answer for `repair` (a repair of a healthy service must not be an outage)
+ * and the WRONG one for `restart`, which is the verb an operator reaches for precisely when
+ * they want a new process. Only `restart` acts on it; see {@link restartLaunchdJob}.
+ */
+export interface LaunchdInstallOutcome {
+  reloaded: boolean;
+}
+
 /**
  * Deps follow {@link startLaunchd}: `launchctl` replaces the LAYER, returning a
  * {@link runLaunchctl} result, not a spawnSync result. Every one is optional so this stays
@@ -2631,6 +2645,9 @@ function readTextOrNull(path: string): string | null {
  *  5. On terminal failure restore the previous plist, try to bootstrap it back, and throw
  *     an error that says what the probe actually found — down, or up on a different
  *     command — and names the manual remedy.
+ *
+ * Returns {@link LaunchdInstallOutcome} so the one caller that needs a RESTART rather than a
+ * repair can tell the no-op path from a reload. See {@link restartLaunchdJob}.
  */
 export function installLaunchd(deps: {
   launchctl?: typeof runLaunchctl;
@@ -2644,7 +2661,7 @@ export function installLaunchd(deps: {
    * refusal mechanical rather than a convention.
    */
   plistPath?: string;
-} = {}): void {
+} = {}): LaunchdInstallOutcome {
   const run = deps.launchctl ?? runLaunchctl;
   const probeLoadState = deps.probe ?? probeLaunchdLoadState;
   const sleepSync = deps.sleepSync ?? ((ms: number) => { Bun.sleepSync(ms); });
@@ -2716,7 +2733,9 @@ export function installLaunchd(deps: {
     // a repair that leaves it stale re-creates the false "OLDER plist" report.
     writeServiceInstallState("scheduler", launcher);
     console.log("ℹ️  service is already loaded from the current plist; nothing to do.");
-    return;
+    // The ONLY `reloaded: false` exit: the process launchd was running when this command
+    // started is still running, same pid. `ocx service restart` turns that into a kickstart.
+    return { reloaded: false };
   }
 
   if (previousPlist !== null) {
@@ -2812,7 +2831,7 @@ export function installLaunchd(deps: {
         verdict.detail ?? "launchctl could not be asked"}. Check: launchctl print ${guiTarget}`,
     );
     writeServiceInstallState("scheduler", launcher);
-    return;
+    return { reloaded: true };
   }
 
   if (verdict.state !== "loaded-current") {
@@ -2855,6 +2874,67 @@ export function installLaunchd(deps: {
   // behind makes the NEXT repair's backup ambiguous (which failure did it come from?) and
   // `uninstall` the only thing that ever cleaned it up.
   if (existsSync(`${p}.prev`)) { try { unlinkSync(`${p}.prev`); } catch { /* best-effort */ } }
+  return { reloaded: true };
+}
+/**
+ * Restart the loaded job IN PLACE — the `restart` half of `ocx service restart`.
+ *
+ * Only reached when {@link installLaunchd} reported `reloaded: false`, i.e. the plist is
+ * already the current one and the probe proved the job is loaded from it. Nothing has to be
+ * published, so this must NOT evict: `kickstart -k` restarts what the domain already holds
+ * without opening an eviction window, which is the whole reason `restart` can be honest
+ * about a healthy service while `repair` stays a no-op on it. `kickstart` restarts the
+ * definition launchd has CACHED and does not re-read the plist — harmless here, and exactly
+ * why the retry path inside `installLaunchd` may only use it for bytes already on disk.
+ *
+ * `launchctl print` answers about REGISTRATION, not liveness, so the verification asks the
+ * same tri-state probe `installLaunchd` does: `loaded-current` is the restart confirmed,
+ * `unknown` is not evidence of anything and only warns, and absence after a kick means the
+ * job went away and KeepAlive did not bring it back — which throws, so the repair branch
+ * reports it and still runs its serving check.
+ *
+ * Both deps are test seams, and the default runner is also refused by
+ * `assertLiveServiceManagerAllowed`: `kickstart` is not a read-only verb, so an armed test
+ * process that reached the real runner would fail closed rather than bounce the developer's
+ * own hub.
+ */
+export function restartLaunchdJob(deps: {
+  launchctl?: typeof runLaunchctl;
+  probe?: typeof probeLaunchdLoadState;
+  /** The exec line the live job must carry; defaults to the one an install would bake. */
+  expectedCommand?: () => string;
+} = {}): void {
+  const run = deps.launchctl ?? runLaunchctl;
+  const target = `${launchdGuiDomain()}/${LABEL}`;
+  const expectedCommand = deps.expectedCommand
+    ?? (() => launchdServiceCommand(stableLauncherEntry()));
+  const kicked = run(["kickstart", "-k", target]);
+  const verdict = (deps.probe ?? probeLaunchdLoadState)({ expectedCommand });
+  if (!kicked.ok || verdict.state === "not-loaded" || verdict.state === "loaded-stale") {
+    // Three different things to say, because they send the operator to three different
+    // places: the job is gone, the job is up on an older definition, or the job is up and
+    // `kickstart` refused — in which case the proxy is fine and only the restart failed.
+    const state = verdict.state === "not-loaded"
+      ? `is NOT loaded in ${launchdGuiDomain()} — nothing is listening`
+      : verdict.state === "loaded-stale"
+        ? "is loaded from a DIFFERENT command than the plist on disk"
+        : "is still loaded, so it may be serving the process this restart failed to replace";
+    throw new Error(
+      `launchctl could not restart ${LABEL}: ${kicked.stderr || "kickstart reported failure"}\n`
+      + `The ${LABEL} job ${state}.\n`
+      + `Restart it manually with:\n  launchctl kickstart -k ${target}\n`
+      + `Inspect it with:\n  launchctl print ${target}\n`
+      + "and run 'ocx service repair' if it is absent.",
+    );
+  }
+  if (verdict.state === "unknown") {
+    console.warn(
+      `⚠️  launchctl accepted the restart but the job state could not be verified — ${
+        verdict.detail ?? "launchctl could not be asked"}. Check: launchctl print ${target}`,
+    );
+    return;
+  }
+  console.log(`ℹ️  service restarted (launchctl kickstart -k ${target}).`);
 }
 /**
  * Deps are named for the layer they replace, not for the process API: `launchctl`
@@ -3422,6 +3502,13 @@ async function restoreWindowsSchedulerTaskIfAbsent(registeredXml: string): Promi
   }
 }
 
+/**
+ * The two CLI verbs `repairService` serves. They differ on ONE platform and ONE case: a
+ * macOS job that is already loaded from the current plist, which `repair` must not touch and
+ * `restart` must restart.
+ */
+export type ServiceRepairVerb = "repair" | "restart";
+
 export interface RepairServiceDeps {
   diagnose?: () => ServiceDiagnostic;
   assertEnv?: () => void;
@@ -3432,8 +3519,17 @@ export interface RepairServiceDeps {
   writeSchedulerState?: () => void;
   writeNativeState?: () => void;
   repairNative?: () => void | Promise<void>;
-  repairLaunchd?: () => void;
+  repairLaunchd?: () => LaunchdInstallOutcome | void;
   repairSystemd?: () => void;
+  /** Restarts a launchd job the install path deliberately left alone. `restart` only. */
+  restartLaunchd?: () => void;
+  /**
+   * Which CLI verb is being served. `repair` must leave a healthy service alone — that no-op
+   * IS the #4236 fix — while `restart` promises a new process, so on darwin it kicks the job
+   * the no-op path did not touch. Windows (stop + start) and Linux
+   * (`systemctl --user restart`) already restart unconditionally, so neither reads this.
+   */
+  verb?: ServiceRepairVerb;
   /** Reads live registered task XML; may be called again after failure, empty when unreadable. */
   readSchedulerXml?: () => string;
   /** Bounded wait before retrying an unreadable live registration snapshot. */
@@ -3706,10 +3802,19 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
     return;
   }
   if (platform === "darwin") {
-    (deps.repairLaunchd ?? installLaunchd)();
+    const outcome = (deps.repairLaunchd ?? installLaunchd)();
+    // `installLaunchd` is the only function that knows whether it published anything, and its
+    // no-op path leaves the live process running on purpose. `repair` wants exactly that;
+    // `restart` would otherwise restart NOTHING on a healthy hub and send the operator to run
+    // `launchctl kickstart -k` by hand, which is the opposite of what these verbs are for.
+    if ((deps.verb ?? "repair") === "restart" && outcome?.reloaded === false) {
+      (deps.restartLaunchd ?? restartLaunchdJob)();
+    }
     return;
   }
   if (platform === "linux") {
+    // `installSystemd` ends in `systemctl --user restart`, unconditionally, so the unit is
+    // restarted whichever verb asked — there is no no-op path here to compensate for.
     (deps.repairSystemd ?? installSystemd)();
     return;
   }
@@ -4090,7 +4195,10 @@ export function systemdServiceInstallCleanupOps(deps: {
 
 function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
   if (process.platform === "darwin")
-    return { install: installLaunchd, start: startLaunchd, stop: stopLaunchd, status: statusLaunchd, uninstall: uninstallLaunchd };
+    // Wrapped, not passed: `installLaunchd` reports whether it reloaded launchd, and only
+    // `repairService` (for the `restart` verb) has any use for that. `ServiceOps.install` is
+    // the generic install seam and deliberately promises nothing about a return value.
+    return { install: () => { installLaunchd(); }, start: startLaunchd, stop: stopLaunchd, status: statusLaunchd, uninstall: uninstallLaunchd };
   if (process.platform === "win32") {
     if (backend === "native")
       return { install: installWindowsNative, start: startWinswService, stop: stopWinswService, status: winswStatusSummary, uninstall: uninstallWinswService };
@@ -4985,8 +5093,18 @@ export async function serviceStatusReport(
     + "   Meanwhile: ocx start           (serves in the foreground)";
 }
 
+/**
+ * `restart` is NO LONGER folded into `repair`.
+ *
+ * It used to be, and on macOS that made it a lie: `repair` now returns early when the plist
+ * is already current and the job is loaded from it (#4236), so `ocx service restart` of a
+ * healthy service restarted nothing and the operator had to run `launchctl kickstart -k` by
+ * hand. The two verbs share the whole repair path and diverge only in `repairService`, which
+ * kicks the launchd job the no-op left running. A BARE `ocx service` still maps to `repair`
+ * (see {@link selectServiceSubcommand}): it is an idempotent "make it current", not a
+ * request to bounce a healthy hub.
+ */
 export function normalizeServiceSubcommand(sub?: string): string {
-  if (sub === "restart") return "repair";
   return sub ?? "install";
 }
 
@@ -5145,7 +5263,8 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       process.exit(1);
     }
     const { parsed, command } = plan;
-  if (command === "repair") {
+  if (command === "repair" || command === "restart") {
+    const verb: ServiceRepairVerb = command === "restart" ? "restart" : "repair";
     assertServiceEnvironmentMatchesInstall();
     assertServiceAuthEnvironment();
     // A throw used to escape straight to the top level, so the one command that can
@@ -5156,17 +5275,17 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     // both halves of that answer, and the exit code stays non-zero either way.
     let repairError: unknown;
     try {
-      await repairService();
+      await repairService({ verb });
     } catch (error) {
       repairError = error;
-      console.error(`❌ Service repair failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.error(`❌ Service ${verb} failed: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;
     }
     // All three platforms: a repair that reports success while nothing serves is the
     // defect class this unit exists to close. Windows bakes its port into the
     // scheduler wrapper or the WinSW XML, both of which installedServiceListenPort()
     // now reads.
-    await reportServiceServing("repaired");
+    await reportServiceServing(verb === "restart" ? "restarted" : "repaired");
     if (repairError !== undefined) process.exitCode = 1;
     return;
   }
@@ -5307,8 +5426,8 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     default:
       console.error("Usage: ocx service [install|repair|restart|start|stop|status|uninstall|remove] [--native|--scheduler]");
       console.error("       With no subcommand, installs when absent or repairs/restarts an existing service.");
-      console.error("       repair: refresh and restart the installed backend; stale Windows tasks may request admin approval.");
-      console.error("       restart: alias of repair.");
+      console.error("       repair: refresh the installed backend, reloading it only when the definition changed; stale Windows tasks may request admin approval.");
+      console.error("       restart: the same refresh, but always restarts the service — on macOS a healthy job is kickstarted in place.");
       console.error("       --native (Windows only): register a real SCM service via WinSW instead of Task Scheduler.");
       process.exit(1);
   }
diff --git a/tests/cli/cli-version-skew.test.ts b/tests/cli/cli-version-skew.test.ts
index 36fb6845f9..212c169524 100644
--- a/tests/cli/cli-version-skew.test.ts
+++ b/tests/cli/cli-version-skew.test.ts
@@ -27,7 +27,7 @@ describe("version skew detection", () => {
       skewed: true,
       warning: "CLI 2.42.0 does not match the running proxy 2.10.1-preview.20260805 — "
         + "the running proxy is older than this CLI. Restart the proxy using the intended current installation. "
-        + "For a background service, run ocx service repair (ocx service restart is an alias).",
+        + "For a background service, run ocx service restart (repair reloads only a changed definition).",
     });
     expect(skew.warning).not.toContain("this ocx on PATH is older");
   });
diff --git a/tests/service/launchd-repair.test.ts b/tests/service/launchd-repair.test.ts
index c1b27bf69e..4cbd70cc41 100644
--- a/tests/service/launchd-repair.test.ts
+++ b/tests/service/launchd-repair.test.ts
@@ -32,12 +32,19 @@ import {
   installLaunchd,
   launchdEvictionTargets,
   probeLaunchdLoadState,
+  repairService,
   resolvedProxyEnv,
+  restartLaunchdJob,
   reusePreviousPlistPathVariable,
   runLaunchctl,
   stableLauncherEntry,
 } from "../../src/service";
-import type { LaunchdLoadProbe, LaunchdLoadState } from "../../src/service";
+import type {
+  LaunchdLoadProbe,
+  LaunchdLoadState,
+  ServiceDiagnostic,
+  ServiceRepairVerb,
+} from "../../src/service";
 import { protectedLaunchAgentsDirForTests } from "../../src/lib/test-home-guard";
 import { repoPath } from "../helpers/repo-root";
 
@@ -138,6 +145,19 @@ function renderedPlist(): string {
   return buildPlist(resolvedProxyEnv(), { launcher: stableLauncherEntry() });
 }
 
+/** Collect `console.log` lines for the one case whose contract IS the printed line. */
+function captureLog(body: () => void): string[] {
+  const lines: string[] = [];
+  const previous = console.log;
+  console.log = (...parts: unknown[]) => { lines.push(parts.join(" ")); };
+  try {
+    body();
+  } finally {
+    console.log = previous;
+  }
+  return lines;
+}
+
 describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () => {
   test("a healthy job loaded from a byte-identical plist is a no-op — launchd is never touched", () => {
     const plistPath = fixturePlist();
@@ -593,6 +613,186 @@ describe("installLaunchd: repair must not be an outage (#4236 defect 1)", () =>
   });
 });
 
+/**
+ * The other half of the no-op (#4249).
+ *
+ * `ocx service restart` runs the repair path, so once `installLaunchd` learned to return
+ * early on a healthy loaded-current job, `restart` of a healthy service restarted NOTHING —
+ * and the operator documentation had to tell people to run
+ * `launchctl kickstart -k gui/$(id -u)/com.opencodex.proxy` by hand. `repair` keeps the
+ * no-op (repairing a healthy service must not be an outage); only `restart` kicks.
+ *
+ * `restartLaunchd` is injected in every case here. Its default is the real
+ * `restartLaunchdJob`, which would kickstart the live hub on this machine.
+ */
+describe("restart restarts, repair stays a no-op (#4249)", () => {
+  const healthyDiag: ServiceDiagnostic = {
+    supported: true,
+    installed: true,
+    enabled: true,
+    running: true,
+    viable: true,
+    startable: false,
+    stale: false,
+    conflict: false,
+    backend: "launchd",
+    summary: "installed and loaded (launchd; gui/501)",
+  };
+
+  /**
+   * Every `repairService` seam a darwin case can reach, owned by the case. `restartLaunchd`
+   * records the call AND runs the real `restartLaunchdJob` over the same scripted launchctl,
+   * so the argv assertions below cover the verb it actually spawns.
+   */
+  function darwinDeps(
+    verb: ServiceRepairVerb,
+    plistPath: string,
+    launchctl: typeof runLaunchctl,
+    probe: typeof probeLaunchdLoadState,
+    restarts: string[],
+  ) {
+    return {
+      platform: "darwin" as const,
+      verb,
+      diagnose: () => healthyDiag,
+      assertEnv: () => {},
+      assertAuth: () => {},
+      repairLaunchd: () => installLaunchd({ launchctl, plistPath, probe, sleepSync: () => {} }),
+      restartLaunchd: () => {
+        restarts.push("restart");
+        restartLaunchdJob({ launchctl, probe });
+      },
+    };
+  }
+
+  test("restart of a healthy loaded-current job kickstarts the gui domain and never boots it out", async () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, renderedPlist(), "utf8");
+    const { argv, launchctl } = recordingLaunchctl({});
+    const restarts: string[] = [];
+
+    await repairService(darwinDeps("restart", plistPath, launchctl, loadedCurrent().probe, restarts));
+
+    expect(restarts).toEqual(["restart"]);
+    // THE fix: one verb, and it is not an eviction. `kickstart -k` restarts what the domain
+    // already holds, so the listener never goes away.
+    expect(verbs(argv)).toEqual(["kickstart"]);
+    expect(argv[0]?.slice(1, 2)).toEqual(["-k"]);
+    expect(argv[0]?.[2]).toMatch(/^gui\/\d+\/com\.opencodex\.proxy$/);
+    expect(verbs(argv)).not.toContain("bootout");
+    expect(verbs(argv)).not.toContain("bootstrap");
+    // The definition was never rewritten, so there is nothing to roll back.
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
+  });
+
+  test("repair of the very same state restarts nothing at all", async () => {
+    const plistPath = fixturePlist();
+    writeFileSync(plistPath, renderedPlist(), "utf8");
+    const { argv, launchctl } = recordingLaunchctl({});
+    const restarts: string[] = [];
+
+    await repairService(darwinDeps("repair", plistPath, launchctl, loadedCurrent().probe, restarts));
+
+    // A repair of a healthy hub is still zero launchctl calls — the #4236 property. Only the
+    // restart verb may cost the operator a process.
+    expect(argv).toEqual([]);
+    expect(restarts).toEqual([]);
+  });
+
+  test("restart of a job that is NOT loaded takes the ordinary bootstrap path, with no kickstart", async () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+    const restarts: string[] = [];
+
+    await repairService(darwinDeps(
+      "restart",
+      plistPath,
+      launchctl,
+      // Pre-check: absent. Verification after the bootstrap: loaded.
+      scriptedProbe("not-loaded", "loaded-current").probe,
+      restarts,
+    ));
+
+    // The install path already started a NEW process, so kicking it again would be a second
+    // restart of a job that is one second old. (`print` is the settle probe between the two
+    // evictions and the bootstrap.)
+    expect(verbs(argv)).toEqual(["bootout", "print", "bootout", "print", "bootstrap"]);
+    expect(verbs(argv)).not.toContain("kickstart");
+    expect(restarts).toEqual([]);
+  });
+
+  test("installLaunchd reports which path it took, because that is the only way to know", () => {
+    const noop = fixturePlist();
+    writeFileSync(noop, renderedPlist(), "utf8");
+    expect(installLaunchd({
+      launchctl: recordingLaunchctl({}).launchctl,
+      plistPath: noop,
+      probe: loadedCurrent().probe,
+      sleepSync: () => {},
+    })).toEqual({ reloaded: false });
+
+    const reloaded = fixturePlist();
+    expect(installLaunchd({
+      launchctl: recordingLaunchctl({ bootstrap: [ok()] }).launchctl,
+      plistPath: reloaded,
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
+      sleepSync: () => {},
+    })).toEqual({ reloaded: true });
+  });
+
+  test("restartLaunchdJob verifies with the probe and says what it ran", () => {
+    const { argv, launchctl } = recordingLaunchctl({});
+    const logged = captureLog(() => restartLaunchdJob({ launchctl, probe: loadedCurrent().probe }));
+
+    expect(verbs(argv)).toEqual(["kickstart"]);
+    // One line, naming the exact command, so an operator reading the output can repeat it.
+    expect(logged).toHaveLength(1);
+    expect(logged[0]).toContain("service restarted (launchctl kickstart -k gui/");
+    expect(logged[0]).toContain("/com.opencodex.proxy)");
+  });
+
+  test("a kickstart whose job is gone afterwards throws instead of claiming a restart", () => {
+    const { launchctl } = recordingLaunchctl({ kickstart: fail(113, "Could not find service") });
+
+    expect(() => restartLaunchdJob({ launchctl, probe: scriptedProbe("not-loaded").probe }))
+      .toThrow(/could not restart com\.opencodex\.proxy[\s\S]*NOT loaded[\s\S]*kickstart -k gui\//);
+  });
+
+  test("an unverifiable state after the kick warns — a probe that cannot answer is not a failure", () => {
+    const { launchctl } = recordingLaunchctl({});
+    const warned: string[] = [];
+    const previous = console.warn;
+    console.warn = (...parts: unknown[]) => { warned.push(parts.join(" ")); };
+    try {
+      // `unknown` is never evidence: EPERM from a non-Aqua context says nothing about the job.
+      restartLaunchdJob({
+        launchctl,
+        probe: scriptedProbe({ state: "unknown", detail: "launchctl could not be run" }).probe,
+      });
+    } finally {
+      console.warn = previous;
+    }
+    expect(warned).toHaveLength(1);
+    expect(warned[0]).toContain("could not be verified");
+  });
+
+  test("the kick is wired to the restart verb only, and defaults to the real job restarter", () => {
+    const source = readFileSync(repoPath("src", "service.ts"), "utf8");
+    const branch = source.slice(
+      source.indexOf('if (platform === "darwin") {', source.indexOf("export async function repairService(")),
+      source.indexOf("throw new Error(`Background service repair is unsupported"),
+    );
+    expect(branch).toContain("const outcome = (deps.repairLaunchd ?? installLaunchd)();");
+    expect(branch).toContain('if ((deps.verb ?? "repair") === "restart" && outcome?.reloaded === false) {');
+    expect(branch).toContain("(deps.restartLaunchd ?? restartLaunchdJob)();");
+    // Linux needs no equivalent: `installSystemd` ends in an unconditional restart, so the
+    // systemd unit is bounced whichever verb asked. Windows stops and starts the task.
+    expect(branch).toContain("(deps.repairSystemd ?? installSystemd)();");
+    expect(source.slice(source.indexOf("function installSystemd()"), source.indexOf("function startSystemd()")))
+      .toContain("sh(`systemctl --user restart ${TASK}`);");
+  });
+});
+
 describe("reusePreviousPlistPathVariable: PATH is the one difference repair may ignore", () => {
   const plist = (path: string, port = 10100): string =>
     `<dict>\n  <key>PATH</key><string>${path}</string>\n  <key>Port</key><string>${port}</string>\n</dict>\n`;
@@ -781,16 +981,16 @@ describe("the surfaces around the repair (#4236 defects 1f, 1h, 2)", () => {
   }
 
   test("the repair branch still reports serving when repairService throws (1f)", () => {
-    const branch = slice('if (command === "repair") {', "// Non-install subcommands follow");
+    const branch = slice('if (command === "repair" || command === "restart") {', "// Non-install subcommands follow");
     // Without the catch, a throw escaped through src/cli/dispatch.ts to the top level and
     // the one command that can evict a hub never reached its own serving check.
     expect(branch).toContain("try {");
-    expect(branch).toContain("await repairService();");
+    expect(branch).toContain("await repairService({ verb });");
     expect(branch).toContain("} catch (error) {");
-    expect(branch).toContain('await reportServiceServing("repaired");');
+    expect(branch).toContain('await reportServiceServing(verb === "restart" ? "restarted" : "repaired");');
     expect(branch).toContain("process.exitCode = 1;");
     // The serving check must not be inside the try, or a throw would still skip it.
-    expect(branch.indexOf("} catch (error) {")).toBeLessThan(branch.indexOf('reportServiceServing("repaired")'));
+    expect(branch.indexOf("} catch (error) {")).toBeLessThan(branch.indexOf("reportServiceServing(verb ==="));
   });
 
   test("install cleanup uses the same probe and the modern evict verb (1h, 2)", () => {
diff --git a/tests/service/service.test.ts b/tests/service/service.test.ts
index 46ead91c47..f15a243e4d 100644
--- a/tests/service/service.test.ts
+++ b/tests/service/service.test.ts
@@ -242,7 +242,11 @@ describe("systemd service unit", () => {
 
   test("bare service installs only when absent and otherwise selects no-admin repair", async () => {
     expect(normalizeServiceSubcommand()).toBe("install");
-    expect(normalizeServiceSubcommand("restart")).toBe("repair");
+    // `restart` is NOT folded into `repair` any more (#4249). It shares the whole repair path
+    // and diverges only in `repairService`, which kickstarts the macOS job that repair's
+    // no-op deliberately leaves running — collapsing the verbs here made `ocx service
+    // restart` of a healthy service restart nothing.
+    expect(normalizeServiceSubcommand("restart")).toBe("restart");
     expect(normalizeServiceSubcommand("start")).toBe("start");
     expect(normalizeServiceSubcommand("nope")).toBe("nope");
 
@@ -289,11 +293,31 @@ describe("systemd service unit", () => {
     expect(explicitInstall).toMatchObject({ ok: true, command: "install" });
     expect(probes).toBe(0);
 
+    // An explicit `restart` survives planning as itself, and like every explicit subcommand
+    // it never probes for installation. A BARE invocation still chooses `repair`: it is an
+    // idempotent "make it current", not a request to bounce a healthy hub.
+    probes = 0;
+    const explicitRestart = planServiceCommand(["restart"], {
+      probeInstallation: () => { probes += 1; return { state: "installed" }; },
+    });
+    expect(explicitRestart).toMatchObject({ ok: true, command: "restart" });
+    expect(probes).toBe(0);
+    expect(selectServiceSubcommand(parseServiceArgs(["restart"]), {
+      hasExplicitSubcommand: true,
+      installed: true,
+    })).toBe("restart");
+
     const service = await readText("src/service.ts");
     const serviceCommand = service.slice(service.indexOf("export async function serviceCommand"));
     expect(serviceCommand).toContain("const plan = planServiceCommand(filteredArgs);");
     expect(serviceCommand).toContain("const { parsed, command } = plan;");
     expect(serviceCommand).toContain("switch (command)");
+    // Both verbs enter the shared repair branch, which hands the distinction to
+    // `repairService` rather than dispatching twice. Without the second half of the
+    // condition, `restart` would fall through to the usage error.
+    expect(serviceCommand).toContain('if (command === "repair" || command === "restart") {');
+    expect(serviceCommand).toContain('const verb: ServiceRepairVerb = command === "restart" ? "restart" : "repair";');
+    expect(serviceCommand).toContain("await repairService({ verb });");
   });
 
   test("Windows install presence distinguishes unknown queries from proven absence", () => {

From 8e669ec42b15792b6abb7e3417d7195c9008fe4a Mon Sep 17 00:00:00 2001
From: bitkyc08-arch <bitkyc08@gmail.com>
Date: Fri, 11 Sep 2026 12:43:22 +0900
Subject: [PATCH 9/9] test(service,doctor): restart is its own verb and the
 skew advice names it

Two cases still pinned the old alias: the service parser expected restart to parse as repair,
and the doctor skew projection expected the repair advice that version-skew.ts stopped emitting.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/codex-integration/doctor.test.ts | 4 +++-
 tests/service/winsw.test.ts            | 6 ++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/tests/codex-integration/doctor.test.ts b/tests/codex-integration/doctor.test.ts
index 3f52ea4e45..56ad8c1a96 100644
--- a/tests/codex-integration/doctor.test.ts
+++ b/tests/codex-integration/doctor.test.ts
@@ -865,7 +865,9 @@ describe("doctor version skew projection", () => {
       if (expected !== null) expect(output).toContain(expected);
       else expect(output).not.toContain("does not match the running proxy");
       if (cli !== "2.43.0" || proxy !== "2.43.0") expect(output).not.toContain("matches the running proxy");
-      if (expected === "the running proxy is older") expect(output).toContain("ocx service repair");
+      // A version skew leaves the service definition byte-identical, so `repair` would no-op over the
+      // old process; the advice names `restart`, which kickstarts an unchanged job.
+      if (expected === "the running proxy is older") expect(output).toContain("ocx service restart");
     } finally {
       for (const cleanup of restore.reverse()) cleanup();
       process.exitCode = previousExitCode;
diff --git a/tests/service/winsw.test.ts b/tests/service/winsw.test.ts
index 3366c6cbc3..5c72052e6b 100644
--- a/tests/service/winsw.test.ts
+++ b/tests/service/winsw.test.ts
@@ -235,8 +235,10 @@ describe("service backend CLI parsing", () => {
     expect(parseServiceArgs([])).toEqual({ sub: "install", backend: null, invalid: [] });
   });
 
-  test("restart aliases the existing no-admin repair path", () => {
-    expect(parseServiceArgs(["restart"])).toEqual({ sub: "repair", backend: null, invalid: [] });
+  test("restart is its own verb: parsed like repair, no backend flag, no admin path", () => {
+    // `restart` used to alias `repair`; since repair became a no-op on a healthy launchd job,
+    // `restart` carries its own verb so the darwin path can kickstart the unchanged job.
+    expect(parseServiceArgs(["restart"])).toEqual({ sub: "restart", backend: null, invalid: [] });
   });
 
   test("--scheduler and unknown flags are recognized separately", () => {