Skip to content

Harnesses

Wijanarko Putra Rajeb edited this page Nov 20, 2026 · 40 revisions

Harnesses

Kabmo can run a chat on more than omp. The agent behind a session is its harness, and it is a first-class idea: it appears in the composer's model dropdown as a tab, beside the session name in the sidebar, and as a section in Settings.

The full measured design — every capability per agent, the frame mapper, the data model, the build order — lives in docs/milestones/M17-harnesses-design.md and docs/milestones/M16-harnesses-research.md. This page is the map of how the shipped code is arranged, and why.


The transport split

Harness Transport Why
omp RPC --mode rpc-ui (unchanged) the DEFAULT. The only path that reports todos, subagents, host tools, stats and compaction
omp-acp ACP over stdio (omp acp) a second tab for the same agent: it proves the adapter against a known agent, and gives a slimmer surface
opencode ACP over stdio (opencode acp) the 1.x CLI: measured 102 models
opencode2 — retired. The 2.x preview is now a 47-byte shim that execs opencode: measured on this machine, both report v2.2.5 and the shim's body is exec "$(dirname "$0")/opencode" "$@". One binary means one tab, not two.
command-code ACP over stdio (cmd acp) Command Code's own agent. Measured: 0.77 s handshake, 43 ms session/new, 96 models · 4 thought levels, list/resume/close advertised. Needs cmd login; todos are off until cmd mods enable todos -g
antigravity ACP over stdio (agy acp) Google's agent, replacing the retired gemini. Sign in once with agy (or agy acp --login); one process serves one project
zcode ACP over stdio (zcode-acp-server) Z.ai's agent. The vendor CLI has no acp subcommand, so the launch line is the community bridge that spawns zcode app-server --stdio. Measured through Kabmo's own client on 0.82.3: 1 model · 3 thought levels · 5 modes, list/resume/fork advertised, steering supported. A chat needs a ZCode runtime: the desktop app, or zcode-app-cli on PATH (ZCODE_BIN for a custom install). Custom providers live in ~/.zcode/v2/provider_config.json; ZCODE_BIN/ZCODE_HOME still decide which install and data root the bridge drives
grok ACP over stdio (grok agent stdio) xAI's Grok Build CLI. It ships its own ACP server (grok agent stdio), driven without --always-approve so tool approvals still arrive as session/request_permission and Kabmo's access tiers decide. Measured on 1.0.77: loadSession: true, sessionCapabilities list/resume/close, mcpCapabilities stdio+http+sse, authMethods: grok.com (a signed-out handshake answers session/new with "Authentication required"). Sessions return standard configOptions plus a models block (currentModelId + availableModels). grok login is needed once for xAI's own models, while a BYOK [model.<name>] table in ~/.grok/config.toml (base_url + api_key) runs without a login — measured end to end: currentModelId: "kenari", prompt returned end_turn on deepseek-v4-1-flash (11 787 in / 3 out) with text hello. By contrast, GROK_MODELS_BASE_URL + XAI_API_KEY alone still answered "Not signed in"
jcode ACP over stdio (jcode acp) The Rust agent from jcode.sh ships its own ACP adapter (src/cli/acp.rs), backed by the Jcode daemon; session/load and session/resume are implemented, session/fork is not. Configure a provider once in ~/.jcode/config.toml (jcode provider add …; API keys go to ~/Library/Application Support/jcode/ on macOS, ~/.config/jcode/ on Linux)
hermes ACP over stdio (hermes acp) Nous Research's Hermes Agent ships the adapter in-tree (acp_adapter/), but the stock install does not include it: the acp extra must be synced once (cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)"), which is what enables hermes acp and hermes-acp. The adapter logs to stderr and reserves stdout for JSON-RPC. Its initialize advertises loadSession: true, image prompts, and sessionCapabilities list/resume/fork; fork_session(cwd, session_id) takes no anchor, so the fork is whole-chat. Providers live in ~/.hermes/config.yaml (providers.<name> → api, api_key or key_env, transport, models), written by hermes model and its dashboard — Kabmo reads that table, never writes it
omo ACP over stdio (pi-acp) Oh My OpenAgent's standalone omo command. The CLI ships no ACP server (measured against 5.1.x: no acp subcommand), so the launch line is the pi-acp adapter with PI_ACP_PI_COMMAND=omo; OmO Native is a senpi (pi fork) engine, so the adapter's --mode rpc surface applies. Measured through Kabmo's own client on 5.1.9: initialize + session/new answered, 69 models · 3 thought levels, list/delete advertised. Providers live in ~/.omo/agent/models.json (same providers.<id> shape as pi); run omo setup (or /login) once before a turn succeeds
every other ACP over stdio measured: all of them ship it, so one adapter covers them all

gemini is gone; antigravity holds its slot. Google deprecated Gemini CLI in favour of Antigravity CLI, and the two are one product line's ancestor and successor — listing both would offer a dead agent beside its replacement and split one Google account across two tabs. The harness COUNT did not grow: exactly one Google adapter is advertised, asserted by catalog.test.ts.

Fork: what each agent can actually do

Standard ACP has no fork point: ForkSessionRequest carries only sessionId/cwd/mcpServers/additionalDirectories/configOptions/systemPrompt, and the session-fork RFD lists a message id as a future extension. Two JetBrains-maintained adapters implement it today as the AIR extension _meta.jetbrains.air.fork = {version: 1, messageId} (gate: none). Everything else forks the whole session, so Kabmo refuses an anchored request there (anchor_unsupported) instead of silently handing back the tip.

Harness session/fork Fork point Transcript store Kabmo path
omp-rpc / omp-acp yes (omp-acp 18.18.8) any turn ~/.omp/agent/sessions/<project>/<ts>_<id>.jsonl file cut (cutIndexFor + buildTruncatedBody)
claude yes (0.106.0) assistant message ~/.claude/projects/<slug>/<session-id>.jsonl (parentUuid chain, sidechains) AIR _meta
codex yes (adapter advertises fork: {}) the turn holding the message ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl (session_meta + items) AIR _meta
opencode yes (1.19.5) REST only: session.fork {before|through}; the ACP adapter calls it with no boundary SQLite ~/.local/share/opencode/opencode.db (session/message/part) whole over ACP; an anchor would need the REST server, which Kabmo does not run
zcode yes (0.83.3) target: {kind: "latestCheckpoint"} only ~/.zcode/cli/db/db.sqlite + rollout/model-io-*.jsonl whole / latest checkpoint
minimax yes runtime has assistantDisplayMessageId; the ACP handler passes none ~/.minimax/v2/sqlite/runtime-state.sqlite whole over ACP
kimi no — ACP fork_session raises NotImplementedError CLI-only file fork (wire.jsonl/context.jsonl truncated at a turn index) ~/.kimi/.../wire.jsonl none over ACP
qwen no session/fork in the ACP agent (only subagent forks) — ~/.qwen/sessions none
dsh no (measured: close/list/resume only) — ~/.dsh/sessions/<project>/<id>/session.v4.jsonl.zstd none
antigravity no (measured 1.5.3: forkSession: false) — not inspected none
pi no (probe blocked; research: list/delete only) — ~/.pi/agent none
command-code no (research: list/resume/close) — not inspected none
cursor unknown (closed source, not installed) — ~/.cursor/projects none
jcode no — ACP server implements load/resume only — not inspected none
grok no (measured 1.0.77: sessionCapabilities = list/resume/close, no fork; the CLI has an x.ai/session/fork extension) — ~/.grok/ session store none
hermes yes — advertises SessionForkCapabilities(), and fork_session(cwd, session_id) takes no message id — its own session DB (SessionDB under ~/.hermes/) whole over ACP
omo no (pi-acp advertises list/delete only) — ~/.omo/agent/sessions none

File surgery on claude/codex is possible in principle — both stores are JSONL — but the adapters' own fork reads the same store and handles sidechains/turns, so a second implementation would drift. kimi is the one agent whose CLI fork IS file surgery (turn-index truncation), but its ACP surface does not expose it.

The button follows the same fact. forkCapability(harness) (shared/lib/harness/fork.ts) is the one model: message (omp, claude, codex), tip (opencode, minimax, zcode) or none (qwen, dsh, antigravity, pi, command-code, jcode, grok, omo). canForkAt(harness, role) gates the row's Fork control — omp on a user turn and on the run footer, claude/codex on the run footer only, and tip/none on neither. The whole-chat fork is the session menu's Fork chat (canForkChat, probe-authoritative: an agent that does not advertise session/fork gets no item), which opens the same pending composer with no anchor — that is the only fork entry point for a tip harness. MessageList passes the session's harness down to ChatMessageItem and RunFooter, so the control cannot appear on a row the send path would refuse (anchor_unsupported).

omp over RPC is the default and is not a CHOICE, so catalog.ts marks it builtIn: true. Three surfaces read that flag:

  • Settings → Harnesses leaves it out (there is nothing to install or configure);
  • the composer's tab strip never treats it as blocked — see below;
  • /api/harness REFUSES to probe it, and reports builtIn, so no probe record can ever exist for it.

It stays in the CATALOG — a session row still has to name the transport that ran it — and it stays in the tab strip, which names the list on screen.

A probe must never mark the default harness blocked. Before the guard, a ?probe=omp-rpc produced the only answer probeHarness has for a harness with no launch line — capabilities.blocked: "No launch command is configured for this harness" — cached it for 30 minutes, and the tab strip reads blocked as both a ⚠ AND disabled. Measured: the omp tab rendered omp⚠ with disabled="true", so the harness every session actually runs on could not be selected. The flag is now honoured in the route (no probe record, and probing it answers 400 builtin_not_probeable) AND in the client (harnessBlockedReason returns null for a built-in, so a cache written by an older build cannot resurrect the mark).

The RPC path is untouched. Adding harnesses did not generalise omp's RPC mode into an abstraction; the ACP adapter is a second driver behind the same per-session seam.

Where the code lives

Concern Module
the catalog (ids, labels, glyphs, transport) src/shared/lib/harness/catalog.ts
brand colours for the marks src/shared/lib/harness/brand-color.ts
the mark itself src/client/components/common/harness-glyph/
which models a tab shows src/client/components/workspace/model-dropdown/harness-models.ts
the tab strip src/client/components/workspace/model-dropdown/HarnessTabs.tsx
the picker's measured size src/client/components/workspace/model-dropdown/popover-metrics.ts
the phone placement src/client/components/workspace/model-dropdown/Fullscreen.tsx
launch table + session spawn src/server/lib/harness/launch.ts, spawn.server.ts
capability model src/server/lib/harness/capabilities.ts
the ACP client src/server/lib/harness/acp/
the open chat's harness + the pending pick src/client/hooks/chat/timeline/session-harness.ts
the harness a spawn answered (before the sidebar row) src/client/hooks/chat/timeline/spawn-harness.ts
the mark on a run (indicator + answer footer) src/client/components/workspace/chat-timeline/RunMark.tsx
discovery + probe route src/server/routes/harness/root.ts
availability, the config-aware probe, the boot pass src/server/lib/harness/auto-probe.server.ts
which parts an update moves (pure) src/shared/lib/harness/update-plan.ts
the background job: start, record, settle, repoint src/server/lib/harness/update-job.server.ts, update-job-store.ts, update-worker.ts
the record's wire shape + guard src/shared/types/harness-update.ts, src/shared/lib/harness/update-job.ts
the dialog's start-and-follow hook src/client/hooks/models/use-harness-update.ts
the shared catalog store + its one read src/client/hooks/models/harness-catalog.ts
the useHarnesses() controller src/client/hooks/models/use-harnesses.ts
registry writes, in refresh order src/server/lib/models/registry-refresh.server.ts
which harnesses read a registry file harnessesSharingRegistry in src/server/lib/harness/provider-sources.server.ts
Settings → Harnesses src/client/components/settings/categories/HarnessSettings.tsx

The rules that took a bug to learn

The active tab decides the model list — never a merge

omp's list is Kabmo's /api/models (omp's registry, with favorites, recents and provider plates), returned untouched. Every other harness replaces it with its own configOptions[model]. A merge would offer rows the active agent cannot run, which fail at the first prompt; and an unprobed harness reports unprobed rather than showing omp's list as a stand-in.

A LIVE chat outranks the probe. There are three sources, ranked: omp-rpc → /api/models; an ACP harness with an open session → the selectors that session itself published (get_state → configOptions, served on /api/chat/:id as harness + liveModels); an ACP harness with no session → its probe. A probe is one throwaway spawn and can be REFUSED while the running chat lists models — measured with codex: the probe answered "Authentication required" beside rows the chat was already offering. The loader publishes the live lists once per session read (publishLiveModels guards a no-op update), and harnessModels(..., live) reads them first, so no "Authentication required" banner sits beside a usable list.

Measured sizes: omp 221, omp (ACP) 221, claude 5 (default, opus, claude-fable-5[1m], sonnet, haiku), opencode 102, dsh 1.

Before liveModels, an ACP harness's JSONL branch returned without the live fields at all: the picker could only ever show a probe snapshot, and the composer named the file's last model instead of the one in force.

Pinned by harness-models.test.ts (the merge is refused, the omp list survives identically, a live chat outranks a refused probe, an unprobed harness yields unprobed) and session-load.test.ts (a session payload publishes its live lists to the harness store).

The popover is sized by measurement, not a constant

popover-metrics.ts computes the box from the trigger's own rect, the space above it, and the visual viewport. A constant width is what makes a picker look right at 1440px and clip at 900px. popover-metrics.test.ts pins the cases that matter: a short window shrinks the height before the width, a narrow panel shrinks the width, and the box never exceeds the trigger's panel.

On a phone the picker is FULL SCREEN; a desktop keeps the popover

fullscreen-picker.ts decides. The shell's own isMobile verdict wins when the picker is given one (App.tsx already answered it from the user agent, the pointer and a landscape-phone height test); otherwise it reads (pointer: coarse) first and width second — a 900px touch window is still a phone surface, a 600px mouse window is still a desktop.

Fullscreen.tsx renders the SAME card content as a 100dvh overlay and portals to <body>, for the reason the composer rule states: the composer card can become a containing block for position: fixed through backdrop-filter, transform or contain: layout.

The sheet that came first is gone, and the measurements are why: on a 390x844 phone an 86dvh sheet showed ~7 model rows and left 344px of dead canvas above it; the full screen shows ~18. The full screen also drops the popover's keyboard-hint footer (↑ ↓ navigate, Tab switch agent) — a phone has no keyboard to press them on.

The click-outside guard is DISABLED in the full-screen placement

This is the bug that made a phone picker look broken. A portalled overlay is outside the picker's containerRef by construction, so an armed useOnClickOutside sees the press that was meant to trigger a row as an outside press and closes the picker on mousedown — before click reaches the row. useOnClickOutside(ref, handler, enabled) now takes an enabled flag and the picker passes !fullscreen.

Pinned by on-click-outside.test.ts (armed closes on an outside press and ignores an inside one; disabled listens to neither pointer type) and placement.test.tsx (the frame portals to <body>, not into the composer).

The popover measures from its ANCHOR to the composer's right EDGE

popover-metrics.ts takes anchorLeft (the trigger's left edge, where the card starts) and containerRight (the composer card's right edge, read from [data-composer-style]), with a ResizeObserver on both elements.

Two earlier forms were wrong, each in a different direction:

Budget Failure, measured
the TRIGGER's width a 259px chip inside a 712px composer produced a 275px card; every model name rendered Agn…
the PANEL's width a 437px card hung 29px past a 421px composer — the card starts 13px inside the panel and that overhang was never subtracted

Desktop caps: 512 x 460. The width went 384 → 512 because the row (two marks, the name, a context figure, a thinking chip, a star) cut the name at 384; measured scrollWidth 139 / clientWidth 0. The height went to 620 and came back to 460 — at 620 the card stood ~14 rows tall on a 1200px window and read as a panel over the conversation rather than a menu beside it.

Two older measured bugs the pure arithmetic also pins:

  • The popover's measured width was applied to the card inside the phone frame, so a 390px frame held a 292px card and every name truncated to A..
  • vh sizing put the last row under the browser chrome; dvh plus env(safe-area-inset-*) does not.

The harness mark is gated at the CALL SITE, not inside the glyph

HarnessGlyph returns null for an unknown harness — but the wrapper span that owns the 6px gap (mr-1.5) stays behind, shifting every pre-harness and MOCK row's title right by 6px while the page still looks plausible. So each row writes {harness && (<span…>)}, in all three layouts: SessionItem (classic), common/session-row (modern), and mobile-session-sidebar/SessionRow.

The mark reads its id from harness_sessions, the table a spawn writes and sidebar-data.server.ts reads. Before it existed the field was filled from DEFAULT_HARNESS_ID for EVERY row, so the mark said omp for a chat that ran on opencode2 — decoration, not information. Two consequences of that table:

  • an ACP chat is now LISTED at all. Its agent writes no session file, so omp's JSONL discovery cannot see it: the chat existed in the registry and in no list, and disappeared from the sidebar when its tab closed. acp-rows.server.ts builds those rows from the record, filed by resolving each chat's own cwd to a project root — the same resolution the scan applies.
  • the merged list is sorted as ONE sequence. Appending the ACP rows after omp's already-sorted bucket put a chat just spawned below 240 older ones, behind "Show more" (measured).

An omp row is persisted too (its resume id lives there), which is why the ACP listing carries harness <> 'omp-rpc' in its SQL. That is a cheap PRE-FILTER, not the rule: omp-acp is omp over the Agent Client Protocol — the same binary, writing the same JSONL store — so its chats are found by the scan and recorded in this table, and the filter let both through. Measured on a real id (01a1af9c-…): two sidebar rows, Halo from the scan and Untitled from the record. One chat, one row is enforced where the two lists MERGE (sidebar-data.server.ts): a recorded row whose id the scan already listed is dropped, keeping the scan's row because it carries the real title and timestamps. That rule holds for any future agent that writes a session file. The client's placeholder id (__new__<uuid>) is never persisted: it is an alias in the live registry, not a session, and storing it listed the chat twice.

A recorded chat is NAMED, not left Untitled

acpRowsFor used to write a literal title: 'Untitled' for every row it built, on the argument that an ACP agent publishes no title of its own and inventing one would put words in its mouth. The argument was right for a chat with no content and wrong for every chat that has any: measured an hour after a claude chat's first prompt, its row still read Untitled — while the placeholder row it replaced (the client's titleHint) had shown the user's own words all along, so the real row was a visible REGRESSION of the placeholder.

Two sources now, and harness_sessions.title holds whichever arrived:

Order Source Written by
1 the first prompt notePromptTitle, from dispatchCommand's prompt case — the ONE place every ACP prompt passes (a new chat's first send, a live send, a queue delivery)
2 the agent's own title (session_info_update) noteAgentTitle (see the note on the turn gate below)

The DISPLAY rule is the omp row's, unchanged: deriveSessionTitle (shared/lib/omp/session/sidebar.ts) is name → first message → a New Session - <created> stamp, and sessionTitleFor now calls the same function — two copies of that precedence is how one row source starts saying Untitled where the other says the first prompt. The stamp comes from the row's created_at, never new Date(), so a revalidation cannot re-stamp the title.

saveHarnessSessionTitleIfEmpty is the contract that makes a first prompt safe to record from a path that sees EVERY prompt: a steering message, a retry or a queued follow-up reaches the same call with its own text and must not rename the chat. The agent's own title uses the unconditional writer, because it outranks Kabmo's guess — and the writer's inequality guard keeps an agent that re-sends the same title from republishing the sidebar's whole structure.

Pinned by harness/session-title.server.test.ts (the two writers, the empty-title no-op, one publish per change) and the three title cases in sidebar-data.harness.test.ts, which read the row the sidebar actually draws.

The mark sits between the leading slot and the name, at 12px compact / 13px touch. Measured geometry in a running build, all three layouts: slot x=12, gap x=28, mark x=36, title x=54.

Pinned by harness-mark.test.tsx — including the spacer assertion, which is the one the text-only test missed.

Delete and archive: the RECORD is the row

harness_sessions is the sidebar row of an ACP chat, so the delete flow has to purge it — it only purged Kabmo's own tables. Measured against the delete route:

Chat Before Visible result
opencode (no JSONL) 404 {"error":"Session not found","code":"not_found"} row stayed forever
omp-acp (JSONL and record) 200 {"success":true,"fileRemoved":true} row came straight back from the record
an ARCHIVED ACP chat 200, and the purge ran archived_sessions before answering row returned unarchived — read as "delete undoes Archive"

purgeSessionData now deletes harness_sessions, harness_goal_state and harness_usage_state with the other session-keyed rows, and found is true for an ACP chat that only ever had a record. After the fix the same calls answer 200 and the next sidebar build has no row.

The process half is the harness-AGNOSTIC registry, not getRpcSession: an ACP session is not an AgentSessionWrapper, so the omp-only lookup answered "nothing live" for every non-omp chat and the delete removed rows under a running agent. removeSession now uses getLiveSession — busy → 409 session_busy, idle → destroyAndWait() before the purge.

Pinned by routes/sessions/delete-acp.test.ts (record-only delete, goal/usage rows, the archived case, omp-acp not re-listed, busy refusal, idle teardown).

Delete removes the AGENT's copy too

Purging Kabmo's rows is not a deletion for a chat that ran on another agent: the conversation lives in that agent's store, and the next import (session/list) copies it straight back. Measured on this machine: bun run dev auto-imported 615 sessions from opencode and dsh; deleting one removed the row and the next pass restored it. dsh's 337 imported rows had no title, so the sidebar drew them as New Session - <timestamp> — the "hundreds of New Session rows" report.

removeSession now asks the agent before any Kabmo row goes (lib/harness/session-delete.server.ts):

  • Live child first. deleteAgentSession() returns false when the agent advertises no session/delete, and THROWS on a real failure (it used to log and swallow, which is how a failed delete still answered 200).
  • No live child (an imported row, a closed tab, an exited child): one fresh child per harness, reused for the whole batch — 300 rows on one harness must boot that agent once, not 300 times.
  • dsh has no verb to call. 0.2.2-rc.1 advertises sessionCapabilities.list only, so its <DSH_HOME|~/.dsh>/sessions/<project>/<id>/ directory is removed directly, without spawning it. The project level is scanned rather than re-encoding a cwd the row may no longer have.
  • omp-rpc/omp-acp keep no second copy: the JSONL the purge removes IS the agent's store.
  • A refusal is the answer. 502 agent_session_not_removed with the agent's own words; the row stays, because purging it would only bring it back and the user would believe the chat was gone.
  • The purge writes a tombstone. purgeSessionData inserts the id into deleted_sessions (lib/sessions/deleted-sessions.server.ts), and both the import and the sidebar skip it. The agent's store is the source an import copies from, so removing Kabmo's rows alone is not a deletion: measured, a deleted imported row returned on the next pass. The tombstone is durable — it outlives the process, a reload and a second instance — and it is written with the purge rather than by the route, so a future caller cannot skip it.

Pinned by lib/harness/session-delete.server.test.ts (the id on the wire is the AGENT's, an agent without the verb refuses, the dsh directory goes without a spawn, omp needs no second store) and the dsh/refusal cases in routes/sessions/delete-acp.test.ts.

An idle ACP child is reclaimed, on the omp clock

The omp wrapper has always ended its child after a quiet window (IdleReaper, IDLE_REAP_MS = 10 min). The ACP transport had no clock at all, and nothing else ends a child it is not actively driving — so an omp acp spawned for a chat the user had not touched stayed resident indefinitely. Measured on this machine: omp acp (pid 29716) still alive 3 h 43 m after its chat's last command, under a server that had been up 20 h.

AcpSession now owns the same IdleReaper (acp/session-idle.ts): start() arms it after the handshake, every dispatched command and every incoming frame defers it, and a destroy stops it. A session that is running or parked on an approval dialog answers false, so the reaper re-arms instead of killing the question the user is still reading.

One exception is deliberate: a child whose agent cannot session/load is never reclaimed. resumeRecordedHarnessSession refuses to start a fresh agent under a chat's id, so reclaiming one would leave a chat that can never take another prompt. omp-acp is reclaimed regardless of its advertised loadSession (measured true) because it writes a session file Kabmo resumes over RPC.

Pinned by acp/session-reaper.test.ts (decision + wiring) and smoke-tested against a real omp acp: idleDestroyMs: 1500 reclaimed the child 1.5 s after the handshake and isAlive() went false.

A pending chat warms its agent — the PROCESS, never a session

Opening a new chat used to pay the agent's boot on the first prompt. omp's RPC child had a prewarm pool; every ACP agent had none, so picking claude from the composer's tab strip and typing was followed by a cold spawn.

Two pools now exist (routes/agent/prewarm.ts picks one by harness), and the client fires the request at the earliest moment each fact is known: the sidebar's New Session click warms omp, a New Chat card opened from an ACP chat warms THAT agent, and pending-warmup.ts re-fires when the composer's harness or Plan pick moves (the server recycles an entry that can no longer serve the request).

The ACP pool warms a process and stops at initialize. Measured on omp-acp: ~1 ms spawn, ~100 ms initialize, ~80-120 ms session/new. Warming through session/new was tried and reverted — omp-acp writes its session JSONL at that moment, Kabmo's sidebar scans that directory, and a warm child nobody claimed appeared as an empty chat row (measured: the file lands before any prompt and outlives the child). So the claim adopts the process and the session that owns it runs the same session/new and config writes a cold spawn does.

Why it can be warmer than omp's pool: omp's modes ride the spawn ENVIRONMENT and are read once, so an entry whose selection differs is killed. ACP applies model, thinking, mode and the approval tier after session/new, so ONE warm process serves any pick. Smoke-tested against a real omp acp with an isolated DB: prewarm settled in 99 ms with zero session files; startAcpSession with claimPrewarmed adopted that same child in 89 ms (cold: 208 ms) and landed mode: plan plus accessMode: yolo on it.

The pool is keyed by harness + cwd, replaces a candidate the operator left (one pending chat runs one agent), and disposes an unclaimed entry after IDLE_REAP_MS — restartPrewarmedAcpSessions disposes them on an engine reload/update too. Pinned by acp/prewarm.test.ts (single adoption, dead child, failed-spawn retry, sibling replacement, recycle).

About names the agents, and links to their pages

About used to answer "which product am I running?" for two products. It now runs a chat on a dozen agents, so the card carries an Agents strip: one row per harness, its real state (ready / needs setup / not installed / not probed from harness/status.ts), and a link to that harness's settings page.

  • the rows come from the SAME shared useHarnesses() store the composer's tab strip and Settings read, so a probe made anywhere appears here with no reload;
  • a row is a LINK, never an editor — editing lives on the harness's own page, and About is where you learn which page to open;
  • the built-in transport gets no row: nothing to install or probe, so listing it would inflate the count with the one entry nobody decides about.

Layout: the sheet went from max-w-[340px] in one column — which could not hold the strip at all — to 720px, two panes at md (agents on the wide side, updates and links on a 260px column), scrolling as ONE page so the close control never sits over a pane still moving. Measured on a 390x844 phone: 358px wide, 743px tall, two 151px columns, scrollable.

Two columns also fixed a truncation: three cells inside a ~380px pane cut command-code to command-c…, and no label truncates at two.

Pinned by HarnessStrip.test.tsx — the real state per row, the binary named in a missing-install title, no row and no count for the built-in transport, and a row opening harness:<id> while the footer opens harness-index.

The settings menu draws the vendor's mark, not a lucide shape

Every harness page in the Settings drawer carries the agent's OWN logo (HarnessGlyph, 14px), because the rest of the app already identifies an agent by its mark — a session row, the composer's tab strip, a model row — and a generic Waypoints glyph beside the word "claude" asked the reader to learn a second vocabulary for the same fact.

Two exceptions, both deliberate:

  • the overview keeps a lucide glyph. It is not an agent, so a brand mark would claim it were one.
  • the mark sits in a FIXED-WIDTH slot (w-[14px]). The marks have different viewBoxes — omp is 64x64, the rest 24x24 — so an unstyled inline svg makes every label beside it shift. Measured: with the slot, labels in the HARNESSES group and the rest of the menu all land at the same x.

Pinned by settings/harness-icons.test.tsx: every harness row draws a branded svg, the overview draws none, the generic glyph is GONE (not merely accompanied), opencode and opencode2 share one vendor key, and the slot is what holds the column.

A tab is the MARK, and the two omp surfaces differ by colour

A harness tab draws no label. Three to five tabs share one strip, and the names (claude, deepseek-harness, omp (ACP)) spent the strip's width restating what the vendor's own mark already says. The consequence is that the mark now carries the accessible name (aria-label is the harness's label), the reason a tab is unavailable moved into title + aria-description — see the next section, which is where that turned out to be broken — and a blocked tab is dimmed with OPACITY, because the colour mode paints it a brand hue that no text-ink/35 can outrank: a hue-only mute left an unavailable agent looking as ready as the one beside it.

HARNESS_GLYPH_SIZE is { compact: 12, touch: 13, tab: 18 }. The tab gets its own entry rather than reusing touch: reusing it would mean growing the sidebar silently shrinks the composer's tabs, and the two are not the same kind of surface — a session row is a dense list, the tab strip is a primary control whose mark IS the target.

size is measured against the INK, not the source viewport. Reported as "the icons look different sizes". They were: every mark is drawn at one size, but a brand's viewport is not a brand's mark. Measured with getBBox() across the twelve shipped marks — omp draws a 36x40 mark inside its 64x64 art (62.5% of the height) while codex, command-code and qwen fill all of 24x24. At an 18px tab that was 11px of omp ink beside 18px of codex. So HarnessBrandGlyph carries the measured ink box and HarnessGlyph renders viewBox={ink}: one size now paints the same mark height for every brand (measured after: omp 16.2x18 ink, codex 18x18, claude 18x11.3 — same nominal height, each brand's own shape kept by preserveAspectRatio). The box is measured, never derived, and harness-glyph.test.ts pins three of them.

One brand, two surfaces, two colours. omp publishes one logo, and HARNESS_BRAND_COLORS is keyed by it — so omp-rpc and omp-acp drew the same purple. That was correct while the word "omp (ACP)" sat beside the mark and is a defect the moment the mark is the whole tab: two identical glyphs naming two different transports. The glyph therefore also carries data-harness-id (the harness) beside data-harness (the brand), and HARNESS_SURFACE_COLORS paints the id: purple #9b4dff for RPC, red #dc2626 for ACP. The surface rules are emitted AFTER the brand rows — same specificity, so order is what lets the override win — and both values go through legiblePair so each variant clears the 3:1 non-text floor on every shipped palette.

Pinned by harness-tabs.test.tsx (empty textContent, aria-label carries the name, 18px mark, dimmed blocked tab), harness-glyph.test.ts (the measured viewBox crop and data-harness-id on the svg), icon-paint-harness.test.ts (the two surfaces differ, the surface rule follows the brand rows, the tab strip keeps both hues in monochrome) and brand-color.test.ts (both variants clear the floor).

A tab that cannot be pressed still has to EXPLAIN itself

Four measured defects, three of which made the reason unreachable:

  1. disabled swallows the tooltip and the click. In Chromium a <button disabled> never shows its title — the one thing a blocked tab exists to say — and never delivers a click, so onFix could not fire either (elementFromPoint on the tab answered the tab, and the handler ran 0 times). The tab therefore uses aria-disabled, stays focusable, and keeps its handler.
  2. A nested title wins. HarnessGlyph sets title="Session runs on claude" on its own <span>, and that span is INSIDE the tab button — the browser shows the innermost title, so a locked tab announced the generic sentence and never the explanation one level up. That is the reported "tooltip tidak informatif". Inside a named control the mark is drawn with decorative: no title, no role="img", no aria-label.
  3. cursor-help is a QUESTION MARK. Reported as "kenapa ada icon tanda tanya ketika hover" — on macOS the help cursor is an arrow with a ?, which read as a stray icon over an icon-only tab. Three states now, each earned: pointer where a press selects (or opens that agent's settings), not-allowed where the chat already runs on another agent and a press cannot switch anything (the state most tabs are in once a transcript exists — reported from use as "kasih tanda larangan"), and default on the current selection, which is not a refusal.
  4. A missing install was blamed for an auth failure. Measured in the running picker: codex was blocked with Authentication required and the tab appended npm i -g @agentclientprotocol/codex-acp — advising a user to install a program that had just replied. harnessBlock() now separates the REASON from the FIX: a probe refusal carries no install hint (the binary ran, and its own sentence names the command), while a harness that never launched carries one. Pressing a blocked tab opens THAT agent's settings page (omp:open-settings with harnessCategoryId), because login and install are both fixed there; it used to re-probe and console.warn the answer into devtools.

The sentence itself names the OWNER. "Start a new chat to use claude" was true and useless — it never said which agent already held the chat, so a lock could not be told from a mistake:

  • blocked → <label>: <agent's words> (+ — install: … only when nothing launched);
  • chat already started → Cannot switch to <label>: this chat already started on <owner>. Start a new chat to use <label>.;
  • the tab IS the owner → <label> is the agent this chat already started on.;
  • otherwise → <label> · <agent name> <version> from the probe.

The same sentence is the accessible one: title for the pointer and aria-description for the keyboard path, so screen readers cannot hear "claude, tab, dimmed" with no reason. Both come from one call, so they cannot drift.

A pick on a pending chat has to be WRITTEN and RENDERED

Reported as "I sent with the opencode harness and it was processed by omp".

Two independent gaps, and both had to be closed for one click to work:

  1. The composer was never handed the harness. PendingChatView and EmptyWorkspacePrompt — the branch every new-… chat renders through — had no harness / onSelectHarness props at all, so ModelDropdown's tab strip changed only its OWN viewHarness state. pendingHarnessRef stayed null, send.ts omitted the field, and routes/agent/new.ts fell back to its documented default: 'omp-rpc'. The tab LOOKED switched, which is what made it read as the server ignoring the pick.
  2. The pick lived only in a ref. Even once wired, a ref cannot re-render, so the strip could not show the choice it had just recorded. useSessionHarness now keeps the pick in state as well, keyed by the chat it was made on (a second new-… chat must not inherit the first one's harness), and writes the ref in the same call.

The tab strip's own view is deliberately NOT the source: harness is a SPAWN property that decides the transport, the model list and every capability, so it has one owner per chat — the sidebar row once spawned, the pick before that.

The access tier is remembered PER HARNESS, and its copy follows the transport

The composer's access chip drew omp's three tiers on every harness and stored one global value (omp_access_mode). Two things were wrong with that:

  • The same three words are a different control on ACP. omp's tier IS the approval gate (--approval-mode over RPC, tools.approvalMode over ACP). Another agent decides which calls it asks about (session/request_permission) and Kabmo's tier only decides which of those arrive as a dialog (acp/permissions.ts → autoApproval). It can loosen the agent's own policy and never tighten it, and tools.restrictedFolders does not exist there — so the omp copy ("except a restricted folder, which always asks") was a promise this transport cannot keep.
  • The value leaked across a harness switch. Full bypass picked on omp followed the operator to claude, whose approvals were then auto-answered — a grant nobody made for that agent.

access-mode.ts now keeps the pick per harness (harness_access_modes), with omp's own entry mirrored into omp_access_mode because the server reads that key as its spawn-time default for the paths that carry no explicit pick (a scheduled task, a child spawn, a held prompt). Every other harness starts at always-ask until the operator picks one FOR IT. accessLevelCopy(harness) switches the descriptions and adds the disclaimer under the list. Measured in the browser: Full bypass on claude, switch to omp → Always ask, switch back → Full bypass; the stored map read {"omp-rpc":"always-ask","claude":"yolo"}.

The run's mark names the agent, and the spawn's answer covers the gap

The generating indicator and the AI answer footer both hardcoded lucide's Bot. On an opencode or claude chat that is a false claim in the one row the user watches while waiting, so both now draw the harness's own brand mark through one component (RunMark.tsx); an unknown or absent harness still falls back to the robot rather than an empty badge.

The source is the sidebar row, which is written at spawn — so a fresh chat has no harness for the first seconds. spawn-harness.ts records what the SERVER answered with (new.ts returns harness on the ACP branch and omits it for RPC, which means omp), and useSessionHarness reads it in that window. The answer is used rather than the request, so a pick the server refused can never be reported as the agent running the chat.

The badge is an INVERTED surface (bg-ink + text-canvas), so the mark passes inherit and the colour mode's .bg-ink svg[data-harness] { color: currentColor } rule keeps it on that foreground. Without it an opencode mark (brand #000000) or a claude one (#D97757) painted its brand hue on a fill that already IS the palette's foreground — invisible in one of the two themes.

Brand chroma rides the icon-paint rule

The mark's colour comes from HARNESS_BRAND_COLORS, painted through the fourth family in the one color: rule: svg.lucide, svg[data-provider], svg[data-file-brand], svg[data-harness]. legiblePair derives the dark variant from the brand's own hex, so a harness with no published colour stays ink instead of inventing a hue.

HARNESS_SURFACE_COLORS is the layer above it, keyed by data-harness-id, for the one case the brand table structurally cannot express: a vendor whose two harnesses share one logo. See "A tab is the MARK" for the measured reason.

The catalog is ONE store, shared by the picker and the settings page

use-harnesses.ts holds module state, not per-call useState. Two surfaces read /api/harness at once — the composer's tab strip and Settings → Harnesses — and with one state each, a probe lived in whichever instance ran it: pressing Check status on opencode2 wrote the 96 models into the SETTINGS copy while the picker still said "This harness has not reported its models yet". Measured in a browser: probe in Settings, open the picker, 0 rows; reload the page, 96 rows — the answer only looked fresh because the server had cached it and the reload re-read the cache. probe() now pushes to every subscriber.

Pinned by use-harnesses.test.ts: two mounts share ONE catalog read, a probe from one is visible from the other with no reload, a late mount still sees the catalog, and a failed read reports instead of claiming "none installed".

A models frame during the mount's own read must re-run it. The topic routinely lands while the first GET /api/harness is still in flight, so a re-read that merely cleared the "loaded" flag joined that same promise and kept the PRE-write answer — the picker showed the old probe until a manual reload. invalidateCatalog() bumps a generation; a read that finishes with a stale generation starts another instead of settling. Pinned by use-harnesses-signal.test.ts, which publishes the frame against a real socket and asserts a third read (mount, subscription snapshot, post-write).

The catalog also follows the models topic. A provider import, add or bespoke write refreshes the server's probes on its way to republishing models (invalidateModelsCaches), so the cached catalog is stale in exactly the way the composer's model list is — and the picker showed pre-write probes until a reload. The hook's effect now subscribes through subscribeModelsUpdated and drops loaded before re-reading /api/harness; announceProviderWrite already refreshes the affected probes, and the topic carries the same fact to every other surface and tab.

Measured cost, and why it is paid: realtimeClient.subscribe delivers the CURRENT value of a topic when the subscription opens, indistinguishable from a change, so mounting the hook reads the catalog twice (its own read plus the snapshot-triggered one). The second answer is the same catalog. use-harnesses-signal.test.ts pins both halves: baseline probe is null after 2 reads on a topic that never changed, and one publish with a probe now available takes a third read and renders the models.

A registry write refreshes every reader, in order

models.yml is loaded by the pooled omp utility child when it is SPAWNED, and get_available_models only awaits an in-flight refresh — it never compares the file's mtime. Dropping Kabmo's cache alone therefore left /api/models answering the OLD registry from that child: measured, adding a provider only appeared after omp was restarted.

refreshModelRegistryAfterWrite (src/server/lib/models/registry-refresh.server.ts) is the one path every settings write and the import route use, and its order is the contract: recycle the pooled readers → forget the probes that measured the old file → re-probe when asked → invalidate the caches LAST (the models topic resolver reads through loadModelsWithCache; invalidating first would publish and cache the pre-write answer for another minute).

The relation is the FILE, not a pair of ids. harnessesSharingRegistry(path) maps whatever file a harness reads to every harness that reads it — omp-rpc and omp-acp are two transports over the same models.yml, so a provider added on either tab invalidates both pickers. A per-model override passes probes: false: it changes a row's metadata, not which models exist, so the stored probe stays valid and the ACP picker does not blank out.

Pinned by registry-refresh.server.test.ts (the injected side effects run in that order; a restart that throws drops no cache) and provider-sources.server.test.ts (both transports share one file; a harness with its own file names only itself; a file no harness reads invalidates nothing).

About: ONE table, not a grid plus a version table

The card draws a single table — one row per harness carrying its STATE, its running VERSION and the one ACTION that moves it. It used to draw the same fourteen agents twice (a status grid, then a version table below it), which is why it had grown to 760x920 and why a reader asking "is this working, and is it current?" read the same names twice for two halves of one question. Measured after the merge: 680x640, one list, three aligned columns, no name truncated.

Column widths are the design, and they were wrong first: a 9rem action column left the NAME column narrow enough to cut command-code and deepseek-harness while their action cells had room to spare. The name takes the slack (it is what a reader scans) and the widest installer command ellipsizes with its full text in title.

Two measurement traps, both hit here:

  • a stale stylesheet. bun run build wrote the new utilities, the server served the old sheet, and getComputedStyle reported the arbitrary grid-cols-[...] as one 350px track. Restart the server after a build before trusting a layout measurement.
  • measure the row, not its container. The first probe read the outer two-pane grid (grid-cols-[1fr_260px]) and reported the merge as broken.

The About card's final shape

Desktop: a wide two-column card that never scrolls — 880x718 measured, three columns per row pair, the harness list in TWO columns. The tally and Open Settings → Harnesses sit on the heading's row at the right edge (both are ABOUT the section), and the strip under the list is one stacked column: update controls, then the links in ONE centred row under them.

Phone: ONE centered card with 12px gutters — 366x820 measured at 390x844 — one column, and one scroller. It used to be the whole screen (h-full w-full, no gutter, box [0,0,500,913]): the header sat at the viewport's top edge, which a viewport-fit: cover surface draws UNDER the phone's status bar, so the wordmark and half the close button were unreachable. The scrim now carries safeAreaPadding() (shared/lib/ui/safe-area.ts) — max(0.75rem, env(safe-area-inset-*)), the same rule the shared Modal shell states — and the card caps at the model picker's own 512px instead of the screen width.

The card is also the ONLY scroller on a phone. Two scroll traps were measured: the harness list capped itself at 46vh and scrolled while the card had most of the screen empty below it, and the phone card had a second overflow-y-auto on its own body — so a drag near the bottom moved the container, not the table. The list is now plain flow and the body holds min-h-0 flex-1 overflow-y-auto; measured listScrolls: false, cardScrolls: true with the whole 13-row list laid out below the fold.

The phone tracks are their own pair, because the desktop pair starves the name: minmax(0,1fr) 7rem 1.75rem measured 168 / 112 / 28 px at 324px of content width — 9.5rem stays for md. An arbitrary grid-cols-[…] utility is compiled by the BUILD, so a dev server started before the edit serves the old sheet and getComputedStyle reports no track at all; restart before measuring (the same stale-stylesheet trap the desktop table hit).

Three layout mistakes were measured and undone on the way here:

  • a right rail for the update controls squeezed each row's three cells into 280px while the rail held two short blocks — the content paid for the sidebar;
  • a two-column bottom strip put "check for updates" beside the links, making a reader pick a column for a control that has nothing to do with them;
  • a border-t on the wrapper doubled UpdateSection's own border-y, two rules 16px apart reading as a mistake;
  • a md:w-auto card, which is sized by its CONTENT: shrinking the action column to an icon collapsed the whole dialog. The width is now fixed (md:w-[880px]) and the action column keeps its own track, so the card cannot be resized by a change inside a row.

The state mark sits beside the name, inline. Two earlier shapes were wrong, and both looked plausible in the markup:

  • as a trailing child of the row it claimed a column of its own, so every agent name lost ~14px to a 6px dot;
  • absolute right-0 inside the flex-1 wrapper anchored it to the column's edge, which put it beside the VERSION cell — it read as a marker on the version.

inline-flex max-w-full hugging the text is what makes it a mark on the name, and it still truncates.

Column widths are taken from what each cell must SHOW. Both earlier guesses starved the version: the action column held 7rem for a single icon, and the version held 4rem — 64px cannot show a current → latest pair, so the number truncated while the action cell sat mostly empty. The tracks are now minmax(0,1fr) 7.5rem 1.75rem, measured as 239 / 120 / 28 px: the pair reads 0.100.0 → 0.101.0 in full, the button gets one 24px square, and the name keeps the slack.

The action cell is an icon, only when a newer version exists. A permanent "Update" label claims work that does not exist, and a copy chip for every vendor command turned the column into prose — so the label moved to aria-label/title and the row goes quiet otherwise. The glyph is lucide-download: the press installs something, and ArrowUpRight read as "open this elsewhere".

Two reported defects, and what each one actually was

"I updated, but the Update button is still there." The versions store skipped its own reload: loadVersions(false) returned early when loaded was already true, so the refresh an update asks for did nothing. refresh() is now a DISTINCT operation from reload(force):

  • refresh re-reads the rows — an update already knows the number it installed;
  • reload(true) also bypasses the server's registry cache, which costs one request per npm harness and belongs to the explicit Check button.

Measured after a real install: the row's Update disappeared and its version went to —, because a successful install also FORGETS the probe (the running adapter is still the previous process).

"An Update button appears where there is no newer version." Two causes, both fixed by removing a claim Kabmo cannot support:

  • the self branch drew an unconditional Update button, so a CLI that was already current still offered one. Kabmo cannot even READ a self-updating CLI's latest version (it lives with the vendor, not in a registry we query), so the row offers the vendor's command instead;
  • opencode2 was pointed at the opencode-ai package, whose 1.19.5 was compared against the preview binary's v0.0.0-beta-18743. Measured: opencode2 is a SEPARATE binary on its own beta line, so that comparison was fabricated on every refresh. It now reads own with no package and no action.

"Harnesses I never installed show an Update." The versions route reported kind, command and latest for every harness in the CATALOG, not for the ones on this machine. A row now carries installed (the launch command resolves), and an absent harness gets kind: null, latest: null, command: null and a note that says "Not installed on this machine — nothing to update". Measured on this install: six catalog entries have no action at all now.

About: the update path each agent owns

The card now carries Versions below the two panes: one row per harness — running version, and the action that moves it. Three kinds, and the kind decides what the row may say:

Kind Meaning Row shows
npm published on npm; the number IS the install target current → latest + a download icon
self the CLI updates itself (opencode upgrade, cmd update) the command, copyable — Kabmo must not install behind the vendor's launcher
own a vendor installer owns it (agy, cursor-agent) the command; the route REFUSES to run it

A row shows the CLI's version, and the adapter's beside it. claude --version answers 2.1.318 (Claude Code) while the ACP adapter answers 0.101.0 — two real numbers for two real things. Reporting only the adapter read as "why is my 2.x showing 0.100?", so the row leads with the CLI's number (read from its own --version, cached 10 minutes) and states adapter 0.100.0 → 0.101.0 underneath.

Two shapes were wrong first, both from adding a FOURTH grid child: the row shifted one track and the action button fell onto its own line. The adapter note belongs inside the version cell.

The arrow may only point between the SAME number line. With the CLI's 2.1.318 leading, the package in latest is the ADAPTER's — 2.1.318 → 0.101.0 is a fabricated comparison. The pair is shown on the adapter's own line instead.

The package must be the one the probe reports. The first table pointed claude at @anthropic-ai/claude-code while the probe reports @agentclientprotocol/claude-agent-acp — measured as "0.100.0 → 2.1.318" with an Update button, a comparison across two unrelated number lines. Numbers that look comparable but are not are worse than a dash.

An adapter is TWO installs, and one press moves only the halves that are behind

claude is not one package: it is the npm ACP adapter (@agentclientprotocol/claude-agent-acp, the number initialize reports) sitting on top of the claude CLI (its own --version, its own claude update). The two move independently — measured on this machine: adapter 0.100.0 under CLI 2.1.318 — so the route reports them separately and the update decides per part:

  • agent — the adapter's probe version and its package's latest;
  • cli — the CLI's --version and the latest of its own npm package, which the facts table names (cli.pkg). Without that package the CLI line can only report what is installed, because Kabmo has no registry number to compare — and the planner then never plans it. Only claude carries both (claude update plus @anthropic-ai/claude-code); codex and pi name no CLI updater, so their CLI line is report-only.

planHarnessUpdate (src/shared/lib/harness/update-plan.ts) is the decision, kept pure so it can be tested without spawning:

State Commands run
both behind npm install -g <adapter>@<latest> then claude update
only the CLI behind claude update
only the adapter behind the npm install alone
neither nothing — the answer is "already up to date"

The first shape ran BOTH unconditionally, which reinstalled an adapter that was already current and reported "updated to 0.101.0" about a version that never moved. A part whose latest version Kabmo cannot read is never planned: it cannot claim the part is behind. A row with no probe still plans the adapter install — a press there means "make this install current" — and the outcome says plainly that nothing could be compared instead of claiming it is current.

updateAvailable on the row is the UNION of the parts, so the button appears when either half can move; the accessible name names each part and its target (Update claude to adapter 0.102.0 + Claude Code 2.1.400), because one press running two installs must not read as one. The action icon is a download (lucide-download); it used to be ArrowUpRight, which reads as "open this elsewhere" next to a version number.

After a successful run the cached probe AND the cached CLI --version are forgotten (forgetProbe, forgetCliVersion), and the server probes the harness again by itself — otherwise the row keeps quoting the pre-update number until the reader opens Settings and presses Check status, which is what "updated" next to the OLD version looked like. Forgetting alone was the bug: it only dropped the stale answer.

The re-probe is probeWithConfig (the same call the boot pass uses, so the user's command/env override is honoured), and it is NOT awaited by the install's report — it spawns an agent that may take a minute. So the record carries probe: 'pending' and the dialog's poll (and the queue ticker) keep going on jobMoving until it turns 'done'; the client then drops the cached version rows (invalidateHarnessVersions) and the row reads the new number. A probe that fails, or a run that failed, still writes 'done'/null rather than leaving the row polling forever, and a successful probe names what it found in the record's message (— it now reports 0.103.0) — a version claimed only because the agent answered it. A probe left pending by a server that died mid-flight is kicked again by the next pass. Opening About also re-reads the rows without forcing the registry, because a run may have settled while the card was closed.

A CLI part with no number must not hide the adapter's. The row leads with the CLI only when its --version read SUCCEEDED. Carrying the empty part as the lead rendered — over a number the probe had already reported — measured on zcode (adapter 0.82.3 probed while no zcode runtime was on PATH) and claude (claude --version answered claude native binary not installed while the adapter answered 0.100.0). The part that has a number leads; the adapter … line is drawn only when BOTH numbers exist and differ.

npm i -g writes PATH; a pinned npx launch never reads it. The launch table starts claude, codex, pi and zcode as npx -y pkg@x.y.z, while the update installs the package globally. Measured: global @agentclientprotocol/claude-agent-acp was 0.101.0 while every launch requested 0.100.0, so the press reported success and the row stayed behind forever. A successful adapter install now repoints the harness's command at the binary the install wrote (facts.agentBin: claude-agent-acp, codex-acp, pi-acp, zcode-acp-server) unless the user already configured a command of their own. repointAdapterLaunch is the pure decision; the route only does the I/O.

The update runs in a BACKGROUND worker, because a killed npm install -g is a corrupt install. The route used to hold the POST open and run every step inside it. Three properties of that shape were measured failure modes:

  • the request was the run's lifetime. Closing About or reloading the page did not stop it, but a bun --hot reload or a server restart dropped the only record of it, so the dialog came back showing nothing while npm was still writing.
  • the five-minute child timeout killed the installer mid-write. A 147 MB native package measured 33 s on this machine's link and 67 s for the full npm i -g; a slower link crosses five minutes, and SIGTERM there leaves a half-replaced package tree — the corruption the press was blamed for.
  • nothing serialized two presses. The old route had no single-flight at all: a reload re-enabled the button (the console's "in flight" flag is JavaScript), and two npm install -g over the same prefix is the classic way an npm tree is destroyed.

So one press now spawns a detached worker (src/server/lib/harness/update-worker.ts) that owns the steps and writes a record the server reads. One install at a time, but a second harness is QUEUED rather than refused — see below.

File Role
<data>/run/harness-update.<id>.spec.json what to run: the planned argv, from planHarnessUpdate
<data>/run/harness-update.<id>.json that harness's record: steps + states, streamed output, pid, queuedAt, finishedAt, ok, message
<data>/run/harness-update.lock flock, held for the run — the kernel releases it if the worker dies. ONE lock for every harness, because the installs share the global npm prefix
  • POST /api/harness/update answers 202 {started, queued, job} in milliseconds. A second press for the SAME harness is a 409 naming its record; a press for a DIFFERENT harness is 202 with queued: true, and the record carries queuedAt instead of a pid. The decision is read from disk, so a second tab and a second server instance agree.
  • GET /api/harness/update/status answers {jobs} — one record per harness, an empty array for "nothing ever ran" (never a 404). It runs the same pass the ticker runs: settle a run that died, apply the post-install side effects once (forgetProbe, forgetCliVersion, the launch-line repoint, applied: true as the marker), then start the oldest WAITING record when nothing is installing.
  • update-queue.server.ts owns the queue and its clock. The ticker (2 s, globalThis-anchored, unref'd) exists only while a record is unfinished, so a queued run starts with the About card CLOSED and after a server restart (runAfterListenTasks pumps once at boot). Every read-decide-write over the records goes through one promise chain — two presses arriving together are one decision, not two "nothing is running" reads that both spawn.
  • A QUEUED record is never "dead". jobQueued is finishedAt: null && pid: null && queuedAt != null; the dead-run settlement skips it, because nothing was ever spawned for it. The worker clears queuedAt when it takes the record over.
  • The worker's kill bound is 30 minutes PER STEP, not five for the whole run, and it stops at the first failure. Output is appended as it arrives (throttled to 400 ms), so the dialog can name the step it is on (adapter, then Claude Code).
  • A record whose pid is gone is settled by the next read, not polled forever: finishedAt is written with ok: false and the message says the install may still have completed, because a dead reporter is not proof the command failed. The first 15 s after startedAt are exempt — that is the window between the record and the worker's pid handshake.
  • A settled run is not necessarily done: probe: 'pending' keeps both the ticker and the dialog's poll alive until the post-install probe answers (see the paragraph above), so jobMoving — not finishedAt alone — is what "keep following" means.
  • The rows show it: the installing row says Installing <step>…, the waiting row says Queued — starts when the install running now finishes, both keep View log for their OWN record, and pressing a row that is waiting is disabled rather than a second refusal (measured in Chromium: both lines on screen at once).

The install passes --allow-scripts=<package>, per package. npm 11 blocks lifecycle scripts by default, and @anthropic-ai/claude-code needs its postinstall to unpack the native binary — measured on this machine: bin/claude.exe was left as a 500-byte stub printing Error: claude native binary not installed., and claude update then failed with update_apply_native_binary_missing (recorded in ~/.claude/.last-update-result.json). Blanket script execution is not the fix; the flag names the one package whose vendor scripts this install is for.

Pinned by update-job-store.test.ts (atomic replace, a foreign JSON file reads as "no job", live pid vs dead pid, the start grace, a queued record neither in flight nor dead, and a settled run left alone), update-queue.test.ts (the refusal is per harness; a press while another installs writes a waiting record and starts nothing; the oldest waiting record goes next; the waiting run is handed to a real worker once the run ahead settles — the worker is detached, so its own record is the only way to observe it), update-worker.test.ts (runs the real worker in a child process: every step in order, the first failure ends the run, a held lock refuses the second install), update.test.ts (the refusals: unknown harness, vendor-managed, same-harness in flight, same-harness already queued, and the two-record status payload) and use-harness-update.test.ts (a 202 starts following, a second harness is accepted as queued and BOTH settles are reported once each, a 409 is a refusal, an in-flight run is adopted on open, a finished record is history).

The probe's agent version is not always the package version. dsh answers deepseek-harness-acp 0.0.1 from initialize while dsh --version is 0.2.2-rc.1. Comparing 0.0.1 against @deepseek-ai/dsh 0.2.2 planned an install of the version already on disk on every press. The CLI is the part that carries the package and the comparison; the agent line is report-only. An npm CLI with no vendor updater now plans npm install -g <cli.pkg>@<latest>.

"Installed" is the same question the catalog asks. The versions read used to resolve the build's launch table directly, so it called a zcode with no runtime installed and refused a harness whose binary is only reachable through its configured launch line. It now uses commandAvailable (user command + the bridge's required runtime), which is the rule the spawn and the status card use.

A dash is a real answer. updateAvailable needs BOTH numbers; one missing shows — with the reason, never "up to date". A row with no probe has no running version, and claiming otherwise would be fabricating a fact.

An install FORGETS the probe (forgetProbe): measured after a real npm install -g, the row still read 0.100.0 while npm had 0.101.0 on disk, because the running adapter was the previous process. The message says so — "check its status to read the new version".

Routes: GET /api/harness/versions?force=1 (one registry read per npm harness, cached 10 min), POST /api/harness/update (starts the background job, 202), and GET /api/harness/update/status (the job record). All three are registered as their OWN static paths, never under a /api/harness/:id parameter route.

Layout, measured: the table is three columns and at 260px the label collapsed to nothing while installer commands ran past the card — so it sits at the card's FULL width below the panes, scrolls inside its own section, and the card grew to min(92vh, 980px) / 760px wide. max-w utilities silently did not apply on a stale build for one round of checks; the class was present in the stylesheet and the browser had an older sheet — restart the server after bun run build before trusting a layout measurement.

A probe is stored on DISK, not only in memory

harness_probes (one row per harness) holds each probe; the Map on globalThis is only the fast layer in front of it.

Memory alone was a reported bug: press Check status, watch the card turn ready, restart Kabmo — or let bun --hot reload during development, which is every edit — and every harness read not probed again. A probe is a fact about the installed binary, not about the process that asked, so the record belongs on disk. The spawn had the same symptom one layer down: it resolves a harness's configured default model against the probed model list, and after a restart that list was empty, so the default silently fell through to the agent's own preference.

probedAt AGES a probe; it must not DELETE it. A row older than PROBE_TTL_MS (30 min) used to be read as absent, which reproduced the same reported bug by a second route: probe a harness, come back an hour later, and the card said not probed while harness_probes still held the answer. Measured on a cold process against the real database — omp-acp at 17 minutes answered, claude at 61 minutes read as absent — so "re-probe after every restart" was still the user's experience even though the row had survived the restart.

A stored record is now always returned and carries stale: true once it is past the TTL. The card shows the answer WITH its age (ready (aged), "checked 1h ago · re-check for a current version") instead of forgetting it.

The two gates differ on purpose, and that split is the point:

  • showing an old answer is honest, so the catalog returns it;
  • acting on one is not, so harnessProbeModels — the read the SPAWN uses to resolve a configured default model — still refuses a record past the TTL. A model the agent dropped in the meantime would fail at the first prompt.

The real invalidators are the ones that change what was measured: a launch line or env edit (forgetProbe via probeInvalidatedBy) and an install (routes/harness/update.ts).

Pinned by probe-cache.server.test.ts, whose cases empty the memory map to simulate a restart (the only thing a restart changes): the record survives, the catalog is read back in one call, the spawn still finds its models, forgetProbe really deletes, an aged record is returned and labelled, an aged record is NOT used to pick a spawn model, and a re-probe replaces rather than piles up.

opencode refuses session/new until its plugins activate — retry the PROCESS

opencode 2.x activates "Location plugins" asynchronously per directory and guards every request that needs them with a HARD five-second wait. Measured on 2.2.5 against a real config: the first session/new answered at +6 s with Internal error: Internal service failure: {"errorName":"ServiceUnavailableError"} (a 5 s gate that expired just before a 6 s request timeout), plugin installs finished at ~30 s and 72–82 s, and the SAME process then answered a real session. The probe read that first refusal as final, so the card showed opencode blocked while the agent was still booting — and the composer could not start it either.

newSessionAfterActivation (acp/activation.ts) retries on that error name alone, up to 150 s (headroom over the measured 82 s), sleeping 3 s between attempts. Three properties are deliberate:

  • the same process. Activation is per-process state, so the retry re-sends session/new to the running agent. Respawning would restart the clock.
  • opencode only. Every other harness's first refusal (Authentication required) is final; retrying would hide it behind a two-minute wait.
  • bounded, and it says why. A plugin that never settles ends in the agent's own words plus plugin activation did not finish within 150s, instead of a bare opaque error.

Both owners of session/new go through it: probeHarness and handshakeAcpSession (including its load path). Pinned by activation.test.ts; measured end to end against a stub ACP agent that emits the real error frame — two refusals, then ses_stub after three attempts — and against a real opencode 2.2.5 process (89 models probed in 1.3 s once activation was warm).

Every RESTART re-checks the harnesses that are ON

startHarnessAutoProbe() runs from runAfterListenTasks (lifecycle/after-listen.ts), after the listener is up. It reads the roster (omp_harness_disabled), keeps the switchable entries the user has not hidden, drops anything whose launch command is not resolvable, and probes the rest one at a time, writing each answer through rememberProbe.

Measured on a mocked boot with a temp data dir: the log line [harness] probed on boot: claude, codex, pi, zcode appears after listening on …, without delaying the listener. The pass is not awaited on purpose — a probe can take a minute (an agent that has to authenticate, a wrapper that resolves a container) and boot must not wait for it.

The guard is the PID on globalThis, not a module flag. bun --hot re-evaluates the entry, and probing spawns agents: without the guard every edit during development would start one process per enabled harness. A real restart is a new PID and therefore runs the pass again, which is the requirement. The built-in omp-rpc is skipped because there is no agent to spawn, and a missing binary is skipped for the same measured reason as the toggle route — the card already says "not installed", and spawning it can only repeat that fact.

Pinned by auto-probe.server.test.ts: a switched-off harness and the built-in transport never reach the availability check, an unresolvable command is skipped, every target's answer is stored, and one failing probe does not stop the pass.

Availability is a lookup over the REPAIRED PATH, not Bun.which

A login-entry launch hands the server a minimal PATH. Measured on this machine: ~/Library/LaunchAgents/dev.kabmo.tray.plist carries no EnvironmentVariables, so launchctl print gui/$UID/dev.kabmo.tray reports default environment PATH => /usr/bin:/bin:/usr/sbin:/sbin. Under that PATH Bun.which('npx') and Bun.which('omp') both answer null while /opt/homebrew/bin/npx and ~/.bun/bin/omp are installed — so the first boot after login logged [harness] probed on boot: omp-acp (omp survived only through resolveOmpBin's own fallback list) and every npx-launched harness read not installed. Starting Kabmo from a terminal inherited the shell's PATH and probed the whole roster; a restart spawned BY the launchd-started server inherited the same minimal PATH and did not repair it.

The spawn side was already repaired (withToolchainPath in the ACP stdio transport), which is why "not installed" and "runs fine" could both be true. The resolution side now uses the same repair: whichOnToolchainPath (src/server/lib/fs/toolchain-path.ts) is the one lookup commandAvailable, harnessRequirementMet/resolvable, resolveOmpBin, the update queue's agent check and cliVersion all use. cliVersion executes the RESOLVED absolute path, because a bare name that passes the check still fails the spawn under a minimal PATH. Verified end to end: env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin bun src/cli/kabmo.js serve --prod logged [harness] probed on boot: omp-acp, claude, codex, opencode, dsh, antigravity, pi, zcode, jcode. Pinned by toolchain-path.test.ts (a binary that exists only in ~/.bun/bin is found while the inherited PATH cannot see it).

Probing spawns an agent, so it never happens on a page load

GET /api/harness answers from the cache (30 min TTL before a record is labelled stale, memory on globalThis over the disk row for the bun --hot reason); ?probe=<id> spawns exactly one, switching an agent ON does so when its launch command is resolvable, and the server's own boot pass does the whole ON roster once per process (previous section). The page has an explicit Check status button, which is also what makes the capability rows honest: they render FROM the probe, never from a hardcoded table.


One settings PAGE per harness, and a SWITCH that decides the roster

The sidebar's HARNESSES group holds an overview (harness-index) followed by one entry per agent. Ids are DYNAMIC — harness:claude, from shared/lib/harness/menu.ts — not twelve more members of the SettingsCategoryId union: the catalog decides which agents exist, and a union member per adapter would need a build-time edit for every agent added at runtime. The union accepts `harness:${string}` for that reason.

A single-harness page renders the SAME card the overview draws, with HarnessSettings only={id}. A second renderer for one agent is how the two views start disagreeing about what that agent can do.

The overview is a ROSTER, not twelve cards. It used to be one full card per agent — capabilities, config form, provider panel each — which turned "which agents do I run here?" into a page you scroll. It is now one row per agent with a switch, its live status, a Check button when it is on, and a link to its page.

omp_harness_disabled (one app_settings row) holds the SWITCHED-OFF ids:

  • the DISABLED list is stored, not the enabled one. An adapter added by a later Kabmo update must arrive ON. Storing "what the user had enabled" would freeze the roster on the day they first opened Settings, and a new agent would silently never appear.
  • an empty list is the default, so the row is DELETED when nothing is off — same rule as an all-empty harness config.
  • the built-in transport has no switch: omp over RPC is the path this app IS, and a build with it off could run no chat. Refused with a 400, not silently ignored.
  • a switched-off agent leaves the DRAWER and the composer's model PICKER, but not the All Harnesses page — that page always lists every agent, because it is the only place one can be switched back on. It also keeps its catalog entry, since a session row must still say which transport ran it.
  • the agent owning an open chat is never removed from the picker, so an existing conversation can still name the harness that produced it (pickerHarnesses).

Switching ON is a roster decision and ALWAYS succeeds — including for an agent that is not installed. The user may want the tab present before installing the binary; refusing made the switch look broken (reported). The probe is therefore a BONUS with two guards: it runs only when the launch command is actually resolvable (commandAvailable — no spawn for a missing binary), and a failure for any other reason is caught so it cannot undo a roster write the database already holds. The response says probed: false when nothing was measured, so the UI can tell "on, not checked" from "on, and here is its answer".

Pinned by menu.test.ts (the id round-trip, the overview first, no page for the built-in transport, and every menu entry present in SETTINGS_CATEGORIES), groups.test.tsx (a switched-off harness has no drawer row and comes back when re-enabled, while its neighbours stay), enabled.test.ts / enabled.server.test.ts (the stored list, the retired-id drop, the built-in refusal, deletion when empty), toggle.test.ts (enable succeeds with the binary absent and spawns nothing), and harness-models.test.ts (pickerHarnesses).

Providers: WHERE each agent keeps them, measured

shared/lib/harness/provider-facts.ts is the table, and it is MEASURED against each vendor's own reference and, where possible, the installed binary:

Harness File Pointer Format
omp / omp-acp ~/.omp/agent/models.yml providers YAML
opencode and opencode2 $XDG_CONFIG_HOME/opencode/opencode.json provider JSON
codex ~/.codex/config.toml model_providers TOML
pi ~/.pi/agent/models.json providers JSON
kimi ~/.kimi-code/config.toml (kimi-code; KIMI_CODE_HOME moves it) providers + models TOML
qwen ~/.qwen/settings.json modelProviders JSON (array per protocol)
command-code ~/.commandcode/providers.json providers agent-managed, read-only
zcode ~/.zcode/v2/provider_config.json (personal rules; config.json is the app's legacy map and is never written) config.providerConfigRules.providerRules + config.modelConfigRules JSON rules, writable
minimax mcode's own BYOK store — agent-managed, read-only
claude / antigravity environment — ANTHROPIC_BASE_URL / GOOGLE_GEMINI_BASE_URL

The first version of this table GUESSED and was wrong three times, which is why the corrections are pinned by provider-facts.test.ts:

  • opencode2 reads the same opencode.json as 1.x — verified by writing a provider and watching both binaries list it. That entry is now GONE rather than merged: the preview became a shim for opencode, so there is one binary and one tab.
  • codex HAS a registry ([model_providers.<id>]), so calling it "no registry" sent the reader to the wrong page.
  • pi, kimi and qwen each have one, in three different formats.

Two formats store a VARIABLE NAME, never the secret: codex's env_key and qwen's envKey. The form says so, and the writer never puts a key in those files.

A dialect the target cannot speak is REFUSED. codex has OpenAI's two wire formats only, so importing an Anthropic endpoint throws with the reason instead of writing wire_api = "chat" at a gateway that never agreed to that protocol — measured on a real import, where the mislabelled entry would have failed the first request.

ZCode's registry is a RULE GRAPH, not a map (provider-zcode.server.ts). 3.12+ writes user-added providers to ~/.zcode/v2/provider_config.json; the legacy config.json map stopped syncing and belongs to the app, so Kabmo never rewrites it. Two measured consequences: a provider rule alone is INVISIBLE (the bridge builds its dropdown from modelConfigRules), so the writer emits one model rule per id; and a new model rule WITHOUT an explicit reasoning map inherits a catalog family rule — a qwen3-… id got enable_thinking + thinking + reasoning_effort and a Kenari gateway answered every turn with 400. The writer emits the catalog's generic { "reasoningLevel": { "values": ["disabled", "enabled"], "map": "{}" } }, and the same prompt then reached the gateway with no reasoning parameters and returned ok. The write takes a .kabmo.lock lease because the runtime's own writer locks a DIRECTORY at <file>.lock; a file there would look like a lock it must reclaim. A chat also needs a ZCode runtime — the desktop app, or zcode-app-cli on PATH (ZCODE_BIN for a custom install).

provider-write.server.ts is one writer per FORMAT, dispatched by the same table. Every format merges rather than rewrites (these files hold plugins, agents, MCP, approval policy), refuses an unparseable file untouched, keeps a stored credential and the user's own dialect on update, and writes 0600 because the file can hold a key.

Under bun test, a write outside KABMO_TEST_HOME is refused. That guard exists because a verification run of this feature wrote into the developer's real ~/.codex/config.toml, ~/.pi/agent/models.json, ~/.kimi/config.toml, ~/.qwen/settings.json and ~/.omp/agent/models.yml — a script with HOME reassigned was fine, while a real server started for a browser check was not. The damage was reverted by removing exactly the injected entries; the guard is at the one place that writes.

Add and import a provider per harness

Two actions on one landing path (routes/harness/import-action.ts → applyProvider):

Action Where the endpoint comes from Where the key comes from
import another agent's registry row the SOURCE file, read in the request that writes
add typed into the card typed into the card

Everything after that is shared, so "copy" and "type" cannot drift:

  1. The endpoint is PROBED first (provider-probe.server.ts) — one unauthenticated request per protocol. An empty JSON body is enough because every one of these APIs rejects a body it cannot parse before it looks at a credential: /v1/messages → 400 invalid Anthropic request JSON, /v1/chat/completions → 400 invalid JSON: missing field model, /v1/responses → 400, /v1beta/models → 200 list. 404/405 and an HTML error page mean the route is absent. Measured on kenari.id: chat + responses + anthropic answer, the Gemini listing is a 404 HTML page.
  2. The protocol is chosen from the measurement, not the declaration. Measured: omp's models.yml calls kenari openai-completions, and the same host answers Anthropic Messages — which is the whole reason "import kenari from omp into Claude Code" works and writing its declared dialect there would fail every request.
  3. A protocol neither side has is REFUSED by name, including what the endpoint answered. A probe that reached the host is EVIDENCE: when it answers nothing the target speaks, the answer is no — an earlier version fell back to "the target has only one protocol, so use it" and would have written a Chat gateway into Responses-only codex.
  4. The write lands where that agent reads it: the registry (with its own dialect spelling) or, for an environment harness, the vendor variables at the host root — measured, ANTHROPIC_BASE_URL=https://kenari.id/v1 made Claude Code request /v1/v1/messages and answer an empty turn.

CUSTOM only, in both directions. shared/lib/models/provider/vendors.ts is the census (omp 18.3.0's KnownProvider plus each agent's reserved ids), the list filters with it and the writer refuses anyway: copying anthropic into codex writes an override of codex's OWN built-in provider instead of adding a gateway.

Per-provider credential variable names. codex's env_key and qwen's envKey hold a NAME. A fixed OPENAI_API_KEY meant two providers added to qwen both wrote it, so the second silently re-pointed the first at a different key; the name is now derived from the provider id (KENARI_ID_API_KEY) and the value is written into the harness env (or qwen's env block) — measured: two gateways, two names, two values.

A provider with no models SAYS so. Measured: omp serves zero rows from an entry with no models and no discovery, and prints no warning. The write answers with a note instead of a bare success, and the form's hint says empty ids are only for an endpoint override.

The display name survives. omp keys a provider by slug and prints the slug, so a card read ui-gateway after the form said "UI Gateway". The entry now carries name (accepted by omp), and both the harness reader and omp's own native reader prefer it.

The card lists what the agent already holds (configured, custom only). Without it an add that wrote correctly and one that silently wrote nothing rendered the same card; it is re-read from the server after a write, because the file is the only proof.

Which CONFIGURATION fields a harness gets, measured

The card used to draw the same six fields for every agent, and two of them were lies on most of them. The probe the card already reads answers it:

Harness probe.models values Providers Fields shown
omp-acp kenari/agnes-2-5-flash:free, … (221) kenari, kenari-jatis, aihub-brisnets-jatis launch, Provider, model, thinking, mode, env
claude default, opus, sonnet, haiku, claude-fable-5[1m] (5) none launch, model, env
codex (unauthenticated) none published none launch, model, env

shared/lib/harness/config-fields.ts is the rule, pure and probe-injected:

  • The Provider field exists only where the agent publishes provider/model selectors. claude publishes bare names, so its picker could never populate and its model list never narrowed by it. A provider already STORED keeps the field visible even with no probe — hiding a value the config holds is how a form silently rewrites it.
  • Thinking and mode appear only when the probe published a ladder. The old free-text fallback invited a value the agent rejects, and "Empty leaves the agent on its own effort" was shown on agents that have no such selector at all.
  • The Environment box speaks the agent's OWN variables. Claude Code gets ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL, plus one ANTHROPIC_DEFAULT_<FAMILY>_MODEL per picker alias (opus, sonnet, haiku, fable); Antigravity gets GOOGLE_GEMINI_BASE_URL / GEMINI_API_KEY. It used to hint GEMINI_API_KEY on a Claude Code card — an instruction that cannot work. A registry harness says where its providers actually live (.codex/config.toml), and cursor says the launch line is the whole surface.
  • An unpinned alias fails against a gateway. Measured with the SDK's own binary (2.1.318): --model sonnet against a gateway that lists claude-sonnet-5-5 still sends the vendor's id, and a gateway that does not serve it answers 400 model not found; with ANTHROPIC_DEFAULT_SONNET_MODEL=<gateway id> the same turn succeeds.
  • A gateway must accept a role: "system" entry in messages. Measured on Claude Code 2.1.316's captured request body: the Environment block travels as {"role":"system","content":"# Environment …"} inside messages, not in the top-level system array. A gateway that forwards that role to an upstream which only accepts user/assistant answers 400 the model's provider rejected the request on EVERY turn — measured on kenari: qwen3-8-27b:free refused it, agnes-2-5-flash:free answered 200. The model, not the env form, is the variable.
  • The launch hint names that agent's own install line, and the model placeholder is provider/model only where selectors are the shape.

Verified in the browser at 1440: claude renders launch / model / env with the ANTHROPIC names and no provider picker; omp-acp (probed, 221 models) renders launch / Provider (commandcode) / model / thinking ("7 levels") / mode ("2 modes") / env, plus its registry panel.

Per-harness config: provider, defaults, launch line, env

Each ACP card carries a form (harness-settings/ConfigForm.tsx) with six fields, all optional — empty means the build's table, stated in the field's own hint rather than implied:

Field What it is actually for
Launch command The binary is not on PATH, or needs a wrapper that signs in first. Quoted paths survive (/Users/me/My Tools/agy acp)
Provider Which of the agent's providers a new chat starts on. ACP publishes each model as provider/model, so this is a FILTER over that list
Default model / thinking / mode The selectors a spawn writes after session/new, so the first prompt does not run on whatever the agent prefers
Environment KEY=VALUE lines. This is the provider/credential switch an ACP agent actually honours (GEMINI_API_KEY, GOOGLE_GEMINI_BASE_URL, CODEX_PATH)

Storage is one app_settings key per harness (omp_harness_config:<id>), not a blob: a blob would let two instances writing different harnesses clobber each other, the same defect session_ui_state avoids by keying on the session. Saving an all-empty form DELETES the row, so a reset leaves nothing stale behind.

A default model only applies if the agent still lists it. resolveDefaultModel matches against what the probe published, so a model the agent dropped falls through to the provider's first model rather than being written and failing the first prompt. command and env overrides are what make this a real provider setting: there is no Kabmo-side model routing for an ACP agent.

Only a changed command or env invalidates the cached probe. probeInvalidatedBy is the single rule, used by the route and its test. The first version dropped the probe on EVERY save, which collapsed the provider/model pickers back into free-text fields the moment a default was stored — measured: probe command-code (96 models, dropdown populated), press Save, dropdowns gone.

Stop: a notification nobody answers, and the turn that must not race it

Three separate defects made the Stop button do nothing on an ACP harness, and each one was invisible in a different way:

  1. session/cancel was never sent. It is a JSON-RPC notification, so nothing awaits it and a failure to write it is silent. AcpProcess.cancel passed this.notify — a plain method — into verbs.cancel, which loses the receiver: the throw was undefined is not an object (evaluating 'this.write') and the route answered 500 while the turn kept running. notify is now an arrow field, like call beside it, and client.test.ts asserts the frame on a real pipe (an echoing child) rather than a stubbed write, which would have hidden exactly this.
  2. A failed abort counted as a stop. stopAgentSession returned true for any HTTP answer, so the 500 above suppressed the force_reset escalation it exists to trigger. It now requires res.ok; a failed or dropped request escalates.
  3. The turn's flags were cleared by hand, and only half of them. The abort branch set isPromptRunning = false and left isStreaming up, so a session whose agent never answered stayed "already processing" forever. cancelTurn now closes the turn itself (finishTurn({stopReason:'cancelled'})): the open message is flushed, abandoned tool cards are failed, and the terminal agent_end is emitted once — by that close, not by a hand-built frame beside it.

omp does answer the cancel (measured with a raw stdio client: session/cancel 4.3 s into a turn → {"stopReason":"cancelled"} immediately). What is easy to get wrong afterwards is the next turn: ACP has no queue, and a second session/prompt while one is open cancels the first. Kabmo sent it 1 s after the stop and the agent persisted the new user row and never answered it — every later send then failed as "already processing". Turns are now chained behind the outstanding request, and abandonPrompt settles it locally, because the agent's own reply is not something the next turn can wait for.

Frames are also dropped when no turn is open (openTurn === null): after a stop, omp keeps emitting chunks for work nobody is watching, and forwarding them reopened the assistant message the client had already finalized.

Verified end to end against a scripted ACP agent over a real pipe: turn 1 end_turn; stop mid-turn → exactly one terminal cancelled frame, isRunning() false, zero frames afterwards; turn 3 streams normally. A deliberate destroyAndWait no longer reports itself as "the agent exited" (closing), since force_reset is now the user-requested path.

ACP messageId is OPTIONAL — a missing id must not become one row per chunk

ACP v1 makes messageId optional on agent_message_chunk, and antigravity 1.5.3 sends none: every chunk was exactly {sessionUpdate, content} (measured on a 500-word answer — 25 chunks over ~10 s, none with an id).

AcpFrameMapper.snapshot() only wrote id when the agent supplied one. With no id, toChatMessage minted msg-<Date.now()>-ai per frame, so the client's onMessageUpdate found no existing row and appended: chunk 2, chunk 3 … and the final message_end each became a separate bubble. One assistant turn rendered as N duplicate rows that grew in length, and the answer looked like it was not streaming because only the first frame ever filled the placeholder.

The mapper now synthesizes one identity per turn (acp-<uuid>) the first time a snapshot is built, including a tool_call that precedes the first text chunk. reset() and closeMessage() clear it, so the next turn gets a fresh id. The same id reaches message_end, which is what makes the client replace the streamed row in place instead of appending the completed answer beside it.

Pinned by frames.test.ts (id-less chunks share one id, message_end carries it, a tool-first turn shares it, reset() gives a new one). A short answer still arrives in a burst because agy finishes generating it first; that is the agent's cadence, not a transport defect.

The client side of ACP: advertise only what Kabmo answers

initialize used to send clientCapabilities: {}. That is legal, but it told every agent that this client could not read or write a file, so an adapter that routes edits through the client had to refuse them. The advertisement is now client-capabilities.ts:

Advertised Why
fs.readTextFile / fs.writeTextFile client-fs.ts serves both against the session's workspace
session.notices AcpFrameMapper already renders notice, and the turn gate was moved so a notice sent between turns is not dropped

Everything else is deliberately absent, and each omission is a promise Kabmo cannot keep: terminal (no bridge surfaces a terminal's live output in the timeline), elicitation (no form/URL dialog), auth.terminal (Kabmo does not reproduce the agent's launch line interactively), session.configOptions.boolean (the selector UI is select-only) and session.compaction (no renderer). An advertised capability the client cannot serve parks a turn on a call nobody answers — the same failure the explicit refusal exists to prevent.

Two details are load-bearing:

  • Containment, not string prefixes. Every fs path must be absolute and must survive pathHolds(session.cwd, path), which canonicalizes symlinks and the nearest existing ancestor. A symlink inside the workspace that points at /etc/hosts is outside and gets -32602; a missing file gets -32002. line/limit are 1-based, and a write creates the file and its parents.
  • A refusal carries the spec's code. An unimplemented method answers -32601, not -32603: an agent decides from the code whether to fall back.

assertProtocolVersion accepts 1 and 2 and refuses anything else by name; the connection is not parsed as v1 when the peer says v3.

Verified with a scripted ACP agent over a real pipe (the agent echoed the received clientCapabilities, then read a file through fs/read_text_file and got its contents back), and with a real omp 18.18.6 initialize + session/new against the new advertisement.

What every v1 page means on this transport

The protocol is one document per surface. This is the state of each, so a future change knows whether it is filling a hole or re-deciding a choice:

Page State
Overview / Transports stdio, newline-delimited JSON-RPC. Non-JSON stdout lines are skipped (measured: opencode acp prints plugin-boot logs first).
Initialization Major version checked; client advertises fs + session.notices, nothing it cannot answer.
Authentication authMethods are read into the probe (the blocked card names them), but there is no login control yet; authenticate / logout are not called.
Session Setup new, load and resume are capability-gated. session/close exists but is not called (Kabmo kills the process); additionalDirectories, systemPrompt and MCP servers are never sent.
Session List listAllSessions follows nextCursor; Settings → Harnesses → Import sessions copies the agent's own history into harness_sessions, and the Auto import switch runs the same pass at boot and every 15 minutes. The request carries NO cwd (codex's cwd-filtered list exits the adapter 3/3 before answering, on 2.5.0 and 2.7.0), so rows are filed locally by their own cwd.
Session Delete session/delete runs for every recorded harness — on the live child when there is one, else on one fresh child reused for the whole batch. dsh advertises no delete (0.2.2-rc.1: list only), so its own <DSH_HOME>/sessions/<project>/<id>/ directory is removed. A failure refuses the delete (502 agent_session_not_removed) instead of leaving a row that returns on the next import.
Prompt Turn Chunks, usage and notices; stop reasons forwarded. Compaction updates are not advertised, so a spec-compliant agent falls back to a normal message.
Content Prompts carry text and, when the agent advertised image, images. Tool output and chunks expose embedded-resource text and name resource links. Audio is never sent.
Tool Calls tool_call_update merges as a PATCH; diff blocks become the Edit panel; permission requests park and are answered (or cancelled on Stop). Embedded terminal content is not rendered because terminals are not advertised.
Elicitation Not advertised: no form/URL dialog exists, and advertising it would park the agent on a question nobody draws.
File System Both methods served inside the session root.
Cancellation session/cancel answers every parked approval with cancelled; $/cancel_request answers the named one; an agent's -32800 answer closes the turn as cancelled rather than as an error.
Terminals Not advertised: there is no bridge from an ACP terminal to the timeline, and advertising one would route shell work into a terminal the user cannot see.
Agent Plan plan entries feed the Todos topic through buildAcpTodos.
Session Modes A mode config selector when published; otherwise the legacy modes list is synthesized into the same selector and writes go to session/set_mode. The composer offers the whole ladder in a dropdown (except omp-acp, which keeps the Plan toggle for its default/plan pair); a pick POSTs set_mode, flips optimistically, rolls back on refusal, and mode_changed/config_changed re-reads the authoritative value. An agent-initiated change also updates the persisted plan flag.
Session Config Options Select options are adopted as published. boolean is not advertised because the selector UI is select-only, and an agent must not send a type the client cannot render.
Slash Commands available_commands_update feeds the composer's / pool; a command is sent as ordinary prompt text, exactly as the spec defines.
Extensibility _meta.steering is read at the result root; unknown methods answer -32601; unknown notifications are ignored.
Security Considerations fs paths are canonicalized and root-checked; agent-authored text is rendered through the app's existing Markdown surface; no agent-supplied URI is fetched.
Errors Codes survive as AcpRequestError; refusals to the agent use -32601, -32602, -32002, -32603.
Schema Only the fields Kabmo reads are typed (protocol.ts), deliberately, so an adapter's newest field is not a compile error.

v1 and v2 side by side: one internal model, an adapter at the boundary

Kabmo sends protocolVersion: 2 as its latest version, but the request also carries the v1 field names (clientCapabilities, clientInfo). Migration says a v1 agent reads a v2 request WITHOUT those fields and loses the client's file system support, so carrying both is what lets a v1 peer answer 1 and still see what it understands; a v2 peer ignores the v1 names as unknown fields. A strict v1 peer that rejects version 2 gets one clean v1 retry — allowed because the connection is still uninitialized — and no retry happens for a dead process or a timeout.

Internally the model stays v1-shaped; v2.ts translates at the process boundary:

  • initialize — role-agnostic info/capabilities become agentInfo/ agentCapabilities; object support markers become booleans; capabilities.session implies list/resume/close; session.delete and additionalDirectories keep their markers; authMethods.methodId becomes id. capabilities._meta is merged where steering is read.
  • session setup — configId/groupId become id/group; initial availableCommands are adopted; v2 restore calls session/resume and never session/load (removed in v2), keeping the chat's agent id.
  • updates — whole-message agent_message/agent_thought upserts and tool_call_content_chunk are applied to the same accumulator; v2's single tool_call_update creates on first sight; paused stays open and cancelled is final; plan_update feeds the same Todos topic; state_update goes to the turn machine instead of the mapper; terminal/compaction updates are ignored (no renderer).
  • prompt lifecycle — AcpTurns.completion = 'state': the session/prompt response only acknowledges insertion (messageId), and an idle state_update ends the turn. An idle stopReason: "error" becomes the failed outcome with the agent's message; -32800 before insertion is a failure, after insertion it cannot be returned. v2 does not infer failure from an idle without a stop reason, so the v1 "silent answer is a failure" verdict is gated to completion === 'response'.
  • permissions — the required title plus a tool_call/command subject are normalized into the v1 toolCall the approval queue and access tiers already understand.
  • config writes — session/set_config_option adds v2's required type: "id" | "boolean"; session/set_mode is never called on v2 because modes are config options there.
  • client APIs — v2 removed fs/* and terminal/*; the v2 advertisement is capabilities: {}, so nothing is promised that v2 does not define.

Verified with a scripted v2 agent over a real pipe: v2 negotiated, initial config/commands adopted, streaming message + tool + plan produced the same frame types as v1, and state_update idle closed the turn with end_turn. A real omp 18.18.6 still negotiates 1 through the same hybrid request and keeps session/load.

Deliberately outside this adapter, because the surface does not exist yet: elicitation (elicitation/create), auth/login/auth/logout (auth methods are normalized for the probe but no login control), Agent-owned terminal rendering (terminal_update/terminal_output_chunk are ignored), compaction rendering, and session/close (Kabmo kills the process). v2 background activity that keeps updating after idle is also dropped by the turn gate: Kabmo's timeline has no open message to attach it to, and pretending it were foreground would resurrect a finished turn. session/cancel answers every parked approval, including one v2 would keep open because it belongs to listed background work; the background list is not tracked.

Settings → Harnesses, in its own sidebar group

The page is one section per harness: the mark, the transport, the probed version, and the capability rows it actually published.

A card states the REAL status, never a bare blocked

shared/lib/harness/status.ts derives one of five states from facts the card already has, and the chip, the sentence under it and the disabled-reason on the button all read that single derivation:

State Chip Says
ready (probed) ready claude answered as version 0.100.0.
ready (built-in) built in Kabmo runs this transport itself — nothing to install or probe.
not-installed not installed cursor: cursor-agent was not found on PATH, so it cannot be launched. + the install line
needs-setup needs setup the AGENT's own refusal, quoted (Authentication required: …)
unprobed not probed … has not answered yet — press Check status …

The word blocked covered four of those at once while the fix differed in every one of them: install a package, run a login, press a button, do nothing. Two details are load-bearing and each was a wrong instruction before:

  • the sentence names the BINARY, not the harness id — minimax is launched by mcode and cursor by cursor-agent, so "minimax is not installed" sends the reader looking for a package that does not exist;
  • the install line belongs to not-installed only — telling a signed-out agent to install a package it already has is a wrong instruction.

Precedence is stated, not implied: a missing binary outranks a stale refusal (there is nothing to authenticate against with no binary on disk), and a refusal outranks "not probed" (something did answer). The state also drives SHAPE, not only colour: a filled dot, a slashed package, a warning circle or an empty ring, so a reader who cannot separate two low-contrast tones still sees a difference.

Pinned by status.test.ts — every state's words, the binary-name rule, the precedence, and the shipped defect as an assertion: no state may render the bare word blocked. What it deliberately does not do is duplicate omp's own settings — Providers, Models, Agent and Behavior stay omp-specific, and two write paths to one config file is the defect.

The sidebar files it under HARNESSES, a group of its own rather than a member of OMP. omp's group is one engine's own config (engine state, providers, agents, behavior, commands, MCP); this group holds OTHER agents entirely — a different transport, a different config file, one section per agent. Filed under OMP, the drawer read as "omp settings" followed by seven pages that are not omp.

SETTINGS_SECTIONS (src/shared/lib/settings/sections.ts) is the ONE list of groups, imported by both the section type and the render loop. It used to be written twice — the union and an array beside the drawer — so a group added to one and forgotten in the other rendered nothing under it: no error, no empty state, just every category filed there missing from the settings drawer.

Pinned by settings/groups.test.tsx: every category's group is drawn, the headings equal the declared order (one per non-empty group), and every declared category label is reachable — a count, because the bug this prevents dropped a whole group and a spot check on one category would have passed.


Importing an agent's own sessions

A chat that was born in a terminal has no harness_sessions row and no omp JSONL, so it cannot appear in the sidebar. Import sessions (Settings → Harnesses → one agent) asks the agent itself through session/list, writes one row per reported session, and emits sidebar-structure.

Measured rules:

  • No cwd on session/list. codex tears its app-server down before answering a cwd-filtered list (exit 0, 3/3 on 2.5.0; 2.7.0 fails without a cwd too). The rows carry cwd; Kabmo resolves each to a workspace folder and reports the rest as "outside your workspaces".
  • Both ids are the dedupe key. A resumed chat whose load forked keeps Kabmo's id in session_id and the agent's in agent_session_id; checking only session_id imported a second row for one conversation (measured).
  • The row is marked origin = 'imported'. That marker decides restore eligibility. It no longer exempts Delete: an imported chat is removed from the agent's own history too (see "Delete removes the AGENT's copy too"), because forgetting only Kabmo's row made the next import restore it.
  • The agent may shut down while listing. A first session/list has answered ACP agent exited (code 0) before any frame; the import retries once with a fresh process and never retries a real refusal (auth, launch).
  • codex exec sessions are invisible. The adapter's sourceKinds excludes exec; TUI (cli) and adapter-created (vscode) sessions are listed.

Automatic import: ON by default, switched OFF per harness

A spawn per installed harness on sidebar load is not a read — the same reason probing never runs there. The automatic pass therefore has its own clock and its own per-harness switch:

  • ON by default. The switch turns it OFF for one harness; the stored value is the EXCLUSION list (app_settings.harness_auto_import_disabled), so a harness added later arrives ON with no migration. A build from the first cut stored the ENABLED ids under harness_auto_import; that row is migrated once.
  • Switching it back ON imports once immediately. A switch whose effect appears a quarter-hour later reads as broken; the counts land beside it.
  • Boot, every 15 minutes, and when the sidebar is opened. The boot tick runs immediately AFTER the probe pass finishes: its cache is what says which agents answer list, and sequencing avoids two agents per harness competing. The sidebar route triggers a pass at most once every 30 s, so a terminal chat followed by a reload appears without waiting for the clock. One clock per PROCESS (globalThis), unref'd, with an in-flight guard so a slow pass cannot overlap the next.
  • A target must be: not switched off, roster on, launchable, and its cached probe must advertise list. A spawn that can only fail is not a discovery. omp-acp is skipped — it writes omp's JSONL, which the scan already lists.
  • Sequential, and one failed agent does not stop the others. The log names the harness and the agent's own error.
  • A session with no transcript is not imported, and not listed. An agent reports every session it CREATED, not the ones that were used: measured on this machine, 114 of opencode's 131 sessions held zero messages, and the sidebar drew them as New session - <timestamp> rows that open an empty chat. sessionsWithoutTranscript (lib/harness/session-transcript.server.ts) reads the store Kabmo can name — opencode's SQLite (message/session_message), zcode's SQLite (message), antigravity's per-conversation SQLite (steps), dsh's session.v4.jsonl.zstd, claude's project .jsonl, codex's rollout — and answers "provably empty" only for those. A non-empty file is not a transcript: dsh writes a header plus its setup events (permission/preset, sandbox/mode, approval/policy) before the first prompt, so the dsh check decompresses the zstd JSONL and looks for a turn/start or a message event — measured, every dsh session on this machine held those four lines and nothing else. A harness with no readable store (pi, qwen, minimax, grok, hermes, kimi, cursor, command-code, jcode) yields no verdict and its rows are kept: hiding a real chat is worse than listing an empty one. The same rule filters omp's own scan (messageCount > 0 — 208 of 1793 files on this machine carried a header and no message), and the import result reports the skipped count as empty.
  • The pass never DELETES rows: a terminal session removed in the agent's store stays in Kabmo until the user archives or deletes it. A DELETE writes a tombstone (deleted_sessions), and the pass skips every id in it — so a chat the user deleted does not return even when the agent still lists it.

Pinned by auto-import.server.test.ts (switch round-trip, built-in/omp-acp refusals, one failure does not stop the pass), session-transcript.server.test.ts (each store's empty/present verdict, and the no-verdict case), and the card's DOM test (the switch renders the server's state and names its harness; the manual button reports the counts).

Opening one: replay, then persist

The sidebar row is not a transcript. A v2 agent replays retained history only when session/resume carries replayFrom: { type: 'start' }; without it the open tab is empty. Measured on codex 0.169.0 through codex-acp@2.5.0: 8 frames (user message + chunk, assistant message + chunk, title, usage, idle) in 3.7 s, no duplicate thread.

Two gates dropped those frames and both were correct for a live turn:

  • the turn gate (acceptingFrames) has no open turn during a resume;
  • the mapper treats user_message as a receipt for a bubble the composer already drew, so every replayed question vanished.

AcpReplay opens a bounded window (closed by state_update: idle, or 1.5 s), buffers the frames, and AcpFrameMapper.setReplaying(true) materializes user turns. transcriptFromReplay reduces the last snapshot per message id into ChatMessageData, and the restore command persists it to chat_sessions once. Every later open is an ordinary read: no agent, no auth, no second replay.

A blocked probe no longer refuses a restore: codex answered "Authentication required" before login, and that stale record locked a chat that could already resume. The gate now ignores capabilities.blocked.

A child spawned SERVER-SIDE writes its own transcript

The restore path assumed every chat Kabmo spawned had a client-written transcript. An orchestration worker (or a CLI child) has no tab, so nothing wrote chat_sessions: measured on a real antigravity worker, the row was messages='[]', harness_sessions.origin='', session_relations.parent_session_id named the coordinator, and session_answers held the final report — the conversation existed only in the agent's store, and the open tab was empty.

Two halves fix it:

  • AcpTranscriptRecorder (lib/harness/acp/session-transcript.server.ts) is attached in startAcpSession and folds the frames the driver already receives (user_turn, message_*, tool_execution_*) into acp_transcripts. It hydrates from the newer of acp_transcripts and chat_sessions on a resume, merges by message id (a user turn by its text, because the composer's optimistic id is local to the tab), and writes chat_sessions only when its copy is AHEAD — so an open tab's richer row (attachment chips, notices) is never replaced. A restore session is skipped: it persists its own replay.
  • The loader reads acp_transcripts when chat_sessions has no assistant row, and the restore gate is now the LOCAL TRANSCRIPT, not origin: a spawned child with no answer is eligible for the same session/load replay an imported chat uses. A user-only row is a prompt whose tab closed, not a transcript.

Pinned by session-transcript.server.test.ts (prompt/answer, tool pairing, resume hydration, notice preservation), the loader's child cases in routes/chat/session.test.ts, and restoreEligible in routes/agent/harness-command.test.ts.

A session still open in Codex is READ from its rollout

session/resume on a Codex thread that another client owns (the TUI, the app, an IDE) answers thread_active_writer and starts nothing. That is the normal case right after using the terminal, and it left the imported chat empty.

codex/transcript.server.ts reads the rollout file (CODEX_HOME or ~/.codex/sessions/**/rollout-*.jsonl) for DISPLAY only: the sidebar row still comes from session/list. It drops Codex's own developer turns and the <environment_context> user turn, pairs function_call with its output, and returns the same ChatMessageData rows the timeline reads. The loader uses it only when the imported chat has no local transcript, and then it does not ask for a restore — so the conversation is visible while the TUI still holds the lock. Continuing still needs that client closed; the agent's own message says so.

v2 mcpServers are not v1's

A v2 peer validates the list strictly: every entry is tagged (type: 'stdio') and a stdio command must be ABSOLUTE. Kabmo sent the v1 shape, and both codex and claude answered Invalid params — no session at all, on every spawn/resume with an MCP server configured. toAcpV2McpServers converts after initialize (the first point the negotiated major is known), resolves a bare binary on the toolchain PATH, and skips an unresolvable server with a log line rather than failing the chat.


Reopening a chat: the resume path is per TRANSPORT

POST /api/agent/:id is Kabmo's one lazy-spawn path, and it used to have exactly one resume: the .jsonl locator. That is omp's store, so a chat on any other harness had no resume at all — measured on a claude chat after a restart, whose row was in the sidebar: both prompt and get_state answered {"error":"Session not found"}, because resolveSessionPathOr404 found no file to hand omp --resume.

resumeRecordedHarnessSession (routes/agent/command.ts) now reads the harness out of harness_sessions and respawns a non-omp chat on its OWN agent, passing the id the AGENT reported so session/load can restore the conversation. Measured after the fix, from a second instance (so nothing was live): the same prompt answered {"success":true,"data":{"agentInvoked":true}} and spawned @agentclientprotocol/claude-agent-acp as a child of that server.

Three rules the code owes:

  • an id no catalog harness claims spawns NOTHING. A retired adapter must not be guessed at from a stale row, so the old 404 stands.
  • an EMPTY agent_session_id means "the same as ours" (saveHarnessSession writes it blank in exactly that case, when the agent's id equals Kabmo's), so the row's own id is the value to send. Passing '' starts a FRESH agent session under this chat's id and throws the conversation away silently.
  • omp-acp is excluded even though ACP is what it speaks. It writes a session file, so the locator resumes it in place — same chat, same id, one row. session/load on omp FORKS (measured: a load for 01a1b49f-… answered id 01a1b4cc-…), and a forked id is a second record: a second sidebar row for one conversation, which is exactly what the merge rule prevents. The recorded mark is rewritten to omp-rpc on that path, which is truthful — RPC is then the transport that ran it.
  • a non-omp load forks too, and the record FOLLOWS the chat. Measured on a resumed claude chat: the agent answered 340f24a3-… for 5c5e776e-…, and the spawn's own record of that id drew an empty twin row beside the conversation. repointHarnessSession therefore moves the chat's row onto the agent's id and drops the twin — the chat keeps the id the tab, the transcript and the layout name, and the next session/load sends the id the agent actually resumed into.

A harness whose probe advertises neither session/load nor sessionCapabilities.resume is refused in words, because the only alternative is a fresh agent session under an old chat's id. When loadSession is absent but resume is present, the handshake calls session/resume instead: it replays nothing and creates nothing, so the chat keeps the agent id and only the config state the reply carries is adopted.

Pinned by the two cases in routes/agent/command.test.ts: a retired id keeps its 404 and spawns nothing, and a recorded non-omp chat reaches its OWN launch line (the failure names the configured command, not "Session not found").

Which mode toggles a harness may offer

The composer used to draw Plan and Goal on every chat. For a non-omp ACP agent that is a button whose only outcome is a refusal: there is no /kabmo-mode extension on the wire, and its own mode selector is the only place plan can live. Measured: press Plan on a claude chat and the extension prompt reached the MODEL as prose, which then refused the next mode command as "already processing".

modeAvailability (client/hooks/chat/timeline/modes.ts) is the pure rule, and it is injected with the two facts it needs:

Harness Plan Goal Why
omp-rpc shown shown omp carries the extension AND the RPC goal driver
omp-acp shown shown Plan is the agent's selector; Goal is Kabmo-owned with the ACP driver
another ACP agent that publishes a plan mode value shown shown applyHarnessMode maps Plan to the agent's own mode selector; Goal is Kabmo-owned
another ACP agent without one hidden shown nothing can express Plan; Goal needs no agent mode
unknown (no row, no spawn record, no pick yet) shown shown the row may simply not have arrived

The value comes from the CALLER, never re-derived: chat-timeline/index.tsx already holds useSessionHarness's answer (sidebar row → spawn record → pending PICK) and passes it in. A second resolution inside the timeline hook read only the first two, so a pending claude chat — picked in the tab strip, not yet spawned — still offered Goal, and arming it did nothing: harnessModeSelection forwards plan on that path and silently drops a goal. A pick the composer renders must be the same pick every consumer reads.

applyHarnessMode (routes/agent/command.ts) is the other half: for a live non-omp session a mode command becomes set_mode('plan') / set_mode('default') where the agent publishes plan, and is refused in words where it does not (<label> has no plan mode, <label> has no goal mode). Pinned by mode-availability.test.ts and the mode cases in command.test.ts.

Goal on ACP is Kabmo-owned. The agent has no /kabmo-mode extension (and omp-acp's extension writes to a transcript this transport cannot rely on), so acp-goal.server.ts stores the record in harness_goal_state, the turn-end driver audits the closed message, and it opens the next turn itself. The AUDIT runs on the same harness, not omp RPC: acp-audit.server.ts opens a disposable ACP session with the same launch command/env (and therefore the harness's own tools/MCP setup), applies the chat's own model (runModel), sends the shared classification prompt, and reads the JSON verdict. No omp -p is spawned and the omp goalAuditModel setting is not applied to an ACP chat. Markers travel as extension_ui_request / notify frames on the session stream, which the composer's fold already parses. ACP reports context tokens (not spend), so the goal budget is enforced on the summed per-turn peak used; tokensUsed on the strip is that figure. The continuation is a normal prompt, not a hidden custom message. A GUIDED goal is approximated as a create whose objective is the operator's message: a real interview ends with the model calling a goal tool to write the objective, and an ACP agent without that extension cannot do it. Plan mode is still the agent's own selector.

ACP composer parity, measured

  • Thinking. probe.thinking is the agent's thought_level ladder and is a SESSION selector, so every ACP model row carries it (harness-models.ts). Without that the composer disabled the picker even though set_thinking_level → session/set_config_option is implemented.
  • Plan state survives a reload. GET /api/sessions/:id/modes used to answer 404 for every non-omp ACP chat (no omp transcript), so a plan mode the user turned on came back OFF. The route now asks the live session's own mode selector (applyHarnessMode(…, {scope:'plan', action:'state'})).
  • Selector IDs, not categories. session/set_config_option keys on the option's id; the category only classifies it. The writes used the literal model/thinking/mode, which worked only on agents whose ids happened to use those words. Every write now passes option.id, measured against a fake agent publishing sel-model/sel-thinking/sel-mode.
  • Model identity on reopen. A non-omp ACP chat has no JSONL. /api/chat/:id now answers the live session's get_state model/thinking, falling back to the last run's session_stream_state row after a restart. Before it, the composer matched the session id against omp's registry, never found it, and displayed an omp model over a chat running a different agent.
  • A model pick must reach the footer, three ways. set_model is a config write, not a respawn: the session adopts the reply list (or the requested value when a harness returns {}), renames the live session_stream_state row, and emits model_changed so /api/chat/:id is re-read. In addition every message_update/message_end is stamped with the session's runModel, which is what RunFooter was designed to read; before it every ACP footer fell back to the SESSION's model and an idle chat kept showing the first pick forever. Verified against a fake agent that answers session/set_config_option with {}: runModel moved first → second, the message_end carried {model:"second", provider:"p"}, and a model_changed frame arrived.
  • A silent turn is a REPORTED error, not an empty bubble. pi-acp answers session/prompt with {} and sends no frames on a provider failure; the ACP driver turns that (and a whitespace-only chunk) into prompt_error. The client used to log it and leave the optimistic row blank. It now attaches the reason to that row — MessageItem already renders msg.error as its error alert — and consumes the placeholder so a late frame cannot fill it. A failed prompt emits the agent's error ONCE: finish no longer appends its generic "no answer" verdict on top. Warning/error ACP notice updates also become notice rows instead of console lines.
  • Slash commands are the AGENT's. /api/settings/commands?sessionId= returns the agent's get_commands list even when empty; falling through to omp's utility catalog offered commands from a different agent. /api/settings/skills returns none for a live non-omp chat for the same reason. The client's TUI-only refusal is scoped to omp-rpc/omp-acp — claude publishes /clear and /status itself, and the omp table used to refuse them before they left the composer.
  • @ agents are omp's. The @ pool drops the omp subagent rows on a non-omp harness (loadComposerItems(..., { includeAgents:false })) and buildPromptText leaves the token as typed: the rewrite names omp's task tool, which those agents do not have. File mentions still translate to @path, which remains agent-dependent — ACP's resource_link is the standard form and is not sent yet.
  • The @harness:<id>: model tail completes from that harness's catalogue. Before this, the popup said No matching files or agents for the model the hint told the user to type. detectComposerTrigger now returns a model phase whose replaceFrom sits AFTER the second colon, so a row inserts only the --model value (provider/id for omp, the bare ACP value) and the typed mention survives. The rows are harnessModels — the same list the model dropdown's tab shows, live session before probe — and the id is resolved through harnessIdForName, one table shared with parseHarnessMentions, so @harness:omp: scopes to omp-rpc. Measured in the browser: omp listed 319 registry models, claude its 5 selectors, and Enter left @harness:claude:claude/opus in the draft with the popup closed.
  • Tool output and renderer key. ACP nests text as {type:"content", content:{type:"text"}}; acpToolOutput flattens it onto tool_execution_start/update/end, and the shared fold prefers that output over re-walking the raw envelope. The transport's own kind (execute → bash, search → grep) rides the message block as toolType, so a vendor name still draws the right panel. A tool_call announced already completed is closed immediately — leaving it open made turn-end report a success as an error.
  • Panels. A {type:"diff"} content block becomes details.diff/path for the Edit card. plan updates become the Todos payload, and usage_update feeds the Context ring/panel (contextUsage, cost, user/assistant counts) through the telemetry topic. A turn end republishes session-data-dirty, and the last snapshot is persisted (harness_usage_state) so a reopened chat's ring still fills after the process is gone.
  • Queue. The stored model snapshot is best-effort per command: a harness with no model/thinking selector used to make set_model throw, which aborted the delivery and re-queued the user's message forever.
  • Undo/Retry work on BOTH omp transports, and refuse on the other ACP agents. The action calls the omp JSONL rewind endpoint, so the rule is a capability, not a transport: harnessSupportsRewind (shared/lib/harness/rewind.ts) allows omp-rpc and omp-acp — omp-acp writes the SAME session file, and the endpoint destroys its live child first (that child holds the old context and is the only other writer), then truncates. The next prompt resumes the truncated file over RPC, because session/load on omp forks and resumeRecordedHarnessSession excludes omp-acp for exactly that reason. Another ACP agent (claude, codex, opencode, …) keeps its history in its own store and ACP defines no truncation (session/load replays it, a fork copies it), so it is refused in words BEFORE its child is touched rather than truncating a file it does not read. The endpoint refuses a live non-rewindable harness with harness_not_rewindable; the client reports the same sentence.
  • A subagent that outlives its turn is recovered from session/load. antigravity ends the turn right after invoke_subagent (the tool call is marked completed, the agent sends a holding sentence, session/prompt answers stopReason:"end_turn") and holds the subagent's completion until the next request — upstream google-antigravity/antigravity-cli#1461, measured on 1.5.3: zero frames for 60 s, while the transcript already held the answer. Kabmo starts a session/load probe for a closed message carrying invoke_subagent / spawn_subagent; the replay is swallowed (it repeats the whole chat) and the text past the holding answer is emitted as a follow-up run only once two replays repeat it, because a single replay can be a prefix while the model is still writing. Measured end to end: holding answer at 15.3 s, image and final answer delivered at 51.8 s. An empty session/prompt is refused (-32602 Empty prompt), and session/resume neither replays nor subscribes; session/load is the only request that surfaces the held frames.
  • Not built: @file: mentions travel as @path text, not ACP resource_link blocks (agent-dependent); Kabmo's own subagent roster and compaction controls remain RPC-only (an agent's INTERNAL background subagent is recovered by the probe above).

Adding a harness

  • A harness is a row, not a build. custom_harnesses holds { id, label, initial, command, env, note }; src/server/lib/harness/custom.server.ts loads it into a process-wide registry and publishes a descriptor to the shared catalog. The ACP transport was already generic — a launch line is a command vector, the handshake is one implementation, and the settings page reads /api/harness — so nothing in the session path is per-agent.
  • HarnessId is open, the built-in tables are not. HarnessId = BuiltinHarnessId | (string & {}) keeps autocomplete and typo errors for the shipped ids while letting a runtime id through. Tables that must be COMPLETE (HARNESS_CATALOG, HARNESS_MCP_FACTS) are keyed by BuiltinHarnessId; tables that may be partial (HARNESS_LAUNCH, provider/update facts) stay Partial<Record<HarnessId, …>>.
  • Every fact has a fallback, and each one is a decision. MCP delivery → acp (the only transport the add form offers); provider facts → kind: 'none' (no registry editor); update facts → none (no Update button); fork → none (the probe is still authoritative for session/fork); local transcript → false (no rewind, no message-anchored fork). A custom harness therefore gets the generic ACP behaviour instead of a crash on an undefined table entry.
  • Launch resolution reads the registry. launchFromConfig/resolveLaunch/commandAvailable use HARNESS_LAUNCH[id] ?? customLaunch(id), and openAcpSession awaits ensureCustomHarnesses() before asking — the resolver is synchronous, the row is not. The boot loads the registry before any probe or spawn.
  • A removed harness is still named. knownHarness keeps any well-formed id even when no descriptor exists, so a chat that ran on a deleted harness reports that id and the resume path refuses with "No launch command is configured for X" instead of silently rewriting the chat to omp-rpc. Removal deletes the definition, its config key, its probe row and its disabled entry; it does NOT delete harness_sessions.
  • The UI is roster-driven. /api/harness returns custom: true and initial; the client registers the descriptors before rendering, HarnessGlyph draws the initial when there is no vendor mark, and the settings sidebar rebuilds its HARNESSES section from the live roster (settingsCategoriesFor) rather than the build's static list. Settings → Harnesses → Add an ACP harness is the only writer.

What is not built yet

  • harness_events persistence — needed by dsh, which has no loadSession.
  • The discover dialog with a count preview.
  • Hosting an agent's terminal auth flow in Kabmo's own PTY.

The session ownership lease's primitive is per-platform (omp 19.0.1)

omp holds a per-session lease on ~/.omp/run/session-owners/<id>.lock for the life of the process that opened the session; a second process that resumes a held session forks itself (reason: "open-elsewhere"), which is the duplicate sidebar row a user sees. Kabmo asks "is it held" itself (src/server/lib/omp/session/lease-probe.server.ts) so it can refuse before spawning and relay to the owning instance instead.

Linux keeps flock(2) and record locks in separate spaces, so the primitive has to match the one omp takes. omp 19.0.1 moved Linux from an abstract socket to an open-file-description lock (F_OFD_SETLK on the .lock file). A flock-based probe — what this module was until that pin — acquires a lease another omp is holding and answers "free", so the guard silently stopped working on the platform where it now had a file to look at. Measured in a Linux container (bun 1.4.4, 2026-11-20) with a second process holding the write lock:

flock says held? false
ofd getlk l_type: 1 => held? true      # F_WRLCK
free: flock held? false  ofd l_type: 2 # F_UNLCK

The module is lease-probe.server.ts (it is no longer flock-only): flock with LOCK_EX|LOCK_NB on macOS, F_OFD_GETLK on Linux — a query, so the probe never takes the lock it asks about. holdLeaseForTest takes the same primitive per platform, so the detached-holder test in ownership.server.test.ts holds a lease omp would recognise, and lease-probe.server.test.ts pins the Linux half against a lock it takes with fcntl directly (a regression to flock fails it rather than passing tautologically — verified by reverting the branch).

A 32-bit Linux struct flock is a different layout (16 bytes, not 32) and is refused as null ("cannot answer") instead of guessed at; a null is not "free", and ownership.server.ts falls back to the instance registry.

Clone this wiki locally