@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/service/diagnostics.ts

@@ -21,13 +21,19 @@ import { LABEL, TASK, serviceLogPath } from "./state";
  * moved, nvm switch, reinstall) — the service manager would restart-loop on a dead path
  * while `schtasks`/`launchctl` still report "installed".
  */
-export function bakedServicePathsDiagnostic(): string | null {
+export function bakedServicePathsDiagnostic(platform: NodeJS.Platform = process.platform): string | null {
   const state = readServiceInstallState();
   // A launcher install runs the launcher, not the baked pair, so the pair's existence says
   // nothing about whether the service can start. Judging the recorded launcher is both
   // necessary (a deleted launcher IS stale) and sufficient (a replaced version directory
   // is not, which is exactly what #2898 made routine).
   if (state?.launcherPath) {
+    // launchd no longer bakes a launcher at all: a recorded one can only have come from an
+    // install that handed the service token and proxy environment to a mutable PATH shim,
+    // so it is stale whether or not the file it names still exists.
+    if (platform === "darwin") {
+      return "STALE mutable launchd launcher — run 'ocx service repair' to re-bake trusted package paths";
+    }
     if (existsSync(state.launcherPath)) return null;
     return `STALE baked paths (missing: ${state.launcherPath}) — run 'ocx service repair' to re-bake`;
   }

package/src/service/launchd.ts

@@ -12,7 +12,7 @@ import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./guards";
 import { resolveServiceListenPort, buildServiceShellCommand, buildServiceLauncherShellCommand, installedServiceListenPort, resolvedProxyEnv } from "./health";
-import { SERVICE_MANAGED_ENV, LABEL, cliEntry, stableLauncherEntry, logPath, serviceStatePath, currentCodexSqliteHomeAbsolute, type ServiceInstallState, writeServiceInstallState, readServiceInstallState } from "./state";
+import { SERVICE_MANAGED_ENV, LABEL, cliEntry, logPath, serviceStatePath, currentCodexSqliteHomeAbsolute, type ServiceInstallState, writeServiceInstallState, readServiceInstallState } from "./state";
 import { writeServiceDefinitionFile } from "./windows-ops";
 import { readTextOrNull } from "./windows-taskxml";
 
@@ -26,20 +26,18 @@ function plistString(value: string): string {
 }
 
 /**
- * Render the launchd plist. Mirrors `buildUnit`: when `deps.launcher` names a stable `ocx`
- * executable, the job execs that launcher instead of the package-local Bun + CLI pair, so a
- * version-manager upgrade (mise, asdf, nvm) that replaces the package directory is picked up
- * on the next launchd start instead of leaving the old build serving (#3464 — the macOS
- * counterpart of #2898). Discovery belongs to `installLaunchd()`; the default here is the
- * legacy pair so callers and tests stay hermetic.
+ * Render the launchd plist from the package-local Bun + CLI pair. Unlike systemd, launchd
+ * must not hand the service token and proxy environment to a PATH-discovered launcher: a
+ * mutable version-manager shim could be replaced after installation and run with those
+ * secrets. The legacy `launcher` dependency remains accepted for API compatibility but is
+ * ignored.
  */
 export function buildPlist(
   proxyEnv: { name: string; value: string }[] = resolvedProxyEnv(),
-  deps: { launcher?: string | null; runtime?: DurableBunRuntime } = {},
+  deps: { runtime?: DurableBunRuntime; launcher?: string | null } = {},
 ): string {
   const runtime = deps.runtime ?? durableBunRuntime();
   const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
-  const launcher = deps.launcher ?? null;
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = process.env.CODEX_HOME?.trim();
@@ -52,16 +50,8 @@ export function buildPlist(
     // (src/cli/index.ts preserveRouting). Only the wrapper writes this second marker, so
     // the dashboard-stop refusal below can tell a real launchd job from an ordinary child.
     `    <key>${SERVICE_MANAGED_ENV}</key><string>1</string>`,
-    ...(launcher ? [] : [
-      `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntimeSource}</string>`,
-      `    <key>${BUN_RUNTIME_PATH_ENV}</key><string>${plistString(bun)}</string>`,
-    ]),
-    // A launcher resolves the current package's bundled Bun after every upgrade. Preserve
-    // only a proof-bound shell override; baking a package-local path here would recreate
-    // the version-manager pin that launcher mode exists to remove (same rule as buildUnit).
-    launcher && runtime.source === "override"
-      ? `    <key>${runtime.overrideEnv}</key><string>${plistString(runtime.path)}</string>`
-      : null,
+    `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntimeSource}</string>`,
+    `    <key>${BUN_RUNTIME_PATH_ENV}</key><string>${plistString(bun)}</string>`,
     `    <key>PATH</key><string>${plistString(path)}</string>`,
     codexHome ? `    <key>CODEX_HOME</key><string>${plistString(codexHome)}</string>` : null,
     codexSqliteHome ? `    <key>CODEX_SQLITE_HOME</key><string>${plistString(codexSqliteHome)}</string>` : null,
@@ -69,7 +59,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 = launchdServiceCommand(launcher, runtime);
+  const command = launchdServiceCommand(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">
@@ -135,18 +125,16 @@ export function reusePreviousPlistPathVariable(previous: string, rendered: strin
 }
 
 /**
- * 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).
+ * The exec line {@link buildPlist} bakes, for the 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` falls back to the package
+ * pair — identical here, but only by accident of the fresh state).
  */
 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);
 }
@@ -496,13 +484,14 @@ export function installLaunchd(deps: {
   // 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();
+  // Keep launchd bound to the package paths selected by this trusted invocation. A PATH
+  // launcher can be replaced later and would inherit the service token and proxy
+  // environment.
   // 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);
+  // falls back to the Bun + CLI pair, which happens to be the same answer only by accident
+  // of the empty state.
+  const expectedCommand = launchdServiceCommand();
   const uid = process.getuid?.() ?? 0;
   const guiDomain = launchdGuiDomain();
   const guiTarget = `${guiDomain}/${LABEL}`;
@@ -523,7 +512,7 @@ export function installLaunchd(deps: {
     );
   }
 
-  let rendered = buildPlist(resolvedProxyEnv(), { launcher });
+  let rendered = buildPlist(resolvedProxyEnv());
   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
@@ -553,7 +542,7 @@ export function installLaunchd(deps: {
     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);
+    writeServiceInstallState("scheduler");
     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.
@@ -652,7 +641,7 @@ export function installLaunchd(deps: {
       `⚠️  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);
+    writeServiceInstallState("scheduler");
     return { reloaded: true };
   }
 
@@ -691,7 +680,7 @@ export function installLaunchd(deps: {
       + `then re-run '${wasInstalled ? "ocx service repair" : "ocx service install"}'.`,
     );
   }
-  writeServiceInstallState("scheduler", launcher);
+  writeServiceInstallState("scheduler");
   // 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.
@@ -730,7 +719,7 @@ export function restartLaunchdJob(deps: {
   const run = deps.launchctl ?? runLaunchctl;
   const target = `${launchdGuiDomain()}/${LABEL}`;
   const expectedCommand = deps.expectedCommand
-    ?? (() => launchdServiceCommand(stableLauncherEntry()));
+    ?? (() => launchdServiceCommand());
   const kicked = run(["kickstart", "-k", target]);
   const verdict = (deps.probe ?? probeLaunchdLoadState)({ expectedCommand });
   if (!kicked.ok || verdict.state === "not-loaded" || verdict.state === "loaded-stale") {

package/src/service/windows-ops.ts

@@ -12,7 +12,7 @@ import { dirname, join } from "node:path";
 import { getConfigDir } from "../config";
 import { OCX_ELEVATED_STAGING_UNREADABLE, runWindowsElevatedScheduledTaskRegistration, WindowsSchtasksError, type StagedWindowsTaskXml } from "../lib/windows-elevation";
 import { defaultWinswEntry, installWinswService, statusWinswRaw, uninstallWinswService, WINSW_SERVICE_ID, type WinswStatus } from "../lib/winsw";
-import { forgetEphemeralSecretDir, forgetEphemeralSecretPath, hardenSecretDir } from "../lib/windows-secret-acl";
+import { forgetEphemeralSecretDir, forgetEphemeralSecretPath, hardenElevatedStageDir, hardenElevatedStagePath, hardenSecretDir } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
@@ -192,19 +192,24 @@ export interface ElevatedSchedulerStagingDeps {
  * alone:
  *
  * - **Access.** The directory is created fresh by `mkdtemp`, then ACL-hardened before
- *   anything is written into it, so another local account cannot read or replace the
- *   payload while the UAC prompt is open. Hardening the directory first is what makes
- *   the file private from the moment it exists.
+ *   anything is written into it, so no non-administrator account can read or replace
+ *   the payload while the UAC prompt is open. Administrators get read — never write —
+ *   because an over-the-shoulder UAC prompt answered with a different administrator's
+ *   credentials runs the elevated process as that admin (#4779); tamper-evidence does
+ *   not depend on the DACL, it comes from the pinned handles and the digest below.
+ *   Hardening the directory first is what makes the file private from the moment it
+ *   exists.
  * - **No reparse point.** Each artifact is inspected with `lstat` and rejected unless it
  *   is what it claims to be. `wx` already refuses to create over an existing name, which
  *   is the atomic step here — there is no replace path to race, because every path is
  *   inside a directory that did not exist a moment ago. The explicit check is what keeps
  *   that guarantee from depending on a reading of `O_EXCL` semantics.
- * - **Tamper evidence.** The digest is taken over the exact bytes written, and the
- *   elevated script recomputes it over the bytes it reads. An ACL cannot cover this:
- *   a process running as the same user has the same SID and can rewrite the file, so
- *   the digest is the only thing that makes such a swap fail closed rather than
- *   silently register a different task definition.
+ * - **Pinned namespace and content.** Before UAC, the launcher opens every ancestor and
+ *   payload without following reparse points. Ancestor handles share read/write but
+ *   deny delete, so the namespace cannot be redirected while sibling payloads can
+ *   still be written; payload handles deny write/delete outright. Those handles stay
+ *   open until elevation exits. The digest then verifies the exact,
+ *   length-bounded bytes read by the elevated process.
  *
  * Payloads are UTF-16LE with no BOM, and the elevated process decodes them straight into
  * `Register-ScheduledTask`. What is hashed is therefore exactly what is registered, with
@@ -217,11 +222,11 @@ export function stageElevatedSchedulerRegistration(
 ): StagedElevatedSchedulerRegistration {
   const createStageDir = deps.createStageDir
     ?? (() => mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX)));
-  const hardenDir = deps.hardenDir ?? ((path: string) => { hardenSecretDir(path, { required: true }); });
+  const hardenDir = deps.hardenDir ?? ((path: string) => { hardenElevatedStageDir(path, { required: true }); });
   const writePayload = deps.writePayload ?? ((path: string, bytes: Buffer) => {
     writeFileSync(path, bytes, { flag: "wx", mode: 0o600 });
   });
-  const hardenPath = deps.hardenPath ?? ((path: string) => { hardenSecretPath(path, { required: true }); });
+  const hardenPath = deps.hardenPath ?? ((path: string) => { hardenElevatedStagePath(path, { required: true }); });
   const inspect = deps.inspect ?? ((path: string) => lstatSync(path));
   const removeStageDir = deps.removeStageDir ?? ((path: string) => { rmdirSync(path); });
 
@@ -266,7 +271,7 @@ export function stageElevatedSchedulerRegistration(
         throw new Error(`Refusing to stage an elevated Task Scheduler payload through a redirected path: ${path}`);
       }
       hardenPath(path);
-      return { path, sha256: createHash("sha256").update(bytes).digest("hex") };
+      return { path, byteLength: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
     };
     return {
       xml: stage("register.xml", xml),
@@ -293,10 +298,9 @@ export function stageElevatedSchedulerRegistration(
  *
  * The elevated process runs hidden, so nothing it writes survives; only the exit code
  * crosses back. That makes an unexplained code the whole user-facing error, which is
- * exactly what made the ENAMETOOLONG in #4692 expensive to diagnose. Staging introduces
- * one new failure of its own — the payload is readable only by the account that created
- * it, so an elevation answered with a different administrator's credentials cannot open
- * it — and that one gets named along with its remedy rather than surfacing as a number.
+ * exactly what made the ENAMETOOLONG in #4692 expensive to diagnose. Staging has one
+ * failure of its own — the elevated process cannot open the payload — and that one
+ * gets named along with its remedy rather than surfacing as a number.
  */
 export function describeElevatedRegistrationFailure(
   failureLabel: string,
@@ -305,10 +309,10 @@ export function describeElevatedRegistrationFailure(
 ): string {
   if (exitCode === OCX_ELEVATED_STAGING_UNREADABLE) {
     return `${failureLabel}: the elevated process could not read the staged task definition in `
-      + `${stageDir}. That directory is readable only by the account that staged it, so this `
-      + "happens when the UAC prompt was answered with a different administrator account. "
-      + "Approve the prompt as the signed-in user, or run the command again from a session "
-      + "already elevated as that user.";
+      + `${stageDir}. That directory grants read access to the staging account and to `
+      + "administrators, so the hardening did not take effect there or the file was "
+      + "replaced. Retry the command; if it keeps failing, run it again from a session "
+      + "already elevated as an administrator.";
   }
   return `${failureLabel} with exit code ${exitCode}.`;
 }

package/src/types/config.ts

@@ -1,6 +1,37 @@
 import type { OcxProviderConfig } from "./provider";
 import type { CodexAccount } from "./accounts";
 
+/** Public inference API exposure. Responses and Chat Completions are always served. */
+export interface OcxApiSurfacesConfig {
+  /**
+   * `/v1/messages` and `/v1/messages/count_tokens`. Absent means "inherit
+   * `claudeCode.enabled !== false`"; a present non-boolean value disables the surface.
+   */
+  messages?: { enabled?: boolean };
+}
+
+/** Protocol delivery policy (devlog/_plan/260924_protocol_first_class). */
+export interface OcxProtocolsConfig {
+  /**
+   * What happens when the final upstream wire cannot express a requested feature.
+   * `legacy` (default) keeps today's behavior; `reject` refuses before any upstream send.
+   */
+  unrepresentable?: "legacy" | "reject";
+  /** Staged rollout switches. Every switch defaults off and changes no semantics while off. */
+  rollout?: {
+    /** Eligible Chat candidates inside combos and policy routes send natively. */
+    nativeChatCombos?: boolean;
+    /** Proxy-managed key-auth Anthropic targets receive `/v1/messages` natively. */
+    managedMessagesNative?: boolean;
+    /** Extends managed native Messages to Anthropic OAuth accounts. Requires the switch above. */
+    managedMessagesNativeOAuth?: boolean;
+    /** Chat and Messages clients are encoded directly from adapter events. */
+    directEncoders?: boolean;
+    /** Compare the dispatch plan with the observed path; never sends a second request. */
+    shadowPlan?: boolean;
+  };
+}
+
 /**
  * Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
  * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
@@ -397,10 +428,17 @@ export interface OcxPrivacyConfig {
   maskEmails?: boolean;
 }
 
+export interface OcxLinkTransportConfig {
+  tunnelPort: number;
+  linkId: string;
+}
+
 export interface OcxClientConnectionConfig {
   serverUrl: string;
   managementUrl: string;
   managementTransport: "direct" | "relay";
+  transport?: "hub" | "link";
+  link?: OcxLinkTransportConfig;
   selectedClients: OcxConnectedClientId[];
   tokenEnv: "OPENCODEX_API_AUTH_TOKEN";
   apiKeyId: string;
@@ -527,6 +565,14 @@ export interface OcxConfig {
   googleAntigravityStaticCatalogVersion?: 1 | 2;
   /** Claude Code inbound + launcher settings. */
   claudeCode?: OcxClaudeCodeConfig;
+  /**
+   * Which public inference APIs this proxy serves. Read only through
+   * `resolveApiSurfaceSettings` in `src/protocols/settings.ts`, which fails closed on a
+   * malformed value and inherits `claudeCode.enabled` while no explicit value exists.
+   */
+  apiSurfaces?: OcxApiSurfacesConfig;
+  /** Protocol delivery policy and rollout switches; see `resolveProtocolSettings`. */
+  protocols?: OcxProtocolsConfig;
   /**
    * Per-client durable intent. This phase owns only `codex`; later phases extend
    * one key at a time rather than widening a shared union.
@@ -742,6 +788,12 @@ export interface OcxConfig {
     timeoutMs?: number;
     /** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
     cacheEntries?: number;
+    /**
+     * Extra recovery sends when ChatGPT rejects with a transient 5xx or the transport
+     * fails, sharing the same credential, deadline, and cache flight (#3661).
+     * Default: 0 (single attempt); maximum: 2.
+     */
+    retries?: number;
   };
   /**
    * Quota-reset detection and notification. Absent means off: no detection, no timer, no sink.
@@ -1136,7 +1188,7 @@ export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-fir
 
 export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
 
-export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window";
+export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window" | "jev";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
 export type OcxComboDefaultEffortMode = "fallback" | "force";
 
@@ -1161,6 +1213,11 @@ export interface OcxComboTarget {
   model: string;
   /** Relative target weight for round-robin batches and random selection. Default 1; valid range 1..10000. */
   weight?: number;
+  /**
+   * Exact efforts JEV may choose for this target. Omit to allow every effort the
+   * target currently advertises; an explicit list must be non-empty.
+   */
+  reasoningEfforts?: OcxComboDefaultEffort[];
   /**
    * Marks an emergency-only target. Inert unless the combo sets
    * `cooldownWaitPolicy`, and never makes a target permanently ineligible —

package/src/types.ts

@@ -61,6 +61,8 @@ export type {
 } from "./types/request";
 
 export type {
+  OcxApiSurfacesConfig,
+  OcxProtocolsConfig,
   OcxClaudeCodeConfig,
   OcxClaudeDesktopFamily,
   OcxClaudeDesktopAssignment,

package/src/update/transactional-install.d.mts

@@ -20,7 +20,6 @@ export function sweepUpdateLeftovers(args: {
   log?: (line: string) => void;
   deps?: UpdateFsDeps;
 }): {
-  removed: string[];
   inUse: Array<{ path: string; code: string }>;
   recent: string[];
   notOwned: string[];

package/src/update/transactional-install.mjs

@@ -17,9 +17,9 @@
  *   <scopeDir>/.ocx-recovery.json             double-fault marker with a one-line restore
  *
  * A staging directory is created exclusively and immediately carries an ownership marker
- * (`.ocx-update-owner.json`). Only a marked staging directory is ever swept by a later
- * update; anything else next to the package — an unmarked stage from an older updater, npm's
- * own `.<name>-<random>` rename-aside, a link — is reported and left alone (#5624).
+ * (`.ocx-update-owner.json`). Later updates report leftovers but do not delete them: a marker
+ * proves provenance only while this process owns the fresh path, not after another local
+ * process could have replaced it. Other neighbouring entries are likewise left alone (#5624).
  */
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -169,9 +169,8 @@ function stampedName(prefix) {
 export const UPDATE_OWNER_MARKER = ".ocx-update-owner.json";
 const STAGE_PREFIX = ".ocx-staging-";
 /**
- * A marked stage younger than this is left alone by the sweep. npm's staging install is bounded
- * at three minutes by the launcher; the floor is far above it so an update running from another
- * home against the same global prefix never loses its in-flight stage.
+ * A marked stage younger than this is reported as recent. npm's staging install is bounded at
+ * three minutes by the launcher; the floor distinguishes likely in-flight work from leftovers.
  */
 export const STALE_STAGE_MIN_AGE_MS = 30 * 60 * 1000;
 const RETRYABLE_REMOVE_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
@@ -256,14 +255,14 @@ export function removeOwnedStage(stageRoot, deps = {}) {
 }
 
 /**
- * Clear what earlier update attempts left next to the package, without ever deleting anything
- * this updater cannot prove it created. Never throws and never fails the update: every stage is
- * a fresh, uniquely named directory, so a leftover can only cost disk space, not block staging.
+ * Report what earlier update attempts left next to the package. A marker is forgeable and a
+ * pathname can be replaced after inspection, so no later process may recursively delete a
+ * leftover by that pathname. Never throws or fails the update: fresh unique stages step around it.
  */
 export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps = {} }) {
   const scopeDir = dirname(packageDir);
   const now = (deps.now ?? Date.now)();
-  const result = { removed: [], inUse: [], recent: [], notOwned: [] };
+  const result = { inUse: [], recent: [], notOwned: [] };
   let names = [];
   try {
     names = readdirSync(scopeDir);
@@ -281,9 +280,7 @@ export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps
       } else if (now - marker.createdAt < STALE_STAGE_MIN_AGE_MS) {
         result.recent.push(full);
       } else {
-        const removal = removeOwnedStage(full, deps);
-        if (removal.removed) result.removed.push(full);
-        else result.inUse.push({ path: full, code: removal.code });
+        result.inUse.push({ path: full, code: "ESTALE" });
       }
     } else if (name.startsWith(renameAsidePrefix)) {
       result.notOwned.push(full);
@@ -291,9 +288,10 @@ export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps
   }
   // Names only: the full path under a user-scoped npm prefix carries the account name, and
   // this logger is the launcher's console.
-  for (const path of result.removed) log("Removed a staging directory left by an earlier update: " + basename(path));
   for (const entry of result.inUse) {
-    log("Left an earlier update's staging directory in place (" + entry.code + "; a file inside is still in use); the next update retries it: " + basename(entry.path));
+    log(entry.code === "ESTALE"
+      ? "Left an earlier update's staging directory in place; delete it by hand once no OpenCodex process is running from it: " + basename(entry.path)
+      : "Left an earlier update's staging directory in place (could not remove it: " + entry.code + "): " + basename(entry.path));
   }
   for (const path of result.notOwned) {
     log("Not removing " + basename(path) + " next to the package: this updater did not create it. Delete it by hand once no OpenCodex process is running from it.");
@@ -393,7 +391,7 @@ export function transactionalNpmUpdate({
 }) {
   const rename = deps.rename ?? renameSync;
   const scopeDir = dirname(packageDir);
-  // Leftovers from earlier attempts are cleared or stepped around first; this never fails.
+  // Leftovers from earlier attempts are only reported; fresh unique stages step around them. This never fails.
   try { sweepUpdateLeftovers({ packageDir, pkgName, log, deps }); } catch { /* report-only */ }
   let stageRoot;
   // GLOBAL-style staging (-g --prefix): npm nests the package's dependencies INSIDE the
@@ -419,7 +417,9 @@ export function transactionalNpmUpdate({
   const discardStage = () => {
     const removal = removeOwnedStage(stageRoot, deps);
     if (!removal.removed) {
-      log("Left this update's staging directory in place (" + removal.code + "; a file inside is still in use); the next update removes it: " + basename(stageRoot));
+      // EACCES/EUNKNOWN do not prove an open file, so the message names the failure
+      // without blaming a process; the code stays for whoever reads the log.
+      log("Left this update's staging directory in place (could not remove it: " + removal.code + "); later updates will not remove it either — delete it by hand once no OpenCodex process is running from it: " + basename(stageRoot));
     }
   };
   const spec = pkgName + "@" + (targetVersion || tag);