@bitkyc08/opencodex 2.7.27 → 2.7.28

package/src/server/management-api.ts

@@ -30,6 +30,8 @@ import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { clearThreadAccountMap } from "../codex/routing";
 import { primeCodexPoolQuotas } from "../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../providers/context-cap";
+import { resolveCodexHomeDir } from "../codex/home";
+import { scanStorage } from "../storage/scanner";
 import { readUsageEntries } from "../usage/log";
 import { getUsageDebugLogEntries } from "../usage/debug";
 import { parseRange, parseUsageSurface, summarizeUsage } from "../usage/summary";
@@ -46,7 +48,9 @@ import {
 } from "../lib/debug-settings";
 import type { OcxClaudeCodeConfig, OcxConfig, OcxProviderConfig } from "../types";
 import { drainAndShutdown } from "./lifecycle";
-import { filterRequestLogs, getRequestLogEntries } from "./request-log";
+import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "./request-log";
+import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../usage/cost";
+import type { PersistedUsageAttempt } from "../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
 import { applySystemEnvToggle } from "./system-env";
 
@@ -82,6 +86,96 @@ function parseDebugLogQuery(url: URL): { after: number; limit: number } {
   };
 }
 
+// ---- /api/logs display metrics (devlog/_plan/260720_toks_speed_price_columns/020) ----
+// Derived at response time only; NEVER persisted to the request log or usage.jsonl.
+
+type MetricUnavailableReason =
+  | "usage_missing" | "usage_unsupported" | "output_missing" | "invalid_duration"
+  | "price_unmatched" | "invalid_cache_breakdown"
+  | "invalid_usage" | "combo_attempt_unavailable";
+
+type TokPerSecondResult =
+  | { kind: "value"; value: number; estimated: boolean }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+type CostEstimateReason = "usage_estimated" | "cache_detail_missing" | "expected_price_overlay";
+
+type CostResult =
+  | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage"> & {
+  attempts?: readonly PersistedUsageAttempt[];
+};
+
+function tokPerSecondResult(entry: Pick<MetricSource, "durationMs" | "usageStatus" | "usage">): TokPerSecondResult {
+  if (!entry.usage) return { kind: "unavailable", reason: "usage_missing" };
+  if (entry.usageStatus === "unsupported") return { kind: "unavailable", reason: "usage_unsupported" };
+  const value = tokensPerSecond(entry.usage.outputTokens, entry.durationMs);
+  if (value === null) {
+    return {
+      kind: "unavailable",
+      reason: entry.usage.outputTokens <= 0 ? "output_missing" : "invalid_duration",
+    };
+  }
+  return { kind: "value", value, estimated: entry.usageStatus === "estimated" || entry.usage.estimated === true };
+}
+
+function unavailableCostReason(entry: MetricSource): MetricUnavailableReason {
+  // Normalizer-first classification: the landed normalizer recovers legacy
+  // cachedInputTokens=read+write rows via retry, so a raw read+write>input
+  // pre-check would misclassify recoverable rows (020 audit blocker #2).
+  if (!entry.usage && !entry.attempts?.length) return "usage_missing";
+  if (entry.usageStatus === "unsupported") return "usage_unsupported";
+  if (entry.attempts?.length) return "combo_attempt_unavailable";
+  if (!entry.usage) return "usage_missing";
+  if (!normalizeCostTokens(entry.usage)) {
+    const effectiveRead = entry.usage.cacheReadInputTokens ?? entry.usage.cachedInputTokens ?? 0;
+    const effectiveWrite = entry.usage.cacheCreationInputTokens ?? 0;
+    const finite = [entry.usage.inputTokens, entry.usage.outputTokens, effectiveRead, effectiveWrite]
+      .every(v => Number.isFinite(v) && v >= 0);
+    return finite ? "invalid_cache_breakdown" : "invalid_usage";
+  }
+  return "price_unmatched";
+}
+
+function costResult(entry: MetricSource): CostResult {
+  const estimate = entry.attempts?.length
+    ? estimateComboCost(entry.attempts)
+    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus });
+  if (!estimate) return { kind: "unavailable", reason: unavailableCostReason(entry) };
+  const estimateReasons = [
+    entry.usageStatus === "estimated" || entry.usage?.estimated ? "usage_estimated" as const : undefined,
+    entry.usage && entry.usage.cachedInputTokens === undefined
+      && entry.usage.cacheReadInputTokens === undefined
+      && entry.usage.cacheCreationInputTokens === undefined ? "cache_detail_missing" as const : undefined,
+    estimate.price?.source === "expected" || estimate.attempts?.some(a => a.price.source === "expected")
+      ? "expected_price_overlay" as const : undefined,
+  ].filter((reason): reason is CostEstimateReason => reason !== undefined);
+  return { kind: "value", estimate, estimateReasons };
+}
+
+function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
+  return {
+    ...entry,
+    displayMetrics: {
+      tokPerSecond: tokPerSecondResult(entry),
+      cost: costResult(entry),
+    },
+    ...(entry.attempts?.length
+      ? {
+        attempts: entry.attempts.map(attempt => ({
+          ...attempt,
+          displayMetrics: {
+            tokPerSecond: tokPerSecondResult(attempt),
+            cost: costResult({ ...attempt, attempts: undefined }),
+          },
+        })),
+      }
+      : {}),
+  };
+}
+
 export async function handleManagementAPI(req: Request, url: URL, config: OcxConfig, deps: ManagementApiDeps = {}): Promise<Response | null> {
   if (!isAllowedRequestOrigin(req, config)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
@@ -311,7 +405,8 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
   }
 
   if (url.pathname === "/api/logs" && req.method === "GET") {
-    return jsonResponse(filterRequestLogs(getRequestLogEntries(), url.searchParams));
+    const logs = filterRequestLogs(getRequestLogEntries(), url.searchParams);
+    return jsonResponse(logs.map(requestLogDto));
   }
 
   if (url.pathname === "/api/debug" && req.method === "GET") {
@@ -378,6 +473,7 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
         generatedAt: now,
         summary: {
           requests: 0,
+          attemptCount: 0,
           measuredRequests: 0,
           reportedRequests: 0,
           unreportedRequests: 0,
@@ -391,6 +487,10 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
           reasoningOutputTokens: 0,
           totalTokens: 0,
           coverageRatio: 0,
+          estimatedCostUsd: 0,
+          pricedRequests: 0,
+          unpricedRequests: 0,
+          unmeteredRequests: 0,
         },
         days: [],
         models: [],
@@ -400,6 +500,20 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     }
   }
 
+  if (url.pathname === "/api/storage" && req.method === "GET") {
+    try {
+      return jsonResponse(scanStorage());
+    } catch {
+      return jsonResponse({
+        codexHome: resolveCodexHomeDir(),
+        generatedAt: Date.now(),
+        total: { bytes: 0, fileCount: 0 },
+        buckets: [],
+        error: "scan_failed",
+      });
+    }
+  }
+
   if (url.pathname === "/api/provider-quotas" && req.method === "GET") {
     const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
     return jsonResponse(await fetchProviderQuotaReports(config, forceRefresh));
@@ -543,13 +657,19 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
         return jsonResponse({ error: "authMode must be key, forward, oauth, or local" }, 400);
       }
     }
-    if (Object.hasOwn(rawBody, "note")) {
-      if (typeof rawBody.note !== "string") return jsonResponse({ error: "note must be a string" }, 400);
-      const note = rawBody.note.trim();
-      if (note) next.note = note;
-      else delete next.note;
-      touched = true;
-    }
+   if (Object.hasOwn(rawBody, "note")) {
+     if (typeof rawBody.note !== "string") return jsonResponse({ error: "note must be a string" }, 400);
+     const note = rawBody.note.trim();
+     if (note) next.note = note;
+     else delete next.note;
+     touched = true;
+   }
+
+   if (Object.hasOwn(rawBody, "allowPrivateNetwork")) {
+     if (typeof rawBody.allowPrivateNetwork !== "boolean") return jsonResponse({ error: "allowPrivateNetwork must be a boolean" }, 400);
+     next.allowPrivateNetwork = rawBody.allowPrivateNetwork;
+     touched = true;
+   }
 
     if (!touched) return jsonResponse({ error: "no recognized fields to update" }, 400);
 
@@ -1241,13 +1361,24 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
   // 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 req.json().catch(() => ({})) as { provider?: string; addAccount?: boolean };
+    const body = await req.json().catch(() => ({})) as { provider?: string; addAccount?: boolean; accountId?: string; reauth?: boolean };
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    const accountId = body.accountId?.trim();
+    const reauth = body.reauth === true || Boolean(accountId);
     try {
-      // addAccount forces a fresh browser identity (skips local-CLI token import) so a
-      // SECOND account can be added instead of re-importing the first one.
-      const { url: authUrl, instructions } = await startLoginFlow(provider, body.addAccount ? { forceLogin: true } : undefined);
+      if (accountId) {
+        const { getAccountSet } = await import("../oauth/store");
+        const set = getAccountSet(provider);
+        if (!set?.accounts.some(a => a.id === accountId)) {
+          return jsonResponse({ error: "Unknown account for reauth" }, 404);
+        }
+      }
+      // addAccount / reauth forces a fresh browser identity (skips local-CLI token import).
+      const { url: authUrl, instructions } = await startLoginFlow(provider, {
+        forceLogin: body.addAccount === true || reauth,
+        ...(accountId ? { reauthAccountId: accountId } : {}),
+      });
       upsertOAuthProvider(config, provider); // mutate LIVE config — routing sees it without restart
       if (authUrl) {
         // Open the browser server-side (the proxy runs on the user's machine) — the GUI's

package/src/server/relay.ts

@@ -6,6 +6,7 @@ import {
   httpStatusForRequestLogTerminal,
   inspectResponseLogJson,
   inspectResponseLogSsePayload,
+  recordFirstOutput,
   type RequestLogContext,
   type RequestLogEntry,
 } from "./request-log";
@@ -107,6 +108,34 @@ export function sseDataPayload(block: string): string | null {
 }
 
 export function terminalStatusFromSsePayload(payload: string): ResponsesTerminalStatus | null {
+  return terminalStatusFromSsePayloadInner(payload);
+}
+
+/** True when a native Responses SSE payload carries the FIRST kind of non-empty model output. */
+export function isFirstOutputSsePayload(payload: string | null): boolean {
+  if (!payload || payload === "[DONE]") return false;
+  try {
+    const event = JSON.parse(payload) as { type?: unknown; delta?: unknown };
+    return (event.type === "response.output_text.delta"
+      || event.type === "response.reasoning_summary_text.delta"
+      || event.type === "response.reasoning_text.delta")
+      && typeof event.delta === "string"
+      && event.delta.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function createFirstOutputReporter(onFirstOutput?: () => void): (payload: string | null) => void {
+  let reported = false;
+  return payload => {
+    if (reported || !isFirstOutputSsePayload(payload)) return;
+    reported = true;
+    try { onFirstOutput?.(); } catch { /* metrics must not break the stream */ }
+  };
+}
+
+function terminalStatusFromSsePayloadInner(payload: string): ResponsesTerminalStatus | null {
   if (payload === "[DONE]") return null;
   try {
     const json = JSON.parse(payload) as { type?: unknown };
@@ -144,11 +173,13 @@ export function trackSseForRequestLog(
   onTerminal: (status: ResponsesTerminalStatus) => void,
   onCancel: () => void,
   logCtx?: RequestLogContext,
+  onFirstOutput?: () => void,
 ): ReadableStream<Uint8Array> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
   let terminalReported = false;
+  const reportFirstOutput = createFirstOutputReporter(onFirstOutput);
 
   const reportTerminal = (status: ResponsesTerminalStatus) => {
     if (terminalReported) return;
@@ -159,6 +190,7 @@ export function trackSseForRequestLog(
   const inspectPayload = (payload: string | null) => {
     if (!payload) return;
     if (logCtx) inspectResponseLogSsePayload(logCtx, payload);
+    reportFirstOutput(payload);
     const status = terminalStatusFromSsePayload(payload);
     if (status) reportTerminal(status);
   };
@@ -264,6 +296,7 @@ export function responseWithDeferredRequestLog(
       addFinalRequestLog(requestId, start, logCtx, 499, { closeReason: "client_cancel" }, addLog);
     },
     logCtx,
+    () => recordFirstOutput(logCtx, start),
   );
   return new Response(body, {
     status: response.status,
@@ -379,12 +412,14 @@ export function consumeForInspection(
   logCtx?: RequestLogContext,
   onCancel?: () => void,
   onCompletedResponse?: (response: { id?: unknown; output?: unknown; status?: unknown }) => void,
+  onFirstOutput?: () => void,
 ): void {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
   let reported = false;
   let cancelled = false;
+  const reportFirstOutput = createFirstOutputReporter(onFirstOutput);
   if (signal) {
     if (signal.aborted) {
       // Aborted before we could read anything (Codex disconnects the instant it finishes reading).
@@ -413,6 +448,7 @@ export function consumeForInspection(
           if (buffer.trim() && !reported) {
             const payload = sseDataPayload(buffer);
             if (logCtx) inspectResponseLogSsePayload(logCtx, payload);
+            reportFirstOutput(payload);
             if (payload) {
               const status = terminalStatusFromSsePayload(payload);
               if (status) { reported = true; onTerminal(status); }
@@ -432,6 +468,7 @@ export function consumeForInspection(
           if (reported && !onCompletedResponse) continue;
           const payload = sseDataPayload(next.block);
           if (!reported && logCtx) inspectResponseLogSsePayload(logCtx, payload);
+          reportFirstOutput(payload);
           if (!payload) continue;
           if (!reported) {
             const status = terminalStatusFromSsePayload(payload);
@@ -458,10 +495,12 @@ export function consumeForResponseLogMetadata(
   signal?: AbortSignal,
   onDone?: () => void,
   onCompletedResponse?: (response: { id?: unknown; output?: unknown; status?: unknown }) => void,
+  onFirstOutput?: () => void,
 ): void {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
+  const reportFirstOutput = createFirstOutputReporter(onFirstOutput);
   if (signal) {
     if (signal.aborted) {
       reader.cancel(signal.reason).catch(() => {});
@@ -481,6 +520,7 @@ export function consumeForResponseLogMetadata(
           if (buffer.trim()) {
             const payload = sseDataPayload(buffer);
             inspectResponseLogSsePayload(logCtx, payload);
+            reportFirstOutput(payload);
             if (payload && onCompletedResponse) {
               const response = completedResponseFromSsePayload(payload);
               if (response) onCompletedResponse(response);
@@ -494,6 +534,7 @@ export function consumeForResponseLogMetadata(
           buffer = next.rest;
           const payload = sseDataPayload(next.block);
           inspectResponseLogSsePayload(logCtx, payload);
+          reportFirstOutput(payload);
           if (payload && onCompletedResponse) {
             const response = completedResponseFromSsePayload(payload);
             if (response) onCompletedResponse(response);

package/src/server/request-log.ts

@@ -29,6 +29,8 @@ import {
 export interface RequestLogContext {
   model: string;
   provider: string;
+  /** TTFT: ms from request start to the first non-empty model output delta (WP4, devlog 040). */
+  firstOutputMs?: number;
   surface?: "claude";
   requestedModel?: string;
   requestedEffort?: string;
@@ -65,6 +67,8 @@ export interface RequestLogEntry {
   timestamp: number;
   model: string;
   provider: string;
+  /** TTFT: ms from request start to the first non-empty model output delta; unset for non-streaming/tool-only. */
+  firstOutputMs?: number;
   surface?: "claude";
   requestedModel?: string;
   requestedEffort?: string;
@@ -117,6 +121,7 @@ export function addRequestLog(entry: RequestLogEntry) {
       ...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
       status: entry.status,
       durationMs: entry.durationMs,
+      ...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
       usageStatus: entry.usageStatus,
       ...(entry.usage ? { usage: entry.usage } : {}),
       ...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
@@ -133,6 +138,26 @@ export function nextRequestLogId(timestamp = Date.now()): string {
   return `ocx-${timestamp.toString(36)}-${requestLogSeq.toString(36)}`;
 }
 
+/**
+ * One-shot TTFT recorder (WP4). Records the first non-empty model output moment
+ * relative to the request start, and — when a combo attempt is in flight —
+ * relative to that attempt's start as well. Later calls are no-ops, so both the
+ * bridge callback and the deferred SSE tap may fire without double-recording.
+ */
+export function recordFirstOutput(
+  logCtx: RequestLogContext,
+  requestStartedAt: number,
+  now = Date.now(),
+): void {
+  if (!Number.isFinite(requestStartedAt) || !Number.isFinite(now)) return;
+  const requestElapsed = Math.max(0, now - requestStartedAt);
+  if (logCtx.firstOutputMs === undefined) logCtx.firstOutputMs = requestElapsed;
+  if (logCtx.activeAttempt && logCtx.activeAttempt.firstOutputMs === undefined) {
+    const attemptStartedAt = logCtx.activeAttemptStartedAt ?? requestStartedAt;
+    logCtx.activeAttempt.firstOutputMs = Math.max(0, now - attemptStartedAt);
+  }
+}
+
 export function requestLogErrorCode(status: number, upstreamError?: string): string | undefined {
   if (status >= 200 && status < 400) return undefined;
   // Defense in depth: mid-stream web-search aborts used to land as 502 with this message.
@@ -456,6 +481,7 @@ export function addFinalRequestLog(
     ...(logCtx.resolvedModel ? { resolvedModel: logCtx.resolvedModel } : {}),
     status: effectiveStatus,
     durationMs: Date.now() - start,
+    ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
     ...(errorCode ? { errorCode } : {}),
     ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
     ...(closeReason ? { closeReason } : {}),

package/src/server/responses.ts

@@ -462,6 +462,8 @@ interface ConsumedComboFailure {
 interface HandleResponsesOptions {
   forceEmptyResponseId?: boolean;
   abortSignal?: AbortSignal;
+  /** One-shot TTFT callback: first non-empty model output observed (WP4). */
+  onFirstOutput?: () => void;
   onCodexAuthContextResolved?: (context: CodexAuthContext | undefined) => void;
   recordTerminalOutcomes?: boolean;
   setTerminalOutcomeRecorder?: (recorder: ((status: ResponsesTerminalStatus) => void) | undefined) => void;
@@ -634,6 +636,14 @@ async function handleComboResponses(
       response = await handleResponses(childRequest, config, childLog, {
         ...options,
         comboAttempt: true,
+        // Attempt-relative TTFT is recorded HERE (not via childLog.firstOutputMs — a later
+        // Object.assign(logCtx, childLog) would overwrite the request-relative value).
+        onFirstOutput: () => {
+          if (attempt.firstOutputMs === undefined) {
+            attempt.firstOutputMs = Math.max(0, Date.now() - started);
+          }
+          options.onFirstOutput?.();
+        },
         onCodexAuthContextResolved: value => { resolvedAuth = value; },
         setTerminalOutcomeRecorder: value => { terminalRecorder = value; },
         onConsumedComboFailure: value => { consumedChildFailure = value; },
@@ -1176,9 +1186,17 @@ export async function handleResponses(
           logCtx,
           () => options.onNativePassthroughCancel?.(),
           rememberPassthroughResponse,
+          options.onFirstOutput,
         );
       } else {
-        consumeForResponseLogMetadata(inspectBody, logCtx, turnAc.signal, () => unregisterTurn(turnAc), rememberPassthroughResponse);
+        consumeForResponseLogMetadata(
+          inspectBody,
+          logCtx,
+          turnAc.signal,
+          () => unregisterTurn(turnAc),
+          rememberPassthroughResponse,
+          options.onFirstOutput,
+        );
       }
       if (!headers.has("content-type")) headers.set("content-type", "text/event-stream");
       // win32 must keep the pure native relay (Bun#32111 JS-sink segfault); elsewhere a JS pull
@@ -1266,6 +1284,7 @@ export async function handleResponses(
           ...(options.forceEmptyResponseId ? { responseId: "" } : {}),
           stallTimeoutSec: config.stallTimeoutSec,
           hideThinkingSummary: parsed.options.hideThinkingSummary,
+          ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
           ...(routedCompaction ? { compaction: true } : {}),
           ...(routedCompaction ? {} : { onCompletedResponse: (response: Record<string, unknown>) => rememberResponseState(parsed._rawBody, response, parsed._cursorConversationId) }),
         },
@@ -1317,6 +1336,7 @@ export async function handleResponses(
       maxSearches: wsPlan.maxSearches,
       forceEmptyResponseId: true,
       abortSignal: options.abortSignal,
+      ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
       recordSidecarOutcome: wsPlan.forwardSidecar?.recordOutcome,
       connectTimeoutMs: config.connectTimeoutMs ?? 200_000,
       routedModelStallTimeoutMs: wsPlan.routedModelStallTimeoutMs,
@@ -1529,6 +1549,7 @@ export async function handleResponses(
         ...(options.forceEmptyResponseId ? { responseId: "" } : {}),
         stallTimeoutSec: config.stallTimeoutSec,
         hideThinkingSummary: parsed.options.hideThinkingSummary,
+        ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
         ...(routedCompaction ? { compaction: true } : {}),
         // Compaction turns must NOT enter the continuation cache: _rawBody still holds the full
         // PRE-compaction history, and a later previous_response_id expansion would rehydrate the

package/src/stall-timeout.ts

@@ -0,0 +1,20 @@
+/**
+ * Bridge upstream stall budget: seconds of silence (no adapter events) before the
+ * Responses bridge emits `response.incomplete` / `upstream_stall_timeout`.
+ *
+ * Raised from 90s so long reasoning + large tool writes are not cut mid-turn.
+ * Hung streams still die; they just get a more realistic window.
+ */
+export const DEFAULT_STALL_TIMEOUT_SEC = 300;
+
+/**
+ * Resolve the effective bridge stall deadline for a turn.
+ * - unset / non-finite config → {@link DEFAULT_STALL_TIMEOUT_SEC}
+ * - finite config → ceil, minimum 1
+ */
+export function resolveStallTimeoutSec(configuredSec: number | undefined): number {
+  if (typeof configuredSec === "number" && Number.isFinite(configuredSec)) {
+    return Math.max(1, Math.ceil(configuredSec));
+  }
+  return DEFAULT_STALL_TIMEOUT_SEC;
+}