lidge-jun · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026 · coderabbitai
@@ -13,7 +13,7 @@ import { probeSpawn, probeSpawnSync } from "../src/update/mutation-guard.mjs";
 import { createSupervisionLatch, inspectDesktopSupervision } from "../src/service/desktop-supervision.mjs";
 import { planDesktopCliHandoff, runDesktopCliHandoff } from "../src/lib/desktop-cli-handoff.mjs";
 import { forwardLauncherSignals } from "../src/lib/launcher-signal-forwarding.mjs";
-import { acquireSyncGuard } from "../src/update/sync-update-mutex.mjs";
+import { acquireSyncGuard, staleUpdateMarkerHint } from "../src/update/sync-update-mutex.mjs";
 import { desktopCliRecordPath } from "../src/lib/desktop-cli-record.mjs";
 import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../src/update/stop-contract.mjs";
 import { probeProxyLiveness } from "../src/update/proxy-liveness-probe.mjs";
@@ -275,7 +275,11 @@ async function runPackageManagerSelfUpdate(manager, child) {
   } else {
     session = createLegacyUpdateSession({ home: configDir() });
     const started = session.start();
-    if (!started.ok) { console.error(`opencodex: ${started.error}`); process.exit(1); }
+    if (!started.ok) {
+      console.error(`opencodex: ${started.error}`);
+      if (started.staleMarker) for (const line of staleUpdateMarkerHint(configDir())) console.error(line);
+      process.exit(1);
+    }
     process.once("exit", () => {
       try { if (enteredMutation) session.finish(childOutcome); else session.finishPreflight(); }
       catch (error) { console.error(`Update outcome write failed: ${error?.message ?? error}`); process.exitCode = 1; }

@@ -626,7 +626,7 @@ skipped as `child-busy`. The Child's pinned sync may still restart its own OpenC
 after applying changed Home settings. If the Home times out and stops its local SSH process, a remote
 sync already running may continue on the Child.
 
-If an update is in flight or the shared update/sync mutex cannot be determined, sync changes nothing, reports `update-in-flight`, and exits 7. If another sync holds the mutex, it reports `sync-in-progress` and exits 1; a Home counts that Child as failed and exits 6 when its own sync succeeded. With `--json`, either refusal prints one result document with the Home skipped and the refusal reason in `fanout.reason`.
+If an update is in flight or the shared update/sync mutex cannot be determined, sync changes nothing, reports `update-in-flight`, and exits 7. When a marker left by an interrupted update in OpenCodex 2.100.x or earlier causes the refusal, stderr also names the marker and its recovery; see [Update Failed](/troubleshooting/update-failed/#if-every-update-and-sync-says-update-in-flight). If another sync holds the mutex, it reports `sync-in-progress` and exits 1; a Home counts that Child as failed and exits 6 when its own sync succeeded. With `--json`, either refusal prints one result document with the Home skipped and the refusal reason in `fanout.reason`.
 
 An explicitly requested restart also runs after a successful committed `config.toml` change, even if the catalog and cache bytes are unchanged. A configuration-only no-op, refusal, preflight, or rolled-back write does not trigger it. Without a restart flag, sync never automatically restarts Codex.
 

@@ -74,6 +74,45 @@ bildirir. Yalnızca içinden OpenCodex işlemi çalışmadığını doğruladık
 Bir klasör silinemiyorsa içinden çalışan işlem kalmış olabilir. Windows oturumunu
 kapatmak veya yeniden başlatmak kilidi serbest bırakır.
 
+## Her güncelleme ve senkronizasyon update-in-flight diyorsa
+
+Beklemeye, servisi yeniden başlatmaya veya bilgisayarı yeniden başlatmaya rağmen her `ocx update` ve
+`ocx sync` `update-in-flight` ile başarısız oluyorsa, yarıda kalan bir güncelleme işaret dosyasını
+geride bırakmış olabilir ([#8524](https://github.com/lidge-jun/opencodex/issues/8524)). Bu dosya
+OpenCodex ana dizinindeki `update-orchestrated.json` dosyasıdır (Windows'ta
+`%USERPROFILE%\.opencodex`, diğer sistemlerde `~/.opencodex`).
+
+Güncel sürümler Windows yükleyicisinin denetleyici sürecini bu dosyaya kaydeder. Dosya, 15 dakikalık
+koruma süresi dolduğunda ve o denetleyici ile başlatıcı kapandığında kendiliğinden temizlenir.
+2.100.x ve öncesi sürümler denetleyiciyi kaydetmiyordu. Bu sürümlerin yarıda kalan bir güncellemeden
+(kapatılan konsol, Ctrl+C, Görev Yöneticisi, uyku veya elektrik kesintisi) sonra bıraktığı dosya
+denetlenemez ve hiçbir zaman kendiliğinden temizlenmez. Neden buysa, terminaldeki `ocx update` ve
+`ocx sync` `update-in-flight` satırından sonra dosyanın yolunu ve yeniden adlandırma komutunu yazar.
+Pano, Desktop ve Remote Link yalnızca `update-in-flight` bildirir; yönergeyi görmek için
+`ocx update` komutunu bir terminalde çalıştırın.
+
+Dosyayı yeniden adlandırmadan önce hiçbir güncellemenin çalışmadığından emin olun:
+
+1. Başka bir pencerede `ocx update` veya pano güncellemesi sürmüyor.
+2. Hiçbir `npm`, `pnpm` veya `bun` genel kurulumu çalışmıyor. Windows'ta Görev Yöneticisi'nde npm çalıştıran
+   `node.exe` ve komut satırında `npm-install-job.ps1` geçen bir `powershell.exe` olup olmadığına bakın.
+3. Ardından dosyayı yeniden adlandırın (bir kopya kalır) ve `ocx update` komutunu yeniden çalıştırın:
+
+   ```bat
+   ren "%USERPROFILE%\.opencodex\update-orchestrated.json" update-orchestrated.json.stale
+   ```
+
+   ```bash
+   mv -n ~/.opencodex/update-orchestrated.json ~/.opencodex/update-orchestrated.json.stale
+   ```
+
+`OPENCODEX_HOME` başka bir yeri gösteriyorsa hata mesajının yazdığı yolu kullanın. Bu yol bir kabuğun
+genişletebileceği veya yorumlayabileceği karakterler ya da Windows'ta düz ASCII dışında karakterler içeriyorsa hata
+mesajı komut vermeden yalnızca dosyayı adlandırır; dosyayı elle
+yeniden adlandırın. Koruma süresi
+dolmamış ya da kaydedilen süreci hâlâ çalışan bir dosya bu yönergeyi yazdırmaz; bu durumda bekleyin
+veya çalışan güncellemenin bitmesine izin verin.
+
 ## Güncelleme UNSUPERVISED proxy bildiriyorsa
 
 Güncellemeden sonra arka plan servisi yenilenemediğinde güncelleyici önce mevcut

@@ -50,7 +50,7 @@ service. It does not continue extracting into a deleted stage after recovery sta
 
 If installer exit cannot be confirmed, the update fails and keeps the staging folder and
 its ownership marker. Confirm that no installer or OpenCodex process runs from that folder
-before removing it. A retained folder does not prevent another update attempt.
+before removing it. A retained folder does not prevent another update attempt; a leftover update marker can, see [If every update and sync says update-in-flight](#if-every-update-and-sync-says-update-in-flight).
 
 Check your registry connection if the install repeatedly exceeds the budget, then retry
 `ocx update`. Increasing the budget is not needed to clean up a timed-out install safely.
@@ -98,6 +98,43 @@ ownership marker. Delete a leftover only after confirming that no OpenCodex proc
 If a folder will not delete, a process is still running from it. Signing out or restarting Windows
 releases the lock.
 
+## If every update and sync says update-in-flight
+
+If every `ocx update` and `ocx sync` fails with `update-in-flight`, even after waiting, restarting
+the service or rebooting, an interrupted update may have left its marker behind
+([#8524](https://github.com/lidge-jun/opencodex/issues/8524)). The marker is
+`update-orchestrated.json` in the OpenCodex home (`%USERPROFILE%\.opencodex` on Windows,
+`~/.opencodex` elsewhere).
+
+Current releases record the Windows installer's supervisor in the marker. The marker then clears
+by itself once the 15-minute fence has passed and that supervisor and the launcher are gone.
+Releases up to 2.100.x did not record the supervisor. A marker they left after an interrupted
+update (a closed console, Ctrl+C, Task Manager, sleep or power loss) cannot be checked, so it never
+clears by itself. When that is the cause, `ocx update` and `ocx sync` in a terminal print the
+marker's path and the rename command after `update-in-flight`. The dashboard, Desktop and Remote
+Link only report `update-in-flight`, so run `ocx update` in a terminal to see the guidance.
+
+Before you rename the marker, make sure no update is running:
+
+1. No `ocx update` or dashboard update is in progress in another window.
+2. No `npm`, `pnpm` or `bun` global install is running. On Windows, check Task Manager for
+   `node.exe` running npm and for a `powershell.exe` whose command line contains `npm-install-job.ps1`.
+3. Then rename the marker (renaming keeps a copy) and run `ocx update` again:
+
+   ```bat
+   ren "%USERPROFILE%\.opencodex\update-orchestrated.json" update-orchestrated.json.stale
+   ```
+
+   ```bash
+   mv -n ~/.opencodex/update-orchestrated.json ~/.opencodex/update-orchestrated.json.stale
+   ```
+
+Use the exact path the error prints if `OPENCODEX_HOME` points somewhere else. If that path contains
+characters a shell could expand or interpret, or on Windows anything other than plain ASCII, the error names the file
+without a command; rename it by hand. A marker that is
+still inside its fence, or whose recorded process is still running, does not print this guidance.
+In that case, wait or let the running update finish.
+
 ## If the update reports an UNSUPERVISED proxy
 
 When the background service cannot be refreshed after an update, the updater first asks launchd

@@ -1,5 +1,5 @@
 import { getConfigDir } from "../config/paths";
-import { acquireSyncGuard, inspectUpdateMarker, inspectUpdateSyncMutex, parentHoldsSyncMutex, refuseSync } from "../update/sync-update-mutex";
+import { acquireSyncGuard, inspectUpdateMarker, inspectUpdateSyncMutex, parentHoldsSyncMutex, refuseSync, staleUpdateMarkerHint } from "../update/sync-update-mutex";
 
 /** Hold the home-scoped update/sync mutex until the complete sync operation settles. */
 export async function withSyncUpdateGuard(run: () => Promise<number>, args: readonly string[] = []): Promise<number> {
@@ -9,7 +9,12 @@ export async function withSyncUpdateGuard(run: () => Promise<number>, args: read
     while (!parentHoldsSyncMutex(home) && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 20));
     if (!parentHoldsSyncMutex(home)) return refuseSync(inspectUpdateSyncMutex(home) === "sync" ? "sync-in-progress" : "update-in-flight", args);
   }
-  if (parentHoldsSyncMutex(home)) return inspectUpdateMarker(home) === "free" ? await run() : refuseSync("update-in-flight", args);
+  if (parentHoldsSyncMutex(home)) {
+    const detail: { witnessless?: boolean } = {};
+    return inspectUpdateMarker(home, { detail }) === "free"
+      ? await run()
+      : refuseSync("update-in-flight", args, detail.witnessless ? staleUpdateMarkerHint(home) : []);
+  }
   const lease = acquireSyncGuard(home, args);
   if (lease.kind === "refused") return lease.exit;
   try {

@@ -48,6 +48,7 @@ import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { createLegacyUpdateSession, createOrchestratedChildSession, decodeOrchestratedExpect } from "./orchestrated-session.mjs";
 import { runPosixInstallerSync } from "./posix-install-supervisor.mjs";
 import { runWindowsInstallerSync } from "./npm-install.mjs";
+import { staleUpdateMarkerHint } from "./sync-update-mutex.mjs";
 import { protectOrchestratedWorkerSignals } from "./orchestrated-child.mjs";
 import type { OrchestratedChildArgs } from "./orchestrated-arguments.mjs";
 import { PNPM_READ_CWD, withPnpmCommandCwd, pnpmReadEnvironment } from "./pnpm-read-policy.mjs";
@@ -473,7 +474,12 @@ export async function runUpdate(child?: Extract<OrchestratedChildArgs, { ok: tru
   } else {
     session = createLegacyUpdateSession({ home: getConfigDir() });
     const started = session.start();
-    if (!started.ok) { console.error(`opencodex: ${started.error}`); process.exitCode = 1; return; }
+    if (!started.ok) {
+      console.error(`opencodex: ${started.error}`);
+      if (started.staleMarker) for (const line of staleUpdateMarkerHint(getConfigDir())) console.error(line);
+      process.exitCode = 1;
+      return;
+    }
     process.once("exit", () => session?.finishPreflight());
   }
   try { await runUpdateWithSession(child, session); }

@@ -26,7 +26,7 @@ export declare function createOrchestratedChildSession(options: {
   pid?: number;
   verifyIdentity: () => boolean | Promise<boolean>;
 }): {
-  start(): { ok: true } | { ok: false; error: "sync-in-progress" | "update-in-flight" };
+  start(): { ok: true } | { ok: false; error: "sync-in-progress" | "update-in-flight"; staleMarker?: true };
   finishPreflight(): void;
   enterMutation(): Promise<{ ok: true } | { ok: false; error: "sync-in-progress" | "update-in-flight" | "deadline-passed" | "plan-changed" }>;
   noteUntrackedInstaller(): void;

@@ -203,10 +203,12 @@ export function createOrchestratedChildSession({ home, resultPath, resultCapabil
         return { ok: false, error };
       }
       mutex = acquired;
-      if (inspectUpdateMarker(home) !== "free") {
+      const detail = {};
+      if (inspectUpdateMarker(home, { detail }) !== "free") {
         mutex.release(); mutex = undefined;
         result({ phase: "refused", error: "update-in-flight" }); state = "refused"; closeResult();
-        return { ok: false, error: "update-in-flight" };
+        // staleMarker never enters the result record; it lets the launcher print recovery guidance.
+        return { ok: false, error: "update-in-flight", ...(detail.witnessless ? { staleMarker: true } : {}) };
       }
       try { startedAt = now(); marker("preflight"); }
       catch (error) { mutex.release(); mutex = undefined; throw error; }

@@ -4,7 +4,8 @@ export type Acquisition = { kind: "acquired"; addDelegate(pid: number): void; re
 export declare function tryAcquireUpdateSyncMutex(home: string, kind: "sync" | "update", deps?: { now?: () => number; processAlive?: (pid: number) => boolean }): Acquisition;
 export declare function inspectUpdateSyncMutex(home: string): Holder;
 export declare function parentHoldsSyncMutex(home: string, claimedPid?: string): boolean;
-export declare function refuseSync(reason: "update-in-flight" | "sync-in-progress", args: readonly string[]): number;
+export declare function refuseSync(reason: "update-in-flight" | "sync-in-progress", args: readonly string[], hint?: readonly string[]): number;
+export declare function staleUpdateMarkerHint(home: string, platform?: NodeJS.Platform): string[];
 export declare function acquireSyncGuard(home: string, args: readonly string[]): { kind: "acquired"; addDelegate(pid: number): void; release(): void } | { kind: "refused"; exit: number };
-export declare function inspectUpdateMarker(home: string, deps?: { now?: () => number; platform?: NodeJS.Platform; signal?: (id: number) => unknown }): Observation;
+export declare function inspectUpdateMarker(home: string, deps?: { now?: () => number; platform?: NodeJS.Platform; signal?: (id: number) => unknown; detail?: { witnessless?: boolean } }): Observation;
 export declare function isUpdateInFlight(home: string, deps?: { mutex(home: string): Holder; ownershipLease(home: string): Observation; marker(home: string): Observation }): boolean;
@@ -81,23 +81,56 @@ export function parentHoldsSyncMutex(home, claimedPid = process.env.OCX_SYNC_MUT
 }
 
 /** Shared wire format for launcher and Bun sync admission refusals. */
-export function refuseSync(reason, args) {
+export function refuseSync(reason, args, hint = []) {
   const exit = reason === "sync-in-progress" ? 1 : 7;
   console.error(reason);
+  // Recovery guidance follows the reason line on stderr; stdout and the JSON document never change.
+  for (const line of hint) console.error(line);
   if (args.includes("--json")) console.log(JSON.stringify({ schema: "ocx.sync.fanout/1", home: { state: "skipped", exit }, fanout: { state: "not-applicable", reason }, children: [] }));
   return exit;
 }
 
 export function acquireSyncGuard(home, args) {
   const lease = tryAcquireUpdateSyncMutex(home, "sync");
   if (lease.kind !== "acquired") return { kind: "refused", exit: refuseSync(lease.holder === "sync" ? "sync-in-progress" : "update-in-flight", args) };
-  if (inspectUpdateMarker(home) !== "free") {
+  const detail = {};
+  if (inspectUpdateMarker(home, { detail }) !== "free") {
     lease.release();
-    return { kind: "refused", exit: refuseSync("update-in-flight", args) };
+    return { kind: "refused", exit: refuseSync("update-in-flight", args, detail.witnessless ? staleUpdateMarkerHint(home) : []) };
   }
   return lease;
 }
 
+/**
+ * Recovery guidance for a marker that records an interrupted installer with no witness (#8524).
+ * OpenCodex 2.100.x and earlier never recorded the Windows installer supervisor, so such a marker
+ * never clears by itself. Formatting only: the witnessless fact comes from the refusing inspection.
+ */
+export function staleUpdateMarkerHint(home, platform = process.platform) {
+  const path = join(home, "update-orchestrated.json");
+  const windows = platform === "win32";
+  // A copy-paste command must not expand anything from the path. POSIX single quotes expand
+  // nothing. cmd.exe and PowerShell disagree on quoting (PowerShell also closes a string on
+  // typographic quotes and globs [ ]), so Windows gets a command only for plain printable ASCII
+  // without $ ` % " ! [ ]. A path with a control character gets no command on any platform.
+  const controlFree = !/[\x00-\x1f\x7f-\x9f]/.test(path);
+  const rename = !controlFree ? null : windows
+    ? (/^[\x20-\x7e]+$/.test(path) && !/[$`%"![\]]/.test(path) ? `ren "${path}" update-orchestrated.json.stale` : null)
+    : `mv -n ${posixQuote(path)} ${posixQuote(path + ".stale")}`;
+  const shown = path.replace(/[\x00-\x1f\x7f-\x9f]/g, "?");
+  return [
+    `The update marker ${shown} records an interrupted update whose installer can no longer be checked`,
+    windows
+      ? "(OpenCodex 2.100.x and earlier did not record the Windows installer), so it will not clear by itself."
+      : "(its installer was never recorded), so it will not clear by itself.",
+    "If no update is running (no ocx update, no npm, pnpm or bun global install, no OpenCodex installer",
+    "PowerShell process running npm-install-job.ps1), rename the marker and run ocx update again:",
+    rename === null ? "  rename that file by hand, for example to update-orchestrated.json.stale" : `  ${rename}`,
+  ];
+}
+
+function posixQuote(value) { return `'${value.replaceAll("'", "'\\''")}'`; }
+
 function inspectOwnershipLease(home) {
   try {
     const statePaths = serviceStateFilesFor(home, isTestHomeGuardArmed() ? home : join(homedir(), ".opencodex"));
@@ -110,7 +143,7 @@ function inspectOwnershipLease(home) {
   } catch { return "unknown"; }
 }
 
-export function inspectUpdateMarker(home, { now = Date.now, platform = process.platform, signal } = {}) {
+export function inspectUpdateMarker(home, { now = Date.now, platform = process.platform, signal, detail } = {}) {
   const probe = signal ?? (id => process.kill(id, 0));
   const windows = platform === "win32";
   const path = join(home, "update-orchestrated.json");
@@ -158,7 +191,14 @@ export function inspectUpdateMarker(home, { now = Date.now, platform = process.p
     // An unconfirmed installer is free only once its process-tree witness is gone: the POSIX group,
     // or on Windows the supervisor whose exit closes the kill-on-close job.
     const witness = windows ? marker.installerPid : marker.installerPgid;
-    return unknown || (marker.terminationUnconfirmed && witness === undefined) ? "unknown" : "free";
+    if (unknown) return "unknown";
+    if (marker.terminationUnconfirmed && witness === undefined) {
+      // Unknown only because nothing witnesses the installer: the fence has passed and every
+      // recorded process is gone. The refusal can then name the marker and its manual recovery.
+      if (detail) detail.witnessless = true;
+      return "unknown";
+    }
+    return "free";
   } catch (error) { return !found && error?.code === "ENOENT" ? "free" : "unknown"; }
   finally { if (fd !== undefined) closeSync(fd); }
 }