ompchamber 0.4.0 → 0.6.0

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://elysiajs.com"><img alt="Server: Elysia 1.4" src="https://img.shields.io/badge/server-Elysia%201.4-6f42c1"></a>
   <a href="https://preactjs.com"><img alt="UI: Preact 10" src="https://img.shields.io/badge/UI-Preact%2010-673ab7?logo=preact&logoColor=white"></a>
   <a href="https://rsbuild.dev"><img alt="Build: Rsbuild 2" src="https://img.shields.io/badge/build-Rsbuild%202-eab308"></a>
-  <a href="package.json"><img alt="Version: 0.4.0" src="https://img.shields.io/badge/version-0.4.0-3f3f46"></a>
+  <a href="package.json"><img alt="Version: 0.5.0" src="https://img.shields.io/badge/version-0.5.0-3f3f46"></a>
 </p>
 
 <p align="center">
@@ -67,8 +67,8 @@ ompchamber logs -f -n 200            # follow the server log
 - **Full omp settings surface** — OMP Engine config keys, providers, agents, behavior
   (`AGENTS.md` / `RULES.md`), slash commands, MCP servers with live connection tests, skills and
   the skills catalog, token usage and notifications.
-- **Two data modes** — `MOCK=true` ships demo datasets for previews; `MOCK=false` runs purely on
-  the real SQLite database and real workspace files.
+- **Two data modes** — `MOCK=false` (the default, also when unset) runs purely on the real SQLite
+  database and real workspace files; `MOCK=true` opts into demo datasets for previews.
 - **Self-update** — `ompchamber update` installs the latest GitHub release (bun global or git
   checkout) and restarts a running instance; **About → Updates** does the same from the console.
 
@@ -79,6 +79,10 @@ OMPChamber is published to npm. It needs a Bun runtime, not Node:
 > **Bun only** — the server imports `bun:sqlite` and `Bun.YAML`, both of which Node cannot load.
 > `bun` 1.4 or newer is required.
 
+> **omp required** — every live capability (agent sessions, omp config, session state, updates)
+> shells out to the `omp` binary, so `serve` refuses to start when it cannot be resolved on `PATH`
+> (or via `OMPCHAMBER_OMP_BIN`). `MOCK=true` is the only mode that runs without a real omp install.
+
 ```bash
 bun add -g ompchamber     # puts the `ompchamber` command on your PATH
 ompchamber serve --prod   # start the server on :3000
@@ -151,6 +155,47 @@ same install, then asks you to restart the server, because a running server cann
 | `-f, --follow` / `-n, --lines <count>` | Tail the log, optionally from a line count |
 | `--json` / `-q, --quiet` | Machine-readable output / suppress non-essential output |
 
+### Ports and multiple instances
+
+One port is served by exactly one process, and `bun run dev`, `ompchamber serve` and the production
+server all default to `3000`. **A starting instance never stops another one** — not a CLI server
+and not a dev run. If the port is taken by OMPChamber, the newcomer reports who holds it and exits
+non-zero so you can pick another port and re-run:
+
+```bash
+ompchamber serve --port 3001        # CLI flag
+OMPCHAMBER_PORT=3001 ompchamber serve
+PORT=3001 bun run dev              # or: PORT=3001 bun run start
+```
+
+- Nothing is ever signalled to free a port. `ompchamber stop --port 3000` is the deliberate way to
+  free one, and it is per port.
+- A process that is **not** OMPChamber is never signalled either: the server exits with an error
+  naming the port and the `lsof -nP -iTCP:<port> -sTCP:LISTEN` command to identify it.
+- The refusal exists because a second bind would *succeed*: Elysia's Bun adapter hardcodes
+  `reusePort: true`, so two servers would share a port and only the first-bound socket would receive
+  connections — the newcomer would look healthy while the browser kept talking to the old build.
+- `bun run dev` hot reload is unaffected: `--hot` re-evaluates the server entry *inside the running
+  process*, and a port held by that same process is recognized as its own, so Bun swaps the handler
+  on the next `listen`. Saving a file neither trips the guard nor resets the reported uptime.
+
+Running several ports at once is supported. `status`, `stop`, `restart` and `logs` act on **every**
+live instance by default, and `--port <port>` narrows them to one:
+
+```bash
+ompchamber status                  # every instance: port, pid, mode, launch mode, health, log
+ompchamber status --port 3001      # just that one
+ompchamber logs -n 200             # one header per instance, sources included
+ompchamber logs --port 3001 -f     # follow one instance's log
+ompchamber stop                    # stop them all (--all is the explicit spelling)
+ompchamber stop --port 3001        # stop just that one
+```
+
+The server writes `~/.ompchamber/run/<port>.json` (`pid`, `host`, `mode`, `launchMode`,
+`startedAt`) once it owns the port, which is why `status`/`stop`/`logs` also see servers started by
+`bun run dev` or `--foreground` — not just daemon-spawned ones. Records left by a killed server are
+pruned as soon as their PID stops answering, so a recycled PID is never reported as an instance.
+
 ## Configuration
 
 Environment variables, read from `.env` (see [`.env.example`](.env.example)):
@@ -159,7 +204,7 @@ Environment variables, read from `.env` (see [`.env.example`](.env.example)):
 |---|---|---|
 | `PORT` | `3000` | Server port |
 | `HOST` | `localhost` | Server bind address |
-| `MOCK` | `true` | `true` = demo datasets, `false` = real SQLite + workspace only |
+| `MOCK` | `false` | `true` = demo datasets, `false` = real SQLite + workspace only |
 | `SYNC_WORKSPACE` | `true` | Keep the workspace index in sync with disk |
 | `OMPCHAMBER_DATA_DIR` | `~/.ompchamber` | CLI registry, logs and database root |
 | `OMPCHAMBER_PORT` / `OMPCHAMBER_HOST` | — | Defaults for the CLI when no flag is passed |
@@ -167,7 +212,7 @@ Environment variables, read from `.env` (see [`.env.example`](.env.example)):
 | `OMPCHAMBER_DEV_SERVER` | `http://localhost:3100` | Rsbuild asset origin used in dev |
 | `OMPCHAMBER_BUN` | — | Explicit Bun binary for the CLI to spawn |
 | `PI_CONFIG_DIR` / `PI_CODING_AGENT_DIR` | `~/.omp` | Oh-My-Pi config root overrides |
-| `OMP_WEB_OMP_BIN` | — | Explicit `omp` binary path |
+| `OMPCHAMBER_OMP_BIN` | — | Explicit `omp` binary path |
 | `SKILLS_API_URL` | `https://skills.sh` | Skills catalog source |
 | `GITHUB_TOKEN` / `GH_TOKEN` | — | Raise the GitHub API rate limit for update checks |
 
@@ -185,7 +230,7 @@ src/
 │  └─ tailwind.css  theme tokens (--theme-ink, --theme-paper, …)
 ├─ server/    Bun-only — Elysia routes, SQLite, omp RPC bridge, fs/git/terminal
 │  ├─ routes/       one plugin per domain, mounted in routes/index.ts
-│  ├─ lib/          omp session/subagent/config, updates, browser runtime
+│  ├─ lib/          omp session/subagent/config, updates, browser runtime, port lifecycle
 │  └─ plugins/      SSR shell, static assets, compression, dev assets
 ├─ shared/    Imported by both — types, chat timeline folding, pure helpers
 └─ cli/       ompchamber command (plain ESM, runs under Bun)
@@ -215,6 +260,10 @@ There is no HMR: the server reloads on save, the client bundle rebuilds, refresh
 `dist/client/index.html` is the shell for both dev and prod, so run `dev:client` at least once
 after a clean checkout.
 
+Dev and prod share the default port `3000`: a second starter on an occupied port refuses and exits
+with the port options to re-run ([Ports and multiple instances](#ports-and-multiple-instances));
+nothing is stopped for you.
+
 Verification gates, all mandatory:
 
 ```bash
@@ -230,7 +279,7 @@ Publishing is driven by **GitHub releases**, never by a push
 ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)):
 
 ```bash
-bun pm version minor -m "chore(release): v%s"   # bump + commit + tag v0.4.0
+bun pm version minor -m "chore(release): v%s"   # bump + commit + tag v0.5.0
 git push origin main --tags
 # then publish the release on GitHub → the workflow publishes to npm
 ```

package/dist/client/index.html

@@ -24,7 +24,7 @@
       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-->
-  <script defer src="/static/js/markdown-vendor.71e43278b3.js"></script><script defer src="/static/js/shiki-vendor.cb8452ddcd.js"></script><script defer src="/static/js/uy.5f791144ce.js"></script><script defer src="/static/js/index.bf1b1fe988.js"></script><link href="/static/css/index.5291f58223.css" rel="stylesheet"></head>
+  <script defer src="/static/js/markdown-vendor.71e43278b3.js"></script><script defer src="/static/js/shiki-vendor.cb8452ddcd.js"></script><script defer src="/static/js/uy.2e8929ed0c.js"></script><script defer src="/static/js/index.47d3b04d5f.js"></script><link href="/static/css/index.51f68210a5.css" rel="stylesheet"></head>
   <body>
     <div id="app"></div>
     <!--app-bootstrap-->