Codex usage indicator with cross-flavor budget gauge shape (rebase of #537)

[heavygee]

What

Rebases @dsus4wang's stalled #537 onto current main (179 commits caught up since April), then extends the indicator to handle premium-credits accounts, fix unit-rendering bugs, and lay a flavor-agnostic shape for the cross-flavor budget gauge umbrella (#846).

Original PR by @dsus4wang. The first 3 commits on this branch preserve his authorship intact:

• 8f5f164e Add Codex session list/resume flow to web new-session UI
• 3f4f33dc restore Codex session history
• 2f32998b add Codex usage indicator

The remaining 4 commits are follow-up work on top:

• 753b51b8 feat: surface credits + rate_limit_reached_type for premium accounts
• c448e537 fix: drop $ prefix + format credit balance (rate-card-correct rendering)
• b0fad40e fix: ring shows worst constraint, not just context
• 97dc5414 refactor: split ring meaning - centre = context, colour = effective state

Why the extension

Operator-tested @dsus4wang's indicator against a live Codex Pro account on 2026-06-09. Three issues surfaced that the original PR couldn't have caught on a Plus-tier test account:

1. Premium-credits accounts have no time-window rate limits. When subscription is exhausted and billing falls back to credits, codex emits rate_limits.primary=null + secondary=null + credits.has_credits=false. The original indicator was silent on this entire state - showed only the context-window % even when the account was hard-blocked.

2. Ring semantics drifted between states. The same circle meant 'context fill' in the normal case but 'usage exhaustion' when blocked. Operator caught it: 'the circle that WAS showing you context now shows you red 100 meaning no more usage'.

3. A Pro account that exhausts the subscription window but tops up credits is not blocked - codex falls back to credit billing transparently. The original would have read this as 'weekly 100%, red, you're done' even though the user can keep sending. False alarm vs false safety in the same widget.

What changed

Premium-credits support

• CodexUsageSchema (shared) gains credits (hasCredits / unlimited / balance) plus optional rateLimitReachedType / planType / limitId. JSON-only, no SCHEMA_VERSION bump.
• normalizeCodexUsage (cli) extracts those fields from the token_count payload's rate_limits root.
• Credits rendered as a bare count, no $ prefix. Codex's rate card (reference) makes credits a token-mix-dependent billing unit (~$0.04/credit at Pro tier, not 1:1 USD). String-to-number parser handles the precision-preserving balance shapes codex sends ("250.0000000000", "0", "0.0000000000").

Ring metaphor: centre = task room, colour = account constraint

• New AgentBudgetState shape under shared/src/agentBudget.ts. Flavor-agnostic - declares only axes (each with pressure 0-100), an operationalAxisId (which axis the centre number shows), and an effective state (green / amber / red / blocked) computed per-flavor.
• AgentBudgetIndicator (web) is a flavor-agnostic renderer that consumes the state. The Codex adapter (codexBudgetAdapter.ts) is the only Codex-specific module on the web side.
• Adapter encodes the Codex-Pro covering rule: subscription window at cap AND credits > 0 → amber, not red, with the credits axis flagged covering. The popover renders a left-accent on the covering axis so the user sees why the gauge isn't red.
• Centre number is always the operational axis (context for LLM agents). Ring colour is always the effective state. The two no longer fight; the centre number never silently changes meaning.

Cross-flavor seed (umbrella #846)

• AgentBudgetState is intentionally not Codex-specific. A toClaudeBudgetState adapter (or Cursor / Gemini equivalents) can drop in without touching the indicator. The Codex adapter is the reference implementation; Claude is queued next.

Visual change

State	Before	After
Context 80%, no rate-limit data	Ring 80 blue	Ring 80 blue (unchanged)
Context 80%, weekly 100%, credits 246	Ring 80 blue (silently hides the weekly cap)	Ring 80 amber; popover shows 1 Week Usage 100% (dominant, accented) and Credits 246 covering exhausted subscription window (blue accent)
Context 80%, no windows, credits 0 (blocked)	Ring 80 blue (silently misrepresents block)	Ring 80 red; tooltip 'Blocked: subscription window and credits both exhausted'; popover shows Credits 0 subscription / top-up exhausted (critical, dominant)

Testing

• bun typecheck + bun run test: 114 test files, 958 tests, all pass on this branch
• Manual: validated against a live Codex Pro account on the operator's session - weekly at 100%, 246 credits, indicator correctly reads amber with covering accent
• New test coverage: 13 tests in codexBudgetAdapter.test.ts covering the operator-caught scenarios (premium-credits shape, covering / blocked / red transitions, transition-window edge where both subscription axes are present at 100 + credits 0, unlimited credits exemption, etc); plus refreshed codexUsageSchema.test.ts and codexUsage.test.ts for the cli normalizer

Known follow-ups (out of scope for this PR)

• i18n: the indicator strings ('Context Window', '5h Usage', 'Credits', 'subscription / top-up exhausted', etc) are English-only. The original PR was English-only as well; the cross-flavor refactor preserves that. Should route through t() in a follow-up so zh-CN locale gets coverage too.
• account/rateLimits/updated standalone events: appServerEventConverter.ts currently only surfaces rate limits when piggy-backed on thread/tokenUsage/updated. Standalone rate-limit-update events from the codex app-server are dropped. Worth surfacing in a follow-up so rate-limit transitions reach the UI without waiting for the next turn.
• Claude / Cursor / Gemini adapters: the AgentBudgetState shape is the cross-flavor foundation. Claude adapter is queued next (depends on confirming Anthropic ratelimit headers reach HAPI's hook stream); Cursor is data-blocked until they expose telemetry; Gemini follows.

Related

• Original PR: [codex] add Codex usage indicator #537 (by @dsus4wang)
• Umbrella issue: feat(web+cli+hub): cross-flavor agent budget/quota gauges in composer (umbrella) #846

Made with Cursor

[github-actions]

Findings

• [Major] Codex history import flag is dropped before runner launch — the new web resume flow sends importHistory: true and the hub includes it in the machine RPC payload, but the machine-side SpawnHappySession handler never reads or forwards that field into spawnSession. As a result, remote web resumes execute hapi codex resume <thread> without --hapi-import-history, so the newly selected Codex transcript history is not imported into the fresh HAPI session. Evidence: hub/src/sync/rpcGateway.ts:142, with the drop at cli/src/api/apiMachine.ts:252-277.
  Suggested fix:

  const {
      directory,
      sessionId,
      resumeSessionId,
      machineId,
      approvedNewDirectoryCreation,
      agent,
      model,
      effort,
      modelReasoningEffort,
      yolo,
      permissionMode,
      token,
      sessionType,
      worktreeName,
      importHistory
  } = params || {}
  
  const result = await spawnSession({
      directory,
      sessionId,
      resumeSessionId,
      importHistory,
      machineId,
      approvedNewDirectoryCreation,
      agent,
      model,
      effort,
      modelReasoningEffort,
      yolo,
      permissionMode,
      token,
      sessionType,
      worktreeName
  })

Questions

• None.

Summary

• Review mode: initial
• Found one Major issue in the remote Codex resume/import path. Residual risk: I did not run the full test suite in this automation pass; add a machine RPC boundary test that asserts importHistory reaches spawnSession.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Codex session listing bypasses workspace-root scoping — the new machine RPC is registered through the shared handler path, then reads every Codex transcript under CODEX_HOME and returns transcript titles plus parsed cwd paths. Runner machines that were started with --workspace-root currently guard spawn, directory browsing, and scoped model discovery, but this new picker can still expose Codex sessions from projects outside those roots. Evidence: cli/src/modules/common/registerCommonHandlers.ts:19, with the unfiltered scan/return at cli/src/modules/common/codexSessions.ts:407 and cli/src/modules/common/codexSessions.ts:433.
  Suggested fix:

  export function registerCommonHandlers(
      rpcHandlerManager: RpcHandlerManager,
      workingDirectory: string,
      options: { codexSessionPathAllowed?: (path: string | null) => Promise<boolean> | boolean } = {}
  ): void {
      registerBashHandlers(rpcHandlerManager, workingDirectory)
      registerCodexModelHandlers(rpcHandlerManager)
      registerCodexSessionHandlers(rpcHandlerManager, options.codexSessionPathAllowed)
      // ...
  }
  
  registerCommonHandlers(this.rpcHandlerManager, getInvokedCwd(), {
      codexSessionPathAllowed: async (path) => {
          if (!this.normalizedWorkspaceRoots?.length) return true
          if (!path) return false
          return this.isWithinWorkspaceRoots(await this.resolveForWorkspaceCheck(path))
      }
  })

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Major issue in the newly added Codex session listing path. The prior importHistory forwarding issue appears fixed in the latest head.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Codex resume can start in the wrong workspace — selecting a Codex transcript only stores selectedCodexSessionId; the spawn request still sends the independent directory input as directory. The runner launches the child with that directory as cwd, and both Codex local/app-server paths pass it through to Codex, so resuming/importing a transcript from /repo-a while the form still contains the recent/default /repo-b resumes the old thread against the wrong files. Evidence: web/src/components/NewSession/index.tsx:592, with the transcript path only rendered in the picker label at web/src/components/NewSession/CodexSessionSelector.tsx:31.
  Suggested fix:

  const selectedCodexSession = codexSessionsState.sessions.find(
      (session) => session.id === selectedCodexSessionId
  ) ?? null
  const spawnDirectory = agent === 'codex' && selectedCodexSessionId
      ? selectedCodexSession?.path
      : trimmedDirectory
  if (!spawnDirectory) {
      setError('Selected Codex session has no workspace path')
      return
  }
  
  const existsResult = await checkPathsExists([spawnDirectory])
  const directoryExists = existsResult[spawnDirectory]
  
  const result = await spawnSession({
      machineId,
      directory: spawnDirectory,
      agent,
      resumeSessionId: agent === 'codex' && selectedCodexSessionId ? selectedCodexSessionId : undefined,
      importHistory: agent === 'codex' && Boolean(selectedCodexSessionId),
      // ...existing fields
  })

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Major regression in the new Codex session picker/resume path. The prior workspace-root scoping finding appears addressed in the latest head.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Metadata-only session updates stale the session list — adding metadata to SessionPatchSchema makes the new hub event payload parse as a patch, so useSSE takes the patch path instead of invalidating. patchSessionDetail merges the metadata for an open session, but patchSessionSummary only copies active/thinking/model/effort fields and still returns true; that suppresses queueSessionListInvalidation(). A Codex history import/title update can therefore update the chat header while /sessions keeps the old title/path/agentSessionId until a full refetch. Evidence: shared/src/schemas.ts:279, with the summary patch path at web/src/hooks/useSSE.ts:500.
  Suggested fix:

  const toSummaryMetadata = (metadata: Metadata | null): SessionSummaryMetadata | null => metadata ? {
      name: metadata.name,
      path: metadata.path,
      machineId: metadata.machineId ?? undefined,
      summary: metadata.summary ? { text: metadata.summary.text } : undefined,
      flavor: metadata.flavor ?? null,
      worktree: metadata.worktree,
      agentSessionId: metadata.codexSessionId
          ?? metadata.claudeSessionId
          ?? metadata.geminiSessionId
          ?? metadata.opencodeSessionId
          ?? metadata.cursorSessionId
          ?? metadata.kimiSessionId
          ?? undefined,
      lifecycleState: metadata.lifecycleState
  } : null
  
  const nextSummary: SessionSummary = {
      ...current,
      metadata: Object.prototype.hasOwnProperty.call(patch, "metadata")
          ? toSummaryMetadata(patch.metadata ?? null)
          : current.metadata,
      active: patch.active ?? current.active,
      thinking: patch.thinking ?? current.thinking,
      activeAt: patch.activeAt ?? current.activeAt,
      updatedAt: patch.updatedAt ?? current.updatedAt,
      backgroundTaskCount: Object.prototype.hasOwnProperty.call(patch, "backgroundTaskCount")
          ? patch.backgroundTaskCount ?? 0
          : current.backgroundTaskCount,
      model: Object.prototype.hasOwnProperty.call(patch, "model") ? patch.model ?? null : current.model,
      effort: Object.prototype.hasOwnProperty.call(patch, "effort") ? patch.effort ?? null : current.effort
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Major cache regression introduced by the new metadata patch flow. The prior Codex resume workspace issue appears addressed in the latest head.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Imported Codex history is replayed again after switching to local — the new import path writes the whole selected transcript into the fresh HAPI session before loop() starts, but the same run still sets replayTranscriptHistoryOnStart for any new resumeSessionId. If that remote session is later handed off to local, codexLocalLauncher attaches the transcript with replay enabled and sends the same historical user/agent messages again, duplicating imported history in the chat. Evidence: cli/src/codex/runCodex.ts:97, with replay consumed by cli/src/codex/codexLocalLauncher.ts:84.
  Suggested fix:

  const replayTranscriptHistoryOnStart = Boolean(
      opts.resumeSessionId && !opts.existingSessionId && !opts.importHistory
  );

• [Major] Hidden stale Codex selection can resume the wrong thread — after selecting an old Codex session and then toggling showOldCodexSessions off, the query result no longer contains that option, so the <select> visually falls back to “Start new Codex session”. The state still keeps selectedCodexSessionId, and handleCreate() sends it as resumeSessionId even though selectedCodexSession is null, so the user can unknowingly resume/import the hidden old thread using the directory text box. Evidence: web/src/components/NewSession/index.tsx:602.
  Suggested fix:

  useEffect(() => {
      if (!selectedCodexSessionId) return
      if (codexSessionsState.isLoading) return
      if (!codexSessionsState.sessions.some((session) => session.id === selectedCodexSessionId)) {
          setSelectedCodexSessionId('')
      }
  }, [selectedCodexSessionId, codexSessionsState.isLoading, codexSessionsState.sessions])

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found two Major regressions in the current diff. The previous bot finding about metadata-only SSE updates appears fixed in this head.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Minor] Codex session picker only loads the first cursor page — the machine endpoint returns nextCursor, and the CLI scanner can expose more sessions than one page, but this hook discards nextCursor after the first request. Because listCodexSessions() caps limit to 100, any matching Codex thread after the first page is unreachable from the resume/import selector. Evidence: web/src/hooks/queries/useCodexSessions.ts:26
  Suggested fix:

  const sessions: CodexSessionSummary[] = []
  let cursor: string | undefined
  
  do {
      const page = await api.getMachineCodexSessions(machineId, {
          includeOld,
          olderThanDays: 180,
          limit: 100,
          cursor
      })
      if (page.success === false) return page
      sessions.push(...(page.sessions ?? []))
      cursor = page.nextCursor ?? undefined
  } while (cursor)
  
  return { success: true, sessions, nextCursor: null }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Minor pagination gap in the new Codex session selector path. The prior Major findings from the last bot review appear fixed in this head.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• No issues found.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Re-reviewed the full current diff, including the follow-up pagination fix, Codex resume/import propagation, workspace-scoped Codex session listing, usage normalization, metadata/SSE updates, and the budget indicator adapter. The prior pagination finding appears fixed. Residual risk is mostly integration coverage around live Codex premium-account payload variants.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Minor] Pathless Codex resume can enable a no-op Create button — the selector can return Codex transcripts with path: null (CodexSessionSummary.path allows null and listCodexSessions keeps them), but canCreate now treats any selected Codex session as enough even when the directory input is empty. In that state the button is enabled, then handleCreate computes spawnDirectory as selectedCodexSession?.path ?? trimmedDirectory and silently returns because both are empty, so the user gets no error and no session starts. Evidence web/src/components/NewSession/index.tsx:632
  Suggested fix:

  const selectedCodexSession = agent === 'codex' && selectedCodexSessionId
      ? (codexSessionsState.sessions.find((s) => s.id === selectedCodexSessionId) ?? null)
      : null
  const hasSpawnDirectory = Boolean(selectedCodexSession?.path ?? trimmedDirectory)
  const canCreate = Boolean(machineId && hasSpawnDirectory && !isFormDisabled && !missingWorktreeDirectory)

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Re-reviewed the full current diff. Found one UI regression in the Codex resume flow for transcripts without a recorded workspace path. Residual risk remains around live Codex premium-account payload variants, but the added adapter/normalizer tests cover the documented cases.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• No issues found.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Re-reviewed the full current diff, including the follow-up change that gates Codex resume creation on the resolved spawn directory. No new blocker/major/minor findings met the confidence threshold. Residual risk remains around live Codex payload variants and UI behavior for very large local transcript sets, but the added normalizer, adapter, import, and route tests cover the documented cases.

Testing

• Not run (automation); checked git diff --check only.

HAPI Bot

[github-actions]

Findings

• [Major] Revalidate imported Codex history against workspace roots — --workspace-root now scopes the session picker and the spawn directory, but the actual import still trusts any resumeSessionId. A client can POST /api/machines/:id/spawn with directory inside an allowed root, agent: "codex", importHistory: true, and a Codex thread id whose transcript belongs to another project; runCodex then imports that transcript through importCodexSessionHistory without checking the transcript cwd/path, leaking out-of-scope history into the new HAPI session. Evidence: cli/src/codex/runCodex.ts:108, with the unchecked lookup at cli/src/codex/importHistory.ts:42.
  Suggested fix:

  const importedHistory = await importCodexSessionHistory({
      session,
      codexSessionId: opts.resumeSessionId,
      expectedDirectory: workingDirectory
  })

  and have importCodexSessionHistory parse the transcript session_meta.cwd/path before replaying, rejecting when it does not resolve to the requested spawn directory or an allowed workspace root.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Major issue in the latest full diff: Codex history import can bypass the workspace-root boundary even though the picker/spawn path are scoped.

Testing

• Not run (automation); checked git diff --check.

HAPI Bot

[heavygee]

Fixed in 4fdb65e. importCodexSessionHistory now accepts expectedDirectory; it reads the first session_meta event from the transcript, extracts cwd/path, and rejects (warning + {imported:0,filePath:null}) if the session path does not start with the expected directory. runCodex passes workingDirectory as expectedDirectory at the call site.

[github-actions]

Findings

• [Major] Use path-aware validation for imported Codex history — the follow-up guard still treats sibling paths as inside the selected workspace because it checks sessionPath.startsWith(expectedDirectory). A transcript from /tmp/workspace-other passes when the requested spawn directory is /tmp/workspace, so a direct /api/machines/:id/spawn request can still import an out-of-directory Codex thread into a scoped runner session. Evidence: cli/src/codex/importHistory.ts:72.
  Suggested fix:

  import { isAbsolute, relative, resolve } from 'node:path'
  
  function isSameOrChild(parent: string, child: string): boolean {
      const rel = relative(resolve(parent), resolve(child))
      return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
  }
  
  if (args.expectedDirectory) {
      const sessionPath = extractSessionPath(content.split('\n'))
      if (!sessionPath || !isSameOrChild(args.expectedDirectory, sessionPath)) {
          logger.warn(
              `[codex-history-import] Rejecting import: session path "${sessionPath ?? '(missing)'}" is outside expected directory "${args.expectedDirectory}"`
          )
          return { imported: 0, filePath: null }
      }
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one Major issue in the latest full diff: the Codex history import boundary check added after the previous review is still bypassable for sibling path prefixes.

Testing

• Not run (automation); checked git diff --check refs/remotes/origin/main...refs/remotes/origin/pr-847.

HAPI Bot

[github-actions]

Findings

• No issues found.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The prior Major finding on path-prefix validation is addressed in cli/src/codex/importHistory.ts with path-aware relative(resolve(...)) containment and missing-path rejection.
• Reviewed the latest full diff, including Codex history import/listing, workspace-root scoping, spawn/resume parameter flow, usage normalization, budget adapter behavior, and SSE/session metadata cache updates. Residual risk: large PR and review-only pass; no local test execution in this run.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Codex resume can bypass workspace-root scoping — cli/src/api/apiMachine.ts:286

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one workspace-root enforcement gap in the new Codex resume/import flow. Residual risk: review-only pass; local tests not run here.

Testing

• Not run (automation). Suggested: add an ApiMachineClient spawn RPC test where directory is inside an allowed workspace root but resumeSessionId resolves to a Codex transcript whose session_meta.cwd is outside, and assert spawn is rejected before spawnSession is called.

HAPI Bot

[github-actions]

Findings

• None.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• No issues found in the latest diff. The prior workspace-root bypass finding is addressed in this head. Residual risk: review-only pass; full CI was not run here.

Testing

• Not run (automation).

HAPI Bot