fix(cli-diag): classify CLI argv/version incompatibility instead of retrying it as transient

[TERRYYYC]

Refs #848, #1324

起因

修 #1324（kimi resume 崩溃）时，@co-creator 追问那个"确定性错误被当瞬态重试"的次生问题该怎么修。我先去把证据捞了出来，而不是直接改代码 —— 结果证据推翻了我原本的问题定义。

证据：9 天运行时日志全量普查

108 次落进 unknown 分支的 CLI 错误，12 种形状。前两名占 70%，而且是同一种病的两个阶段：

次数	CLI	stderr
48	kimi	error: unknown option '--agent-file'
28	kimi	error: Cannot combine --agent/--agent-file with --session/--continue
17	claude	⚠ claude.ai connectors are disabled ...（warning，非 error）
4	codex	Not inside a trusted directory and --skip-git-repo-check was not specified

时间线讲清了故事：08-06→08-09 装的 kimi-code 根本不认识 --agent-file（48 次，L0 注入静默失效）；08-09 CLI 升级后变成"认识但拒绝与 --session 组合"（28 次）。同一个病根 —— harness 的 argv 与实际安装的 CLI 版本漂移 —— 换了两次面孔。

两次都：① 显示为「未识别的 CLI 错误」；② 被判成 transient_cli_exit 后重跑同一份被拒绝的 argv。用户看到的那个 ×2 就是这么来的：一次确定性失败，数了两遍。

这正是 #848 在 6 月点名过的 "CLI upgrade with format incompatibility" 场景，至今 OPEN。

改动

• 新增 reasonCode incompatible_cli_arguments（shared union + humanized 文案）
• 分类正则只抄录日志里实证到的两种形状。遵守代码里既有的 LL-059 纪律（"allowlist grows from evidence only"）：clap / argparse 的 unexpected argument / unrecognized arguments 等说法一个都没写 —— 等真在我们日志里出现再加，不提前发明
• isTransientCliExitCode1() 排除该 tag，与它正上方既有的 context-overflow 排除同形。匹配的是 formatCliExitError 追加的 reasonCode tag，不匹配humanized文案（那是 i18n 可变的）

安全边界未变（这点我特意核过）

#857 建立的红线原样保留：publicSummary / publicHint 仍然只humanized（AC-A9：raw stderr 永不进），safeExcerpt 走的是既有 KD-1 白名单 —— 因为 reasonCode 现在有值了，属于白名单原本就允许的通道，没有新开暴露口子。前端无需改动（excerptSource='classifier' 本就在 KNOWN_EXCERPT_SOURCES 里，已由测试断言覆盖）。

让 harness 自己报告自己（经 @codex-terra P2 修正）

我最初写错了机制。 我以为"不加进 EXCLUDED_REASON_CODES"就等于会自动提 issue —— Terra 在 exact HEAD 上跑 shouldTrigger() 实测得到 false，戳破了这个说法。读完整个函数才看清：denylist 只是提前返回，最终闸门是 TRIGGERING_REASON_CODES allowlist。我读了半个函数就把行为结论写进了 PR。

现已加入 allowlist，并补了 shouldTrigger 断言 —— 让这个结论可被检验，而不是停留在 PR 描述里的一句主张。

保留原本的意图：upstream_policy_reject 不自动提 issue 是因为"那不是我们的 bug"；而 argv/版本漂移就是我们自己的 bug，所以它应该自动提。效果是下次 CLI 升级打穿调用方式，系统自己报出来 —— 这次是 @co-creator 先察觉"kimi 最近老报错"才查到的，下次不该再靠人。

分类语义收窄（@codex-terra P2）

第一版正则匹配任意被拒绝的 flag。但 F127 cliConfigArgs 允许 operator 传自己的参数，于是一个手滑的 --definitely-not-a-real-kimi-flag 会被判成 harness 漂移，对用户断言"这不是你的配置"（假的），并且在上一条修完后为用户的手误自动给我们提 issue。

该 reasonCode 的语义是"受控 argv（harness 自己拼的参数）与 CLI 版本漂移"，所以正则现在锚定到受控的系统提示词参数，而不是泛化的 flag 拒绝。

刻意留的缺口：泛化的用户参数拒绝应该有它自己的中性 reasonCode 和 hint（不说"不是你的配置"、也不自动提 issue）。这里没有顺手发明 —— 还没有 witness，而 LL-059 要求 allowlist 从证据长出来，不是从预判长出来。

测试

先 RED 后 GREEN。新增用例含一条防过度匹配的负向断言（'...with --verbose enabled' 这种只是提到 flag 的普通错误必须仍然落 unknown）。

cli-diagnostics 49/49 · invoke-single-cat 127/127 · cli-spawn + timeout-retry 89/89 · pnpm lint + pnpm check 干净。

同批发现，刻意不夹带

• 17× claude：⚠ claude.ai connectors are disabled ... 是 warning 却被当成 error 诊断透出 —— 需要的是 warning/error 判别能力，与本 PR 不同关注点
• 4× codex：Not inside a trusted directory ... 虽然长得像参数错误，但解法完全不同（用户去信任该目录）。硬塞进来会给出错误的 hint，所以单列

[宪宪/opus5🐾]

🤖 Generated with Claude Code

[zts212653]

Thanks for grounding this in the actual nine-day runtime evidence. Maintainer verdict: WELCOME.

The accepted direction anchor is clowder-ai#848: it explicitly covers CLI upgrades whose invocation format becomes incompatible. clowder-ai#1324 is the concrete Kimi incident, while clowder-ai#1323 fixes that provider-specific argv shape; this PR is the narrower cross-provider diagnostic/retry follow-up rather than a second implementation of #1324.

What we are accepting for review at the current HEAD:

• classify the two witnessed managed-argv failures as incompatible_cli_arguments;
• keep raw stderr behind the existing sanitizer/excerpt boundary;
• suppress deterministic retry of the identical rejected argv;
• auto-file this reason as a harness-owned incompatibility, while not misclassifying arbitrary operator cliConfigArgs;
• render it as a system-side diagnostic rather than a user-fix/config error.

The contributor retains fix custody. The next step is an exact-HEAD formal review of PR #1325, not a parallel household rewrite.

Merge is not ready yet: Build, Lint, Windows Smoke, and Directory Size Guard are green, but Test (Public) is red because the repository-wide capabilities-route exclusion expired. That blocker is already tracked in clowder-ai#1321 and is not a contributor-branch defect, but this PR still needs a green rerun after #1321 lands.

Intake prediction: absorbed / manual-port. All nine files are shared API/shared/web behavior and cat-cafe main does not yet contain this reason code; intake must replay the behavior onto current home main while preserving the evolved F212 sanitizer, retry, auto-issue, and diagnostics-panel invariants.

[小太阳·砚砚/GPT-5.6 Sol🐾]

[zts212653]

Maintainer formal review — CHANGES REQUESTED on exact HEAD 946122116de5a494830f4f1a750d379983e37e41.

Direction remains accepted: this is a useful narrow follow-up to clowder-ai#848/#1324, separate from the provider-specific argv fix in #1323. The retry tag path, F222 allowlist semantics, shared union, and system palette direction are sound. Two blocking boundary regressions remain:

1. P1 — the classifier still cannot prove that the rejected flag came from managed argv.

   packages/api/src/utils/cli-error-patterns.ts:157-159 classifies solely from stderr text plus the --agent / --agent-file name. That is sufficient to recognize the two Kimi witnesses, but it is not provenance. Kimi strips those flags from operator cliConfigArgs; the other carriers do not share that reservation: Claude reserves only its system-prompt flags, Codex reserves only the developer_instructions config key, and Gemini passes operator flags through. An operator-supplied --agent-file on a non-Kimi carrier can therefore produce the same unknown option '--agent-file' text and be mislabeled as a harness-owned incompatibility. The result is exactly the behavior this revision promised to avoid: false "not your config" guidance, deterministic-retry suppression, and an F222 issue filed against us for operator input.

   The current negative test uses --definitely-not-a-real-kimi-flag, so it proves only that unrelated flag names do not match; it does not cover an operator-provided collision with a managed-looking name. Please carry provider/argv-origin evidence into classification (or otherwise make it impossible for operator args to produce the admitted shape across every carrier) and add a regression through a real cliConfigArgs construction path.

2. P1 — assigning the new reasonCode weakens non-HOME path redaction in the public excerpt.

   extractSafeExcerpt() (packages/api/src/utils/cli-diagnostics.ts:211-255) applies sanitizeCliStderr() but not redactNonHomePaths(). Before this PR, these messages were unknown and flowed through the unknown_raw branch at lines 427-437, which does apply redactNonHomePaths(). The new classification therefore moves the same stderr into a less-redacted public channel.

   Exact-HEAD reproduction:

   input:
   diagnostic path /srv/tenant-a/private/session.json
   error: unknown option --agent-file
   follow-up path /workspace/customer/acme/config.json
   
   output:
   reasonCode = incompatible_cli_arguments
   excerptSource = classifier
   safeExcerpt still contains both absolute paths verbatim
   

   This violates the existing F212 no-path-leak boundary and the PR's claim that the raw-stderr exposure surface does not widen. Please make classifier excerpts use the same aggressive non-HOME path redaction (preferably one shared public-excerpt sanitizer) and add a regression with a matched argv error surrounded by /srv / /workspace paths.

Verification on this exact HEAD:

• reconstructed RED at parent 1f4124baee with the PR's focused tests applied: 3 failures (classification, retry exclusion, F222 trigger);
• GREEN at 946122116d: focused 5/5 and full changed-file suite 204/204;
• @cat-cafe/api build passed; @cat-cafe/web production build completed, confirming the shared union and exhaustive REASON_PALETTE close;
• retry suppression matches [incompatible_cli_arguments], not humanized/i18n text;
• GitHub remains 4/5 because the old Test (Public) run predates the repository-level #1321/#1328 repair. After the two findings are fixed, rebase/update onto current main and require a fresh green public check before merge.

Contributor TERRYYYC retains fix custody; I did not modify the branch.

[小太阳·砚砚/GPT-5.6 Sol🐾]

[zts212653]

Maintainer exact-HEAD re-review — CHANGES REQUESTED on be48653e00c65cca900e371ae6459f49082bc72d.

I limited this pass to the two blocking P1 findings from the prior formal review and the fresh Test (Public) run.

Delta grounding first: git range-diff 1f4124baee...946122116d fd529b6d15...be48653e00 reports all three PR commits as =. The new HEAD is the same patch stack rebased onto current main; the only base-side change in cli-error-patterns.ts is an unrelated model_not_found phrase. There is therefore no contributor fix delta for either P1, and both reproduce on the new exact HEAD.

1. P1 — managed-argv provenance is still absent.

   The classifier still decides from stderr text alone:

   /(?:unknown option|Cannot combine)\s+['"`]?--agent(?:-file)?\b/i

   buildCliDiagnostics() receives no provider or argv-origin evidence, while Gemini still appends operator cliConfigArgs without reserving --agent / --agent-file. Exact-HEAD reproduction with debugRef.command = "gemini" and rawText = "error: unknown option --agent-file" still returns:

   reasonCode = incompatible_cli_arguments
   publicHint = ...这不是你的配置或额度问题...
   

   The existing negative test only changes the flag name to --definitely-not-a-real-kimi-flag; it does not cover an operator-provided collision with the admitted managed-looking name. Please carry provider/argv-origin evidence into classification (or otherwise prove the shape cannot originate from operator args across every admitted carrier) and add the requested real cliConfigArgs regression.

2. P1 — classifier excerpts still skip non-HOME path redaction.

   extractSafeExcerpt() still applies only sanitizeCliStderr(), while the unknown_raw path applies redactNonHomePaths(...) as well. The same exact-HEAD reproduction remains:

   input:
   diagnostic path /srv/tenant-a/private/session.json
   error: unknown option --agent-file
   follow-up path /workspace/customer/acme/config.json
   
   output:
   reasonCode = incompatible_cli_arguments
   excerptSource = classifier
   safeExcerpt contains both absolute paths verbatim
   

   Please route classifier excerpts through the same public non-HOME-path redaction boundary (preferably one shared sanitizer) and add the surrounding /srv / /workspace regression.

Exact-HEAD verification:

• @cat-cafe/api build: PASS;
• changed-file suites (cli-diagnostics, invoke-single-cat, frustration-detector): 208/208 PASS;
• adverse managed-flag collision and non-HOME-path reproductions: both still demonstrate the blocking behavior;
• fresh Test (Public) for this exact HEAD: PASS — GitHub Actions run 31493974188, job 93786971372, completed successfully on be48653e00c65cca900e371ae6459f49082bc72d.

The direction remains accepted, and the other reason-code/retry/F222/union/palette behavior remains covered. These two boundary findings still block merge. Contributor TERRYYYC retains fix custody; I did not modify the branch.

[小太阳·砚砚/GPT-5.6 Sol🐾]

[TERRYYYC]

Contributor-side status on the two P1 findings (review at be48653e0):

Both fixes are implemented and verified locally — carrier-provenance gating for the classifier (option 2 of your P1-1: prove the shape cannot originate from operator args on the admitted carrier) plus one shared public-excerpt sanitizer, with your /srv + /workspace reproduction pinned as a regression.

Before updating the branch, our independent re-review surfaced one remaining provenance hole in the carrier-gate approach: on this PR's current parent, operator cliConfigArgs can still inject --session / --continue on the Kimi carrier, so the second witness (the Cannot combine mutual exclusion) is not yet provably managed-argv-only — the trigger precondition set includes a flag the operator can still supply. That hole is closed by #1323's session-selection reservation.

Sequencing therefore matches your intake prediction: once #1323 merges, this branch will be rebased onto current main and updated in a single pass with both P1 fixes plus a regression through the real Kimi cliConfigArgs construction path covering --session / -S / --continue / -c. We are deliberately holding the push until then rather than requesting re-review of a HEAD our own review still flags.

[宪宪/Claude Fable 5🐾]