Skip to content

Plugins Skills and Automation

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

Plugins, skills and automation

Plugins (Settings → Plugins)

  • The panel is a view over omp's own plugin state, and every mutation is omp plugin …. omp owns four files — <dataRoot>/marketplaces.json, <scope>/plugins/installed_plugins.json, <scope>/plugins/omp-plugins.lock.json and the shared cache/{marketplaces,plugins}/ — and re-implementing a write whose format omp also reads at runtime would be a second source of truth for state omp reports. The Kabmo's own job is the two things the CLI cannot answer: WHICH features and settings a plugin declares (its manifest) and WHERE its runtime state lives (the lockfile of its scope). src/server/lib/omp/config/{plugin-registry,plugins,plugin-cli,plugin-actions}.ts, route src/server/routes/settings/plugins.ts, UI src/client/components/settings/categories/plugin-settings/.
  • A plugin id is not unique — the selection is (id, scope). The same name@marketplace installs into BOTH registries at once, and omp lists the user copy with shadowedBy: "project" while the project copy shadows it; the two differ in version, enablement, install path and shadowing. Selecting by id made them one row, so the pane could render the user copy and act on the project copy. pluginSelectionKey (plugin-settings/selection.ts) is the key the rows, the selection and every action name.
  • cwd is the scope selector, not a filter. omp plugin reads the PROJECT registry of the directory it runs in, so a workspace scope lists that workspace's project installs beside the user ones and the user scope runs in $HOME — which omp's own anchor walk deliberately stops before, because ~/.omp is the USER config dir. A project install issued from a user-scope cwd would land in the wrong registry. getProjectPluginsDir (core/paths.ts) is a faithful port of omp's resolveOrDefaultProjectRegistryPath (nearest .omp/, else nearest .git, else the cwd).
  • The user plugin root is the DATA root, not ~/.omp. getPluginsDir/getMarketplacesRegistryPath follow omp's DirResolver data category, so on an XDG install they are $XDG_DATA_HOME/omp/…. Reading ~/.omp/plugins unconditionally reports an empty plugin list there — the same trap agentDataSubdir documents for sessions. The condition is omp's own: the XDG app root must already EXIST.
  • A marketplace entry carries no manifest, and its runtime state is keyed by the PACKAGE NAME. omp plugin list --json reports { id, scope, entries } for a marketplace install, with no features and no settings; both live in the cached install directory, and its lockfile state sits under @local/manifest-plugin, never manifest-plugin@local-mkt. Reading the id against the lockfile reports "no features" for every marketplace plugin (measured), which is why readPluginPackageName exists.
  • Features are saved as ONE selection through --set, not as --enable/--disable. The add/remove pair cannot express "no optional features", so a plugin that started with features on could never be returned to omp's defaults. selected === null means omp is applying the features marked default, and that is what the draft starts from. A project-scoped install's features are read-only, because omp's features command resolves the plugin from its USER plugin root (getPluginsNodeModules()) and writes the USER lockfile: on a project-shadowed pair it reports success while the ACTIVE project selection is untouched (verified on 18.4.4 — features --set alpha wrote ~/.omp/plugins/omp-plugins.lock.json and left the project lock's enabledFeatures null). featuresEditable/featuresNote carry that to the pane, which renders the ladder without its save controls, and the route refuses the same request so a stale client cannot silently write the shadowed copy.
  • A plugin's SETTINGS live in the user lockfile in both scopes. omp plugin config set/delete go through PluginManager's single runtime config (getPluginsLockfile()) and have no --scope at all — the runtime reads them back the same way (getPluginSettings(name, cwd) merges that global map with the project overrides file). Reading the scope's own lockfile reports "no settings" for every project-scoped install (verified: a config set issued from a workspace cwd wrote the user lock and left the project lock's settings empty), so listPlugins reads values from the user lock in both scopes while enable/disable state still comes from the scope's own lock.
  • Features and settings are addressed by PACKAGE NAME, not by plugin id. omp's features and config commands resolve the plugin from its node_modules entry, so a marketplace plugin needs @local/manifest-plugin — a bare catalog name exits 1 with Plugin "<name>" not found (measured). PluginItem.packageName carries it; name stays the catalog name the user sees.
  • A secret setting's value never leaves the server. omp-plugins.lock.json stores plugin settings in plaintext and the pane is a browser surface, so pluginSettingState reports a secret: true key as present (secretSet) and omits its value — the pane can replace or clear it, never show it, which is also omp's own answer (config list masks it). The input starts EMPTY rather than prefilled with a placeholder a careless Save would write back literally.
  • --json is not honoured by every omp plugin verb. install, marketplace add/remove/update and upgrade ignore it and answer on stdout as text, reporting failure on stderr with exit code 1 — so runPluginCli returns both streams and pluginCliError prefers stderr. A caller reading stdout alone reports every failure as an empty success. omp's own sentence is surfaced verbatim ("Plugin "nope" not found in marketplace …", "is installed in both user and project scope"), because it names the missing marketplace or the ambiguous scope, neither of which Kabmo could reconstruct.
  • Every mutation answers with the whole panel payload, and the server re-reads omp's registries. Installing moves the catalog's installed flag and can add a lockfile entry; uninstalling can drop a cache directory another scope referenced; an upgrade changes the version a second scope sees. Adopting the response verbatim is what keeps one source of truth.
  • A scope flag rides along only when it can matter. The uninstall/enable actions send --scope for a marketplace plugin (whose id can exist in both registries), and nothing for a package plugin (npm/git/link), which omp resolves by name against the active project root first and the user root second — the flag is only honoured on the marketplace path. Features and settings carry the panel's scope instead, because that is the cwd those two commands resolve in.
  • reloadLiveSessions() runs after every accepted mutation. omp discovers plugin capabilities once per process, so a newly installed plugin's skills and commands are invisible to a running session until /reload-plugins — the same refresh the Skills panel performs after a SKILL.md write.
  • MOCK mode answers a deterministic four-plugin dataset (src/client/data/settings/plugin.ts) covering every render shape: a marketplace plugin, a project install with an update available, a shadowed disabled user copy, and a plugin with no omp manifest at all (conventional skills/ content only).

Kabmo plugins (Settings → Plugins Kabmo)

  • A plugin is a package with two halves, and either may be absent. kabmo in package.json (or kabmo.json) names app (the ESM bundle the host import()s into its own Preact tree) and/or server (the factory Kabmo's process calls). A server-only plugin is legitimate: a background job that owns storage and answers RPC but draws nothing. The manifest is src/shared/types/panels.ts; the loader is src/server/lib/plugins/loader.server.ts.
  • A plugin declares settings in settings-schema.json, and Kabmo renders the form. The file is an optional map of name → { type: 'string'|'number'|'boolean', label, description?, default?, secret? } at the plugin root; the host draws it behind the sliders button on the plugin's card, and the same definitions validate every write (src/server/lib/panels/settings-schema.server.ts, route /api/panels/settings/:plugin, UI panel-plugins/SettingsModal.tsx). It is read from disk, not from the running plugin, so a disabled or unbuilt plugin still shows and saves its settings — that is why the scan keeps a directory map for every parsed manifest (pluginDirs, distinct from the servable dirs). A schema that exists but does not parse is a rejection in the pane, not an empty form. A secret is write-only: the server returns only the marker (PLUGIN_SECRET_MASK), an untouched field is omitted from the PUT, and the server drops the marker rather than storing it. The manifest's inline settings key is still read when the file is absent.
  • The server half is namespaced by the host, not by convention. storage, settings, rpc, http, realtime, events, background and mcp all bind the plugin's own id before they reach SQL or a registry, so a plugin never holds a string it could point at another plugin's rows. Disposal is exact-once and LIFO; every registry the plugin wrote to is cleared on disable/removal.
  • background.service starts at declaration; background.schedule is fired by Kabmo's clock. The split is deliberate: a service that needed the loader to begin would not exist for the first tick, while a schedule that owned its own timer would leak one per reload. src/server/lib/plugins/schedule-runner.server.ts is the ONE consumer of LoadedPlugin.background.schedules — a 15 s process-wide tick anchored on globalThis, serial per pass, advancing each schedule with the shared grammar (@/shared/lib/schedule/parse). The fire time is a ROW (plugin_schedules), not just memory: the loader adopts a stored time at declaration, and a tick claims it by writing a -1 sentinel before computing the next fire, so a restart keeps the countdown, a server that was down for three intervals runs the job once, and two instances on the shared database cannot both fire it. A -1 left by a crash is due on the next boot. service.stop runs on disposal (reverse order, one failure does not skip the rest) — it is not a disposer, so the loader has to call it. Measured bug this fixed: the runner did not exist, so the bundled session-info (5m) and stats (1h) schedules were recorded and never fired; a plugin author's only working periodic option was a service that owned a timer the host could not see. A run that throws is logged under the plugin's own name and the schedule still advances; a cron with no next fire is parked at Infinity rather than spinning.
  • MCP is a contribution, not a process. api.mcp.register({ id, transport, command/args/env | url/headers }) adds a server to the list every session receives; the host owns delivery, so a plugin never learns which harness the user picked and a reload cannot leave a second child behind. A malformed declaration (no command for stdio, no url for http) is refused at load by name. The name agents see is <pluginId>:<id> unless the plugin states one.
  • One MCP list, two deliveries. src/server/lib/mcp/registry.server.ts merges native user mcp.json, the project's .omp/mcp.json, the app-local settings rows and plugin contributions, first name wins — the same precedence the settings pane shows. src/shared/lib/harness/mcp-facts.ts names the delivery per harness: every ACP harness receives the list on session/new|load|resume|fork (mcpServers), while omp-rpc reads ~/.omp/agent/mcp.json at spawn. Measured bug this fixed: the ACP spawn passed mcpServers: [] hardcoded, so a server configured in Settings reached exactly one harness — the one that happened to read the same file. The list is read per spawn, so a new server reaches the next chat without a restart; omp's file delivery still needs a respawn.

Skills (Settings → Skills, composer / popup)

  • Skill discovery delegates to omp, it is not re-implemented here. discoverSkills (src/server/lib/omp/config/skills.ts) runs omp skill list <dir> --json — omp's own resolver, so it reports exactly what a session in that directory would load. A hand-rolled scan of ~/.omp/agent/skills + <cwd>/.omp/skills is what it replaced, and it silently disagreed with the agent in both directions: it listed 6 skills where omp loaded 9, and it could not see ~/.agents/skills, .claude, .codex, .github, .opencode, plugin packages or the Skillshare store (~/.omp/skillshare, source skillshare:@scope/name@version). It also re-derived frontmatter rules it could not keep in sync — a missing description makes omp skip a SKILL.md entirely, and hide/disableModelInvocation keeps a skill runnable but out of the model's <skills> listing. One CLI call (~0.4 s, no session, no model) answers all of it, cached 5 s per directory (invalidateSkillCache after every write).

  • A skill is only editable where Kabmo is the owner. managedSkillRoots is ~/.omp/agent/skills plus <workspace>/.omp/skills, and managed is true only for an native:* skill sitting directly under one of them. Everything else — a Skillshare package in ~/.omp/skillshare, a Claude plugin — renders read-only and its DELETE is refused by name, because Kabmo is not the tool that put it there. The detail pane shows the source path instead of an editor it must not save through. A Skillshare skill still gets an Uninstall action: the package is the user's install, and omp skill uninstall -g @scope/name is the counterpart of the catalog install (uninstall_registry_skill in the skills route).

  • Create/save/delete are real SKILL.md files (writeSkillFile / deleteSkillDir), not rows in an app_settings list. The old "custom skill" wrote only to Kabmo's own store and omp never read it: the panel offered a save that changed nothing, and deleting it removed a record while the skill (or nothing at all) stayed as it was. A rename or a scope move (user ⇄ project) removes the previous directory, which is why writeSkillFile takes previousDir rather than a name — resolving the old path from the new scope silently left the source copy behind (verified: a user→project move left both).

  • The catalog is omp's own Skillshare registry, not a second one. searchSkillCatalog runs omp skill search <q> --json (so the registry URL is omp's skills.registryUrl), installCatalogSkill runs omp skill install -g @scope/name -y, and uninstall/update are the matching omp skill uninstall -g / omp skill update -g. The row's repoTag is the package spec (@scope/name), which is what every action names — the display name is not unique across packages. Measured on 18.20.0: the search answer is { total, page, perPage, hits: [{ scope, name, version, description, weeklyDownloads, publisher: { username } }] }, and the install records the package in ~/.omp/agent/skills.json with its store under ~/.omp/skillshare. The Browse tab starts EMPTY because the CLI exposes no "popular" listing; a pre-fetched query the user never typed is a list they cannot explain.

  • A catalog source is a REAL git repository, and its count is a real scan. A source used to carry stars, updatedAt and a skillCount that no request had produced ('1.2K', 'Just now', 3), and "Add your own source" posted { catalogSources: [...] } — a body the route had no branch for, so it answered 400 Unsupported skill action behind a .catch(console.error) and the card vanished on reload. SkillCatalogSource is now { id, name, repo, skillCount: number | null, scannedAt }, add_source/remove_source/scan_source are real actions with a duplicate-repo 409, and skillCount is null ("Not scanned") until scan_source writes the number inspectSkillRepo measured. src/server/lib/omp/config/skill-sources.ts is the single reader/normaliser, so the old literals are dropped on read instead of leaking through a narrower type.

  • Import from an arbitrary repository inspects by CLONING, not by asking a CLI. A CLI listing prints a human tree (measured: 60+ wrapped lines for anthropics/skills) and has no machine shape to parse. skills-git-repo.ts clones --depth 1 into a staging directory, reads every SKILL.md's frontmatter itself (conventional skills/, plugins/, root, then a depth-4 walk), and always rm -rfs the clone in a finally. An entry with no description is reported loadable: false — omp skips such a file outright, so listing it as installable promises a skill that never appears.

  • A repository install has ONE target: a managed copy. installSkillCopies copies the skill directory WHOLE into a root Kabmo owns (~/.omp/agent/skills or <workspace>/.omp/skills), which is what makes it editable and deletable in the pane afterwards. The old registry mode ran bunx skills add into ~/.agents/skills — a second registry and a second tool, and an arbitrary repository is not a Skillshare package, so omp skill install cannot express it. The managed copy refuses a name with a path separator, refuses to overwrite an existing directory unless overwrite is set, and reports every refusal PER SKILL (skipped: [{name, reason}]) so one collision cannot abort a batch of twenty. A local path is its own source key — its last segment would make two checkouts both named repo one source, and the stored value is fed back to git clone, which cannot resolve a bare directory name (measured: the source saved as repo and the next scan failed).

  • The catalog's search box queries the registry. It used to filter the ~26 rows the loader had pre-fetched, so a query the catalog really held answered "no skills found" — a false negative indistinguishable from an empty registry. search_catalog calls searchSkillCatalog (debounced 300 ms client-side), and an empty query restores the loader's own (empty) list rather than leaving the last search's rows on screen.

  • The skills pane edits only the BODY. The pane's own fields own name/description/hidden, and writeSkillFile serialises the frontmatter; a draft that carried the original frontmatter in its body therefore produced a SKILL.md with two frontmatter blocks. draftBody strips it on load and on save, and pane.test.tsx pins that a saved body contains no ---. Save is disabled while the draft equals disk (the pane used to rewrite an unchanged file), a missing description is a BLOCKING error rather than a hint, and a read-only skill renders no editor or save at all rather than a paragraph below an enabled button.

  • omp discovers skills once per process, so a write is followed by a reload — and the reload reaches EVERY live process, including a busy one. A SKILL.md that lands while a session runs is invisible to that session until it restarts (measured: get_available_commands kept reporting 8 entries after a ninth was written). reloadLiveSessions (src/server/lib/omp/session/reload.server.ts) sends /reload-plugins — omp's only refresh, reachable as a prompt because the builtin has a text-mode handle — and it broadcasts to the per-session children AND the pooled utility processes (which answer the composer's / popup). The isBusy() skip is gone, and its premise was wrong. The old guard reasoned that a prompt dispatched into a running turn is a queue insert; measured on omp 18.4.3, it is not. A /reload-plugins sent mid-turn is answered from omp's command loop in 16-40 ms with the turn still streaming — and with a blocking approval dialog parked (get_state, get_available_commands and the reload all answered within 16 ms; the RPC loop is independent of the turn waiting on the dialog) — after which the turn completes normally and the new skill is listed immediately. A PLAIN mid-turn prompt is neither queued nor injected: it is dropped outright (one agent_start for two prompts). The guard was actively harmful, because the common case IS a busy session: create-skill writes its SKILL.md with a tool WHILE the invoking chat streams, so the write landed during a run and the refresh was skipped — leaving the new skill invisible until the user found the manual ⟳ button (verified against a live Kabmo: absent from get_available_commands after the turn ended, present the moment a session reloaded). Verified on 18.4.3 it answers agentInvoked: false (no model turn) and leaves the session file byte-identical, and a burst of triggers coalesces onto one in-flight pass. Verified end to end: creating a skill through the API took a live session 9 → 10 skill entries with no restart, deleting it took the session back to 9, and a hand-written skill mid-turn was listed while the turn still streamed.

  • A SKILL.md written by anything OTHER than Kabmo is watched for, not polled. The root set is ONE table, src/server/lib/omp/config/discovery-roots.ts, shared by locateCommandFile and the watcher — they were written separately and the watcher's copy was short by every root but the omp-native pair, so a skill added to .claude/skills, .codex/skills, .opencode/skills, .agents/skills or .github/skills in a live session was never noticed. The set is measured against omp 18.4.3, not assumed: the project roots are those six, the user roots are ~/.omp/agent/skills and ~/.agents/skills, and ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills and ~/.opencode/skills were verified NOT read — do not add a root on the strength of its command counterpart (omp does read ~/.claude/commands and friends). Skills and commands share the project roots; .github differs by layout (.github/prompts/*.prompt.md for commands) and ~/.agents/skills is skills-only. src/server/lib/omp/config/roots-watch.server.ts watches those roots for the user scope, for each registered workspace, and for each LIVE session — a session can run outside every registered workspace (a folder opened straight from the sidebar, the app root) and omp still resolves project skills from that cwd (verified: without this, a SKILL.md written into such a session's own .omp/skills was never picked up). It refreshes every live child 250 ms after a change (one reload per burst). The alternative — re-running omp skill list on a timer per workspace — spawns a process per tick to answer a question that only changes when a file does. Three rules make it work. A root that does not exist is never created (Kabmo must not write .omp/skills into a user's repository just to watch it): the nearest existing ancestor is watched instead, and the change that creates the real root triggers a re-sync, which re-attaches it RECURSIVELY. omp also reads project skills from every ANCESTOR of the cwd, up to the enclosing git repository — measured on 18.4.3: from /tmp/walk/a/b/c with no .git anywhere it reported the skills of all four levels, an empty .git at a/b cut it to that level and below, a .git FILE (worktree/submodule) stops it the same way, and $HOME is NOT a boundary (the walk crossed it, and ~/.omp/skills was never read). skillRoots() therefore appends <ancestor>/.omp/skills for each level, managed: false so Kabmo's write/delete paths stay scoped to the cwd's own root. Without this, a skill written into the ancestor a session actually resolves was invisible (verified: a session in /tmp/anc/sub saw a-parent from /tmp/anc/.omp/skills but never a-late added later). Only a genuine root is watched recursively, and a BRIDGE is watched not at all in the sense that matters: the nearest existing ancestor of a missing root can be ~/.omp/agent or a whole workspace, so a bridge firing only re-syncs — it never reports a change itself. Reporting those as reloads produced 170 broadcasts in 20 s on an idle machine and, worse, MASKED the ancestor gap: the skill appeared to be picked up by the watcher when it was only being re-read by a broadcast an unrelated file had triggered. Two further rules close timing holes a filesystem watch cannot: a root attached for the first time owes one delayed pass (the OS registers a recursive watch ASYNCHRONOUSLY, so a file written in the instant after a session spawn raises no event — verified: the skill was missed, and picked up once the attach settled), and a pending reload is never downgraded by a bridge pass in the same debounce window (the reload a root attach scheduled was overwritten by an unrelated directory's traffic before it ran). And the reconcile is idempotent and serialized, because bun --hot re-runs the server entry: a duplicated watcher would double every broadcast. The watcher set itself is anchored on globalThis for the reason the database is — a bun --hot module re-evaluation would otherwise orphan the previous fs.watch handles with no way to close them (confirmed: with the binding anchored in the module, a hand write stopped reaching the session after a hot reload; anchored on globalThis, it survived). It is reconciled at boot and on every workspace create/delete (POST /api/folders, .../delete), so a workspace added mid-session is watched without a restart. fs.watch({recursive:true}) costs no descriptors on Bun/macOS (measured with the repo's own countOpenFileDescriptors: zero delta for three recursive watchers over 42 entries).

  • Both panels and the composer are scoped to one omp scope at a time. resolveDiscoveryScope (src/server/lib/omp/config/scope.ts) turns the request into a cwd: ?scope=user asks the agent dir (~/.omp/agent), ?root=<workspace> asks that workspace, and neither keeps the historical app-root meaning (the composer's fallback for a session with no workspace folder, where omp itself spawns in the server's cwd). resolveRoot still gates a client-supplied ?root= (app root, a path under it, or an exact registered project_path), and an unresolvable root falls back to the USER scope rather than to a directory the caller never asked about. The cwd is the whole point: omp resolves project skills and commands from the process cwd — a child in $HOME reported 7 skill entries and one file command, the same child in this repo reported 9 and its own .omp/commands — which is also why the utility RPC is pooled per cwd (runUtilityCommand(command, timeout, cwd)), so a home-scoped pool entry serves the registry queries while a workspace read gets its own. The composer's cache is keyed command::<root> and invalidateComposerCache matches that prefix, so available_commands_update still clears every workspace's copy.

  • A write lands in the scope the panel is showing, and a new draft inherits it. The save carries the scope (scope/root on the POST body) and the draft's own location picks the root, so a create made while a workspace is selected writes <workspace>/.omp/skills; the panel passes defaultLocation for that, because a new draft used to open as user and a project skill created from the workspace scope was written to ~/.omp/agent/skills — it then vanished from the list being viewed. A project write with no workspace is refused server-side rather than landing somewhere the user did not pick, and only the omp-native roots are writable at all (managedSkillRoots, locateCommandFile's managed flag): everything else renders read-only, keeps its Save hidden, and its DELETE is refused by name.

  • The commands panel reads omp's own list, and finds the file behind a name itself. get_available_commands reports the name, description and hint but never a path, so withCommandFile → locateCommandFile looks the name up in every root omp reads (.omp/commands, .claude, .codex, .agents, .opencode, .github/prompts — the last with its .prompt.md suffix); a name with no file is a builtin, a skill:<name> entry or an extension command and is isBuiltIn: true, managed: false. Only <workspace>/.omp/commands and ~/.omp/agent/commands are managed. A name present in both roots resolves to the PROJECT file, which is what omp runs (measured), so the lookup checks the workspace first and a delete can only reach the two managed roots.

  • The panels' project picker lists real workspace folders (useWorkspaceRoots → /api/settings/projects), not the hardcoded kabmo/workspace-edge placeholders it used to offer: those sent a root the server could not resolve, so choosing one changed nothing. Each option's value is the folder's project_path, which is what the API takes as ?root=, and rootFor resolves an option by id OR value — the dropdown emits the value through onChange, so an id-only lookup silently answered the user scope for every workspace while the trigger still printed the folder's name. Both the Skills and the Commands panel share the hook, the trigger-label resolver and the scope query.

Side Questions (BTW panel)

  • /btw [question] typed in the main composer replaces the composer with the side-question panel (src/client/components/workspace/btw-panel/, swapped in by ComposerDock, opened by the omp:btw window event; the mode state machine is src/client/hooks/chat/btw/mode.ts); bare /btw opens it on the current history. The open flag is deliberately NOT persisted (useState, not useSessionState): a panel that reopened itself on load left the user with no chat composer and a field they never asked for, and a /btw typed into that field became a real question to the model. The panel is a mode the user enters, so every load starts in the chat — while the drafts and the selected topic do persist (chat.btwAsk / chat.btwFollowUp / chat.btwTopicId), so leaving and re-entering loses nothing. The panel is two cards: the panel card — the ask card as its header (the field that starts a new topic, plus ⟳ start over, ⌄ topic history, ⧉ promote into chat, ✕ leave), the running turn's GeneratingIndicator, and the topic's turns as its body — and the composer below it for follow-ups. The ask field must stay a header rather than a free-standing card above the composer: as its own card it read as a second composer and users typed follow-ups into it. The answer card is capped at 520px (ANSWERS_MAX_HEIGHT_PX) with its own scrollbar, and the header stays visible while the body scrolls.
  • The panel renders the CHAT's timeline, not a btw-specific one. A turn's messages are ChatMessageData — the same shape the chat timeline folds — so BtwMessages builds one row list (each question as a user row, then that turn's conversation) and hands it to the chat's own MessageList. A tool the side child runs therefore draws the same card it would in the chat, and thinking / usage / errors come along; the two renderers cannot drift. On the server the conversation is accumulated by trackTurnMessage (src/server/lib/btw/lifecycle.server.ts) through the shared toChatMessage mapper, with the SAME by-id upsert the chat stream's onMessageUpdate performs (omp emits one frame per segment carrying that segment's full accumulated content). BtwTurn.answer stays as the plain-text summary (history labels, promotion titles) and is the fallback for a turn stored before the conversation column existed.
  • The run footer's token counts come from message_end, not the streaming frames. omp's message_update frames report usage zeros; only the completed message carries the real counts, so handleFrame upserts message_end too — as a COMPLETED row (toChatMessage(record, false), the same flag the chat stream passes), because mapping it as streaming left thinking.isGenerating true on every stored turn: each reload reopened the accordion and pulsed it over a finished answer. Dropping that branch is silent: the footer renders without its … tok segment. The row's thinkingLevel comes from the chat's transcript (loadSessionThinkingSelector), not from get_state — that reports the level the child RESOLVED, and storing it would pin an auto chat to a concrete effort on every later spawn.
  • BtwState.live carries the running turn, not just frames: a client attaching mid-turn (a reload, a second tab) would otherwise get a snapshot whose running turn has no persisted messages yet and would show an empty answer while the child streams on. The btw_message / btw_activity frames drive the live upsert; the state is the seed. The child echoes the <btw>-wrapped prompt it received, and the panel drops that user echo (it already renders the user's own question).
  • The indicator's verb is the side child's own. btw_activity carries it, derived server-side from that child's frames (describeAssistantPhase / describeToolActivity) — the chat's verb describes a different process and must never be borrowed. PHASE_VERBS.sideQuestion ("Answering side question") is the honest fallback before the child reports anything, since the side stream cannot tell reasoning from prose.
  • The child ECHOES the prompt it received, and that echo is the <btw> wrapper the panel itself built, so it is filtered out of the rendered rows — the panel draws the user's own question instead. A legacy turn's plain answer is rendered only when it has no stored conversation.
  • The panel has NO model / thinking / access pickers. A side question runs on the CHAT's model and thinking selector, and every ask re-reads both from the parent transcript (loadSessionModel / loadSessionThinkingSelector) — a chat that switched model or level is mirrored by the next question, and a live child is re-targeted over RPC before the prompt (BtwRuntime.retarget). That is omp's own shape: its side turn reads request.session.model at run time, so the TUI panel has no pickers either, and Kabmo's per-topic set_model / set_thinking_level / set_access_mode actions are gone. showModel/showThinking/showAccess on ComposerToolbar (all off for BtwForm) is what keeps the composer's own selectors out of the side-question card without forking ChatInput.
  • omp's /btw is TUI-only, so Kabmo implements it. Its registry entry in omp 18.2.6 has handleTui and no text-mode handle, and RPC dispatch only runs entries with handle — sending /btw … as a prompt would reach the model as literal text. Client interception lives in src/client/hooks/chat/timeline/actions.ts; server behaviour in src/server/lib/btw/. Because get_available_commands cannot advertise it, the composer's / popup gets its entry from Kabmo-owned pool in src/shared/lib/chat/composer/client.ts (CHAMBER_COMMANDS, byte-identical to omp's own description and [question] hint) — never from omp's list.
  • Context arrives by transcript reuse, never by re-prompting it as text. A topic owns a private copy of the parent session file (<db dir>/btw/<sessionId>/<topicId>/session.jsonl) taken on its first question; the side child is spawned as omp --mode rpc-ui --resume <that copy> --no-title --no-tools (src/server/lib/btw/child.server.ts builds the argv). This is the one parity gap that cannot be closed: omp's side turn runs IN PROCESS over the live this.messages (including a message still streaming), while Kabmo resumes a file snapshot — there is no RPC for an ephemeral turn, so a side question here sees the parent as of the snapshot plus its own turns, not the parent's in-flight work. The parent's prompt-cache prefix survives, the parent file is never written (verified: byte-identical after many questions), and a follow-up after the child was reclaimed resumes the copy and still sees every earlier turn.
  • The side child runs WITHOUT tools (--no-tools), which is what omp's /btw effectively is. omp's TUI does not pass --no-tools (that is a CLI flag for a whole session) — it runs the side turn through runEphemeralTurn, which keeps the tool catalog attached only to hold the prompt cache warm, tells the model in a <system-reminder> that tools are NOT available, and DISCARDS any tool call the model emits anyway (agent-session.ts filters toolCall blocks out of the final message). --no-tools reaches the same end state from the CLI: no catalog, so nothing can execute. Verified against omp 18.3.2 on a resumed transcript that already carries 384 tool results: toolNames empty, zero tool calls emitted, zero executions, the turn completed normally. There is therefore no approval gate to park on and no dialog path: PendingUiDialogs, BtwState.dialogs, ExtensionDialog in the panel, and the dialog_response action are all gone. withoutToolCalls in lifecycle.server.ts drops a toolCall block that arrives anyway (a hallucinated call against the catalog omp would still attach), mirroring omp's own filter.
  • One side question in flight per session — no implicit queue, no implicit cancel; a second question is refused (btw_busy, 409) exactly like the TUI. A new question is its own topic; only the panel's composer continues the active one.
  • State and streaming: btw_topics/btw_turns in Kabmo DB (schema in src/server/lib/btw/schema.server.ts; thinking_level/approval_mode are added by the additive column migration there, because CREATE TABLE IF NOT EXISTS leaves an existing table alone — approval_mode is retained for rows written while a side child ran with tools and nothing writes it now, and thinking_level holds the chat's SELECTOR, auto included). A turn's status vocabulary is omp's own (running/complete/cancelled/error/interrupted; a row written as failed is migrated by ensureBtwSchema), and the stored answer summary is bounded the way omp bounds its side replies (src/server/lib/btw/reply.ts). The server is the source of truth and every frame is a snapshot (btw_state, carrying the live turn) or a delta (btw_message / btw_activity). Commands: POST /api/btw/:sessionId (ask/abort/promote/delete), stream: GET /api/btw/:sessionId/events + WS /:sessionId/ws. Unlike the agent stream this one is NOT observer-only: history must be readable while no omp child is running, so reading the state also repairs running rows whose runtime is gone.
  • Promote materializes the topic as a session of the chat's own: the copy is written beside the parent under a fresh id, carrying parentSession and a title slot padded to exactly the SESSION_TITLE_SLOT_BYTES - 1 bytes omp rewrites in place, with the <btw> boilerplate unwrapped so the promoted chat shows the question the user actually asked. It is refused while a turn runs, while the CHAT is streaming, for a topic with follow-ups (btw_multi_turn — omp's branch carries one question/answer pair and refuses multi-turn history), and once the parent transcript has moved past the snapshot's leaf (omp's own /btw branch guard). That leaf is written where the snapshot is taken (BtwRuntime.openWorkspace → setBtwTopicLeaf); it had lost its writer in the tools change, so readBtwTopicLeaf always returned null and the guard could never fire — rows created before the fix keep a null leaf and are not guarded, since their snapshot entry cannot be reconstructed.

Scheduled Tasks (sidebar Calendar button)

  • The Kabmo owns the clock, because omp has none. src/server/lib/schedule/runtime.server.ts runs ONE process-wide setInterval (20 s, anchored on globalThis like the database handle and the terminal registry — a bun --hot reload must not leave a second interval running). Each tick claims every task due at now and dispatches it. The Calendar button in both sidebars used to open a mock dialog: a textarea with no state, a "Schedule Task" button that only closed the window, and decorative kind/interval controls.
  • A fire is a normal prompt through the normal spawn path. runScheduledTask opens a child with startNewRpcSession (fresh conversation) or startRpcSession when the task names a sessionId, sends the task's model snapshot (set_model / set_thinking_level), then prompt — exactly what a queued follow-up delivery sends. Nothing bypasses the registry, so the approval mode, the idle reaper and the stream-status row all behave as they do for a user-initiated prompt. Verified end to end on a real server: a once task and an every 1m task each produced a real omp session whose transcript reads user: <prompt> / ai: <answer>.
  • A claim is a WRITE, and it advances the schedule in the same transaction (claimDueTasks). That is what makes two ticks — or two Kabmo instances on the shared database — safe: the second sees the row already moved past its own now and takes nothing. A once task is disabled by its own claim (next_run_at = NULL, enabled = 0) rather than by the dispatcher, so a one-shot whose dispatch failed cannot resurrect on the next tick or on a restart.
  • next_run_at is stored, not derived. A once task's fire time IS its spec, a paused task has none, and a spent one-shot is a third state — none of which a re-parse could distinguish. The task list renders them differently on purpose: Paused versus Ran once — no next run versus a real Next <time>.
  • Editing a schedule or resuming a task RECOMPUTES the clock from now (updateScheduledTask). Keeping the pending value would fire once on the cadence the user just replaced (a 1h → 1d edit), and re-enabling a paused interval task would fire immediately for every interval it spent paused.
  • The run record is the only place a failure exists. A task is claimed before it is dispatched, so a spawn that throws can never be retried by a later tick; finishScheduledRun writes error + the message and the modal renders it under the row. A manual "Run now" is recorded with countRun: false, so testing a task does not inflate its fire count, and it deliberately does NOT move next_run_at — the user is asking "does this work", not asking to skip the scheduled fire.
  • One grammar, shared by the form and the runtime (src/shared/lib/schedule/parse.ts). every takes 30s/5m/1h30m/2 days; cron takes 5 fields with *, N, a-b, a,b,c, star-slash-n and a-b/n. Two rules are load-bearing and unit-tested: when BOTH day-of-month and day-of-week are restricted the day matches if EITHER does (Vixie cron — 0 0 13 * 5 fires on the 13th AND every Friday, not only Friday the 13th), and nextCronOccurrence walks DAYS with whole-month skips (a 0 0 29 2 * is 1461 day-steps away; a minute walk would be 2.1 M iterations and an impossible date such as 0 0 30 2 * reports "never" rather than hanging). The next fire is strictly AFTER the cursor, so a task that fires at exactly its own lastRunAt advances instead of re-firing forever. The 1-minute floor is enforced because the tick is 20 s.
  • A cron expression is a WALL-CLOCK statement, so every task stores its IANA zone (timezone, resolved at write time to the server's zone when the request names none). src/shared/lib/schedule/timezone.ts resolves wall times through Intl.DateTimeFormat with the standard two-pass offset: a spring-forward gap returns null (the fire is skipped, not shifted) and a fall-back overlap resolves to its first occurrence. A container is usually UTC, so interpreting 0 9 * * * with Date's local getters fired a "morning" task at the wrong hour for every user east or west of Greenwich. The schedule topic carries serverTimeZone so the editor's new-task default and preview use the server's clock, not the browser's. A legacy row with no zone reads as the server's zone — the behaviour it had.
  • A manual "Run now" is single-flight per task. runScheduledTask counts in-flight runs in the runtime slot and isTaskRunning is the route's 409; a second click (or a click while the scheduled fire is still dispatching) would otherwise spawn a second omp session for the same prompt. A scheduled fire is NOT refused — its claim already advanced the clock, so skipping it would lose the fire.
  • The modal validates with the same parser it previews with (TaskForm), so the form cannot accept a spec the route would refuse — and the route validates again (createScheduledTask/updateScheduledTask), because a stale client is always possible. Verified in the browser: 30s renders "The shortest interval is 1 minute.", a red border and a disabled submit; a valid 2h renders "Next run in 2h · ".
  • A task names its harness, and the harness decides the transport. ScheduledTask.harness (omp-rpc by default) is a spawn-time property: openDispatchTarget branches to startAcpSession for anything else, and the model/thinking picks are applied by the ACP handshake instead of set_model/set_thinking_level. A resume reuses a recorded harness_sessions row only when its harness matches; an omp session id means nothing to claude, so a foreign row starts a fresh conversation. The form's harness/model/thinking/access fields read the SAME catalog the composer does (harnessModels), so a task cannot offer a model the agent would refuse.
  • The model snapshot is resolved SERVER-side when the request carries none (resolveDefaultTaskModel), and only for omp-rpc: the composer's persisted pick plus the persisted access mode. An ACP task with no model starts on that harness's configured default. A harness change without an explicit model drops the snapshot, because an omp model id means nothing to an ACP agent.
  • The cwd is resolved at WRITE time and stored on the row (resolveTaskCwd → project_path else the folder name). A folder deleted after the task was created must still let it fire in the directory it was created for; storing only the folder id would leave the runtime falling back to the server's own cwd, which is how a scheduled job silently runs in the wrong project. No folder chosen means the server's cwd, and the form says so ("Server default directory").
  • State lives in scheduled_tasks / scheduled_task_runs (src/server/lib/schedule/schema.server.ts, called from initSchema beside the BTW tables). Runs are capped at RUN_HISTORY_LIMIT (50) per task, pruned after each close, or an interval task would grow the table without bound. API: GET/POST/PATCH/DELETE /api/schedule (?id= for the single-task verbs, ?id=…&run=now to fire immediately) and GET /api/schedule/:taskId/runs.
  • The toolbar badge is a derived read, and it follows the write. useScheduledTaskCount reads the schedule realtime topic — the same one the modal reads, so the badge cannot disagree with the list and a mutation reaches it with no event and no poll. Verified live in the browser with no reload: 4 armed → pause a row → 3 armed, and the count survived a full server restart (the row is the state).
  • The runtime's dependencies are INJECTED (ScheduleDeps), never mocked through mock.module in tests. mock.module swaps a registry entry for the whole bun test run: mocking the RPC manager in runtime.server.test.ts broke six unrelated suites with "Export named … not found" (measured), which is why runScheduledTask(task, { deps }) takes them and runtime.server.test.ts drives the real dispatch logic with a fake session handle.

Waiting for Another Session (composer, new chats only)

  • A held prompt is a SERVER row, not a client timer. src/server/lib/waiting/ owns it (waiting_prompts, created by ensureWaitingSchema from initSchema) for the reason the scheduled tasks are server-owned: a prompt that waits must survive a reload, a closed tab and a second Kabmo instance. runtime.server.ts is the clock — a 5 s tick plus two event triggers — and store.server.ts's claimWaitingPrompt is the whole concurrency answer: the UPDATE that flips waiting → dispatched reports whether it won, so two sweeps (or two instances on the shared database) can never spawn two sessions for one prompt.
  • "Finished" is five conditions, and finish alone is not one of them (waiting/settle.ts). The stream row must not be stream; a live wrapper must not be isBusy() (a compaction, a subagent or an open ask dialog keeps it busy with no row to say so); the dependency's follow-up queue must be empty; no delivery slot may be armed for it (the run end arms one 500 ms out); and its last status write must be older than SETTLE_GRACE_MS (1.5 s), because CURRENT_TIMESTAMP has one-second resolution. That clock is read by waiting/row-clock.server.ts, NOT carried on SessionStreamState — that payload is the sidebar:status wire contract and its exact shape is pinned by stream-state.server.test.ts, so a field added for one caller would ride every frame for nobody. Each condition is a measured way a prompt would otherwise be delivered into a running turn — where omp refuses it and the message is lost. A row with NO stream entry counts as finished: nothing can be waited on, and holding the prompt forever would be worse.
  • The dependency is a session ID, re-read at every sweep — never a snapshot of its state. A session that looks finished picks up a queued follow-up a moment later, and the two triggers exist for exactly that: a terminal agent_end (requestWaitingSweep in terminal-settle.ts) and the queue's own drain (delivery.server.ts). Both go through waiting/sweep-trigger.ts, a globalThis slot, because the runtime already imports the queue and a direct edge back would close a cycle.
  • The session's send is passed as a CLOSURE, never as a detached method. The wrapper reaches its runtime state through this; applyModelSnapshot(session.send, …) ran it against undefined and every prompt failed with undefined is not an object (evaluating 'host.restarting'). Pinned by a test whose fake session is an object METHOD and asserts the receiver survives.
  • A failed dispatch is retried, then REPORTED (MAX_DISPATCH_ATTEMPTS 3). The prompt is returned to waiting while attempts remain — nothing was delivered, so it is still wanted — and failWaitingPrompt accepts a row that was already claimed, because a spawn that succeeded and a delivery that then threw has still failed. Deleting the dependency fails every prompt waiting on it by name (failWaitingOn in delete.server.ts), rather than leaving a row waiting for a session that no longer exists.
  • The prompt is assembled by queue/payload.ts, shared with the follow-up queue. Both send a prompt nobody typed in this tab, from the same persisted shape (an attachment's bytes live in dataBase64, its text in content — the live File never survives the row). A second copy is how one path inlines a text file and the other sends a bare filename.
  • The picker lists only sessions with a run in flight, and the STATUS MAP is that list (WaitingDependencyPicker, beside the workspace picker in EmptyWorkspacePrompt — both answer "what is this not-yet-started chat about"). The folders only supply names: a freshly spawned session has its stream row the moment the prompt is dispatched, while omp's transcript — what the sidebar structure is scanned from — lands seconds later. Driving the list off folder.sessions therefore offered nothing in exactly the case the feature exists for, measured where the running session was a PENDING row and its folder listed no sessions at all. A wait on an idle session would be released by the next sweep, so offering it would promise a wait that cannot happen. The choice persists in the session's UI state (chat.waitingFor) AND is mirrored into a ref (waiting/choice.ts): the composer is remounted by a stretch, a tab switch and a reload, and the send handler is created once per deps record — a pick read from render state there would send immediately, which is the one outcome the feature defers.
  • The cue is STAMPED from the server list, never cleared from an absence (session-sidebar-controller). The effect runs on the render a hold triggers — one frame before the topic's first snapshot — and a snapshot resolved before the create does not carry the row either, so clearing on "not in the list" deleted the cue the user had just made and, with it, the id the dispatch watcher needs. A wait ENDS through a terminal row: dispatched (adopted), cancelled or error. useWaitingPrompts().loaded gates the stamp for the same reason.
  • A stale pick SENDS and says so (waiting/hold.ts): the dependency can finish while the draft is being written, and the honest outcome is a normal send with a notice, not a zero-length wait. A refusal keeps the draft — the user's text is the only copy — and reports the server's own reason.
  • The row does not disappear; it changes what it says. The pending store gains a waiting field, withPendingRows stamps waitingFor onto the sidebar row, and both layouts draw an Hourglass in the existing 16 px status slot plus one muted line under the title. reconcilePendingSessions keeps a waiting entry past PENDING_SETTLE_MS (a held prompt has no transcript to arrive, so the settle window would delete the very row the user is waiting on), and the cue is re-stamped from the server list on every publish (session-sidebar-controller) so a reload or a second tab sees the wait it did not create.
  • The dispatch is followed from the topic, not from the request (waiting/dispatch.ts, mounted in both sidebars). Nothing on this side sends the prompt, so the only report is the waiting topic: a dispatched row carries omp's session id, which is what adoptPendingSession moves the row onto — the same adoption the local send path performs — plus the URL rewrite when this tab was left on the pending id. It adopts when this tab OWNS the chat (it still holds the cue, or its URL names the pending id); another tab's row is left alone, since adopting it would mint a sidebar entry for a chat this tab never opened. The answer itself is deliberately not asserted by the spec: the run starts server-side, so it streams before this page's subscription exists — the URL rewrite and the dispatched row are the observables, and a reload reads the transcript back. error and cancelled release the row with a notice. Cancel is the row's own ⋯ item and the composer's strip; it is refused once dispatched (409 already_dispatched, naming Stop instead), and the refusal is reported.
  • MOCK refuses the create (409 mock_mode): a demo install spawns no child, so a held prompt could never be sent, and a row that waits forever is worse than a refusal that says why.
  • Pinned by waiting/settle.test.ts (every condition, including the ones that must NOT settle), waiting/runtime.server.test.ts (two racing sweeps spawn once; a queued dependency holds; a failed spawn is retried then reported; attachments and the model snapshot ride), waiting/store.server.test.ts (claim-once, requeue, claimed-then-failed, delete-by-name, retention), pending-sessions.waiting.test.ts (the settle-window exception, cancel-by-wait, adoption clears the cue), WaitingDependencyPicker.test.ts (a streaming id the structure has not scanned is still offered). The assembled browser proof was removed: every one of its specs flaked on the Windows leg across seven consecutive runs (a wait-picker that never appeared, and a Running cue that never arrived), so it reported the harness rather than the feature.

Terminal Panel (real PTY)

  • The right-panel terminal is a real shell on a pseudo-terminal, not a command runner: Bun.Terminal + Bun.spawn, one shell per terminal id, N attached viewers. src/server/lib/terminal/runtime.server.ts owns the registry, history.ts the bounded scrollback, shell.ts the launch argv, and src/server/routes/terminal/ws.ts the socket. GET /api/terminal/sessions lists live shells.
  • Transport is one WebSocket per terminal (/api/terminal/:terminalId/ws): text frames are JSON control (attach / resize / close), binary frames are raw PTY bytes both ways. The frame contract lives in src/shared/lib/workspace/terminal/protocol.ts and is shared by both ends — change it there, never per side. Client pieces: src/client/hooks/workspace/terminal/{index,socket}.ts and terminal-panel/RealtimeXtermView.tsx.
  • Three invariants the runtime depends on (each was verified against Bun 1.4.2 and each fails silently when broken): spawn with detached: true on POSIX (otherwise the child sits in the server's process group — no job control, and a group signal would kill Kabmo); launch POSIX shells through the shellLaunch shim that re-opens the PTY as the controlling terminal (setsid drops it, and a shell without one disables job control entirely); and send SIGWINCH after term.resize() (Bun updates the winsize but never signals the child, so a TUI would not repaint).
  • Windows must NOT detach, and that is what broke the panel there. detached maps to UV_PROCESS_DETACHED → DETACHED_PROCESS, which gives the child no console at all; cmd.exe will not run without one, so every shell exited with code 1 within a second. Measured on the Windows CI runner: all eight attached shells came back status: "exited", exitCode: 1, so nothing ever counted toward the cap and the terminal panel showed a dead shell — which is what the two terminal-capacity specs were skipping for, and they no longer do. The option is built by shellSpawnOptions (src/server/lib/terminal/spawn.ts) rather than written at the spawn site, because a POSIX-only run cannot observe the value; spawn.test.ts asserts both branches. omp/rpc/process.ts and tests/e2e/fixtures/server.ts carry the same guard for the same reason. Windows needs no process group: killProcessTree walks the tree with taskkill /t.
  • SIGWINCH must be debounced (resizeTerminalDebounced). Every accepted grid change signals the shell, and a shell answers by redrawing its prompt — so a resize burst that reaches the PTY one-per-frame prints the prompt dozens of times (measured: 10 signals in one second for a single panel drag). A quiet period coalesces the burst to its trailing size. For the same reason the client suppresses term.onResize reports while it is laying out replayed scrollback: that transient grid is the recorded history's, not the panel's.
  • PTY reads are coalesced into frames, never forwarded one-per-read (lib/terminal/output.ts). Bun.Terminal's data callback fires per read, and one read is one line for a line-oriented producer: seq 1 300000 arrived as 182,259 reads, p50 = 12 bytes, 419 reads/ms, and cat of a 5 MB file never exceeded 2,048 bytes in one read. Framing each read spent the socket on headers. Measured end to end through the real registry (PTY → coalescer → viewer) on seq 1 400000: per-read 109,491 frames / 28 bytes each / 1.78 MB/s, coalesced at 4 ms or 8 KiB 382 frames / 8,089 bytes each / 2.99 MB/s. In a browser (PTY → WS → the panel's renderer) the same change took 33.7 MB from 2.12 → 6.9–7.3 MB/s, where the ceiling became the PTY producer rather than the client — which is why swapping the emulator for a faster core (libghostty-wasm parses 3–4× faster in isolation) buys 1.25× on the assembled panel and nothing at all once this is fixed. Three rules come with it: a flush never discards accepted bytes (xterm parses across write boundaries, so a frame may split an escape sequence but may not drop one); the queue is a pass-through for a single read rather than a copy (Bun does not reuse the data buffer — verified: 2,000 seq lines across 1,104 reads concatenate byte-identically after exit); and attachTerminal flushes before capturing the replay, because pending bytes are already in history, so a replay captured first would deliver them twice and a frame delivered first would arrive ahead of the replay. attach-replay.test.ts drives a real PTY and asserts the late viewer's live stream starts exactly one line after its replay's last line; removing the flush fails it.
  • ws.send's -1 is a delivery, not a failure. Bun 1.4.4's ServerWebSocket.send returns >0 bytes queued, -1 queued-with-backpressure (a drain follows, the frame is sent) and 0 dropped (socket closed, or past backpressureLimit, 16 MiB by default). The route used to treat -1 as failure, so a healthy terminal was closed at the first burst: measured against Bun 1.4.4, 20,000 frames of 4 KiB stopped at frame 160 (0.8 %) while the socket was still accepting, and a 40,000 × 1 KiB burst returned -1 17,870 times and 0 20,851 times — i.e. the real drops were the ones being reported as successes. frameAccepted (lib/terminal/send-result.ts) is the single mapping now, and send-result.test.ts asserts both directions.
  • Terminal ids are per Kabmo session (terminal.id in session UI state) so a page reload reattaches to the same shell and the server replays its scrollback. The replay is written at the size it was drawn for (replayCols/replayRows) and only then fitted — re-wrapping history at another width leaves fragments the shell's redraw never clears.
  • A terminal has one grid, so with several viewers (two tabs, a phone and a desktop) the most recent attach/resize owns cols/rows and the others see output wrapped for it. That is inherent to sharing a PTY; there is no per-viewer size to fall back to.
  • Do not reintroduce a per-command sh -c route or a client-side line editor: the shell owns line editing, history, completion and signals, and the renderer must receive raw bytes so a character split across PTY reads stays intact: Uint8Array in, and keystrokes out through terminalInputFrame — ghostty-web has no onBinary, so the legacy X10 mouse report is split back into bytes there (TextEncoder turns its 0xdc into two bytes and the shell receives garbage).
  • A failed terminal spawn reports the descriptor table, not just the shim. createSession's error is spawn: Failed to start <shell>: <bun message>, and the message now goes through describeSpawnFailure (lib/lifecycle/fd-pressure.ts). Bun's own text for an exhausted table is EBADF: bad file descriptor, posix_spawn '/bin/sh' — naming the shellLaunch shim and never the cause — so the helper appends the real one (the server is out of descriptors, with the count and the fix) only when fcntl(F_GETFD) can see the pressure; a genuine bad-descriptor failure still reads as itself. The omp child's spawn (omp/rpc/process.ts) is wrapped the same way, because it fails for the same reason at the same moment.
  • One shell per terminal id, even when two attaches race. Creation awaits (cwd resolution, the shell probe, the capacity ps), so two attach frames for the same new id both used to pass the sessions.get check and both spawned: the map kept whichever landed last, and the other PTY plus its detached shell had no record — the reaper could never see it and the cap never counted it (measured on the real runtime: two concurrent attaches left two shells for one record). openTerminal shares one in-flight promise per id instead, and that map lives in store.ts beside the records, because a reload that dropped it would reopen the same race.
  • A touch device gets a key bar, and its bytes are xterm's own key encodings (terminal-panel/KeyBar.tsx + src/shared/lib/workspace/terminal/keys.ts, shown when useTouchDevice() reports a soft keyboard — (pointer: coarse), or touch points plus (hover: none), subscribed rather than read once so docking a keyboard hides the bar). A phone's soft keyboard has no Ctrl, Alt, arrows, Esc or |, so those are buttons; every sequence is what @xterm/xterm/src/common/input/Keyboard.ts sends for the same physical key, because a bar key that invented its own encoding works in bash and breaks in vim. Three of its rules are load-bearing: a modifier is a CSI parameter (ESC [ 1 ; 5 A), never an ESC prefix; DECCKM (set by vim/less) swaps arrows and Home/End to the SS3 spelling and a modifier beats it — read at press time from term.modes through the view handle, since the encoding cannot be decided at mount; and Ctrl is a latch, not a fold on literal keys, so a tapped | stays a pipe while ^C is its own button. A fourth rule is that xterm's own default is not always what the shell binds: Home and End send the terminfo spelling, not xterm's CSI one. The PTY child runs with TERM=xterm-256color, and infocmp xterm-256color declares khome/kend as SS3 (\EOH/\EOF) — while xterm.js emits ESC[H/ESC[F whenever DECCKM is off, which is exactly the state a shell prompt sits in. The mismatch is silent from this side and total on the other: zsh's ZLE rings the bell and leaves the cursor where it was. Verified A/B/A against Kabmo's own zsh — ESC[H → bell, ESC[OH → accepted, ESC[H → bell again — and the fix is a terminfo field on the CsiSpec that takes precedence over the DECCKM/default branches (keys.test.ts pins it). The arrows need no such field: their CSI and SS3 forms are both accepted, so DECCKM stays their only variable. The latch also folds into the soft keyboard's own letters (applyModifiers in handleInput) — that is the only way a phone reaches Ctrl+R or Alt+B — and only a single typed character consumes it, or a paste would spend it silently. Verified end to end against a live PTY: ^C took the server's busy from true to false mid-sleep 30, and printf '\033[?1h' switched a subsequent Up arrow from ESC [ A to ESC O A. The bar wraps instead of scrolling (overflow-x-auto no-scrollbar hides keys with nothing on screen to say so — the diff toolbar's lesson) and is its own @container, so a 320px desktop panel gets three rows of keys and a wide one gets one. The control row carries the three Ctrl keys a terminal actually needs without a physical keyboard — ^C (interrupt), ^D (end of input), ^L (clear screen, which is also the only way to clear a scrollback too wide to scroll on a phone) — and Shift+Tab, which no soft keyboard can produce.
  • The bar has two layers, and Cmd is an ACTION rather than a key. A layer key swaps the control/cursor row for the symbol row in place — TERMINAL_SYMBOLS carries the $ * ? & < > set plus |, ~, backslash, backtick and the brackets/quotes, because reaching $ on an iOS keyboard is a mode switch per character and ~/|/backslash/backtick have no layer at all. There is deliberately no Cmd button: the renderer treats metaKey as the host's modifier rather than the terminal's — a printable Cmd chord sends nothing (isPrintableCharacter returns false) and Cmd+C / Cmd+V are its own copy and paste — so a button for it would send nothing. In a terminal Cmd+C/Cmd+V mean copy and paste, and that is what the bar offers instead — Copy selection reports "Nothing selected" rather than flashing success over an untouched clipboard, and Paste goes through term.paste() so a bracketed-paste shell receives its \x1b[200~…\x1b[201~ markers (verified: the bytes on the wire carry them) rather than a line-by-line write. A denied clipboard read is surfaced as "Clipboard unavailable" with the button in its error tone, and no bytes are sent. Both actions share the row with the latches, and both disabled with the shell.
  • A phone's terminal focus is the TEXTAREA, and the keyboard has to be armed inside the tap. ghostty's Terminal.focus() focuses the CONTAINER (its keydown listener is the hardware path), and open() calls it again on a 0 ms timer; a phone's input is beforeinput on the renderer's textarea, so the container focus opened no keyboard and swallowed the first characters. Measured on the phone layout: the textarea held focus at mount and the container owned it 12 ms later. focus-target.ts focuses the textarea on a soft-keyboard device and redirects the container's focusin to it (event-driven, so it survives the vendor's timer), and the mobile shell arms a 1px offscreen bridge textarea in the tap that opens the drawer or the Terminal chip (lib/ui/soft-keyboard.ts) — a focus that lands after the tap opens no keyboard on either mobile WebView. The drawer releases the bridge when the view it resolved is not the terminal.
  • The panel lifts by its OWN overlap with the keyboard, never by the keyboard's height (useKeyboardInset → paddingBottom on the panel root). Neither mobile browser shrinks the layout viewport for the soft keyboard by default, so a bottom-anchored bar would sit behind the very keys the user is typing on. The lift is panelBottom − (visualViewport.offsetTop + visualViewport.height), and that form is the whole point: innerHeight − visualViewport.height measures the keyboard and then applies it to a panel that may not reach the screen's bottom edge — a drawer with env(safe-area-inset-bottom) padding, a container a dvh wrapper already shrank for the keyboard — which lifts by the keyboard's height plus a gap the panel never had. That was the too-far margin. Deriving from the panel's own edge yields exactly zero in every one of those cases. Two guards keep it honest: MIN_KEYBOARD_INSET_PX (80) so a collapsing URL bar is not mistaken for a keyboard, and a ≤ 0 visible-bottom fail-safe to no-lift. The measurement is deferred one requestAnimationFrame, because visualViewport.resize fires BEFORE the container reflows — reading in the handler sees the old full height and doubles the lift — and a ResizeObserver on the panel's border box catches a container that shrinks with no viewport event at all, without a feedback loop (our own padding moves the content box only). Verified with a stubbed visualViewport on a 390×844 phone: keyboard over a full-height panel → bar 844 → 508px (exactly the keyboard's top edge) and grid refit (resize 58x13, back to 58x30); a panel that already cleared the keyboard → 0 lift; a 40px overlap under the floor → ignored.
  • The terminal font stack must keep its glyph fallbacks (TERMINAL_GLYPH_FALLBACKS in src/client/data/theme/terminal.ts). Shell prompts are drawn with private-use symbols — powerline separators, devicons, Material Design icons — that no coding webfont contains: @fontsource/fira-code's latin subset maps 226 codepoints, none above U+FFFF. Without a Nerd Font face in the chain the browser paints a hollow tofu box for every prompt segment. Note the two ways a local face can be referenced, because only one is reliable in Chrome: a family name in the font stack works, while @font-face { src: local("…") } matches the full or PostScript name only — local("FiraCode Nerd Font Mono") fails where local("FiraCode Nerd Font Mono Reg") and local("FiraCodeNFM-Reg") succeed.
  • The Kabmo bundles the symbols face, and it is LAST in the stack (NERD_SYMBOLS_FAMILY, src/shared/lib/fonts/nerd-symbols.css). Naming installed families is not enough: the glyphs appeared on the machine that had one and were tofu on every other device — a phone, a second laptop. The vendored subset of Nerd Fonts' SymbolsNerdFontMono (MIT, 1.1 MB, built by scripts/nerd-symbols-font.mjs) closes that gap without taking the choice away, because a face is only reached when no earlier family supplies the glyph. Two properties make that safe and both are asserted in nerd-symbols.test.ts: the face must stay LAST (moved ahead of the installed families it would win on every machine and make every desktop download 1.1 MB for nothing), and its unicode-range must cover only private-use — which is what makes the download conditional. Verified: with a local Nerd Font present, laying out a PUA glyph issued zero font requests and the face stayed unloaded; with no local family, the face is fetched and all 43 codepoints of the user's own starship prompt render.
  • Both faces are awaited before the terminal opens, and a late one re-measures the grid (waitForTerminalFonts / watchTerminalFonts, terminal-panel/fonts.ts). The renderer measures its cell box at open(), so opening against a fallback face gives the grid the wrong cell — measured with Fira Code's request delayed, document.fonts.check('12px "Fira Code"') was false at mount. The text face is therefore loaded first (bounded at 2 s, and it is the only face asked for: the bundled symbols face is deliberately lazy, see the bullet above), and a loadingdone naming either face re-measures — ghostty-web's only public re-measure is a font-size round-trip, which the mount performs and then re-fits.
  • The cell box is Kabmo's measurement, and it is what a painted rectangle looks like (measureTerminalCell, terminal-panel/fonts.ts, installed by installCellMetrics). The vendor measures M alone: M has no descender, so it substitutes 0.2em and produces a 13px cell at 12px Fira Code whose last pixel is the descender — and because every row is repainted with the theme background before its cells, the next row's fill clipped it, so every SGR background block read as cropped. Measuring Mg gives a real descent; the box is the ink plus 4px above and 1px below (16px), installed by replacing the renderer's private measureFont and re-measuring. Verified by pixels on the real panel: cell 16px, ink 11px, 4 above / 1 below.
  • The terminal has no surface of its own, and the fit uses the whole panel. Its theme background is transparent, so the panel's paper — and under [data-surface="glass"] the frosted chrome behind it — shows through; the host lost its p-1.5; and installFullWidthFit replaces FitAddon.proposeDimensions, which subtracts a hard-coded 15px for its in-canvas scrollbar before dividing by the cell width (measured: the grid stopped 1-3 columns short, and a full-width TUI ran out of room the panel visibly had). Cost, and why it is acceptable: the in-canvas scrollbar (8px, only while scrolling) can overlap the last column.
  • A grid announcement is a PTY resize, so it is announced only when it is real and settled (terminal-panel/grid.ts). The right panel animates its width, and announcing a fit taken mid-transition sent resize 5x37 to a real shell; before the first successful fit the terminal still holds ghostty's 80×24 default, which looks plausible and rewrapped the prompt at 80 columns. Each resize is a SIGWINCH, the shell answers by redrawing its prompt, and that redraw is output that stays in the scrollback — so every reload replayed one more hard-wrapped block above the live prompt and the prompt marched down the panel. The gate: a grid must come from a fit that actually measured the container, be at least 10×5, and have held still for 120ms; finishReplay re-states it afterwards, and attachTerminal applies the attach's size to an existing session so a missed resize self-heals, and resizeTerminal moves replayCols/replayRows with the PTY — they used to stay at the spawn size, so after any panel resize each reload laid the whole scrollback out at the OLD grid, re-wrapping lines drawn at the new one, and the fit that followed resized the shell, which redrew its prompt into the history: measured replayBytes 2125 → 2582 → 3496 across three reloads, the transcript creeping down a row each time. Verified by frames after both fixes: attach is the settled 40x36, every resize equals it, ready reports replay 41x47 pty=41x47, and replayBytes stays 2125.
  • PTY frames must leave the server as BINARY frames (asBinaryFrame, lib/terminal/send-result.ts). Elysia's ws.send JSON-stringifies every object that is not a Buffer, so a Uint8Array reached the browser as a byte map ({"0":27,…}) and the client dropped live output. Measured on the same 33.7 MB cat: 4.58 MB/s as text byte maps, 34.8 MB/s as binary — the spelling had been the ceiling, not the renderer.

Clone this wiki locally