Skip to content

Commit 43a1fdc

Browse files
authored
Merge pull request #1106 from lidge-jun/codex/260806-wp13-toggles
Merging the WP13/WP14 toggle resume after an independent completeness audit (4 rounds) closed three real defects: the self-cancelling /apply enable, in-process snapshot incoherence, and an unconsumed partial-success envelope. Issue #1048 stays open for the deferred disposable-host census rows.
2 parents 3c24629 + 38d3834 commit 43a1fdc

62 files changed

Lines changed: 3404 additions & 329 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# 260806 — WP13/WP14 resume: Codex CLI toggle truth, Claude Desktop toggle, composed acceptance
2+
3+
PR-ONLY unit: the branch `codex/260806-wp13-toggles` (from `origin/dev` @ `b3a1d90a8`)
4+
is pushed and opened as PR(s) against `dev`, but **never merged** in this session —
5+
that boundary is a user instruction, not a preference.
6+
7+
This unit resumes the paused tail of two prior campaigns:
8+
9+
- `devlog/_fin/260804_codex_write_substrate/` — WP13 (composed acceptance, issue
10+
[#1048](https://github.com/lidge-jun/opencodex/issues/1048)) was deferred; WP14's PR
11+
deliverable landed as PR #998, so "WP14" here means the *new* toggle work opened as a PR.
12+
- `devlog/_plan/260803_codex_desktop_toggle/` — 040 (Codex toggle CLI truth) and 050
13+
(Claude Desktop toggle) were written but never implemented.
14+
15+
## Stale-check verdicts (explorer audit, 2026-08-06, tree @ b3a1d90a8)
16+
17+
All three pre-written docs are **NEEDS AMENDMENT**, none is ALREADY LANDED, none is
18+
implementable as written. What changed under them:
19+
20+
### Landed since the docs were written
21+
22+
- Durable `clientIntegrations` desired state exists for `codex`/`grok` only
23+
(`src/types.ts:551-556`, `src/config.ts:986-1012`), with owner
24+
`setIntegrationEnabled` (`src/codex/desired-state.ts:90`) and field-scoped
25+
`mutatePersistedConfig` (`src/config.ts:2197`).
26+
- Dashboard `PUT /api/native-integrations/codex` persists intent before artifact work
27+
(`src/server/management/native-integration-routes.ts:58-87,199-293`); startup honors
28+
Codex OFF via `syncCodexOnStartIfEnabled` (`src/cli/index.ts:320`,
29+
`src/codex/desired-state.ts:160-176`). Tests: `tests/native-codex-toggle.test.ts:106-156`,
30+
`tests/codex-desired-state.test.ts:167-223`.
31+
- Production injection runs under `withCodexWriteLock` (`src/codex/inject.ts:871-956`);
32+
the typed lock model exists (`src/codex/codex-write-lock.ts:67-125`) with a real
33+
two-process contention test (`tests/codex-inject-write-lock.test.ts:56-127`).
34+
- c24 (Grok OFF survives restart) is **landed at unit level**: persist-before-strip
35+
(`native-integration-routes.ts:342-374`), startup predicate `shouldSyncGrokOnStart`
36+
(`src/cli/index.ts:350-354`, `desired-state.ts:58-76,195-197`), covered by
37+
`tests/codex-desired-state.test.ts:233-243`. No full-process E2E; the composed
38+
acceptance phase may add it, but c24 is not a standalone work-phase.
39+
40+
### Still missing (the actual work)
41+
42+
1. **CLI restore/eject do not persist desired state.** `ocx restore`/`eject`
43+
(dispatch `src/cli/index.ts:774-819`) call `restoreNativeCodexAsync` without writing
44+
`clientIntegrations.codex=false`; `restore back`/`eject back` do not persist ON.
45+
Startup would resurrect routing the CLI just removed (040's core defect, alive).
46+
2. **No artifact-level restore truth.** `restoreNativeCodexAsync`
47+
(`src/codex/inject.ts:1193-1217`) reports `inline.success` even when the history
48+
worker fails; no per-artifact result envelope exists.
49+
3. **`syncModelsToCodex` and `ocx ensure` are ungated** (`src/codex/sync.ts:49-129`,
50+
`src/cli/index.ts:379-424`): they bypass the desired-state gate.
51+
4. **Claude Desktop has no toggle at all**: no `claude-desktop` key in
52+
`clientIntegrations`, no native-toggle route (union is claude|grok|codex,
53+
`native-integration-routes.ts:31`), auto-apply calls the writer directly ignoring
54+
desired state (`agent-settings-routes.ts:131-150`), status does not classify
55+
standard/gateway/foreign/not_installed (`agent-settings-routes.ts:767-815`), and no
56+
`removeDesktop3pConfig`/read-only inspector exists. Audit correction: the current
57+
status GET reads via `existsSync`/`readFileSync` and never calls the writer, so
58+
reads are non-mutating **today**; the risk 050 guards against is a *future* OFF or
59+
status path routing through `writeDesktop3pConfig`, whose eager `mkdirSync`
60+
(`src/claude/desktop-3p.ts:331-345`) would manufacture a library. 020 adds the
61+
dedicated read-only inspector rather than fixing an active violation.
62+
5. **No composed acceptance suite.** WP13's P01-P36 doc cites pre-substrate line
63+
numbers and pre-substrate RED claims (lock absence, no production caller) that are
64+
no longer true. The surviving target: compose real entry points — CLI
65+
restore/eject/ensure/sync, management toggle routes, startup gate — against a temp
66+
home, including refusal, foreign-home, and race paths.
67+
68+
### External evidence (Luna swarm, 3 lanes, all sources opened)
69+
70+
- Anthropic's official configuration reference (claude.com/docs/third-party/
71+
claude-desktop/configuration, accessed 2026-08-06) now documents the configLibrary
72+
(`~/Library/Application Support/Claude-3p/configLibrary/`, `_meta.json` + `<id>.json`),
73+
gateway fields `inferenceGatewayBaseUrl`/`ApiKey`/`AuthScheme` (bearer|x-api-key),
74+
`inferenceModels` (string or object entries; first entry is default),
75+
`modelDiscoveryEnabled`, and `supports1m`/`prefer1m`. The schema-drift risk recorded
76+
in memory (private fields) is RESOLVED: the fields 050 relies on are documented.
77+
- No official spec for behavior when the selected `<id>.json` is missing — community
78+
evidence shows "configuration needs attention" symptoms only (UNVERIFIED). 050's rule
79+
stands: never leave `appliedId` pointing at a missing file; select the standard `{}`
80+
profile before removing ours.
81+
- No native 1P-restore control is documented; community tools restore standard mode by
82+
selecting an official/empty profile then removing the 3P one — matching 050's pivot.
83+
- Codex CLI reads config.toml at session start (restart-scoped); `model_provider`
84+
selects from `model_providers`; no official restore-after-proxy runbook exists, so
85+
our restore semantics remain artifact-based, not documented-contract-based.
86+
87+
## Phase map (one decade doc per PABCD cycle)
88+
89+
- **010 (WP-B)** Codex toggle completion, consuming existing `clientIntegrations`:
90+
CLI restore/eject persist OFF, restore back/eject back persist ON, artifact-level
91+
restore result (history failure classified, never silent), and desired-state gating
92+
for **every** direct `syncModelsToCodex` caller with 040's discriminated skip
93+
semantics (`040_codex_toggle.md:222-235`) and fresh checks at irreversible
94+
boundaries (`:600-618`): `ocx ensure` (`src/cli/index.ts:379-424`), `ocx sync`
95+
(`:856-871`), restore/eject dispatch (`:774-819`), `src/cli/models.ts:102-107`,
96+
`src/cli/provider.ts:232-237`,
97+
`src/server/management/config-routes.ts:261-268`, and the toggle enable path
98+
itself (`src/server/management/native-integration-routes.ts:262`), which today
99+
interprets only `applied.ok` and needs the same discriminated-skip handling.
100+
Source doc:
101+
`260803_codex_desktop_toggle/040_codex_toggle.md` with the line-map above; drop its
102+
four-client-coordinator premise — extend the landed two-key schema instead.
103+
- **020 (WP-C)** Claude Desktop toggle per 050's amended contract: add
104+
`claude-desktop` to `clientIntegrations` and the native route union; a dedicated
105+
read-only inspector for status classification (absent library = `not_installed`;
106+
reads never write); OFF = write+select `{}` standard profile, then remove the
107+
opencodex profile and its credential-bearing backup; OFF with no owned state =
108+
successful no-op; GUI switch. Also gate the Desktop auto-apply path with 050's
109+
before/after-await desired-state guards (`050_desktop_toggle.md:747-783`,
110+
`agent-settings-routes.ts:131-150`) so a concurrent OFF cannot lose to an in-flight
111+
apply.
112+
- **030 (WP-D)** Composed acceptance, **reduced workstation-only scope**: one suite
113+
through real entry points against temp homes — CLI process invocations, management
114+
routes, startup gate — covering refusal/foreign-home/race/restore truth, including
115+
the missing Grok E2E (disable → fresh start path → fence stays absent). This is a
116+
deliberate subset of issue #1048's 36-entry two-execution-class program: the
117+
disposable-host service-lifecycle class (`050_composed_acceptance.md:24-35,55-99,
118+
108-177,568-580`) needs `ocx service` on a throwaway host, which this session's
119+
safety boundary forbids. **#1048 therefore stays OPEN** after 030; the PR references
120+
it without a closing keyword and states which entries remain.
121+
- **WP-E** Push branch, open template-complete PR(s) against dev referencing #1048,
122+
PR CI green. **No merge, no promotion.** dev/preview/main tips proven unchanged.
123+
124+
Verification per phase: `bun run typecheck`, `bun run test`, `bun run lint:gui` (gui
125+
touched phases), `bun run privacy:scan`, temp-home live proof (`mktemp -d`; never the
126+
real `~/.codex`/`~/.opencodex`; never `ocx start/stop/service` — launchd owns the live
127+
proxy on :10100). Every new mechanism gets a broken-change check.
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# 010 — Codex toggle: design amendments over 040
2+
3+
`040_codex_toggle.md` stays the diff-level source for messages, exit codes, the
4+
seven-caller skip table, and the `CodexHistoryFailureReason` discriminator
5+
(current anchor `src/codex/history-provider.ts:167-175`). Two of its structural
6+
premises are replaced here; where this document and 040 disagree, this document
7+
wins.
8+
9+
## Amendment 1 — no four-client coordinator; the write lock is the serializer
10+
11+
040 imports `runClientIntegrationFlight`, `requirePersistedClientIntent`, and
12+
`mutateClientIntegrationEnabled` from a WP3 shared contract that was never built
13+
(`040_codex_toggle.md:33-38,431-454,578-618`), and `000_plan.md` r3 drops that
14+
premise. What actually exists:
15+
16+
- `setIntegrationEnabled` persists intent and explicitly does not linearize
17+
(`src/codex/desired-state.ts:14-19,90`).
18+
- The management route has a route-local single flight
19+
(`native-integration-routes.ts:199-224`) that serializes toggles *within* the
20+
server process only.
21+
- `withCodexWriteLock` serializes Codex artifact writes *across* processes
22+
(`src/codex/codex-write-lock.ts:67-125`; production caller `inject.ts:871-956`).
23+
24+
Replacement design, Codex-only:
25+
26+
1. Intent writes stay `setIntegrationEnabled` — one owner, no new mutation API.
27+
2. The race 040 worried about (CLI OFF vs route ON, two processes) is closed by
28+
**revalidation under each artifact's own serialization boundary**, not by a
29+
cross-surface flight and not by one global lock. The three artifact families
30+
already have distinct serializers, and the Codex lock is *released* before
31+
the history worker launches (`inject.ts:951-966`), so "inside
32+
withCodexWriteLock" cannot cover history. Concretely:
33+
- config/profile writes re-read persisted desired state inside their
34+
`withCodexWriteLock` transaction (`codex-write-lock.ts:315-345` — the
35+
callback is synchronous, and the desired-state read is a synchronous file
36+
read, so it fits);
37+
- the history worker re-reads desired state inside
38+
`withHistoryWriteSerialization` (`history-worker.ts:119-131`), returning
39+
the existing `blocked`-style envelope with a new reason
40+
`"desired_disabled"`/`"desired_enabled"` instead of mutating;
41+
- catalog restore re-reads inside `withCatalogWriteSerialization`
42+
(`inject.ts:1241-1246`).
43+
A lost race becomes the discriminated skip (`status:"skipped"`,
44+
`skippedReason:"desired_disabled"` or `"desired_enabled"` for the restore
45+
direction). Each lock provides mutual exclusion for its artifact; the
46+
re-read inside it provides the freshness 040's
47+
`requirePersistedClientIntent` wanted (`040:600-618`). The small window
48+
where different artifacts observe different intent is acceptable: each
49+
artifact converges to the latest persisted intent, and the startup gate
50+
re-converges the remainder on the next start.
51+
3. The route keeps its local flight for HTTP idempotency; the CLI needs no
52+
flight because the lock + revalidation is the correctness boundary.
53+
54+
## Amendment 2 — the OFF path stays on the async worker boundary
55+
56+
040's CLI diff wraps synchronous `restoreNativeCodex()` with a `beforeWrite`
57+
hook (`040:184-205`). The CLI has since moved to `restoreNativeCodexAsync()`
58+
with history in a Worker (`inject.ts:1193-1218`); reverting to the inline path
59+
would regress the event-loop isolation the substrate campaign built. Instead:
60+
61+
- `restoreNativeCodexAsync` gains the artifact-level result 040 demands
62+
(`040:294-329`): a per-artifact envelope `{ config, catalog, history }` —
63+
catalog is a first-class member because restore performs it independently
64+
(`inject.ts:1241-1246`) and a `completed`-vs-not outcome exists today that
65+
the summary silently flattens. Profile restoration is reported inside the
66+
`config` member (it rides the same journal transaction). `history` carries
67+
`CodexHistoryFailureReason` (`"busy" | "permission"`) instead of being folded
68+
into `inline.success` (defect at `inject.ts:1193-1217`). Aggregate `success`
69+
is false if ANY member failed.
70+
- Persist-OFF ordering for `ocx restore`/`eject`: `setIntegrationEnabled(false)`
71+
FIRST (so a crash mid-restore leaves intent durable and startup will not
72+
resurrect routing), then the async restore; the history job revalidates
73+
desired state under the lock per Amendment 1 before mutating. `restore back`/
74+
`eject back` persist ON first, then sync — and a sync skip caused by a
75+
concurrent OFF prints 040's competing-OFF error with exit 2.
76+
- `success` for the command means: config (incl. profile) AND catalog restored
77+
AND history either restored or classified (`busy` → retry advice, exit 1;
78+
`permission` → ACL advice, exit 1). No path reports success with an
79+
unclassified hole in any artifact.
80+
81+
## Test impact (from the audit, folded in)
82+
83+
- `tests/codex-sync-api.test.ts:73-81` — expects the new `status:"applied"`.
84+
- `tests/cli-restore-back.test.ts:11-35` — drop source-string assertions,
85+
assert behavior through a temp-home process run.
86+
- `tests/native-codex-toggle.test.ts:106-156` — new envelopes and seams.
87+
- `tests/codex-desired-state.test.ts`, `tests/codex-inject-write-lock.test.ts`
88+
— extend for revalidation-under-lock; not intrinsically broken.
89+
90+
## Commit order (typecheck green at every commit)
91+
92+
1. `CodexHistoryFailureReason` + artifact envelope in history-provider/inject
93+
(additive, no callers change behavior yet).
94+
2. Discriminated `status` on `syncModelsToCodex` + all seven callers updated in
95+
the same commit (exit-code contract lands here).
96+
3. Revalidation-under-lock in inject/restore/history job.
97+
4. CLI restore/eject persist intent + new messages; process-level tests.
98+
5. Route/context wiring + GUI, if any surface text changes.

0 commit comments

Comments
 (0)