@huynle/hub 0.7.3 → 0.8.0

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
@@ -145,12 +188,17 @@ shell, and the hub never gets a way to run commands here.
 # 1. Download hubctl for your platform (darwin-arm64, darwin-x64, linux-x64, linux-arm64) and the signed manifest
 #    from the release, then install the binary yourself (the first apply installs the release's copy as
 #    ~/.local/bin/hubctl, with `hub` linked to it):
-curl -fsSLo hubctl https://github.com/huynle/hub/releases/download/v<version>/hubctl-darwin-arm64 && chmod +x hubctl
-curl -fsSLO https://github.com/huynle/hub/releases/download/v<version>/hubctl-manifest.json
+curl -fsSLo hubctl https://github.com/huynle/hub-releases/releases/download/v<version>/hubctl-darwin-arm64 && chmod +x hubctl
+curl -fsSLO https://github.com/huynle/hub-releases/releases/download/v<version>/hubctl-manifest.json
 
 # 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
@@ -209,7 +257,7 @@ The hub serves the web app, pairs devices, enrolls machines, and does push and (
 | Way | For | How |
 |---|---|---|
 | **`/hub` → On this computer** | Local use; nothing to install (plugin from npm) | started by the plugin with OpenCode's own runtime (`BUN_BE_BUN=1 opencode bin/hub.ts`), or `bun` when installed |
-| **Standalone binary** | Any server or laptop, no runtime needed | `hub-<os>-<arch>` from the [releases](https://github.com/huynle/hub/releases) |
+| **Standalone binary** | Any server or laptop, no runtime needed | `hub-<os>-<arch>` from the [releases](https://github.com/huynle/hub-releases/releases) (the source repository is private; releases are mirrored to the public `huynle/hub-releases`) |
 | **Docker** | Servers | `ghcr.io/huynle/hub` (linux/amd64, linux/arm64) |
 | **bunx / from source** | Bun users, development | `bunx --package @huynle/hub hub-server` · `bun bin/hub.ts` |
 | **Kubernetes (cluster mode)** | Several pods on Postgres + Valkey, rolling updates | [docs/cluster.md](docs/cluster.md), manifests in [`deploy/k8s/`](deploy/k8s/) |
@@ -221,8 +269,8 @@ answers `--help` and `--version`. While no device is paired, the hub logs a pair
 `hub-<darwin|linux>-<arm64|x64>` and `hub-windows-x64.exe`, plus `SHA256SUMS`.
 
 ```sh
-curl -LO https://github.com/huynle/hub/releases/latest/download/hub-linux-x64
-curl -LO https://github.com/huynle/hub/releases/latest/download/SHA256SUMS
+curl -LO https://github.com/huynle/hub-releases/releases/latest/download/hub-linux-x64
+curl -LO https://github.com/huynle/hub-releases/releases/latest/download/SHA256SUMS
 sha256sum --check --ignore-missing SHA256SUMS && chmod +x hub-linux-x64
 HUB_PUBLIC_URL=https://hub.example.com ./hub-linux-x64
 ```
@@ -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 |
@@ -458,9 +531,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). 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 +567,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.
@@ -696,6 +773,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 +821,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 +875,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
@@ -1050,8 +1138,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
@@ -1093,6 +1184,7 @@ holds the startup (`bin/hub.ts` serves `web/` from disk; the compiled binaries e
 | `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) |
@@ -1119,6 +1211,26 @@ the Docker image, npm package and binaries ship the build). One store fed by the
   terminal grouped by project (or server) with `+`, Recents; 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 +1330,16 @@ 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). 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.
 
@@ -1873,8 +1989,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 +2020,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 +2036,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "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.3",
+  "version": "0.8.0",
   "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>()

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

@@ -3,7 +3,8 @@
 // --input-format stream-json --output-format stream-json --verbose [--model m] [--agent a]`, so its hooks reach the
 // daemon like any `hub claude` run (HUB_CLAUDE_LAUNCH, HUB_CLAUDE_SOCKET), a turn is a user message written to its
 // stdin, the turn's end is the result line on its stdout, and an interrupt is a control request (Esc has no hook,
-// a control request works). Turns are answered in order (Claude Code runs queued user messages one after another).
+// a control request works). A profile's model (HWA-17) is the control request set_model, confirmed by Claude Code's
+// control response. Turns are answered in order (Claude Code runs queued user messages one after another).
 // When claude exits its open turns fail and onExit reports it; stopAll closes stdin (claude ends after the running
 // turn) and kills what lingers.
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
@@ -44,7 +45,8 @@ interface Turn {
 interface Proc {
   readonly child: ChildProcessWithoutNullStreams
   readonly turns: Turn[]
-  readonly controls: Map<string, () => void>
+  /** Open control requests: called with Claude Code's response, or nothing when it exited. */
+  readonly controls: Map<string, (response?: Record<string, any>) => void>
   readonly exited: Promise<void>
   stderr: string
 }
@@ -224,14 +226,32 @@ export class ClaudeLauncher {
     const proc = this.#procs.get(sessionID)
     if (!proc) return false
     for (const turn of proc.turns) turn.interrupted = true
-    const id = `hub_int_${++this.#controlID}`
-    const answered = new Promise<void>((resolve) => proc.controls.set(id, resolve))
-    proc.child.stdin.write(`${JSON.stringify({ type: "control_request", request_id: id, request: { subtype: "interrupt" } })}\n`)
-    await Promise.race([answered, sleep(CONTROL_WAIT_MS)])
-    proc.controls.delete(id)
+    await this.#control(proc, { subtype: "interrupt" }, CONTROL_WAIT_MS)
     return true
   }
 
+  /**
+   * Changes the session's model (control request set_model, a Claude Code model ID or alias); resolves when Claude
+   * Code confirms, rejects with its error, when it does not answer in `waitMs`, or for a session it did not start.
+   */
+  async setModel(sessionID: string, model: string, waitMs = CONTROL_WAIT_MS): Promise<void> {
+    const proc = this.#procs.get(sessionID)
+    if (!proc) throw new Error(`Session ${sessionID} was not started by the hub here (only hub-launched Claude Code sessions change model from the hub)`)
+    const response = await this.#control(proc, { subtype: "set_model", model }, waitMs)
+    if (!response) throw new Error("Claude Code did not confirm the model change")
+    if (response.subtype !== "success") throw new Error(typeof response.error === "string" && response.error ? response.error.slice(0, 200) : "Claude Code refused the model change")
+  }
+
+  /** Sends a control request; resolves with Claude Code's response, or undefined (no answer in time, or it exited). */
+  async #control(proc: Proc, request: Record<string, unknown>, waitMs: number): Promise<Record<string, any> | undefined> {
+    const id = `hub_ctl_${++this.#controlID}`
+    const answered = new Promise<Record<string, any> | undefined>((resolve) => proc.controls.set(id, resolve))
+    proc.child.stdin.write(`${JSON.stringify({ type: "control_request", request_id: id, request })}\n`)
+    const response = await Promise.race([answered, sleep(waitMs).then(() => undefined)])
+    proc.controls.delete(id)
+    return response
+  }
+
   /** Ends every process: stdin closed, then SIGTERM and SIGKILL for what lingers. */
   async stopAll(): Promise<void> {
     const procs = [...this.#procs.values()]
@@ -258,8 +278,8 @@ export class ClaudeLauncher {
       const turn = proc.turns.shift()
       turn?.resolve(turnResult(line, turn.interrupted))
     } else if (line.type === "control_response") {
-      const id = record(line.response).request_id
-      if (typeof id === "string") proc.controls.get(id)?.()
+      const response = record(line.response)
+      if (typeof response.request_id === "string") proc.controls.get(response.request_id)?.(response)
     }
   }
 }