|
1 | | -# Codex and Claude Desktop toggles |
| 1 | +# Client integration switches: Codex, Claude Desktop, and the memory they need |
2 | 2 |
|
3 | | -Split out of `260803_integrations_toggle_all` after its fourth audit |
4 | | -(`../260803_integrations_toggle_all/007_audit_synthesis_r4.md`). That unit keeps |
5 | | -Claude Code and Grok, whose toggles need no durable operation state. These two |
6 | | -need one, and it is the shared dependency four audit rounds kept circling. |
| 3 | +Split out of `260803_integrations_toggle_all` after its fourth audit. That unit |
| 4 | +shipped Claude Code and Grok. This one was scoped around a durable |
| 5 | +operation-state engine — and a research cycle against the real code says that |
| 6 | +engine solves the wrong problem. |
7 | 7 |
|
8 | | -## Why these two are together and separate |
| 8 | +> **Re-planned 260803 after four research passes.** The rollback engine |
| 9 | +> (`010_operation_state.md`, never written) is **dropped**. Evidence: |
| 10 | +> `001`-`004`. The replacement is smaller, and it also fixes a defect in the |
| 11 | +> toggle we shipped hours ago. |
9 | 12 |
|
10 | | -| | Codex | Claude Desktop | |
11 | | -|---|---|---| |
12 | | -| Artifacts | `config.toml`, `opencodex.config.toml`, model catalog, resume history (SQLite) | `<id>.json`, `.bak`, `_meta.json`, four fields in our config | |
13 | | -| Owner | us, mostly | **Claude Desktop** — we edit another app's registry | |
14 | | -| Prior state recoverable? | from its own journal, when hashes still match | only from `_meta.json` bytes; `appliedId` was never recorded | |
15 | | -| Removal code exists? | yes, `restoreNativeCodex` | **no** | |
| 13 | +## The requirement in the owner's words |
16 | 14 |
|
17 | | -Neither can be undone by re-running its enable path, which is what makes Claude |
18 | | -Code and Grok cheap. Codex's enable is not the inverse of its disable — the |
19 | | -journal fallback means a disable may strip fragments rather than restore bytes, |
20 | | -and a later enable writes today's catalog, not yesterday's arrangement. Desktop |
21 | | -cannot re-derive which profile the user had selected at all. |
| 15 | +> "스위치를 꺼도 프록시는 살아있어야 돼. 코덱스 말고 다른 것만 켜고 싶을 수도 있잖아." |
22 | 16 |
|
23 | | -So both need an operation record that outlives the request, and that record is |
24 | | -the first phase. |
| 17 | +Turning a client off must leave the proxy running and serving every other |
| 18 | +client. That is two obligations: the mutation must not stop the proxy, and the |
| 19 | +OFF must survive a restart. |
| 20 | + |
| 21 | +## What the research changed |
| 22 | + |
| 23 | +| Prior claim | What the code says | |
| 24 | +|---|---| |
| 25 | +| Codex needs a durable operation-state engine | `ocx restore` already restores native Codex **without stopping the proxy** (`src/cli/help.ts:18`), and `ocx restore back` is the enable direction. Both exist. (`001`) | |
| 26 | +| Desktop removal is impossible to do safely | Anthropic documents that a selected config without a valid `inferenceProvider` launches **standard mode**. We aim at that instead of guessing. (`002`) | |
| 27 | +| The missing piece is crash recovery | The missing piece is **desired state**. Only Claude Code has one; Grok's shipped toggle is silently re-enabled by the next `ocx start`. (`003`) | |
| 28 | + |
| 29 | +The fourth research doc (`004`) is an unrelated live defect found while looking: |
| 30 | +one out-of-enum modality value makes a client reject its entire config. It joins |
| 31 | +this unit as an independent work-phase (LOOP-UNIT-CHAIN-01). |
25 | 32 |
|
26 | 33 | ## Read first |
27 | 34 |
|
28 | | -From the parent unit, all still authoritative: |
| 35 | +In this unit, all four written this cycle: |
| 36 | + |
| 37 | +- `001_native_restore_thesis.md` — Codex restore, its asymmetries, the history lock |
| 38 | +- `002_desktop_standard_mode.md` — the official standard-mode contract, and why `default` is not the restore verb |
| 39 | +- `003_durable_desired_state.md` — desired vs observed, the Grok regression, the schema |
| 40 | +- `004_export_modality_poisoning.md` — the gjc/Pi enum defect |
29 | 41 |
|
30 | | -- `001_removal_path_inventory.md` — what each client's disable actually costs |
31 | | -- `003`, `004`, `005`, `007` — the four audit syntheses; `007` is why this unit |
32 | | - exists |
33 | | -- `002_consequence_dialog_ux.md` — dialog direction; the Codex and Desktop copy |
34 | | - lives there |
| 42 | +From the parent unit, still authoritative: `001_removal_path_inventory.md` |
| 43 | +(what each disable costs) and `002_consequence_dialog_ux.md` (dialog direction). |
| 44 | +Its `007_audit_synthesis_r4.md` is the reason this unit exists, but its central |
| 45 | +conclusion is now **superseded** by `001`-`003` here. |
35 | 46 |
|
36 | 47 | ## Phases |
37 | 48 |
|
38 | | -| Phase | Doc | Deliverable | |
39 | | -|---|---|---| |
40 | | -| WP1 | `010_operation_state.md` | The durable operation record: a versioned discriminated journal entry, prepare/commit, restart reconciliation, a field-scoped config writer | |
41 | | -| WP2 | `020_codex_toggle.md` | Codex disable/enable on top of it | |
42 | | -| WP3 | `030_desktop_toggle.md` | Desktop removal + rollback, `appliedProfileId` schema work | |
43 | | - |
44 | | -WP2 and WP3 are **parallel siblings**, not a sequence: Desktop does not depend on |
45 | | -Codex (audit r4 #11). Both depend on WP1 and nothing else. |
46 | | - |
47 | | -## What WP1 must deliver |
48 | | - |
49 | | -Named by audit round 4, findings #1, #2, #5, #3: |
50 | | - |
51 | | -1. **A versioned discriminated journal entry.** Today's `JournalEntry` |
52 | | - (`src/integrations/journal.ts:34-51`) is file-shaped: one `configPath`, one |
53 | | - `SnapshotRef`, one `resultFingerprint`. A routing description and three |
54 | | - library members do not fit it. Needs `file-v1 | native-state-v1 | |
55 | | - desktop-hybrid-v1` with validated serialized state, per-member fingerprints, |
56 | | - and retention behavior. |
57 | | -2. **Prepare/commit with restart reconciliation.** A crash between the mutation |
58 | | - and the append leaves no undo state at all. Idempotent re-apply does not fix |
59 | | - this — it helps once a state exists, and none was recorded. The prepared |
60 | | - record must be durable before the mutation and resolved after. |
61 | | -3. **A field-scoped config writer.** `saveConfigPreservingClaudeCode` persists |
62 | | - the whole live object and its own docstring says a `providers` hand edit is |
63 | | - clobbered (`src/config.ts:2132-2135`); worse, when disk and caller both |
64 | | - changed `claudeCode`, the caller's stale subtree wins, so one toggle field can |
65 | | - clobber a concurrent Desktop-profile edit. Desktop's four fields need a write |
66 | | - that reloads from disk and touches only named paths. |
67 | | - |
68 | | -## Carried-forward findings |
69 | | - |
70 | | -Everything in `005` §Carried forward plus round 4's, in particular: Codex's |
71 | | -pre-state must capture the effective injection mode and history policy, not just |
72 | | -a routing kind (r4 #4); `injectCodexConfig` takes a concrete `catalogPath`, so |
73 | | -"selector" needs a resolver (r4 #4); Desktop's ordering is dangling-pointer-safe |
74 | | -but not transactionally crash-safe and must say so (r4 #6); auto-apply must be |
75 | | -suppressed while an operation is prepared (r4 #6). |
76 | | - |
77 | | -## Status |
78 | | - |
79 | | -Not started. `020` and `030` carry their pre-split content and are **stale** |
80 | | -against the operation-state design WP1 has not written yet; their next P |
81 | | -re-verifies them against it before any build. |
| 49 | +**Re-sliced after audit round 2** (`006_audit_synthesis_r2.md`). The first map |
| 50 | +sliced along a schema — one ten-key `clientIntegrations` map — which forced every |
| 51 | +phase to touch every client's write path. Two audit rounds widened rather than |
| 52 | +narrowed. This map slices along **ownership boundaries**: one client family per |
| 53 | +phase, each independently auditable. |
| 54 | + |
| 55 | +| Phase | Doc | Deliverable | Audit state | |
| 56 | +|---|---|---|---| |
| 57 | +| WP2 | `010_modality_boundary.md` | The client-dialect modality filter | **clean through two rounds** | |
| 58 | +| WP3 | `020_api_keys_row.md` | API keys out of the card grid into their own row | never blocking | |
| 59 | +| WP4 | `030_desired_state.md` → re-scoped | Desired state for **Codex only**, plus its gates, single-flight, ownership preflight and CLI semantics | re-scope pending | |
| 60 | +| WP5 | `040_codex_toggle.md` | The Codex switch on WP4's flag | rewrite pending | |
| 61 | +| WP6 | *(new doc)* | Grok's desired state, reusing the shape WP4 proved | not started | |
| 62 | +| WP7 | `050_desktop_toggle.md` | The Desktop switch via documented standard mode | deferred behind WP5 | |
| 63 | + |
| 64 | +The two pending docs were renamed so the decade order matches the phase order: |
| 65 | +reading the unit lexicographically now gives the build order, which is the whole |
| 66 | +point of the numbering convention. |
| 67 | + |
| 68 | +WP1 was the research cycle plus this roadmap, twice audited. |
| 69 | + |
| 70 | +WP2 and WP3 depend on nothing here and on each other not at all — they ship |
| 71 | +first, alone, because each changes one thing at one boundary. That property is |
| 72 | +the only thing that survived both audit rounds intact. |
| 73 | + |
| 74 | +Three deliberate exclusions, each an accepted audit finding rather than a |
| 75 | +convenience: |
| 76 | + |
| 77 | +- **Claude Code's ingress gates are not touched at all.** Round 1 #1 established |
| 78 | + that `claudeCode.enabled` is the documented kill switch for `/v1/messages`; |
| 79 | + the honest conclusion is not to route it through a new helper in this unit. |
| 80 | +- **The six file clients get no desired-state flag here.** Round 2 #4 (existing |
| 81 | + explicit OFF choices are not migrated) and #5 (a mutating GET) both belong to a |
| 82 | + phase that does not exist yet, and inventing it under audit pressure is what |
| 83 | + produced round 2's new findings. |
| 84 | +- **Desktop is behind Codex, not beside it.** Round 2 #3 found no coherent rule |
| 85 | + when a foreign profile is selected. The goal explicitly permits an evidenced |
| 86 | + deferral; this is one. |
| 87 | + |
| 88 | +## Scope boundary |
| 89 | + |
| 90 | +IN: `src/clients/config-export.ts`, `src/types.ts`, `src/config.ts`, |
| 91 | +`src/codex/sync.ts`, `src/grok/sync.ts`, `src/cli/index.ts`, |
| 92 | +`src/cli/opencode.ts`, `src/claude/desktop-3p.ts`, |
| 93 | +`src/server/management/native-integration-routes.ts`, |
| 94 | +`src/server/management/agent-settings-routes.ts`, `src/server/management-api.ts`, |
| 95 | +`gui/src/pages/integrations/*`, `gui/src/styles-integrations.css`, |
| 96 | +`gui/src/i18n/*`, `tests/`, `gui/tests/`. |
| 97 | + |
| 98 | +OUT: releases, publishing, deploys, tags; starring the repository; rewriting the |
| 99 | +six-client file machinery in `src/integrations/`; `docs-site` restructuring; |
| 100 | +recording the previous `appliedId` (deferred, `002` §Residual). |
| 101 | + |
| 102 | +## Criteria |
| 103 | + |
| 104 | +- C1 — gjc loads our emitted config with no schema error, proven from the real |
| 105 | + file; Pi's identical exposure is closed in the same change. |
| 106 | +- C2 — Codex stays disabled across a proxy restart, an `ocx ensure`, and a |
| 107 | + `POST /api/sync`. |
| 108 | +- C3 — an upgrading user with no `clientIntegrations` key sees no behavior change. |
| 109 | +- C4 — disabling Codex never stops the proxy and never closes `/v1/responses`. |
| 110 | +- C5 — Codex toggles both directions from the overview with the proxy running. |
| 111 | +- C6 — a Codex disable blocked by the held history DB is an explained refusal |
| 112 | + naming the cause, never a raw 500 and never a false green. |
| 113 | +- C7 — startup convergence never touches state owned by a service running from a |
| 114 | + different `OPENCODEX_HOME` (round 2 #2, blocking). |
| 115 | +- C8 — API keys render as a row above the grid, observed rendered. |
| 116 | +- C9 — typecheck, full test, gui lint, gui test, privacy scan all green. |
| 117 | +- C10 — Desktop ships with a proven restore path OR is deferred with recorded |
| 118 | + evidence. Both outcomes close this criterion. |
| 119 | + |
| 120 | +## Risk register |
| 121 | + |
| 122 | +| Risk | Mitigation | |
| 123 | +|---|---| |
| 124 | +| A gate silently unplugs a working client on upgrade | Absent key means ON, everywhere, with a test for the absent-config case (`003`) | |
| 125 | +| Gating a safety path | Explicit do-not-gate list: journal repair, ownership checks, owned teardown, shared transports (`003`) | |
| 126 | +| Desktop pointed at a missing file | Never delete `appliedId`, never leave it dangling, never pick an entry by the name `Default` — this machine's `Default` is already dangling (`002`) | |
| 127 | +| The modality fix erases valid internal metadata | Filter at the client-dialect boundary only; management and CLI keep carrying `audio` verbatim (`004`) | |
| 128 | +| A green suite hides the real failure | 91 tests pass today beside a config gjc refuses to load. Every criterion names a live artifact, not a unit test | |
| 129 | +| A repair introduces a worse defect than the one it fixes | Round 2 produced exactly this. One client family per phase, re-audited before the next starts — never a cross-client rewrite under audit pressure | |
| 130 | +| Convergence tears down a foreign home's state | Every native remover runs `assertNativeTeardownOwned` before removal, and reconciliation runs only after service-ownership resolution (round 2 #2) | |
0 commit comments