@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/extensions/kabmo-modes/registration.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test';
+import entry from './index';
+import type { ExtensionCtx, ModeApi, ModeSession } from './session';
+
+describe('command registration', () => {
+  test('registers both the current and the pre-rename mode command', () => {
+    const registered: string[] = [];
+    const session: ModeSession = {
+      getPlanModeState: () => undefined,
+      setPlanModeState: () => {},
+      getPlanReferencePath: () => 'local://PLAN.md',
+      getEnabledToolNames: () => [],
+      setActiveToolsByName: async () => {},
+      sessionManager: { appendModeChange: () => 'id', getSessionId: () => 's1' },
+    };
+    const api: ModeApi = {
+      appendEntry: () => {},
+      sendMessage: () => {},
+      registerCommand: (name) => { registered.push(name); },
+      pi: { AgentRegistry: { global: () => ({ list: () => [{ id: 's1', session }] }) } },
+    };
+    entry(api);
+    expect(registered).toContain('kabmo-mode');
+    expect(registered).toContain('chamber-mode');
+  });
+});

package/extensions/kabmo-modes/session.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Live-session access for Kabmo's mode extension.
+ *
+ * omp exposes no RPC verb for plan or goal mode — the command union has none,
+ * `mode_change` entries are not restored under `--mode rpc-ui`, and
+ * `plan.defaultOnStartup` is read only by the interactive TUI. An extension
+ * loaded into the child process is the one surface that reaches the live
+ * `AgentSession`, and it reaches it through `AgentRegistry.global()`: the
+ * registry holds the entry for the session this process is running, whose
+ * `session` field is the very object the TUI drives.
+ *
+ * Every call is feature-detected. `setPlanModeState` / `getGoalModeState` /
+ * `goalRuntime` are not part of omp's public extension contract, so a build
+ * that renames or drops one must degrade to a reported refusal rather than a
+ * half-enabled toggle that silently does nothing.
+ *
+ * All omp types here are structural and optional: the extension is loaded by a
+ * child process that may be older or newer than the one this was written
+ * against, so every field is `?` and every call site checks before invoking.
+ */
+
+import { KABMO_PLAN_STATE_ENTRY } from './protocol';
+
+/** Minimal shape of the fields this module touches. */
+export interface ModeSession {
+  getPlanModeState?(): { enabled: boolean; planFilePath: string; workflow?: string } | undefined;
+  setPlanModeState?(state: { enabled: boolean; planFilePath: string; workflow?: string } | undefined): void;
+  setPlanProposalHandler?(handler: ((title: string) => Promise<unknown>) | null): void;
+  getPlanReferencePath?(): string;
+  setPlanReferencePath?(path: string): void;
+  /** omp's own plan validation: normalizes the model-supplied title and
+   *  resolves the plan file the proposal names. */
+  preparePlanForReview?(title: string): Promise<{ details: { planFilePath: string; title: string; planExists: boolean } }>;
+  getGoalModeState?(): { enabled: boolean; goal: { id: string; status: string; objective: string } } | undefined;
+  goalRuntime?: {
+    createGoal(input: { objective: string; tokenBudget?: number }): Promise<unknown>;
+    resumeGoal(): Promise<unknown>;
+    pauseGoal(): Promise<unknown>;
+    dropGoal(): Promise<unknown>;
+    onBudgetMutated(budget: number | undefined): Promise<unknown>;
+  };
+  getEnabledToolNames?(): string[];
+  setActiveToolsByName?(names: string[]): Promise<void>;
+  compact?(instructions?: string, options?: unknown): Promise<unknown>;
+  prompt?(text: string, options?: Record<string, unknown>): Promise<unknown>;
+  sessionManager?: {
+    getSessionId?(): string;
+    getSessionFile?(): string | null;
+    appendModeChange?(mode: string, data?: unknown): string;
+  };
+  isStreaming?: boolean;
+}
+
+/** The extension API surface this module uses. Loose by design: the shape is
+ *  omp's, and a narrow local interface would need editing on every upstream
+ *  addition. */
+export interface ModeApi {
+  /** Append a non-LLM custom entry to the session branch (persistence only). */
+  pi?: {
+    AgentRegistry?: {
+      global?(): { list?(): Array<{ id?: string; parentId?: string; session?: ModeSession }> };
+    };
+  };
+  getActiveTools?(): string[];
+  setActiveTools?(names: string[]): Promise<void>;
+  sendMessage?<T = unknown>(
+    message: { customType: string; content: string; display?: boolean; details?: T },
+    options?: { triggerTurn?: boolean; deliverAs?: string },
+  ): void;
+  appendEntry?<T = unknown>(customType: string, data?: T): void;
+  on?(event: string, handler: (event: unknown, ctx: ExtensionCtx) => unknown): void;
+  registerCommand?(name: string, options: { description?: string; handler: (args: string, ctx: ExtensionCtx) => Promise<void> | void }): void;
+}
+
+/** The slice of omp's extension context the mode commands read. */
+export interface ExtensionCtx {
+  ui?: {
+    notify?(message: string, type?: string): void;
+    select?(title: string, options: string[]): Promise<string | undefined>;
+    editor?(title: string, prefill?: string): Promise<string | undefined>;
+  };
+  cwd?: string;
+  /** The session's `local://` root mapping, needed to read a plan artifact. */
+  localProtocolOptions?: unknown;
+  /** Start a new session (command context only). */
+  newSession?(options?: { parentSession?: string }): Promise<{ cancelled: boolean }>;
+  /** Compact the session context (command context only). */
+  compact?(instructionsOrOptions?: string): Promise<void>;
+  sessionManager?: { getSessionId?(): string; getSessionFile?(): string | null };
+}
+
+/**
+ * The extension API instance, bound once at load.
+ *
+ * The registry lives on `api.pi.AgentRegistry`, so every helper needs the API
+ * object rather than a session — but the session itself is resolved per call,
+ * because the registry entry is created during session start and a value
+ * captured at load time would be undefined.
+ */
+let boundApi: ModeApi | null = null;
+
+export function bindApi(api: ModeApi): void {
+  boundApi = api;
+}
+
+export function getBoundApi(): ModeApi | null {
+  return boundApi;
+}
+
+/**
+ * The live session for this process.
+ *
+ * A subagent's registry entry carries a `parentId`; the top-level session is
+ * the one without it, and it is the one whose mode flags this feature owns.
+ * Falling back to the first entry keeps a single-entry registry (the common
+ * case) working even if omp stops stamping `parentId`.
+ */
+export function activeSession(api: ModeApi): ModeSession | undefined {
+  const registry = api.pi?.AgentRegistry?.global?.();
+  const entries = registry?.list?.() ?? [];
+  const top = entries.find((entry) => !entry.parentId) ?? entries[0];
+  return top?.session;
+}
+
+/** Whether the installed omp build exposes everything a mode toggle needs. */
+export function modeCapabilities(session: ModeSession | undefined): { plan: boolean; goal: boolean } {
+  if (!session) return { plan: false, goal: false };
+  const plan =
+    typeof session.setPlanModeState === 'function' &&
+    typeof session.getPlanModeState === 'function' &&
+    typeof session.setPlanProposalHandler === 'function';
+  const goal =
+    typeof session.getGoalModeState === 'function' && typeof session.goalRuntime?.createGoal === 'function';
+  return { plan, goal };
+}
+
+/**
+ * Add `goal` to the active tool set when it is missing.
+ *
+ * `goal` is a HIDDEN tool: it lives in omp's `HIDDEN_TOOLS`, is excluded from
+ * `BUILTIN_TOOL_NAMES`, and `isToolAllowed` refuses it unless goal mode is
+ * already active — so `--tools goal` cannot force it and neither can a settings
+ * write. `setActiveTools` is the only lever, and omp registers the tool lazily
+ * on demand (`ensureGoalRegistered`).
+ */
+export async function ensureGoalTool(api: ModeApi, session: ModeSession): Promise<boolean> {
+  const current = session.getEnabledToolNames?.() ?? api.getActiveTools?.() ?? [];
+  if (current.includes('goal')) return true;
+  if (typeof api.setActiveTools !== 'function') return false;
+  await api.setActiveTools([...current, 'goal']);
+  return true;
+}
+
+/**
+ * Enter plan mode the way the TUI does: publish the state BEFORE widening the
+ * tool set, because plan mode's read-only guarantee is enforced by the built-in
+ * write/edit guard reading exactly that state — and the model needs `write` to
+ * draft its plan file and to submit it through `xd://propose`.
+ */
+export async function enterPlanMode(session: ModeSession, planFilePath: string): Promise<boolean> {
+  if (typeof session.setPlanModeState !== 'function') return false;
+  const previous = session.getEnabledToolNames?.() ?? [];
+  session.setPlanModeState({ enabled: true, planFilePath, workflow: 'parallel' });
+  if (typeof session.setActiveToolsByName === 'function') {
+    try {
+      await session.setActiveToolsByName([...new Set([...previous, 'write'])]);
+    } catch (error) {
+      session.setPlanModeState(undefined);
+      throw error;
+    }
+  }
+  session.sessionManager?.appendModeChange?.('plan', { planFilePath });
+  return true;
+}
+
+/** Leave plan mode. Clears the proposal handler first so a late `xd://propose`
+ *  cannot reach a handler whose review surface is gone. */
+export function exitPlanMode(session: ModeSession): void {
+  session.setPlanProposalHandler?.(null);
+  session.setPlanModeState?.(undefined);
+  session.sessionManager?.appendModeChange?.('none');
+}
+
+/**
+ * Persist the plan-mode flag on the session branch.
+ *
+ * Plan mode has no omp-side event to mirror (unlike goal mode, whose every
+ * transition arrives as `goal_updated`), so Kabmo's own transition is
+ * what gets recorded. The record is what a respawned child reads to restore the
+ * toggle, and what the console reads after a reload.
+ */
+export function recordPlanState(api: ModeApi, enabled: boolean): void {
+  api.appendEntry?.(KABMO_PLAN_STATE_ENTRY, { enabled });
+}

package/index.html

@@ -0,0 +1,85 @@
+<!doctype html>
+<html lang="en" data-theme="paper" data-theme-variant="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <!-- The theme's canvas color. The SSR shell rewrites this tag in place;
+         a second tag would be ignored, since Chrome reads the first. -->
+    <meta name="theme-color" content="#faf8f3" />
+    <meta name="mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+    <meta name="apple-mobile-web-app-title" content="Kabmo" />
+    <meta
+      name="description"
+      content="A light e-ink paper developer dashboard for AI Oh-My-Pi agent sessions — a browser console for CI/CD deployments."
+    />
+    <title>Kabmo</title>
+    <!-- Inline and in the head on purpose: this has to be registered BEFORE the
+         dev server's HMR client, which it cannot be from the module entry.
+         Bun injects its client script into the head, so a listener installed
+         from `main.tsx` is registered second — and the `error` event is
+         dispatched AT `window`, where listeners run in REGISTRATION order, not
+         capture-then-bubble. Measured here: the dev client's listener at t=272ms
+         and the module's at t=307ms, so `stopImmediatePropagation` from the
+         module arrived after the overlay had already been fed.
+
+         The message is the browser reporting that its per-frame ResizeObserver
+         delivery depth ran out with a notification still pending — a layout
+         timing warning, not an exception anything threw. Chrome and Firefox
+         raise it through `error`, so Bun's client draws its full-screen "Runtime
+         Error" overlay (z-index 2147483647) over the whole app for it and counts
+         it (`1 of 667 Errors`). The Kabmo's own resize-driven auto-scroll no
+         longer provokes it (the timeline defers its pin out of the delivery, see
+         `hooks/chat/timeline/scroll.ts`), but observers the app does not own can
+         still report it and it is never actionable.
+
+         `stopImmediatePropagation`, not `preventDefault`: the dev client's
+         listener runs first and is not cancelable, so the dispatch has to be
+         stopped, not the default. Matched exactly, so every other error still
+         reaches the overlay — that is the whole point of having one. -->
+    <script>
+      (function () {
+        var RESIZE_OBSERVER_LOOP = 'ResizeObserver loop completed with undelivered notifications.';
+        window.addEventListener('error', function (event) {
+          if (event.message === RESIZE_OBSERVER_LOOP) event.stopImmediatePropagation();
+        }, true);
+      })();
+    </script>
+    <!-- Relative, not absolute: Bun's HTML loader resolves every local `href`
+         against this file and emits a content-hashed copy, so `./public/icon.svg`
+         becomes `/icon-<hash>.svg`. An absolute `/icon.svg` is read as a module
+         specifier and fails the whole build with "Could not resolve". The
+         manifest's OWN icon entries stay absolute — Bun does not rewrite inside
+         a copied JSON file, and `public/` is served directly, so `/icon.svg`
+         resolves there. -->
+    <link rel="manifest" href="./public/manifest.webmanifest" />
+    <link rel="icon" type="image/svg+xml" href="./public/icon.svg" sizes="any" />
+    <link rel="icon" type="image/png" href="./public/icon-192x192.png" sizes="192x192" />
+    <link rel="apple-touch-icon" href="./public/apple-touch-icon.png" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap"
+    />
+    <!--app-head-->
+  </head>
+  <body>
+    <div id="app"></div>
+    <!--app-bootstrap-->
+    <!-- The client entry. rsbuild injected this tag into its own output; Bun's
+         HTML loader takes it from the source, which is why the file is now a
+         bundler entry rather than only a template the server reads. -->
+    <script type="module" src="./src/client/main.tsx"></script>
+    <script>
+      if ('serviceWorker' in navigator) {
+        window.addEventListener('load', () => {
+          navigator.serviceWorker.register('/sw.js').catch((err) => {
+            console.log('ServiceWorker registration failed: ', err);
+          });
+        });
+      }
+    </script>
+  </body>
+</html>

package/marketplace/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "Kabmo",
+  "description": "Panels bundled with Kabmo, plus the ones you install from a git URL.",
+  "owner": { "name": "Kabmo" },
+  "plugins": [
+    {
+      "name": "session-info",
+      "source": "plugins/session-info",
+      "description": "Shows the active workspace and keeps a note per session.",
+      "category": "utility"
+    },
+    {
+      "name": "stats",
+      "source": "plugins/stats",
+      "description": "CPU and RAM used by the omp stack — Kabmo, every omp child, the daemons and the shells.",
+      "category": "utility"
+    },
+    {
+      "name": "command-runner",
+      "source": "plugins/command-runner",
+      "description": "Lists a repository's commands and runs them, in the foreground or as background jobs.",
+      "category": "utility"
+    }
+  ]
+}

package/marketplace/plugins/command-runner/README.md

@@ -0,0 +1,223 @@
+# Command Runner
+
+A right-panel view that lists a repository's commands and runs them — in the
+foreground or as background jobs, with their output shown live.
+
+The activity-bar mark is a framed play button (Lucide's `square-play`): the panel
+lists commands and runs one. It deliberately is NOT a shell prompt — that is the
+`terminal` view's own glyph, and two buttons in one activity bar carrying the same
+mark is what this replaced.
+
+## What it lists
+
+Grouped by the FILE each command comes from, because in a monorepo the file is
+the command's identity. 26 filenames across 14 toolchains, plus the group you add
+to yourself:
+
+| Source | What is listed | Row runs |
+|---|---|---|
+| `package.json` | every key of `scripts` | the RESOLVED runner (`bun run dev`, `npm run dev`) |
+| `deno.jsonc` / `deno.json` | every key of `tasks` | `deno task <name>` |
+| `Makefile` / `makefile` / `GNUmakefile` | targets (`.PHONY` and other dot-targets are not commands; a pattern rule is not either) | `make <name>` |
+| `justfile` / `Justfile` / `.justfile` | recipes | `just <name>` |
+| `Taskfile.yml` / `.yaml` | every key of `tasks` | `task <name>` |
+| `pyproject.toml` | `[tool.poe.tasks]`, `[tool.pdm.scripts]`, `[tool.taskipy.tasks]`, `[tool.hatch.envs.*.scripts]` — each with its own runner | `poe <name>`, `pdm run <name>`, `task <name>`, `hatch run <name>` |
+| `Pipfile` | `[scripts]` | `pipenv run <name>` |
+| `manage.py` | Django's own verbs | `python manage.py <verb>` |
+| `docker-compose.yml` / `.yaml` / `compose.yml` / `.yaml` | two rows per SERVICE (`up`, `logs -f`) | `docker compose up <svc>` |
+| `go.mod` | the `cmd/<name>` packages beside it | `go run ./cmd/<name>` |
+| `Cargo.toml` | cargo's verbs + every `[[bin]]` | `cargo build`, `cargo run --bin <name>` |
+| `.cargo/config.toml` | `[alias]` — a project's own command names | `cargo <alias>` |
+| `composer.json` | `scripts`, plus Laravel's verbs when `artisan` sits beside it | `composer run-script <name>` |
+| `artisan` | Laravel's verbs | `php artisan <verb>` |
+| `build.gradle` / `.kts` | Gradle's verbs + any `task <name>` declared in the file | `./gradlew <task>` when a wrapper is committed |
+| `pom.xml` | Maven's verbs | `./mvnw <goal>` when a wrapper is committed |
+| `mix.exs` | the project's own `aliases` | `mix <alias>` |
+| **your own commands** | a group you add to from the panel — see below | the text you saved |
+
+### Three answers to "where are the commands"
+
+The differences are why each source is its own detector rather than one generic
+"look for a build file":
+
+1. **Declared in the file** — `scripts`, `tasks`, targets, recipes, `[alias]`,
+   `aliases`. Read directly.
+2. **Declared only at runtime** — cargo, `go`, `artisan`, `manage.py` and Gradle
+   have no task file, and their command lists are knowable only by RUNNING them.
+   The stable, universal verbs are listed instead, and each row's label says
+   exactly what will run. Deliberately short: a curated list that is wrong is
+   worse than a short one.
+3. **Found beside the file** — `go.mod`'s commands are the `cmd/<name>`
+   directories next to it, Laravel is recognised by the `artisan` beside a
+   `composer.json`, and the Gradle/Maven wrapper is preferred over whatever is on
+   `PATH` because a committed wrapper pins the version the build was written for.
+
+`[project.scripts]` in `pyproject.toml` is deliberately NOT read: those are
+console-script entry points, installed into an environment, so a row would fail
+until the package was installed first.
+
+The walk is bounded (depth 4, 200 files) and never descends into `node_modules`,
+`.git`, `dist`, `build`, `out`, `.next`, `coverage`, `target` or `vendor`. Hitting
+a cap is REPORTED in the panel rather than silently shortening the list.
+
+## Your own commands
+
+Above the file groups sits **`Custom commands`**, always present — even in a
+repository with no command file at all, because its header is where the `+` that
+adds one lives.
+
+A custom command is arbitrary text (`bun run build -- --watch`, `make deploy
+ENV=staging`, `git push && gh pr create`) run through `sh -c`, so pipes, `&&` and
+variables work. It is the ONE place this plugin involves a shell, and the rule
+that keeps it safe is about **who supplies the text**: `start` still takes an ID,
+and the text is read back out of your own storage server-side. There is no method
+that accepts a command line, so a page cannot run a string it invented — only
+something you already saved.
+
+Each entry carries two choices:
+
+| Field | What it decides |
+|---|---|
+| **Available in** | `This workspace` (only under the repo you created it in) or `Every workspace` (offered everywhere) |
+| **Directory** | the cwd, RELATIVE to the workspace root. `.` is the root. A script in a monorepo only resolves in its own directory |
+
+A stored command's row gains **`✎` edit** and **`🗑` delete**, revealed on hover
+and always shown on a touch device. Edit opens the dialog seeded with the entry;
+delete asks first, because a stored command exists nowhere else — there is no
+file and no git history to restore it from.
+
+Where they live: the plugin's own record storage (`plugin_records`, namespaced by
+the host to this plugin's id), keyed `<scope>:<slug>`. A global command and a
+repo-scoped one with the same name are two entries; editing the text MOVES the
+row (the slug is part of the key), and the old one is removed as it moves.
+
+## The package runner is resolved, and shown
+
+For a `package.json`, the runner is decided in this order:
+
+1. the file's own `packageManager` field (`bun@1.4.2` → `bun`);
+2. the nearest lockfile, walking up to the repo root — `bun.lock`/`bun.lockb`,
+   `package-lock.json`/`npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml`;
+3. `bun`.
+
+The resolved runner appears on the row (`bun run dev` vs `npm run build`), so the
+guess is visible rather than implied.
+
+## Two collapsible levels: file, then command
+
+```
+▾ Custom commands                 1          [+]
+  ▸ bun run build -- --watch      exit 0   [✎] [🗑] [⏱] [▶]
+▾ package.json                    2
+  ▸ bun run dev       exit 0      [≡] [⏱] [▶]
+  ▾ bun run test      running     [≡] [⏱] [■]
+    ┌────────────────────────────────────────┐
+    │ running · 12s · 48 KB            Stop  │
+    │  12 pass · 0 fail                       │
+    └────────────────────────────────────────┘
+▸ Makefile                        2
+```
+
+The custom group's header is **not** a disclosure: the `+` lives in it, and a
+button inside a button is invalid HTML whose inner click never fires.
+
+A **group header** is one command FILE — it collapses its rows, and carries the
+count. A **row** is one command — it collapses its own output. Both use the same
+reveal, and a collapsed body leaves the tab order entirely (its rows cannot be
+reached with `Tab` or announced), so a closed group is genuinely closed.
+
+## Every command is a row that opens
+
+A row is one line — the command, its last outcome, and four controls:
+
+```
+▸ bun run dev            exit 0   [≡] [⏱] [▶]
+```
+
+- **`▸` / `▾`** — the disclosure. It opens that command's own output underneath
+  it, and the reveal is Kabmo's standard one (`grid-template-rows: 0fr → 1fr`),
+  so the body rises rather than the list jumping.
+- **`[⏱]` background** — track this command as a job. On, the run is also listed
+  under `Running` with a Stop button and its elapsed time, which is the shape of
+  `bun run dev`. Turning it OFF stops the command's runs.
+- **`[▶]` run / `[■]` stop** — run it once. The glyph becomes a square while the
+  run is live, so one control says which of the two things a click will do.
+
+**The disclosure is disabled until the command has run.** There is nothing to
+expand before that, and a toggle that opens onto a placeholder teaches the reader
+the control is unreliable; the row says `has not run yet` instead. Once a run
+exists the row opens ITSELF, so a Run never looks like it did nothing.
+
+There is no output toggle: expanding the row is what shows the output, so a
+second control for the same thing was one decision with two controls. The
+background toggle is the only one left, because how a run is *tracked* is a real
+choice — it is per command and persisted per session.
+
+## Reading the output
+
+The type is a three-step hierarchy, and the sizes are load-bearing:
+
+| Level | Size | Weight |
+|---|---|---|
+| Group (`package.json`) | 12px | 600 — the heading of the list |
+| Command (`bun run speak`) | 11px | 400 — one item in it |
+| Log | 10px | 400 — that item's OUTPUT |
+
+The log must never out-weigh the command that names it, so it sits one step
+BELOW the label rather than at the code-block default (`text-xs`, which was a
+full step larger). The line box is a ratio of the size, so a wrapped log line
+stays readable at any zoom.
+
+The header of an expansion names the outcome and what is NOT shown. A killed run
+reads `stopped (SIGTERM)` — never `exit 0`, which is what a null exit code would
+look like. A build larger than the 256 KB buffer says `last 64 KB of 3.1 MB`
+rather than presenting a window as the whole log.
+
+## The repo picker
+
+The panel header carries the same nested-repo picker the Files, Search, Source
+Control and Terminal panels share. The selection is ONE value
+(`workspace.activeRepo`) for all of them, so picking a repo here moves those
+panels too — and vice versa.
+
+## Switching repos stops everything
+
+A repo switch force-stops every run of the session, background or not. That is
+enforced by three mechanisms, because each alone has a hole:
+
+1. **A content script** watches the shared scope for as long as the plugin is
+   enabled — the panel itself is unmounted while another view is on screen, so a
+   switch made from the Files panel would otherwise leave processes running with
+   nothing to notice. The script renders nothing.
+2. **The panel sweeps on mount**, which covers a reloaded Kabmo (no watcher has
+   run yet) and a phone.
+3. **Every run records its scope**, so a sweep kills runs started before a
+   watcher existed.
+
+`stop-others` is defined by the scope it is handed: it kills this session's runs
+in any OTHER scope and leaves the current one alone. Calling it twice is a no-op,
+which is why the watcher fires on every notification instead of tracking changes.
+
+## What it does not do
+
+- **No run history.** A restart forgets every run.
+- **No run of an unsaved string.** A run is started by command ID: a file command
+  is re-resolved against a fresh scan, a custom one against your own storage. So
+  this is not a remote-shell endpoint, even though a custom command is free text.
+- **No PTY.** These are pipes: a command expecting a terminal (a progress bar, an
+  editor) behaves differently from the Terminal panel's shell. A custom command
+  runs `sh -c <text>` under the same pipe, so it is not an exception.
+- **No editing** of `package.json` / `Makefile` from the panel. Only a command you
+  added yourself is editable here.
+- **No runtime discovery.** Cargo, `go`, `artisan` and Gradle could each answer
+  their real command list if the toolchain were run; the panel does not execute
+  anything to build a LIST, so it shows their stable verbs instead (and a project's
+  own names where the file states them, such as `[[bin]]`, `[alias]` and
+  `mix.exs`'s aliases).
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| Log tail (KB) | 64 | How much output one read returns. The server keeps the last 256 KB per run regardless. |
+| Concurrent runs | 8 | A run beyond this is refused with a reason rather than queued. |

package/marketplace/plugins/command-runner/icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Runner">
+  <title>Runner</title>
+  <!-- Geometry follows the built-in views' convention (Lucide): the art is inset
+       2/24 of the box and strokes at 2/24, so a plugin's mark carries the same
+       ink weight as the icons it sits beside. Paint is `currentColor`: the host
+       draws a vector mark through a CSS mask, so the file supplies the shape and
+       the surrounding ink supplies the colour.
+
+       The shape is Lucide's `square-play`, and the choice is deliberate: the
+       panel lists commands and RUNS one, and the first draft drew a shell prompt
+       (a chevron over a line) — which is exactly the `terminal` view's own mark,
+       so two buttons in the same activity bar carried the same glyph. A framed
+       play button says "start this" and collides with nothing. -->
+  <g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="3" y="3" width="18" height="18" rx="2" />
+    <path d="M9 9.003a1 1 0 0 1 1.517-.859l4.997 2.997a1 1 0 0 1 0 1.718l-4.997 2.997A1 1 0 0 1 9 14.996z" />
+  </g>
+</svg>

package/marketplace/plugins/command-runner/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "command-runner",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Lists a repository's commands and runs them, in the foreground or as background jobs.",
+  "type": "module",
+  "kabmo": {
+    "id": "command-runner",
+    "name": "Runner",
+    "version": "0.0.1",
+    "description": "Lists a repository's commands and runs them, in the foreground or as background jobs.",
+    "app": "dist/app.js",
+    "server": "dist/server.js",
+    "icon": "icon.svg",
+    "capabilities": ["server", "storage", "rpc", "realtime", "repo-scope"],
+    "settings": {
+      "logTailKb": {
+        "type": "number",
+        "label": "Log tail (KB)",
+        "description": "How much of a run's output the panel reads at a time. The full buffer is kept server-side; this is only what one read returns.",
+        "default": 64
+      },
+      "maxRuns": {
+        "type": "number",
+        "label": "Concurrent runs",
+        "description": "A run beyond this is refused with a reason rather than queued, so a runaway script cannot start a hundred processes.",
+        "default": 8
+      }
+    }
+  },
+  "peerDependencies": {
+    "@kabmo-labs/kabmo-sdk": "*",
+    "@kabmo-labs/kabmo-ui": "*",
+    "preact": "^10.29.8"
+  },
+  "peerDependenciesMeta": {
+    "@kabmo-labs/kabmo-sdk": { "optional": true },
+    "@kabmo-labs/kabmo-ui": { "optional": true },
+    "preact": { "optional": true }
+  }
+}