One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
Release 0.4.1
yuz207e142a2fa88b0
diff --git a/README.md b/README.mdindex 96f064d..71e7af1 100644--- a/README.md+++ b/README.md@@ -27,7 +27,7 @@>> — Juvenal, *Satires*-+You run coding agents on a laptop, a workstation and a server. SITREP shows all of them at once: which are working,which are waiting on you, which are stuck or have failed. Answer the ones that are waiting from the dashboard, withoutdiff --git a/codex-reporter/package.json b/codex-reporter/package.jsonindex b796822..00bc46e 100644--- a/codex-reporter/package.json+++ b/codex-reporter/package.json@@ -1,6 +1,6 @@{"name": "codex-reporter",- "version": "0.4.0",+ "version": "0.4.1","private": true,"license": "MIT","type": "module",diff --git a/codex-reporter/plugin/.codex-plugin/plugin.json b/codex-reporter/plugin/.codex-plugin/plugin.jsonindex 53b9cd4..822877f 100644--- a/codex-reporter/plugin/.codex-plugin/plugin.json+++ b/codex-reporter/plugin/.codex-plugin/plugin.json@@ -1,5 +1,5 @@{"name": "sitrep-codex",- "version": "0.4.0",+ "version": "0.4.1","description": "SITREP: records bounded, redacted Codex hook events to a local spool for the codex-reporter. Never decides anything, never touches the network."}diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.mdindex 7d7bcc2..8483c38 100644--- a/docs/HOW-IT-WORKS.md+++ b/docs/HOW-IT-WORKS.md@@ -46,8 +46,7 @@ thresholds, are settings.When a session asks for a permission, an answer or a plan approval, its reporter announces the ask and waits on theserver for the answer. Signed in, you answer in the dashboard, and the reporter gives the session exactly that answer.-Answer in the terminal instead and the dashboard's answer is dropped: the first answer wins, and the dashboard says-what became of yours.+You can still answer in the terminal: the first answer wins, and the dashboard says what became of yours.- **Claude Code** sessions are answered through the plugin.- **Codex** sessions running in Codex's managed daemon on that machine are answered through it. The others (`codex exec`,diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex a1f0eec..df759c8 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -1,6 +1,6 @@# Operations-How to run SITREP: the server on an always-on machine, the reporters on each machine. The README has the short version.+How to run SITREP: the server on an always-on machine, the reporters on each machine.Contents:@@ -29,16 +29,14 @@ Contents:| Every machine with Claude Code | The plugin `sitrep-reporter`, inside each Claude Code session (state, asks, answers); and Claude Code's own telemetry, which carries the sessions' usage | Claude Code, from this repository's plugin marketplace; the telemetry, from the settings the install writes || Every machine with Codex | The Codex plugin `sitrep-codex` (hooks that write a local spool) and the `codex-reporter` process (reads the spool, the session files and the Codex daemon; sends the reports) | Codex, from this repository's plugin marketplace; a user service |-Reporters push to one URL, so the server lives on the machine that is always on. While the-server cannot be reached, a reporter keeps each session's latest state and up to 500 events (the oldest are dropped)-and sends them when it is back; sessions that start and end during the gap, chart samples and live visibility are lost.-Claude Code's telemetry keeps no batch it failed to send, so a Claude session's usage during the gap is lost too.-Moving the server is a change of URL in each reporter.+Reporters push to one URL, so moving the server is a change of URL in each reporter. While the server cannot be+reached, a reporter keeps each session's latest state and up to 500 events (the oldest are dropped) and sends them when+it is back. Sessions that start and end during the gap, chart samples and live visibility are lost. So is a Claude+session's usage during the gap: Claude Code's telemetry keeps no batch it failed to send.## Deploy the server-1. **Node 24.** The server needs Node 24 (it uses the built-in `node:sqlite`). If the machine has an older Node,- install Node 24 for your user, for example with nvm (`nvm install 24`).+1. **Node 24.** If the machine has an older Node, install Node 24 for your user, for example with nvm (`nvm install 24`).2. **A built clone.**```sh@@ -65,7 +63,7 @@ Moving the server is a change of URL in each reporter.5. **Firewall.** Allow TCP 7487 from the LAN only, for example `sudo ufw allow from 192.0.2.0/24 to any port 7487 proto tcp`.6. **Host names.** The server refuses a request whose `Host` it does not expect (a guard against DNS rebinding). With- `--bind 0.0.0.0`, any IP address works, so `http://192.0.2.10:7487` works as is. To use a name such as+ `--bind 0.0.0.0`, any IP address works, such as `http://192.0.2.10:7487`. To use a name such as`http://server:7487`, add it to `SITREP_ALLOWED_HOSTS` in `server.env` and restart.7. **Check it.**@@ -81,15 +79,15 @@ On macOS, the same install writes `~/Library/LaunchAgents/dev.sitrep.server.plis## Add a machine-In the dashboard, Machines → Add a machine (or "+" beside Machines in the sidebar) gives these steps for the OS (macOS,-Linux) and harnesses (Claude Code, Codex) you pick, each with Copy: the clone; the install with `--url` set to the-address you opened the dashboard at, `--token-stdin` and `--apply` (paste the admin secret, then Ctrl-D); the Codex-hooks, which the install trusts; on Linux with Codex, linger; and, for Claude Code sessions already open, quit each and-resume it (`claude --resume`) so it sends its usage. "Waiting for the first report…" turns into "✓ <name> reported"-when the new machine reports.+In the dashboard, Machines → Add a machine (or "+" beside Machines in the sidebar) gives the steps for the OS (macOS,+Linux) and harnesses (Claude Code, Codex) you pick, each with Copy. They are the clone; the install, with `--url` set+to the address you opened the dashboard at, `--token-stdin` and `--apply` (paste the admin secret, then Ctrl-D); the+Codex hooks, which the install trusts; on Linux with Codex, linger; and, for Claude Code sessions already open,+quitting each and resuming it (`claude --resume`) so it sends its usage. "Waiting for the first report…" turns into+"✓ <name> reported" when the new machine reports.Every machine that runs sessions needs a clone of this repository with `npm ci` run in it. The Claude Code plugin runs-from the clone; for Codex, also build the reporter (`npm run build -w codex-reporter`; it needs Node 22.15 or later).+from the clone. For Codex, also build the reporter (`npm run build -w codex-reporter`; it needs Node 22.15 or later).Then:```sh@@ -97,21 +95,21 @@ ssh server "sed -n 's/^SITREP_TOKEN=//p' ~/.sitrep/server.env" \| npx tsx scripts/install.ts --claude --codex --url http://192.0.2.10:7487 --token-stdin```-Check the dry run, then run it again with `--apply`. Leave out `--claude` or `--codex` for a machine without that tool.+Check the dry run, then run it again with `--apply`. Leave out `--claude` or `--codex` where that tool is not installed.On the server machine itself, leave out `--url` and `--token-stdin`: the reporters then send to the local server, bythe rule below, with the secret from the local `server.env`.**Which URL the local reporters get.** With `--url`, both reporters use it. Without it, on a machine with a server-config (`--server` in this run, or `~/.sitrep/server.env` already there), every run that configures the reporters sets-them to that server's address, replacing a saved URL: the host is this run's `--bind`, else the saved `HOST`, else-`127.0.0.1`, and the port is this run's `--port`, else the saved `PORT`, else `7487`. `--bind` and `--port` set where-the server listens, so the install takes them only with `--server` and refuses them otherwise; to point the reporters-at a server, use `--url`. A server bound to `0.0.0.0` or `::` is reached at `127.0.0.1`; one bound to a specific address-(`localhost`, `::1`, any `127.x`, or a LAN address such as `192.0.2.10`) is reached at that address (an IPv6 address in-brackets). On a machine without a server config, a reporter set up for the first time sends to `http://127.0.0.1:7487`-and one set up before keeps the URL it was given (a Claude plugin never given one follows the default): pass `--url` there. When the reporters send to a LAN address over plain HTTP,-Claude Code on that machine shows its plain-HTTP warning (`⚠` in the status line and a toast); `--bind 0.0.0.0`, as in-[Deploy](#deploy-the-server), keeps them on `127.0.0.1` without it.+config (`--server` in this run, or `~/.sitrep/server.env` already there), every run that sets up the reporters points+them at that server, replacing a saved URL. The host is this run's `--bind`, else the saved `HOST`, else `127.0.0.1`;+the port is this run's `--port`, else the saved `PORT`, else `7487`. `--bind` and `--port` set where the server+listens, so the install refuses them without `--server`; to point the reporters at a server, use `--url`. A server+bound to `0.0.0.0` or `::` is reached at `127.0.0.1`. One bound to a specific address (`localhost`, `::1`, any `127.x`,+or a LAN address such as `192.0.2.10`) is reached at that address (an IPv6 address in brackets). On a machine without+a server config, pass `--url`: without it, a reporter set up for the first time sends to `http://127.0.0.1:7487`, and+one set up before keeps the URL it was given (a Claude plugin never given one follows the default). When the reporters send+to a LAN address over plain HTTP, Claude Code on that machine shows its plain-HTTP warning (`⚠` in the status line and+a toast); `--bind 0.0.0.0`, as in [Deploy](#deploy-the-server), keeps them on `127.0.0.1`, without the warning.What the install does, and nothing more:@@ -121,30 +119,28 @@ What the install does, and nothing more:the marketplace and `enabledPlugins` in `~/.claude/settings.json`, saves the URL under `pluginConfigs` there, and keepsthe secret in the system's secure credential store. Sessions report from their next start or after `/reload-plugins`.To try the plugin in one session without any of this: `claude --plugin-dir <clone>/mod/claude-reporter`.-- **Claude Code's telemetry**, which carries every Claude session's usage: the install merges into- `~/.claude/settings.json` the `env` keys `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_LOGS_EXPORTER=otlp`,- `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json`, `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=<the plugin's URL>/api/fleet/v1/logs`- and `OTEL_LOGS_EXPORT_INTERVAL=1000`, and `otelHeadersHelper`, which runs the clone's `scripts/claude-otel-headers.sh`- with `/bin/sh`; every other setting and hook entry stays. The helper prints the two headers the server needs:- `X-Sitrep-Machine` (the machine id) and `X-Sitrep-Token` (the admin secret, read from `~/.sitrep/claude-otel-token`).- The install writes that file (mode 0600) with the secret the reporters get, from `--token-stdin` or else this- machine's `server.env`. A run with no secret keeps a token file that is there; with no secret and no token file, the- install leaves Claude Code out, its plugin too, and says to re-run with `--token-stdin`. The secret is never in- `settings.json`, on a command line or in a URL.- The endpoint follows the URL this run sets with `--url`, else the one the plugin has. If `settings.json` already sets- Claude Code's telemetry for something else (`CLAUDE_CODE_ENABLE_TELEMETRY`, an `OTEL_` key or `otelHeadersHelper`),- the install leaves Claude Code out and says so. Claude Code reads these settings at start, so a session sends its- usage from its next start; `/reload-plugins` does not re-read them.-- **Codex:** `codex plugin marketplace add <clone>` and `codex plugin add sitrep-codex@sitrep`. The- first adds `[marketplaces.sitrep]` to `~/.codex/config.toml` (Codex reads the clone's- `.agents/plugins/marketplace.json` in place); the second copies the plugin into Codex's plugin cache and enables it with- `[plugins."sitrep-codex@sitrep"]`. Then it writes- `~/.sitrep/codex-reporter.env` (mode 0600) and the `sitrep-codex-reporter` user service, and starts+- **Claude Code's telemetry:** the install merges into `~/.claude/settings.json` the `env` keys+ `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_LOGS_EXPORTER=otlp`, `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json`,+ `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=<the plugin's URL>/api/fleet/v1/logs` and `OTEL_LOGS_EXPORT_INTERVAL=1000`, and+ `otelHeadersHelper`, which runs the clone's `scripts/claude-otel-headers.sh` with `/bin/sh`. Every other setting and+ hook entry stays. The helper prints the two headers the server needs: `X-Sitrep-Machine` (the machine id) and+ `X-Sitrep-Token` (the admin secret, read from `~/.sitrep/claude-otel-token`). The install writes that file (mode+ 0600) with the secret the reporters get, from `--token-stdin` or else this machine's `server.env`. A run with no+ secret keeps a token file that is there. With no secret and no token file, the install leaves out Claude Code, its+ plugin too, and says to re-run with `--token-stdin`. The secret is never in `settings.json`, on a command line or in+ a URL. The endpoint follows the URL this run sets with `--url`, else the one the plugin has. If `settings.json`+ already sets Claude Code's telemetry for something else (`CLAUDE_CODE_ENABLE_TELEMETRY`, an `OTEL_` key or+ `otelHeadersHelper`), the install leaves Claude Code out and says so. Claude Code reads these settings at start, so a+ session sends its usage from its next start; `/reload-plugins` does not re-read them.+- **Codex:** `codex plugin marketplace add <clone>` and `codex plugin add sitrep-codex@sitrep`. The first adds+ `[marketplaces.sitrep]` to `~/.codex/config.toml` (Codex reads the clone's `.agents/plugins/marketplace.json` in+ place). The second copies the plugin into Codex's plugin cache and enables it with `[plugins."sitrep-codex@sitrep"]`.+ Then it writes `~/.sitrep/codex-reporter.env` (mode 0600) and the `sitrep-codex-reporter` user service, and startsit. Last, it trusts the plugin's hooks: see [Codex hook trust](#codex-hook-trust).Each component you name is applied on its own, in the order server, Codex, Claude Code. One that is blocked is left-out with the reason; one whose command fails stops there; the others are still applied, except the reporters when this-run's server was left out or failed. The install then exits non-zero.+out with the reason, and one whose command fails stops there. The others are still applied, except the reporters when+this run's server was left out or failed. The install then exits non-zero.Running the install again is safe: it keeps a config that exists and changes only what you pass (`--url`, `--bind`,`--port`, the secret; the reporters' URL follows the rule above), rewrites the service unit, restarts the service and@@ -153,17 +149,16 @@ trusts the Codex hooks again.## HermesHermes's sessions reach the dashboard through `hermes-reporter`, a sidecar container that mounts Hermes's state volume-read-only and reports like codex-reporter. It needs nothing installed in Hermes and never writes to it.-Build the clone (`npm run build`), then start, stop, upgrade and read its logs with the commands in-`hermes-reporter/README.md`; it reads the server address and secret from `~/.sitrep/codex-reporter.env`.-Never mount the volume writable.+read-only. It needs nothing installed in Hermes and never writes to it. Build the clone (`npm run build`), then start,+stop, upgrade and read its logs with the commands in `hermes-reporter/README.md`. It reads the server address and+secret from `~/.sitrep/codex-reporter.env`. Never mount the volume writable.## In a Claude Code sessionThe plugin adds one command:-- `/sitrep` prints the dashboard link (the plugin's `serverUrl`), the connection state (not tried yet, online,- or offline and retrying, with the server's count of live sessions), the reporter's and the server's versions with+- `/sitrep` prints the dashboard link (the plugin's `serverUrl`), the connection state (connecting, connected with the+ server's count of live sessions, offline, token refused or report rejected), the reporter's and the server's versions withany owner, version or update notice, the reports sent, failed and rejected and the events queued and dropped, thelast error, this machine's name and id, the session id and any name given below, the session's background work, andthe reporter's time per hook. Before the session has started it says only that the reporter is loaded.@@ -184,22 +179,23 @@ port.## Settings-**In the dashboard.** Settings → Server changes answering, the activity feed, the stuck thresholds per model family,-the lifecycle timers and retention (signed in; signed out it shows them read-only). The server keeps them in its-database and applies them at once; the `server.env` values below are their defaults. A row's Reset removes the change-made in Settings, so the `server.env` value applies again, including one edited there later (after a restart). Settings-takes retention of 1 hour or more, timers of 1 second or more and stuck thresholds of 10 seconds or more. The reporters-learn the answering and feed settings from their next report reply. Settings also lists the price table and, under+**In the dashboard.** Signed in, Settings → Server changes answering, the activity feed, the stuck thresholds per model+family, the lifecycle timers and retention; signed out, it shows them read-only. The server keeps them in its database+and applies them at once; the `server.env` values below are their defaults. A row's Reset removes the change made in+Settings, so the `server.env` value applies again, including one edited there later (after a restart). Settings takes+retention of 1 hour or more, timers of 1 second or more and stuck thresholds of 10 seconds or more. The reporters get+the answering and feed settings in the reply to their next report. Settings also lists the price table and, underAbout, the address, port, allowed hosts, time zone and log level, which only `server.env` and a restart change.**In the env files.** The server and `codex-reporter` read their settings from env files (`KEY=VALUE` lines) through-`node --env-file`. Change one, then restart the service (`systemctl --user restart sitrep`, or re-run the-install). The tables list every setting each program reads, with the default it uses when the setting is unset or-empty; `scripts/server.env.example` and `scripts/codex-reporter.env.example` carry the same list.+`node --env-file`. Change one, then restart its service (`systemctl --user restart sitrep` or `sitrep-codex-reporter`,+or re-run the install).+The tables list every setting each program reads, with the default it uses when the setting is unset or empty.+`scripts/server.env.example` and `scripts/codex-reporter.env.example` carry the same list.### Server: `~/.sitrep/server.env`-The server also reads a `.env` file at the repository root when there is one (handy under `npm run dev`); a setting+The server also reads a `.env` file at the repository root when there is one (handy under `npm run dev`). A settingalready in the environment, such as one from the service's `server.env`, wins over it.| Setting | Default | Meaning |@@ -259,7 +255,7 @@ its default.| `flushIntervalMs` | `1000` | The least time between reports while something changes, in milliseconds; less than 200 reads as 200 || `heartbeatMs` | `5000` | Report at least this often even when nothing changed, in milliseconds; less than 1000 reads as 1000 || `sessionName` | empty | A display name for this machine's sessions, used after the `/sitrep name` name and Claude Code's own title ([In a Claude Code session](#in-a-claude-code-session)). Usually left empty |-| `showStatus` | on | Show the reporter's state in the status line under the prompt: `dashboard v<version> ● N live`, where the version is the dashboard's own, as the dashboard shows it under its name (the plugin's is in `/sitrep`). In place of the count it shows `○ connecting` (with no version until the server first answers), `○ offline` or `○ token refused`. After the count comes `· update plugin` or `· update server` when the versions do not fit, or `· update available` when a newer plugin exists. `⚠` comes first when the server is plain HTTP beyond this machine |+| `showStatus` | on | Show the reporter's state in the status line under the prompt: `dashboard v<version> ● N live`, where the version is the dashboard's, as shown under its name (the plugin's own is in `/sitrep`). In place of the count it shows `○ connecting` (with no version until the server first answers), `○ offline`, `○ token refused`, or `○ report rejected` when the server rejects this session's reports. After the count comes `· update plugin` or `· update server` when the versions do not fit, or `· update available` when a newer plugin exists. `⚠` comes first when the server is plain HTTP beyond this machine || `fullPrompts` | off | Send each agent's whole task prompt and final answer (up to 20,000 characters each, secrets redacted) so the dashboard can show them in full. Off, only the first 400 characters are sent |## Files and services@@ -276,16 +272,15 @@ its default.| Codex machine | `~/.codex/config.toml`, Codex's plugin cache, `~/.codex/.hook-trust/` | The marketplace and plugin entries `codex plugin` wrote, and the trust the install wrote for our hooks || Claude machine | `~/.claude/settings.json` | The marketplace, `enabledPlugins` and `pluginConfigs` entries `claude plugin` wrote (the secret is in the system's secure credential store), and the telemetry `env` keys and `otelHeadersHelper` the install wrote || Claude machine | `~/.sitrep/claude-otel-token` | The admin secret the telemetry headers helper sends (0600) |-| Each reporter machine | `~/.claude/sitrep-machine-id` (under `$CLAUDE_CONFIG_DIR` when set) | The machine id both reporters share. Uninstall keeps it, even with `--purge` |+| Each reporter machine | `~/.claude/sitrep-machine-id` (under `$CLAUDE_CONFIG_DIR` when set) | The machine id both reporters share |The services record the `PATH` of the shell that ran the install, so `codex-reporter` can find `codex` and `git`.Re-run the install after moving Node or Codex.## Security: one owner, one secret-One owner holds one admin secret, and the server speaks plain HTTP on a home LAN treated as trusted. Reads are open on-the LAN, and a machine off the LAN reaches the server through an SSH tunnel ([Off the LAN](#off-the-lan)). Know what-that means:+One owner holds one admin secret, and the server speaks plain HTTP on a home LAN treated as trusted. A machine off the+LAN reaches the server through an SSH tunnel ([Off the LAN](#off-the-lan)). What that means:- **One secret everywhere.** Every reporter machine holds the same admin secret, and it travels in clear on everyreport over plain HTTP. Anyone who can watch the LAN can copy it.@@ -294,7 +289,7 @@ that means:- **Reading is open.** Anyone who can reach port 7487 sees every session without signing in: names, machines, paths,branches, plan steps, and bounded, redacted excerpts of prompts, answers, commands, failed-tool output and messagesagents send each other.-- **What leaves each machine.** The reports carry all of that in clear over the LAN; their free text is redacted on the+- **What leaves each machine.** The reports carry all of that in clear over the LAN. Their free text is redacted on themachine and cut to fixed lengths. While a session waits on you, its report also carries the open ask as the nativeprompt shows it, redacted: the questions, the plan, or the tool call and its input, including the redacted Codex patchwhile a file approval is open. The server holds an open ask in memory only and shows it only after sign-in.@@ -312,9 +307,8 @@ Ways to narrow it, from least to most work:only lets a machine report.- Use an SSH tunnel from the laptop ([Off the LAN](#off-the-lan)): it encrypts the secret and your sign-in, and thedashboard at `localhost` is a secure context, so browser notifications work.-- Put a TLS-terminating reverse proxy in front of the server and list its host name in- `SITREP_ALLOWED_HOSTS`. HTTPS is needed only if the server is reached other than over the LAN, a tunnel or a- VPN; the server has no built-in HTTPS.+- Put a TLS-terminating reverse proxy in front of the server and list its host name in `SITREP_ALLOWED_HOSTS`. The+ server has no built-in HTTPS. You need HTTPS only if the server is reached other than over the LAN, a tunnel or a VPN.**Rotating the secret.** Put a new value in `server.env` and restart the server:@@ -325,10 +319,10 @@ systemctl --user restart sitrepOn macOS, `sed -i` is `sed -i ''` and the restart is `launchctl kickstart -k gui/$(id -u)/dev.sitrep.server`.`printf` is the shell's own, so the new secret is never on a command line. Then, on each machine, re-run the reporter-install with the new secret on `--token-stdin` and `--apply`. That updates the Claude plugin's option and-`codex-reporter.env` and restarts codex-reporter. Settings → About gives these commands, and the one that reads the-secret, for the server's OS. The new secret also ends every browser sign-in: sign in again with it. Otherwise a sign-in-lasts 400 days unused in that browser, and each use renews it.+install with the new secret on `--token-stdin` and `--apply`. That updates the Claude plugin's option, the telemetry+token file and `codex-reporter.env`, and restarts codex-reporter. Settings → About gives these commands, and the one that reads the+secret, for the server's OS. The new secret also ends every browser sign-in, so sign in again with it. Otherwise a+sign-in lasts 400 days unused in that browser, and each use renews it.## Back up and restore@@ -353,14 +347,14 @@ With the `sqlite3` tool installed, `sqlite3 ~/.sitrep/data/sitrep.sqlite ".backutakes a consistent copy without stopping the server.Restore: stop the service, delete the database and its `-wal` and `-shm` files, copy the backup in, start the service.-Every unfinished session in the backup shows its stored state; those still running carry on when their reporters send-again, a few seconds later, and the rest leave after `REMOVE_AFTER_MS`.+Every unfinished session in the backup shows its stored state. Those still running carry on when their reporters send+again, a few seconds later; the rest leave after `REMOVE_AFTER_MS`.## Upgrade-Upgrade the server first, then the other machines: a server older than its reporters answers 400 to a report that+Upgrade the server first, then the other machines. A server older than its reporters answers 400 to a report thatcarries a value it does not know, such as a new kind of event, and the reporter drops that report. Back up the database-first ([Back up and restore](#back-up-and-restore)): the server applies a new version's database migrations by itself+first ([Back up and restore](#back-up-and-restore)). The server applies a new version's database migrations by itselfwhen it starts, and going back to an older version can mean restoring that backup.On each machine:@@ -372,17 +366,17 @@ npm run build # a machine without the server: npm run build -w c```- **Server:** `systemctl --user restart sitrep` (macOS: `launchctl kickstart -k gui/$(id -u)/dev.sitrep.server`),- or re-run `npx tsx scripts/install.ts --server --apply`; the new version's migrations run as it starts. Running- sessions stay on the dashboard in their last state and carry on when their reporters next send.+ or re-run `npx tsx scripts/install.ts --server --apply`. Running sessions stay on the dashboard in their last state+ and carry on when their reporters next send.- **Codex:** re-run `npx tsx scripts/install.ts --codex --apply`. It copies the new plugin into Codex's cache, trustsits hooks again and restarts codex-reporter; the configs are kept.- **Claude Code:** re-run `npx tsx scripts/install.ts --claude --apply` (the machine's Update command in Machines does- `git pull`, `npm ci` and this); it runs `claude plugin update`, so Claude Code takes the clone's new version. Then- restart each open Claude Code session: quit it, then `claude --resume`, which keeps the conversation; new sessions+ `git pull`, `npm ci` and this). It runs `claude plugin update`, so Claude Code takes the clone's new version. Then+ restart each open Claude Code session: quit it, then `claude --resume`, which keeps the conversation. New sessionstake the new plugin at once. The same restart loads telemetry settings the install first wrote or changed. The- install keeps the telemetry settings unless the server address or the helper changed, and the admin secret already- on the machine (`~/.sitrep/claude-otel-token`); with no secret at all it leaves Claude Code out and says to re-run- with `--token-stdin`.+ install keeps the telemetry settings, unless the server address or the helper changed, and keeps the admin secret+ already on the machine (`~/.sitrep/claude-otel-token`). With no secret at all, it leaves Claude Code out and says to+ re-run with `--token-stdin`.- **Hermes:** on the Hermes machine, once its clone is built, `docker restart sitrep-hermes-reporter`(`hermes-reporter/README.md`).@@ -390,20 +384,20 @@ When a reporter and the server are on versions that do not fit, Machines and `scupdate, and the machine's row in Machines gives its Update command.**After every deploy, run `npx tsx scripts/doctor.ts` on each machine and check Machines:** every reporter's version-fits the server (doctor says "fits the server") and none reads "outdated". An outdated Claude-reporter is a session running an older plugin: its machine's clone was not updated, or the session loaded the plugin-before it was. Run that machine's Update command, then restart (resume) the session.+fits the server (doctor says "fits the server") and none reads "outdated". An outdated Claude reporter is a session+running an older plugin: its machine's clone was not updated, or the session loaded the plugin before it was. Run that+machine's Update command, then restart (resume) the session.**Prices.** At each start the server fetches LiteLLM's `model_prices_and_context_window.json` (5 s limit) and lays it-over the copy shipped in `server/model_prices_and_context_window.json`; Settings shows which one is in use and why a+over the copy shipped in `server/model_prices_and_context_window.json`. Settings shows which one is in use and why afetch failed. To refresh the shipped copy, download the file from LiteLLM's repository into that path and update`SNAPSHOT_AS_OF` in `server/src/fleet/pricing.ts`. Overrides go in `prices.json`.## Codex hook trust-Codex runs a plugin's hooks only once they are trusted, and it ties that trust to a hash of the plugin's contents+Codex runs a plugin's hooks only once they are trusted, and ties that trust to a hash of the plugin's contents(`codex-rs/hooks/src/engine/plugin_trust.rs`), so every plugin update needs it again. `install.ts --codex` writes it-the way Codex's own `/hooks` screen does (`codex-rs/tui/src/hooks_rpc.rs`):+as Codex's own `/hooks` screen does (`codex-rs/tui/src/hooks_rpc.rs`):1. `hooks/list`, for the hooks Codex finds;2. for our plugin's hooks that it lists as untrusted or modified, and no other, one `config/batchWrite`: key path@@ -415,8 +409,8 @@ runs, else a private `codex app-server` over stdio. The dry run prints both requ`sitrep-codex@sitrep:hooks/hooks.json:<event>:<group>:<handler>` (for example`sitrep-codex@sitrep:hooks/hooks.json:pre_tool_use:0:0`; `codex-rs/hooks/src/lib.rs` `hook_key`,`declarations.rs`). Codex keeps them in `~/.codex/config.toml` under `[hooks.state]`, with a content baseline in-`~/.codex/.hook-trust/`. If the install cannot reach Codex, it says so: trust the `sitrep-codex` hooks in-Codex's `/hooks` instead.+`~/.codex/.hook-trust/`. If the install cannot reach Codex, it says so; then trust the `sitrep-codex` hooks in Codex's+`/hooks` instead.While the hooks are not trusted, the machine's row in Machines shows the Codex hooks off, auto-compacts read "—" and athread outside the daemon cannot show that it waits on a permission. Usage, context, plans and agents still come from@@ -424,17 +418,17 @@ the session files. Uninstalling leaves the trust entries; they do nothing once t## Off the LAN-Sessions on the laptop keep running when it leaves the LAN; its reporters queue and drop as described in-[What runs where](#what-runs-where). To keep reporting and see the dashboard, tunnel to the server machine however you-reach it over SSH from outside:+Sessions on the laptop keep running when it leaves the LAN, and its reporters queue and drop as in+[What runs where](#what-runs-where). To keep reporting and see the dashboard, tunnel to the server machine over SSH,+however you reach it from outside:```shssh -N -L 7487:127.0.0.1:7487 server```-The dashboard is then at `http://localhost:7487`, a secure context, so browser notifications work there. (If the-server listens only on its LAN address, use `-L 7487:192.0.2.10:7487`. If something on the laptop already uses 7487,-pick another local port and use it below.) Settings → About gives this command for the server's address and port, and+The dashboard is then at `http://localhost:7487`, a secure context, so browser notifications work there. If the server+listens only on its LAN address, use `-L 7487:192.0.2.10:7487`. If something on the laptop already uses 7487, pick+another local port and use it below. Settings → About gives this command for the server's address and port, andSettings → This browser shows it while notifications are unavailable.Point the laptop's reporters at the tunnel:@@ -444,9 +438,9 @@ ssh server "sed -n 's/^SITREP_TOKEN=//p' ~/.sitrep/server.env" \| npx tsx scripts/install.ts --claude --codex --url http://127.0.0.1:7487 --token-stdin --apply```-With that, the laptop reports only while the tunnel runs, on the LAN or off it; keep the tunnel up whenever you work,-or switch back with `--url http://192.0.2.10:7487` when you are home. `--url` moves Claude Code's telemetry endpoint-with the plugin's URL; Claude Code reads it at start, so a session started before the switch sends its usage to the old+The laptop then reports only while the tunnel runs, on the LAN or off it. Keep the tunnel up whenever you work, or+switch back with `--url http://192.0.2.10:7487` when you are home. `--url` moves Claude Code's telemetry endpoint with+the plugin's URL, but Claude Code reads it at start: a session started before the switch sends its usage to the oldaddress until restarted.## Check a machine@@ -455,25 +449,26 @@ address until restarted.npx tsx scripts/doctor.ts```-It changes nothing. It checks Node, the clone and its build, the Claude plugin and its saved secret, Claude Code's-telemetry (the settings the install writes, that they send to where the plugin reports, and the headers helper, run as-Claude Code runs it; its output is never printed), the Codex plugin and its hook trust, the codex-reporter service, the-server each reporter sends to (`/api/fleet/state`), whether that server takes each admin secret a config here holds for-it (codex-reporter's, the telemetry token file's and, on the server machine, `server.env`'s), whether this machine's-reporter versions fit, as the server judges them for Machines (a version no live session reports is "last reported"),-and the machine id. A sender whose secret it cannot check gets a line saying why (the plugin's own copy is in Claude-Code's secure storage, which doctor cannot read). Each problem prints the command that fixes it, or the section here-that does, and doctor exits 1 when there is one. A machine's row in Machines and Settings → About give this command.+It changes nothing. It checks Node, the clone and its build, the Claude plugin and its saved secret, and Claude Code's+telemetry: the settings the install writes, that they send to where the plugin reports, and the headers helper, run as+Claude Code runs it (its output is never printed). It checks the Codex plugin and its hook trust, the codex-reporter+service, the server each reporter sends to (`/api/fleet/state`), and whether that server takes each admin secret a+config here holds for it (codex-reporter's, the telemetry token file's and, on the server machine, `server.env`'s). It+checks whether this machine's reporter versions fit, as the server judges them for Machines (a version no live session+reports is "last reported"), and the machine id. A sender whose secret it cannot check gets a line saying why (the+plugin's own copy is in Claude Code's secure storage, which doctor cannot read). Each problem prints the command that+fixes it, or the section here that does, and doctor exits 1 when there is one. A machine's row in Machines and+Settings → About give this command.## Troubleshooting-**Fix commands.** A machine's row in Machines gives the machine's commands for its OS, its problems named beside the-ones that fix them; Settings → About gives the server's. Run them on that machine, in its clone.+**Fix commands.** A machine's row in Machines gives its commands for its OS, each problem beside the command that fixes+it; Settings → About gives the server's. Run them on that machine, in its clone.| To | Linux (systemd) | macOS (launchd) ||---|---|---|| Check the machine | `npx tsx scripts/doctor.ts` | the same |-| Update it | `git pull && npm ci && npm run build -w codex-reporter && npx tsx scripts/install.ts --claude --codex --apply` (leave out the Codex build and `--codex`, or `--claude`, for a machine without that tool; the installer runs `claude plugin update`, so Claude Code's recorded plugin version matches the clone), then restart each open Claude Code session: quit it, then `claude --resume`. With no admin secret on the machine the installer leaves Claude Code out, applies Codex, and says to re-run with `--token-stdin` | the same |+| Update it | `git pull && npm ci && npm run build -w codex-reporter && npx tsx scripts/install.ts --claude --codex --apply` (leave out the Codex build and `--codex`, or `--claude`, where that tool is not installed), then restart each open Claude Code session: quit it, then `claude --resume`. With no admin secret on the machine, the installer leaves Claude Code out, applies Codex, and says to re-run with `--token-stdin` | the same || Trust the Codex hooks | `npx tsx scripts/install.ts --codex --apply` (or Codex's `/hooks`) | the same || Restart codex-reporter | `systemctl --user restart sitrep-codex-reporter` | `launchctl kickstart -k gui/$(id -u)/dev.sitrep.codex-reporter` || Read codex-reporter's log | `journalctl --user -u sitrep-codex-reporter -e` | `tail -n 50 ~/.sitrep/codex-reporter.log` |@@ -484,19 +479,19 @@ ones that fix them; Settings → About gives the server's. Run them on that mach| Symptom | Check ||---|---|| A session never appears | A session is kept off the dashboard until it has done something, such as its first prompt. Then run `scripts/doctor.ts` on its machine: it checks that the reporters reach the server |-| Reports refused with 401 | The reporter's secret is missing or wrong. A refused 401 carries no machine id, so Machines lists it under "N refused, no machine", by address, with the install command that fixes it: re-run the reporter install with `--token-stdin` |+| Reports refused with 401 | The reporter's secret is missing or wrong. Machines lists it under "N refused, no machine", by address, with the install command that fixes it: re-run the reporter install with `--token-stdin` || Requests refused with 403 | The server does not expect that host name. Add it to `SITREP_ALLOWED_HOSTS`, or use the IP address |-| No Codex sessions from a machine | Is codex-reporter running? `scripts/doctor.ts`, then its log, which names a session whose report it could not build, with the error. It needs Node 22.15 or later, and `codex` and `git` on the `PATH` the install recorded |+| No Codex sessions from a machine | Is codex-reporter running? Run `scripts/doctor.ts`, then read its log, which names any session whose report it could not build, with the error. It needs Node 22.15 or later, and `codex` and `git` on the `PATH` the install recorded || A machine's Codex hooks are off | Re-run `npx tsx scripts/install.ts --codex --apply`, which trusts them ([Codex hook trust](#codex-hook-trust)) || A Codex session says "Answer in its terminal" or "Answer in the Codex app" | Only threads in the machine's Codex daemon can be answered: CLI sessions and desktop-app remote projects. Desktop-app local projects (they read "Answer in the Codex app"), `codex exec`, CLI sessions started with `--no-daemon`, `--profile` or most `-c` overrides, and machines without the daemon are watch-only |-| Claude sessions show the old plugin after an upgrade (Machines: "outdated") | Run the machine's Update command (Machines), whose installer runs `claude plugin update`, then restart (resume) the session, or start a new one |-| A Claude session's usage and cost stay "—" or stop rising | Its usage comes from Claude Code's telemetry. Run `scripts/doctor.ts` on its machine: if the telemetry is not set up, run `npx tsx scripts/install.ts --claude --token-stdin --apply` as in [Add a machine](#add-a-machine), then restart (resume) the session, since Claude Code reads the settings only at start. Refused telemetry exports are listed under that machine's "N refused" (401: no or a wrong secret in `~/.sitrep/claude-otel-token`). Until the machine id exists the headers helper fails and Claude Code sends nothing; doctor says so |-| After an upgrade, a session's reporter reads "update" (Machines: "outdated"), and its asks and message box read "Answer in its terminal" | Its reporter is older than the server supports (claude-reporter 0.2.0, codex-reporter 0.3.0), so the dashboard cannot answer it ([Upgrade](#upgrade)): the machine's Update command, then restart (resume) each open Claude Code session; or update and restart codex-reporter |+| Claude sessions show the old plugin after an upgrade (Machines: "outdated") | Run the machine's Update command (Machines), then restart (resume) the session, or start a new one |+| A Claude session's usage and cost stay "—" or stop rising | Run `scripts/doctor.ts` on its machine. If Claude Code's telemetry is not set up, run `npx tsx scripts/install.ts --claude --token-stdin --apply` as in [Add a machine](#add-a-machine), then restart (resume) the session, since Claude Code reads the settings only at start. Refused telemetry exports are listed under that machine's "N refused" (401: a missing or wrong secret in `~/.sitrep/claude-otel-token`). Until the machine id exists, the headers helper fails and Claude Code sends nothing; doctor says so |+| After an upgrade, a session's reporter reads "update" (Machines: "outdated"), and its asks and message box read "Answer in its terminal" | Its reporter is older than the server supports (claude-reporter 0.2.0, codex-reporter 0.3.0), so the dashboard cannot answer it. Run the machine's Update command, then restart (resume) each open Claude Code session; or update and restart codex-reporter ([Upgrade](#upgrade)) || Nothing reports from a machine, and it has no id file (`~/.claude/sitrep-machine-id`, or under `$CLAUDE_CONFIG_DIR`) | Start codex-reporter or a Claude Code session; either creates it |-| Nothing reports from a machine, and a reporter says this machine's id cannot be read | The reporter names the file: it cannot be read, or holds no id, and no reporter makes a new id over it. Fix its permission (`chmod 644`: the Hermes sidecar reads it as another user) or delete it; a new id makes a new machine row, and the old row stays in Machines until you Remove it |+| Nothing reports from a machine, and a reporter says this machine's id cannot be read | The reporter names the file, which cannot be read or holds no id; no reporter makes a new id over it. Fix its permission (`chmod 644`: the Hermes sidecar reads it as another user) or delete it. A new id makes a new machine row, and the old row stays in Machines until you Remove it || The server does not start | Its log (`journalctl --user -u sitrep -e`, or `~/.sitrep/server.log`). It needs Node 24 || The server stops when you log out of the server machine | `loginctl enable-linger $USER` |-| A machine reads Silent | Its reporters cannot reach the server (it slept, left the LAN, or the server restarted). They send again when they can; a machine you no longer use goes with Remove. The logs of codex-reporter and the Hermes sidecar say, per session, when posting its reports began to fail and why (a connection error, no answer within 15 s, or an HTTP status), and when the server answered again |+| A machine reads Silent | Its reporters cannot reach the server (it slept, left the LAN, or the server restarted). They send again when they can. Remove a machine you no longer use. The logs of codex-reporter and the Hermes sidecar say, per session, when posting its reports began to fail and why (a connection error, no answer within 15 s, or an HTTP status), and when the server answered again || A machine is listed twice | Its id file was deleted, so it reports under a new id. Remove the old row in Machines (Remove silent) || Notifications read "Needs HTTPS or localhost" | Browsers allow notifications only on a secure context: open the dashboard at `localhost` through the tunnel, whose command Settings → This browser shows beside it |@@ -511,18 +506,18 @@ Name the components the machine has. It stops and deletes the services, and remorepository's marketplaces with the providers' own commands: `claude plugin uninstall sitrep-reporter@sitrep --scope user`(which also deletes the plugin's saved options and secret), `claude plugin marketplace remove sitrep --scope user`,`codex plugin remove sitrep-codex@sitrep` (which also deletes Codex's cached copy) and-`codex plugin marketplace remove sitrep`. With `--claude` it also removes the telemetry keys the install added-to `~/.claude/settings.json` (only while `otelHeadersHelper` still runs our helper; telemetry settings of anything else-stay). It prints where the Codex hook trust stays-([Codex hook trust](#codex-hook-trust)). With `--purge` it also deletes the named components' data: the configs, the-telemetry token file (`~/.sitrep/claude-otel-token`), the server's database, the logs, codex-reporter's saved-state and the Codex hook spool. Back up the database first if you want History.+`codex plugin marketplace remove sitrep`. With `--claude` it also removes the telemetry keys the install added to+`~/.claude/settings.json`, only while `otelHeadersHelper` still runs our helper; telemetry settings of anything else+stay. It prints where the Codex hook trust stays ([Codex hook trust](#codex-hook-trust)). With `--purge` it also+deletes the named components' data: the configs, the telemetry token file (`~/.sitrep/claude-otel-token`), the+server's database, the logs, codex-reporter's saved state and the Codex hook spool. Back up the database first if you+want History.It keeps the machine id (`~/.claude/sitrep-machine-id`), even with `--purge`, so a reinstall does not show themachine twice. To take a machine off the dashboard, uninstall it, then Remove it in Machines.-Without `--purge`, `--server` keeps `~/.sitrep/server.env`, and install then still treats the machine as a-server host ([Which URL the local reporters get](#add-a-machine)): a later `install --claude` or `--codex` without-`--url` points those reporters at this machine's old server address; `--purge`, or `--url` on that install, avoids it.-Nothing in `~/.claude/settings.json` or `~/.codex/hooks.json` that you wrote is touched, and no provider session is+Without `--purge`, `--server` keeps `~/.sitrep/server.env`, so install still treats the machine as a server host+([Which URL the local reporters get](#add-a-machine)). A later `install --claude` or `--codex` without `--url` then+points those reporters at this machine's old server address; `--purge`, or `--url` on that install, avoids it.+Nothing you wrote in `~/.claude/settings.json` or `~/.codex/hooks.json` is touched, and no provider session isdeleted.diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.mdindex 0a61fd5..5fd6688 100644--- a/docs/TUTORIAL.md+++ b/docs/TUTORIAL.md@@ -1,7 +1,6 @@# Tutorial-A short tour of the dashboard on a simulated fleet: twelve Claude Code and Codex sessions on three machines.-Every screenshot is the real interface fed by `scripts/sim.ts`; no project, path or session in them is real.+A tour of the dashboard. A simulator stands in for the agents.## Start it@@ -17,32 +16,32 @@ npx tsx scripts/sim.ts --sessions 12 --codex 0.5 --machines 3 --seed 7```Add `--chaos` to make some sessions stall, fail or go silent, so every state shows up. Reading needs no sign-in. To-answer, rename or change settings you sign in (top right) with the server's admin secret; under `npm run dev` the server-has one only if a `.env` file at the repository root sets `SITREP_TOKEN`, and the simulator then needs the same variable-in its environment.+answer, rename or change settings, sign in (top right) with the server's admin secret. Under `npm run dev` there is one+only if a `.env` file at the repository root sets `SITREP_TOKEN`, and then the simulator needs the same variable in its+environment.## The Fleet-+-The home view. At the top, a chip per state; press one to show only those sessions. At the bar's end, today's estimated-spend and each provider's plan window nearest its limit; press them for the usage panel, open in the picture above.-Headless runs and sessions nobody is attached to sit behind a chip that counts them (**Headless**, **Detached**), there-when the fleet has any.+The home view. At the top is a chip per state: press one to show only those sessions. At the bar's end are today's+estimated spend and each provider's plan window nearest its limit; press them for the usage panel. Headless runs and+sessions nobody is attached to sit behind a chip that counts them (**Headless**, **Detached**), shown when the fleet has+any.-The usage panel: estimated spend by model (today, the last 7 days or all time, ended sessions included), cost per-minute and output tokens per second. It stays open or closed as you leave it. Each machine's spend and plan windows-with their resets are on its own header among the sessions.+The usage panel shows estimated spend by model (today, the last 7 days or all time, ended sessions included), cost per+minute and output tokens per second. It stays open or closed as you leave it. Each machine's header among the sessions+shows its own spend and plan windows, with their resets.-Then **Attention**, with its counts, shut until you open it. Open, it holds **Needs you** (every open question,-permission or plan, longest wait first, answerable in the row) and **Problems** (failed or stuck sessions, stuck-agents, files two sessions both edit), each a box that scrolls.+Next comes **Attention**, with its counts. It stays shut until you open it, and holds **Needs you** (every open+question, permission or plan, longest wait first, answerable in the row) and **Problems** (failed or stuck sessions,+stuck agents, files two sessions both edit), each in a box that scrolls.-The sidebar opens with four links: **Fleet** (every machine), History, Plans and Machines. Under Machines, every-machine with live sessions, its projects and sessions under it; a machine narrows the page you are on to its own-sessions, and pressing it again, or "× Show all machines", shows them all. **Details**, at the foot, is off by default;-on, it adds a second line to each sidebar row (model with its effort word and bars, plan progress, agents running) over-its context bar, a line and a small chart to each card, and its parts to each List row: who it delegates to, notes,+The sidebar opens with four links: **Fleet** (every machine), History, Plans and Machines. Under Machines is every+machine with live sessions, with its projects and sessions. Press a machine to narrow the page you are on to its+sessions; press it again, or "× Show all machines", to show them all. **Details**, at the foot, is off by default. On,+it adds a second line to each sidebar row (model with its effort word and bars, plan progress, agents running) over its+context bar, and a line and a small chart to each card. Each List row gets its parts: who it delegates to, notes,messages, shared files and tool calls, and the next step.## Three layouts@@ -63,32 +62,32 @@ stays where you left it until you press Fit.-**Plans** (in the sidebar): every session's plan steps on a board, a column per state (Pending, In progress, Review,-Blocked, Done), each card in its session's state colour. Review holds a step whose session waits on you. A card opens-its session; sessions without a plan are not on it.+**Plans**: every session's plan steps on a board, a column per state (Pending, In progress, Review, Blocked, Done),+each card in its session's state colour. Review holds a step whose session waits on you. A card opens its session.+Sessions without a plan are not on the board.-+-The theme follows the system, or Light or Dark from the top bar. Colour always means state: green working, amber needs-you, blue idle, orange stuck, red failed.+The theme follows the system unless you pick Light or Dark in the top bar. Colour always means state: green working,+amber needs you, blue idle, orange stuck, red failed.## A session-A session's page: its state and name; machine, model and effort, path, repo and git state; Resume, Fork and the session-id to copy. Its facts (cost, tokens, time, context, the last minute's trends), its plan as a checklist, its agents as a-Timeline or a tree with their files, and at the foot the message box (a message, `/clear` or `/compact`); a session the-dashboard cannot answer, like the simulator's here, reads "Answer in its terminal" instead. An open question, permission-or plan shows first, with its answer.+At the top are its state and name; machine, model and effort, path, repo and git state; and Resume, Fork and the+session id to copy. Then its facts (cost, tokens, time, context, the last minute's trends), its plan as a checklist,+and its agents as a Timeline or a tree with their files. At the foot is the message box (a message, `/clear` or+`/compact`); a session the dashboard cannot answer, like the simulator's, reads "Answer in its terminal" instead. An+open question, permission or plan shows first, with its answer.## Machines-Each machine: reporting, quiet, silent or not seen since a restart; its sessions, versions and whether its Codex hooks-run. A row opens what the server refused from it ("N refused": reports and telemetry exports) and the commands that fix-them. **Remove** and **Remove silent** take machines off the dashboard.+Each machine with its state (reporting, quiet, silent, or not seen since a restart), its sessions, its versions and+whether its Codex hooks run. A row opens to what the server refused from it ("N refused": reports and telemetry+exports) and the commands that fix them. **Remove** and **Remove silent** take machines off the dashboard.@@ -98,13 +97,13 @@ them. **Remove** and **Remove silent** take machines off the dashboard.-Server settings apply at once (answering, the activity feed, stuck thresholds, timers, retention); Prices shows what each-model costs, long-context lines included; This browser holds the theme, notifications, refresh rates, Animation and the-keys.+Server settings (answering, the activity feed, stuck thresholds, timers, retention) apply at once. Prices shows what+each model costs, long-context lines included. This browser holds the theme, notifications, refresh rates, Animation+and the keys.-Ended sessions by day, each with its session id to copy; each opens read-only, and Delete removes one.+Ended sessions by day, each with its session id to copy. Each opens read-only, and Delete removes one.## Filter and keysdiff --git a/docs/demo.gif b/docs/demo.gifnew file mode 100644index 0000000..a00b0f9Binary files /dev/null and b/docs/demo.gif differdiff --git a/docs/tutorial/01-fleet-cards.png b/docs/tutorial/01-fleet-cards.pngindex 440f4e8..016ec54 100644Binary files a/docs/tutorial/01-fleet-cards.png and b/docs/tutorial/01-fleet-cards.png differdiff --git a/docs/tutorial/02-fleet-list.png b/docs/tutorial/02-fleet-list.pngindex 5b3ed16..67d73e2 100644Binary files a/docs/tutorial/02-fleet-list.png and b/docs/tutorial/02-fleet-list.png differdiff --git a/docs/tutorial/03-fleet-graph.png b/docs/tutorial/03-fleet-graph.pngindex e18cc19..d72712e 100644Binary files a/docs/tutorial/03-fleet-graph.png and b/docs/tutorial/03-fleet-graph.png differdiff --git a/docs/tutorial/04-plans.png b/docs/tutorial/04-plans.pngindex ccef948..2b9ad89 100644Binary files a/docs/tutorial/04-plans.png and b/docs/tutorial/04-plans.png differdiff --git a/docs/tutorial/05-fleet-light.png b/docs/tutorial/05-fleet-light.pngindex ac84960..5074362 100644Binary files a/docs/tutorial/05-fleet-light.png and b/docs/tutorial/05-fleet-light.png differdiff --git a/docs/tutorial/07-session.png b/docs/tutorial/07-session.pngindex 06000c7..011ceb9 100644Binary files a/docs/tutorial/07-session.png and b/docs/tutorial/07-session.png differdiff --git a/docs/tutorial/08-machines.png b/docs/tutorial/08-machines.pngindex d266961..c4e54da 100644Binary files a/docs/tutorial/08-machines.png and b/docs/tutorial/08-machines.png differdiff --git a/docs/tutorial/09-add-a-machine.png b/docs/tutorial/09-add-a-machine.pngindex b28695f..77cc432 100644Binary files a/docs/tutorial/09-add-a-machine.png and b/docs/tutorial/09-add-a-machine.png differdiff --git a/docs/tutorial/10-settings.png b/docs/tutorial/10-settings.pngindex 27244b0..2323f1b 100644Binary files a/docs/tutorial/10-settings.png and b/docs/tutorial/10-settings.png differdiff --git a/docs/tutorial/11-history.png b/docs/tutorial/11-history.pngindex 85a36d3..0020102 100644Binary files a/docs/tutorial/11-history.png and b/docs/tutorial/11-history.png differdiff --git a/frontend/package.json b/frontend/package.jsonindex 4c0d93e..d446a98 100644--- a/frontend/package.json+++ b/frontend/package.json@@ -1,6 +1,6 @@{"name": "frontend",- "version": "0.4.0",+ "version": "0.4.1","private": true,"license": "MIT","type": "module",diff --git a/hermes-reporter/package.json b/hermes-reporter/package.jsonindex fc1ceeb..9b74b17 100644--- a/hermes-reporter/package.json+++ b/hermes-reporter/package.json@@ -1,6 +1,6 @@{"name": "hermes-reporter",- "version": "0.4.0",+ "version": "0.4.1","private": true,"license": "MIT","type": "module",diff --git a/mod/claude-reporter/.claude-plugin/plugin.json b/mod/claude-reporter/.claude-plugin/plugin.jsonindex 8cda3c1..cd6b1d2 100644--- a/mod/claude-reporter/.claude-plugin/plugin.json+++ b/mod/claude-reporter/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "sitrep-reporter",- "version": "0.4.0",+ "version": "0.4.1","description": "Reports this Claude Code session (model, effort, plan, agents, context, git, failures) to a SITREP server, and takes answers sent from it.","userConfig": {"serverUrl": {@@ -37,7 +37,7 @@"showStatus": {"type": "boolean","title": "Status line",- "description": "The reporter's state under the prompt: 'dashboard v<the dashboard's version> ● N live', or '○ connecting', '○ offline' or '○ token refused' in place of the count; after the count, '· update plugin' or '· update server' when the versions do not fit, '· update available' when a newer plugin exists.",+ "description": "The reporter's state under the prompt: 'dashboard v<the dashboard's version> ● N live', or '○ connecting', '○ offline', '○ token refused' or '○ report rejected' in place of the count; after the count, '· update plugin' or '· update server' when the versions do not fit, '· update available' when a newer plugin exists.","default": true},"fullPrompts": {diff --git a/mod/claude-reporter/hooks/register.ts b/mod/claude-reporter/hooks/register.tsindex 6983a77..6bd7bad 100644--- a/mod/claude-reporter/hooks/register.ts+++ b/mod/claude-reporter/hooks/register.ts@@ -1218,7 +1218,7 @@ async function dashboardCommand($: Engine, args: string): Promise<string> {}if (!r) return 'SITREP: session not started yet';const t = r.transport;- const connection = t.refused ? 'token refused' : t.online === null ? 'connecting' : t.online ? `connected · ${t.liveSessions ?? 1} live` : 'offline';+ const connection = t.notLive ?? `connected · ${t.live}`;const reports = [`${t.sent} sent`, `${t.failed} failed`, `${t.rejected} rejected`, `${t.queue.length} events queued`, ...(t.dropped ? [`${t.dropped} dropped`] : [])];const times = Object.entries(hookTimes).filter(([, h]) => h.calls > 0)diff --git a/mod/claude-reporter/hooks/transport.ts b/mod/claude-reporter/hooks/transport.tsindex b99d4bf..21bf38f 100644--- a/mod/claude-reporter/hooks/transport.ts+++ b/mod/claude-reporter/hooks/transport.ts@@ -184,6 +184,7 @@ export class Transport {private rejectedWith(res: Pick<HttpResponse, 'status' | 'text'>, batch: readonly ActivityEvent[], now: number): PostOutcome {this.dropAcked(batch, batch.length);this.rejected++;+ this.online = true;this.lastError = `report rejected (${res.status})`;this.lastSentAt = now;this.rejectStreak++;@@ -258,6 +259,19 @@ export class Transport {return (this.compat === 'ok' || this.compat === null) && mine !== null && newest !== null && mine < newest;}+ /** What keeps this session off the dashboard; null while the server takes its reports. */+ get notLive(): 'token refused' | 'offline' | 'connecting' | 'report rejected' | null {+ if (this.refused) return 'token refused';+ if (this.online === false) return 'offline';+ if (this.online === null) return 'connecting';+ return this.rejectStreak > 0 ? 'report rejected' : null;+ }++ /** The server's count of live sessions; "live" alone when it has not given one, never a made-up number. */+ get live(): string {+ return this.liveSessions === null ? 'live' : `${this.liveSessions} live`;+ }+/*** The status line: `dashboard v0.1.0 ● 3 live`, or the state that keeps it from that, then a version hint. The version is* the dashboard's, as the dashboard shows it (the server's, from its last reply; none before the first), never this@@ -265,10 +279,10 @@ export class Transport {*/statusText(): string {const name = `${overPlainHttp(this.cfg.serverUrl) ? '⚠ ' : ''}dashboard${this.serverVersion ? ` v${this.serverVersion}` : ''}`;- const notLive = this.refused ? 'token refused' : this.online === false ? 'offline' : this.online === null ? 'connecting' : null;+ const notLive = this.notLive;if (notLive !== null) return `${name} ○ ${notLive}`;const hint = this.compat === 'outdated' ? 'update plugin' : this.compat === 'newer' ? 'update server' : this.behind ? 'update available' : null;- return `${name} ● ${this.liveSessions ?? 1} live${hint ? ` · ${hint}` : ''}`;+ return `${name} ● ${this.live}${hint ? ` · ${hint}` : ''}`;}/** Said once when the server is plain HTTP beyond this machine; names no address and no token. */diff --git a/package-lock.json b/package-lock.jsonindex 76b0232..9736d2e 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "sitrep",- "version": "0.4.0",+ "version": "0.4.1","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "sitrep",- "version": "0.4.0",+ "version": "0.4.1","license": "MIT","workspaces": ["server",@@ -25,7 +25,7 @@}},"codex-reporter": {- "version": "0.4.0",+ "version": "0.4.1","license": "MIT","dependencies": {"ws": "^8.22.0"@@ -41,7 +41,7 @@}},"frontend": {- "version": "0.4.0",+ "version": "0.4.1","license": "MIT","dependencies": {"d3-force": "^3.0.0",@@ -62,7 +62,7 @@}},"hermes-reporter": {- "version": "0.4.0",+ "version": "0.4.1","license": "MIT","devDependencies": {"@types/node": "^24.19.2",@@ -4815,7 +4815,7 @@}},"server": {- "version": "0.4.0",+ "version": "0.4.1","license": "MIT","dependencies": {"dotenv": "^18.0.9",diff --git a/package.json b/package.jsonindex 6af9d19..a532380 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "sitrep",- "version": "0.4.0",+ "version": "0.4.1","private": true,"license": "MIT","type": "module",diff --git a/server/package.json b/server/package.jsonindex e7b96a8..a48eaf8 100644--- a/server/package.json+++ b/server/package.json@@ -1,6 +1,6 @@{"name": "server",- "version": "0.4.0",+ "version": "0.4.1","private": true,"license": "MIT","type": "module",