@bitkyc08/opencodex 2.67.0-preview.20260926 → 2.68.0-preview.20260927

package/src/server/management/link-routes.ts

@@ -2,14 +2,14 @@ import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv } from "../../link/ssh-argv";
+import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../../link/ssh-argv";
 import { parseFingerprintLine } from "../../link/fingerprint";
 import { awaitFirstAdmission } from "../../link/admission-wait";
 import { linkKnownHostsPath, linkStorePath } from "../../link/paths";
 import { clearCompensationFailed, compensationPath, markCompensationFailed, readCompensation } from "../../link/compensation";
 import { loadHostCandidates } from "../../link/ssh-config";
 import { newLinkId, readLinkStore, writeLinkStore, type LinkStore } from "../../link/store";
-import { createSshRunner, type SshRunner } from "../../link/ssh-runner";
+import { boundHint, createSshRunner, sshFailureHint, sshRunnerErrorHint, type SshRunner, type SshRunResult } from "../../link/ssh-runner";
 import { projectLinkStatus, type LinkStatusDto } from "../../link/status-projection";
 import { isLinkPort } from "../../link/ports";
 import { joinHome, type ClientLinkJoinDeps } from "../../client/link-join";
@@ -17,11 +17,18 @@ import { clientLinkTunnelStatus } from "../../client/link-tunnel";
 import type { ManagementContext } from "./context";
 import { readManagementJsonBodyOr } from "./body";
 import { issueApiKeyInProcess, revokeApiKeyInProcess, type IssuedApiKey } from "./oauth-account-routes";
-import { acceptSystemRestart } from "./system-restart";
+import { acceptSystemRestart, resolveListenPort } from "./system-restart";
 
 const PROBE_TTL_MS = 5 * 60_000;
 const APPLY_ADMISSION_TIMEOUT_MS = 15_000;
 const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+// `ocx link` and `ocx connect --link` first shipped in 2.66.0; an older remote passes --version
+// and then fails at apply with remote_port_failed.
+const MIN_REMOTE_OCX = [2, 66, 0] as const;
+// A bounded semver shape: the parsed version reaches the confirm-host body and the outdated hint,
+// so the tail admits only a pre-release and build of semver identifier characters and must end
+// the token. Anything else attached to the version makes the output unrecognized.
+const REMOTE_OCX_VERSION = /^opencodex (\d{1,9})\.(\d{1,9})\.(\d{1,9})(-[0-9A-Za-z.-]{1,64})?(\+[0-9A-Za-z.-]{1,64})?(?=\s|$)/;
 const isLinkPath = (path: string): boolean => path === "/api/link" || path.startsWith("/api/link/");
 
 export interface PendingLinkHost {
@@ -55,8 +62,13 @@ const states = new WeakMap<object, LinkRouteState>();
 // One process runs at most one join: a join ends by restarting this process as a client.
 let joinInProgress = false;
 
-function fail(code: string, message: string, status: number): Response {
-  return Response.json({ error: { code, message } }, { status, headers: { "cache-control": "no-store" } });
+/**
+ * `hint` is one line bounded by `boundHint`: from ssh stderr (`sshFailureHint`), from the ssh
+ * runner's own failure (`sshRunnerErrorHint`), or the parsed remote version for
+ * `remote_ocx_outdated`. It is returned, never logged.
+ */
+function fail(code: string, message: string, status: number, hint?: string): Response {
+  return Response.json({ error: { code, message, ...(hint ? { hint } : {}) } }, { status, headers: { "cache-control": "no-store" } });
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -74,23 +86,54 @@ function port(value: unknown): value is number {
   return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
 }
 
-function dashboardSession(ctx: ManagementContext): boolean {
+/** A paired GUI session. Only hub runtimes issue these. */
+function pairedSession(ctx: ManagementContext): boolean {
   return ctx.principal === "gui-session"
     && ctx.sessionControl?.isPaired(ctx.req, ctx.config) === true;
 }
 
+/**
+ * A paired session, or on a standalone runtime the current loopback-issued session that reached
+ * the public listener bound to a loopback hostname. The loopback bootstrap mints that session
+ * without a credential, so this is casual-path protection like POST /api/github/star, not a
+ * secret-backed boundary like the admin token. Hubs keep the paired-only rule. Join admits this
+ * session too: turning a Child on from its own dashboard is the point of the route, and the
+ * dashboard warns first that the restart briefly interrupts running Codex turns.
+ */
+function dashboardSession(ctx: ManagementContext): boolean {
+  if (pairedSession(ctx)) return true;
+  return ctx.principal === "gui-session"
+    && (ctx.config.runtimeRole ?? "standalone") === "standalone"
+    && ctx.guiSessionIssuance === "loopback"
+    && ctx.trustedLoopbackIngress
+    && ctx.sessionControl?.isCurrent(ctx.req, ctx.config) === true;
+}
+
 function adminLoopback(ctx: ManagementContext): boolean {
   return ctx.principal === "admin-token" && ctx.trustedLoopbackIngress;
 }
 
 function auth(ctx: ManagementContext, kind: "dashboard" | "admin" | "either"): Response | null {
   if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403);
-  const dashboard = dashboardSession(ctx);
-  const admin = adminLoopback(ctx);
-  if ((kind === "dashboard" && !dashboard) || (kind === "admin" && !admin) || (kind === "either" && !dashboard && !admin)) {
-    return fail("forbidden", "The required link authorization was not present.", 403);
-  }
-  return null;
+  const allowed = kind === "dashboard" ? dashboardSession(ctx)
+    : kind === "admin" ? adminLoopback(ctx)
+      : dashboardSession(ctx) || adminLoopback(ctx);
+  return allowed ? null : fail("forbidden", "The required link authorization was not present.", 403);
+}
+
+/**
+ * The client runtime a join restarts into binds exactly the configured port, with no fallback.
+ * A standalone that runs elsewhere (`ocx start --port`, or a port fallback) would restart into a
+ * proxy that cannot bind where Codex is routed, so it may not join.
+ */
+function joinPortMatches(ctx: ManagementContext): boolean {
+  const live = (ctx.deps.liveListenPort ?? resolveListenPort)();
+  return live !== undefined && live === ctx.config.port;
+}
+
+/** Whether `POST /api/link/join` would pass its admission, role and port gates for this caller. */
+function joinAvailable(ctx: ManagementContext): boolean {
+  return dashboardSession(ctx) && (ctx.config.runtimeRole ?? "standalone") === "standalone" && joinPortMatches(ctx);
 }
 
 function runnerFor(ctx: ManagementContext): SshRunner {
@@ -220,16 +263,16 @@ async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Res
   const runner = runnerFor(ctx);
   try {
     const result = await runner.run(buildProbeArgv({ alias: body.alias, tempKnownHostsFile: tempKnownHosts }), { timeoutMs: 30_000 });
-    if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502);
+    if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr));
     const fingerprintResult = await runner.run(buildFingerprintArgv(tempKnownHosts), { timeoutMs: 10_000 });
-    if (fingerprintResult.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502);
+    if (fingerprintResult.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fingerprintResult.stderr));
     const parsed = parseFingerprintLine(fingerprintResult.stdout.trim());
     const knownHostLine = readFileSync(tempKnownHosts, "utf8").trim().split(/\r?\n/).filter(Boolean).at(-1);
     if (!knownHostLine) return fail("fingerprint_failed", "The SSH probe did not record a host key.", 502);
     state.pendingHosts.set(body.alias, { alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine, probedAt: (ctx.deps.now ?? Date.now)() });
     return Response.json({ alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType });
-  } catch {
-    return fail("probe_failed", "SSH host probing failed.", 502);
+  } catch (error) {
+    return fail("probe_failed", "SSH host probing failed.", 502, sshRunnerErrorHint(error));
   } finally {
     try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
   }
@@ -244,18 +287,43 @@ async function confirmHost(ctx: ManagementContext, state: LinkRouteState): Promi
   if (pending.fingerprint !== body.fingerprint) return fail("host_fingerprint_mismatch", "The confirmed fingerprint does not match the probe.", 409);
   const path = knownHostsFile(ctx);
   const before = putKnownHost(path, pending.alias, pending.knownHostLine);
+  // Every refusal restores known_hosts and keeps the pending probe, so a retry within its TTL works.
+  const refuse = (response: Response): Response => { restoreKnownHost(path, before); return response; };
+  let result: SshRunResult;
   try {
-    const result = await runnerFor(ctx).run(buildExecArgv({ alias: pending.alias, argv: ["ocx", "--version"], knownHostsFile: path }), { timeoutMs: 30_000 });
-    if (result.code !== 0 || !result.stdout.trim()) throw new Error("version probe failed");
-    const confirmed = { ...pending, ocxVersion: result.stdout.trim().split(/\r?\n/)[0]! };
-    state.confirmedHosts ??= new Map();
-    state.confirmedHosts.set(pending.alias, confirmed);
-    state.pendingHosts.delete(pending.alias);
-    return Response.json({ alias: pending.alias, fingerprint: pending.fingerprint, ocxVersion: confirmed.ocxVersion });
-  } catch {
-    restoreKnownHost(path, before);
-    return fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502);
+    result = await runnerFor(ctx).run(buildExecArgv({ alias: pending.alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+  } catch (error) {
+    return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshRunnerErrorHint(error)));
   }
+  if (result.code === REMOTE_COMMAND_NOT_FOUND) return refuse(fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr)));
+  if (result.code !== 0) return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshFailureHint(result.stderr)));
+  const version = parseRemoteOcxVersion(result.stdout);
+  if (!version) return refuse(fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502));
+  if (!meetsRemoteOcxFloor(version.parts)) {
+    return refuse(fail("remote_ocx_outdated", `The remote OpenCodex is older than ${MIN_REMOTE_OCX.join(".")}.`, 409, boundHint(`opencodex ${version.version}`)));
+  }
+  const confirmed = { ...pending, ocxVersion: version.version };
+  state.confirmedHosts ??= new Map();
+  state.confirmedHosts.set(pending.alias, confirmed);
+  state.pendingHosts.delete(pending.alias);
+  return Response.json({ alias: pending.alias, fingerprint: pending.fingerprint, ocxVersion: confirmed.ocxVersion });
+}
+
+/**
+ * `ocx --version` prints `opencodex <version>` first; a usage banner, an unbounded version tail or
+ * other output is refused.
+ */
+function parseRemoteOcxVersion(stdout: string): { version: string; parts: [number, number, number] } | null {
+  const match = REMOTE_OCX_VERSION.exec(stdout.trim().split(/\r?\n/)[0] ?? "");
+  if (!match) return null;
+  return { version: `${match[1]}.${match[2]}.${match[3]}${match[4] ?? ""}${match[5] ?? ""}`, parts: [Number(match[1]), Number(match[2]), Number(match[3])] };
+}
+
+function meetsRemoteOcxFloor(parts: readonly [number, number, number]): boolean {
+  for (let index = 0; index < MIN_REMOTE_OCX.length; index += 1) {
+    if (parts[index] !== MIN_REMOTE_OCX[index]) return parts[index]! > MIN_REMOTE_OCX[index]!;
+  }
+  return true;
 }
 
 function parsePortOutput(stdout: string): number | null {
@@ -274,11 +342,14 @@ async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Res
   const knownHosts = knownHostsFile(ctx);
   const runner = runnerFor(ctx);
   let remotePort: number;
+  let portHint: string | undefined;
   try {
-    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: ["ocx", "link", "port"], knownHostsFile: knownHosts }), { timeoutMs: 30_000 });
+    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["link", "port"]), knownHostsFile: knownHosts }), { timeoutMs: 30_000 });
+    if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr));
     remotePort = result.code === 0 ? parsePortOutput(result.stdout) ?? 0 : 0;
-  } catch { remotePort = 0; }
-  if (!port(remotePort)) return fail("remote_port_failed", "The remote link port could not be determined.", 502);
+    if (result.code !== 0) portHint = sshFailureHint(result.stderr);
+  } catch (error) { remotePort = 0; portHint = sshRunnerErrorHint(error); }
+  if (!port(remotePort)) return fail("remote_port_failed", "The remote link port could not be determined.", 502, portHint);
   let issued: IssuedApiKey;
   try { issued = issueKey(ctx, `link:${body.alias}`); }
   catch { return fail("key_issue_failed", "The link key could not be issued.", 503); }
@@ -309,11 +380,15 @@ async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Res
   const admission = awaitFirstAdmission(issued.id, APPLY_ADMISSION_TIMEOUT_MS, state.listener.onAuthenticatedCatalog);
   const input = new TextEncoder().encode(JSON.stringify({ apiKeyId: issued.id, key: issued.key }));
   try {
-    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: ["ocx", "connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id], knownHostsFile: knownHosts }), { stdin: input, timeoutMs: APPLY_ADMISSION_TIMEOUT_MS });
+    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id]), knownHostsFile: knownHosts }), { stdin: input, timeoutMs: APPLY_ADMISSION_TIMEOUT_MS });
     if (result.code !== 0) {
       void admission.catch(() => {});
       const compensation = await compensateNewLink(ctx, state, record);
-      return compensation ?? fail("remote_connect_failed", "The remote link connection failed.", 502);
+      if (compensation) return compensation;
+      const hint = sshFailureHint(result.stderr);
+      return result.code === REMOTE_COMMAND_NOT_FOUND
+        ? fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, hint)
+        : fail("remote_connect_failed", "The remote link connection failed.", 502, hint);
     }
     try {
       await admission;
@@ -322,10 +397,10 @@ async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Res
       return compensation ?? fail("admission_timeout", "The remote link did not authenticate a catalog request in time.", 502);
     }
     return Response.json({ linkId: id }, { status: 202 });
-  } catch {
+  } catch (error) {
     void admission.catch(() => {});
     const compensation = await compensateNewLink(ctx, state, record);
-    return compensation ?? fail("remote_connect_failed", "The remote link connection failed.", 502);
+    return compensation ?? fail("remote_connect_failed", "The remote link connection failed.", 502, sshRunnerErrorHint(error));
   } finally {
     input.fill(0);
   }
@@ -362,6 +437,7 @@ async function issue(ctx: ManagementContext): Promise<Response> {
       failureCode = "listener_unavailable";
       throw new Error("link listener unavailable");
     }
+    await state.supervisor.ensureStarted();
     const boundStore = readStoreFor(ctx);
     if (!port(boundStore.listenerPort)) throw new Error("link listener did not bind");
     return Response.json({ linkId: id, apiKeyId: issued.id, key: issued.key, listenerPort: boundStore.listenerPort });
@@ -383,11 +459,13 @@ type ManagementApiDepsWithJoinOverrides = ManagementContext["deps"] & LinkJoinRo
 
 function joinFailure(error: unknown): Response {
   const code = error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : "";
+  const hint = error && typeof error === "object" && "hint" in error && typeof error.hint === "string" ? error.hint : undefined;
   switch (code) {
     case "host_not_confirmed": return fail("host_not_confirmed", "Confirm the SSH host before joining the link.", 409);
     case "host_confirmation_expired": return fail("host_confirmation_expired", "The SSH host confirmation has expired.", 409);
     case "join_port_failed": return fail("join_port_failed", "No local port is available for the link tunnel.", 503);
-    case "join_issue_failed": return fail("join_issue_failed", "The home could not issue a link.", 502);
+    case "join_issue_failed": return fail("join_issue_failed", "The home could not issue a link.", 502, hint);
+    case "remote_ocx_missing": return fail("remote_ocx_missing", "ocx was not found on the home.", 502, hint);
     case "join_tunnel_failed": return fail("join_tunnel_failed", "The SSH tunnel to the home did not become ready.", 502);
     case "admission_failed": return fail("admission_failed", "The home refused the issued link key.", 502);
     case "join_rollback_failed": {
@@ -442,14 +520,14 @@ async function remove(ctx: ManagementContext, state: LinkRouteState, id: string)
   };
   if (!force && record.direction === "hub-initiated") {
     try {
-      const result = await runnerFor(ctx).run(buildExecArgv({ alias: record.alias, argv: ["ocx", "disconnect"], knownHostsFile: knownHostsFile(ctx) }), { timeoutMs: 30_000 });
+      const result = await runnerFor(ctx).run(buildExecArgv({ alias: record.alias, argv: remoteOcxArgv(["disconnect"]), knownHostsFile: knownHostsFile(ctx) }), { timeoutMs: 30_000 });
       if (result.code !== 0) {
         await restartTunnel();
-        return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502);
+        return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshFailureHint(result.stderr));
       }
-    } catch {
+    } catch (error) {
       await restartTunnel();
-      return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502);
+      return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshRunnerErrorHint(error));
     }
   }
   if (!revokeKeyIdempotent(ctx, record.apiKeyId)) return fail("key_revoke_failed", "The link key could not be revoked.", 502);
@@ -471,9 +549,12 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
   if (!isLinkPath(path)) return null;
   if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403);
   if (url.pathname === "/api/link/join" && req.method === "POST") {
+    // The same dashboard admission as the Home side. Every refusal below runs before link state
+    // is read and before any SSH.
     const denied = auth(ctx, "dashboard");
     if (denied) return denied;
     if ((ctx.config.runtimeRole ?? "standalone") !== "standalone") return fail("standalone_required", "Client initiated links require standalone runtime mode.", 409);
+    if (!joinPortMatches(ctx)) return fail("join_port_mismatch", "OpenCodex is not running on its configured port, so it cannot restart as a Child.", 409);
     const state = suppliedState ?? stateFor(ctx);
     if (!state) return fail("link_unavailable", "The link lifecycle is unavailable.", 503);
     return handleJoin(ctx, state);
@@ -497,7 +578,10 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
       const failure = state.compensationFailures?.get(store.links[0].id);
       if (failure) Object.assign(dto.child, { state: "failed" as const, since: failure.since, reason: failure.reason });
     }
-    return Response.json(dto, { headers: { "cache-control": "no-store" } });
+    // A dashboard session also learns whether it may join as a Child. The admin-token answer stays
+    // the exact K16 document that `ocx link status` validates key by key.
+    const body: LinkStatusDto & { joinAvailable?: boolean } = ctx.principal === "gui-session" ? { ...dto, joinAvailable: joinAvailable(ctx) } : dto;
+    return Response.json(body, { headers: { "cache-control": "no-store" } });
   }
   if (url.pathname === "/api/link/candidates" && req.method === "GET") {
     const denied = auth(ctx, "dashboard");

package/src/server/management/logs-usage-routes.ts

@@ -67,7 +67,7 @@ import {
 } from "../../lib/debug-settings";
 import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
-import { filterRequestLogs, filteredRequestLogCount, getRequestLogEntries, type RequestLogEntry } from "../request-log";
+import { getRequestLogEntries, queryRequestLogs, type RequestLogEntry } from "../request-log";
 import { decodeRequestLogCursor, selectRequestLogPoll } from "../request-log-cursor";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
 import { userCostOverlayVersion } from "../../usage/user-cost-overlays";
@@ -120,11 +120,12 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
       return jsonResponse({ error: { code: "invalid_cursor", message: "invalid cursor" } }, 400);
     }
     const all = getRequestLogEntries();
-    const total = filteredRequestLogCount(all, url.searchParams);
+    const queried = queryRequestLogs(all, url.searchParams);
+    const total = queried.total;
     // Not point-free: requestLogDto takes an options object second, and Array.map would pass the
     // element INDEX into it. An explicit arrow keeps the default (decode rate included) and is
     // what /api/logs wants; /api/request-history opts out at its own call sites.
-    const logs = filterRequestLogs(all, url.searchParams).map(entry => requestLogDto(entry));
+    const logs = queried.logs.map(entry => requestLogDto(entry));
     const poll = selectRequestLogPoll(logs, url.searchParams, cursor);
     return jsonResponse({
       timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
@@ -347,45 +348,11 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
       }
       return jsonResponse(requestedSummary);
     } catch {
-      return jsonResponse({
-        range,
-        surface,
-        since: window?.since ?? null,
-        ...(window ? { customWindow: true, until: window.until } : {}),
-        generatedAt: now,
-        summary: {
-          requests: 0,
-          attemptCount: 0,
-          measuredRequests: 0,
-          reportedRequests: 0,
-          unreportedRequests: 0,
-          unsupportedRequests: 0,
-          estimatedRequests: 0,
-          inputTokens: 0,
-          outputTokens: 0,
-          cachedInputTokens: 0,
-          cacheReadInputTokens: 0,
-          cacheCreationInputTokens: 0,
-          reasoningOutputTokens: 0,
-          totalTokens: 0,
-          coverageRatio: 0,
-          estimatedCostUsd: 0,
-          pricedRequests: 0,
-          unpricedRequests: 0,
-          unmeteredRequests: 0,
-        },
-        days: [],
-        models: [],
-        providers: [],
-        accounts: [],
-        historyTruncated: false,
-        truncatedPrefixBytes: 0,
-        entriesTruncated: false,
-        entriesDropped: 0,
-        snapshotWindowStart: null,
-        snapshotWindowEnd: null,
-        error: "read_failed",
-      });
+      // A missing ledger is handled as an empty installation by the reader. Reaching this catch
+      // therefore means the report is unavailable, not that usage was measured as zero. Keep the
+      // transport status aligned with the JEV projection above so every dashboard consumer can
+      // retain its last valid snapshot instead of caching fabricated zero totals.
+      return jsonResponse({ error: "read_failed" }, 500);
     }
   }
 

package/src/server/management/model-rows.ts

@@ -241,6 +241,7 @@ export function toExportModel(row: ManagementModelRow): ExportModel {
     ...(row.native ? { native: true } : {}),
     ...(row.displayName && row.displayNameSource !== "fallback" ? { displayName: row.displayName } : {}),
     ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
+    ...(row.maxOutputTokens !== undefined ? { maxTokens: row.maxOutputTokens } : {}),
     ...(row.inputModalities ? { inputModalities: row.inputModalities } : {}),
     ...(row.reasoningEfforts ? { reasoningEfforts: row.reasoningEfforts } : {}),
     ...(row.defaultReasoningEffort ? { defaultReasoningEffort: row.defaultReasoningEffort } : {}),

package/src/server/management/oauth-account-routes.ts

@@ -24,6 +24,7 @@ import {
   submitManualLoginCode,
 } from "../../oauth";
 import { OAuthMutationBusyError, removeCredential } from "../../oauth/store";
+import { cancelKiroDeviceLogin, kiroDeviceConfigBaseline, startKiroDeviceLogin, statusKiroDeviceLogin, type KiroDeviceMethod } from "../../oauth/kiro-device-login";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { emailMaskingEnabled } from "../../lib/privacy";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
@@ -186,8 +187,12 @@ export function revokeApiKeyInProcess(config: OcxConfig, id: string): boolean {
   return true;
 }
 
+function canStartManagementOAuth(provider: string, principal: ManagementContext["principal"]): boolean {
+  return provider !== "meta-muse" || principal === "gui-session";
+}
+
 function metaMuseConsentRequired(provider: string, principal: ManagementContext["principal"]): Response | null {
-  if (provider !== "meta-muse" || principal === "gui-session") return null;
+  if (canStartManagementOAuth(provider, principal)) return null;
   return jsonResponse({
     error: "Meta Muse login requires acknowledgement in the OpenCodex dashboard.",
     code: "oauth_consent_required",
@@ -204,7 +209,9 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
 
   // Which providers support real OAuth login (drives the GUI's "Log in with …" buttons).
   if (url.pathname === "/api/oauth/providers" && req.method === "GET") {
-    return jsonResponse({ providers: listOAuthProviders() });
+    // Discovery reflects this principal's admission; hiding a button is not the
+    // consent boundary, which remains independently enforced on both POST routes.
+    return jsonResponse({ providers: listOAuthProviders().filter(provider => canStartManagementOAuth(provider, principal)) });
   }
 
   // API-key "login" providers (open dashboard → paste key). Drives the GUI's key-provider picker.
@@ -216,7 +223,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
   // the provider's loopback callback server (inside this process) captures the redirect in the
   // background, then the credential is persisted. The GUI opens the URL and polls /api/oauth/status.
   if (url.pathname === "/api/oauth/login" && req.method === "POST") {
-    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; addAccount?: boolean; accountId?: string; reauth?: boolean; openBrowser?: unknown };
+    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; addAccount?: boolean; accountId?: string; reauth?: boolean; openBrowser?: unknown; method?: unknown };
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
     // Muse may import a local Keychain credential or start a device grant; add-account
@@ -229,6 +236,20 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     if (namespaceCollision) return jsonResponse({ error: namespaceCollision }, 409);
     const accountId = body.accountId?.trim();
     const reauth = body.reauth === true || Boolean(accountId);
+    if (provider === "kiro") {
+      if (reauth && !accountId) return jsonResponse({ error: "Kiro reauth requires an accountId" }, 400);
+      if (body.method !== undefined) {
+        if (body.method !== "builder-id" && body.method !== "google" && body.method !== "github") {
+          return jsonResponse({ error: "invalid Kiro device method" }, 400);
+        }
+        if (reauth) return jsonResponse({ error: "native_login_is_add_only" }, 400);
+        try {
+          return jsonResponse(await startKiroDeviceLogin(body.method as KiroDeviceMethod, principal ?? "admin-token", readConfigDiagnostics().config));
+        } catch {
+          return jsonResponse({ error: "Kiro device login could not start" }, 409);
+        }
+      }
+    }
     try {
       if (accountId) {
         const { getAccountSet } = await import("../../oauth/store");
@@ -281,9 +302,14 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
   // Cancel an in-progress browser/device OAuth login (GUI "Cancel" / modal close). Guarded by
   // the same public predicate as /api/oauth/login — only publicly startable flows are cancellable.
   if (url.pathname === "/api/oauth/login/cancel" && req.method === "POST") {
-    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string };
+    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; flowId?: unknown };
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    if (provider === "kiro" && body.flowId !== undefined) {
+      if (typeof body.flowId !== "string") return jsonResponse({ error: "unknown login flow" }, 404);
+      const result = cancelKiroDeviceLogin(body.flowId, principal ?? "admin-token");
+      return result ? jsonResponse(result) : jsonResponse({ error: "unknown login flow" }, 404);
+    }
     const { cancelLoginFlow } = await import("../../oauth");
     const cancelled = cancelLoginFlow(provider);
     return jsonResponse({ ok: true, cancelled });
@@ -309,6 +335,17 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
   if (url.pathname === "/api/oauth/status" && req.method === "GET") {
     const provider = (url.searchParams.get("provider") ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    if (provider === "kiro" && url.searchParams.has("flowId")) {
+      const flowId = url.searchParams.get("flowId") ?? "";
+      const baseline = kiroDeviceConfigBaseline(flowId, principal ?? "admin-token");
+      const status = await statusKiroDeviceLogin(flowId, principal ?? "admin-token");
+      if (!status) return jsonResponse({ error: "unknown login flow" }, 404);
+      if (status.state === "done") {
+        reconcileLiveConfigFromDisk(config, baseline ?? structuredClone(config));
+        reconcileLiveStateStores();
+      }
+      return jsonResponse(status);
+    }
     // Resolved here, at the request boundary that already holds the config, and passed down.
     // getLoginStatus stays free of config I/O. This route does not re-mask afterwards: it
     // consumes the already-projected status rather than redacting a second time.
@@ -347,6 +384,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const quotaMode = providerOAuthAccountQuotaMode(provider);
     const quotaProvider = config.providers[provider];
     const { getAccountSet } = await import("../../oauth/store");
+    const { kiroAutoSelection } = await import("../../oauth/generic-account-failover");
     const {
       oauthAccountHealthFields,
       projectOAuthAccountHealth,
@@ -365,7 +403,8 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
               needsReauth: summary.needsReauth === true,
               reauthReason: summary.needsReauth === true ? "refresh_failed" : undefined,
             });
-          return { ...summary, ...oauthAccountHealthFields(provider, summary.id, health), quotaMode };
+          return { ...summary, ...oauthAccountHealthFields(provider, summary.id, health), quotaMode,
+            ...(provider === "kiro" && full ? kiroAutoSelection(full) : {}) };
         }),
       };
     };
@@ -439,14 +478,14 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
   // them that kind honours.
   if (url.pathname === "/api/pool/settings" && (req.method === "GET" || req.method === "PUT" || req.method === "PATCH")) {
     const {
-      poolSettingsCapability, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold, parseGenericStickyLimit,
+      poolSettingsCapability, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold, parseGenericStickyLimit, parseKiroAccountCap,
       unifiedPoolSettingsDto,
     } = await import("../../oauth/pool-settings-capability");
     const rawBody = req.method === "GET" ? {} : await readManagementJsonBodyOr(req, {});
     if (req.method !== "GET" && !isPlainRecord(rawBody)) {
       return jsonResponse({ error: "body must be an object" }, 400);
     }
-    const fields = rawBody as { provider?: unknown; enabled?: unknown; strategy?: unknown; stickyLimit?: unknown; autoSwitchThreshold?: unknown; quotaWindow?: unknown };
+    const fields = rawBody as { provider?: unknown; enabled?: unknown; strategy?: unknown; stickyLimit?: unknown; autoSwitchThreshold?: unknown; quotaWindow?: unknown; maxConcurrentPerAccount?: unknown };
     const provider = req.method === "GET"
       ? (url.searchParams.get("provider") ?? "").trim().toLowerCase()
       : (typeof fields.provider === "string" ? fields.provider.trim().toLowerCase() : "");
@@ -458,10 +497,10 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     // sticky limit is refused identically whichever pool is addressed.
     let strategy: string | undefined;
     if (fields.strategy !== undefined) {
-      const parsed = kind === "codex" ? parseCodexAccountPoolStrategy(fields.strategy) : parseGenericPoolStrategy(fields.strategy);
+      const parsed = kind === "codex" ? parseCodexAccountPoolStrategy(fields.strategy) : parseGenericPoolStrategy(fields.strategy, provider);
       if (parsed === null) return jsonResponse({ error: kind === "codex"
         ? "strategy must be one of: quota, round-robin, fill-first, reset-first"
-        : "strategy must be one of: quota, round-robin, fill-first" }, 400);
+        : `strategy must be one of: quota, round-robin, fill-first${provider === "kiro" ? ", least-loaded" : ""}` }, 400);
       strategy = parsed;
     }
     let stickyLimit: number | undefined;
@@ -489,6 +528,12 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       if (kind === "codex") return jsonResponse({ error: "enabled is not part of the codex pool contract" }, 400);
       if (typeof fields.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
     }
+    let accountCap: number | null | undefined;
+    if (fields.maxConcurrentPerAccount !== undefined) {
+      if (provider !== "kiro" || kind !== "generic") return jsonResponse({ error: "maxConcurrentPerAccount is only supported for Kiro OAuth" }, 400);
+      accountCap = fields.maxConcurrentPerAccount === null ? null : parseKiroAccountCap(fields.maxConcurrentPerAccount);
+      if (accountCap === null && fields.maxConcurrentPerAccount !== null) return jsonResponse({ error: "maxConcurrentPerAccount must be an integer 1-100 or null" }, 400);
+    }
 
     if (req.method !== "GET") {
       if (kind === "codex") {
@@ -508,6 +553,8 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
         const next = { ...(prov.oauthAccountFailover ?? {}) };
         if (fields.enabled !== undefined) next.enabled = fields.enabled as boolean;
         if (strategy !== undefined) next.strategy = strategy as never;
+        if (accountCap === null) delete next.maxConcurrentPerAccount;
+        else if (accountCap !== undefined) next.maxConcurrentPerAccount = accountCap;
         if (stickyLimit !== undefined) next.stickyLimit = stickyLimit;
         if (autoSwitchThreshold !== undefined) next.autoSwitchThreshold = autoSwitchThreshold;
         if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
@@ -558,12 +605,13 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       strategy?: unknown;
       stickyLimit?: unknown;
       quotaWindow?: unknown;
+      maxConcurrentPerAccount?: unknown;
     };
     const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
     if (provider !== "anthropic") {
       const {
         poolSettingsCapability, genericPoolSettingsDto, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold,
-        parseGenericStickyLimit,
+        parseGenericStickyLimit, parseKiroAccountCap,
       } = await import("../../oauth/pool-settings-capability");
       const prov = config.providers[provider];
       if (!provider || !prov || poolSettingsCapability(provider, prov) !== "generic") {
@@ -580,8 +628,8 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       if (body.strategy !== undefined) {
         if (body.strategy === null) delete next.strategy;
         else {
-          const parsed = parseGenericPoolStrategy(body.strategy);
-          if (parsed === null) return jsonResponse({ error: "strategy must be one of: quota, round-robin, fill-first" }, 400);
+          const parsed = parseGenericPoolStrategy(body.strategy, provider);
+          if (parsed === null) return jsonResponse({ error: `strategy must be one of: quota, round-robin, fill-first${provider === "kiro" ? ", least-loaded" : ""}` }, 400);
           next.strategy = parsed;
         }
       }
@@ -601,6 +649,13 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
           next.stickyLimit = parsed;
         }
       }
+      if (body.maxConcurrentPerAccount !== undefined) {
+        if (provider !== "kiro") return jsonResponse({ error: "maxConcurrentPerAccount is only supported for Kiro OAuth" }, 400);
+        const cap = body.maxConcurrentPerAccount === null ? null : parseKiroAccountCap(body.maxConcurrentPerAccount);
+        if (cap === null && body.maxConcurrentPerAccount !== null) return jsonResponse({ error: "maxConcurrentPerAccount must be an integer 1-100 or null" }, 400);
+        if (cap === null) delete next.maxConcurrentPerAccount;
+        else next.maxConcurrentPerAccount = cap;
+      }
       if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
       else delete prov.oauthAccountFailover;
       saveConfigPreservingClaudeCode(config);

package/src/server/management/route-registry.ts

@@ -368,11 +368,11 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/storage/codex-logs/unprotect", module: "server/management/storage-log-guard-routes", mutates: true },
   // server/management/link-routes
   { method: "GET", path: "/api/link/status", module: "server/management/link-routes", mutates: false },
-  { method: "GET", path: "/api/link/candidates", module: "server/management/link-routes", mutates: false, exempt: { reason: "session-only", why: "SSH candidates are a dashboard pairing surface and are withheld from admin-token and Tailscale identity sessions." } },
-  { method: "POST", path: "/api/link/probe", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "SSH probing and host-key presentation are part of the interactive pairing consent flow." } },
-  { method: "POST", path: "/api/link/confirm-host", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Persisting a host key requires the paired dashboard session that saw the fingerprint." } },
-  { method: "POST", path: "/api/link/join", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Joining a confirmed Home issues a link credential and restarts this standalone runtime as a client." } },
-  { method: "POST", path: "/api/link/apply", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Applying a link issues a data key and starts a remote tunnel, so it requires the paired dashboard session." } },
+  { method: "GET", path: "/api/link/candidates", module: "server/management/link-routes", mutates: false, exempt: { reason: "session-only", why: "SSH candidates are a dashboard surface: a paired session, or on a standalone runtime the current loopback dashboard session on trusted loopback ingress; admin-token and Tailscale identity sessions are refused." } },
+  { method: "POST", path: "/api/link/probe", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "SSH probing and host-key presentation are part of the interactive dashboard consent flow (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
+  { method: "POST", path: "/api/link/confirm-host", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Persisting a host key requires the dashboard session that saw the fingerprint (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
+  { method: "POST", path: "/api/link/join", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Joining a confirmed Home issues a link credential and restarts this standalone runtime as a client on its configured port, which briefly interrupts running Codex turns. It is the dashboard's turn-on flow with a pre-join notice (paired, or standalone loopback dashboard on trusted loopback ingress); admin-token and Tailscale identity sessions are refused." } },
+  { method: "POST", path: "/api/link/apply", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Applying a link issues a data key and starts a remote tunnel, so it requires a dashboard session (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
   { method: "DELETE", path: "/api/link/{id}", module: "server/management/link-routes", mutates: true, mechanism: "regex" },
   { method: "POST", path: "/api/link/issue", module: "server/management/link-routes", mutates: true },
   // server/management/remote-workspace-routes