run cmmand supports to exit under all error scenarios & quota detection

Signed-off-by: weizhoublue <weizhou.lan@daocloud.io>

Author: weizhoublue

docs/superpowers/plans/2026-07-11-run-retry-bounds.md

@@ -0,0 +1,176 @@
+# Run Retry Bounds Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Bound non-quota retries for non-interactive `opencode run` to five retries and 120 seconds without changing global retry behavior.
+
+**Architecture:** Keep enforcement in `src/cli/cmd/run.ts`, where the CLI consumes `session.status.retry` and can abort a Session. Quota errors retain immediate abort and key rotation; other retry statuses use `attempt` and `next` for CLI-only bounds.
+
+**Tech Stack:** TypeScript, Bun test, Effect, OpenCode SDK v2.
+
+## Global Constraints
+
+- Apply retry bounds only to non-interactive `opencode run`; do not modify `SessionRetry.policy`.
+- Known quota errors abort immediately and remain eligible for key rotation.
+- Non-quota errors never rotate keys or write `throttle.json`.
+- Allow attempts 1 through 5; reject attempt 6 before it waits.
+- Abort a non-quota retry when `status.next` would exceed 120 seconds from retry attempt 1.
+- Text and JSON retry-bound errors use `OPENCODE_RETRY_LIMIT:`.
+- Run tests and `bun typecheck` from `packages/opencode`.
+
+---
+
+### Task 1: Add retry-limit process regressions
+
+**Files:**
+- Modify: `packages/opencode/test/cli/run/run-process-limit.test.ts`
+
+**Interfaces:**
+- Consumes: `opencode.run(message, { format?, timeoutMs? })` and TestLLMServer response helpers.
+- Produces: process assertions for retry count, retry deadline, text output, and JSON output.
+
+- [ ] **Step 1: Write failing retry-count tests**
+
+Queue five retryable 500 responses followed by text and assert exit code `0`. Queue six retryable 500 responses and assert nonzero exit, duration below 30 seconds, and `OPENCODE_RETRY_LIMIT:` in stderr. Set `retry-after-ms: 0` so the suite does not sleep.
+
+```ts
+const result = yield* opencode.run("say hi", { timeoutMs: 30_000 })
+expect(result.exitCode).not.toBe(0)
+expect(result.stderr).toContain("OPENCODE_RETRY_LIMIT:")
+expect(result.durationMs).toBeLessThan(30_000)
+```
+
+- [ ] **Step 2: Write failing deadline and JSON tests**
+
+Return a retryable response with `retry-after: 121` and assert immediate nonzero exit with `OPENCODE_RETRY_LIMIT:`. Add a JSON-format sixth-failure test that requires a prefixed `error.message` while retaining retry fields.
+
+```ts
+const events = opencode.parseJsonEvents(result.stdout)
+expect(events.find((event) => event.type === "error")?.error).toMatchObject({
+  type: "retry",
+  message: expect.stringMatching(/^OPENCODE_RETRY_LIMIT:/),
+  attempt: expect.any(Number),
+  next: expect.any(Number),
+})
+```
+
+- [ ] **Step 3: Run tests and confirm red**
+
+Run:
+
+```sh
+bun test --test-name-pattern 'retry limit|Retry-After|format json' test/cli/run/run-process-limit.test.ts --timeout 60000
+```
+
+Expected: new marker and bounded-retry assertions fail because no retry-limit path exists.
+
+### Task 2: Bound CLI retry status handling
+
+**Files:**
+- Modify: `packages/opencode/src/cli/cmd/run.ts:35-55`
+- Modify: `packages/opencode/src/cli/cmd/run.ts:827-850`
+
+**Interfaces:**
+- Consumes: retry status `{ attempt, message, next }`, `SessionRetry.isQuotaOrRateLimitRetryStatus`, and `client.session.abort({ sessionID })`.
+- Produces: `OPENCODE_RETRY_LIMIT` text/JSON errors and bounded non-quota retries.
+
+- [ ] **Step 1: Add CLI-only constants and message helper**
+
+Add constants beside `quotaError` and use the existing error-payload pattern for both markers.
+
+```ts
+const RUN_RETRY_MAX_ATTEMPTS = 5
+const RUN_RETRY_MAX_WAIT = 120_000
+
+function retryLimitError(message: string) {
+  return `OPENCODE_RETRY_LIMIT: ${message}`
+}
+```
+
+- [ ] **Step 2: Track a non-quota retry deadline**
+
+Before `loop`, declare `let retryDeadline: number | undefined`. In a non-quota retry branch, reset it when `status.attempt === 1` to `Date.now() + RUN_RETRY_MAX_WAIT`. Abort before waiting when either condition is true:
+
+```ts
+status.attempt > RUN_RETRY_MAX_ATTEMPTS || status.next > retryDeadline
+```
+
+On the limit, abort the session, produce `retryLimitError(status.message)`, emit the prefixed JSON error in JSON mode, print the same text in default mode, and return from the event loop.
+
+- [ ] **Step 3: Preserve quota ordering**
+
+Keep recognized quota handling before generic retry limiting. Do not set `pendingRotation` for generic retry-limit errors.
+
+```ts
+if (status.type === "retry" && SessionRetry.isQuotaOrRateLimitRetryStatus(status)) {
+  // Existing abort, immediate exit, and key rotation path.
+}
+```
+
+- [ ] **Step 4: Run focused tests and confirm green**
+
+Run:
+
+```sh
+bun test --test-name-pattern 'retry limit|Retry-After|format json' test/cli/run/run-process-limit.test.ts --timeout 60000
+```
+
+Expected: all new retry-limit tests pass.
+
+### Task 3: Verify quota and rotation contracts
+
+**Files:**
+- Verify: `packages/opencode/test/session/retry.test.ts`
+- Verify: `packages/opencode/test/cli/run/run-process-limit.test.ts`
+- Verify: `packages/opencode/test/cli/run/run-key-rotation.test.ts`
+
+**Interfaces:**
+- Consumes: existing quota classification, process, and key-rotation fixtures.
+- Produces: evidence that retry limits do not change quota exits or API-key rotation.
+
+- [ ] **Step 1: Run regression suites**
+
+Run:
+
+```sh
+bun test test/session/retry.test.ts --timeout 30000
+bun test test/cli/run/run-process-limit.test.ts --timeout 60000
+bun test test/cli/run/run-key-rotation.test.ts --timeout 60000
+```
+
+Expected: all tests pass, including quota exits, JSON quota markers, rotation, all-key exhaustion, and throttle-disabled rotation.
+
+- [ ] **Step 2: Format and typecheck**
+
+Run:
+
+```sh
+bunx prettier --write src/cli/cmd/run.ts test/cli/run/run-process-limit.test.ts
+bun typecheck
+git diff --check
+```
+
+Expected: typecheck succeeds and whitespace check is clean.
+
+- [ ] **Step 3: Build and release verification**
+
+Run:
+
+```sh
+bun run script/build.ts --single --skip-install --skip-embed-web-ui
+PATH=/tmp/opencode-verify:$PATH timeout --signal=TERM 25s /usr/sbin/opencode-cheap run 'hi'
+PATH=/tmp/opencode-verify:$PATH timeout --signal=TERM 25s /usr/sbin/opencode-cheap run --format json 'hi'
+```
+
+Expected: both commands return nonzero before timeout; text and JSON expose `OPENCODE_QUOTA_LIMIT:`.
+
+- [ ] **Step 4: Commit implementation**
+
+Run:
+
+```sh
+git add packages/opencode/src/cli/cmd/run.ts packages/opencode/test/cli/run/run-process-limit.test.ts
+git commit -s -S -m 'fix(cli): bound run retries'
+```
+
+Expected: one signed commit containing only retry-limit implementation and tests.

docs/superpowers/plans/2026-07-11-single-key-throttle.md

@@ -0,0 +1,79 @@
+# Single-Key Throttle Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Persist and honor quota throttle records when `OPENCODE_API_KEY` contains one key.
+
+**Architecture:** Route every non-empty `OPENCODE_API_KEY` list through `runWithKeyRotation`, including one key. `KeyRotator` remains the shared throttle reader and writer. A quota failure records the key before the controller reports exhaustion; a later CLI invocation sees the same record and exits before contacting the provider.
+
+**Tech Stack:** TypeScript, Bun test, Effect subprocess CLI tests.
+
+## Global Constraints
+
+- Keep `OPENCODE_THROTTLE_ENABLE=false` as a complete read/write opt-out.
+- Do not change quota detection, API-key parsing, or retry policy.
+- Preserve final quota error and nonzero exit for a throttled single key.
+
+---
+
+### Task 1: Cover single-key shared throttle behavior
+
+**Files:**
+
+- Modify: `packages/opencode/test/cli/run/run-key-rotation.test.ts:194-215`
+
+**Interfaces:**
+
+- Consumes: `opencode.run(prompt, { env, timeoutMs })` and per-test `home` directory.
+- Produces: subprocess regression proving persisted record suppresses later invocation.
+
+- [ ] **Step 1: Replace obsolete assertion with failing shared-state test**
+
+Replace existing single-key test with test named `single key writes throttle.json and later invocation skips it after quota limit`. It must run key1 against 429 `RateLimitError`, assert nonzero exit, read `throttle.json`, assert an `OPENCODE_API_KEY` record matching `hashKey("key1")`, then run same command again with same `home` and assert nonzero exit plus `OPENCODE_QUOTA_LIMIT: all configured API keys are exhausted or throttled`.
+
+- [ ] **Step 2: Run test and confirm RED state**
+
+Run: `bun test test/cli/run/run-key-rotation.test.ts --timeout 60000`
+
+Expected: new test fails at reading `throttle.json` with `ENOENT`.
+
+### Task 2: Route one key through shared throttle control
+
+**Files:**
+
+- Modify: `packages/opencode/src/cli/cmd/run/key-rotation.ts:12-17`
+- Test: `packages/opencode/test/cli/run/run-key-rotation.test.ts`
+
+**Interfaces:**
+
+- Consumes: `parseKeys(): string[]`, `KeyRotator.selectKey()`, and `KeyRotator.recordThrottle(key)`.
+- Produces: quota persistence for any non-empty explicit key list.
+
+- [ ] **Step 1: Change only no-explicit-key fast path**
+
+Replace `if (keys.length <= 1)` with:
+
+```ts
+if (keys.length === 0) {
+  await options.execute(options.createSdk())
+  return
+}
+```
+
+Existing quota handling already calls `await rotator.recordThrottle(key)` before final exhaustion, so a one-key quota then writes the shared record.
+
+- [ ] **Step 2: Run regression and confirm GREEN state**
+
+Run: `bun test test/cli/run/run-key-rotation.test.ts --timeout 60000`
+
+Expected: all key-rotation subprocess tests pass.
+
+- [ ] **Step 3: Run focused verification**
+
+Run: `bun test test/provider/key-rotator.test.ts --timeout 30000 && bun test test/provider/throttle-store.test.ts --timeout 30000 && bun typecheck && git diff --check`
+
+Expected: all commands exit 0.
+
+- [ ] **Step 4: Commit implementation**
+
+Run: `git add packages/opencode/src/cli/cmd/run/key-rotation.ts packages/opencode/test/cli/run/run-key-rotation.test.ts && git commit -s -S -m "fix(opencode): persist single key throttle"`

docs/superpowers/plans/2026-07-11-throttle-local-time.md

@@ -0,0 +1,121 @@
+# Throttle Local Time Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Store `throttle.json` timestamps as readable local ISO 8601 strings while preserving throttle and expiry behavior.
+
+**Architecture:** `ThrottleStore` formats the two calculated timestamps into local ISO 8601 strings with milliseconds and a numeric UTC offset before persisting. It parses `endTime` when deciding whether a record is active or removable. Test fixtures use the same string representation because numeric timestamp support is deliberately removed.
+
+**Tech Stack:** TypeScript, Bun test runner, Node `fs/promises`, existing `Flock` utility.
+
+## Global Constraints
+
+- Scope is `packages/opencode` throttle persistence and its tests only.
+- `startTime` and `endTime` are local ISO 8601 strings with milliseconds and an explicit UTC offset.
+- Numeric timestamp compatibility and migration are out of scope.
+- Run tests and `bun typecheck` from `packages/opencode`, never from repo root.
+- Commit with `git commit -s -S` using a concise conventional one-line message.
+
+---
+
+## File Structure
+
+- Modify `packages/opencode/src/provider/throttle-store.ts`: change the persisted timestamp type, format local values, and parse expiry values.
+- Modify `packages/opencode/test/provider/throttle-store.test.ts`: make unit fixtures string-based and verify write format, duration, active state, and expiry cleanup.
+- Modify `packages/opencode/test/cli/run/run-key-rotation.test.ts`: replace pre-seeded numeric timestamp fixtures with local ISO 8601 strings.
+
+### Task 1: Persist and consume local ISO timestamps
+
+**Files:**
+- Modify: `packages/opencode/test/provider/throttle-store.test.ts`
+- Modify: `packages/opencode/test/cli/run/run-key-rotation.test.ts`
+- Modify: `packages/opencode/src/provider/throttle-store.ts`
+
+**Interfaces:**
+- Consumes: `createThrottleStore({ configDir })` with `isThrottled`, `addThrottle`, and `cleanExpired`.
+- Produces: `throttle.json` records whose `startTime` and `endTime` are local ISO 8601 strings, such as `2026-07-11T14:21:02.689+08:00`.
+
+- [x] **Step 1: Write the failing unit and CLI fixture changes**
+
+Add this test helper near `hashKey` in both affected test files, using local date parts and `getTimezoneOffset()` to generate a portable local ISO string:
+
+```typescript
+function localTime(time: number) {
+  const date = new Date(time)
+  const offset = -date.getTimezoneOffset()
+  const sign = offset >= 0 ? "+" : "-"
+  const pad = (value: number) => String(value).padStart(2, "0")
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`
+}
+```
+
+Replace every pre-seeded unit and CLI record timestamp with `localTime(now - 1_000)` or `localTime(now + 60_000)` as appropriate. In the `addThrottle` creation test, replace numeric subtraction with these assertions:
+
+```typescript
+expect(data[0].startTime).toMatch(/\.\d{3}[+-]\d{2}:\d{2}$/)
+expect(data[0].endTime).toMatch(/\.\d{3}[+-]\d{2}:\d{2}$/)
+expect(Date.parse(data[0].endTime) - Date.parse(data[0].startTime)).toBe(120 * 60 * 1000)
+```
+
+Apply the same parsed-duration assertion to the upsert test. Add a test that calls `addThrottle(..., -1)` then `isThrottled(...)`, expects `false`, and verifies that the expired record was removed.
+
+- [x] **Step 2: Run the targeted unit test and verify it fails**
+
+Run:
+
+```bash
+cd packages/opencode && bun test test/provider/throttle-store.test.ts
+```
+
+Expected: FAIL because the production store still writes numbers and compares `now` directly to `record.endTime`.
+
+- [x] **Step 3: Implement the smallest timestamp conversion and parsing change**
+
+Change the record type and add these helpers below it:
+
+```typescript
+type ThrottleRecord = {
+  source: string
+  key_hint: string
+  key_hash: string
+  startTime: string
+  endTime: string
+}
+
+function formatLocalTime(time: number) {
+  const date = new Date(time)
+  const offset = -date.getTimezoneOffset()
+  const sign = offset >= 0 ? "+" : "-"
+  const pad = (value: number) => String(value).padStart(2, "0")
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`
+}
+
+function isExpired(record: ThrottleRecord, now: number) {
+  const endTime = Date.parse(record.endTime)
+  return Number.isNaN(endTime) || now >= endTime
+}
+```
+
+In `isThrottled`, replace the numeric comparison with `if (!isExpired(record, now)) return true`. In `addThrottle`, write `startTime: formatLocalTime(now)` and `endTime: formatLocalTime(endTime)`. In `cleanExpired`, replace `now >= r.endTime` with `isExpired(r, now)` in the matching-record predicate so expired and invalid old numeric entries are removed.
+
+- [x] **Step 4: Run focused verification**
+
+Run:
+
+```bash
+cd packages/opencode && bun test test/provider/throttle-store.test.ts && bun test test/cli/run/run-key-rotation.test.ts && bun typecheck
+```
+
+Expected: all targeted tests pass and `bun typecheck` exits 0.
+
+- [x] **Step 5: Review changed files and commit**
+
+Run:
+
+```bash
+git diff --check && git diff -- packages/opencode/src/provider/throttle-store.ts packages/opencode/test/provider/throttle-store.test.ts packages/opencode/test/cli/run/run-key-rotation.test.ts
+git add packages/opencode/src/provider/throttle-store.ts packages/opencode/test/provider/throttle-store.test.ts packages/opencode/test/cli/run/run-key-rotation.test.ts
+git commit -s -S -m "fix(opencode): store throttle times locally"
+```
+
+Expected: no whitespace errors; one signed and signed-off commit containing only the three implementation files.