Skip to content

Omp Engine and Settings

Wijanarko Putra Rajeb edited this page Nov 18, 2026 · 11 revisions

omp engine and settings

OMP Engine Settings Schema (generated)

  • src/client/data/settings/omp-schema.json is GENERATED, never hand-edited. bun run omp:schema (scripts/omp-schema.mjs) imports orderedSettings() from the installed @oh-my-pi/pi-coding-agent and SETTING_TABS/TAB_METADATA from pi-tui, and writes the panel's tab/group/label/editor metadata from that. bun run omp:schema:check regenerates in memory and exits non-zero when the file is stale, so a stale schema is a CI failure rather than a shipped panel — that gate is the Settings schema job in .github/workflows/gates.yml (called by ci.yml), deliberately separate from checks because the generator imports the INSTALLED package (this repo does not depend on @oh-my-pi/pi-coding-agent) and a cold Bun global install would otherwise sit in front of every other check. The gate installs the PIN in .github/scripts/install-omp.sh, so the schema and that pin are bumped TOGETHER — a schema generated from a newer omp than the pin is reported stale by CI, and a pin newer than the schema is the same failure in reverse (measured twice: 948f9e4 refreshed the schema from a local 18.10.3 with the pin at 18.10.0, and the pin then stayed at 18.10.3 while 18.11.0 was installed, so CI stayed green over two rows omp config set refuses). It was documented here before it existed: no workflow called the script until 2026-10-12, which is how the file drifted 9 rows behind omp 18.9.2 unnoticed (as of omp 18.16.0: 438 upstream entries, 10 tabs / 582 settings, and 0 of Kabmo's 461 merged keys rejected by omp config list --json). The JSON sat frozen from the Remix→Elysia migration (2026-09-18) until this existed: 157 live settings had no row at all (every title.*, tui.renderSvg, tui.autoGraph, task.completionProbe, skills.*, ida.*, searxng.*, gc.*, memories.*, compaction.v2RetainedMessageBudget, browser.tern, stream.serverUrl, telemetry.otlpExportEnabled), and 12 rows Kabmo still offered were rejected by omp config get with Unknown setting: — stt.modelName, providers.tts, tts.localModel, providers.webSearchOrder, irc.timeoutMs, providers.autoThinkingModel, providers.imageOrder, providers.memoryModel, providers.tinyModel, providers.unexpectedStopModel, providers.webSearchExclude, providers.webSearchGeminiModel — an editor whose write was guaranteed to fail. The generator reads the PACKAGE, not the binary, and now pins it to the script's own version. omp can self-update its compiled binary (omp update) while ~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent stays behind — measured at 18.17.0: omp --version answered omp/18.17.0 while the package still said 18.16.0, and bun run omp:schema regenerated the OLD 438-row file. A candidate is now used only when its package.json version equals OMP_VERSION in .github/scripts/install-omp.sh; an explicit OMP_SCHEMA_PACKAGE_DIR with the wrong version is an error. A machine whose only omp is the standalone binary has no global package, so a miss under OMP_SCHEMA_PACKAGE_DIR / repo node_modules / Bun's global install provisions @oh-my-pi/pi-coding-agent@<pin> into $XDG_CACHE_HOME/kabmo/omp-schema/<pin> and generates from there. That cache is outside PATH, so Bun's bin link cannot collide with the standalone binary (EEXIST) and no second omp command appears. CI is unchanged: install-omp.sh installs the pin globally and the generator finds it first.
  • The generator reads omp's own source, not its bundle. The published package ships src/ beside dist/, and the definitions live in src; dist/cli.js is minified, so its re({…}) calls only partially evaluate (the enum and ui shape survive, an expression-valued default does not). A setting with no ui block has no row in omp's own panel either, so it is deliberately not carried — and schema-extras.ts still supplies Kabmo's documented extras, which never shadow an upstream entry (asserted by schema.test.ts).
  • The credential marker is credential, not isCredential. orderedSettings() yields Setting instances, but the generator destructures { definition } — the raw SettingDefinition — so definition.isCredential (a getter on the instance) was always undefined and NO row ever carried credential: true. Every credential row therefore rendered in plain text, including live.apiKey when omp 18.22.1 added it. The generator now reads definition.credential === true || definition.ui?.secret === true, the same rule as omp's own Setting.isCredential; four rows mask (live.apiKey, mnemopi.embeddingApiKey, mnemopi.llmApiKey, hindsight.apiToken), asserted in schema-releases.test.ts.
  • task.completionProbe replaced task.completionProbeMs in omp 18.5.0 (0 → off, any period → on), so the old key is gone from the schema and offering it would write a key the binary rejects.

Model Roles & Presets (OMP Engine settings)

  • A role row is a MODEL PICKER, not a text field. modelRoles holds a provider/model selector, which a user cannot type reliably and which fails silently when mistyped — omp falls back to its own resolution and the role runs on a different model than the panel shows. RoleRow.tsx renders a <select> grouped by provider (native type-ahead, keyboard and screen-reader semantics for free), and the stored value is always an option even when the catalog no longer lists it (a model removed from models.yml, a provider that lost its credential, a catalog read that failed): dropping it would make the select display a model config.yml does not hold, and the next edit would write that one over it.
  • The candidates come from omp models --json --kind all, not from get_available_models. The RPC answers CHAT models only (modelRegistry.getAvailable() defaults to kind chat), so the five kind roles would have offered nothing; the CLI lists every kind (~1.3 s, cached 60 s on globalThis). The cache is dropped by invalidateModelsCaches — the same signal every provider/model mutation already emits — because a model that disappeared must leave the role pickers too. A catalog failure is REPORTED (candidatesError) rather than thrown: the roles live in config.yml and stay editable without it, and an empty dropdown with no explanation reads as "no models exist".
  • The role table is ONE shared module (src/shared/lib/omp/config/model-roles.ts), read by the editor, the pickers and the tests. It mirrors omp's MODEL_ROLES at 18.12.6 — including widget ("Job widgets"), which this panel had omitted, making it the one role unreachable from the console. Each role's upstream accepts predicate is flattened into a catalog-kind list; web additionally admits a chat model declaring a grounding transport, which the CLI's JSON does not carry, so that one case is a webCapable flag and roleAcceptsCandidate is the single predicate.
  • A preset is Kabmo's own record, in model_role_presets (src/server/lib/model-roles/{schema,store}.server.ts). omp has the same idea upstream (modelPresets.<name> driven by /modelpreset), but that surface is TUI-only and Kabmo does not own that key — a second writer on a file omp rewrites is how a config gets clobbered. The preset's whole map is one JSON column: it is applied as a UNIT, which is the only operation that exists. name is COLLATE NOCASE UNIQUE, and a collision is reported as a sentence ("A preset named “cheap” already exists") rather than the SQLite constraint text.
  • Role ids are NOT narrowed to the built-ins. modelRoles accepts custom role ids and omp adds them to its own role list, so filtering a preset's keys would silently delete a custom role the moment it was applied — the map is written whole, and a filtered copy is an edit of the live config. Only keys that cannot be a role name (and empty selectors) are dropped.
  • PUT /api/model-roles writes the whole map; that one verb serves both a single row edit and applying a preset. config.yml holds the map whole either way, and two writers is how a preset and a row edit end up disagreeing. The client adopts the server's echo, and a REFUSED write restores the previous map (useModelRoles) — leaving the optimistic draft on screen after config.yml rejected it shows an assignment that does not exist, and the next edit builds on it.
  • The selected preset and "in use" are two different facts. in use is derived by comparing the live map with the preset, so there is no stored "last applied" flag to go stale. The SELECTION is not: tying it to the comparison made Update unreachable in the exact flow it exists for — pick a preset, tweak one role, save the tweak back into it — because the edit moved the picker to Custom and disabled the button. The picker therefore reads preset · modified while they differ, in use only while they agree, and Update/Delete always target the selected preset (disabled only with no selection). Delete confirms inline; Save as… names a new preset.
  • The first open snapshots the roles an install already had into ONE preset (seedPresetFromCurrentRoles, called from the GET loader). A machine that has been running omp for months has a full modelRoles map and an empty preset table, so the picker would offer nothing until the user hand-saves what it is already running. Three cases step aside and still spend the one run: an EMPTY map (a fresh install has nothing to snapshot), a table that already holds a preset, and MOCK mode (a demo must not write rows into a real database). The name is Default — what it is, not a strategy claim the seeder cannot make — and the app_settings marker model_role_presets_seeded is written on EVERY deciding path, the same rule workspace_sync_ran follows: "the table is empty" cannot separate never-seeded from user-deleted, so without the marker a deleted preset would come back on the next panel open. Verified end to end: a temp install with four roles came back from its first GET with Default holding exactly that map, a second GET did not duplicate it, a DELETE followed by another GET stayed empty, and the marker read true. A failed insert is swallowed (the panel's own Save as… is the manual path) and still spends the run, so a config omp rejects cannot make every open retry.
  • The panel's role wiring lives in useModelRoles (src/client/hooks/settings/model-roles.ts) — the load is still the panel's single Promise.all so one spinner covers the screen, hence applyPayload beside the three writes.

The OMP Engine panel's controls and write feedback

  • Search is a WHOLE-SCHEMA view, and the tab strip is HIDDEN while it is active. The results have always been global (they span every tab), so leaving the pills on screen made a tab click look broken: the highlighted tab changed and nothing in the results did. The strip is replaced by a summary line ("Searching every tab — N matching keys"), and each tab pill carries its own visible row count under the current config snapshot, so an empty tab is recognisable before it is opened.
  • Reset is offered only for a key config.yml actually holds. omp config list --json omits value for an unset key, and omp config reset on one is a silent no-op — the row's reset button was clickable and did nothing. It now reads This key is not set — omp already uses the schema default.
  • A row's text editor commits on blur, Enter or its own check button; Escape abandons the draft. It used to commit on blur only, so Enter did nothing at all, and a draft that could not be parsed (a trailing comma in a JSON array, a half-typed number) reverted with NO message — which reads as "saving is broken". src/shared/lib/omp/config/row-value.ts now returns the parsed value or a sentence naming the shape the key wants, and the row prints it under the field.
  • Credential rows get a reveal toggle. A password-type field with no way to check what was pasted is a field users get wrong once and never trust.
  • A boolean row's saved badge comes from the SERVER's answer. Measured: colorBlindMode toggled in the browser wrote true to config.yml and the row state matched, but omp does not validate a theme name, so theme.dark = "definitely-not-a-theme" is a SUCCESS — a panel cannot use "the value looks wrong" as its failure signal. A real refusal (Unknown setting: <key>) renders omp's own sentence under the row.
  • Extension toggles are switches with a per-row pending state and a refusal banner. The row used to be a <select> whose onChange ignored the chosen value, and a failed write was console.error only — so the row could show a state config.yml did not hold. The empty case now says where extension modules are looked for instead of returning null (a panel that vanishes is indistinguishable from a broken one).
  • setExtensionDisabled read the list through doc.get(), which returns a YAML SEQ NODE. Array.isArray on a node is false, so the list always looked empty: disabling replaced every other disabled id, and re-enabling found its own id "absent", answered "nothing to do", and left the extension disabled forever. Measured on a real config (disabledExtensions: [extension-module:smoke] → POST disabled: false answered changed: false, file untouched). valueAt(doc, ['disabledExtensions']) unwraps the node and seqAt edits the existing sequence in place. Pinned by two cases that fail on the old code.
  • A preset's name form stays open until the preset is STORED. commitNew closed it on the click, so a refused name ("A preset needs at least one role assigned", "A preset named “cheap” already exists") threw away what the user typed. The bar also states how many roles carry an override (1 / 16 set) — the one number that says whether the map does anything.
  • A failed config read is REPORTED, never rendered as defaults. GET /api/settings/omp-config answers {error} with a 500, and the panel used to drop it; it now shows the sentence with a Retry, and keeps the rows writable.

Agent definitions are omp's markdown files, with omp's keys

  • The Agents panel reads and writes omp's OWN definition files (~/.omp/agent/agents/*.md, <workspace>/.omp/agents/*.md). It used to POST into a Kabmo-local mirror, so "Create Agent" reported success and omp had no agent to load. The route is now {type: 'write'|'delete'} over writeAgentDefinition/deleteAgentDefinition, and every answer carries the re-read list.
  • The field set is omp's parseAgentFields at 18.16.0, not Kabmo's invention: name, description, tools, spawns, model, thinkingLevel, blocking, structured, prewalk, advisor, autoloadSkills, readSummarize, plus the body as the system prompt. mode, temperature and top_p are NONE of them — the pane offered all three, and editing them changed a file omp never reads. They are gone from AgentItem, the pane and the mock data; the pane now edits tools and spawns, which omp does read.
  • A write edits the frontmatter IN PLACE. Re-serializing an owned key set deleted the keys the panel does not own: a shipped agent's block-list tools: and its nested output: schema vanished the moment its prompt was saved. writeAgentDefinition replaces an owned key where it stands, appends one the file lacks, and keeps every other line verbatim; tools: undefined (an untouched field) leaves the existing tools: alone. Measured on a real ~/.omp/agent/agents/scout.md: after an edit, its five-line tools: list and 20-line output: block were byte-identical and only model moved.
  • model is written as a YAML block list by omp's own shipped agents, so the scalar-only parseFrontmatter in yaml.ts read every one of them as having no model. parseAgentDefinition (agents.ts) handles both the scalar and the sequence form, and thinking/thinking-level as aliases of thinkingLevel.
  • A definition needs a description, and omp refuses to load one without it. The pane says so, and refuses an empty system prompt before sending: both would otherwise write a file omp silently ignores or an agent that does nothing.
  • The model picker is the LIVE /api/models catalog, grouped by provider, not the hardcoded display-name list the pane carried (gpt-4o, deepseek-reasoner-r1, …) — a value nothing reads and a name no provider serves.
  • A rename writes the new file and deletes the old one in the same request (previousFileName), so one definition cannot survive under two names.

Panes report the server's answer, not the click

  • useCrudList resolves save/remove with { ok, error }, and a pane sets its badge from that. Every panel used to paint "Saved successfully" the instant the button was pressed: a duplicate agent name, a read-only native file or a rejecting validator all showed a success over a row that had not changed. The shared useWriteFeedback (src/client/hooks/settings/write-feedback.ts) owns saving/saved/error, keeps the server's sentence, and is the only thing that flips the badge. Its own test pins a landed write, a refusal, a sentence-less refusal, a thrown request and the recovery path.
  • A failed list read is loadError, not an empty list. "No agents" and "the read failed" are different facts, and the sidebar now says which with a Retry. useCrudList's reload() exists for that.
  • A delete asks first, in place. The Agents, Commands, MCP and Skill panes deleted on the first click; each now names what disappears.
  • ImportModal closes on the save's ANSWER, so a refused MCP import stays readable against the JSON that produced it.

MCP route: missing await answered servers: {}

  • Three branches of POST/PUT /api/settings/mcp returned json({ servers: mergeServers(...) }) without await. JSON.stringify turns a Promise into {} rather than failing, so the response was a 200 carrying servers: {} — the save landed in mcp.json, and the panel that adopts its own answer showed an empty list. Measured: create → {"success":true,"servers":{}} while ~/.omp/agent/mcp.json held the entry. Every list-reporting branch now awaits, pinned by src/server/routes/settings/mcp.test.ts (four of its five cases fail on the old code).
  • A rename also left the OLD name behind as an app-local row. The native file was rewritten under the new name, but the SQLite mirror still held the old row and the panel listed both. The route drops the row named by previousNativeName after the upsert.

The MCP pane covers omp's whole mcp.json schema, not two fields

  • The pane used to write {command,args,env} or {url} and nothing else. omp's schema (mcp-schema.json) also defines type: stdio|http|sse, headers, cwd, timeout, requestIdFormat, instructions, auth and oauth; a server needing an Authorization header, a working directory or an SSE endpoint could only be configured by hand-editing the file. McpServerItem now carries every field, toNativeServer writes them, and nativeToServerItem reads them back. type is written for both remote transports because omp infers url → http — an SSE endpoint without type: "sse" silently loads as streamable HTTP.
  • Enablement is omp's own three-part model, and the pane used to write none of it. disabledServers (user file) is the highest-precedence denylist, enabledServers overrides a source's enabled: false, and the entry's own enabled: false disables it. The old save wrote only the entry, so the "Enable Server" checkbox flipped back on the next read. writeServerAt now writes the entry's flag AND the user-level lists (a project-scope save updates both files), and isServerEnabled is the one precedence rule the pane and the session registry share. definitionFromNative also honours enabled: false now — before, a server disabled in the file still reached every session.
  • Both user files and every project candidate are read. omp discovers ~/.omp/agent/mcp.json and ~/.omp/agent/.mcp.json, and every existing project candidate (.omp/mcp.json, .omp/.mcp.json, mcp.json, .mcp.json), first name wins. readUserMcpConfig/readProjectMcpConfig merge them; resolveProjectMcpConfig stays the single WRITE target. mcp.enableProjectConfig (default true, read from config.yml) gates project discovery in both the pane and the registry.
  • The connection test speaks all three transports. HTTP POSTs initialize with the configured headers; SSE opens the stream, waits for the endpoint event, POSTs initialize there and reads the answer off the same stream. A plain POST to an SSE URL — the old behaviour — cannot succeed. Header values whose key looks like a credential (authorization, cookie, *key*, *token*, *secret*) are redacted before the browser sees them, and the writer preserves the stored value when the form sends the sentinel back.
  • Import reads every envelope and every server. {mcpServers} (omp/Claude/Gemini, httpUrl included), {servers} (VS Code, typed transports), {mcp} (OpenCode, local|remote, command array, environment) and a bare definition; all entries are imported, not just the first. The parser is src/shared/lib/mcp/import.ts, pure and unit-tested.
  • Plugin contributions accept sse too. PluginMcpTransport is stdio | http | sse; the registry already carried the transport through to ACP, so the SDK type was the only thing refusing it.

Per-session MCP: the list is a SPAWN property, so the switch is a directory

  • The navbar's context popover lists the session's MCP servers and switches them for THAT session only. GET/POST /api/sessions/:sessionId/mcp (src/server/routes/sessions/mcp.ts) reads the same merge the spawn path uses (mcpServerEntriesFor, src/server/lib/mcp/registry.server.ts) and stores only the names that DIFFER from the configured state in session_mcp_state (overrides JSON: name → true|false). A toggle back to the configured value deletes the entry, so a later settings edit still reaches a session that never touched that server. The row is server-side, not session_ui_state: the spawn path reads it before any client exists.
  • omp-rpc reads mcp.json once at spawn and has no RPC verb to add or remove a server. The only lever is PI_CODING_AGENT_DIR — the same one utility-agent-dir.ts uses to spawn an MCP-free child. A session with overrides therefore gets $TMPDIR/kabmo-omp-session-mcp/<sessionId>: every entry of the real agent dir is SYMLINKED (auth, models, sessions, skills, extensions, the databases stay one copy), mcp.json is written from the merged list with the session's enablement, and .mcp.json is not linked at all (omp unions both user files, so a linked secondary would resurrect a disabled server). A --config overlay sets mcp.enableProjectConfig: false, because the project's own file is read from the cwd and would otherwise add back a server the session disabled. Measured on 18.20.0: with the overlay a project server's command never ran; without it, it did. A session with no overrides gets no overlay and reads the real config exactly as before.
  • A live toggle is /mcp reload, not a respawn. Measured on 18.20.0 over RPC: /mcp reload answers agentInvoked: false in a few ms, emits one command_output frame, opens no turn, and re-runs discoverAndConnect — so rewriting the overlay's mcp.json and sending the prompt applies the change live (reload-mcp.ts, deliberately not routed through dispatchSessionCommand). A child spawned WITHOUT an overlay read the real file, so an idle one is destroyed and the next command respawns it with the overlay; a busy one keeps its list until the next spawn and the response says appliesOnNextSpawn: true.
  • ACP receives the list as a handshake argument, so the filter is applied in spawn.server.ts. An idle ACP session is destroyed and the next command respawns it through resumeRecordedHarnessSession with the filtered list. omp-acp is excluded: session/load on omp FORKS the conversation (measured), so that chat keeps its list until the next spawn rather than losing its id.
  • The list is truthful per delivery. omp-rpc shows only the sources omp can read (user + project files); app-local rows and plugin contributions stay ACP-only, as they were. The overlay materializes only those two sources, so the list does not change shape when the first override is applied.
  • Status is a PROBE, not a guess. omp publishes no MCP state over RPC: mcp:connection-status is an internal TUI event bus, /mcp list over RPC prints the configured state, and get_state.dumpTools carries only the built-in tools (measured on 18.20.0 — a live codegraph server mounted no mcp__ entry there). The info control therefore runs a real handshake (testMcpServer, the same one the settings pane uses) and caches the answer per session+server for 60 s (probe.server.ts). Green = the handshake answered and listed tools; red = it failed or the server is disabled; yellow = checking, or not probed yet. The probe starts a SECOND instance of the server, which is why it runs on the info control and never on mount.
  • The popover is one control for both layouts (ContextUsageButton, layout prop), widened from w-56/14rem to w-72/18rem to hold the list. The checkbox uses the shared CHECKBOX_CLASS — the repo's checkbox contract test counts every <input type="checkbox"> call site.

Standby omp Processes (Reload OMP, omp update)

  • A reload means DISPOSE, not re-read. recycleStandbyProcesses (src/server/lib/omp/session/standby.server.ts) disposes the two pools that hold an omp process with no session and no turn — the shared utility children (--no-session --no-lsp, answering get_available_models, get_login_providers, get_available_commands) and the per-cwd prewarm entries (an idle session host waiting for the next send) — so the next command boots the binary currently installed. /reload-plugins is a different question and lives in reload.server.ts: it re-reads skill/plugin FILES inside a live process and would leave the OLD BINARY running, which is exactly the staleness this exists to fix.
  • The utility child carries NO MCP servers, and that is a deliberate subtraction. omp --mode rpc-ui connects every configured MCP server at startup, and no CLI flag skips it (--no-tools still spawned the proxy: measured). The shared utility child answers registry/auth/slash-command queries and never runs a turn, so the codegraph serve --mcp proxy it spawned — plus that proxy's main-thread watchdog — was 88 MB per cwd serving nothing; the xd:// notice proved it, mounting mcp__codegraph_explore into a child that can never call it. ensureUtilityAgentDir (rpc/utility-agent-dir.ts) builds $TMPDIR/kabmo-omp-utility-<pid> as a symlink farm over ~/.omp/agent with mcp.json and sessions/ omitted, and startProcess passes it as PI_CODING_AGENT_DIR. Measured on the real path: children=[] (no codegraph, no watchdog) with get_available_models 220, get_login_providers 86, get_available_commands 58/7 skills, get_state ok — identical to the unlinked child, which is the acceptance bar. Symlinks, never copies: logout writes credentials and the .db files are live WAL SQLite, so a copy would fork state. Directories must be linked too — materialising skills/ empty dropped the count to 52 commands / 1 skill, because omp discovers its roots by reading that directory. A build that fails returns undefined and the child uses the real dir: a slow models list is not worth a failed boot.
  • Why it is needed at all: a running child is the build it was spawned from, for its whole life. omp update replaces the launcher and the package on disk, but a utility child lives up to 5 minutes (IDLE_KILL_MS) and a prewarm waits for a send that may be an hour away — so the provider list, the model list and the composer's / popup keep answering from the previous version with nothing on screen to say so. Verified end to end against a real server: after a successful update the utility child's pid was gone and the next /api/models booted a new one, while an already up-to-date run left the same pid alive (applyOmpUpdate returns updated: false for the phrase checkOmpUpdate already matches — a success that must not bounce a warm pool).
  • Live sessions are deliberately untouched. They may be mid-turn, and a --resume on their next command already boots the current binary. The button is therefore safe to press at any time, and the smoke run proves it: with a real session host and a utility child alive, POST /api/omp/reload-engine recycled the utility pool and left the session's pid running and its get_state answering.
  • The prewarm pool's recycle is claim-safe by construction. An unclaimed entry owns no session and no turn, and startNewRpcSession claims an entry with a synchronous check-and-set — so an entry is either taken before the pass reads it or taken after the pass removed it, never both. restartPrewarmedSessions (rpc/session-registry.ts) marks each doomed entry claimed before deleting it, then awaits destroyAndWait; a wrapper still booting is torn down the same way the prewarm's own error path does.
  • A resumed session can come back under a DIFFERENT id, and the registry must answer for the one the CLIENT holds. omp 18.10.0 forks a session marked moved away (omp session moved, or a departed session-transfer marker) instead of continuing it: the child answers a fresh sessionId and writes the fork to a fresh file under a fresh id — verified against a real child, which resumed a departed file into another directory. The registry is keyed by the id the caller holds (the URL's session id), so keying it on that alone MISSED on the very next message: the send re-resolved the ORIGINAL file and spawned again, and two sends on one session file produced two children with two different ids, each forking its own file — a chain of forks with a sidebar row each and nothing on screen to explain it (measured through both startRpcSession and the route-level lookup). registerSpawnedSession (rpc/session-registration.ts) therefore registers the wrapper under the reported id AND, when they differ, under the requested one, removing both on destroy so a dead child cannot answer for the requested id; the spawn path also emits session-attached for the requested id so a subscribed tab re-snapshots instead of holding the pre-spawn running:false. realSessionId reports the child's OWN id even on a registry hit (it reported the requested id, which is the alias, not the session). Pinned by forked-resume.test.ts, which drives the real spawn path against test-support/fake-omp-fork.ts — the only way the two ids can differ — and fails with 2 children if the alias is removed.
  • Caches built FROM a process or the binary are dropped in the same pass (invalidateModelsCaches, invalidateSkillCache, invalidateUsageCache, invalidateOmpCliCache), because a recycled server behind a cached provider/model list makes the recycle look like it did nothing. The client half is useReloadOmpEngine (src/client/hooks/settings/reload-engine.ts), which also calls invalidateComposerCache + notifyModelsUpdated — the / popup holds its list for 5 minutes and would otherwise keep offering the old commands.
  • Two triggers, one pass. POST /api/omp/reload-engine (route src/server/routes/omp/reload-engine.ts) is the settings sidebar's "Reload OMP" button — previously a 1200 ms spinner with no request behind it — and applyUpdate's omp branch fires the same recycle after a successful update, gated on updated so an already-current run does not bounce anything. Both coalesce onto one in-flight pass, and a failure in one pool never skips the other (each is caught and reported separately; standby.server.test.ts pins all four properties).
  • The toast carries a tone. The settings modal's single toast slot now reports the reload's real outcome — Reloaded omp engine — N utility, M prewarmed process(es) recycled., or the empty-pool wording when nothing was live (a normal state, not a failure: the next command spawns the current build either way) — and a failed request renders under an alert icon in text-error instead of a check mark. Verified in the browser on a live server: the click issued POST /api/omp/reload-engine → 200, the toast named 1 utility, 0 prewarmed, and a forced 500 rendered alert-circle text-error.

Updates from the Console (self-restart and the page reload)

  • A Kabmo update from the console restarts the server that answered it, and the page then reloads ITSELF into the new build. POST /api/updates/apply arms the detached restart and answers first (RESTART_GRACE_MS, 1.2 s — the margin that lets the result frame reach the browser), so the page is still served by the process whose files were just replaced. Reloading on the result frame would fetch the OLD bundle back; never reloading leaves the user on a stale page with a "restarting" toast and nothing else. useUpdates therefore reads /api/health BEFORE the run, waits for a process that answers with a different pid/startedAt, and only then reloads (src/client/hooks/ui/updates/restart.ts, waitForServerRestart).
  • Identity, never a timer, is what "the replacement is up" means. A timer is wrong in both directions: too short reloads into the dying process, too long leaves the user on a stale page after the new one is already serving. /api/health reports the serving process's pid and startedAt, so a different pair IS the replacement. A failed probe is EXPECTED (the old server is exiting and the port is briefly unbound) and is never read as an answer; with no baseline — the pre-run health read failed — the fallback is a young uptime (REPLACEMENT_MAX_UPTIME_S), which the update's own multi-minute duration makes safe. The ceiling is 30 s (RESTART_WAIT_TIMEOUT_MS), and on a timeout the result comes back with restarting: false and a sentence telling the user to reload by hand rather than a promise the console cannot keep. Verified against a live server: the real /api/health payload carries both fields, a re-read of the same process is not a replacement, and a changed pid is.
  • restarting is a FIELD on the result, not something the client sniffs out of the message. UpdateApplyResult.restarting is set from the plan scheduleSelfRestart returned, and the sentence is folded in by the same helper (withRestartPlan, src/server/lib/lifecycle/restart.ts) so the flag and the wording cannot drift apart. Absent on every other outcome — an "already up to date" success, a manual install, a failure — and false when a restart was refused (an instance the CLI does not own), where the appended sentence is the only place the user learns why.
  • The message was wrong, and this is the fix. It read … — the console reconnects on its own, which described the realtime socket and not the page: the console stayed on the old bundle until the user reloaded by hand. It now says Restarting on port <port> to apply it — this page reloads on its own., pinned by selfRestartMessage's own test.
  • The update check is not a mount-time fact. useUpdates checked once per mount, so a console that booted before a release reached npm kept the old answer forever: the "update available" popup never appeared until the page was reloaded (reported against v0.16.0 → v0.17.0; restarting the app remounted the page and the popup appeared). It now re-reads /api/updates/check on visibilitychange (visible), on window focus (a native shell's WebView can stay visible while backgrounded), and on a UPDATE_RECHECK_INTERVAL_MS 30-minute interval for a console that never leaves the screen, with a 60 s floor between automatic reads so the two return-to-app triggers do not double-read. The popup gate itself is unchanged: a re-check that reports a newer latest opens the same once-per-version dialog. Verified in the browser by stubbing only /api/updates/check after mount (mount: no update) and dispatching visibilitychange past the floor: the Update available dialog appeared with no reload.
  • The dialog stays in its "working" state across the wait, and the install log is APPENDED to rather than replaced. A run that flashed back to idle before the navigation would read as finished; apply therefore leaves applying set when it ends by navigating, and appends Update installed — waiting for the server to restart on this port… to the log it already has, because a failed restart has to be read against the output that ran. An abort (the panel going away with the run) still returns null — the same answer the other abort path gives — so no caller toasts into a torn-down view.
  • The omp target never enters this path. applyUpdate's omp branch recycles the standby pools and restarts nothing, so the client only reads the baseline and only waits for target === 'kabmo'. restarting is never set for it.
  • About's "What's new" control sits ON the version line and answers about the version you RUN; the update popup answers about the version you could INSTALL. Each line in the version block (Kabmo v0.17.0, Oh-My-Pi 18.14.0) carries a circle-i button whose accessible name names the product (What's new in Kabmo / What's new in Oh-My-Pi), and clicking it opens NotesDialog above About. A separate pair of buttons above the list was retired because it read as an action on the UPDATE — the updates row already answers that. The section is chosen SERVER-side by buildActiveReleaseNotes (src/server/lib/updates/active-notes.ts): GET /api/updates/notes?target= accepts a PRODUCT only, never a version, so the dialog cannot describe a release the install never had. omp's prose comes from packages/coding-agent/CHANGELOG.md in can1357/oh-my-pi — the file the release bodies mirror; the repository root has no changelog (404, measured) — and the changelog cache is keyed by SOURCE URL, because one shared slot rendered omp's sections under the Kabmo heading. The Kabmo updates row and its What's new in <latest> button stay: that release is what an update would install. Verified on a live server: About showed Kabmo v0.17.0 and Oh-My-Pi 18.14.0 with their controls, and each dialog rendered exactly that release's section with a link to the full changelog. Both changelog dialogs (NotesDialog and the update popup) are max-w-3xl and render prose at 13px: measured at 1440x900 the panel is 768px with a 726px article, omp's longest list item (430 chars) wraps to 4 lines instead of 7, and on a 390px phone the panel is 358px inside a 16px gutter with no horizontal overflow. The popup's sticky bottom-0 footer still pins its actions — the body scrolls, the action row does not.
  • The settings sidebar carries the same restart as a button, beside "Reload OMP", and it reuses that contract rather than a second one. POST /api/console/restart (src/server/routes/console/restart.ts, registered by routes/console/index.ts; the pre-rename /api/chamber/restart stays mounted by routes/chamber/index.ts) calls scheduleSelfRestart('restart') — the same detached kabmo restart --port <port> the update path arms, on the same RESTART_GRACE_MS — and answers { success, restarting, message }. useRestartKabmo (src/client/hooks/settings/restart-kabmo.ts) reads /api/health before the request, then waits through waitForServerRestart and reloads into the replacement, so the page cannot be left on the dying process's bundle. The purpose argument is the whole wording difference: an update says Restarting on port <port> to apply it — … and its refusal says start it again to apply the update, while a plain restart drops that clause (Restarting on port <port> — …) because there is no update to apply — one function per sentence (selfRestartMessage, skipRestartNote) with SelfRestartPurpose choosing the branch, so the two surfaces cannot drift. An instance the CLI does not own is REFUSED with that sentence and restarting: false (verified against a real bun run src/server/index.ts: this instance runs from source … — start it again), MOCK mode refuses outright because a demo must not take a server down, and the armed branch was verified end to end against a --launch-mode=daemon instance: pid 76144 answered the request, and 6 s later pid 76188 was serving the same port. Both buttons are disabled while either operation runs — a reload while the server is restarting answers a socket nobody serves.
  • A restart launches the copy the update INSTALLED, never the one the running process happens to be in — and a rename is why. bun add -g @kabmo-labs/kabmo installs a SECOND package beside the one that answered the update, so resolving the helper from that process's own PKG_ROOT relaunches the build the update just replaced. Measured on the 4.23.1 → 0.0.1 move: the log read [ompchamber] restarting on port 3001: … /node_modules/ompchamber/src/cli/ompchamber.js restart --port 3001, the console came back as 4.23.1, and the update had reported success. updateKabmo therefore reads the copy back off disk AFTER its steps (installed-cli.ts: copyAt for a checkout, resolveInstalledCopy for a global install) and returns it on KabmoUpdateResult.installed → AppliedUpdate.installed → scheduleSelfRestart('update', applied.installed); kabmo update does the same through restartCtx. A null falls back to this process's own root, which is correct for Restart (it installs nothing) and for a copy whose install could not be read.
  • The CLI file comes from the package's own bin map, and the credential marker follows the TARGET package. Two consequences of a rename that fail silently on their own. A hard-coded src/cli/kabmo.js does not exist in a copy that names its bin differently, so restartInvocation resolves the bin from package.json, preferring the entry named after the package (@kabmo-labs/kabmo → kabmo) because a bridge release registers both and picking the first key would restart a renamed install through the legacy spelling. And the handover variable was renamed too (OMPCHAMBER_PASSWORD_HANDOVER → KABMO_PASSWORD_HANDOVER), so a restart that set only its own spelling handed a payload to a CLI that never reads it and the replacement came back with authentication disabled — HANDOVER_ENV_BY_PACKAGE keys the marker by the target's package name. Both are pinned by installed-cli.test.ts (including that a pre-rename copy keeps the old marker) and update.test.js (restartCtx moves the spawn to the installed root, and leaves it alone when the update reported none).
  • What is not covered by a test: the real self-restart followed by a browser reload. Exercising it means killing a live CLI-managed instance mid-session, so the wiring is pinned by the pieces (withRestartPlan sets the flag and the sentence together; the hook's mounts drive the wait, the reload and the timeout through an injected clock and a stubbed window.location; the health payload is smoke-tested against a live server) and the assembled path is not.

Settings → Projects (workspace folders)

  • A workspace folder is a row in workspace_folders and nothing else. The name, the bound directory (project_path), the default model, the accent, the icon and the pin all live there, and every surface — the sidebar's header and menu, Settings → Projects, the skills/commands/agents scopes — reads that one table through the sidebar-structure signal. The retired omp_projects_config JSON is read once by migrateLegacyProjectSettings and never again; src/client/data/settings/project.ts now only holds the seed list that migration falls back to when that legacy row is not an array.

  • Every project field is a REAL write, validated server-side, and a refusal is NAMED. prepareProjectPatch (src/server/lib/workspace/project-patch.server.ts) enforces the four rules the form can violate: a name is required (the store skips an empty one, which used to show a cleared field over an unchanged row), names are unique case-insensitively (the sidebar identifies a workspace by name), a project_path must be an existing directory with ~ expanded exactly like POST /api/folders, and one directory belongs to one workspace (two rows list the same sessions and fight over the discovery tombstones). The refusals carry name_required / duplicate_name / directory_not_found / duplicate_path / invalid_icon, and the client reverts the row and shows the sentence — the pane used to log to console.error and let the next refresh silently undo the edit.

  • The name and the directory COMMIT on blur/Enter, never per keystroke. The old field wrote one PATCH per character, so a rename raced itself and the last response won regardless of order. The response's project is adopted (it carries the trimmed name and the expanded path), which is why the field a user typed into can come back different from what they typed.

  • A changed project_path re-syncs the discovery watchers. syncDiscoveryRootsWatch() is keyed by the bound roots, so a re-bind otherwise kept watching the OLD root and never picked up the new one until a restart — a skill written in the new workspace stayed invisible to a live session.

  • "Defaults for new chats" is provider:modelId, and the SPAWN reads it. The picker offers the live /api/models catalog (this route no longer serves its own hardcoded display-name list, and ModelEntry ids are not unique across providers, hence the composite). projectModelForCwd (src/server/lib/workspace/project-model.server.ts) resolves the folder for the spawn's cwd — exact match first, then the longest bound root that contains it, so a worktree of a project resolves to that project — and POST /api/agent/new consults it BEFORE Kabmo's global pick. Not selected and the legacy display names parse to null, i.e. "inherit", rather than to a model no provider serves. The pending composer shows the same value (usePendingProjectModel), so the pill and the spawn cannot disagree.

  • An icon must be something an <img> can render. customIconUrl accepts an uploaded data URL (png/jpeg/svg/webp/gif, ≤512 KiB) or an absolute http(s) URL; anything else — including a javascript: URI — is a 400. The client's generated mark is only saved after it LOADS (the old "discover favicon" button actually built a DiceBear identicon and saved the URL unverified, so an offline request overwrote the icon with a broken image).

  • Deleting a project is a dialog that names what disappears, and the session counts are read from the sidebar payload. The trash button used to delete immediately. The tombstone (deleted_workspaces) is what stops omp discovery from re-adding the folder on the next boot, and the dialog says so; the directory itself is never touched.

  • One icon map and one accent palette. src/shared/lib/workspace/project-icon.ts holds the glyph table the sidebar, the mobile row and the settings grid all iterate (PROJECT_ICON_OPTIONS), and src/shared/lib/workspace/project-accent.ts holds the swatches the route serves. The two halves had each drifted: default was a folder in the sidebar and an ✕ in the settings grid, and a colour added on one side was missing on the other.

  • A custom accent is a hex colour the palette does not contain, and the server checks that. The swatch row is a fixed table, but a user picks any colour through the native picker (<input type="color">) beside it; normalizeHexAccent reduces #ABC to #aabbcc so the stored string has ONE spelling — the sidebar compares it against the preset table to decide whether to highlight a swatch. The server refuses anything that is not #rgb/#rrggbb with invalid_accent, because the accent is painted straight into a CSS color: before this, accentColor: "red;background:url(//evil)" was stored verbatim and reached the sidebar's style. A custom accent is not a table entry — DEFAULT_CUSTOM_ACCENT (#7c3aed) is deliberately absent from PROJECT_ACCENT_OPTIONS, so "custom" never lights up a preset.

  • The custom control writes on COMMIT, and those listeners are attached natively. Dragging inside the system colour panel fires hundreds of input events and each commit is a PATCH carrying the whole project, so only the colour input's change and the text field's blur/Enter write. They are bound with addEventListener in an effect rather than through onChange/onInput props: preact/compat maps onChange onto the input event, so under the app's runtime a prop would commit on every drag tick — and a test file where compat is not yet loaded reports the opposite.

  • The Agents panel's project picker is a SCOPE. GET /api/settings/agents?root=<workspace> discovers <workspace>/.omp/agents through resolveRoot (the same gate skills and commands use), so a project's agents are reachable from the panel whose job is listing them; the selector used to offer three hardcoded names and read nothing.

  • The icon is TWO fields and ONE write. icon says which glyph, customIconUrl carries the image; sent as two PATCHes they race and the slower response decides the row, which showed up as an uploaded icon that saved and then reverted. useProjectSettings().updateFields sends a multi-field patch, and the grid calls it for every icon change (selecting a built-in glyph clears the custom URL in the same request).

  • A normal photo is not an error. The upload used to refuse anything over 512 KiB, which is smaller than a phone picture. The file is downscaled in the browser to a 128px PNG mark (fileToIconMark), and SVG passes through untouched; only an image the browser cannot decode is refused. The server still enforces the real ceiling (invalid_icon), so the client's limit is a convenience rather than the contract.

Clone this wiki locally