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..15d88e421d
--- /dev/null
+++ b/devlog/_plan/260911_hub_single_port/010_launchd_repair.md
@@ -0,0 +1,421 @@
+# 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.
+
+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
+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, 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
+   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 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. 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` (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
+`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` 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.
+
+### 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.
+
+- **`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.
+
+  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.
+
+## 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.
+- **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
+
+`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
+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 `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.
+
+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()
+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
+                                                     → 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: 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 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 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.
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/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/lib/test-home-guard.ts b/src/lib/test-home-guard.ts
index 493e7f8297..0c1a0ad715 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 {
@@ -76,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.
  *
@@ -94,6 +121,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..1a678e7438 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, isProtectedHomeUnderTest, isTestHomeGuardArmed } from "./lib/test-home-guard";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -98,11 +98,27 @@ 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.
+ *
+ * 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;
   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 +130,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 +181,44 @@ 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.
+   *
+   * 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.
+   */
+  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 {
@@ -254,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 });
@@ -537,9 +592,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">
@@ -564,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, "'\\''")}'`;
 }
@@ -604,6 +697,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
@@ -788,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();
@@ -991,6 +1101,140 @@ 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;
+
+/**
+ * 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.
+ *
+ * - `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 +2582,32 @@ 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;
+  }
+}
+
+/**
+ * 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. 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,66 +2616,325 @@ 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.
+ * `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. 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. 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` 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 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 } = {}): void {
+export function installLaunchd(deps: {
+  launchctl?: typeof runLaunchctl;
+  probe?: typeof probeLaunchdLoadState;
+  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;
+} = {}): LaunchdInstallOutcome {
   const run = deps.launchctl ?? runLaunchctl;
-  const dir = join(homedir(), "Library", "LaunchAgents");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
-  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
-  writeServiceApiTokenFile();
-  const p = plistPath();
+  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);
   // 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;
   // 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.
+  // 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 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.");
+    // 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) {
+    // 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.
-    run(["bootout", bootoutTarget]);
-    loaded = run(["load", "-w", p]);
-  }
-  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.
+  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 evictThenBootstrap = (): { ok: boolean; stdout: string; stderr: string; status: number | null } => {
+    evictEveryDomain();
+    return run(["bootstrap", guiDomain, p]);
+  };
+
+  let loaded = evictThenBootstrap();
+  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)) {
+      // "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 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 = 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
+      // 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();
+      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 { reloaded: true };
+  }
+
+  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");
+        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 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 ${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 ${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 */ } }
+  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`
@@ -2445,12 +2971,60 @@ 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, 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 {
+    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 */ }
+}
+
+/**
+ * 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 */ } }
 }
 
 /**
@@ -2928,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;
@@ -2938,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. */
@@ -3212,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;
   }
@@ -3596,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 };
@@ -3628,11 +4230,29 @@ 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. 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: () => {
+        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)}`}`);
+        }
       },
-      stop: () => { sh(`launchctl unload "${plistPath()}"`); },
     };
   }
   if (process.platform === "win32") {
@@ -4310,6 +4930,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 +4994,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();
@@ -4419,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";
 }
 
@@ -4579,15 +5263,30 @@ 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();
-    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({ verb });
+    } catch (error) {
+      repairError = 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;
   }
   // Non-install subcommands follow the backend recorded at install time (state v2).
@@ -4727,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/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/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..4cbd70cc41
--- /dev/null
+++ b/tests/service/launchd-repair.test.ts
@@ -0,0 +1,1093 @@
+/**
+ * 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 { 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";
+import {
+  buildPlist,
+  deriveLaunchdServiceDiagnostic,
+  installLaunchd,
+  launchdEvictionTargets,
+  probeLaunchdLoadState,
+  repairService,
+  resolvedProxyEnv,
+  restartLaunchdJob,
+  reusePreviousPlistPathVariable,
+  runLaunchctl,
+  stableLauncherEntry,
+} 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";
+
+/**
+ * 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.
+ *
+ * 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 };
+
+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 {@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");
+}
+
+/** The plist `installLaunchd` will render in this process, for the byte-identical case. */
+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();
+    writeFileSync(plistPath, renderedPlist(), "utf8");
+    const { argv, launchctl } = recordingLaunchctl({});
+
+    installLaunchd({ launchctl, plistPath, probe: loadedCurrent().probe, 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);
+  });
+
+  /**
+   * 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");
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // First answer is the no-op pre-check (stale ⇒ do the repair); the second is the
+      // post-bootstrap verification.
+      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 in BOTH domains, not legacy load -w", () => {
+    const plistPath = fixturePlist();
+    const { argv, launchctl } = recordingLaunchctl({ bootstrap: [ok()] });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
+      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);
+    // 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"));
+  });
+
+  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,
+      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); },
+    });
+
+    expect(delays).toEqual([]);
+    expect(verbs(argv)).toEqual(["bootout", "bootout", "bootstrap"]);
+  });
+
+  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,
+      probe: scriptedProbe("not-loaded").probe,
+      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();
+    // 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")],
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // 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: () => {},
+    });
+
+    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);
+  });
+
+  /**
+   * 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
+   * `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();
+    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'),
+    });
+
+    installLaunchd({
+      launchctl,
+      plistPath,
+      // 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", "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$/);
+  });
+
+  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,
+      probe: scriptedProbe("not-loaded", "loaded-current").probe,
+      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,
+      probe: scriptedProbe("not-loaded").probe,
+      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,
+        probe: scriptedProbe("not-loaded").probe,
+        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);
+  });
+
+  /**
+   * 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()] });
+
+    expect(() => installLaunchd({
+      launchctl,
+      plistPath,
+      probe: scriptedProbe("not-loaded").probe,
+      sleepSync: () => {},
+    })).toThrow(/ocx service install/);
+
+    expect(existsSync(`${plistPath}.prev`)).toBe(false);
+    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,
+      probe: loadedCurrent().probe,
+      sleepSync: () => {},
+    })).toThrow(/real LaunchAgents directory/);
+  });
+});
+
+/**
+ * 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`;
+
+  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}`);
+
+  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" || 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({ verb });");
+    expect(branch).toContain("} catch (error) {");
+    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(verb ==="));
+  });
+
+  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"');
+    // 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)", () => {
+    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("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 e6362201c8..f15a243e4d 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,9 +173,80 @@ 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);
+  });
+
+  /**
+   * 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");
+    // `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");
 
@@ -216,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", () => {
@@ -3328,141 +3425,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"]);
-    });
-  });
 });
 
 /**
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", () => {