agentus 0.0.0-stage → 0.2.0

package/docs/dev/01-dev-loop.md

@@ -0,0 +1,186 @@
+# Running a development instance
+
+This doc answers: how do I start a dev instance of Agentus, and how is its code and data
+kept away from the live one?
+
+## The two-worktree model
+
+Agentus is developed in **two git worktrees of the same repository**, running as two
+instances:
+
+| | live | dev |
+|---|---|---|
+| path | `worktrees/agentus` | `worktrees/agentus-dev` |
+| HTTP port | `8787` | `8901` |
+| TLS port | `8443` | disabled (`AGENTUS_TLS_PORT=0`) |
+| data dir | `<tree>/packages/server/.data` | `/tmp/agentus-qa-account` |
+| started by | `~/.hermes/cache/agentus/launch.py` | `bash scripts/dev.sh start` |
+| watcher | no (one process, no reload) | yes (`tsx watch`) |
+
+The live tree serves the operator's real sessions. The dev tree is where you edit; its
+`tsx watch` reloads on save, which is convenient precisely because its sessions are
+disposable. **Never edit the live tree while the operator is using it** — a reload there
+kills his agent children (see [03-release.md](./03-release.md) for the release path and
+[04-recover.md](./04-recover.md) for what to do if it happened).
+
+First move of any round: check where you are.
+
+```bash
+git -C worktrees/agentus      branch --show-current && git -C worktrees/agentus      status --short
+git -C worktrees/agentus-dev  branch --show-current && git -C worktrees/agentus-dev  status --short
+```
+
+Edit whatever the **dev** tree has checked out. Use absolute paths when writing files —
+the two trees have identical filenames, so nothing reminds you if you picked the wrong one.
+
+## The dev launcher: `scripts/dev.sh`
+
+Run from the dev worktree root:
+
+```bash
+bash scripts/dev.sh start     # start :8901, wait for /healthz, re-point the mock backend row
+bash scripts/dev.sh status    # is :8901 up? prints the pid, the tree, and /healthz
+bash scripts/dev.sh logs      # follow the dev log (tail -f /tmp/agentus-dev.log)
+bash scripts/dev.sh stop      # stop the process group on :8901
+bash scripts/dev.sh promote [<slug>]       # release to live — see 03-release.md
+bash scripts/dev.sh promote-log            # follow /tmp/agentus-qa-account/promote.log
+```
+
+`start` prints where everything went:
+
+```
+[dev] pid=<n> port=8901 data=/tmp/agentus-qa-account log=/tmp/agentus-dev.log
+[dev] http://127.0.0.1:8901  login scratch / scratch-pass-1
+```
+
+Defaults are overridable by `DEV_PORT`, `DEV_DATA`, `DEV_USER`, `DEV_PASS`, `DEV_LOG`.
+
+Three things `start` does that matter:
+
+- **It detaches** the server from the calling shell's process group (`detached: true`), so
+  it does not die with the terminal that launched it.
+- **It strips inherited identity.** `dev.sh` reads the caller's environment and deletes
+  every `AGENTUS_*` / `AGENTSL*` / `DEV_*` key it did not set itself, printing
+  `[dev] dropped inherited <KEY>`. This exists because a dev watcher that inherits a live
+  identity pair will, on a reload, read the live port/data and reap the live agent
+  children. Keep that behaviour when you touch the script.
+- **It re-points the `mock` backend row at this tree.** A backend row stores an absolute
+  path to the mock agent, seeded by whichever tree first created the store, so a dev
+  instance reusing a store can silently spawn the *live* tree's mock. `start` PATCHes the
+  row back to `$HERE/packages/server/mock/agent.mjs` each boot and prints
+  `[dev] re-pointing backend 'mock' at this tree (was …)` when it does.
+
+## Data directories and how they resolve
+
+The server resolves its data directory in three ordered steps, and the **boot log prints
+which one won and why** — a directory change is the thing that would otherwise read as
+"my sessions are gone":
+
+| order | rule |
+|---|---|
+| 1 | `AGENTUS_DATA` when it is set |
+| 2 | `~/.agentus` once it holds something, or when there is no repo-side data yet |
+| 3 | `<repo>/packages/server/.data` — an existing checkout that predates the install layout |
+
+For the worktrees, the outcome is fixed by the launchers rather than by the rules:
+
+- **live** — `~/.hermes/cache/agentus/launch.py` pins `AGENTUS_DATA=<live>/packages/server/.data`
+  and `AGENTUS_PORT=8787`, and pops the inherited QA/DEV keys. The launcher owns its
+  identity; it never trusts `os.environ`.
+- **dev** — `scripts/dev.sh` exports `AGENTUS_DATA=/tmp/agentus-qa-account` and
+  `AGENTUS_PORT=8901`.
+
+`agentus --where` (or `AGENTUS_PRINT_PATHS=1`) prints the resolved paths and exits without
+starting anything — the single source of truth for "where did my state go".
+
+### Keeping a dev instance's data separate
+
+The dev instance already points at `/tmp/agentus-qa-account`, so it shares nothing with
+live. Two independent knobs if you need more:
+
+- **The store** — override `AGENTUS_DATA` (as `dev.sh` does). A throwaway instance is one
+  line:
+  ```bash
+  AGENTUS_PORT=8907 AGENTUS_TLS_PORT=0 AGENTUS_DATA=/tmp/<name> npx tsx packages/server/src/index.ts
+  ```
+  Note the server reads `AGENTUS_PORT`, not bare `PORT` — and this box exports an ambient
+  `PORT=8648` (Hermes Studio), so a script that reads the ambient value starts a retry loop
+  against the wrong port.
+- **The agent subprocess home** — see below.
+
+## The mock agent backend
+
+The dev instance runs against a MOCK ACP agent:
+`packages/server/mock/agent.mjs`. It implements enough of the ACP agent surface
+(`initialize` / `newSession` / `prompt` / `cancel` / `setSessionMode` + the permission
+flow) to exercise the whole pipeline with fake streaming and no real model or token spend.
+
+The mock switches behaviour on the prompt text (per turn) and on env vars (global
+defaults). The ones QA relies on:
+
+| trigger / env | effect |
+|---|---|
+| `[think]` / `[think:N]` | stream N thought chunks before the answer |
+| `[tools:N]` | N tool calls, each with a reasoning burst (the transcript-flood case) |
+| `[tool]`, `[tool-diff]`, `[tool-hermes]` | a tool call + `requestPermission` (the approval surface) |
+| `[table]` | a deliberately-unsorted table, a local file link and a relative image |
+| `[slow]` | ~900 ms between chunks, so a socket can be dropped mid-turn |
+| `[sink]` | exit the process mid-turn (the crash path) |
+| `[plan]`, `[blocks]`, `[mcp]` | plan / structured-block / handshake-shape probes |
+| `MOCK_FORGET=1` | answer like a real agent to a forgotten session (empty `load`) |
+
+**For an ordinary prompt the mock emits no tool calls.** So a visual rule about tool cards
+(a "short card is not stretched to the column" CSS rule, say) cannot be measured from a
+real dev turn — either drive a `[tools:N]` turn or inject a fixture row with the real class
+names and assert the injection count before and after. See [02-verify.md](./02-verify.md).
+
+## Front-end hot reload
+
+The web bundle is built by Vite (`packages/web`, `vite.config.ts`). The server serves the
+**built** bundle at `packages/web/dist`, not the sources, so:
+
+- for standalone front-end work: `npm run dev -w @agentus/web` (Vite dev server, `host: true`
+  so it is reachable over the LAN);
+- for anything the dev server or a sweep must serve: **`npm run build`** first. A sweep run
+  after editing web sources but before a build measures the previous bundle and reports
+  the old behaviour as if the fix did nothing.
+
+## Isolating a slot's agent subprocess (HERMES_HOME)
+
+A spawned agent CLI inherits the server's environment, so the server **always sets
+`HERMES_HOME` explicitly**: the backend row's own home if it names one, otherwise the
+default — the operator's real `~/.hermes`. That default is intentional for the live
+instance (a slot drives the real agent). For a dev/test slot that should not touch the
+operator's data, name a directory in that row's HERMES_HOME (no permission gate exists
+any more).
+
+One trap when a row points at a fresh home: an empty home has no `config.yaml`, no
+`auth.json` and no `.env`, so `session/new` fails and the cockpit session goes `error`
+with zero messages — which looks exactly like a broken adapter. Copy **all three** files
+from a working home:
+
+```bash
+mkdir -p /tmp/<home> && cp ~/.hermes/{config.yaml,auth.json,.env} /tmp/<home>/
+```
+
+Also note a fresh home whose `hindsight/config.json` keeps the default profile name
+`"hermes"` would attach to the production memory daemon; the spawn builder warns when it
+would. Details: [`05-agent-driven.md`](./05-agent-driven.md) and
+[`docs/refs/`](../refs/).
+
+## Reading the dev logs
+
+```bash
+bash scripts/dev.sh logs              # tail -f /tmp/agentus-dev.log
+bash scripts/dev.sh status            # :8901 up? pid, tree, /healthz
+curl -s --noproxy '*' http://127.0.0.1:8901/healthz   # {"ok":true,...} + backend list
+```
+
+The dev log is a history of many launches (the `tsx watch` restarts write to it too), so
+it is not by itself evidence about the *current* process — for "did it restart?", read the
+served pid and the group leader's argv, not the log (see [03-release.md](./03-release.md)
+and [04-recover.md](./04-recover.md)).
+
+Cross-links: [02-verify.md](./02-verify.md) for the suites and sweeps ·
+[03-release.md](./03-release.md) for `promote` · [04-recover.md](./04-recover.md) for
+ports, stores and orphaned processes.

package/docs/dev/02-verify.md

@@ -0,0 +1,237 @@
+# Verifying a change
+
+This doc answers: how do I prove a change to Agentus actually works, and which check is the
+right size for which change?
+
+## Pick the cheapest evidence that can fail
+
+Not every change needs a browser. Reach for the smallest check that can actually go red:
+
+| change | evidence |
+|---|---|
+| a pure formatter / decision function | a `*.mts` unit sweep (runs under `npx tsx`, needs no build, no browser) |
+| server logic / a REST contract | a `node scripts/*.mjs` suite against a scratch server |
+| rendered UI behaviour or geometry | a CDP page sweep (`scripts/qa/*.mjs`) |
+| a release | the promote log + the served bundle (see [03-release.md](./03-release.md)) |
+| a doc / config edit | it is done when it is written — no verification run |
+
+A change with no runtime effect is finished when it is written; an unasked-for sweep just
+spends the round.
+
+## Unit suites and smoke suites
+
+### `npm test`
+
+`package.json` maps `test` to `npm run test -ws --if-present`, i.e. "run each workspace's
+own `test` script if it has one". As of this writing **no workspace defines a `test`
+script**, so `npm test` runs nothing. The runnable suites are the scripted ones below —
+run them directly. `TODO(verify)`: this placeholder is expected to gain real suites.
+
+### Server / API smoke suites (each boots its own scratch server on a random port `8900+`)
+
+```bash
+npm run typecheck                                        # 0 errors before any commit
+npm run build                                            # web bundle + shared types
+node scripts/auth-smoke.mjs                              # the lock, both credentials (~48 assertions)
+node scripts/backend-registry-smoke.mjs                  # backend registry, spawn env, health (~42)
+node scripts/workspace-smoke.mjs                         # workspace, file API, shell, attachments (~85)
+node scripts/voice-smoke.mjs                             # settings/theme guards, voice router (~47)
+npm run tls-smoke                                        # the TLS listener, real sockets + real certs
+npm run package-smoke                                    # pack + install into a throwaway HOME + boot
+node scripts/smoke.mjs mock "hello"                      # end-to-end against the mock agent
+```
+
+`backend-registry-smoke` is shaped as three layers so it passes on a machine without the
+operator's CLI: always-on (registry CRUD, spawn env, session health via the in-repo mock),
+local-only checks guarded by "does this command resolve / does that tree exist" and
+announced as `skip`, and a summary line reporting the skip count. A suite that needs a
+local binary must **skip**, never fail.
+
+### `*.mts` unit sweeps (importable TS, no build, no browser)
+
+```bash
+npm run transcript-fold   # tsx scripts/qa/transcript-fold.mts
+npm run store-fold        # tsx scripts/qa/store-fold.mts
+npm run live-stream       # tsx scripts/qa/live-stream.mts   real server frames -> real store
+npm run resume-tail
+npm run rail-recent
+npm run turn-pulse        # the silence->amber decision, with injected `now`
+npm run sentence-units
+```
+
+Plus non-aliased ones run with `npx tsx scripts/qa/<name>.mts`: `accent-text.mts` (the
+accent-as-text derivation, 61 checks), `presence-rule.mts` (`watchingNow`), `open-target.mts`,
+`plan-v2-sweep.mts`, `asr-idle-wedge.mts`. These are the right home for a **time- or
+boundary-driven decision**: extract it into a pure function with an injected `now` and
+assert either side of the boundary (59s vs 60s, `2 < 10 < 100`), because a browser cannot
+be made to wait for a 60-second window reliably.
+
+## The CDP browser sweeps
+
+`scripts/qa/*.mjs` drive a **real browser** over the Chrome DevTools Protocol and read
+computed styles and geometry from the rendered page — never assert on internals. They run
+by hand and are not in CI.
+
+### Start the debug browser
+
+Launch Edge or Chrome with remote debugging on `127.0.0.1:9222`:
+
+```bash
+open -a "Microsoft Edge" --args --remote-debugging-port=9222
+# or: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+```
+
+### Run a sweep
+
+```bash
+cd worktrees/agentus-dev
+PORT=8901 node scripts/qa/layout-sweep.mjs
+PORT=8901 W=390 H=844 node scripts/qa/popover-sweep.mjs
+```
+
+Each sweep opens its **own tab** (`PUT http://127.0.0.1:9222/json/new?<BASE>`), builds its
+own page state, and defaults to the dev port (`8901`, overridable with `PORT` / `BASE`).
+Sweeps that post REST calls want the QA data dir: `AGENTUS_DATA=/tmp/agentus-qa-account`.
+
+**Rebuild before you sweep a web change.** The dev server serves `packages/web/dist`, so
+after editing web sources run `npm run build` (or `npm run build -w @agentus/web`) first, or
+the sweep measures the previous bundle.
+
+**Page-driving sweeps on `:8901` must log in themselves.** The operator's Edge profile
+holds the cookie for the live port, not the dev one, so an unattended tab renders the login
+wall and every step reads as a 401-induced "product failure". Standard opening:
+`POST /api/auth/login` as `scratch` / `scratch-pass-1` (the `DEV_USER`/`DEV_PASS` defaults),
+then reload. Assert the page is authenticated before measuring.
+
+**Run one browser sweep at a time.** Two sweeps share this box's CPU and the one CDP
+browser; the starved one fails in a cluster of unrelated places. Re-run a red suite alone
+before believing it. And do not run a sweep in the same breath as a branch switch or any
+server-source edit — the dev watcher restarts, the page's WebSocket drops mid-run, and one
+assertion fails at random.
+
+### The exit-code discipline (or node hangs)
+
+End every sweep with:
+
+```js
+ws.close();
+process.exit(fail ? 1 : 0);
+```
+
+A sweep that only sets `process.exitCode` prints its summary and then **hangs forever on
+the open CDP WebSocket** — and a shell chaining two sweeps with `;` never reaches the
+second one. Measured: three sweeps sat "still running" 8–25 minutes after their last check,
+each holding a tab, which then made the next sweep time out. When a suite "hangs after
+passing", look for the missing exit before hunting a product bug.
+
+### Traps worth knowing before you write one
+
+- **`Runtime.evaluate` needs `awaitPromise: true`**, or a `fetch(...)` expression comes back
+  as a serialised pending Promise (`{}`) — truthy, so a step "succeeds" while nothing was
+  created.
+- **`Runtime.evaluate` must return something serialisable.** `returnByValue: true` on an
+  expression that evaluates to a DOM node fails the whole call (`Object reference chain is
+  too long`). Wrap it: `Boolean(document.querySelector('.sidebar'))`.
+- **Enter needs `text:'\r'`.** `Input.dispatchKeyEvent` with only `key:'Enter'` / `code`
+  delivers the event but the app's `keydown` handler never sees it. Add `text:'\r'`.
+- **A trusted click lands where the viewport says.** If the target is scrolled out of the
+  viewport the event is silently swallowed — `scrollIntoView({block:'center'})`, re-measure,
+  assert `top >= 0 && bottom <= innerHeight`, then click.
+- **The oracle comes from the page, not from node.** The cockpit is authenticated, so a
+  node-side `fetch('<BASE>/api/sessions')` returns 401 and every "UI value == server value"
+  comparison silently becomes "== undefined". Fetch from inside the page:
+  `ev("fetch('/api/sessions').then(r=>r.json())")`.
+- **The app consumes `?session=` and strips it** (`state.ts #openTarget` → `replaceState`),
+  so a later `location.search` read is always null — keep the id in a variable. And
+  `Page.reload` wipes injected page helpers; re-inject after every reload.
+- **Never wrap `window.WebSocket`.** Installed via `Page.addScriptToEvaluateOnNewDocument`
+  it replaces the constructor the app uses and the cockpit's own socket never connects.
+  Patch `WebSocket.prototype.send` after the app is up instead.
+- **Token-injection cannot reach the WS handshake.** Injecting the machine token as an HTTP
+  header (via `Fetch.continueRequest` with `headers` as an **array** of `{name,value}`)
+  authenticates REST but not `/ws`, and the app's WS URL carries no token. That is enough
+  to prove REST-fed surfaces on the live instance but **not** WS-fed ones like the session
+  rail's live rows — say which you proved and which you did not.
+
+### Why a visual rule needs an injected fixture row
+
+The dev instance's mock emits **no tool calls for an ordinary prompt** (see
+[01-dev-loop.md](./01-dev-loop.md)). A sweep whose subject is a `.tool-card` will therefore
+never produce one and spends its time failing. When the assertion is about the CSS, inject a
+probe with the **real class names** into the real container, measure it, remove it, and
+assert the count is unchanged (`0 → 0`) so a leaked probe cannot pass:
+
+```js
+const mk = (html) => { const d = document.createElement('div'); d.innerHTML = html;
+  const el = d.firstElementChild; stream.appendChild(el); return el; };
+const row = mk('<div class="msg"><div class="tool-card completed">…</div></div>');
+const box = row.querySelector('.tool-card').getBoundingClientRect();
+row.remove();
+```
+
+Say in the check's label which rows are real and which are probes. An operator who judges a
+layout by eye still needs a screenshot; a probe that only the script saw is not verified.
+
+### Writing a new sweep from an existing one
+
+Copy the closest existing sweep and keep its scaffolding (identical in every file):
+
+1. the CDP client (`send` / `ev` / `until` helpers over a `WebSocket`),
+2. the `check(ok, what, detail)` counter and the pass/fail summary,
+3. `PUT /json/new?<BASE>` to open the tab, `sleep(~2600)` to let the app boot,
+4. login-as-scratch if the surface needs a live socket,
+5. build the page state you need (create a **fresh** mock session rather than adopting one),
+   and reset any preference you depend on (both `localStorage` and the server setting),
+6. `ws.close(); process.exit(fail ? 1 : 0)`.
+
+Prefer a new mock `[trigger]` prompt over editing a shared fixture constant — the mock is
+spawned per session, so a new session picks up the edit with no server restart, and the
+assertion then drives a real agent bubble instead of HTML the sweep injects.
+
+## Table of existing sweeps
+
+The QA directory is large; these are the ones that carry each surface, with what each covers.
+
+| sweep (`scripts/qa/`) | covers |
+|---|---|
+| `layout-sweep.mjs` | rail indent ladder + folder icon + directory colour, accent-neutral split, three-pane widths with real pointer drags, chat column edge alignment, content-width rows (short tool card not stretched), phone 390px — 58 checks |
+| `rail-archive-sweep.mjs` | the 已归档 section: built like 工作空间 (same row shape, folder icons, grouped by directory), a fold flag that survives a reload, and the two sections keeping separate fold state for the same path — 15 checks |
+| `terminal-sweep.mjs` | the workspace panel's terminal is a real pty, not a text box: xterm mounted, a prompt only a tty prints, the shell's own echo of what was typed, an SGR colour surviving to the screen, and a resize that reaches the kernel (`stty size` + SIGWINCH) — 15 checks |
+| `queue-sweep.mjs` | the message queue: enqueue while a turn runs, the row is not in the transcript, the three buttons' order, delete/edit, automatic ordered drain on `turn-end` — 28 checks |
+| `table-sweep.mjs` | table headers sort three ways (numeric, not string), filter, full-screen reader with content rotation on a phone, a file chip in the reply, a relative image — real agent bubble via `[table]` |
+| `rail-contrast-sweep.mjs` | sidebar text contrast computed per element against its actual background, in both palettes with the operator's blue and the built-in amber; the accent-vs-neutral chroma gap |
+| `render-files-sweep.mjs` | local file links / images in a reply (all four forms), the workspace panel previewing and saving by type, the raw endpoint behind auth |
+| `popover-sweep.mjs` | every popover's geometry at both viewports (a popover can pass every DOM text assertion while being off-screen) |
+| `rail-sweep.mjs`, `rail-live-sweep.mjs`, `rail-recent-sweep.mjs` | the session rail: one title per row, row geometry, the ⋯ menu, inline rename landing in DOM *and* API, the phone bottom sheet, rail ordering |
+| `message-actions-sweep.mjs` | per-message copy (text compared character-for-character), fork-on-tail |
+| `permission-sweep.mjs` | a permission request reaches the operator's view (card + dialog), names the file, shows the diff, the answer reaches the agent, ≥32px tap targets |
+| `voice-stop-sweep.mjs`, `call-sweep.mjs` | the speech layer and the full-screen call: deliberate stop vs real failure, the hero's real animation, phases, barge-in, controls on screen at 390×844 |
+| `session-title-sweep.mjs`, `session-restart-sweep.mjs` | naming over API + browser; swapping an agent child under a live slot without it leaving the live list |
+| `transcript-sweep.mjs`, `window-ui-sweep.mjs`, `turn-line-sweep.mjs`, `turn-pulse-sweep.mjs` | transcript rendering/paging/gestures, the usage strip, the turn timer and the silence→amber state |
+| `config-sweep.mjs`, `dismiss-sweep.mjs`, `model-switch-sweep.mjs`, `plan-*-sweep.mjs` | the config/plan/model surfaces |
+| `live-endpoints-check.mjs` | the file endpoints over the machine token; same source runs against live **and** dev |
+| `think-cadence.mjs`, `render-lag-sweep.mjs`, `replay-window.mjs` | streaming cadence, render lag, replay windows |
+
+Unit (`*.mts`) sweeps: `accent-text`, `transcript-fold`, `store-fold`, `live-stream`,
+`resume-tail`, `rail-recent`, `turn-pulse`, `sentence-units`, `presence-rule`, `open-target`,
+`plan-v2-sweep`, `asr-idle-wedge`. There are also `notify-smoke.mts` (the notify contract,
+65 → 72 checks) and `notify-cockpit-e2e.mts` (a real agent turn end-to-end) for the phone
+channel; see [`docs/android-notify-contract.md`](../android-notify-contract.md).
+
+## Assertion discipline
+
+Every sweep assertion must be able to prove **this run** caused the observed state:
+
+- use a water mark (`createdAt >= runStart`) rather than "the newest row in that directory";
+- establish `cwd` for any seeded fixture (`POST /api/sessions` refuses a `cwd` that is not a
+  directory) and assert the fixture exists before asserting behaviour;
+- set what you depend on first — a leftover server preference from an earlier run turns
+  unrelated checks red;
+- judge the effect on the far side ("the button cleared our state" is not "the answer
+  reached the agent" — read the agent's own tool output);
+- when a fix is claimed, re-run the suite whose surface you touched: a change to the harness
+  invalidates every green it produced.
+
+Cross-links: [01-dev-loop.md](./01-dev-loop.md) (ports, mock triggers) ·
+[03-release.md](./03-release.md) (proving a release) ·
+[04-recover.md](./04-recover.md) (stray tabs, leaked processes).

package/docs/dev/03-release.md

@@ -0,0 +1,218 @@
+# Releasing to the live instance
+
+This doc answers: how do I move a verified change from the dev tree onto the live instance
+the operator uses, and how do I undo it?
+
+## The rule that governs every release
+
+`promote` **restarts the live server when server-side code changed**, and a restart SIGTERMs
+every live `hermes acp` child — every session the operator has open, including his current
+conversation. It is a release, not a hot reload. So:
+
+- releases happen only after the sweeps are green and, unless the change is strictly
+  web-only, **only when the operator says so** in that round;
+- a strictly web-only change may be published without asking first — but "web-only" is
+  decided by what `promote` prints, not by which files you remember editing (below).
+
+## Branches
+
+Work happens on a branch cut in the dev tree:
+
+| branch | use |
+|---|---|
+| `feat/<slug>` | a feature |
+| `fix/<slug>` | a fix (e.g. `fix/rail-readable-tokens`) |
+| `run/<slug>` | created **by `promote` on the live tree** — never check it out yourself |
+| `main` | the integration line; **not** what live runs from |
+
+`TODO(verify)`: the project also refers to a `fix/<base>/<desc>` convention; the branches
+observed in the tree are `feat/<slug>` and `fix/<slug>`.
+
+Keep the dev tree on its own branch. `promote` publishes the dev tree's **current HEAD**,
+whatever branch that is — leaving it parked on a stale branch publishes a rollback with no
+warning. `promote` guards against the common case (HEAD strictly behind `origin/main` → it
+refuses; override with `DEV_PROMOTE_FORCE=1` for a deliberate rollback), but it will not
+know that you meant to be on another branch.
+
+## Committing
+
+Commit and push the dev branch **before** promoting: `promote` refuses an uncommitted tree
+(`the dev tree has uncommitted changes — commit them first`), and the pushed branch is what
+makes the round recoverable if the release goes wrong.
+
+**Write the commit message to a file and use `-F`.** A multi-line message with inline
+backticks (`` `--text-dim` ``) or `$`/`!` triggers shell command substitution inside
+`-m "…"`, and the substitutions silently vanish from the message:
+
+```bash
+$EDITOR /tmp/msg.txt          # backticks, $ and ! are literal here
+git commit -F /tmp/msg.txt
+```
+
+## Promoting
+
+```bash
+bash scripts/dev.sh promote [<slug>]
+```
+
+If `<slug>` is omitted, the branch name is used with `/` → `-`. What it does:
+
+1. **Refuses** an uncommitted dev tree, and refuses HEAD-behind-`origin/main` (unless
+   `DEV_PROMOTE_FORCE=1`).
+2. Runs **detached** — because the restart it may cause kills the agent that ran it — and
+   writes its log to `/tmp/agentus-qa-account/promote.log`. Follow it with:
+   ```bash
+   bash scripts/dev.sh promote-log      # follows the log (it hangs until the run ends)
+   ```
+   or read `/tmp/agentus-qa-account/promote.log` directly.
+3. Checks the **live** tree out onto `run/<slug>` at the dev tip and rebuilds the web bundle.
+4. Decides whether the live process must restart, from the diff between the live tree's old
+   tip and the promoted HEAD:
+
+| trigger | files |
+|---|---|
+| server graph | `packages/server/src/**`, `packages/shared/src/**` |
+| start shape | `scripts/start.sh`, `package.json` |
+| stale launcher | the live process is still running under `tsx watch` |
+
+5. If a restart is needed, calls `scripts/relaunch.sh --port 8787 --tree <live>
+   --launcher <live launcher>`, which TERMs the process group, waits for the port to free,
+   starts the launcher, polls `/healthz`, and **asserts the pid changed** (a failure exits
+   non-zero, so "built fine, still serving old code" cannot pass).
+6. Resumes every live session it captured **before** the restart
+   (`POST /api/sessions/<id>/resume`, expected HTTP 200 each).
+
+### Web-only release (no restart)
+
+When nothing in the trigger list moved, `promote` prints `no server-side change` and the
+running server keeps its process. The new bundle is served on reload, so **no session is
+interrupted at all** — the operator only hard-refreshes his tab. The three success criteria
+are all required:
+
+- `no server-side change` printed,
+- the **asset hash moved** (`web asset: <before> -> <after>`; `promote` warns if web sources
+  changed but the hash did not),
+- the **pid did NOT move** (`lsof -ti:8787` unchanged — a moved pid means it took the
+  restart branch and the release was not the kind it claimed to be).
+
+`package.json` is a restart trigger, so **any** edit to it — even one new npm alias for a QA
+sweep — turns a web-only round into a restarting one. When a web change rides on a dev
+branch that also carries unreleased server work, cut the release from the live tip instead:
+
+```bash
+cd worktrees/agentus-dev
+git checkout -B feat/<slug>-live <live-tip>     # live tip = git -C ../agentus rev-parse HEAD
+git cherry-pick <web-commit>
+git diff --name-only <live-tip> HEAD            # MUST list only packages/web/** (+ scripts/qa/**)
+env -u AGENTUS_DATA -u AGENTUS_BASE -u AGENTUS_PORT -u DEV_* bash scripts/dev.sh promote <slug>
+```
+
+Also drop `package.json` back to the live tip's version before promoting (`git checkout
+<live-tip> -- package.json && git commit --amend --no-edit`) so the alias stays out of the
+promoted tree, and run the sweep directly (`npx tsx scripts/qa/x.mts`) where the alias is
+absent.
+
+### Never fire the release from the dev environment
+
+The shell that runs `promote` usually carries the QA instance's variables
+(`AGENTUS_DATA=/tmp/agentus-qa-account`, `AGENTUS_BASE=…:8901`, `DEV_*`), and
+`promote → relaunch.sh → launch.py` inherits them. The launcher now pins its own identity,
+but wrap it anyway to keep the environment (and the log) honest:
+
+```bash
+env -u AGENTUS_DATA -u AGENTUS_BASE -u AGENTUS_PORT \
+    -u DEV_LOG_PATH -u DEV_PROMOTE_DETACHED -u DEV_PROMOTE_SELF -u DEV_PROMOTE_SLUG \
+    bash scripts/dev.sh promote <slug>
+```
+
+## Verifying what actually got deployed (with no password)
+
+The promote log is one leg; prove the *served* instance independently. Everything below
+needs no browser and no operator password.
+
+**1. The machine token.** Each instance mints one at `<DATA_DIR>/auth.token` (0600). The
+server accepts it as `Authorization: Bearer <token>` **or** `?token=<token>`. Read it inside
+a script and never print it — and do not write the literal `Bearer <value>` shape into a
+file, because the write-time secret masker rewrites it to `***` and breaks the syntax.
+Assemble the header at runtime.
+
+```bash
+TOK=$(cat /tmp/agentus-qa-account/auth.token)          # dev;  live: worktrees/agentus/packages/server/.data/auth.token
+curl -s --noproxy '*' -H "Authorization: Bearer $TOK" http://127.0.0.1:8901/api/sessions | head -c 300
+```
+
+**2. The served asset hash.** `GET /api/version` is public and returns the served bundle
+hash. `promote` echoes it; you can also read it directly:
+
+```bash
+curl -s --noproxy '*' http://127.0.0.1:8787/api/version
+```
+
+**3. Grep the served bundle for the new markers.** Fetch the real vite-named file
+(`assets/index-<hash>.js`) and look for a string only the new code has:
+
+```bash
+HASH=$(curl -s --noproxy '*' http://127.0.0.1:8787/api/version | ...)
+curl -s --noproxy '*' "http://127.0.0.1:8787/assets/$HASH.js" | grep -c '<new-marker>'
+```
+
+Two traps: the file is `index-<hash>.js`, so a check that fetches `/assets/<hash>.js`
+misses and hits the SPA fallback (a body opening with `<!doctype` means the wrong URL, not a
+broken build); and `echo "$B" | grep -q` under `set -o pipefail` reports a **hit as a miss**
+(grep exits on first match, `echo` takes SIGPIPE) — use `grep -q "$lit" <<<"$B"` or
+`grep -c` against a saved file.
+
+**4. Rebuild locally and compare the emitted filename.** Stronger than the hash alone and
+needs no credentials: rebuild the same source in the live tree and confirm the produced
+asset filename is **identical** to the one the live instance is serving.
+
+```bash
+cd worktrees/agentus && npm run build
+ls packages/web/dist/assets/          # index-<hash>.js must match what /api/version reports
+```
+
+Same source in the two trees legitimately differs by ~5 KB (the dev build bakes absolute
+source paths into its debug info) and therefore by hash — compare **strings/paths**, not
+sizes, and expect the only differences to be tree-name fragments.
+
+After a **restarting** release, the operator's open tab keeps the old bundle until a hard
+refresh — say so in the hand-off. A web-only release needs only the hard refresh.
+
+## Merging to main
+
+Merging is a separate step from releasing, and is the standing convention for this repo once
+a release is done. `main` is not what live runs from (`promote` puts live on `run/<slug>`),
+so fast-forward the ref without checking `main` out anywhere:
+
+```bash
+cd worktrees/agentus-dev
+git fetch origin
+git push origin <dev-branch>:main          # fast-forward only
+git branch -f main origin/<dev-branch>
+git branch --set-upstream-to=origin/main main
+```
+
+Judge the outcome by identity, not by "the push succeeded": `git ls-remote origin
+refs/heads/main` must equal the commit live is actually serving.
+
+## Rollback
+
+The release path has no separate rollback mechanism — you revert the change and promote
+again:
+
+1. On the dev tree, revert or fix the offending commit.
+2. Promote. If HEAD is now behind `origin/main` and you mean to roll back deliberately,
+   `promote` refuses; override with `DEV_PROMOTE_FORCE=1 bash scripts/dev.sh promote <slug>`.
+   If the release restarted live, the new (reverted) server starts and `promote` resumes the
+   sessions it captured before the restart.
+
+The promote log is the record of what happened and where to look:
+
+- **log file:** `/tmp/agentus-qa-account/promote.log`
+- **follow:** `bash scripts/dev.sh promote-log`
+
+Relay-side incident recovery (a live instance that came up on the wrong store, a slot that
+did not resume) is in [04-recover.md](./04-recover.md).
+
+Cross-links: [01-dev-loop.md](./01-dev-loop.md) · [02-verify.md](./02-verify.md) ·
+[04-recover.md](./04-recover.md).