fix(claude): opt in to harness prompt-cache stabilization (carry #4052)

devlog/_plan/260912_cache_lane/035_prefix_adapt.md

@@ -0,0 +1,7 @@
+# Prefix current-dev adaptation
+
+Previous D: reverse native affinity correction reviewed. Parent requested current-dev integration of own prefix branch #4347. Class C2 adaptation; all existing no-local-suites/no-merge restrictions apply. Safe rebase own prefix commit df5853600a onto fetched origin/dev, dropping no product change. Existing roadmap commit already integrated via #4338. Record old/new immutable refs. No other branch/worktree edits.
+
+MODIFY only conflict resolutions in structure/clients/claude-desktop.md, structure/data-planes/inbound-compat.md, structure/runtime.md: preserve latest dev appended helper contract AND prefix opt-in section/link. Runtime prefix delta remains byte-identical. Test layout maps auto-merge retaining both sides' entries. No new implementation.
+
+Independent design/audit: confirm union of append-only docs is correct; compare old base..old tip to new base..new tip by file and range-diff, disclose every changed patch. Existing independent source review at df585 remains valid only for unchanged authored bytes, and conflict interdiff needs a separate inherited reviewer. C text diff check and new exact head hosted CI tracking; no local product tests. Push --force-with-lease tied to old prefix head and --no-verify; parent owns merge.

devlog/_plan/260912_cache_lane/036_prefix_linear.md

@@ -0,0 +1,13 @@
+# Linear canonical suffix parsing
+
+Previous D: affinity integrated by parent; prefix serial base81f0c78d7a2bf56e759511e89f450c7d49e0a42e. New public reviews on4347 discussion_r3995155701/P1 and3995155709/P2 require code repair, not only adaptation. C3 bounded parser performance/correctness. Same no-local-suites/build/typecheck/install/no-merge scope; hosted CI is runtime verifier.
+
+First rebase own prefix commits after5042a376 onto pinned81f0c78d. Union three mapped structure conflicts preserving base affinity/helper paragraphs and prefix opt-in contract; original runtime delta unchanged before repair. Preserve Warexpor/Cursor credit.
+
+MODIFY src/claude/inbound-cache-stabilize.ts: replace repeated whole-rest regex scans and slices with one forward fence-range scan plus backward line cursor. Each backward iteration strips trailing horizontal/line whitespace, isolates one complete single line via lastIndexOf newline, accepts only exact total_tokens with digits + one ASCII space + tokens left or either full exact TaskCreate paragraph, and checks monotonically decreasing fence-range cursor. On recognized line move end cursor before separator newlines, retain only latest total/nudge. Slice original instructions once at final end; no match returns original bytes. Fence opener/closer behavior retained. No whole shrinking-string rescan or per-footer copy. No multiline/tab/formfeed inside canonical tag.
+
+MODIFY tests/claude-integration/claude-inbound-cache-stabilize.test.ts: add controls for newline/tab/formfeed between digits and tokens left, exact single-space positive, CRLF outer separators, many consecutive footer sequence (20k) retains exact prefix/latest footer. No tight wall-clock benchmark; normal hosted test timeout plus source complexity review validates bounded work. Preserve existing fence/default-off/HTTP/header/config tests.
+
+Update structure/data-planes/inbound-compat.md to state single-line canonical notices and linear scan. Exact old runtime-delta comparison binds inherited source review, new parser receives independent A and implementation source audit. GitHub hosted finaltip CI after --no-verify lease push. Parent owns merge and review-thread resolution. Safe public final handoff will be exported to tracked devlog at verification completion; scratch raw evidence retained locally only.
+
+Design dispositions LINEAR01-04 accepted. Keep committed `end` unchanged until notice acceptance. A speculative `lineEnd` skips only complete LF/CRLF sequences; candidate horizontal padding trims only ASCII space/tab by indices. Do not cross whitespace-only lines, consume lone CR or trim unmatched prefix. After matching, commit end before immediately preceding LF/CRLF runs; failed candidate returns prior committed prefix unchanged. Compare exact nudge strings and anchored digits + literal single space. Fence index decreases only. Add preserved two-space prefix, malformed-before-valid, whitespace-only separator, loneCR and many closed fences+footers controls.

devlog/_plan/260912_cache_lane/037_prefix_slot.md

@@ -0,0 +1,9 @@
+# Final prefix slot and durable evidence
+
+Parent pinned dev81f6cd5915ca59f784a584d8cd739adff55c9bd0 after Cline4371, holding other structure merges. Previous D: linear canonical parser repair e1d262acee freshly source-audited PASS0, no local product execution. Class C2 adaptation/docs, no local suites/build/typecheck/install/no merge.
+
+Rebase own three commits after81f0c78d onto81f6cd5915, preserving exact repair/source/test bytes and all parent-base source/docs. Conflict union only in mapped docs; unexpected runtime conflicts need independent review. Compare oldbase81f0..e1d262 against newbase81f6..newhead; source/test patches identical. Lease push remains pinned to remote e1c92f10c3, which was intentionally kept during repair.
+
+MODIFY050_verify.md: .tmp is scratch, not sole durable evidence. NEW060_handoff.md safe tracked index includes original dispositions, branches/PRs, known source-audit and CI references, remaining3433 live acceptance, local suites NOT RUN, cycle list and parent-only integration. Private paths/raw evidence stay in scratch. Export current exact SHA/CI/source-review data to4347 PR body on publication, then update only PR body with terminal results; this preserves final source head without a self-referential new commit. Keep parent integration annotations when updating PR body. Final verification must inspect the exported body before closing goal.
+
+Independent conflict audit binds prior fresh linear-parser PASS to final head; no old pre-P1/P2 PASS stands in for repair. Parent decides review-thread resolution and merge.

devlog/_plan/260912_cache_lane/050_verify.md

@@ -1,7 +1,9 @@
 # Hosted verification and delivery
 
-Prerequisites: independent implementation PRs. NEW durable .tmp/cache-handoff/050_handoff.md records actual worktree, branches/PR URLs/full head SHA, source dispositions/credits, cycle receipts, remaining acceptance and reviews. Capture gh pr view/checks and gh run view JSON at each final independent tip; ordinary manual children only for real correction dependencies. No native membership mutation.
+Prerequisites: independent implementation PRs. Scratch .tmp/cache-handoff/050_handoff.md records actual worktree, branches/PR URLs/full head SHA, source dispositions/credits, cycle receipts, remaining acceptance and reviews. Capture gh pr view/checks and gh run view JSON at each final independent tip; ordinary manual children only for real correction dependencies. No native membership mutation.
 
 No product source changes planned here. If CI exposes a scoped defect, append a numbered repair plan and full PABCD cycle before implementation, then verify new exact head. Hosted workflow definition determines jobs actually executed; skipped/cancelled runs are never passes. No automatic workflow cancellation or protection edit. Local tests/build/typecheck/install remain NOT RUN. Only source/diff checks may be wrapped in cxc receipt and must retain their true label.
 
 C: final head matches hosted run headSha; successful required jobs and skipped jobs recorded individually. D: finish handoff with source review gaps and Hermes field residual, no merge/issue closure. Parent decides integration.
+
+Durable delivery: 060_handoff.md is the tracked safe index. Before any scratch cleanup, export exact final PR/head/CI and source-review evidence into the #4347 PR body, preserving parent annotations, and read it back. Terminal CI updates change that body only, so the verified source head remains stable. Private paths and raw security analysis never enter the public index or PR. Scratch is not the sole retained handoff.

devlog/_plan/260912_cache_lane/060_handoff.md

@@ -0,0 +1,26 @@
+# Cache lane handoff index
+
+The cache lane contains independent dev PRs, with no native stack or artificial dependency chain. Main implementation used managed worktree slot `7e43`; the coordination task owns integration and original-PR closures. This index preserves source dispositions. Exact final-head CI and source-review snapshots are exported to the [prefix PR description](https://github.com/lidge-jun/opencodex/pull/4347) and read back at delivery; private execution paths and raw scratch evidence are excluded.
+
+| Source | Delivered PR / branch | Outcome and remaining evidence |
+| --- | --- | --- |
+| #4118 | [#4338](https://github.com/lidge-jun/opencodex/pull/4338), `codex/260912-60plus-cache-claim` | Claim deferral adopted. Parent integrated as `75d3e5c78f9ac7fc7125ee27294a962456bf32bb` and closed the source PR. Exact carried head `d27db6dd56c481572728bc99043e2c528f11e1bc`: [hosted CI 34673563105](https://github.com/lidge-jun/opencodex/actions/runs/34673563105) SUCCESS, 19 jobs successful / 2 skipped. |
+| #4050 | [#4340](https://github.com/lidge-jun/opencodex/pull/4340), `codex/260912-60plus-cache-affinity` | Go affinity adopted and reverse Go-to-ChatGPT native identity repaired. Parent integrated as `81f0c78d7a2bf56e759511e89f450c7d49e0a42e`. Final source head `d354924f0af38a48f5768fca0cd09c5145bdb4bd`, fresh repair/conflict audit PASS, blocker 0. [Hosted CI 34674962749](https://github.com/lidge-jun/opencodex/actions/runs/34674962749) pending at this checkpoint. |
+| #4052 | [#4347](https://github.com/lidge-jun/opencodex/pull/4347), `codex/260912-60plus-cache-prefix` | Reimplemented behind literal-true operator configuration; ordinary callers preserve roles and keys. Fresh public P1/P2 findings superseded the first helper approval. The repaired parser uses decreasing line/fence cursors and exact single-space grammar; fresh algorithm audit PASS at `e1d262acee27d55388cccdb96430669e944fbd90`. Final base adaptation and hosted evidence are recorded in the PR body. |
+| #3433 | [#4365](https://github.com/lidge-jun/opencodex/pull/4365), `codex/260912-60plus-cache-hermes` | Transport contract tests only, no runtime synthesis. Exact source head `b254efc8385ce2a9dc34b9a5ac7d2a449605d75d`, independent source audit PASS, blocker 0. [Hosted CI 34674763850](https://github.com/lidge-jun/opencodex/actions/runs/34674763850) pending at this checkpoint. Live issue acceptance below remains open. |
+
+## Hermes acceptance still open
+
+The [latest controlled field-presence observation](https://github.com/lidge-jun/opencodex/issues/3433#issuecomment-5551855276) omitted measured identity fields. The [maintainer follow-up](https://github.com/lidge-jun/opencodex/issues/3433#issuecomment-5556427205) requests a real client-assigned identity stable within a conversation and distinct for a fresh conversation, then comparison at the outbound boundary. Synthetic A/A/B fixtures verify the OCX Direct transport contract when executed; they do not prove actual Hermes emission, Pool cohort stability or improved cache hits. #3433 is not solved by the Claude PRs. #3719 thinking replay is separate.
+
+## Review and attribution
+
+Carry commits preserve luvs01 credit for #4118; David Wang plus original GPT-6 Astra/Claude Fable trailers for #4050; Warexpor and Cursor Agent for #4052. No code from other authors is relabeled as sole authorship.
+
+The first affinity source review missed reverse native routing; the repair was independently reviewed before parent integration. The first prefix helper review missed quadratic scanning and broad inner whitespace; it was superseded by a fresh algorithm review after correction. A green original-PR run or plan approval never substitutes for final implementation review. Outstanding GitHub objections and final-tip status are re-read before the coordinating maintainer's decision.
+
+## Execution record
+
+Each work phase used its own persisted P-A-B-C-D cycle: roadmap, claim, affinity, prefix, native-affinity repair, prefix adaptation, affinity adaptation, Hermes contract, serial affinity slot, linear prefix repair, final prefix slot, then hosted-evidence verification. Source and conflict reviews used inherited-model read-only subagents; no native architect role was claimed.
+
+Local tests of every size, build, typecheck and install were **NOT RUN** by explicit instruction. Local receipts contain text/applicability checks only. Product execution belongs to the linked GitHub-hosted runs; skipped Windows full shards and macOS control are not passing executions. Pushes used `--no-verify`, with exact old-head leases for owned branch rebases. This task did not merge, release, publish packages, restart services or change user runtime settings.

docs-site/src/content/docs/fr/guides/claude-code.md

@@ -623,3 +623,5 @@ par défaut par un contenu minimal (`blockedSkills: ["claude-api"]`).
 **Les sous-agents sont envoyés au mauvais modèle** — Les agents de la liste (`ocx-*`) utilisent les directives
 `<!-- ocx-route: ... -->`, et non l'argument `model` de l'outil Agent. Vérifiez que la directive désigne la route voulue.
 Utilisez `"haiku"` comme valeur de remplacement pour le modèle.
+
+Dans `config.json`, `claudeCode.stabilizePromptCache: true` déplace les notices Claude reconnues en fin des instructions système vers un dernier message utilisateur sur les routes traduites. La valeur par défaut est `false`. Activez cette option seulement si ce changement de rôle convient à vos clients. Les exemples dans des blocs de code et le texte non reconnu sont conservés ; le transfert Anthropic natif reste inchangé. Sans métadonnées, la clé de cache suit les instructions stabilisées. Cette option ne crée pas une identité de conversation et ne garantit aucun succès du cache amont.

docs-site/src/content/docs/guides/claude-code.md

@@ -679,3 +679,5 @@ it by default (`blockedSkills: ["claude-api"]`).
 **Subagent dispatches to wrong model** — Roster agents (`ocx-*`) use `<!-- ocx-route: ... -->`
 directives, not the Agent tool's `model` argument. Make sure the directive matches the intended
 route. Pass `"haiku"` as the model placeholder.
+
+Set `claudeCode.stabilizePromptCache` to `true` in `config.json` to relocate supported trailing Claude harness notices from system instructions to a trailing user message on translated routes. The default is `false`. Enable it only when this role change is appropriate for your clients. It preserves fenced examples and unmatched text; native Anthropic passthrough is unchanged. The metadata-less prompt-cache key then follows stabilized instructions. This does not create conversation identity or guarantee upstream cache hits.

docs-site/src/content/docs/ja/guides/claude-code.md

@@ -494,3 +494,5 @@ Anthropic バックエンドを明示すると意図的に失敗後停止しま
 **サブエージェントが誤ったモデルにディスパッチされる** — ロスターエージェント(`ocx-*`)は Agent ツールの `model`
 引数ではなく `<!-- ocx-route: ... -->` ディレクティブを使います。ディレクティブが希望ルートと一致するか確認し、
 モデルプレースホルダとして `"haiku"` を渡してください。
+
+`config.json` の `claudeCode.stabilizePromptCache` を `true` にすると、変換ルートのシステム指示末尾にある対応済み Claude 通知を最後のユーザーメッセージへ移します。既定値は `false` です。このロール変更が適切なクライアントでのみ有効にしてください。コードフェンス内の例と一致しない本文は保持され、Anthropic のネイティブ転送は変わりません。メタデータがない場合のキャッシュキーは安定化した指示から計算されます。会話 ID の生成やキャッシュヒットの保証は行いません。

docs-site/src/content/docs/ko/guides/claude-code.md

@@ -559,3 +559,5 @@ Anthropic 백엔드를 명시하면 의도적으로 실패 후 중단해요.
 **서브에이전트가 잘못된 모델로 디스패치됨** — 로스터 에이전트(`ocx-*`)는 Agent 도구의 `model`
 인자가 아니라 `<!-- ocx-route: ... -->` 지시문을 사용해요. 지시문이 원하는 라우트와 일치하는지
 확인하고, 모델 자리 표시자로 `"haiku"`를 전달하세요.
+
+`config.json`에서 `claudeCode.stabilizePromptCache`를 `true`로 설정하면 번역 경로의 시스템 지시 끝에 붙은 지원 대상 Claude 알림을 마지막 사용자 메시지로 옮깁니다. 기본값은 `false`입니다. 사용하는 클라이언트에서 이 역할 변경을 허용할 때만 켜세요. 코드 펜스 안의 예제와 일치하지 않는 원문은 보존하며, Anthropic 원본 전달 경로는 바꾸지 않습니다. 메타데이터가 없는 요청의 캐시 키는 정리된 지시문을 기준으로 계산합니다. 대화 식별자를 만들거나 상위 서비스의 캐시 적중을 보장하는 기능은 아닙니다.

docs-site/src/content/docs/ru/guides/claude-code.md

@@ -525,3 +525,5 @@ Responses `web_search_call` в парные блоки Anthropic `server_tool_us
 **Подагент отправляется не в ту модель** — агенты из ростера (`ocx-*`) используют директивы
 `<!-- ocx-route: ... -->`, а не аргумент `model` инструмента Agent. Убедитесь, что директива
 соответствует нужному маршруту. В качестве плейсхолдера модели передавайте `"haiku"`.
+
+Параметр `claudeCode.stabilizePromptCache: true` в `config.json` переносит поддерживаемые уведомления Claude в конце системных инструкций в последнее пользовательское сообщение на маршрутах с преобразованием. По умолчанию он выключен (`false`). Включайте его только когда такое изменение роли допустимо для ваших клиентов. Примеры в блоках кода и нераспознанный текст сохраняются; нативная передача Anthropic не меняется. Без метаданных ключ кэша рассчитывается по стабилизированным инструкциям. Идентификатор разговора не создаётся, попадания в кэш не гарантируются.

docs-site/src/content/docs/tr/guides/claude-code.md

@@ -732,3 +732,5 @@ modellerde opencodex varsayılan olarak bunu taslakla değiştirir (`blockedSkil
 aracının `model` argümanını değil, `<!-- ocx-route: ... -->` yönergelerini
 kullanır. Yönergenin hedeflenen rotayla eşleştiğinden emin olun. Model yer
 tutucusu olarak `"haiku"` iletin.
+
+`config.json` içindeki `claudeCode.stabilizePromptCache: true`, dönüştürülen rotalarda sistem talimatlarının sonundaki desteklenen Claude bildirimlerini son kullanıcı mesajına taşır. Varsayılan değer `false` olur. Yalnızca bu rol değişikliği istemcileriniz için uygunsa etkinleştirin. Kod bloklarındaki örnekler ve eşleşmeyen metin korunur; yerel Anthropic aktarımı değişmez. Meta veri yoksa önbellek anahtarı kararlı talimatlardan hesaplanır. Bu seçenek konuşma kimliği oluşturmaz veya üst hizmette önbellek isabeti garanti etmez.

docs-site/src/content/docs/zh-cn/guides/claude-code.md

@@ -463,3 +463,5 @@ Claude 模型时自动加载。对于原生透传，这是正常现象；对于
 
 **子代理派发到错误模型**——名册代理（`ocx-*`）使用 `<!-- ocx-route: ... -->` 指令，
 而不是 Agent 工具的 `model` 参数。请确保指令与预期路由一致。传入 `"haiku"` 作为模型占位符。
+
+在 `config.json` 中设置 `claudeCode.stabilizePromptCache: true`，可在转换路由上将系统指令末尾受支持的 Claude 提示移到最后一条用户消息。默认值为 `false`。仅在客户端允许这种角色变化时启用。代码围栏内的示例和不匹配的文本会保留，Anthropic 原生透传不变。没有元数据时，缓存键按稳定后的指令计算。该选项不会生成会话标识，也不保证上游缓存命中。