Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(costs): OpenCode is counted, and every harness the workspace offers must be

rubenluetke10-beepbc44974f0671
diff --git a/jarvis/costs/cli_usage_index.py b/jarvis/costs/cli_usage_index.py
index 60421ca4af..dac89dc643 100644
--- a/jarvis/costs/cli_usage_index.py
+++ b/jarvis/costs/cli_usage_index.py
@@ -130,7 +130,40 @@ follows the OpenAI convention — ``inputTokens`` INCLUDES ``cachedReadTokens``.
single key of ``usage.modelUsage``; cwd and session id come from the folder's
``summary.json``. 608 MB of these were read by nothing until 2026-08-25."""
-AGENTS: tuple[str, ...] = (AGENT_CLAUDE, AGENT_CODEX, AGENT_AGY, AGENT_GROK)
+AGENT_OPENCODE = "opencode-cli"
+"""OpenCode. Everything lives in one SQLite store,
+``~/.local/share/opencode/opencode.db`` (``$XDG_DATA_HOME/opencode`` when
+set): ``message.data`` is JSON with ``role``, ``modelID``, ``providerID``,
+``tokens.{input,output,reasoning,cache.{read,write}}`` and — because the
+user brings their own key — the ``cost`` OpenCode itself computed. Read
+with a timestamp cursor instead of a byte offset; the message id is the
+identity. Not a subscription: the recorded cost is the bill."""
+
+AGENTS: tuple[str, ...] = (AGENT_CLAUDE, AGENT_CODEX, AGENT_AGY, AGENT_GROK, AGENT_OPENCODE)
+
+#: Every coding harness the workspace registry can open, mapped to the
+#: index reader that counts its spend. A harness whose transcripts cannot be
+#: read from disk is listed in ``HARNESSES_WITHOUT_LOCAL_TRANSCRIPT`` with the
+#: reason. ``tests/unit/costs/test_harness_cost_parity.py`` fails the build
+#: when a registry entry is in neither — so a new harness is not shippable
+#: until its cost accounting exists (maintainer mandate, 2026-08-25).
+COST_READER_FOR_HARNESS: dict[str, str] = {
+ "claude": AGENT_CLAUDE,
+ "codex": AGENT_CODEX,
+ "kimi": AGENT_AGY,
+ "grok-build": AGENT_GROK,
+ "opencode": AGENT_OPENCODE,
+ # GLM runs the Claude Code binary against z.ai with the same config
+ # directory, so its sessions land in ~/.claude and are read — and priced —
+ # as Claude Code. Attributing them to z.ai needs a config dir of their own
+ # at spawn (docs/BUGS.md BUG-178, still open).
+ "glm": AGENT_CLAUDE,
+}
+HARNESSES_WITHOUT_LOCAL_TRANSCRIPT: dict[str, str] = {
+ "deepseek-harness": (
+ "dsh keeps no usage log on disk (checked ~/.dsh, ~/.deepseek, %LOCALAPPDATA%/dsh)"
+ ),
+}
#: Filename of the index, relative to the data dir.
DB_NAME = "cli_usage_index.db"
@@ -192,7 +225,11 @@ _ROLLOUT_ID = re.compile(r"([0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}
# the old rule would be wrong. An older index is dropped and rebuilt from the
# transcripts, which are the source of truth; nothing is lost but time.
# 2 — Codex: cached input subtracted from input; lineage-based dedup.
-_SCHEMA_VERSION = 2
+# 3 — cost_usd column (OpenCode records its own price). Additive: migrated
+# in place, no rebuild.
+_SCHEMA_VERSION = 3
+#: Versions whose rows are still right and only need columns added.
+_MIGRATE_IN_PLACE_FROM = 2
_SCHEMA = """
CREATE TABLE IF NOT EXISTS indexed_files (
@@ -219,6 +256,7 @@ CREATE TABLE IF NOT EXISTS cli_turns (
tokens_cached INTEGER NOT NULL DEFAULT 0,
cwd TEXT NOT NULL DEFAULT '',
label TEXT NOT NULL DEFAULT '',
+ cost_usd REAL NOT NULL DEFAULT 0,
PRIMARY KEY (agent, dedup_key)
);
CREATE INDEX IF NOT EXISTS idx_cli_turns_ts ON cli_turns (ts_ms);
@@ -231,8 +269,8 @@ CREATE INDEX IF NOT EXISTS idx_cli_turns_session ON cli_turns (agent, session_id
_INSERT_TURN = (
"INSERT INTO cli_turns "
"(agent, dedup_key, path, session_id, ts_ms, model, "
- " tokens_in, tokens_out, tokens_cached, cwd, label) "
- "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+ " tokens_in, tokens_out, tokens_cached, cwd, label, cost_usd) "
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
"ON CONFLICT(agent, dedup_key) DO UPDATE SET model=excluded.model "
"WHERE cli_turns.model = '' AND excluded.model <> ''"
)
@@ -271,6 +309,9 @@ class CliTurn:
tokens_cached: int
cwd: str
label: str
+ #: What the CLI itself priced the call at, when it does (OpenCode). 0.0
+ #: for the seat-driven CLIs, whose bill is derived from the rate tables.
+ cost_usd: float = 0.0
@dataclass(frozen=True, slots=True)
@@ -294,6 +335,7 @@ class CliRollup:
turns: int
cwd: str
label: str
+ cost_usd: float = 0.0
@dataclass(frozen=True, slots=True)
@@ -517,6 +559,19 @@ def _agy_roots(home: Path | None) -> list[Path]:
return [base / ".kimi", base / ".kimi-code"]
+def _opencode_roots(home: Path | None) -> list[Path]:
+ """``$XDG_DATA_HOME/opencode``, else ``~/.local/share/opencode`` — the
+ same path on every OS, which is how OpenCode itself resolves it."""
+ if home is not None:
+ return [home / ".local" / "share" / "opencode"]
+ roots: list[Path] = []
+ xdg = os.environ.get("XDG_DATA_HOME", "").strip()
+ if xdg:
+ roots.append(Path(xdg).expanduser() / "opencode")
+ roots.append(Path.home() / ".local" / "share" / "opencode")
+ return _dedup_paths(roots)
+
+
def _grok_roots(home: Path | None) -> list[Path]:
"""``GROK_HOME`` when set, the default, and every managed account."""
if home is not None:
@@ -544,6 +599,8 @@ _LAYOUTS: tuple[tuple[str, str], ...] = (
(AGENT_AGY, "sessions/*/*/agents/*/wire.jsonl"),
# Grok Build: one folder per session under a url-encoded cwd.
(AGENT_GROK, "sessions/*/*/updates.jsonl"),
+ # OpenCode: the one SQLite store.
+ (AGENT_OPENCODE, "opencode.db"),
)
@@ -554,6 +611,8 @@ def _roots_for(agent: str, home: Path | None) -> list[Path]:
return _codex_roots(home)
if agent == AGENT_GROK:
return _grok_roots(home)
+ if agent == AGENT_OPENCODE:
+ return _opencode_roots(home)
return _agy_roots(home)
@@ -677,6 +736,9 @@ def _decode(raw: bytes) -> dict[str, Any] | None:
# One row as the turn table takes it.
_Row = tuple[str, str, str, str, int, str, int, int, int, str, str]
+#: A row plus the price the CLI recorded. Readers without one emit ``_Row``
+#: and the writer pads it, so four readers stay untouched by the column.
+_PricedRow = tuple[str, str, str, str, int, str, int, int, int, str, str, float]
def _claude_row(
@@ -884,7 +946,8 @@ def _grok_context(path: Path) -> tuple[str, str, str, str]:
if summary.is_file():
parsed = json.loads(summary.read_text(encoding="utf-8", errors="replace"))
if isinstance(parsed, dict):
- info = parsed.get("info") if isinstance(parsed.get("info"), dict) else {}
+ raw_info = parsed.get("info")
+ info: dict[str, Any] = raw_info if isinstance(raw_info, dict) else {}
session_id = str(info.get("id") or session_id)
cwd = str(info.get("cwd") or "")
model = str(parsed.get("current_model_id") or "")
@@ -941,8 +1004,88 @@ class _FileScan:
failed: bool = False
+def _scan_opencode(cand: _Candidate, start: int) -> _FileScan:
+ """Read OpenCode's store. ``start`` is the newest ``time_created`` already
+ indexed (the "offset" column holds a timestamp for this agent), so a run
+ reads only what arrived since. A store that shrank (vacuum) re-reads from
+ zero and the message-id key keeps every turn counted once."""
+ rows: list[_PricedRow] = []
+ newest = start
+ failed = False
+ try:
+ uri = f"file:{cand.path.as_posix()}?mode=ro"
+ conn = sqlite3.connect(uri, uri=True, timeout=_DB_TIMEOUT_S)
+ except sqlite3.Error as exc:
+ log.warning("cli usage index: %s not readable (%s)", cand.path, exc)
+ return _FileScan(
+ rows=[], offset=start, cursor=_Cursor(), bytes_read=0, reason="error", failed=True
+ )
+ try:
+ conn.row_factory = sqlite3.Row
+ for row in conn.execute(
+ "SELECT m.id, m.session_id, m.time_created, m.data, s.directory "
+ "FROM message m LEFT JOIN session s ON s.id = m.session_id "
+ "WHERE CAST(m.time_created AS INTEGER) > ? ORDER BY m.time_created",
+ (start,),
+ ):
+ ts_ms = _int(row["time_created"])
+ newest = max(newest, ts_ms)
+ try:
+ data = json.loads(row["data"] or "{}")
+ except (TypeError, ValueError):
+ continue
+ if not isinstance(data, dict) or data.get("role") != "assistant":
+ continue
+ raw_tokens = data.get("tokens")
+ tokens: dict[str, Any] = raw_tokens if isinstance(raw_tokens, dict) else {}
+ raw_cache = tokens.get("cache")
+ cache: dict[str, Any] = raw_cache if isinstance(raw_cache, dict) else {}
+ tokens_in = _int(tokens.get("input")) + _int(cache.get("write"))
+ tokens_out = _int(tokens.get("output"))
+ if tokens_out <= 0:
+ tokens_out = _int(tokens.get("reasoning"))
+ tokens_cached = _int(cache.get("read"))
+ if tokens_in + tokens_out + tokens_cached <= 0:
+ continue
+ cwd = str(row["directory"] or "")
+ raw_path = data.get("path")
+ path_info: dict[str, Any] = raw_path if isinstance(raw_path, dict) else {}
+ cwd = cwd or str(path_info.get("cwd") or "")
+ rows.append(
+ (
+ cand.agent,
+ str(row["id"]),
+ cand.key,
+ str(row["session_id"] or ""),
+ ts_ms,
+ str(data.get("modelID") or ""),
+ tokens_in,
+ tokens_out,
+ tokens_cached,
+ cwd,
+ _clip(Path(cwd).name) if cwd else "",
+ float(data.get("cost") or 0.0),
+ )
+ )
+ except sqlite3.Error as exc:
+ log.warning("cli usage index: %s query failed (%s)", cand.path, exc)
+ failed = True
+ finally:
+ conn.close()
+ return _FileScan(
+ rows=list(rows), # type: ignore[arg-type]
+ offset=max(newest, cand.size),
+ cursor=_Cursor(),
+ bytes_read=cand.size,
+ reason="eof",
+ failed=failed,
+ )
+
+
def _scan(cand: _Candidate, start: int, cursor: _Cursor, deadline: float) -> _FileScan:
"""Read one transcript from ``start`` and return the turns it added."""
+ if cand.agent == AGENT_OPENCODE:
+ return _scan_opencode(cand, start)
rows: list[_Row] = []
reader = _LineReader(None, start)
if cand.agent == AGENT_AGY and not cursor.session_id:
@@ -1037,6 +1180,13 @@ def _open_rw(path: Path) -> sqlite3.Connection | None:
conn.execute("PRAGMA journal_mode=WAL")
conn.execute("PRAGMA synchronous=NORMAL")
version = _int(conn.execute("PRAGMA user_version").fetchone()[0])
+ if _MIGRATE_IN_PLACE_FROM <= version < _SCHEMA_VERSION:
+ # Rows counted under this version are right; only the shape grew.
+ columns = {r[1] for r in conn.execute("PRAGMA table_info(cli_turns)")}
+ if "cost_usd" not in columns:
+ conn.execute("ALTER TABLE cli_turns ADD COLUMN cost_usd REAL NOT NULL DEFAULT 0")
+ conn.execute(f"PRAGMA user_version={_SCHEMA_VERSION}")
+ version = _SCHEMA_VERSION
if version < _SCHEMA_VERSION:
# Rows counted under an older rule are wrong, not stale. Rebuild.
if _has_rows(conn):
@@ -1266,7 +1416,7 @@ def entries(
try:
for row in conn.execute(
"SELECT agent, session_id, ts_ms, model, tokens_in, tokens_out, "
- " tokens_cached, cwd, label FROM cli_turns "
+ " tokens_cached, cwd, label, cost_usd FROM cli_turns "
"WHERE ts_ms BETWEEN ? AND ? ORDER BY ts_ms",
(since_ms, until_ms),
):
@@ -1280,6 +1430,7 @@ def entries(
tokens_cached=_int(row["tokens_cached"]),
cwd=str(row["cwd"] or ""),
label=str(row["label"] or ""),
+ cost_usd=float(row["cost_usd"] or 0.0),
)
except sqlite3.Error as exc:
log.warning("cli usage index: read failed (%s)", exc)
@@ -1312,7 +1463,7 @@ def rollups(
" MIN(ts_ms) AS ts_ms, "
" SUM(tokens_in) AS tokens_in, SUM(tokens_out) AS tokens_out, "
" SUM(tokens_cached) AS tokens_cached, COUNT(*) AS turns, "
- " MIN(cwd) AS cwd, MIN(label) AS label "
+ " MIN(cwd) AS cwd, MIN(label) AS label, SUM(cost_usd) AS cost_usd "
"FROM cli_turns WHERE ts_ms BETWEEN ? AND ? "
"GROUP BY agent, session_id, model, ts_ms / ? "
"ORDER BY ts_ms",
@@ -1329,6 +1480,7 @@ def rollups(
turns=_int(row["turns"]),
cwd=str(row["cwd"] or ""),
label=str(row["label"] or ""),
+ cost_usd=float(row["cost_usd"] or 0.0),
)
except sqlite3.Error as exc:
log.warning("cli usage index: rollup failed (%s)", exc)
@@ -1443,7 +1595,8 @@ def _commit_file(conn: sqlite3.Connection, cand: _Candidate, scan: _FileScan) ->
before = conn.total_changes
try:
if scan.rows:
- conn.executemany(_INSERT_TURN, scan.rows)
+ priced = [r if len(r) == 12 else (*r, 0.0) for r in scan.rows]
+ conn.executemany(_INSERT_TURN, priced)
added = conn.total_changes - before
if scan.cursor.model:
# A replayed prefix lands before the file's ``turn_context``; the
@@ -1485,7 +1638,10 @@ __all__ = [
"AGENT_CLAUDE",
"AGENT_CODEX",
"AGENT_GROK",
+ "AGENT_OPENCODE",
+ "COST_READER_FOR_HARNESS",
"DB_NAME",
+ "HARNESSES_WITHOUT_LOCAL_TRANSCRIPT",
"CliRollup",
"CliTurn",
"IndexState",
diff --git a/jarvis/costs/model.py b/jarvis/costs/model.py
index b32d015f5b..88844c53de 100644
--- a/jarvis/costs/model.py
+++ b/jarvis/costs/model.py
@@ -265,7 +265,9 @@ def price_entry(
subscription=True,
tokens_cached=tokens_cached,
)
- if model.strip().casefold().endswith(":free"):
+ # ":free" is OpenRouter's free tier; "-free" is OpenCode's (its bundled
+ # zero-cost models are named that way, e.g. nemotron-3-ultra-free).
+ if model.strip().casefold().endswith((":free", "-free")):
return 0.0, "free"
# Lazy import: jarvis.brain.cost pulls the catalog cache and is not worth
diff --git a/jarvis/costs/sources.py b/jarvis/costs/sources.py
index 600002f729..a050f69909 100644
--- a/jarvis/costs/sources.py
+++ b/jarvis/costs/sources.py
@@ -464,7 +464,8 @@ def _mission_entries(path: Path | None, since_ms: int, until_ms: int) -> Iterato
continue
if not isinstance(meta, dict):
continue
- step = meta.get("step") if isinstance(meta.get("step"), dict) else {}
+ raw_step = meta.get("step")
+ step: dict[str, Any] = raw_step if isinstance(raw_step, dict) else {}
cli = str(meta.get("cli") or step.get("worker_cli") or "")
model = str(meta.get("model") or step.get("model") or "")
spawned[str(r["worker_id"] or "")] = (cli, model)
@@ -614,9 +615,9 @@ def _cli_entries(
parsed here: :mod:`jarvis.costs.cli_usage_index` reads each file once in
the background and this walks the small table it leaves behind.
- Every one of these ran on a monthly seat, so the amount is what the same
- work would have cost through the API and is labelled ``subscription``
- rather than counted as money that moved.
+ A CLI on a monthly seat is quoted at what the same work would have cost
+ through the API and labelled ``subscription``; one on the user's own key
+ (OpenCode) carries the price it recorded, which is money that moved.
"""
if data_dir is None:
return
@@ -643,13 +644,16 @@ def _cli_entries(
# ``claude-cli`` / ``codex-cli`` already carry their vendor in the
# name, which is all the logo lookup needs — no translation table.
provider = turn.agent
+ # Seat-driven CLIs are quoted at the API-equivalent; a bring-your-own-
+ # key CLI (OpenCode) recorded what its key was actually billed, and a
+ # free model there stays free rather than becoming a gap.
cost, source = price_entry(
provider=provider,
model=turn.model,
tokens_in=turn.tokens_in,
tokens_out=turn.tokens_out,
- recorded_usd=0.0,
- subscription=True,
+ recorded_usd=turn.cost_usd,
+ subscription=provider in SUBSCRIPTION_RUNNERS,
tokens_cached=turn.tokens_cached,
)
yield CostEntry(
diff --git a/tests/unit/costs/test_cli_usage_index.py b/tests/unit/costs/test_cli_usage_index.py
index 94dfff5aeb..d5714c24f1 100644
--- a/tests/unit/costs/test_cli_usage_index.py
+++ b/tests/unit/costs/test_cli_usage_index.py
@@ -993,3 +993,99 @@ def test_codex_rows_before_the_first_turn_context_get_the_model(tmp_path: Path)
refresh(data_dir=data, home=tmp_path)
assert {t.model for t in _all(data)} == {"gpt-5.6-terra"}
+
+
+# ---------------------------------------------------------------------------
+# OpenCode
+# ---------------------------------------------------------------------------
+
+
+def _opencode_store(home: Path) -> Path:
+ import sqlite3
+
+ folder = home / ".local" / "share" / "opencode"
+ folder.mkdir(parents=True, exist_ok=True)
+ db = folder / "opencode.db"
+ conn = sqlite3.connect(db)
+ conn.executescript(
+ "CREATE TABLE session (id TEXT PRIMARY KEY, directory TEXT, title TEXT);"
+ "CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT, time_created TEXT, "
+ " time_updated TEXT, data TEXT);"
+ )
+ conn.execute("INSERT INTO session VALUES (?,?,?)", ("ses_1", "C:/work/opencode-app", "t"))
+ conn.commit()
+ conn.close()
+ return db
+
+
+def _opencode_message(db: Path, msg_id: str, ts: int, *, cost: float, model: str) -> None:
+ import sqlite3
+
+ data = {
+ "role": "assistant",
+ "cost": cost,
+ "tokens": {"total": 1_050, "input": 1_000, "output": 50, "reasoning": 0,
+ "cache": {"read": 200, "write": 0}},
+ "modelID": model,
+ "providerID": "opencode",
+ "path": {"cwd": "C:/work/opencode-app"},
+ }
+ conn = sqlite3.connect(db)
+ conn.execute(
+ "INSERT INTO message VALUES (?,?,?,?,?)",
+ (msg_id, "ses_1", str(ts), str(ts), json.dumps(data)),
+ )
+ conn.commit()
+ conn.close()
+
+
+def test_opencode_messages_are_indexed_with_their_recorded_cost(tmp_path: Path) -> None:
+ from jarvis.costs.cli_usage_index import AGENT_OPENCODE
+
+ data = tmp_path / "data"
+ db = _opencode_store(tmp_path)
+ _opencode_message(db, "msg_1", 1_787_422_998_689, cost=0.0123, model="gpt-5.5")
+ _opencode_message(db, "msg_2", 1_787_422_999_000, cost=0.0, model="nemotron-3-ultra-free")
+
+ refresh(data_dir=data, home=tmp_path)
+
+ turns = sorted(_all(data), key=lambda t: t.ts_ms)
+ assert [t.agent for t in turns] == [AGENT_OPENCODE] * 2
+ assert turns[0].cost_usd == 0.0123
+ assert turns[0].tokens_in == 1_000 and turns[0].tokens_cached == 200
+ assert turns[0].label == "opencode-app"
+ assert turns[1].model == "nemotron-3-ultra-free"
+
+
+def test_opencode_reads_only_what_arrived_since_the_last_run(tmp_path: Path) -> None:
+ data = tmp_path / "data"
+ db = _opencode_store(tmp_path)
+ _opencode_message(db, "msg_1", 1_787_422_998_689, cost=0.01, model="gpt-5.5")
+ refresh(data_dir=data, home=tmp_path)
+
+ _opencode_message(db, "msg_2", 1_787_422_999_000, cost=0.02, model="gpt-5.5")
+ result = refresh(data_dir=data, home=tmp_path)
+
+ assert result.turns_added == 1
+ assert len(_all(data)) == 2
+
+
+def test_an_index_from_version_two_keeps_its_rows_and_gains_the_column(tmp_path: Path) -> None:
+ import sqlite3
+
+ from jarvis.costs.cli_usage_index import index_db_path
+
+ data = tmp_path / "data"
+ session = "019ffba8-3748-7652-bf9d-f3b54697b10a"
+ _write(_codex_path(tmp_path, session), [*_codex_prelude(session), _codex_token_line()])
+ refresh(data_dir=data, home=tmp_path)
+
+ db = index_db_path(data)
+ with sqlite3.connect(db) as conn:
+ conn.execute("ALTER TABLE cli_turns DROP COLUMN cost_usd")
+ conn.execute("PRAGMA user_version=2")
+
+ refresh(data_dir=data, home=tmp_path)
+
+ turns = _all(data)
+ assert len(turns) == 1 and turns[0].cost_usd == 0.0
diff --git a/tests/unit/costs/test_cost_read_model.py b/tests/unit/costs/test_cost_read_model.py
index d49c2b8468..d30ac4c0b1 100644
--- a/tests/unit/costs/test_cost_read_model.py
+++ b/tests/unit/costs/test_cost_read_model.py
@@ -646,3 +646,30 @@ def test_a_subscription_provider_is_priced_not_free() -> None:
)
assert source == "subscription"
assert cost > 0
+
+
+def test_a_bring_your_own_key_cli_row_is_billed_at_its_recorded_price(tmp_path: Path) -> None:
+ """OpenCode priced the call on the user's key: that number is the bill,
+ not a subscription quote, and its free models stay free."""
+ import sqlite3
+
+ from jarvis.costs.cli_usage_index import _SCHEMA, DB_NAME
+
+ data = tmp_path / "data"
+ data.mkdir()
+ conn = sqlite3.connect(data / DB_NAME)
+ conn.executescript(_SCHEMA)
+ conn.execute("PRAGMA user_version=3")
+ t0 = 1_700_000_000_000
+ rows = [
+ ("opencode-cli", "m1", "p", "s1", t0, "gpt-5.5", 1000, 50, 0, "", "app", 0.0123),
+ ("opencode-cli", "m2", "p", "s1", t0 + 1000, "nemotron:free", 1000, 50, 0, "", "app", 0.0),
+ ]
+ conn.executemany("INSERT INTO cli_turns VALUES (?,?,?,?,?,?,?,?,?,?,?,?)", rows)
+ conn.commit()
+ conn.close()
+
+ entries = {e.model: e for e in collect_entries(CostSources(cli_index_dir=data))}
+ assert entries["gpt-5.5"].price_source == "recorded"
+ assert entries["gpt-5.5"].cost_usd == pytest.approx(0.0123)
+ assert entries["nemotron:free"].price_source == "free"
diff --git a/tests/unit/costs/test_harness_cost_parity.py b/tests/unit/costs/test_harness_cost_parity.py
new file mode 100644
index 0000000000..c515fdca8c
--- /dev/null
+++ b/tests/unit/costs/test_harness_cost_parity.py
@@ -0,0 +1,47 @@
+"""Every coding harness the workspace can open is counted by the cost index.
+
+The registry (``jarvis/workspace/agents.py``) decides what the "Open beside"
+menu offers; the index (``jarvis/costs/cli_usage_index.py``) decides whose
+spend the Costs section shows. Nothing forced them to agree, and the drift is
+silent: a harness that opens, runs and bills — and never appears in a report.
+This binds the two: a new harness fails the build until its transcripts are
+read, or until it is listed with the reason they cannot be.
+"""
+
+from __future__ import annotations
+
+from jarvis.costs import cli_usage_index as index
+from jarvis.workspace import agents as workspace_agents
+
+
+def _builtin_coding_harnesses() -> list[str]:
+ names = set(workspace_agents.builtin_names())
+ return [a.name for a in workspace_agents.coding_agents() if a.name in names]
+
+
+def test_every_builtin_harness_has_a_cost_reader_or_a_stated_reason() -> None:
+ harnesses = _builtin_coding_harnesses()
+ assert harnesses, "the registry offers no coding harness at all"
+ for name in harnesses:
+ counted = name in index.COST_READER_FOR_HARNESS
+ excused = name in index.HARNESSES_WITHOUT_LOCAL_TRANSCRIPT
+ assert counted or excused, (
+ f"{name!r} can be opened from the workspace but the Costs section "
+ "will never see its spend. Add a reader to jarvis/costs/cli_usage_index.py "
+ "and map it in COST_READER_FOR_HARNESS, or state in "
+ "HARNESSES_WITHOUT_LOCAL_TRANSCRIPT why its usage cannot be read from disk."
+ )
+ assert not (counted and excused), f"{name!r} is both counted and excused"
+
+
+def test_every_mapped_reader_is_a_real_agent() -> None:
+ for harness, agent in index.COST_READER_FOR_HARNESS.items():
+ assert agent in index.AGENTS, (harness, agent)
+
+
+def test_no_stale_harness_in_the_cost_map() -> None:
+ """A harness removed from the registry must leave the map too, or the map
+ stops meaning 'what the menu offers'."""
+ registered = set(workspace_agents.coding_agent_names())
+ for name in (*index.COST_READER_FOR_HARNESS, *index.HARNESSES_WITHOUT_LOCAL_TRANSCRIPT):
+ assert name in registered, f"{name!r} is mapped but no longer registered"