Four controls decide which CLI a coding session launches, and the one the console calls "Coding CLI" is read by nothing — switching to Codex kept burning the Claude session limit

[serge-ivo]

The owner's report

"hit the session limit again even after the user thought they had switched to Codex… there are two separate settings… changing only one was not enough."

There are four, not two, and the one the console labels "Coding CLI" — the one on the Settings tab, under the heading "Agent settings" — is read by no code at all.

Verified: the setting has zero readers

It is live on every Repo Coder. GET /v1/agents/agent_coder_repo/settings-schema, production, 2026-08-13:

{ "id": "engine", "label": "Coding CLI", "type": "select",
  "description": "Which CLI this agent drives on your machine.",
  "options": [ {"value":"claude","label":"Claude Code"},
               {"value":"codex","label":"Codex"},
               {"value":"grok","label":"Grok"} ],
  "default": "claude" }

It is rendered by store/console/src/tabs/SettingsTab.tsx:442-445 ("Agent settings"), stored on agent_instances.config.settings.engine, and:

$ grep -rn "settings.engine\|\[\"engine\"\]" --include="*.ts" workers/api/src | grep -v '\.test\.'
(no matches)
$ grep -rn "'engine'\|\"engine\"" --include="*.ts" --include="*.tsx" store/console/src \
    | grep -vi "engineId\|engineLabel\|engineRuntime\|codingEngine\|engineAuth\|engines"
store/console/src/pages/Usage.tsx:212   ← the ai_usage `kind`, unrelated

Nothing reads it. Its only effect is that agent-think.ts injects it into the chat prompt's ## Settings block, so the agent is told its engine is Codex while the runner spawns something else.

The four controls that DO decide, in the order they win

workers/api/src/routes/coding.ts:136-146:

	// One active session per repo — a second would share the repo's single working
	// directory and conflict … Reuse the live one.
	const existing = await getActiveSessionForRepo(c.env, instanceId, uid, repoId);
	if (existing) {
		const runnerConnected = (await startSessionOnRunner(c.env, instanceId, uid, existing, repo)).conn != null;
		return c.json({ session: existing, runnerConnected, reused: true }, 200);
	}
	const { command, clientType } = await resolveEngine(c.env, instanceId, uid, body.engineId ?? body.clientType ?? repo.defaultClient);

and lib/coding-engines.ts:318-320:

const eng = engines.find((e) => e.id === engineId) ?? engines.find((e) => e.id === defaultEngineId) ?? engines[0];

#	Where	Set from	Beats
1	coding_sessions.launch_command	fixed when the session was created	everything — the reuse branch returns before resolveEngine is ever called
2	coding_repos.default_client	createRepo, defaulting to "claude" (coding-store.ts:192)	3 and 4
3	agent_instances.config.defaultEngineId	console ⚙ CLI engines panel	4
4	agent_instances.config.settings.engine	console Settings → Agent settings → "Coding CLI"	nothing

So the visible, obvious, agent-named control is last and inert, and the control that actually decides is #1 — a value frozen on a session that the console's "start a session" button silently reuses. A user who changes any setting and clicks start gets {"reused": true} and the old engine, with no message saying so.

Current state, measured — the controls agree today, so this is latent

GET …/settings and GET …/coding/engines for all nine of this owner's Repo Coder instances, 2026-08-13:

AIPA coder    setting.engine=codex   defaultEngineId=codex   codex exec --sandbox danger-full-access
Heartfull     setting.engine=claude  defaultEngineId=claude   claude --dangerously-skip-permissions
Chess coder 2 setting.engine=claude  defaultEngineId=claude   claude --dangerously-skip-permissions
FIS coder / Chess coder / PAS Coder / FWS platform / FGS platform / FAS platform — all claude/claude

No divergence right now (he evidently fixed both by hand after the incident). The mechanism that produced the incident is untouched, and nothing keeps the four in sync or reports a disagreement.

This is the same defect the platform already fixed once

Migration 0102_coder_repo_drop_repo_setting.sql deleted the Repo Coder's repo setting for exactly this reason, and its header reads as if it were written about engine:

"Which repo does this agent work on" was written down in two places. … The reported bug was "I updated it, but it is still using the old one", and both halves were true. … Half a wire is worse than none: it makes the field look connected.

The repo setting had half a wire (attachSettingRepo, create-only). engine has none. It survived that cleanup, and 0092_coder_repo_engine_copy.sql — which touched this exact field — only corrected its description ("in tmux" → "on your machine") while leaving it inert.

What to do, cheapest first

1. Delete the engine field from the Repo Coder's settingsSchema, by migration, the way 0102 did for repo. One UPDATE agents. Stored values orphan harmlessly (they already do nothing) and the console stops rendering it. This alone removes the control that caused the reported loss.
2. Tell the user when a session was reused. coding.ts:139-142 already returns reused: true and the console ignores it. If the reused session's launch_command does not match what resolveEngine would have picked, say so: "Reusing the live Claude Code session on this repo. End it to start a Codex one." This is the half that actually bit him — even with one control, a live session outlives the change.
3. Then decide where "which CLI" lives — repo, or instance. Today coding_repos.default_client silently outranks config.defaultEngineId, so the ⚙ CLI engines default is itself only sometimes honoured. Making the repo settings sheet ([bug] A repo's folder cannot be changed — the console shows it as read-only text and the update API has no parameter for it, so a wrong path can only be deleted #410) the single home matches 0102's conclusion that a repo's facts live on the repo row; the alternative is dropping repo.defaultClient from the ?? chain. I would put it on the repo, because the engine is a property of the codebase (Codex for one repo, Claude for another) far more often than of the agent. Owner's call; either way it must be one place.

Alternatives considered and rejected

• Wire settings.engine through to resolveEngine. Rejected — that is the mirror image of 0102's reasoning. It makes a typed settings field mutate coding_repos/coding_sessions state, adds a fifth writer, and creates the sync that 0102 says is "a disagreement waiting to happen".
• Make the settings field authoritative and delete the ⚙ panel. Rejected: the panel edits {id,label,command} presets — the actual command line, flags included (codex exec --sandbox danger-full-access). A three-option select cannot express that, and coding-engines.ts:232-247 documents why the write-flag per engine matters.
• Auto-restart the session when the engine choice changes. Rejected: ending a live coding session out from under a running turn to honour a settings save is a destructive side effect of a config write. Tell the user; let them choose.

Acceptance criteria

• GET /v1/agents/agent_coder_repo/settings-schema no longer contains an engine field.
• Starting a session on a repo with a live session returns a message the console shows, naming the engine that is actually running and how to change it.
• A test asserts that no field id in any seeded settingsSchema is also a key that resolveEngine/resolveEngineEnv consults — the general form of this bug, and the one seed-drift.test.ts is already positioned to carry.

Regression risk

Removing a settingsSchema field is proven safe by 0102, with the same orphaning behaviour. The real risk is in step 3: repo.defaultClient defaults to "claude" on every repo created (coding-store.ts:192), so dropping it from the ?? chain would silently move every existing repo onto the instance default. If that path is taken, migrate default_client into defaultEngineId first, or scope the change to repos where the two disagree.

Verified from source and from production reads of the live schema, settings and engine presets. Not verified: that the historical Codex/Claude divergence was #4-vs-#3 rather than #1-vs-#3 — the settings have since been aligned by hand and neither carries an audit trail. Both paths are open and both are fixed by the steps above.

Related: #411 / #520 / migration 0102 (the same defect for repo), #92 (edited this field's description without noticing it was inert), #248 (which credential a session actually used).

[serge-ivo]

Fixed in 00fb83c — CI green, API + Host Workers deployed, migration 0126 applied to production D1.

The decision, and why

agent_instances.config.defaultEngineId — the console's ⚙ CLI engines panel — is authoritative. The other three follow it or are gone. I did not wire them together.

The issue leaned toward putting the choice on the repo. I went the other way, and the deciding argument is one the issue does not make: coding_repos.default_client is the wrong type to be the authority. It holds a CodingClientType, while resolveEngine matches engines.find(e => e.id === engineId) against preset ids. It only ever worked because the seeded preset ids happen to equal the client types — rename a preset and it misses silently and falls through. It also cannot express a preset at all: a preset is {id,label,command,auth} and the command is a real argv (codex exec --sandbox danger-full-access), and ENGINE_WRITE_FLAGS documents why the write flag per engine is load-bearing. The panel is the only control expressive enough, so it could not be the one that disappears.

Per control:

#	Control	Outcome
4	settings.engine	Deleted by migration 0126, byte-for-byte 0102's statement with a different id
2	coding_repos.default_client	Gone from the resolution chain, NewRepoInput, both create routes, CodingRepo and the diagnostics payload
3	config.defaultEngineId	Authoritative, and now the only stored control both doors resolve from
1	coding_sessions.launch_command	Still wins — correctly — but now says so

repo.defaultClient is what actually produced the incident. It never reached the console path (which always sends engineId), but it was the whole input on the agent-opened path — a hardcoded "claude" written once at create, settable by no UI and not accepted by the repo PUT route, outranking the control the owner had set. That is how start_work opened Claude under defaultEngineId = codex.

Rejected exactly as the issue proposes: wiring settings.engine into resolveEngine (0102's own reasoning — a fifth writer needing a sync), making the settings field authoritative and deleting the panel (a select cannot carry an argv), and auto-restarting a live session on a config save.

The reuse notice (step 2)

POST …/coding/sessions returns notice when the live session's launch_command differs from what resolveEngine would pick now, and the console renders it. It compares the command, not the client type: deriveClientType maps every non-Claude binary to codex, so comparing types would call a Grok session and a Codex session identical, and two codex presets differing only in --sandbox workspace-write vs danger-full-access differ in whether git pull can reach the network. A session with no recorded launch_command gets no notice — unknown is not "different", and a false mismatch would send someone to end a session running exactly what they wanted.

Placement, which is the part worth recording. My first attempt put it beside openError on the landing strip. That is dead markup: a reuse always returns a session, so openTerminal unmounts that strip in the same tick — and with the runner up the one-repo surface auto-opens and never renders it at all. Caught by reading the JSX, not by a test. It now renders as a banner in the session view, at both places one exists (solo and multi-repo).

The guard (step 3's acceptance criterion)

repo-path-writer.test.ts already resolves every seeded agent's final settingsSchema by walking all 126 migrations, including 0102's removal shape — so it, not seed-drift.test.ts, was the file already positioned to carry this. It now fails if any seeded field id names something engine resolution owns, with the near-miss names included because re-adding this field under a slightly different name is the obvious way back. A denylist, not a reader check, and the comment says so — "is it read" cannot be automated honestly. Verified non-vacuous: deleting 0126 makes it fail.

Verified

• pnpm typecheck, pnpm vitest run (8244 passed), biome, all seven script gates, pnpm docs:drift, and pnpm test:e2e (388 passed, chromium + webkit) — re-run in full after each of three rebases, the last against 1cb5099.
• New e2e specs assert the banner survives into the terminal and fits 320px and 390px in WebKit, and that an open which changes nothing shows none.
• CI, Deploy API Worker and Deploy Host Worker all green on 00fb83c.
• Production, after the deploy — GET /v1/agents/agent_coder_repo/settings-schema now returns exactly ["autonomy", "merge_policy"]. The engine field is gone, so it no longer reaches agent-think.ts's ## Settings block — which is the half that had the agent asserting Codex while running Claude.
• The deploy log shows 0126_coder_repo_drop_engine_setting.sql applied (✅, 2 commands).

Not verified

I did not exercise the reuse notice against a live session — that would mean opening a session on the owner's machine. It is covered by unit tests on the pure function and by e2e against a mocked response; the production check above is read-only.

Left open, deliberately

coding_repos.default_client remains an unread NOT NULL column, written as the literal "claude". SQLite column drops rewrite the table and coding_sessions/coding_timeline hang off coding_repos by foreign key, so that migration is not free and buys nothing while nothing reads it. Stored config.settings.engine values orphan on instances, exactly as 0102 orphaned repo — not copied into defaultEngineId, because adopting a value nothing ever consulted would silently change which CLI an instance launches.