@huynle/hub 0.7.4 → 0.8.1

package/README.md

@@ -46,6 +46,9 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
   Bring your own speech: OpenRouter or any OpenAI-compatible STT/TTS service (including self-hosted).
 - **What's open in your terminals first**: sessions open in Herdr or the OpenCode TUI, grouped like
   Herdr's sidebar, with the rest under Recent; rename, pin and archive in sync across devices.
+- **Fork and revert a message** (OpenCode): hover one of your messages for Copy, Fork (a new session with the
+  conversation before it, the message in its composer) and Revert (hide it and what follows, restore the files the
+  session changed, edit and resend; Restore undoes it) ([docs/session-view.md](docs/session-view.md#fork-and-revert-a-message)).
 - **Agent identity**: every session's shells carry its own hub identity, so an agent can run `hub status`, name
   itself (`@scout`), claim a role (`@@reviewer`) and read other sessions, with app tokens for scripts and device
   tokens for apps ([Agent identity](#agent-identity-agent-api)).
@@ -60,6 +63,23 @@ Formerly **opencode-voice** and, briefly, **opencode-hub**
   each harness's spoke serves, with an evidence badge and honest delivery labels
   ([docs/harnesses.md](docs/harnesses.md)). Write a spoke for another harness on the spoke SDK and check it with the
   conformance suite ([docs/spoke-sdk.md](docs/spoke-sdk.md)).
+- **Workspaces and supervision**: group sessions from any machine into a durable workspace, drag them under a
+  master or supervisor (separate from native subagent ancestry), track explicit assignments on a situation board,
+  replace a master explicitly, and keep supervisors informed with batched digests and durable checkpoints
+  ([docs/workspaces.md](docs/workspaces.md)).
+- **Split panes and side chats**: up to 4 sessions or artifacts side by side, and side chats started from a bounded
+  copy of a session that never interrupt it ([docs/workspaces.md](docs/workspaces.md#side-chats)).
+- **Agent profiles**: shared, versioned instructions, skills and commands, pinned to a session, launch or team role at
+  runtime, with an honest per-harness acknowledgment ([docs/profiles.md](docs/profiles.md)).
+- **Artifacts with AI**: persistent, revisioned documents, tables, charts, dashboards and files in an **Artifacts**
+  library. AI jobs ask about or edit them through an agent you choose, and interactive apps run only in an isolated
+  sandbox host ([docs/artifacts.md](docs/artifacts.md), [docs/artifact-host.md](docs/artifact-host.md)).
+- **Teams**: roles, an entry role that takes work, and enforced one-way or two-way communication paths (or open
+  mode), staffed with sessions from any machine. The console's **Teams** page lists them and shows each team's
+  members, work (live intake status) and communication ([docs/teams.md](docs/teams.md),
+  [intake](docs/teams-intake.md)).
+- **Watchtower** (formerly Bird's-eye view): a 3D, 2D or list picture of machines, sessions, teams and live
+  message flow, with a team editor ([docs/watchtower.md](docs/watchtower.md)).
 - **Session details**: context usage, todos, MCP status, branch and per-file diffs, on demand; unread
   marks synced per user.
 - **Self-hostable**: a hub on your computer with nothing extra to install, or your own hub for phones
@@ -83,6 +103,29 @@ opencode plugin add @huynle/hub
 opencode service restart
 ```
 
+OpenCode 2.x loads plugins per project, on the first request that opens one, and has no hook at server start: a
+freshly (re)started background service or `opencode serve` has no hub connection, so its machine shows **offline**
+until a client (the TUI, the web app) opens a project. OpenCode also unloads a project after an hour without session
+activity, and the hub plugin with it. `hub node` ([launches](docs/launches.md#hub-node)) keeps the background service
+warm by itself (cheap location reads every 30 s), and any foreground `opencode serve` you list in node.json:
+
+```json
+{ "workspaceRoots": ["/Users/you/projects"],
+  "opencode": { "servers": [{ "url": "http://127.0.0.1:4096", "passwordFile": "/Users/you/.config/hub/opencode-4096.pw" }] } }
+```
+
+(the server's `OPENCODE_PASSWORD` in a `chmod 600` file; loopback URLs only). To stop OpenCode unloading projects at
+all, set `"experimental": { "location_idle_timeout": false }` in your OpenCode config (or a longer duration such as
+`"8 hours"`). Without `hub node`, open OpenCode once, or send the read yourself, e.g. for a foreground
+`opencode serve --port 4096` with `OPENCODE_PASSWORD` set:
+`curl -fsS -u "opencode:$OPENCODE_PASSWORD" http://127.0.0.1:4096/api/agent >/dev/null`.
+
+Which sessions show **online**: the background service reports all of its recent sessions; a foreground
+`opencode serve` with `OPENCODE_PASSWORD` (or `OPENCODE_SERVER_PASSWORD`) in its environment reports every recent
+session of the projects it has loaded, idle ones included (so hub messages reach them at once); a TUI's own server,
+or a foreground server started without a password in its environment (OpenCode then makes one up the plugin cannot
+read), reports only the sessions that were active in that process.
+
 Install from npm: the npm package ships the built web app, so the plugin can run a local hub. A GitHub
 install (`opencode plugin add github:huynle/hub`) has no built web app (`web/dist` is not in the
 repository): it works for connecting to a hub that runs elsewhere, but it does not start a local hub
@@ -151,6 +194,11 @@ curl -fsSLO https://github.com/huynle/hub-releases/releases/download/v<version>/
 # 2. Enroll this machine (device code: approve it on the hub; Ctrl-C cancels). One identity for every spoke here.
 ./hubctl machine enroll --server https://hub.example.com
 ./hubctl machine status          # verified | revoked (exit 9) | offline (exit 7) | insecure (plain-http hub)
+# A plain-http hub on your LAN (a preview at http://10.x / 192.168.x): refused unless you opt in, every time, with a
+# warning; only for private-network IP addresses, never a public address or a host name (`hub login` takes it too):
+#   ./hubctl machine enroll --server http://192.168.1.20:4097 --allow-insecure-http
+#   (the spoke and hub node then use the machine token over plain http; `hub login --allow-insecure-http` likewise
+#   stores an app token that every later `hub` command sends unencrypted, with a warning each time)
 
 # 3. Preview: discover the host and print the exact plan and any manual edits. It writes nothing.
 ./hubctl setup preview --profile session-only --manifest hubctl-manifest.json --out preview.json
@@ -258,7 +306,7 @@ volumes:
 The image sets `HUB_HOST=0.0.0.0`, `HUB_PORT=4097` and `HUB_STATE_DIR=/data`. Build it locally with
 `docker build -t hub .`.
 
-**bunx / from source.** `bunx --package @huynle/hub hub-server` (needs Bun ≥ 1.3), or in
+**bunx / from source.** `bunx --package @huynle/hub hub-server` (needs Bun ≥ 1.4.4), or in
 a checkout: `npm install --no-audit --no-fund && bun bin/hub.ts`. `scripts/hub-local.sh` runs it in the
 foreground with `hub.json`; `scripts/io.github.huynle.hub.plist` is a launchd template. The
 `opencode-hub` and `opencode-voice-hub` commands still work as aliases of `hub-server`.
@@ -270,6 +318,11 @@ front of the web app, and leave `/spoke/*`, `/auth/*`, `/healthz`, `/.well-known
 icons reachable for spokes, sign-in, app discovery and the PWA (and `/mcp`, bearer-authenticated, if MCP clients
 or gateways use [MCP over HTTP](#over-http-mcp)).
 
+**Behind a reverse proxy**, set a request-body limit of about 26 MiB (artifact blobs are up to 25 MiB) and keep
+request streaming on: only the proxy closes a socket a client keeps sending on after the hub answered
+([docs/operations.md](docs/operations.md#request-bodies-and-the-front-proxy)). Back up the whole `HUB_STATE_DIR`,
+including `blobs/` (artifact bytes).
+
 ## Configuration
 
 - **Hub**: env vars (`HUB_HOST`, `HUB_PORT`, `HUB_PUBLIC_URL`, `HUB_STATE_DIR`, `OPENROUTER_API_KEY`, …)
@@ -301,11 +354,12 @@ conversation mode and utterances (403 `not_exposed` for sessions not shared with
 | `GET /api/sessions/:id/timeline/messages/:message/files/:index` | one image attached to a user message, as bytes with its type (`cache-control: private, no-store`). Timeline user items list their attachments as `files: [{index, mime, name?}]` (never the bytes). Every timeline row carries `pos` (ordering position: session message order, then part order; derived from the message's creation time, kept increasing, so it does not change as pages move); tool rows `callID`, subagent tool rows `childSessionID` and `title` (the task description), assistant text rows `ordinal`. Only PNG, JPEG, WebP and GIF are served (404 otherwise or when missing); 413 when the image would not fit in a protocol frame (about 650 KB) |
 | `POST /api/sessions/:id/rename` `{auto: true}` | Auto-name: OpenCode regenerates the title with its Title agent (`session.update` with an empty title on the process's own server). 200 `{title}` (or `{title, unchanged: true}` when OpenCode kept it), 202 `{pending: true}` when it is still generating after 20 s (the catalog updates when it lands), 409 `plugin_outdated` when no process reporting the session supports it, 502 when the process cannot reach its server or the title model failed |
 | `POST /api/sessions/:id/rename` | `{title}` → `{title}`: renames the session in OpenCode (`session.update`), through the process that owns it, else any other process that reports it. The title is trimmed and must be 1–200 characters (400 otherwise). Works with Voice off; the new title shows in every console at once (the spoke reports it before answering) |
+| `POST /api/sessions/:id/fork {messageID}` · `GET …/revert/preview?messageID=` · `POST …/revert {messageID, files?}` · `POST …/revert/restore` · `POST …/revert/commit` | fork before one of the session's user messages (201 `{sessionID, text, attachments}`), or stage, undo and commit a revert from it (409 `busy` while it runs); console only, audited; needs a spoke announcing `fork`/`revert` (409 `unsupported` otherwise). Contract: [docs/session-view.md](docs/session-view.md#fork-and-revert-a-message) |
 | `POST /api/sessions/:id/stop` | interrupts running descendants deepest first, then the root; idempotent. Also releases the hub's turn lock for the tree: a turn request still waiting answers `{outcome: "interrupted"}` and the next turn can start (`/interrupt` does the same) |
 | `GET /api/sessions/:id/summary` | context usage, todos, MCP status (at most 100 servers), branch and working-tree change stats (each part optional). `changes` lists at most 500 files, most-changed first, with `totalFiles` and `truncated`; its `additions`/`deletions` cover every file |
 | `GET /api/sessions/:id/diff?file=` | one file's patch, on demand (capped at 400 KB as JSON, then `truncated: true`); never stored in the hub |
 | `POST /api/sessions/:id/read` · `GET /api/reads` | per-user read marks, synced to your other devices |
-| `GET /api/events?lite=1&session=<id>&last=<id>` | the live stream (SSE). Every message has an `id:`; reconnecting with `Last-Event-ID` (EventSource does it) or `?last=` replays what was missed when the hub still has it (last 2000 events or 5 minutes per user; one fresh `catalog` stands for any catalog changes), else sends the catalog then `{type: "resync"}` (the page refetches what it shows). Ids are `<epoch>.<n>`; a hub restart starts a new epoch. `lite=1` leaves out `delta`/`reasoning` except of `session`'s tree (status, activity, catalog, turns and the rest still come). Heartbeat: `event: ping` every 20 s |
+| `GET /api/events?lite=1&session=<id>&last=<id>` | the live stream (SSE). Every message has an `id:`; reconnecting with `Last-Event-ID` (EventSource does it) or `?last=` replays what was missed when the hub still has it (last 2000 events or 5 minutes per user; one fresh `catalog` stands for any catalog changes), else sends the catalog then `{type: "resync"}` (the page refetches what it shows). Ids are `<epoch>.<n>`; a hub restart starts a new epoch. `lite=1` leaves out `delta`/`reasoning` except of `session`'s tree (status, activity, catalog, turns and the rest still come). Split panes add `sessions=<id>,<id>` (at most 4 with `session`, else 400): each listed tree streams, each event once, and the stream starts with `{type: "scope", sessions}` naming the ones accepted (your own only); without `sessions` nothing changes. Heartbeat: `event: ping` every 20 s |
 | `GET /api/push/prefs?endpoint=` | `{prefs, quietHours, activityMinutes, muted, subscriptions, subscribed?}`: this device's toggles (`handoff, question, permission, done, failed, turn, stopped, retry, subagentDone, subagentFailed, jobDone, jobFailed, longTool, say, activity`; `PUT` also accepts the legacy `finished` → `done` and `blocked` → question + permission), activity update interval and quiet hours, the user's muted sessions, how many subscriptions the hub holds for this device, and whether it holds `endpoint` |
 | `PUT /api/push/prefs {toggles…, quietHours?, activityMinutes?}` | boolean toggles (a 0.5.0 `blocked` sets question and permission); `quietHours` `{start: "HH:MM", end: "HH:MM", timeZone}` or `null`; `activityMinutes` a whole number 1–60 (400 when invalid) |
 | `POST /api/push/subscribe {subscription, prefs?, oldEndpoint?}` · `POST /api/push/unsubscribe {endpoint}` | this device's subscriptions; `oldEndpoint` is dropped (rotated subscription). The endpoint must be https on a public hostname that resolves only to public addresses (no loopback, private, link-local, CGNAT or ULA hosts, no `localhost`/`*.local`/`*.internal`), else 400 |
@@ -321,12 +375,31 @@ MCP exposes the same operations as `archive` and `unarchive`. Naming (`POST /api
 token with `sessions:manage`; role claims and releases take one with `sessions:manage` **and** a grant allowing
 `roles` whose projects cover the session's directory (the session must be online), under the kill switch and hourly
 cap, with every outcome in the agent audit (verbs `roles` and `roles.release`). Reserved roles stay yours to assign.
-Apps and users name the session (`session`); foreign and unknown sessions are both `404 not_found`. MCP: `name`,
+Apps and users name the session (`session`); foreign and unknown sessions are both `404 not_found`. A session token
+writes for its own session only (another one is `403 forbidden`), so an agent names itself and claims or releases its
+own roles with `hub name` / `hub role claim|release` from its shell, the OpenCode `hub` tool (verbs `name`,
+`role_claim`, `role_release`; no `session` argument) or, in Claude Code, the plugin's MCP tools. MCP: `name`,
 `role_claim` and `role_release`. Each change is one `session.named`, `role.claimed` or `role.released` event.
 
+**Intent.** Each session has an optional intent: one line (at most 280 characters) saying what it is for. It is
+untrusted text, sanitised and never interpreted. `GET /api/agent/sessions/:addr/intent` answers `{intent}`: the
+stored one, else the session's non-placeholder title (`source: "title"`), else `null` (users, `sessions:read`,
+session tokens). `PUT /api/agent/sessions/:addr/intent {text | null, expectedRevision}` sets or clears it: users
+and apps with `sessions:manage` write `source: "user"`, a session token its own session only (`source: "self"`;
+another is `403 forbidden`). A launch's `intent` is stored as `source: "launch"`, and the first prompt the hub
+carries (console, launch or acting) becomes `source: "prompt"` once. Precedence is user > launch > self > prompt >
+title; `null` falls back to the next one. A stale `expectedRevision` is `409 conflict {currentRevision}`. Stored
+intents also appear as `intent {text, source, revision}` in `GET /sessions`, `GET /sessions/:addr` and `who`.
+Changes are `session.intent {source, revision}` events, never the text. CLI `hub intent <addr> [text… | --clear]`,
+MCP `session_intent_get` / `session_intent_set`, SDK `intent(addr)` / `setIntent(addr, text, expectedRevision)`;
+the console shows it in the session's Details rail, with Edit (live: the console stream carries
+`{type: "intent", sessionID, source, revision}`, never the text). Reads fetch only the listed sessions' intents.
+Retention: every 6 h one hub drops the intents of deleted sessions and of sessions neither seen nor written for 30
+days; an online session's intent is always kept. A dropped intent's revision starts over at 0.
+
 **Events.** `GET /api/agent/events?cursor=&wait=&limit=&type=&session=` reads a bounded per-user journal (24 h or
 10,000 events) of compact events: `session.added/removed/changed`, `blocker.opened/closed`, `machine.changed`,
-`message.changed`, `launch.changed`, `session.archived`, `session.named`, `role.claimed`, `role.released`. Each is `{id, at, type, subject, data}` with IDs and states
+`message.changed`, `launch.changed`, `session.archived`, `session.named`, `session.intent`, `role.claimed`, `role.released`. Each is `{id, at, type, subject, data}` with IDs and states
 only: never prompts, message bodies, titles, blocker summaries, launch reasons or labels. Without a cursor the answer
 is empty with a cursor at the latest event; pass the returned `cursor` back to get what came after. `wait` (0–60 s)
 holds the request while nothing matches; `limit` is 1–200 (default 50); `type` (exact, or `launch.*`) and `session`
@@ -389,7 +462,7 @@ cookie and a hub bearer token (400).
 |---|---|---|---|---|
 | `GET /api/agent/whoami` | ✓ | ✓ | ✓ (any scope) | `{actor, user}` |
 | `GET /api/agent/status` | ✓ | ✓ | ✓ | machines → projects → sessions, each with name, roles, state, harness, activity and blockers, plus `attention` |
-| `GET /api/agent/sessions?project=&state=&machine=&label=k=v` | ✓ | ✓ | ✓ | the same sessions as a flat list |
+| `GET /api/agent/sessions?project=&state=&machine=&label=k=v&q=` | ✓ | ✓ | ✓ | the same sessions as a flat list; `q` (≤ 200 characters): every word must appear in the title or @name (case, `@` and punctuation ignored) |
 | `GET /api/agent/sessions/:addr` | ✓ | ✓ | ✓ | one session with full blockers and the spoke's summary (`unsupported` when its harness lacks it) |
 | `GET /api/agent/sessions/:addr/log?n=20` | ✓ | ✓ | ✓ | newest timeline rows (1–200); `422 unsupported {feature, harness}` when the spoke has no timeline, `503 offline` |
 | `GET /api/agent/watch?blocked=1&session=<addr>&cursor=` | ✓ | ✓ | ✓ (+ each family's scope) | SSE of the same compact events as `/api/agent/events` (see **Events**), after `ready`; each frame's `id:` is a cursor to resume with (`?cursor=` or `Last-Event-ID`); `reset` when it is no longer covered |
@@ -407,6 +480,11 @@ cookie and a hub bearer token (400).
 | `GET` · `PUT /api/agent/messaging {enabled}` | ✓ | – | – | the per-user messaging switch (off: `423 paused`) |
 | `POST /api/agent/app-tokens {label?, scopes?}` · `GET` · `DELETE …/:id` | ✓ | – | – | creates (token shown once), lists, revokes app tokens |
 
+Sends to a session (`msg`, `ask`, `reply`, `decline`) answer `{message, delivery, woke, wakeSkipped?}`: `woke` says
+whether the hub sent it to wake the recipient, and when not, `wakeSkipped` says why (`wake_false`, `subagent`,
+`hop_cap`, `budget`; see **Limits**). The CLI and MCP tools print it, e.g. `queued (read at its next turn) — wake
+skipped: hop limit reached`. Hubs before 0.8.1 send neither field.
+
 The act verbs, grants, kill switches and the agent audit are in [Agent actions and grants](#agent-actions-and-grants).
 
 **Decisions and `@me`.** `@me` addresses the user: `msg @me` is stored in the user's inbox (push kind `message`);
@@ -458,9 +536,12 @@ most 10,000 characters (a decline's reason 1,000).
 
 **Delivery.** A message reaches an OpenCode session as a hub message in its conversation (the spoke's `deliver`,
 OpenCode's synthetic message; it shows in the console's conversation as a message row). An idle session gets a
-turn; a busy one gets a plain `msg` after its running turn and an `ask` steered into it; subagent sessions and
-`--no-wake` messages wait for the next turn. A session that is offline gets it when it comes back (pending, for 24
-hours). A session on a spoke that cannot take messages (an older plugin, another harness without `deliver`) answers
+turn; a busy one gets a plain `msg` after its running turn and an `ask` steered into it. A `--no-wake` message never
+gets a model call of its own: an idle session reads it with its next turn; a busy one gets it once the running turn
+ends (until then the hub keeps it `pending`), so it too arrives with the next turn. Urgent `--no-wake` messages,
+replies and asks to a busy session that is not woken (a subagent, past the hop cap or wake budget) go into the running
+turn at once, which may cost that turn one more model call. Subagent sessions are never woken. A session that is
+offline gets it when it comes back (pending, for 24 hours; after that it expires undelivered, `expired`, and its sender is told: a session by a quiet hub notice, you by a notification). A session on a spoke that cannot take messages (an older plugin, another harness without `deliver`) answers
 `unsupported` (exit 7) and nothing is stored. An open ask to an idle session is re-woken with a short reminder
 after waits of 5, 15 and 45 minutes in turn, then you are notified. Messages to you and to apps are stored in an inbox (`hub inbox`).
 
@@ -491,7 +572,8 @@ sessions or apps; see [Decisions and `@me`](#agent-identity-agent-api) for the r
 **Where agents send from.**
 - In a shell of an OpenCode session: `hub msg @reviewer "…"` acts as that session ([hub CLI](#hub-cli)).
 - The model itself: the plugin's `hub` tool (verbs `msg`, `ask`, `reply`, `decline`, `inbox`, `who`, `status`,
-  `whoami`, and the [act verbs](#agent-actions-and-grants)), as the calling session ([Spoke](#spoke-opencode-plugin)).
+  `whoami`, the [team intake](docs/teams-intake.md) verbs `intake` and `intake_update`, `name`, `role_claim` and
+  `role_release` for its own @name and roles, and the [act verbs](#agent-actions-and-grants)), as the calling session ([Spoke](#spoke-opencode-plugin)).
 - You, in the OpenCode TUI: `/msg @name text` (as the session on screen) and `/who`.
 - Other agents and tools: [`hub mcp`](#hub-mcp-mcp-server), as the app token you logged in with, or the hub's
   [`POST /mcp`](#over-http-mcp) as the bearer token sent.
@@ -499,8 +581,21 @@ sessions or apps; see [Decisions and `@me`](#agent-identity-agent-api) for the r
 
 **Limits.** Per 10 minutes: 20 messages per sender→recipient pair and 300 per user (`rate_limited`, exit 6, with
 `retryAfter`), and 30 turns started per recipient (more messages are still delivered, without waking it). A chain of
-replies between agents may run 8 hops without a human turn; past that, messages are delivered without waking and
-you are notified once. Typing into a session (console, Voice, the harness) starts its chain over. You can switch
+messages between sessions may run 8 hops without a human turn; past that, messages are delivered without waking and
+you are notified once. Typing into a session (console, Voice, the harness) starts its chain over. Apps (an app
+token, and the hub's own Concierge, workspace coordinator and team intake) count hops per conversation: a new `msg`
+or `ask` from an app starts at hop 1 and replies to an app do not count against it, so an app's 5th (or 50th) ask
+still wakes the session it talks to. Two guards keep apps from restarting chains: a reply or decline counts up from
+the message it answers (reply ping-pong through an app is capped like any other chain), and for 5 minutes after a
+session sends an app something, the app's new messages to *other* sessions continue from that hop (a relay A → app →
+B → app → A reaches the cap after about 8 hops; spaced-out work starts at hop 1 again). An app answering one session
+with new messages forever is held by the pair limit and the wake budget. A team intake submitted by a session
+continues that session's chain. A send's answer says when and why it did not wake (`woke`, `wakeSkipped`); the CLI,
+`hub mcp` and the OpenCode `hub` tool print it.
+
+**Never give agents an app token.** A session that holds one (in its environment, an MCP config, a gateway) can send
+as the app, at a fresh hop depth, outside its own chain and its session-scoped policy. Sessions message with their
+own session token (the `hub` tool, `hub msg` in their shell); app tokens are for scripts and outside tools. You can switch
 messaging off for your account (`PUT /api/agent/messaging {enabled: false}`): sends then answer `paused` (exit 5),
 reading still works.
 
@@ -581,6 +676,7 @@ allow patterns (else `needs_user`) → the hourly cap → the kill switches agai
 | `gone` | 410 | 8 | answered elsewhere first, expired or ended |
 | `unsupported` | 422 | 7 | the session's spoke cannot do it (e.g. an agent's prompt without `hubPrompt`) |
 | `offline` | 503 | 7 | no spoke reports the session now |
+| `busy` | 503 | 7 | the hub's state did not answer in time (`retryAfter`): refused, try again |
 
 **Escalation.** An approval outside the grant answers `needs_user` with the evaluation (`verdict`, `reason`, the
 grants checked, and a `tier`) and opens a Decision for you: one per agent and request (asking again updates its
@@ -633,7 +729,7 @@ and the SDK. Only you manage grants: the console (Settings → Agents) or the CL
 | `GET` · `PUT /api/admin/agents/acting {enabled}` | admins | – | – |
 | `GET /api/agent/audit?limit=&before=` | ✓ | – | – |
 
-**Audit.** Every agent action and every attempt (allowed, `needs_user`, `forbidden`, `paused`, `rate_limited`) is in
+**Audit.** Every agent action and every attempt (allowed, `needs_user`, `forbidden`, `paused`, `rate_limited`, `busy`) is in
 your agent audit with who acted, the verb, the session and request, the grant, the reason and the outcome (`ok`,
 `gone`, `offline`, `unsupported`, `escalated`, `refused`, `failed`); so are your answers to escalations, grant
 requests and switch changes. Read it in Settings → Agents → Activity or with `GET /api/agent/audit` (newest first,
@@ -669,11 +765,17 @@ those harnesses through their service spokes ([docs/launches.md](docs/launches.m
 spec's fields and limits to placement, caps, the node's git rules, webhook signatures and sandboxed launches in
 OpenShell (`hub node openshell check`): [docs/launches.md](docs/launches.md).
 
+A queued launch says why it waits (`hub launches list`, `GET /api/agent/launches/:id` `waiting`, Settings → Agents &
+access → Launches): the per-user cap `agents.launches.maxActive` (default 4) with who holds it, a full node with its
+used/reserved slots, or each node's first problem. The cap counts every launcher's live launches (apps, sessions,
+you), except the Concierge's own; revoking an app token does not stop its launches, they are flagged so you can stop
+them ([docs/launches.md](docs/launches.md#how-the-caps-count)).
+
 ## hub CLI
 
 `hub` (also installed as `hubctl`) reads, names, messages and acts on your sessions through the hub's [`/api/agent` API](#agent-identity-agent-api),
-for agents and scripts. The OpenCode plugin writes both launchers into the hub bin dir (`$HUB_STATE_DIR/bin`, default
-`~/.local/state/hub/bin`) at start and puts that dir first on PATH in every shell it prepares, so inside a
+for agents and scripts. The OpenCode plugin writes both launchers into the hub bin dir (`bin` in
+the hub state dir, see `HUB_STATE_DIR` under [Configuration](#configuration): usually `~/.local/state/hub/bin`) at start and puts that dir first on PATH in every shell it prepares, so inside a
 session `hub` just works. A launcher runs the CLI bundle shipped in this package (`packages/cli/dist/hub-cli.js`)
 with the OpenCode binary itself (`BUN_BE_BUN=1 exec <opencode> hub-cli.js "$@"`), so neither bun nor node has to
 be installed; without Bun it falls back to `node`. The launchers are rewritten only when their content changes.
@@ -681,7 +783,7 @@ When a standalone hubctl is installed as `~/.local/bin/hubctl` (what `hubctl set
 instead, so shells, services and MCP clients all use that one signed program. For your own terminals the plugin also
 links `~/.local/bin/hub` to its `hub` launcher, with the setup's rule for `~/.local/bin`: only when nothing is there or
 it is hub's own link, never when another `hub` is on PATH (then it prints where hub's is), and only from the default
-state dir (not with `HUB_STATE_DIR`). `hubctl setup`'s `hub` → `hubctl` link is kept; `~/.local/bin/hubctl` is left to
+state dir (never with `HUB_STATE_DIR`). `hubctl setup`'s `hub` → `hubctl` link is kept; `~/.local/bin/hubctl` is left to
 `hubctl setup`. When `~/.local/bin` is not on PATH it prints one hint.
 
 **Name clash:** GitHub's old `hub` CLI (github/hub) uses the same name. In hub sessions ours comes first on PATH;
@@ -696,6 +798,7 @@ hub watch [--blocked] [--session <addr>]  events as JSON lines until Ctrl-C (pin
 hub whoami                                who this credential is
 hub who [--project P] [--role R | @@role] named and role-holding sessions
 hub name <@name> [--session <addr>]
+hub intent <addr> [text… | --clear]       what the session is for (one line, ≤ 280 characters)
 hub role claim <role[.project]> [--exclusive] [--session <addr>]
 hub role release <role[.project]> [--session <addr>]
 hub msg <addr> "text" [--all] [--no-wake] [--urgent]     tell: fire and forget
@@ -743,7 +846,8 @@ unchanged (for errors, the `{error: {code, message, hint?, …}}` envelope on st
 message, any candidates or retry time, a missing feature, and the hint on stderr.
 
 **Messaging.** `msg` and `ask` print what was stored and how it reached the recipient (`delivered` into a new or
-the running turn, `queued` for its next turn, `retained` while it has a question open, `pending` while offline, or
+the running turn, `queued` for its next turn, `retained` while it has a question open, `pending` while offline (or,
+for a `--no-wake` message, while the recipient's turn runs), or
 `stored` in a user's or app's inbox); `--all` sends to every session the address names (each holder of a role),
 `--no-wake` admits without starting a turn, `--urgent` steers into a running turn. A text (or `--why`) of `-` is
 read from stdin, so long or quoted bodies need no escaping: `git diff | hub msg @reviewer -`. `--expires` and
@@ -796,7 +900,16 @@ timestamps older than 5 minutes refused). The spec's fields and limits, states,
 **hub node.** `hub node run` is the per-machine daemon that prepares launch workspaces: it needs an enrolled
 machine (it only reads the machine token in `~/.config/hub/config.json`) and `~/.config/hub/node.json` with at
 least `{"workspaceRoots": ["/Users/you/projects"]}` (optional `labels`, `slots`, `memoryMB`); it exits 1 when the
-machine is not enrolled, 78 when there are no workspace roots, and 0 on SIGINT/SIGTERM. `hub node install` writes a
+machine is not enrolled, 78 when there are no workspace roots, and 0 on SIGINT/SIGTERM. While it offers the
+opencode harness (the default; node.json `"harnesses": {"opencode": false}` withholds it) it keeps OpenCode's
+background service warm: every 30 s it finds the service through its registration file
+(`$XDG_STATE_HOME/opencode/service.json`, default `~/.local/state/opencode/service.json`, read directly: no request
+before the check) and, only for a literal loopback URL without user info (127.0.0.1, [::1]; localhost is asked as
+127.0.0.1), reads `GET /api/agent` (the service's default location; redirects are never followed) so the hub plugin loads and the machine comes online without
+anyone opening a project (logged when it starts working or fails). It also loads the projects of the service's
+recent sessions under `workspaceRoots` (at most 8, or node.json `opencode.directories`), and warms each foreground
+server listed in node.json `opencode.servers` (`{url, passwordFile, directories?}`: a loopback URL and a `chmod 600`
+file holding its password; see [docs/launches.md](docs/launches.md#hub-node)) the same way. `hub node install` writes a
 launchd agent (macOS, `~/Library/LaunchAgents/io.github.huynle.hub-node.plist`) or a systemd user unit (Linux,
 `~/.config/systemd/user/hub-node.service`) from the templates in `scripts/`, with the runtime and CLI entry running
 the command (so `hubctl node install` from a hub session runs the bundle with the OpenCode binary) and
@@ -836,7 +949,7 @@ is set and the credential is not that session. The CLI removes `BUN_BE_BUN` from
 | 4 | `needs_user` |
 | 5 | `forbidden`, `paused` |
 | 6 | `rate_limited` (with `retryAfter`) |
-| 7 | `unsupported`, `offline` |
+| 7 | `unsupported`, `offline`, `busy` |
 | 8 | `gone`; an `ask --wait` that expired |
 | 9 | `unauthorized`, `token_expired` (a session token: start a new shell), or not logged in |
 
@@ -856,7 +969,10 @@ carry the same canonical compact events as `events`; their signing secret appear
 `answer` (`answer` object or `cancel`), `prompt` (`delivery`) and `stop`, and the launch tools `launch` (`repo`
 required and absolute; `mode`, `branch`, `base`, `remote`, `key`, `name`, `roles`, `harness`, `agent`, `model`,
 `runtime`, `profile`, `machine`, `nodeLabels` and `labels` objects, `prefer`, `prompt`, `end`, `timeout`,
-`cleanup`), `launches` (`state`, `label`), `launch_show` and `launch_stop` (`id`), with the same arguments
+`cleanup`), `launches` (`state`, `label`), `launch_show` and `launch_stop` (`id`); the profile tools (`profiles`,
+`profile_show`, `profile_create`, `profile_version_create`, `profile_skill_set`, `profile_command_set`,
+`profile_assign`, …; [docs/profiles.md](docs/profiles.md#sdk-and-mcp)), the workspace, artifact and team tools
+([docs/teams.md](docs/teams.md#mcp-tools); `team_staff` takes the nested launch spec), with the same arguments
 (`to`, `text`, `addr`, `id`, `requestID`, `formID`, `why`, `n`, `wake`, `urgent`, `all`, `project`, `role`, …). The act
 tools need an app token with scope `sessions:act` and a grant, the launch tools scope `sessions:launch` and a
 launch grant; `needs_user` results include the evaluation. `ask` takes `wait` of at
@@ -1050,8 +1166,11 @@ not persist those potentially sensitive details.
   keeps listening. The phone's stop words ("stop", "cancel", "never mind", "stop that", "hold on") still
   interrupt the root turn at once.
 - **Messaging other sessions**: the plugin adds a tool `hub {verb, …}` with the verbs `msg`, `ask`, `reply`,
-  `decline`, `inbox`, `who`, `status` and `whoami` (`src/spoke/hub-tool.ts`). It acts as the calling session
-  with that session's own hub token (the token never appears in the tool's output). `ask` with `wait` (seconds,
+  `decline`, `inbox`, `who`, `status`, `whoami`, `intake` and `intake_update` (`src/spoke/hub-tool.ts`). It acts as the calling session
+  with that session's own hub token (the token never appears in the tool's output). `name {name}` sets the
+  session's own @name (the old one stays an alias for 24 h; `name_taken`, invalid and reserved names fail as in
+  `hub name`), `role_claim {role, project?, exclusive?}` and `role_release {role, project?}` its own roles; these
+  take no `session`: a session changes only itself. `ask` with `wait` (seconds,
   at most 600) blocks for the answer until the tool call is stopped; without it the answer arrives later as a hub
   message. Messages from other sessions are shown in the hub's envelope and are not from the user.
 - Child text and execution events are paired by the hub. The latest assistant message of a successful
@@ -1089,10 +1208,11 @@ holds the startup (`bin/hub.ts` serves `web/` from disk; the compiled binaries e
 | `HUB_AUTH` | `pairing` | `oidc` for several users signing in with Google; see [Multi-user](#multi-user-sign-in-with-google) |
 | `HUB_HOST` / `HUB_PORT` | `127.0.0.1` / `4097` | listen address |
 | `HUB_PUBLIC_URL` | `http://<host>:<port>` (`http://127.0.0.1:<port>` when the host is `0.0.0.0` / `::`) | origin used in links, cookies and CSRF checks |
-| `HUB_STATE_DIR` | `~/.local/state/hub` | `state.json` (0600): users, machines and devices (token hashes only) with their owners, VAPID keys, push subscriptions, speech settings (server default and per user; provider API keys set from the phone), the audit log (last 500 entries); `token-keys.json` (0600): the HMAC keys that sign session tokens (created on first use, older keys kept so their tokens still verify); `agent/` (0700, files 0600, created on first use): agent data such as messages and name claims, one JSON file per user and collection, written shortly after each change and on shutdown |
+| `HUB_STATE_DIR` | `$XDG_STATE_HOME/hub` if it holds hub state (`state.json`, `token-keys.json`, `agent/`, `bin/`, … — a `bootstrap/` alone does not count), else an existing `~/.local/state/hub` holding hub state (kept after an upgrade: the hub logs the `mv` to switch), else `$XDG_STATE_HOME/hub` when XDG_STATE_HOME is set (fresh installs), else `~/.local/state/hub`; the plugin, the local hub, the hub server and the Claude Code and Codex spokes all resolve it the same way | `state.json` (0600): users, machines and devices (token hashes only) with their owners, VAPID keys, push subscriptions, speech settings (server default and per user; provider API keys set from the phone), the audit log (last 500 entries); `token-keys.json` (0600): the HMAC keys that sign session tokens (created on first use, older keys kept so their tokens still verify); `agent/` (0700, files 0600, created on first use): agent data such as messages and name claims, one JSON file per user and collection, written shortly after each change and on shutdown |
 | `HUB_TOKEN_KEYS` | | overrides `token-keys.json` with the same JSON, `{"active": "<kid>", "keys": [{"kid": "<kid>", "secret": "<base64 of ≥ 32 random bytes>", "created": <ms>}]}`, e.g. a secret shared by several hub instances; the file is then never written |
 | `HUB_DATABASE_URL` / `HUB_VALKEY_URL` | | cluster mode: several hub pods sharing Postgres and Valkey (both or neither; requires `HUB_AUTH=oidc` and `HUB_TOKEN_KEYS`); see [docs/cluster.md](docs/cluster.md) |
 | `HUB_POD_ID` | the hostname | cluster mode: this pod's unique id |
+| `HUB_DATABASE_STATEMENT_TIMEOUT_MS` | `30000` | cluster mode: Postgres `statement_timeout` of the hub's pools (`0` turns it off) |
 | `HUB_TURN_TIMEOUT_MS` | `600000` | the hub waits this + 15 s so the spoke's own timeout result arrives first |
 | `HUB_VAPID_SUBJECT` | the https public URL, else `mailto:hub@localhost` | contact sent to push services |
 | `OPENROUTER_API_KEY` | | default key for the `openrouter` speech provider (never sent to other providers) |
@@ -1116,9 +1236,30 @@ recent activity.
 the Docker image, npm package and binaries ship the build). One store fed by the hub's SSE stream drives:
 
 - **Sidebar** (⌘B collapses; a drawer on phones): search, New session, Needs you, Running, Pinned, sessions open in a
-  terminal grouped by project (or server) with `+`, Recents; rows show status, a pulsing green dot left of the
+  terminal grouped by project (or server) with `+`, Recents. Each section collapses from its heading (remembered on
+  the device, `hub.sidebar.sections.collapsed`), showing its count; Needs you always shows its count. Rows show status, a pulsing green dot left of the
   title for the session live in Voice (in Voice mode here, or in a conversation), an unread dot and a `⋯` menu
   (rename, pin, archive, stop, Allow/Disallow Voice).
+- **Primary navigation** above the session groups: **All sessions**, **Artifacts** (the library across workspaces,
+  [docs/artifacts.md](docs/artifacts.md)), **Watchtower** ([docs/watchtower.md](docs/watchtower.md)) and **Agent
+  profiles** ([docs/profiles.md](docs/profiles.md)). The sidebar's **Workspaces** tree (drag to supervise) and the
+  session ⋯ menu's **Start side chat…** are described in [docs/workspaces.md](docs/workspaces.md).
+- **Split panes**: **Open beside** in a session's `⋯` menu (table, sidebar, phone list) opens it next to the
+  focused pane, up to 4 panes, side by side, stacked or in a grid (the icon switch in the bar above the panes).
+  On desktop you can also **drag** a session row (sidebar or Workspaces tree), an artifact (Artifacts library) or
+  the Watchtower detail's **Drag into a pane** handle onto a pane: an edge splits there (left/right side by side,
+  top/bottom stacked), the centre replaces that pane, and the shape reflows (a pane dropped across a side-by-side
+  pair makes a grid). Off the pane view a small map of your panes appears to drop on. Drag a pane's grip (⠿ in
+  its header) to move it the same way. A session already open moves instead of opening twice; a fifth pane is
+  refused with a notice. The `⋯` menu's **Open in pane → left/right/top/bottom** does the same from the keyboard
+  (beside the focused pane). Drags carry no session ID or link outside the console. The focused pane
+  (accent line) owns the composer, Dictate and Voice; the URL is its session, and following a link replaces
+  it. Click a pane, or press F6 / Shift+F6 or Ctrl+Alt+1…4, to focus one; Ctrl+Alt+Shift+arrows (or the pane's
+  arrows) move it; Ctrl+Alt+W or ✕ closes it. Closing a pane never stops its session, and a pane whose session
+  vanishes closes with a notice. Drag the separators, or focus one and use the arrows (16px, Shift 64px),
+  Home/End; double-click evens them. Which panes are open is kept per device (`hub.paneLayout.v1`), their sizes
+  too (`hub.paneSizes.v1`); nothing is sent to the hub. On a phone the panes are tabs (arrow keys between
+  tabs); only the selected one is on screen and streams live text.
 - **Archive**: **Archive** in a session's `⋯` menu takes it out of the table, the sidebar's groups, Recents and
   Running, on all your devices (with **Undo**). Nothing is deleted and OpenCode's history is untouched:
   archiving is the hub's own, per user, because OpenCode has no archive API yet (when it gets one, Archive
@@ -1218,12 +1359,17 @@ Pure logic lives in `web/src/core` and `web/src/lib` (bun tests in `test/web-*.t
   a task or ask a question" (images can be attached), and under it where it runs: **Environment** (your
   machines on this hub: online first with their process and OpenCode version, offline ones listed but not
   selectable; ✓ on the chosen one), **Project** (a popover with search: Herdr workspaces with their pane
-  folders, then known folders), the folder's **branch** (from the summary of the latest session in that
+  folders, then known folders, with full paths; the chosen folder's full path shows under the chips; switching
+  the environment never carries a folder over, not even a path both machines report: the chip says "Choose a
+  project" until you pick one of that machine's own), the folder's **branch** (from the summary of the latest session in that
   folder, when there is one) and **Open in Herdr tab** (a Herdr workspace on a machine that runs Herdr; on
   by default). Submitting sends `POST /api/machines/:id/sessions {directory, herdrWorkspace?}`, opens the
   new session and sends the prompt (and images) as its first turn (`POST /api/sessions/:id/turn`). The last
-  environment and folder are remembered on the device (`localStorage` `hub.newSession`); the group "+"
-  preselects with `?machine=&key=&dir=`. "Opened in Herdr · <workspace>" confirms the new tab; if Herdr
+  environment and folder are remembered on the device (`localStorage` `hub.newSession`); the remembered folder is
+  preselected only while that machine still reports exactly that folder, and nothing else is guessed: otherwise the
+  chip says "Choose a project", and the send arrow stays grey (disabled, `aria-disabled`) until a project is chosen
+  (CON-12). A machine that reports exactly one project has it chosen; Enter without a project says so and moves the
+  focus to the Project chip (FX-06). The group "+" preselects with `?machine=&key=&dir=`. "Opened in Herdr · <workspace>" confirms the new tab; if Herdr
   failed, the session still exists and the hub's `warning` is shown. 409 (background service not
   connected) is shown under the composer.
 
@@ -1720,7 +1866,7 @@ in the file).
 | `auth` | `{mode, issuer?, clientId, clientSecret, allowed, admins}`; see [Multi-user](#multi-user-sign-in-with-google) |
 | `cluster` | `{database, valkey}` URLs for cluster mode (env `HUB_DATABASE_URL` / `HUB_VALKEY_URL` win); see [docs/cluster.md](docs/cluster.md) |
 | `agents.never` | permission patterns (`action[:glob]`) no agent may ever approve, for every user, checked before any grant; see [Agent actions and grants](#agent-actions-and-grants) |
-| `agents.launches` | per-user launch caps `{maxQueued?, maxActive?, perHour?}` (defaults 50, 4, 60); see [docs/launches.md](docs/launches.md#placement-and-caps) |
+| `agents.launches` | per-user launch caps `{maxQueued?, maxActive?, perHour?}` (defaults 50, 4, 60) and `lostAfterMinutes?` (0–1440 or false, default 5: a running launch the same node instance stops reporting, with its session gone, ends lost; 0/false: never); see [docs/launches.md](docs/launches.md#placement-and-caps) |
 | `agents.webhooks.allowPrivate` | `true` lets webhooks target `http://`, loopback and private hosts (self-hosted receivers); see [docs/launches.md](docs/launches.md#where-webhooks-may-go) |
 
 Server fields: env vars (`HUB_HOST`, `HUB_PORT`, `HUB_PUBLIC_URL`, `HUB_STATE_DIR`) > hub.json >
@@ -1760,8 +1906,11 @@ When the configured server is loopback (`localhost`, `127.0.0.1`, `[::1]`, http
 on it, the plugin starts `<this repo>/bin/hub.ts` as a detached background process bound to that
 address and port. The runtime (`resolveHubRuntime` in `src/spoke/localhub.ts`): this process when it is
 `bun`, else `bun` on `PATH`, else `~/.bun/bin/bun`, else the current executable with `BUN_BE_BUN=1`
-(inside OpenCode that is the `opencode` binary, a compiled Bun, so nothing else needs installing). Output is appended to `~/.local/state/hub/hub.log` (`$HUB_STATE_DIR`
-if set; a legacy `~/.local/state/opencode-hub`, else `~/.local/state/opencode-voice`, is copied there first). It happens on setup (**On this
+(inside OpenCode that is the `opencode` binary, a compiled Bun, so nothing else needs installing). Output is appended to `hub.log` in the hub state dir (`$HUB_STATE_DIR`, else as in the
+`HUB_STATE_DIR` row of the configuration table, usually `~/.local/state/hub`). When that dir holds no hub state yet (missing,
+empty, or only `hubctl setup`'s `bootstrap/`), the newest legacy state dir is copied there first (next to
+`bootstrap/`, never over it): `opencode-hub`, then `opencode-voice`, under `$XDG_STATE_HOME` and
+then under `~/.local/state` (never with `HUB_STATE_DIR`). It happens on setup (**On this
 computer**, any process), on **Open hub** (even with auto-start
 off), and when an enrolled connection is refused:
 the shared service process (`--service`) tries at once, other processes after 8 s so the service goes
@@ -1873,8 +2022,12 @@ npm run build:cli   # packages/cli/dist/hub-cli.js, the hub CLI bundle (prepack
 
 Console development: `bun test/web-mock-hub.ts 4311` fakes a hub with fixtures (serves `web/dist`), and
 `npm run dev:web` serves the console with hot reload, proxying `/api` to it (`HUB_URL` for a real hub).
-`npm run test:e2e` runs a headless Chromium smoke test against the mock hub at desktop and phone sizes
-(`CHROMIUM_PATH` if Playwright's browsers are not installed; screenshots go to the temp dir).
+`npm run test:e2e` (scripts/test-e2e.sh) runs every headless Chromium suite, each alone: the smoke test against the
+mock hub at desktop and phone sizes (with the nav, profiles, workspace, Watchtower, team editor and artifact suites
+it chains), then the real-hub suites `web/e2e/artifact-host.ts`, `web/e2e/artifact-bridge.ts` and
+`web/e2e/hwa-workflow.ts` (two simulated machines: side chat launch and Send to main, a declared action from an
+embedded app). Build `web/dist` first; `CHROMIUM_PATH` if Playwright's browsers are not installed; screenshots go to
+the temp dir. CI does not run them (no Chromium there): `scripts/test-ci.sh` runs the bun tests.
 
 `test/e2e-phase2.test.ts` does the same for messaging: the OpenCode spoke (with `deliver`) and a spoke without it,
 `hub msg`/`ask`/`mute` as session tokens, replies through the `hub` tool's code path, an app token with the
@@ -1900,7 +2053,9 @@ second user. The opt-in `HUB_IT_OPENCODE=1 bun test test/spoke-env-inject.it.tes
 `opencode serve` (own port, password and XDG dirs) with a local stub model and checks a real shell: its
 `HUB_SESSION_TOKEN`, and that `hub whoami` there prints the session. `HUB_IT_OPENCODE=1 bun test
 test/spoke-deliver.it.test.ts` does the same for hub messages: the model sees the delivered envelope, a repeated
-message id is applied once, `wake: false` waits for the next turn, and inbox deliveries carry their origin. `HUB_IT_OPENCODE=1 bun test test/spoke-hub-tool.it.test.ts` has the stub model call the `hub` tool and checks
+message id is applied once, `wake: false` waits for the next turn, and inbox deliveries carry their origin.
+`HUB_IT_OPENCODE=1 bun test test/e2e-quiet-delivery.it.test.ts` sends `wake: false` messages through a real hub to an
+idle and to a busy session and checks that neither costs a model call and the next real turn carries them. `HUB_IT_OPENCODE=1 bun test test/spoke-hub-tool.it.test.ts` has the stub model call the `hub` tool and checks
 that the hub sees the session's token while the model and the transcript never do. `HUB_IT_OPENCODE=1 bun test
 test/spoke-prompt-refs.it.test.ts` checks that a prompt naming a session reaches the model unchanged with the
 reference note attached, and that hub-sourced prompts get none.
@@ -1914,6 +2069,13 @@ with a throwaway `HOME`, `CLAUDE_CONFIG_DIR` / `CODEX_HOME` and a deny-all proxy
 `bun packages/spoke-sdk/scaffold.ts <name> <dir>`, whose output passes `npx hub-conformance spoke --driver "bun
 <dir>/driver.ts"` as written ([docs/spoke-sdk.md](docs/spoke-sdk.md)).
 
+`test/e2e-hwa-*.test.ts` (part of `npm test`) run workspaces, profiles, side chats, artifacts, AI jobs, teams and the
+Watchtower graph end to end across two simulated machines (`test/e2e-hwa-kit.ts`: each a node plus a service spoke,
+real launch engine): a workspace bound on both, supervision, board, digests and checkpoints, disconnect/reconnect,
+master replacement, archive and a restart that keeps everything; profile acks; jobs handled on the other machine;
+teams through `POST /mcp`; load caps; a record from a newer hub refused, never overwritten; and a tenant matrix
+that sends every parameterised route of these features as another user (answers like an unknown ID).
+
 Point a project's `.opencode/opencode.jsonc` at your checkout to try changes:
 `{ "plugins": [{ "package": "/path/to/hub" }] }`. If the plugin is also installed globally,
 OpenCode keeps the first copy with the same id, so test with `OPENCODE_CONFIG_DIR` pointing at a copy of
@@ -1944,6 +2106,42 @@ workflow). Publish it by hand after `@huynle/hub` of the same version is on npm:
 `@huynle/opencode-hub` was never published, so it has no shim. A new package name needs one manual first
 publish before trusted publishing can take over (see the comment in `release.yml`).
 
+### Hub state dir: upgrades and service units
+
+A dir counts as the hub state dir only when it holds hub state (`state.json`, `token-keys.json`, `agent/`, `blobs/`,
+`concierge-sessions.json`, `bin/`, `hub.log`, `hub.pid`, `claude-code/` or `codex/`); `hubctl setup`'s `bootstrap/`
+alone does not count, and setup writes `bootstrap/` into the dir the hub resolves. A relative `XDG_STATE_HOME` is
+ignored (the XDG spec allows only absolute paths). Nothing moves on upgrade: with
+`XDG_STATE_HOME` set and an existing `~/.local/state/hub`, the hub keeps that one and logs the `mv` command to switch.
+
+**Service units must see the same `XDG_STATE_HOME` as your shell** (or set the same `HUB_STATE_DIR`): the resolver
+runs in every process, so a unit without `XDG_STATE_HOME` next to a shell that has it can pick a different dir on a
+fresh install (two `hub.pid` locks, two Concierge lock files, launchers in one dir and logs in the other). The units
+hub writes itself (`hub claude-code install`, `hub codex-spoke install`) already pass `XDG_STATE_HOME` and
+`HUB_STATE_DIR` through. A unit you write yourself, such as one running `opencode serve --service` (the OpenCode
+background service, which loads the hub plugin), must set `Environment=XDG_STATE_HOME=…` (systemd) or the plist's
+`EnvironmentVariables` (launchd) to your shell's value, or `HUB_STATE_DIR`.
+
+### Testing and preview isolation
+
+A test or preview OpenCode with the hub plugin shares the user's files unless told otherwise: its spoke may
+auto-start a hub, write the `hub`/`hubctl` launchers, the Concierge lock file and `hub.log`, and read Herdr. Keep it
+apart:
+
+- **State**: an isolated instance MUST set `HUB_STATE_DIR` to a scratch directory and its own `HOME` (plus its own
+  `XDG_CONFIG_HOME` / `XDG_STATE_HOME` / `XDG_DATA_HOME` / `XDG_CACHE_HOME`). `XDG_STATE_HOME` alone is not enough:
+  the state dir is sticky, so with the real `~/.local/state/hub` present it is used even when `XDG_STATE_HOME` points
+  elsewhere. With `HUB_STATE_DIR` set the plugin never links `~/.local/bin/hub` and migrates nothing. With `HUB_STATE_DIR` set,
+  the Concierge lock is read and written only there: an isolated instance never reads the user's
+  `~/.local/state/hub` or `$XDG_STATE_HOME/hub`.
+- **Spoke config** (`config.json` in its own `XDG_CONFIG_HOME/hub`, or `HUB_SPOKE_CONFIG`): `"herdr": false` (no
+  reading the user's Herdr panes), `"autoStartLocalHub": false` (no hub started on a loopback URL that is down), and
+  the test hub's URL.
+- **Sessions**: create them only in scratch repositories (a temp dir with `git init`), never in a real project, so
+  a stray session, launch or worktree cannot land in your work.
+- Never restart the user's `opencode serve --service`; start a private `opencode serve` on its own port and
+  password (as the `*.it.test.ts` suites do).
+
 ## Known limits
 
 - Speech-to-text is batch per utterance (on-device voice detection + one request per utterance); no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "Hub: a harness-agnostic central hub your AI agent harnesses connect to (OpenCode first). Follow, steer and stop sessions from your phone or browser, with notifications, optional hands-free Voice and a self-hostable server.",
   "license": "MIT",
   "author": "Huy Le",
@@ -99,7 +99,7 @@
     "packages/codex"
   ],
   "engines": {
-    "bun": ">=1.3"
+    "bun": ">=1.4.4"
   },
   "publishConfig": {
     "access": "public"
@@ -110,7 +110,7 @@
     "build:web": "vite build --config web/vite.config.ts",
     "build:cli": "bun build packages/cli/src/main.ts --target=node --outfile=packages/cli/dist/hub-cli.js",
     "dev:web": "vite --config web/vite.config.ts",
-    "test:e2e": "bun web/e2e/smoke.ts",
+    "test:e2e": "bash scripts/test-e2e.sh",
     "prepack": "npm run build:web && npm run build:cli",
     "hub": "bun bin/hub.ts"
   },
@@ -121,7 +121,9 @@
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
+    "@types/three": "0.186.0",
     "@types/web-push": "^3.6.4",
+    "3d-force-graph": "1.80.1",
     "onnxruntime-web": "1.23.2",
     "playwright-core": "^1.64.1",
     "solid-js": "^1.9.17",

package/packages/claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-claude-code",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "private": true,
   "description": "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/claude-code/src/daemon.ts

@@ -9,7 +9,7 @@
 // once and runs its claude headless (launcher.ts) with the hub plugin, so its hooks come back here like any other
 // session's. turn and interrupt reach only those sessions (stdin user messages, control requests); a terminal
 // session refuses them. stop interrupts a launched session's running turn at once, besides the hook-level stop.
-// Stopping the daemon ends the claude processes it started.
+// Stopping the daemon ends the claude processes it started. profileApply (HWA-17, profile.ts) is served either way.
 //
 // A `hub claude` run registers its pid ("launch"); the daemon checks it now and then and ends the run's sessions
 // when the process is gone (Claude Code killed without SessionEnd), and at once when the wrapper reports its exit.
@@ -23,6 +23,7 @@ import { parseHookInput } from "./hook-input.ts"
 import { ensurePrivateDir, SOCKET_PATH_MAX } from "./paths.ts"
 import { createMcpRouter, MCP_END, type McpRouter } from "./mcp.ts"
 import { ClaudeLauncher, launchAgent, launchDirectory, launchModel } from "./launcher.ts"
+import { ClaudeProfiles } from "./profile.ts"
 import { hubReferences } from "./references.ts"
 import { ClaudeSessions, type SessionsOptions } from "./sessions.ts"
 import { ask, onLines, WIRE_VERSION } from "./wire.ts"
@@ -167,9 +168,14 @@ export async function startDaemon(options: DaemonOptions): Promise<ClaudeDaemon>
     return { stopped: stopped.stopped.length ? stopped.stopped : [req.sessionID] }
   }
 
+  const profiles = new ClaudeProfiles({
+    kind: (id, native = sessions.nativeOf(id)) => (native === undefined ? undefined : launchKeys.has(native) ? "launched" : "terminal"),
+    setModel: (id, model) => launcher!.setModel(sessions.nativeOf(id)!, model),
+  })
   const handlers: OpHandlers = {
     permission: (req) => sessions.permission(req),
     stop,
+    profileApply: profiles.handle,
     ...(launcher ? { create, turn, interrupt } : {}),
   }
   const features: ModifierFeature[] = ["permissionMessage", "hubPrompt", ...(launcher ? (["launch"] as const) : [])]
@@ -195,6 +201,7 @@ export async function startDaemon(options: DaemonOptions): Promise<ClaudeDaemon>
     ...(options.tokenWaitMs !== undefined ? { tokenWaitMs: options.tokenWaitMs } : {}),
     ...(options.permissionWaitMs !== undefined ? { permissionWaitMs: options.permissionWaitMs } : {}),
     references: options.references ?? hubReferences((id) => spoke.sessionToken(id)),
+    profiles,
   })
 
   const launches = new Map<string, number>()