fix(errors): stop suggesting --timeout, which adapter commands do not accept

[cat0825]

Description

The default TimeoutError hint tells users to retry with --timeout <seconds>, but adapter commands do not declare that flag — following the advice fails with a different error.

Only two commands in the repo accept --timeout, and neither is an adapter command: browser wait (--timeout <ms>, src/cli.ts:2412) and antigravity serve (--timeout <seconds>, src/cli.ts:3612). The default hint is reached from the generic runWithTimeout() wrapper (src/runtime.ts:24-31) used by adapter execution, plus a handful of adapters that omit the third constructor argument.

Before:

$ OPENCLI_BROWSER_COMMAND_TIMEOUT=1 opencli xiaohongshu search "opencli" --limit 3
ok: false
error:
  code: TIMEOUT
  message: xiaohongshu/search timed out after 1s
  help: Try again, or increase timeout with --timeout <seconds> (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)
  exitCode: 75

$ opencli xiaohongshu search "opencli" --limit 3 --timeout 90
error: unknown option '--timeout'          # exit 1

This matters most for agents driving OpenCLI programmatically: the natural recovery is to retry with the flag the error text named, which converts a retryable TIMEOUT (exit 75) into an opaque usage error (exit 1).

The fix points the default hint at OPENCLI_BROWSER_COMMAND_TIMEOUT, which is the knob that actually applies to adapter commands. The 49 call sites that pass an explicit hint are unaffected.

Related issue: Fixes #2415

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🌐 New site adapter
• 📝 Documentation
• ♻️ Refactor
• 🔧 CI / build / tooling

Checklist

• I ran the checks relevant to this PR
• I updated tests or docs if needed
• I included output or screenshots when useful

Tests

The existing assertion was expect(err.hint).toContain('timeout'), which matches the broken text as well as the fixed one — it could not catch this. Tightened it to assert the env var, and added two cases:

• default hint must not contain --timeout (fails on the old wording — verified by reverting the source and re-running: AssertionError: expected 'Try again, or increase timeout with -…' not to contain '--timeout')
• a caller-supplied hint is still preserved verbatim

$ npx tsc --noEmit                    # clean
$ npm test
 Test Files  628 passed (628)
      Tests  7288 passed | 1 skipped (7289)

Baseline on main before the change was 7286 passing; the +2 are the new cases.

Note

While this is being touched, there is an adjacent inconsistency worth flagging separately: browser wait takes --timeout in milliseconds while antigravity serve takes seconds, so a user who does find a working --timeout may still pass the wrong magnitude. I left that alone here to keep the change minimal — happy to open a follow-up if you'd like it unified.

[cat0825]

Rechecked against current main (48712502), since #2388 has landed in src/errors.ts — the same file this PR touches.

No conflict: the two changes are in different regions (this PR is the TimeoutError hint at ~line 122, #2388 is the duck-typing branch in toEnvelope at ~line 257). Verified with a real trial merge rather than reading the diff:

• git merge --no-commit --no-ff upstream/main → auto-merged cleanly, both changes present afterwards
• npx vitest run src/errors.test.ts → 19 passed
• npx tsc --noEmit → clean

So this is still mergeable as-is; happy to rebase if you'd prefer a linear history. Same check on the other two branches (#2426, #2427): neither touches a file changed by the last six upstream commits.

The workflow run is still sitting at action_required (first-time contributor), so CI needs your approval before any checks can report.

[cat0825]

Updated onto current main (ahead 2, behind 0, MERGEABLE, CLEAN). No conflicts.

Scope: stops the error path from suggesting --timeout, a flag the adapter commands do not accept, so the hint no longer sends users to a nonexistent option.

@jackwener low-risk one whenever you have a moment. Two siblings alongside it: #2426 (update-check) and #2427 (doctor).