@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/link/supervisor.ts

@@ -4,13 +4,16 @@ import { atomicWriteFile } from "../config/atomic-write";
 import { linkDir, linkKnownHostsPath, linkStorePath } from "./paths";
 import { buildTunnelArgv } from "./ssh-argv";
 import { createSshRunner, type SshChild, type SshRunner } from "./ssh-runner";
+import type { LinkDiagnosticSink } from "./diagnostics";
+import { createTunnelHistoryBook, exitCause, type TunnelCause, type TunnelHistory } from "./tunnel-history";
 import {
   classifySshStderr,
   dueForSpawn,
-  failedTunnel,
+  failedSpawnTunnel,
   HOME_TUNNEL_RETRY_POLICY,
   IDLE,
   reduceTunnel,
+  type TunnelFailure,
   type TunnelState,
 } from "./tunnel-state";
 import { emptyLinkStore, readLinkStore, type LinkRecord, type LinkStore } from "./store";
@@ -22,6 +25,8 @@ export type LinkTunnelStatus =
     state: TunnelState;
     pid: number | null;
     orphan?: "orphan-unverified";
+    /** Attempts, last change and last failure cause of this tunnel (`tunnel-history.ts`). */
+    history?: TunnelHistory;
   }
   | {
     linkId: string;
@@ -72,6 +77,10 @@ export interface LinkSupervisorDeps {
   apiKeys?: () => readonly { id: string; name: string }[];
   revokeApiKey?: (id: string) => boolean;
   warn?: (message: string) => void;
+  /** Where tunnel state changes are recorded; production passes the bounded diagnostics file. */
+  diagnostic?: LinkDiagnosticSink;
+  /** Bounded drain of `diagnostic` at stop. */
+  flushDiagnostics?: () => Promise<void>;
 }
 
 const TIMER_MS = 1_000;
@@ -166,6 +175,10 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
   /** The generation of the child whose exit is still being classified, per link. */
   const exiting = new Map<string, number>();
   const recordInstances = new Map<string, string>();
+  const history = createTunnelHistoryBook({
+    diagnostic: deps.diagnostic,
+    tunnelPort: linkId => store.links.find(link => link.id === linkId)?.tunnelPort,
+  });
 
   const reconcileApiKeys = (): void => {
     const keys = deps.apiKeys?.() ?? [];
@@ -218,12 +231,22 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
     }
   };
 
-  const setEvent = (linkId: string, event: Parameters<typeof reduceTunnel>[1]): TunnelState => {
-    const next = reduceTunnel(states.get(linkId) ?? IDLE, event, deps.random, HOME_TUNNEL_RETRY_POLICY);
+  /** Every state change goes through here, so the history sees each transition and its cause. */
+  const put = (linkId: string, next: TunnelState, cause: TunnelCause | null = null): TunnelState => {
+    const before = states.get(linkId) ?? IDLE;
     states.set(linkId, next);
+    history.observe(linkId, before, next, cause, now());
     return next;
   };
 
+  const setEvent = (linkId: string, event: Parameters<typeof reduceTunnel>[1], cause: TunnelCause | null = null): TunnelState =>
+    put(linkId, reduceTunnel(states.get(linkId) ?? IDLE, event, deps.random, HOME_TUNNEL_RETRY_POLICY), cause);
+
+  /** Fail a link whose attempt could not start; a due retry that fails this way counts as one. */
+  const failAttempt = (linkId: string, prior: TunnelState | undefined, reason: TunnelFailure, cause: TunnelCause): void => {
+    put(linkId, failedSpawnTunnel(prior, reason, now(), HOME_TUNNEL_RETRY_POLICY), cause);
+  };
+
   const spawnFor = (record: LinkRecord): void => {
     if (stopping || holds.has(record.id) || record.direction !== "hub-initiated" || children.has(record.id)) return;
     // Only a fresh link or a due attempt spawns. A reload must neither skip the backoff nor start
@@ -231,7 +254,8 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
     const prior = states.get(record.id);
     if (prior && prior.kind !== "idle" && !dueForSpawn(prior, now())) return;
     if (store.listenerPort === null) {
-      states.set(record.id, { kind: "failed", since: now(), reason: "forward" });
+      // Retried like any forward failure; a reload that brings the listener back starts it fresh.
+      failAttempt(record.id, prior, "forward", "listener_unavailable");
       return;
     }
     let argv: string[];
@@ -250,6 +274,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
       exiting.delete(record.id);
       children.set(record.id, { child, argv, spawnedAt: now() });
       orphanUnverified.delete(record.id);
+      history.spawned(record.id);
       setEvent(record.id, { type: "spawn", now: now() });
       writePidfile(pidfilePath(record.id), { version: 1, linkId: record.id, pid: child.pid, argv });
       void child.exited.then(async () => {
@@ -264,7 +289,8 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
           try { stderr = child.stderr ? await child.stderr : ""; } catch { /* classified as unknown */ }
           // A reconnect may have started a fresh child meanwhile; its own lifecycle owns the state.
           if (generations.get(record.id) !== generation) return;
-          setEvent(record.id, { type: "exit", now: now(), stderrClass: classifySshStderr(stderr) });
+          const stderrClass = classifySshStderr(stderr);
+          setEvent(record.id, { type: "exit", now: now(), stderrClass }, exitCause(stderrClass));
         } finally {
           if (exiting.get(record.id) === generation) exiting.delete(record.id);
         }
@@ -272,11 +298,10 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         if (children.get(record.id)?.child !== child) return;
         children.delete(record.id);
         conditionalRemovePidfile(record.id, child.pid);
-        if (!stopping) setEvent(record.id, { type: "exit", now: now(), stderrClass: "network" });
+        if (!stopping) setEvent(record.id, { type: "exit", now: now(), stderrClass: "network" }, "network");
       });
     } catch {
-      const at = now();
-      states.set(record.id, failedTunnel("forward", at, HOME_TUNNEL_RETRY_POLICY, prior?.kind === "failed" ? prior.since : at));
+      failAttempt(record.id, prior, "forward", "spawn_failed");
     }
   };
 
@@ -300,7 +325,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         setEvent(record.id, { type: "ready", now: current });
         continue;
       }
-      const next = setEvent(record.id, { type: "tick", now: current });
+      const next = setEvent(record.id, { type: "tick", now: current }, "timeout");
       if (next.kind === "failed" && !next.inFlight && child && retryInFlight(before)) {
         // A retry started just before the outage limit has not had its grace yet. It carries on as
         // the failed state's retry instead of being killed with a link that may already be back.
@@ -349,7 +374,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
   const stopChild = async (linkId: string): Promise<void> => {
     const current = children.get(linkId);
     if (!current) {
-      states.set(linkId, IDLE);
+      put(linkId, IDLE);
       return;
     }
     const generation = generations.get(linkId);
@@ -358,7 +383,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
     await current.child.exited;
     conditionalRemovePidfile(linkId, current.child.pid);
     // A stop or removal reservation made while this child exited owns the next state.
-    if (generations.get(linkId) === generation) states.set(linkId, IDLE);
+    if (generations.get(linkId) === generation) put(linkId, IDLE);
   };
 
   const invalidateLink = (linkId: string): void => {
@@ -407,6 +432,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
           if (nextInstances.has(linkId) && !changed.has(linkId)) continue;
           await stopChild(linkId);
           states.delete(linkId);
+          history.forget(linkId);
           orphanUnverified.delete(linkId);
           recordInstances.delete(linkId);
           if (stopping) return;
@@ -414,9 +440,13 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         for (const record of nextStore.links) {
           if (changed.has(record.id)) {
             states.delete(record.id);
+            history.forget(record.id);
             orphanUnverified.delete(record.id);
           }
         }
+        for (const linkId of [...states.keys()]) {
+          if (!nextInstances.has(linkId)) history.forget(linkId);
+        }
         recordInstances.clear();
         for (const [linkId, instance] of nextInstances) recordInstances.set(linkId, instance);
         for (const record of nextStore.links) {
@@ -471,12 +501,14 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
           return { linkId: record.id, direction: record.direction, state: "client-owned", pid: null };
         }
         const child = children.get(record.id);
+        const recorded = history.get(record.id);
         return {
           linkId: record.id,
           direction: record.direction,
           state: states.get(record.id) ?? IDLE,
           pid: child?.child.pid ?? null,
           ...(orphanUnverified.has(record.id) ? { orphan: "orphan-unverified" as const } : {}),
+          ...(recorded ? { history: recorded } : {}),
         };
       });
     },
@@ -489,9 +521,10 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
       await runLifecycle(async () => {
         await Promise.all([...children.keys()].map(stopChild));
         for (const record of store.links) {
-          if (record.direction === "hub-initiated") states.set(record.id, IDLE);
+          if (record.direction === "hub-initiated") put(record.id, IDLE);
         }
       });
+      try { await deps.flushDiagnostics?.(); } catch { /* best effort */ }
     },
   };
 }

package/src/link/tunnel-history.ts

@@ -0,0 +1,109 @@
+/**
+ * What the Home remembers about one `-R` tunnel besides its current state: how many ssh attempts
+ * the current outage has cost, the last state change and the last failure with its cause. It lives
+ * in memory next to the supervisor's state, appears in `GET /api/link/status` as `tunnel`, and
+ * each change it records also goes to the bounded diagnostics file (`diagnostics.ts`), so a link
+ * that failed for an hour leaves evidence of why after the fact.
+ *
+ * Nothing here carries ssh output, argv, host names or keys: a cause is one of a fixed set of
+ * words, and times are numbers.
+ */
+import type { LinkDiagnosticSink } from "./diagnostics";
+import type { StderrClass, TunnelState } from "./tunnel-state";
+
+export type TunnelCause =
+  | "auth" | "hostkey" | "forward" | "remote_forward_conflict" | "timeout" | "network" | "unknown"
+  | "spawn_failed" | "listener_unavailable";
+
+export const TUNNEL_CAUSES: readonly TunnelCause[] = [
+  "auth", "hostkey", "forward", "remote_forward_conflict", "timeout", "network", "unknown",
+  "spawn_failed", "listener_unavailable",
+];
+
+export interface TunnelTransitionRecord {
+  from: TunnelState["kind"];
+  to: TunnelState["kind"];
+  at: number;
+  cause: TunnelCause | null;
+}
+
+export interface TunnelHistory {
+  /** ssh attempts started since the link was last connected (0 while connected). */
+  attempt: number;
+  lastTransition: TunnelTransitionRecord | null;
+  lastFailure: { cause: TunnelCause; at: number } | null;
+}
+
+export function exitCause(stderrClass: StderrClass): TunnelCause {
+  return stderrClass === "remote_forward" ? "remote_forward_conflict" : stderrClass;
+}
+
+/**
+ * A retry of a failed link ended without connecting: one that ran while the state read failed, or
+ * one that could not even start (the retry count still grew).
+ */
+function retryFailedAgain(before: TunnelState, after: TunnelState): boolean {
+  if (before.kind !== "failed" || after.kind !== "failed" || after.inFlight === true) return false;
+  return before.inFlight === true || (after.retries ?? 0) > (before.retries ?? 0);
+}
+
+export interface TunnelHistoryBook {
+  /** Count one ssh attempt for the link. */
+  spawned(linkId: string): void;
+  /** Record a state change; `cause` names why the link left a working state, when known. */
+  observe(linkId: string, before: TunnelState, after: TunnelState, cause: TunnelCause | null, at: number): void;
+  get(linkId: string): TunnelHistory | undefined;
+  forget(linkId: string): void;
+}
+
+export function createTunnelHistoryBook(
+  options: { diagnostic?: LinkDiagnosticSink; tunnelPort?: (linkId: string) => number | undefined } = {},
+): TunnelHistoryBook {
+  const histories = new Map<string, TunnelHistory>();
+  const entry = (linkId: string): TunnelHistory => {
+    let history = histories.get(linkId);
+    if (!history) {
+      history = { attempt: 0, lastTransition: null, lastFailure: null };
+      histories.set(linkId, history);
+    }
+    return history;
+  };
+  return {
+    spawned(linkId) {
+      entry(linkId).attempt += 1;
+    },
+    observe(linkId, before, after, cause, at) {
+      const refailed = retryFailedAgain(before, after);
+      if (before.kind === after.kind && !refailed) return;
+      const history = entry(linkId);
+      if (after.kind === "connected" || after.kind === "idle") history.attempt = 0;
+      if (cause && (after.kind === "failed" || after.kind === "reconnecting")) history.lastFailure = { cause, at };
+      history.lastTransition = { from: before.kind, to: after.kind, at, cause };
+      const retryAt = after.kind === "failed" || after.kind === "reconnecting" ? after.retryAt : undefined;
+      const tunnelPort = options.tunnelPort?.(linkId);
+      try {
+        options.diagnostic?.({
+          event: "tunnel_transition",
+          outcome: cause ?? (after.kind === "connected" ? "connected" : after.kind === "idle" ? "stopped" : "spawned"),
+          state: after.kind,
+          previousState: before.kind,
+          attempt: history.attempt,
+          ...(tunnelPort !== undefined ? { tunnelPort } : {}),
+          ...(retryAt !== undefined ? { retryAfterMs: Math.max(0, retryAt - at) } : {}),
+        });
+      } catch { /* Diagnostics never change the tunnel lifecycle. */ }
+    },
+    get(linkId) {
+      const history = histories.get(linkId);
+      if (!history) return undefined;
+      return {
+        attempt: history.attempt,
+        lastTransition: history.lastTransition && { ...history.lastTransition },
+        lastFailure: history.lastFailure && { ...history.lastFailure },
+      };
+    },
+    forget(linkId) {
+      histories.delete(linkId);
+    },
+  };
+}

package/src/link/tunnel-state.ts

@@ -9,18 +9,35 @@
  *   Without a retry policy it needs the user. With one (the Home's `-R` supervisor and the Child's
  *   own `-L` tunnel both run with one) a reason that has a delay is tried again at `retryAt`, and
  *   the retry attempt runs with `inFlight` while the state still reads failed; a reason without a
- *   delay stays terminal.
+ *   delay stays terminal. Each retry that fails again doubles the next delay, up to the policy's
+ *   `maxRetryDelayMs`; `retries` counts those failed retries (absent before the first one). A due
+ *   retry whose ssh could not even be started counts too (`failedSpawnTunnel`).
  */
 
 export type TunnelFailure = "auth" | "hostkey" | "forward" | "timeout";
-export type StderrClass = "auth" | "hostkey" | "forward" | "network" | "unknown";
+/**
+ * `remote_forward` is the Home's `-R` request refused by the peer's sshd: the port is still held,
+ * usually by an earlier session the peer has not dropped yet. It fails the link as `forward` and
+ * keeps the finer cause in `detail`.
+ */
+export type StderrClass = "auth" | "hostkey" | "forward" | "remote_forward" | "network" | "unknown";
+export type TunnelFailureDetail = "remote_forward_conflict";
 
 export type TunnelState =
   | { kind: "idle" }
   | { kind: "connecting"; since: number }
   | { kind: "connected"; since: number }
   | { kind: "reconnecting"; since: number; attempt: number; retryAt: number; inFlight: boolean }
-  | { kind: "failed"; since: number; reason: TunnelFailure; retryAt?: number; inFlight?: boolean };
+  | {
+    kind: "failed";
+    since: number;
+    reason: TunnelFailure;
+    retryAt?: number;
+    inFlight?: boolean;
+    /** Failed retries since the link failed; absent until the first retry fails. */
+    retries?: number;
+    detail?: TunnelFailureDetail;
+  };
 
 export type TunnelEvent =
   | { type: "spawn"; now: number }
@@ -29,9 +46,13 @@ export type TunnelEvent =
   | { type: "tick"; now: number }
   | { type: "stop" };
 
-/** Opt-in retry of a failed tunnel: the delay before each failure reason is tried again. */
+/**
+ * Opt-in retry of a failed tunnel: the first delay before each failure reason is tried again, and
+ * the cap the doubling delay of later retries stops at.
+ */
 export interface TunnelRetryPolicy {
   retryFailedAfterMs: Partial<Record<TunnelFailure, number>>;
+  maxRetryDelayMs?: number;
 }
 
 export const FAILED_AFTER_MS = 5 * 60_000;
@@ -39,19 +60,20 @@ export const BASE_DELAY_MS = 1_000;
 export const MAX_DELAY_MS = 30_000;
 
 /**
- * The client-owned tunnel's policy. Timeout and forward failures retry about once a minute. Auth
- * retries every five minutes, and because each auth failure schedules the next attempt five
- * minutes out, no more than 12 attempts reach the Home's sshd in an hour. A changed host key is a
- * security signal and is never retried.
+ * The client-owned tunnel's policy. Timeout and forward failures are first retried after a minute,
+ * and each retry that fails again doubles the delay up to five minutes (60, 120, 240, then every
+ * 300 seconds). Auth starts at the five-minute cap, so no more than 12 attempts reach the Home's
+ * sshd in an hour. A changed host key is a security signal and is never retried.
  */
 export const CLIENT_TUNNEL_RETRY_POLICY: TunnelRetryPolicy = {
   retryFailedAfterMs: { timeout: 60_000, forward: 60_000, auth: 5 * 60_000 },
+  maxRetryDelayMs: 5 * 60_000,
 };
 
 /**
  * The Home's `-R` supervisor dials the Child's sshd on the same cadence and limits. A sleep, an
- * outage longer than FAILED_AFTER_MS, or a forward the Child's sshd still holds for the session
- * that just died heals about a minute after it clears, instead of waiting for a proxy restart.
+ * outage longer than FAILED_AFTER_MS, or a forward the Child's sshd still holds for a session that
+ * died heals at most five minutes after it clears, instead of waiting for a proxy restart.
  */
 export const HOME_TUNNEL_RETRY_POLICY: TunnelRetryPolicy = CLIENT_TUNNEL_RETRY_POLICY;
 
@@ -65,23 +87,59 @@ export function nextDelayMs(attempt: number, random: () => number = Math.random)
   return Math.round(Math.min(MAX_DELAY_MS, base * jitter));
 }
 
+/** The delay before the next retry of `reason` after `retries` failed retries, or undefined. */
+export function failedRetryDelayMs(reason: TunnelFailure, retries: number, policy?: TunnelRetryPolicy): number | undefined {
+  const base = policy?.retryFailedAfterMs[reason];
+  if (base === undefined) return undefined;
+  const cap = Math.max(base, policy?.maxRetryDelayMs ?? base);
+  return Math.min(cap, base * 2 ** Math.max(0, Math.min(retries, 16)));
+}
+
 /** A failed state; under a policy that retries `reason` it carries the next attempt's time. */
 export function failedTunnel(
   reason: TunnelFailure,
   now: number,
   policy?: TunnelRetryPolicy,
   since: number = now,
+  options: { retries?: number; detail?: TunnelFailureDetail } = {},
 ): TunnelState {
-  const delay = policy?.retryFailedAfterMs[reason];
+  const retries = options.retries ?? 0;
+  const delay = failedRetryDelayMs(reason, retries, policy);
+  const extra = {
+    ...(retries > 0 ? { retries } : {}),
+    ...(options.detail ? { detail: options.detail } : {}),
+  };
   return delay === undefined
-    ? { kind: "failed", since, reason }
-    : { kind: "failed", since, reason, retryAt: now + delay, inFlight: false };
+    ? { kind: "failed", since, reason, ...extra }
+    : { kind: "failed", since, reason, retryAt: now + delay, inFlight: false, ...extra };
+}
+
+/**
+ * The state after an attempt whose ssh could not be started (ssh missing, a pidfile that cannot be
+ * written, no listener port). On a due retry of a failed link it counts as one more failed retry
+ * from the original moment and keeps the reason it was retrying: an attempt that reached no peer
+ * says nothing new about the link, so the backoff keeps its step and an auth failure keeps its
+ * five-minute cadence. Any other state fails fresh with `reason`.
+ */
+export function failedSpawnTunnel(
+  prior: TunnelState | undefined,
+  reason: TunnelFailure,
+  now: number,
+  policy?: TunnelRetryPolicy,
+): TunnelState {
+  if (prior?.kind !== "failed") return failedTunnel(reason, now, policy);
+  return failedTunnel(prior.reason, now, policy, prior.since, { retries: (prior.retries ?? 0) + 1, detail: prior.detail });
 }
 
 function failureOf(cls: StderrClass): TunnelFailure | null {
+  if (cls === "remote_forward") return "forward";
   return cls === "auth" || cls === "hostkey" || cls === "forward" ? cls : null;
 }
 
+function detailOf(cls: StderrClass): TunnelFailureDetail | undefined {
+  return cls === "remote_forward" ? "remote_forward_conflict" : undefined;
+}
+
 export function reduceTunnel(
   state: TunnelState,
   event: TunnelEvent,
@@ -104,11 +162,15 @@ export function reduceTunnel(
       if (state.kind === "failed") {
         if (!state.inFlight) return state;
         // A retry of a failed link failed again. It stays failed from the original moment; a
-        // transient exit keeps the slow cadence (timeout) instead of restarting fast backoff.
-        return failedTunnel(failureOf(event.stderrClass) ?? "timeout", event.now, policy, state.since);
+        // transient exit keeps the slow cadence (timeout) instead of restarting fast backoff, and
+        // the next delay doubles up to the policy's cap.
+        return failedTunnel(failureOf(event.stderrClass) ?? "timeout", event.now, policy, state.since, {
+          retries: (state.retries ?? 0) + 1,
+          detail: detailOf(event.stderrClass),
+        });
       }
       const failure = failureOf(event.stderrClass);
-      if (failure) return failedTunnel(failure, event.now, policy);
+      if (failure) return failedTunnel(failure, event.now, policy, event.now, { detail: detailOf(event.stderrClass) });
       const since = state.kind === "reconnecting" || state.kind === "connecting" ? state.since : event.now;
       if (event.now - since >= FAILED_AFTER_MS) return failedTunnel("timeout", event.now, policy);
       const attempt = state.kind === "reconnecting" ? state.attempt + 1 : 1;
@@ -137,7 +199,8 @@ export function classifySshStderr(stderr: string): StderrClass {
     || text.includes("no ecdsa host key is known") || text.includes("no ed25519 host key is known")
     || text.includes("no rsa host key is known") || text.includes("host key is known for")) return "hostkey";
   if (text.includes("permission denied") || text.includes("too many authentication failures")) return "auth";
-  if (text.includes("remote port forwarding failed") || text.includes("port forwarding failed")
+  if (text.includes("remote port forwarding failed")) return "remote_forward";
+  if (text.includes("port forwarding failed")
     || text.includes("address already in use") || text.includes("cannot listen to port")
     || text.includes("could not request local forwarding")) return "forward";
   if (text.includes("connection refused") || text.includes("timed out") || text.includes("could not resolve")

package/src/messaging/remote-files.ts

@@ -1,9 +1,24 @@
 import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync,
   realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { dirname, isAbsolute, join } from "node:path";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { remoteError, REMOTE_LIMITS } from "./remote-contract";
 
+/** macOS reports access ACLs separately from otherwise-private POSIX mode bits. */
+export function macAclOutputIsPrivate(output: string): boolean {
+  const lines = output.trimEnd().split("\n");
+  return lines.length === 1 && /^[d-][rwxStTs-]{9}[.@]?\s/.test(lines[0]!);
+}
+function checkMacAcl(path: string): void {
+  if (process.platform !== "darwin") return;
+  const result = spawnSync("/bin/ls", ["-lde", path], {
+    encoding: "utf8", timeout: 1_000, shell: false, windowsHide: true,
+    env: { ...process.env, LC_ALL: "C" },
+  });
+  if (result.error || result.status !== 0 || result.stderr || !macAclOutputIsPrivate(result.stdout)) throw new Error();
+}
+
 /** Check the entire path ancestry before using the private messaging subtree. */
 export function checkRemoteDirectory(path: string): void {
   checkDirectory(path, true);
@@ -17,6 +32,7 @@ function checkDirectory(path: string, privateLeaf: boolean): void {
     const final = lstatSync(path);
     if (!final.isDirectory() || final.isSymbolicLink()
       || (privateLeaf && (final.uid !== process.getuid!() || (final.mode & 0o077)))) throw new Error();
+    if (privateLeaf) checkMacAcl(path);
     // Root-controlled OS aliases (/tmp and /var on macOS) are not user-controlled redirects.
     for (let entry = path; ; entry = dirname(entry)) {
       const stat = lstatSync(entry);
@@ -81,6 +97,7 @@ export function readRemoteFile(path: string): string | null {
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid!() || (stat.mode & 0o077)
       || stat.size > REMOTE_LIMITS.storeBytes) throw new Error();
+    checkMacAcl(path);
     const bytes = Buffer.alloc(REMOTE_LIMITS.storeBytes + 1);
     let size = 0;
     while (size < bytes.length) { const count = readSync(fd, bytes, size, bytes.length - size, size); if (!count) break; size += count; }
@@ -98,8 +115,14 @@ export function writeRemoteFile(path: string, text: string, sync = fsyncSync): v
   const temporary = join(dirname(path), `.write-${crypto.randomUUID()}`);
   const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
   try {
-    try { writeFileSync(fd, text, "utf8"); sync(fd); } finally { closeSync(fd); }
+    try {
+      try { checkMacAcl(temporary); }
+      catch { throw remoteError("unsafe_remote_storage", "Cannot safely publish messaging state: temporary file ACL privacy could not be confirmed."); }
+      writeFileSync(fd, text, "utf8"); sync(fd);
+    } finally { closeSync(fd); }
     renameSync(temporary, path);
+    try { checkMacAcl(path); }
+    catch { throw remoteError("remote_storage_unknown", "Messaging state was replaced, but its ACL privacy and crash durability could not be confirmed; inspect state and permissions before explicit recovery."); }
     syncRemoteDirectory(dirname(path), sync);
   } finally { if (remotePathExists(temporary)) unlinkSync(temporary); }
 }

package/src/oauth/generic-account-failover.ts

@@ -260,9 +260,12 @@ function accountListsModel(providerName: string, accountId: string, model: strin
 /**
  * Model evidence only ranks accounts already eligible and below any configured cap.
  *
- * Kiro and Antigravity both gate models per account. For Antigravity (Claude 4.6 vs 5.5, Argon)
- * an account whose discovered roster lists the model wins; an account whose roster omits it is
- * skipped while any other remains; an account with no roster yet is unknown and stays usable.
+ * Kiro and Antigravity both gate models per account, but only Antigravity's roster is a gate
+ * (#7500). An account whose discovered roster lists the model wins; an account with no fresh
+ * roster is unknown and stays usable after it; an account whose fresh roster omits the model is
+ * never returned, so a field of only such accounts answers EMPTY rather than falling back to them.
+ * Callers treat empty as "no account to move to", and the transport refuses the request through
+ * {@link routeAntigravityModel}. Kiro listings remain a preference only.
  */
 export function preferKiroModelSupport(
   providerName: string, ids: string[], model?: string | null, config?: OcxConfig,
@@ -271,8 +274,7 @@ export function preferKiroModelSupport(
   if (providerName === "google-antigravity") {
     const positive = ids.filter(id => accountListsModel(providerName, id, model) === true);
     if (positive.length) return positive;
-    const notListedAgainst = ids.filter(id => accountListsModel(providerName, id, model) !== false);
-    return notListedAgainst.length ? notListedAgainst : ids;
+    return ids.filter(id => accountListsModel(providerName, id, model) !== false);
   }
   if (providerName !== "kiro") return ids;
   const cap = config?.providers?.kiro?.oauthAccountFailover?.maxConcurrentPerAccount;
@@ -282,6 +284,83 @@ export function preferKiroModelSupport(
   return positive.length ? positive : ids;
 }
 
+/** Where an Antigravity request may be sent, judged from per-account model discovery (#7500). */
+export type AntigravityModelRoute =
+  | { readonly kind: "keep" }
+  | { readonly kind: "reroute"; readonly accountId: string }
+  | { readonly kind: "refuse"; readonly message: string };
+
+const KEEP_ANTIGRAVITY_ROUTE: AntigravityModelRoute = { kind: "keep" };
+
+/** Client-facing refusal when no usable account's discovery lists the model. Mirrored in docs-site. */
+export function antigravityModelUnlistedMessage(model: string): string {
+  return `No usable Google Antigravity account lists the model "${model}" in its model discovery. `
+    + "Choose a model your accounts list, or add an account that has access to it.";
+}
+
+/** Client-facing refusal when the chosen account omits the model but a sibling may serve it. */
+export function antigravitySelectedAccountUnlistedMessage(model: string): string {
+  return `The selected Google Antigravity account does not list the model "${model}" in its model discovery. `
+    + "Select an account that lists it, or enable oauthAccountFailover so OpenCodex can choose one.";
+}
+
+/**
+ * Fail-closed model routing for Antigravity (#7500).
+ *
+ * `plannedAccountId` is the account the request would otherwise be sent with. It is kept unless
+ * its own fresh roster omits the model: absence of a roster is unknown, never a denial, because
+ * rosters live in memory, are refreshed only for the account active during discovery, and expire
+ * after six hours, so a restart must not take every account out of service.
+ *
+ * A planned account with a proven omission is replaced by a usable sibling (not paused, not
+ * flagged for reauth) that lists the model, then by one whose roster is unknown; siblings out
+ * of cooldown win over cooled ones within each tier. Moving a request before upstream refused it
+ * is a proactive choice, so a replacement needs {@link isProactivePreferenceEnabled}, exactly as
+ * Kiro's known-refusal exclusion does. Otherwise, or when no sibling qualifies, the request is
+ * refused locally instead of being sent to an account known not to serve the model.
+ */
+export function routeAntigravityModel(
+  config: OcxConfig,
+  providerName: string,
+  plannedAccountId: string | null | undefined,
+  model: string | null | undefined,
+  now = Date.now(),
+): AntigravityModelRoute {
+  if (providerName !== "google-antigravity" || !model || !plannedAccountId
+    || accountListsModel(providerName, plannedAccountId, model) !== false) return KEEP_ANTIGRAVITY_ROUTE;
+  const serving = (getAccountSet(providerName)?.accounts ?? [])
+    .filter(account => account.id !== plannedAccountId && account.paused !== true && account.needsReauth !== true)
+    .map(account => account.id)
+    .filter(id => accountListsModel(providerName, id, model) !== false);
+  if (serving.length === 0) return { kind: "refuse", message: antigravityModelUnlistedMessage(model) };
+  if (!isProactivePreferenceEnabled(config, providerName, now)) {
+    return { kind: "refuse", message: antigravitySelectedAccountUnlistedMessage(model) };
+  }
+  const ready = new Set(eligibleFailoverAccounts(providerName, now, classifyModelFamilyForQuota(providerName, model)));
+  const rank = (id: string) => (ready.has(id) ? 0 : 2) + (accountListsModel(providerName, id, model) === true ? 0 : 1);
+  const best = serving.reduce((left, right) => rank(right) < rank(left) ? right : left);
+  return { kind: "reroute", accountId: best };
+}
+
+/**
+ * Client-facing refusal when failover is on and a sibling may serve the model, but the request
+ * still resolved to an omitting account (the sibling could not be resolved or admitted).
+ */
+export function antigravityReplacementUnavailableMessage(model: string): string {
+  return `The selected Google Antigravity account does not list the model "${model}" in its model discovery, `
+    + "and no account that may serve it could be used for this request. Retry the request.";
+}
+
+/** The refusal for an account that already resolved, or null when it may serve the model. */
+export function antigravityModelRefusal(
+  config: OcxConfig, providerName: string, accountId: string, model: string | null | undefined, now = Date.now(),
+): string | null {
+  const verdict = routeAntigravityModel(config, providerName, accountId, model, now);
+  if (verdict.kind === "keep") return null;
+  // A reroute verdict exists only with failover on, so advising to enable it would be wrong.
+  return verdict.kind === "refuse" ? verdict.message : antigravityReplacementUnavailableMessage(model!);
+}
+
 function kiroModelListingHasRoom(config: OcxConfig, accountId: string, model: string): boolean {
   if (kiroAccountSupportsModel(accountId, model) !== true) return false;
   const cap = config.providers?.kiro?.oauthAccountFailover?.maxConcurrentPerAccount;
@@ -320,7 +399,11 @@ export function hasEligibleGenericOAuthFailoverTarget(
   const set = getAccountSet(providerName);
   if (!set || set.accounts.length < 2) return false;
   const family = classifyModelFamilyForQuota(providerName, requestedModelId);
-  return eligibleIdsIn(set, providerName, now, family).some(id => id !== failedAccountId);
+  // Same model filter rotation applies, so an Antigravity sibling whose roster omits the
+  // model is not advertised as a target rotation would then refuse to pick.
+  const siblings = eligibleIdsIn(set, providerName, now, family).filter(id => id !== failedAccountId);
+  return (providerName === "google-antigravity"
+    ? preferKiroModelSupport(providerName, siblings, requestedModelId) : siblings).length > 0;
 }
 
 /** Select a live Antigravity sibling using activation captured before the refused send. */
@@ -344,7 +427,8 @@ export function rotateAntigravityAccountOnAuthRefusal(
     });
     sweepExpiredOnWrite(now);
   }
-  const eligible = new Set(eligibleIdsIn(set, "google-antigravity", now, family));
+  const eligible = new Set(preferKiroModelSupport("google-antigravity",
+    eligibleIdsIn(set, "google-antigravity", now, family).filter(id => id !== failedAccountId), requestedModelId));
   const order = set.accounts.map(row => row.id);
   const start = order.indexOf(failedAccountId);
   const ring = start >= 0 ? [...order.slice(start + 1), ...order.slice(0, start)] : order;