A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers

[serge-ivo]

The gap

AIPA coder (a1d3522f…) runs Codex. Measured on production 2026-08-13, GET /v1/instances/a1d3522f…/coding/engines:

defaultEngineId = codex   command = "codex exec --sandbox danger-full-access"

Its whole all-time footprint in usage_summary is 20 calls, $0.000475 — the cloud-side Pilot decisions. The Codex process itself has produced zero ai_usage rows and zero usage.unmetered trace events. On the Usage page that agent's engine reads as costless, in the same way a tmux-driven Claude Code session read as costless before #348.

#348's own header states the rule this violates:

A zero you did not measure is a lie; an absence you did measure is data.

It applied that rule to the terminal driver and left the headless raw-engine case unrecorded — even though the classifier it shipped covers both.

Verified

The classifier knows. workers/api/src/lib/engine-metering.ts:100-121, classifyEngineMetering("headless", "codex"):

	if (STRUCTURED_ENGINES.has(name)) {
		return { metered: true, reason: "Claude Code reports each turn's tokens and cost, and that figure is recorded as measured." };
	}
	return {
		metered: false,
		reason: name
			? `${name} ends a turn with plain stdout and reports no token counts, so its spend cannot be measured.`
			: "This engine reports no token counts, so its spend cannot be measured.",
	};

with STRUCTURED_ENGINES = new Set(["claude", "claude-code"]) (:70), and the module docstring saying so outright: "Codex and Grok are spawned raw and their turns are stdout text, which is why they are unmetered under BOTH drivers rather than only under the terminal one."

Nothing calls it.

$ grep -rn "classifyEngineMetering" --include="*.ts" workers packages store | grep -v node_modules
workers/api/src/lib/engine-metering.ts:107:export function classifyEngineMetering(…)
workers/api/src/lib/engine-metering.test.ts:  (10 assertions, including `("headless","codex").metered === false`)

One definition, ten test assertions, zero production call sites. The function that describes this gap is dead code.

And the absence recorder is wired only to the terminal driver.

$ grep -rn "noteUnmeteredDrive" --include="*.ts" workers/api/src | grep -v '\.test\.'
lib/connectors/tmux.ts:100,129,162       driver: "terminal"
lib/connectors/terminal.ts:114,144,178   driver: "terminal"

Six call sites, all driver: "terminal". EngineDriver is declared as "headless" | "terminal" (engine-metering.ts:40) and "headless" is never passed by any caller.

So the runner-side path confirms it. packages/browser-runner/src/coding/headless.ts sets this.mode = config.clientType === "claude" ? "stream-json" : "raw" (:255); only the stream-json path parses a result event carrying tokens. A raw engine's turn produces stdout and nothing else, so takeUsage() returns [] and recordEngineUsage no-ops on !records?.length (usage.ts:191).

Why it composed into a bug

Two correct decisions:

1. [bug] Coding CLIs driven through the terminal connector are completely unmetered — a tmux run reads as $0, not as unknown #348 fixed the driver axis. Its rule — "metering is a property of the (driver, engine) PAIR, not of the engine" — is right, and it built the classifier over both axes.
2. noteUnmeteredDrive was wired where the drives were happening, in the two terminal connectors, which is where the reported problem was.

Composed: the classifier covers a 2x2, the recorder was wired to one row of it, and the remaining cell — headless + raw engine — is now the default for any subscriber who picks Codex or Grok from the engines panel. The panel offers all three as equals (coding-engines.ts:253, DEFAULT_ENGINES) with nothing saying that one of them is measurable and two are not.

The full metering picture, for the record

Path	Ledger row?	Draws a budget pool?
BYOK chat / apply / coding / copilot / overseer / translate / resume / pipeline ai_generate	yes — all funnel through user-ai.ts, recordUsage at :272 / :462	no
Platform Workers AI (embeddings, summaries, translation)	yes — recordPlatformUsage (vectors.ts:313, summaries.ts:141, instances-translation.ts:289)	no
Voice STT / TTS via the key-proxy	yes — recordVoiceUsage (routes/keys.ts:561,564)	no
Coding Engine, headless + Claude Code	yes — recordEngineUsage, 4 sites	no (the Pilot's own decisions do)
Coding Engine, headless + codex/grok/gemini	NO — and no absence recorded	no
Coding CLI via the tmux/kitty/iTerm2 connector	no — but the absence is recorded (#348)	no
Loop / delegated runs (agent-loop.ts:88)	yes	yes
Pilot (coding-session.ts:459)	yes	yes
JOB_APPLY	yes (job-apply.ts:155, kind:"apply")	no — #516

reserve() has exactly two callers; openBudget has six. So four paths open a pool that nothing ever draws against.

One latent hole worth naming, not currently costing anything: the key-proxy meters only OpenAI /audio/speech and /audio/transcriptions (routes/keys.ts:555). api.anthropic.com is on its allowlist (keys.ts:58), so a proxied /v1/messages would be entirely unmetered. Grepped: the only in-repo consumers are packages/sdk/src/voice/stt.ts:635 and tts.ts:333, both audio. Nothing exploits it today.

What to do, cheapest first

1. Call the classifier from the headless drain. In routes/coding.ts (capture, :237) and workflows/coding-session.ts (:402), when classifyEngineMetering("headless", session.clientType).metered === false, call noteUnmeteredDrive(env, ctx, { driver: "headless", target: session.engineLabel, activeCommand: session.clientType }). Everything needed is already in hand at both sites, the row id is already coarse enough not to flood the trace (unmeteredRowId keys on instance+target+day), and unmeteredUsageSummary — which the Usage page already renders — picks it up with no change.
2. Say it in the engines panel. classifyEngineMetering(...).reason is a finished sentence written for exactly this: "codex ends a turn with plain stdout and reports no token counts, so its spend cannot be measured." Show it under any preset whose engine is not Claude Code. This is the cheapest half and it prevents the choice being made blind.
3. Consider --json for Codex. Out of scope here; note only that if any raw engine grows a structured turn-end event, the fix is to add it to STRUCTURED_ENGINES and teach headless.ts to parse it — the classifier needs no change.

Alternatives considered and rejected

• Estimate raw-engine spend from stdout length. Rejected — this is precisely the "a guess wearing a measurement's clothes" that engine-metering.ts:20-27 refuses for pane text, and the same refusal applies to stdout.
• Warn on the Usage page only. Insufficient: the page already says the terminal connector is unmetered in prose, and the whole point of [bug] Coding CLIs driven through the terminal connector are completely unmetered — a tmux run reads as $0, not as unknown #348 was that prose does not distinguish "nothing ran" from "we could not see it". This needs a counted observation, which step 1 provides.
• Block or hide non-Claude engines. Rejected outright. Codex is a legitimate choice and DEFAULT_ENGINES ships it deliberately; the fix is to record the consequence, not to remove the option.

Acceptance criteria

• Driving a Codex session writes usage.unmetered trace events with driver: "headless", visible via GET /v1/instances/:id/trace and MCP agent_trace.
• unmeteredUsageSummary counts them, so the Usage page's "what this leaves out" figure covers headless raw engines.
• classifyEngineMetering has at least one production caller, asserted by the same style of source test that guards CHARGED_SQL.
• The engines panel shows the metering verdict per preset.
• A test drives the ("headless", "codex") cell end to end — today all four cells are unit-tested and only two are reachable.

Regression risk

noteUnmeteredDrive is best-effort and never throws (engine-metering.ts:230-247), so adding it to the capture drain cannot break a session. The one thing to watch is volume: the capture poll runs every 3s per open session, and the coarse unmeteredRowId (instance + target + day + aiCli) is what keeps that from becoming thousands of trace rows — do not make the id finer to include the session, or a day of Codex work becomes a day of identical trace rows. unmeteredUsageSummary's own comment already calls the resulting count "drives on distinct target-days", and that stays true.

Measured on production (engine presets, usage_summary, the instance's trace) and read from source.
Related: #348 (the terminal half of the same rule), #267 (engine metering), #449 (raw engines are one-shot), #516, #543, #551.

[serge-ivo]

Three line citations in the body are off by a few — corrected, no claim changes: headless.ts:255 → :257 (this.mode = config.clientType === "claude" ? "stream-json" : "raw";); STRUCTURED_ENGINES is at engine-metering.ts:73, not :70; EngineDriver is at :38, not :40. classifyEngineMetering:107, usage.ts:191, coding-engines.ts:253, keys.ts:58 and keys.ts:555 are as cited.

[serge-ivo]

Shipped in 1fca891 — CI green, Deploy API Worker succeeded 2026-08-13T00:13:00Z (the live API worker is this commit).

Why classifyEngineMetering had no caller

You asked me to establish this before wiring it. It is an oversight of coverage, not a call site that turned out to be hard — and the shape is worth stating because it explains how the gap survived two correct decisions.

Under terminal the verdict is a constant: a pane carries rendered characters, so nothing in it is measurable whatever is running. That is exactly why #348’s six connector sites could call noteUnmeteredDrive unconditionally and never needed to ask the classifier anything. Under headless the verdict varies by engine. So the classifier was built over a 2×2 and wired to the one row where consulting it was unnecessary. A table half-wired looks finished from either end.

What I did differently from the issue’s step 1, and why

Recorded at the DRIVE sites, not at the capture drain. A 3s poll is not a drive: recording one would claim spend on an idle session somebody merely has open — the same overclaim describeUnmetered refuses when it declines to read a quiet pane as "nothing was spent". It also resolves an internal contradiction in the issue: step 1 proposes target: session.engineLabel (which is per-session) while the regression note warns against a per-session id. Triggering on drives rather than polls makes both halves satisfiable at once, and it matches what the terminal half records (run / send_keys / send_message).

Doors covered: POST …/sessions/:id/message (console, MCP coding_session_message, the Co-pilot Loop), POST …/sessions/:id/run, the Overseer’s delegation, driveClaude, and the loop driver. That set is chosen so the Pilot’s own act loop needs no change — every Workflow that drives an engine is created by one of those doors, and the day-coarse row is written before the Pilot’s first act runs. workflows/coding-session.ts is being edited by a concurrent agent, so reaching the same coverage without touching it was worth the extra thought.

Not covered, and I would rather say so than let this look complete: the chat brain’s send_to_repo in lib/storage-tools.ts. That file is at 799 lines and the call crosses the 800-line ratchet (#302). Pinning a file at 803 to fit a four-line observability call defeats the ratchet for a poor trade, and splitting the file is separable work. A drive made only through that tool, on a raw engine, in a session no other door touched that day, still records nothing.

Also fixed, because opening the headless row made it reachable: two sentences in describeUnmetered said "the pane’s command could not be read" / "pane running X". There is no pane in a child process the platform spawned itself. Driver-aware now. Unreachable today (a session’s clientType is always one of the four the cloud derives, all AI CLIs), which is exactly why it would have gone unnoticed.

No cost is estimated from stdout length — the same guess-wearing-a-measurement’s-clothes the module refuses for pane text.

The panel

States the verdict per preset beside #449’s continuity line, muted, not warning: codex and grok ship deliberately in DEFAULT_ENGINES, so an unmeasurable engine is a legitimate choice, not a misconfiguration. Derived client-side because the user edits the command in a text box — a value keyed by preset id would be stale on the very edit whose consequence it exists to state. Same argument engine-posture.ts already makes; the API’s STRUCTURED_ENGINES, the runner’s mode = clientType === "claude" and isClaudeEngine are one fact, not three opinions. docs/coding-engines.md gained the matching section.

Verified

• The ("headless","codex") cell driven end to end through the route — all four cells were unit-tested from day one and two were unreachable, so the unit tests could never have failed.
• Claude Code writes NO absence row, so the "what this total leaves out" figure is not inflated beside a real measurement.
• Forty drives collapse to one row id.
• Source guards: the classifier has ≥1 production caller, and both rows of the 2×2 have a recorder, in different modules.
• Full bar green against the exact deploy tree (typecheck, 8,204 tests, biome, six guard scripts, docs:drift) plus 380 Playwright e2e in chromium + webkit, re-run after rebasing onto origin/main.

Production baseline (read-only — I drove nothing)

AIPA coder = a1d3522f-6b91-4cd9-bf7b-380e470192b7; active session csess_22d08431-… with clientType: codex, launchCommand: codex exec --sandbox danger-full-access — the issue’s premise reproduces exactly. Its trace holds 48 events, zero usage.unmetered. Account-wide usage_summary.unmetered = {drives: 4, aiCliDrives: 1, instances: 1} and all four belong to a different instance ("Heartfull (tmux)"), every one source: "terminal" — so the headless row has zero production rows anywhere, which is precisely the state this issue describes.

What the owner’s next Codex run should show

Exactly one new trace row, visible via GET /v1/instances/a1d3522f…/trace or MCP agent_trace:

• event: usage.unmetered, source: headless, level: info
• message: "Drove codex in codex:<sessionId> — its token spend is NOT measured and is missing from your usage total."
• context: {driver: "headless", target: "codex:csess_…", paneCommand: "codex", paneCommandReadable: true, aiCli: true, metered: false}
• trace_id = the run id via chat start_work, the session id via …/message or …/run, the task id via the Overseer

and usage_summary.unmetered moving to drives: 5, aiCliDrives: 2, instances: 2.

Three things that would be a false negative, not a failure: the row is day-coarse (a second drive the same day is not a second row); a refused start writes nothing, because no drive happened; and the dollars will not move — usage.unmetered is a trace row, not an ai_usage row, so this agent’s 20 calls / $0.000475 should be unchanged. The new trace row and the unmetered counters are the only correct signal.

Leaving open until that first Codex drive is observed, since the acceptance criterion is a live observation and I will not drive the owner’s agent to manufacture it. Everything else in the criteria list is delivered and tested.

[serge-ivo]

Wired, not deleted — and it was already wired before I got here. You asked me to establish which; that is the answer, and 1fca891 did it. Nothing further to build. Leaving open on the one acceptance criterion that is a live observation, which has still not occurred.

classifyEngineMetering now has five production callers

The issue's central tell — "a function with no callers" — is stale:

workers/api/src/routes/coding.ts:601          POST …/sessions/:id/message
workers/api/src/routes/coding.ts:702          POST …/sessions/:id/run
workers/api/src/routes/coding-brains.ts:73    driveClaude
workers/api/src/routes/coding-brains.ts:191   the Overseer's delegation
workers/api/src/lib/loop-drivers.ts:314       the loop driver / start_work

all through noteUnmeteredHeadlessDrive, which consults the classifier and returns early on a metered pair. Both rows of the 2×2 now have a recorder, in different modules.

The one gap the previous comment named does not exist. It said send_to_repo in lib/storage-tools.ts was uncovered and blocked by the 800-line ratchet. grep -rn "send_to_repo\|sendToRepo" workers packages store returns nothing in the current tree, and git cat-file -p 1fca891:workers/api/src/lib/storage-tools.ts | grep -c send_to_repo returns 0 — so it was not there at the commit that shipped #556 either. Whatever that caveat was about, it is not a hole you have today; the chat brain's drive path is loop-drivers.ts:314, which is covered. (storage-tools.ts is 798 lines, under the ratchet, and needs nothing.)

Why the acceptance criterion has not fired — measured

Account-wide usage_summary.unmetered is {drives: 6, aiCliDrives: 1, instances: 1}. I traced all six to a single instance, Heartfull (tmux), and every one is driver: "terminal". Zero headless rows exist anywhere.

AIPA coder (a1d3522f…) — the instance this issue was filed on — has 48 trace events, newest 2026-08-12 22:40:55, and zero usage.unmetered. Its two Codex sessions (csess_22d08431, csess_43be1f0e, both codex exec --sandbox danger-full-access) were ended after the deploy but never driven after it: the deploy of 1fca891 landed 2026-08-13 00:10:16 UTC, ~90 minutes after that instance's last event of any kind.

Every session on the only other active coding instance is clientType: "claude", and classifyEngineMetering("headless","claude") is metered: true — so the recorder correctly writes nothing for them.

So the path is not falsified, it is untested: no non-Claude engine has been driven since the deploy. One POST …/sessions/:id/message or …/run against a codex/grok/gemini session is all it takes.

What to look for when you next drive Codex

Exactly one new trace row (it is day-coarse — a second drive the same day is not a second row):

• event: usage.unmetered, source: headless, level: info
• context: {driver: "headless", target: "codex:csess_…", aiCli: true, metered: false}

and usage_summary.unmetered moving to drives: 7, aiCliDrives: 2, instances: 2. The dollars will not move — usage.unmetered is a trace row, not an ai_usage row — so an unchanged cost figure beside a new absence row is the correct outcome, not a failure.

I did not drive your agent to manufacture this, and I would rather leave the ticket open than close it on an untested path.

(Read-only production check; no code change in this pass. lib/usage.ts is #551's lane and I did not touch it.)