feat(codex): persist reset-credit operation identity

AGENTS_INSTALL.md

@@ -5,8 +5,8 @@ user's machine. It is not about contributing to this repository — that is
 [`AGENTS.md`](./AGENTS.md), and nothing here concerns you if you are only
 reading or changing this codebase.
 
-There is one rule, and it exists because `ocx start` can print a question that
-an agent is capable of answering and must not.
+There is one consent rule, and it covers user-owned identity and scarce credits
+that an agent is capable of spending and must not.
 
 For everything else about driving opencodex from a scripted terminal —
 installation, `ocx init`, headless flags, exit codes — see the
@@ -22,7 +22,8 @@ install or operations task authorizes, and an agent must never perform or
 auto-answer them — even when the surrounding task is approved, even when the
 credential is sitting right there.
 
-The current one is **starring the repository on GitHub**.
+The current consent-bound actions are **starring the repository on GitHub** and
+**consuming a Codex reset credit**.
 
 ### Do not
 
@@ -35,6 +36,15 @@ The current one is **starring the repository on GitHub**.
   `ocx service install`. When an agent is detected the prompt is deliberately
   suppressed and its one-time marker left unwritten, so the user still gets the
   real question on their own next run.
+- Do **not** run `ocx account reset-credits <id|main> --consume --yes` or call
+  `POST /api/codex-auth/reset-credits/consume` on the user's behalf. Inspecting
+  reset credits is read-only and allowed; consuming one is not. Agent-driven
+  CLI runs are refused, and the API returns `403 agent_consent_required` unless
+  the request carries both a loopback-dashboard GUI session and a separately
+  re-entered owner admin token, or the CLI's short-lived one-shot local consent
+  capability. Remote dashboards cannot mint that GUI session; the user must run
+  the local CLI consent flow on the OpenCodex host. A reusable admin token by itself or a client
+  `confirmed` field is not consent; do not route around either refusal.
 
 ### Do
 
@@ -60,18 +70,30 @@ reads, so the CLI prints one dim line and this file carries the contract.
 
 ## Where the enforcement lives
 
-Reading this file is not what makes the boundary hold — the code refuses
-agent-driven callers regardless:
+Reading this file is not what makes the boundary hold — the code refuses known
+agent-driven callers on the normal path. Like the dashboard session, local
+capability checks are not proof of human presence: a determined process running
+as the same user can reach the same local secrets and browser surface. The rule
+above is the actual boundary and remains binding even when those mechanisms are
+technically reachable:
 
 - [`src/cli/agent-driven.ts`](./src/cli/agent-driven.ts) — agent detection.
 - [`src/cli/star-prompt.ts`](./src/cli/star-prompt.ts) — prompt suppression and
   the one-time marker.
 - [`src/server/management/sidebar-routes.ts`](./src/server/management/sidebar-routes.ts)
   — the `403 agent_consent_required` refusal.
+- [`src/cli/account-auth.ts`](./src/cli/account-auth.ts) and
+  [`src/cli/reset-credit-consent-client.ts`](./src/cli/reset-credit-consent-client.ts)
+  — hand-typed reset-credit consent and one-shot capability transport.
+- [`src/codex/auth-api.ts`](./src/codex/auth-api.ts) and
+  [`src/server/management-auth.ts`](./src/server/management-auth.ts) — consent
+  principal enforcement before any reset-credit dispatch.
 
 Regression coverage: `tests/startup-prompt.test.ts`,
-`tests/agent-driven.test.ts`, `tests/sidebar-routes.test.ts`.
+`tests/agent-driven.test.ts`, `tests/sidebar-routes.test.ts`,
+`tests/cli-account.test.ts`, `tests/reset-credit-consent-client.test.ts`,
+`tests/server-management-auth.test.ts`, and `tests/codex-auth-api.test.ts`.
 
-If a future action spends the user's identity, credits, or reputation, gate it
+If another action spends the user's identity, credits, or reputation, gate it
 the same way rather than relying on a prompt an agent can answer, and document
 it here.

docs-site/src/content/docs/getting-started/for-agents.md

@@ -54,6 +54,17 @@ most once per opencodex version, and a later version asks again on its own. Star
 only after an explicit yes; an explicit no settles it permanently and is never raised again.
 :::
 
+:::caution[Codex reset-credit consent]
+Inspecting reset credits is read-only. Never run `ocx account reset-credits <id|main> --consume --yes`
+or call the consume endpoint on the user's behalf. Agent-driven attempts are refused with
+`agent_consent_required`; do not bypass the refusal with an admin token or a client `confirmed`
+field. Only a hand-typed user-confirmed CLI run or a loopback dashboard action that combines its
+GUI session with a separately re-entered owner admin token may consume a credit. A remote
+dashboard cannot mint that GUI session; the user must run the local CLI consent flow on the host.
+These checks remove the casual automation path but do not prove human presence to a determined
+same-user process; the agent consent rule remains the actual boundary.
+:::
+
 ## Check a headless installation
 
 Use these read-only checks in scripts and agent runs:

docs-site/src/content/docs/guides/web-dashboard.md

@@ -34,6 +34,13 @@ password manager can offer to save and autofill it. The dashboard itself still k
 in memory and does not write it to `localStorage` or `sessionStorage`; whether it is saved is entirely
 the browser or password manager's decision.
 
+Most loopback dashboard actions need no token entry. Consuming a Codex reset credit is the
+exception: because it is irreversible, the confirmation flow asks for the owner admin token and
+the server requires that proof together with the short-lived GUI session. Either credential alone
+is refused. The token is verified and used for that request without being written to web storage.
+Remote dashboards cannot mint the required GUI session, so reset-credit consumption is disabled
+there; run the local CLI consent flow on the OpenCodex host instead.
+
 ## What you can do
 
 | Area | What it does |

docs-site/src/content/docs/ja/getting-started/for-agents.md

@@ -36,6 +36,17 @@ ocx init
 エージェントは GitHub のスタープロンプトに決して回答せず、ユーザーに代わって `gh`、GitHub の Star API、`POST /api/github/star` のいずれも呼び出してはいけません。スターを付ける操作はユーザーのアイデンティティを使用するため、別途明示的な同意が必要です。エージェント主導の実行では、CLI はプロンプトを抑止して `.star-prompted` を書き込まず、管理 API は `403 agent_consent_required` を返します。どちらの保護も回避しないでください。確認は、その提示が表示された起動に続く返答の冒頭で、ユーザーが必ず選ぶ Yes/No の質問として一度だけ行ってください（`lidge-jun/opencodex にスターを付けますか？ Yes / No`）。「よかったらスターをどうぞ」のような曖昧な言い方や、長い返答の末尾に紛れ込ませる形は避けてください。無回答は何も決着しません。沈黙は保留であって Yes でも記録された No でもありませんが、以降の返答で同じ質問を繰り返さないでください。CLI はこの確認を opencodex のバージョンごとに最大一度しか再表示しないため、次のバージョンが自動的に再確認します。明示的に同意した場合にのみスターを付け、明示的な拒否はそれで確定なので二度と持ち出さないでください。
 :::
 
+:::caution[Codex リセットクレジットの同意]
+リセットクレジットの確認は読み取り専用です。ユーザーに代わって
+`ocx account reset-credits <id|main> --consume --yes` を実行したり、消費 API を呼び出したり
+しないでください。エージェント主導の試行は `agent_consent_required` で拒否されます。管理者
+トークンやクライアントの `confirmed` フィールドでこの拒否を回避してはいけません。クレジットを
+消費できるのは、ユーザーが手入力して確認した CLI 実行、または短命な GUI セッションと別途再入力
+した所有者管理者トークンを組み合わせるループバックダッシュボード操作だけです。リモート
+ダッシュボードはその GUI セッションを発行できないため、ホスト上のローカル CLI 同意フローを
+使用する必要があります。
+:::
+
 ## ヘッドレスインストールを確認する
 
 スクリプトおよびエージェントの実行では、次の読み取り専用チェックを使用します。

docs-site/src/content/docs/ja/guides/web-dashboard.md

@@ -25,6 +25,8 @@ bun run dev:gui
 
 `localhost` や `127.0.0.1` などのループバックアドレスで開いたダッシュボードは、短時間有効な GUI セッションを自動的に受け取るため、通常はトークン入力が不要です。ループバック以外のホストで公開する場合は、`OPENCODEX_ADMIN_AUTH_TOKEN`、または自動生成される `~/.opencodex/admin-api-token` ファイルの管理トークンが必要です。
 
+Codex reset credit の消費は例外です。この不可逆操作にはループバック GUI セッションに加えて、所有者による管理トークンの再入力が必要です。リモートダッシュボードでは GUI セッションを発行できないため、reset credit の消費にはローカル CLI の同意フローを使用してください。
+
 リモートダッシュボードでは標準のパスワードフォームが表示され、ブラウザのパスワードマネージャーで保存・自動入力できます。ダッシュボード自体はトークンをメモリ内だけに保持し、`localStorage` や `sessionStorage` には書き込みません。保存するかどうかはブラウザまたはパスワードマネージャーだけが決定します。
 
 ## できること

docs-site/src/content/docs/ja/reference/cli/providers-accounts.md

@@ -207,7 +207,7 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 ### `ocx account reset-credits <id|main> [--consume --yes]`
 
-アカウントの Codex リセット クレジットを検査します。クレジットの消費は破壊的であり、`--consume` と `--yes` の両方が必要です。
+アカウントの Codex リセット クレジットを検査します。消費は破壊的なため、ユーザーが手入力で確認した実行で `--consume` と `--yes` の両方が必要です。エージェント駆動の実行は one-shot のローカル同意 capability を発行する前に拒否され、再利用可能な管理トークンでは代替できません。CLI は terminal response を受け取るまで同じ operation ID を永続的に再利用するため、timeout 後は新しい消費を開始せず同じコマンドを再実行してください。
 
 ### `ocx account main <subcommand>`
 

docs-site/src/content/docs/ja/reference/management-api.md

@@ -217,7 +217,7 @@ Authorization: Bearer <admin-token>
 | `PUT /api/codex-auth/failover` |アカウントのフェイルオーバーしきい値を設定する | 400 無効なしきい値 |
 | `GET /api/codex-auth/quota` |キャッシュされたクォータ状態をアカウントごとに読み取る | — |
 | `GET /api/codex-auth/reset-credits` |アカウントのリセット クレジット資格を検査する | 400 アカウント ID がありません。アップストリームステータスパススルー。 500 検索失敗 |
-| `POST /api/codex-auth/reset-credits/consume` |対象となるリセット クレジットを消費する | 400 アカウント ID がありません。アップストリームステータスパススルー。 503 `server_busy`; 500 消費失敗 |
+| `POST /api/codex-auth/reset-credits/consume` | 対象のリセット クレジットを消費する。管理 token の再入力で所有者を確認した GUI session、または CLI の one-shot ローカル同意 capability が必要。管理認証だけや `confirmed` field では代替不可。呼び出し元が安定して保持する正規の小文字 UUIDv4 を `operationId` として指定し、terminal code を含む response を受け取るまで永続的に再利用する。quota refresh は別の後続 read として行う | 400 `accountId` または `operationId` の欠落/無効; 403 `agent_consent_required`; 409 `reset_credit_operation_identity_changed`; upstream status passthrough; 503 `server_busy`; 507 `reset_credit_operation_history_full`（maintainer の対応が必要、自動再試行不可）; 500 消費失敗 |
 | `POST /api/codex-auth/login` | Codex のログインまたは再認証を開始する | 400 無効なリクエスト。競合/ビジー ログイン状態 |
 | `POST /api/codex-auth/login/code` | Codex ログイン フローの手動コードを送信する | 400 無効なフロー/コード |
 | `POST /api/codex-auth/login/cancel` | Codex ログイン フローをキャンセルする | — |

docs-site/src/content/docs/ko/getting-started/for-agents.md

@@ -36,6 +36,16 @@ ocx init
 에이전트라면 GitHub 별표 프롬프트에 응답하거나, 사용자를 대신해 `gh`, GitHub의 별표 API, 또는 `POST /api/github/star`를 호출하지 마세요. 별표 표시는 사용자의 신원을 사용하며 별도의 명시적 동의가 필요합니다. 에이전트가 주도하는 실행에서는 CLI가 프롬프트를 숨기고 `.star-prompted`를 쓰지 않으며, 관리 API는 `403 agent_consent_required`를 반환합니다. 어느 쪽도 우회하지 마세요. 대신 그 안내가 뜬 시작에 이어지는 답변 맨 앞에서, 사용자가 반드시 골라야 하는 Yes/No 질문으로 한 번만 물으세요 — `lidge-jun/opencodex에 star를 남길까요? Yes / No`. "star 한번 눌러주실래요?" 같은 흘리는 말투나 긴 답변 맨 끝에 끼워 넣는 방식은 안 됩니다. 무응답은 아무것도 결정하지 않습니다. 침묵은 보류일 뿐 yes도 기록된 no도 아닙니다. 그렇다고 이후 답변에서 같은 질문을 반복하지는 마세요. CLI가 이 안내를 opencodex 버전당 최대 한 번만 다시 띄우니, 다음 버전이 알아서 다시 묻습니다. 명시적으로 예라고 답한 뒤에만 별표를 누르고, 명시적인 아니오는 그것으로 끝이니 다시 꺼내지 마세요.
 :::
 
+:::caution[Codex 리셋 크레딧 동의]
+리셋 크레딧 조회는 읽기 전용입니다. 사용자를 대신해
+`ocx account reset-credits <id|main> --consume --yes`를 실행하거나 소비 API를 호출하지
+마세요. 에이전트 주도 시도는 `agent_consent_required`로 거부됩니다. 관리자 토큰이나
+클라이언트 `confirmed` 필드로 이 거부를 우회하지 마세요. 크레딧은 사용자가 직접 입력하고
+확인한 CLI 실행, 또는 짧은 수명의 GUI 세션과 별도로 다시 입력한 소유자 관리자 토큰을 함께
+사용하는 루프백 대시보드 작업에서만 소비할 수 있습니다. 원격 대시보드는 이 GUI 세션을 발급할
+수 없으므로 호스트에서 로컬 CLI 동의 절차를 사용해야 합니다.
+:::
+
 ## 비대화형 설치 확인하기
 
 스크립트와 에이전트 실행에서는 다음 읽기 전용 점검을 사용합니다:

docs-site/src/content/docs/ko/guides/web-dashboard.md

@@ -25,6 +25,8 @@ bun run dev:gui
 
 `localhost`나 `127.0.0.1` 같은 loopback 주소에서 연 대시보드는 짧게 유지되는 GUI 세션을 자동으로 받으므로 보통 토큰을 입력할 필요가 없습니다. loopback이 아닌 호스트로 공개한 대시보드에는 `OPENCODEX_ADMIN_AUTH_TOKEN` 또는 자동 생성되는 `~/.opencodex/admin-api-token` 파일의 관리자 토큰이 필요합니다.
 
+Codex reset credit 소비는 예외입니다. 되돌릴 수 없는 이 작업은 loopback GUI 세션에 더해 소유자가 관리자 토큰을 다시 입력해야 합니다. 원격 대시보드는 GUI 세션을 발급받을 수 없으므로 reset credit 소비에는 로컬 CLI 동의 흐름을 사용하세요.
+
 원격 대시보드는 표준 비밀번호 폼을 표시하므로 브라우저 비밀번호 관리자가 토큰 저장과 자동 완성을 제안할 수 있습니다. 대시보드 자체는 토큰을 메모리에만 보관하며 `localStorage`나 `sessionStorage`에 쓰지 않습니다. 저장 여부는 전적으로 브라우저 또는 비밀번호 관리자가 결정합니다.
 
 ## 할 수 있는 일

docs-site/src/content/docs/ko/reference/cli/providers-accounts.md

@@ -206,7 +206,7 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 ### `ocx account reset-credits <id|main> [--consume --yes]`
 
-계정의 Codex reset credits를 확인합니다. credit을 소비하는 동작은 파괴적이므로 `--consume`와 `--yes`를 둘 다 요구합니다.
+계정의 Codex reset credits를 확인합니다. credit 소비는 파괴적이므로 사용자가 직접 입력해 확인한 실행에서 `--consume`와 `--yes`를 둘 다 요구합니다. 에이전트가 실행한 호출은 one-shot 로컬 동의 capability를 만들기 전에 거부되며, 재사용 가능한 관리 토큰으로 대체할 수 없습니다. CLI는 terminal 응답을 받을 때까지 동일한 operation ID를 영구 재사용하므로 timeout 뒤에는 새 소비를 시작하지 말고 같은 명령을 다시 실행하세요.
 
 ### `ocx account main <subcommand>`
 

docs-site/src/content/docs/ko/reference/management-api.md

@@ -217,7 +217,7 @@ Authorization: Bearer <admin-token>
 | `PUT /api/codex-auth/failover` | account failover threshold를 설정합니다 | 400 잘못된 threshold |
 | `GET /api/codex-auth/quota` | 계정별 캐시된 quota 상태를 읽습니다 | — |
 | `GET /api/codex-auth/reset-credits` | 계정의 reset-credit 자격을 확인합니다 | 400 누락된 account id; upstream 상태 전달; 500 조회 실패 |
-| `POST /api/codex-auth/reset-credits/consume` | 사용할 수 있는 reset credit을 소비합니다 | 400 누락된 account id; upstream 상태 전달; 503 `server_busy`; 500 소비 실패 |
+| `POST /api/codex-auth/reset-credits/consume` | 사용할 수 있는 reset credit을 소비합니다. 관리자 토큰을 별도로 다시 입력해 소유자를 확인한 GUI 세션 또는 CLI의 one-shot 로컬 동의 capability가 필요합니다. 재사용 가능한 관리자 인증이나 `confirmed` 필드만으로는 동의를 대신할 수 없습니다. 호출자가 안정적으로 유지하는 정규 소문자 UUIDv4를 `operationId`로 제공하고 terminal code가 포함된 응답을 받을 때까지 영구 재사용해야 하며, quota refresh는 별도의 후속 읽기입니다 | 400 `accountId` 또는 `operationId` 누락/잘못됨; 403 `agent_consent_required`; 409 `reset_credit_operation_identity_changed`; upstream 상태 전달; 503 `server_busy`; 507 `reset_credit_operation_history_full`(maintainer 조치 필요, 자동 재시도 금지); 500 소비 실패 |
 | `POST /api/codex-auth/login` | Codex 로그인 또는 재인증을 시작합니다 | 400 잘못된 요청; 충돌/바쁨 로그인 상태 |
 | `POST /api/codex-auth/login/code` | Codex 로그인 흐름용 수동 코드를 제출합니다 | 400 잘못된 흐름/code |
 | `POST /api/codex-auth/login/cancel` | Codex 로그인 흐름을 취소합니다 | — |

docs-site/src/content/docs/reference/cli/providers-accounts.md

@@ -279,7 +279,10 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 ### `ocx account reset-credits <id|main> [--consume --yes]`
 
 Inspect Codex reset credits for an account. Consuming a credit is destructive and requires both
-`--consume` and `--yes`.
+`--consume` and `--yes` in a hand-typed user-confirmed run. Agent-driven runs are refused before
+the one-shot local consent capability is minted; a reusable management token cannot substitute.
+The CLI durably reuses the same operation identity until a terminal response is observed, so rerun
+the same command after a timeout instead of trying to start a second redemption.
 
 ### `ocx account main <subcommand>`