@bitkyc08/opencodex 2.52.0 → 2.53.0

package/src/cli/remote-workspace.ts

@@ -0,0 +1,154 @@
+import type { RemoteWorkspaceDeviceState } from "../remote-control/workspace-device";
+import {
+  RemoteWorkspaceDeviceFileStore,
+  pairRemoteWorkspaceDevice,
+  remoteWorkspaceCapabilitiesForCommandRunner,
+  runRemoteWorkspaceAgent,
+  type PairRemoteWorkspaceDeviceOptions,
+  type RemoteWorkspaceAgentRunStatus,
+  type RemoteWorkspaceDeviceStateStore,
+} from "../remote-control/workspace-device";
+import { createPlatformRemoteWorkspaceCommandRunner } from "../remote-control/workspace-command-runner";
+import {
+  CliUsageError,
+  readSecretLine,
+  rejectArgs,
+  takeFlag,
+  takeJsonFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const REMOTE_WORKSPACE_USAGE = `Usage:
+  ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--root <absolute-path> ...] [--toolchain-root <absolute-directory> ...] [--executor-helper <absolute-file>] [--name <device-name>] [--json]
+  ocx remote-workspace agent
+  ocx remote-workspace status [--json]`;
+
+export interface RemoteWorkspaceCliDeps extends RuntimeApiDeps {
+  store?: RemoteWorkspaceDeviceStateStore;
+  pair?: (options: PairRemoteWorkspaceDeviceOptions) => Promise<RemoteWorkspaceDeviceState>;
+  runAgent?: typeof runRemoteWorkspaceAgent;
+  signal?: AbortSignal;
+  onStatus?: (status: RemoteWorkspaceAgentRunStatus) => void;
+}
+
+function takeRepeatedPathFlag(args: string[], flag: "--root" | "--toolchain-root"): string[] {
+  const roots: string[] = [];
+  for (;;) {
+    const index = args.indexOf(flag);
+    if (index < 0) break;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) throw new CliUsageError(`${flag} requires an absolute path`, REMOTE_WORKSPACE_USAGE);
+    roots.push(value);
+    args.splice(index, 2);
+  }
+  return roots;
+}
+
+function publicStatus(state: RemoteWorkspaceDeviceState | null): Record<string, unknown> {
+  if (!state) return { paired: false };
+  const capabilities = remoteWorkspaceCapabilitiesForCommandRunner(
+    createPlatformRemoteWorkspaceCommandRunner({
+      linux: {
+        toolchainRoots: state.toolchainRoots,
+        writableRoots: state.roots.map(root => root.path),
+      },
+      ...(state.nativeHelper ? { native: {
+        helper: state.nativeHelper,
+        toolchainRoots: state.toolchainRoots,
+        writableRoots: state.roots.map(root => root.path),
+      } } : {}),
+    }),
+    state.capabilities,
+  );
+  return {
+    paired: true,
+    hubUrl: state.hubUrl,
+    deviceId: state.deviceId,
+    deviceName: state.deviceName,
+    devicePlatform: state.devicePlatform,
+    capabilities,
+    roots: state.roots.map(root => ({ id: root.id, label: root.label, path: root.path })),
+    toolchainRoots: state.toolchainRoots,
+  };
+}
+
+export async function runRemoteWorkspaceCommand(rawArgs: string[], deps: RemoteWorkspaceCliDeps = {}): Promise<number> {
+  const args = [...rawArgs];
+  const command = args.shift();
+  const store = deps.store ?? new RemoteWorkspaceDeviceFileStore();
+  if (command === "status") {
+    const wantsJson = takeJsonFlag(args);
+    rejectArgs(args, REMOTE_WORKSPACE_USAGE);
+    const status = publicStatus(store.load());
+    if (wantsJson) console.log(JSON.stringify(status, null, 2));
+    else if (!status.paired) console.log("Remote Workspace executor is not paired.");
+    else {
+      console.log(`Remote Workspace executor: ${status.deviceName}`);
+      console.log(`Hub: ${status.hubUrl}`);
+      console.log(`Capabilities: ${(status.capabilities as string[]).join(", ")}`);
+      console.log(`Workspace roots: ${(status.roots as unknown[]).length}`);
+    }
+    return 0;
+  }
+  if (command === "pair") {
+    const wantsJson = takeJsonFlag(args);
+    const readCode = takeFlag(args, "--pairing-code-stdin");
+    const name = takeOption(args, "--name");
+    const nativeHelperPath = takeOption(args, "--executor-helper");
+    const roots = takeRepeatedPathFlag(args, "--root");
+    const toolchainRoots = takeRepeatedPathFlag(args, "--toolchain-root");
+    const hubUrl = args.shift();
+    if (!hubUrl || !readCode || roots.length === 0) throw new CliUsageError(
+      "pair requires <hub-url>, --pairing-code-stdin, and at least one --root",
+      REMOTE_WORKSPACE_USAGE,
+    );
+    rejectArgs(args, REMOTE_WORKSPACE_USAGE, { redactValues: true });
+    const pairingCode = await readSecretLine(deps, "Remote Workspace pairing code");
+    const state = await (deps.pair ?? pairRemoteWorkspaceDevice)({
+      hubUrl,
+      pairingCode,
+      ...(name ? { name } : {}),
+      roots: roots.map(path => ({ path })),
+      toolchainRoots,
+      ...(nativeHelperPath ? { nativeHelperPath } : {}),
+      store,
+    });
+    const status = publicStatus(state);
+    if (wantsJson) console.log(JSON.stringify(status, null, 2));
+    else {
+      console.log(`Paired ${state.deviceName} with ${state.hubUrl}.`);
+      console.log("Run `ocx remote-workspace agent` to keep this executor online.");
+    }
+    return 0;
+  }
+  if (command === "agent") {
+    rejectArgs(args, REMOTE_WORKSPACE_USAGE);
+    const state = store.load();
+    if (!state) throw new CliUsageError("Remote Workspace executor is not paired. Run the pair command first.", REMOTE_WORKSPACE_USAGE);
+    const controller = deps.signal ? null : new AbortController();
+    const signal = deps.signal ?? controller!.signal;
+    const stop = () => controller?.abort();
+    if (controller) {
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    }
+    try {
+      await (deps.runAgent ?? runRemoteWorkspaceAgent)({
+        state,
+        signal,
+        onStatus: deps.onStatus ?? (status => {
+          if (status.state === "online") console.log(`Remote Workspace executor online: ${state.deviceName}`);
+          if (status.state === "reconnecting" && status.message) console.error(`Remote Workspace reconnecting: ${status.message}`);
+        }),
+      });
+    } finally {
+      if (controller) {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+      }
+    }
+    return 0;
+  }
+  throw new CliUsageError("choose pair, agent, or status", REMOTE_WORKSPACE_USAGE);
+}

package/src/cli/status.ts

@@ -18,6 +18,7 @@ import { effectiveLoopbackListenerPort } from "../codex/loopback-target";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy, type ClaudeDesktopPolicyHealth } from "../claude/desktop-policy";
 import { collectClientConnectionStatus, type ClientConnectionStatus } from "./connect";
+import { readClientConnectionState, sameClientConnectionOwner } from "../client/state";
 import type { HubStateOAuthEntry, HubStateProvider } from "../remote/hub-state";
 import type { HubStateSource } from "../client/hub-state";
 import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
@@ -324,6 +325,35 @@ export function disconnectedRemoteHubStatus(): CliRemoteHubStatus {
   };
 }
 
+/**
+ * The data key this status snapshot may spend, and the cause when it may not.
+ *
+ * A reconnect or a rotation can replace both files between the snapshot and this read, so a
+ * matching cache owner alone does not authorize sending the current token. Withholding is only
+ * half the job: reporting every withheld case as "no usable data-plane token" is false for a
+ * client that reconnected and holds a perfectly good token for a different hub, and a cause the
+ * operator acts on has to be the real one (#4169 is the same defect in the stop path).
+ */
+function boundHubStateToken(
+  current: ReturnType<typeof readClientConnectionState>,
+  token: ReturnType<typeof readServiceApiTokenState>,
+  owner: { serverUrl: string; apiKeyId: string; connectedAt: string },
+): { token: string | null; withheldReason?: string } {
+  if (current.kind !== "connected") {
+    return { token: null, withheldReason: "this client is no longer connected" };
+  }
+  if (!sameClientConnectionOwner(current.value, owner)) {
+    return { token: null, withheldReason: "the saved connection no longer matches the one this status reports" };
+  }
+  if (token.kind !== "present") {
+    return { token: null, withheldReason: "this client has no usable data-plane token" };
+  }
+  if (token.fingerprint !== current.value.tokenFingerprint) {
+    return { token: null, withheldReason: "the data-plane token no longer belongs to the saved connection" };
+  }
+  return { token: token.token };
+}
+
 /**
  * Ask the hub what it can serve, with a bounded read and a cache fallback.
  *
@@ -340,14 +370,16 @@ export async function collectRemoteHubStatus(
     return disconnectedRemoteHubStatus();
   }
   const { resolveHubState } = await import("../client/hub-state");
-  const token = readServiceApiTokenState();
+  const owner = {
+    serverUrl: connection.serverUrl,
+    apiKeyId: connection.apiKeyId,
+    connectedAt: connection.connectedAt,
+  };
+  const bound = boundHubStateToken(readClientConnectionState(), readServiceApiTokenState(), owner);
   const resolved = await resolveHubState({
-    owner: {
-      serverUrl: connection.serverUrl,
-      apiKeyId: connection.apiKeyId,
-      connectedAt: connection.connectedAt,
-    },
-    token: token.kind === "present" ? token.token : null,
+    owner,
+    token: bound.token,
+    ...(bound.withheldReason ? { withheldTokenReason: bound.withheldReason } : {}),
     ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
     ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     ...(options.now === undefined ? {} : { now: options.now }),

package/src/cli/usage-report.ts

@@ -21,6 +21,10 @@ interface CostRow {
 }
 
 interface UsageReportInput {
+  source?: "hub";
+  scope?: "client";
+  usageIncomplete?: true;
+  usageIncompleteReason?: "oversized_rows";
   range?: string;
   surface?: string;
   since?: number | null;
@@ -109,11 +113,19 @@ function describeScope(data: UsageReportInput): string {
 export function formatUsageReport(data: UsageReportInput): string[] {
   const summary = data.summary ?? {};
   const lines: string[] = [describeScope(data), ""];
+  if (data.source === "hub" && data.scope === "client") {
+    lines.push("Source: hub — this client's data key only. Account totals are not shared.", "");
+  }
+  if (data.usageIncomplete === true) {
+    lines.push("WARNING: Usage is incomplete; some records could not be included. Totals and rankings reflect readable records only.", "");
+  }
 
   if (data.filter && !data.filter.matched) {
     const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
       .filter(Boolean).join(" and ");
-    lines.push(`No usage recorded for ${terminalText(what)} in this range.`);
+    lines.push(data.usageIncomplete === true
+      ? `No matching readable usage records for ${terminalText(what)} in this range; skipped records may contain matches.`
+      : `No usage recorded for ${terminalText(what)} in this range.`);
     lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
     return lines.map(terminalText);
   }
@@ -151,7 +163,7 @@ export function formatUsageReport(data: UsageReportInput): string[] {
   // server cannot answer it honestly.
   const accountFilterActive = Boolean(data.filter?.provider || data.filter?.model);
   const accounts = (data.accounts ?? []).filter(row => row.requests > 0);
-  if (accountFilterActive) {
+  if (accountFilterActive && data.scope !== "client") {
     lines.push("");
     lines.push("ACCOUNT: not reported under a provider or model filter; run without filters for per-account totals.");
   } else if (accounts.length > 0) {

package/src/client/hub-client.ts

@@ -1,5 +1,6 @@
 import { MAX_REMOTE_CATALOG_BYTES } from "../server/catalog-download";
 import { MAX_HUB_STATE_BYTES, parseHubStateBody, type HubStateDTO } from "../remote/hub-state";
+import { MAX_HUB_USAGE_BYTES, parseHubUsage, type HubUsageReport } from "../remote/hub-usage";
 import { readBoundedResponseBytes } from "../lib/bounded-body";
 import { clearableDeadline } from "../lib/abort";
 import type { Desktop3pModelEntry } from "../claude/desktop-3p";
@@ -472,6 +473,39 @@ export async function downloadClientCatalog(
   return { kind: "fresh", body, ...(keyId ? { keyId } : {}) };
 }
 
+/** Bounded own-key usage read; never falls back to a local management endpoint. */
+export async function fetchHubUsage(
+  serverUrl: string,
+  admissionToken: string,
+  query: URLSearchParams,
+  options: { timeoutMs?: number; fetchImpl?: typeof fetch } = {},
+): Promise<HubUsageReport> {
+  const origin = normalizeHubOrigin(serverUrl);
+  if (!isPairingTransportPermitted(origin)) {
+    throw new HubClientError("insecure_http_refused", "Client usage requires HTTPS or loopback HTTP");
+  }
+  const response = await fetchBounded(options.fetchImpl ?? fetch, `${origin}/v1/usage?${query}`, {
+    method: "GET",
+    cache: "no-store",
+    headers: new Headers({ Accept: "application/json", "x-opencodex-api-key": admissionToken }),
+  }, options.timeoutMs);
+  if (!response.ok) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    const message = response.status === 404 ? "Hub does not support client usage; upgrade the hub"
+      : response.status === 401 || response.status === 403 ? "Hub rejected this client's usage credential"
+      : `Hub usage request failed (${response.status})`;
+    throw new HubClientError(`hub_usage_http_${response.status}`, message, response.status);
+  }
+  if (!jsonCompatibleContentType(response)) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    throw new HubClientError("hub_usage_invalid", "Hub usage response was not JSON");
+  }
+  const text = await boundedText(response, MAX_HUB_USAGE_BYTES, { inactivityTimeoutMs: safeTimeout(options.timeoutMs) });
+  const report = parseHubUsage(parseJson(text, "hub_usage_invalid"));
+  if (!report) throw new HubClientError("hub_usage_invalid", "Hub usage response was invalid");
+  return report;
+}
+
 /**
  * Read the hub's provider/login/roster state with the per-client DATA key (#4236).
  *

package/src/client/hub-state.ts

@@ -161,6 +161,12 @@ export interface ResolveHubStateOptions {
   owner: HubStateOwner;
   /** The per-client data key. Null when the token file is missing or unsafe. */
   token: string | null;
+  /**
+   * Why the caller withheld the token, when it withheld one it holds. A null token reads the
+   * same here whether the file is missing or the caller declined to send a perfectly good
+   * token for a different connection, and the operator acts on that difference.
+   */
+  withheldTokenReason?: string;
   timeoutMs?: number;
   fetchImpl?: typeof fetch;
   now?: number;
@@ -195,7 +201,9 @@ export async function resolveHubState(options: ResolveHubStateOptions): Promise<
       ? withAge("cache", cached.state, cached.fetchedAt, now, reason)
       : withAge("unavailable", null, undefined, now, reason);
   };
-  if (!options.token) return fromCache("this client has no usable data-plane token");
+  if (!options.token) {
+    return fromCache(options.withheldTokenReason ?? "this client has no usable data-plane token");
+  }
   if (options.allowNetwork === false) return fromCache("a live hub read was not attempted");
   let state: HubStateDTO;
   try {

package/src/codex/account-store.ts

@@ -13,6 +13,8 @@ import {
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import type { CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
+import { isValidCodexAccountId } from "./account-id";
+import type { PoolQuotaWriter } from "./quota-types";
 import { CODEX_REFRESH_FLIGHT_CEILING_MS } from "./quota-recovery-timing";
 
 type LegacyCodexAccountStore = Record<string, CodexAccountCredentials>;
@@ -163,6 +165,7 @@ export function saveCodexAccountCredential(
       generation: (current?.generation ?? 0) + 1,
       refreshGrantFingerprint,
       replacedAt: current ? Date.now() : undefined,
+      quotaHistoryIdentity: crypto.randomUUID(),
       ...preservedValidationMetadata(current),
       ...(options.validationPending ? {
         codexValidationPending: true,
@@ -257,6 +260,75 @@ export function readCodexAccountRecord(id: string): CodexAccountCredentialRecord
   return loadCodexAccountRecordStore()[id] ?? null;
 }
 
+const QUOTA_HISTORY_IDENTITY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+function validQuotaHistoryIdentity(value: unknown): value is string {
+  return typeof value === "string" && QUOTA_HISTORY_IDENTITY_RE.test(value);
+}
+
+type DispatchedPoolCredential = Pick<CodexAccountCredentials, "accessToken" | "chatgptAccountId"> & { generation: number };
+
+function matchesDispatchedPoolCredential(record: CodexAccountCredentialRecord | undefined | null, dispatched: DispatchedPoolCredential): record is CodexAccountCredentialRecord & { credential: CodexAccountCredentials } {
+  return !!record?.credential && record.deletedAt == null
+    && dispatched.accessToken.length > 0 && dispatched.chatgptAccountId.length > 0
+    && Number.isSafeInteger(dispatched.generation) && dispatched.generation >= 0
+    && record.generation === dispatched.generation
+    && record.credential.accessToken === dispatched.accessToken
+    && record.credential.chatgptAccountId === dispatched.chatgptAccountId;
+}
+
+/** Optional evidence capture; a stale credential or unavailable store never gains a new writer. */
+export function capturePoolQuotaWriter(accountId: string, dispatched: DispatchedPoolCredential): PoolQuotaWriter | undefined {
+  if (!isValidCodexAccountId(accountId)) return undefined;
+  try {
+    const current = readCodexAccountRecord(accountId);
+    if (!matchesDispatchedPoolCredential(current, dispatched)) return undefined;
+    if (validQuotaHistoryIdentity(current.quotaHistoryIdentity)) {
+      return { accountId, credentialGeneration: dispatched.generation, historyIdentity: current.quotaHistoryIdentity };
+    }
+    return withCredentialMutationLockSync(() => {
+      const store = loadCodexAccountRecordStore();
+      const locked = store[accountId];
+      if (!matchesDispatchedPoolCredential(locked, dispatched)) return undefined;
+      if (!validQuotaHistoryIdentity(locked.quotaHistoryIdentity)) {
+        locked.quotaHistoryIdentity = crypto.randomUUID();
+        // Identity metadata is not a new credential; preserve generation and mutation epoch.
+        persist(store);
+      }
+      return { accountId, credentialGeneration: dispatched.generation, historyIdentity: locked.quotaHistoryIdentity };
+    });
+  } catch {
+    // History is optional evidence. Permission, lock and disk errors cannot fail inference.
+    return undefined;
+  }
+}
+
+/** Read-only retention identity; unlike capture this never initializes legacy metadata. */
+export function poolQuotaHistoryIdentity(accountId: string): string | undefined {
+  if (!isValidCodexAccountId(accountId)) return undefined;
+  try {
+    const record = readCodexAccountRecord(accountId);
+    return record?.credential && record.deletedAt == null && validQuotaHistoryIdentity(record.quotaHistoryIdentity)
+      ? record.quotaHistoryIdentity : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Recheck append admission after upstream I/O; refresh may retire a writer without erasing history. */
+export function isPoolQuotaWriterLive(writer: PoolQuotaWriter): boolean {
+  if (!isValidCodexAccountId(writer.accountId)) return false;
+  try {
+    const record = readCodexAccountRecord(writer.accountId);
+    return !!record?.credential && record.deletedAt == null
+      && record.generation === writer.credentialGeneration
+      && validQuotaHistoryIdentity(writer.historyIdentity)
+      && record.quotaHistoryIdentity === writer.historyIdentity;
+  } catch {
+    return false;
+  }
+}
+
 export function isCodexAccountGenerationLive(id: string, generation: number): boolean {
   const record = readCodexAccountRecord(id);
   return !!record?.credential && record.deletedAt == null && record.generation === generation;
@@ -281,6 +353,8 @@ export function saveCodexAccountCredentialIfGeneration(
       generation: generation + 1,
       refreshGrantFingerprint,
       replacedAt: current.replacedAt,
+      quotaHistoryIdentity: current.credential.chatgptAccountId === cred.chatgptAccountId
+        ? current.quotaHistoryIdentity : crypto.randomUUID(),
       ...preservedValidationMetadata(current),
     };
     persistCredentialMutation(store);
@@ -340,6 +414,8 @@ export function commitRefreshedCodexCredentialWithAliases(
       generation: generation + 1,
       refreshGrantFingerprint,
       replacedAt: current.replacedAt,
+      quotaHistoryIdentity: current.credential.chatgptAccountId === cred.chatgptAccountId
+        ? current.quotaHistoryIdentity : crypto.randomUUID(),
       ...preservedValidationMetadata(current),
     };
 
@@ -354,6 +430,7 @@ export function commitRefreshedCodexCredentialWithAliases(
       priorFingerprint !== undefined
       && priorCredential.refreshToken !== cred.refreshToken
       && !!priorCredential.chatgptAccountId
+      && priorCredential.chatgptAccountId === cred.chatgptAccountId
     ) {
       for (const [aliasId, alias] of Object.entries(store)) {
         if (aliasId === id || alias.deletedAt != null || !alias.credential) continue;
@@ -369,6 +446,7 @@ export function commitRefreshedCodexCredentialWithAliases(
           generation: aliasGeneration,
           refreshGrantFingerprint,
           replacedAt: alias.replacedAt,
+          quotaHistoryIdentity: alias.quotaHistoryIdentity,
           ...preservedValidationMetadata(alias),
         };
         propagatedAliases.push({ id: aliasId, generation: aliasGeneration });