ompchamber 0.5.0 → 0.7.0

package/README.md

@@ -70,7 +70,8 @@ ompchamber logs -f -n 200            # follow the server log
 - **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.
+  checkout) and restarts the instance it started; **About → Updates** does the same from the console,
+  restart included.
 
 ## Install
 
@@ -125,8 +126,16 @@ release tag and rebuilt (`bun install`, `bun run build`). Uncommitted work is ne
 the update refuses and asks you to commit or stash first. An install owned by another package
 manager is not touched — the command prints the exact command to run instead.
 
-The same check runs from the console — **About → Updates** — and its Update button performs the
-same install, then asks you to restart the server, because a running server cannot replace itself.
+The same check runs from the console — **About → Updates**. Its Update button performs the same
+install and then restarts the instance serving that console, exactly as `ompchamber update` restarts
+the instance it finds: a detached `ompchamber restart --port <port>` is armed a moment after the
+response, so the server that answered is replaced without losing the reply, and the console
+reconnects on its own.
+
+A server OMPChamber did not start is never restarted. `bun run dev`, `bun run start`, a manual
+`bun src/server/index.ts` and an instance owned by a supervisor (systemd, pm2, a container) all
+record themselves as `direct`, so the update leaves them running and says so — their own launcher is
+what picks up the new files. `--no-restart` turns the restart off entirely.
 
 ## CLI
 
@@ -135,9 +144,9 @@ same install, then asks you to restart the server, because a running server cann
 | Command | Purpose |
 |---|---|
 | `serve` | Start the web server (daemon by default) |
-| `update` | Install the latest GitHub release, then restart a running instance |
+| `update` | Install the latest GitHub release, then restart the instance it started |
 | `stop` | Stop the running instance |
-| `restart` | Stop, then start again |
+| `restart` | Stop, then start again — leaving servers started from source alone |
 | `status` | Report whether an instance is running |
 | `logs` | Print or follow the server log |
 
@@ -155,6 +164,54 @@ 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. `restart` is the one exception to
+"every": an instance started from source is reported and left running, exactly as `ompchamber update`
+leaves it — `status`/`stop`/`logs` still see it, and `stop` still ends it:
+
+```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
+ompchamber restart                 # restart the CLI-started ones, skip a `bun run dev`
+```
+
+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. `launchMode` is `daemon` or
+`foreground` for a server the CLI spawned and `direct` for every other launch, and it is derived from
+the process's **argv**, never from an environment variable: env is inherited, so a `bun run dev`
+started inside an OMPChamber shell would otherwise be mislabelled and replaced by an update. 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)):
@@ -189,7 +246,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)
@@ -219,6 +276,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

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.0ac93ee878.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.eccad0b70a.js"></script><link href="/static/css/index.51f68210a5.css" rel="stylesheet"></head>
   <body>
     <div id="app"></div>
     <!--app-bootstrap-->