From 693105d22cc2d5ccccef70745b2ea0e00caf21dd Mon Sep 17 00:00:00 2001 From: James Reilly Date: Fri, 30 Oct 2026 19:50:06 +0000 Subject: [PATCH 1/6] docs(hive): record Spindle Hive layout, per-hive GitHub Apps and Bitwarden recovery items School and Reef now use separate GitHub Apps (hanthor-hive-agent, tuna-reef-hive). Document where the IDs and keys live on Spindle, the cross-registered bot logins, the running fork build, and the three Bitwarden secure notes that hold the App keys and /srv/hives/.env. --- docs/src/bitwarden.md | 10 +++++ docs/src/cluster/hive.md | 62 +++++++++++++++++++++++--- docs/src/servers/spindle-vps/README.md | 3 +- 3 files changed, 68 insertions(+), 7 deletions(-) diff --git a/docs/src/bitwarden.md b/docs/src/bitwarden.md index 5fa9b1dc..aae5c1fa 100644 --- a/docs/src/bitwarden.md +++ b/docs/src/bitwarden.md @@ -52,6 +52,16 @@ Every item a role or script reads (grep `bw get` / `bw list` under `roles/` and | `bw-api-key` | Login | `scripts/bw-resolve.sh` — `bw login --apikey` on a remote | | `James Bitwarden` | Login | `scripts/bw-resolve.sh` — non-interactive unlock on a remote | +### Recovery items (not read by any role) + +These items are kept so a lost host can be rebuilt by hand. No role reads them. + +| Bitwarden Item | Type | Holds | +|---------------|------|-------| +| `hive-github-app-hanthor-hive-agent` | Secure Note | School's GitHub App: App ID, installation ID, PEM private key (the hub mounts the same key). See [Hive](cluster/hive.md#github-apps) | +| `hive-github-app-tuna-reef-hive` | Secure Note | Reef's GitHub App: App ID, installation ID, PEM private key | +| `hive-spindle-env` | Secure Note | `/srv/hives/.env` on Spindle (hub secret, dashboard token, omp broker token, provider keys) | + ## Running Without Secrets For fast iteration that doesn't need the vault — packages, dotfiles, desktop config — use the explicit no-secrets path: diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index a63b4268..4a376a53 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -13,12 +13,62 @@ Caddy configuration routes [school.tunaos.org](https://school.tunaos.org) and state alone does not establish that the public endpoints or agents are healthy. The configured images are `ghcr.io/hivecommons/hive:v6-latest` for the two -spokes and `ghcr.io/hivecommons/hive-hub:v6-latest` for the hub. The Compose -services bind-mount `/srv/hives/bin/hive` over `/usr/local/bin/hive`, so the -image tag alone does not describe the running binary. The observed school and -reef seed configurations use the `omp` backend with -`github-copilot/gpt-6-luna`, not the historical pi/DeepSeek backend below. -Runtime state and model selection may differ from the seed files. +spokes and `ghcr.io/hivecommons/hive-hub:v6-latest` for the hub, but the image +tag does not describe the running binary. `compose.override.yaml` bind-mounts a +`tuna-os/hive` fork build over `/usr/local/bin/hive` on all three services and +mounts a patched `proxy/server.js` on both spokes. The header comment in that +file records which commit each `bin/hive-` contains. The fork's +`tuna/v6` branch is upstream `v6` plus the patches the fleet pilots; the +tracker is [tuna-os/tunaOS#4072](https://github.com/tuna-os/tunaOS/issues/4072). +Since 2026-10-30 the agents use the `omp` backend with +`openai-codex/gpt-6-luna` through the `omp-auth-broker` user service, and the +ioscan classifier runs through omp on `anthropic/claude-haiku-4-5`. + +### Layout under `/srv/hives` + +| Path | Contents | +|---|---| +| `compose.yaml`, `compose.override.yaml` | Services; the override pins the fork binary and the proxy patch | +| `.env` (mode 600) | `HIVE_HUB_SECRET`, `HIVE_DASHBOARD_TOKEN`, `OMP_AUTH_BROKER_TOKEN`, `NTFY_TOPIC` and provider API keys. Copy in Bitwarden: `hive-spindle-env` | +| `/config/hive.yaml` | Seed config, mounted read-only at `/etc/hive` | +| `/data/` | `/data`. `hive.yaml.runtime` is the running config and **wins over the seed** for `github.*` and most other keys, so change both | +| `/secrets/gh-app-key.pem` | GitHub App private key, mounted at `/secrets` | +| `bin/` | Fork builds, `hive-`; earlier builds stay for rollback | +| `backups/` | Timestamped copies taken before each change: `.` | + +### GitHub Apps + +Since 2026-10-30 School and Reef use separate GitHub Apps, so each has its own +installation rate limit (6,150 requests/hour across the 43 org repos). Before +that they shared one installation and exhausted it every hour. + +| Hive | App (bot login) | App ID | Installation | Key in Bitwarden | +|---|---|---|---|---| +| school (the hub mounts the same key) | `hanthor-hive-agent` (`hanthor-hive-agent[bot]`) | 3942065 | 137498420 | `hive-github-app-hanthor-hive-agent` | +| reef | `tuna-reef-hive` (`tuna-reef-hive[bot]`) | 5546574 | 177007234 | `hive-github-app-tuna-reef-hive` | + +The IDs appear in three places per hive: `GH_APP_ID`/`GH_APP_INSTALLATION_ID` +in `compose.yaml`, and `github.app_id`/`installation_id` in both the seed and +`hive.yaml.runtime`. + +Both hives manage `.github`, `Tavern`, `bluefin-cli`, `corral`, `docs` and +`flatpak-index`. Each therefore lists the other's bot in +`github.additional_bot_logins`, so the other hive's issues and PRs count as +hive-authored. + +To restore a key, write the Bitwarden note's key block to +`/secrets/gh-app-key.pem` (`ubuntu:ubuntu`, mode 600), then recreate the +service with `docker compose up -d `. + +To check that each hive is on its own budget, run: + +```bash +ssh ubuntu@100.113.75.88 'for c in hives-school-1 hives-reef-1; do docker exec $c sh -c \ + "curl -s -H \"Authorization: Bearer \$(cat /var/run/hive-metrics/gh-app-token.cache)\" https://api.github.com/rate_limit" \ + | jq -c .resources.core; done' +``` + +Different `reset` times mean separate installations. The old AWS cluster also had a `hive.reilly.asia` spoke; no hanthor container was present in the inspected Spindle Docker inventory. Its current status was diff --git a/docs/src/servers/spindle-vps/README.md b/docs/src/servers/spindle-vps/README.md index bed01118..928c4db2 100644 --- a/docs/src/servers/spindle-vps/README.md +++ b/docs/src/servers/spindle-vps/README.md @@ -8,7 +8,8 @@ as Docker Compose services under `/srv/spindle`. The School and Reef Hives, Hub and branded hub frontend run separately under `/srv/hives`, sharing the `spindle_default` network and Caddy ingress. The `omp-auth-broker` user service also runs on this host. The Hive deployment's runtime configuration and data are not restored by `deploy.sh`; -preserve and back them up separately. +preserve and back them up separately. Its layout, GitHub Apps and Bitwarden recovery items are in +[Hive](../../cluster/hive.md#current-deployment-spindle-vps). | Piece | Source | |---|---| From f4a1dc4ee70df8c66344da53079cba516331a129 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Sat, 31 Oct 2026 18:29:39 +0000 Subject: [PATCH 2/6] docs: record Reef and School ambient Matrix pilot Signed-off-by: James Reilly --- docs/src/cluster/hive.md | 49 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index 4a376a53..2c84d3ca 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -23,17 +23,23 @@ tracker is [tuna-os/tunaOS#4072](https://github.com/tuna-os/tunaOS/issues/4072). Since 2026-10-30 the agents use the `omp` backend with `openai-codex/gpt-6-luna` through the `omp-auth-broker` user service, and the ioscan classifier runs through omp on `anthropic/claude-haiku-4-5`. +Reef and School's 2026-10-31 Matrix pilot is pinned to +`deploy/upstream-v6-matrix` at `71ce0ef56889f8f023dc77236b03c1d08611c0a8`, +rather than a moving image tag; Hub stays on `230f745`. +See [the fleet ledger](https://github.com/tuna-os/hive/blob/docs/spindle-matrix-rollout/FORK.md#what-the-fleet-runs) +for the per-service rollout state and +[integration PR #172](https://github.com/tuna-os/hive/pull/172) for CI and provenance. ### Layout under `/srv/hives` | Path | Contents | |---|---| -| `compose.yaml`, `compose.override.yaml` | Services; the override pins the fork binary and the proxy patch | +| `compose.yaml`, `compose.override.yaml` | Services; the override pins the fork binary, proxy patch and matching Matrix dashboard HTML | | `.env` (mode 600) | `HIVE_HUB_SECRET`, `HIVE_DASHBOARD_TOKEN`, `OMP_AUTH_BROKER_TOKEN`, `NTFY_TOPIC` and provider API keys. Copy in Bitwarden: `hive-spindle-env` | | `/config/hive.yaml` | Seed config, mounted read-only at `/etc/hive` | | `/data/` | `/data`. `hive.yaml.runtime` is the running config and **wins over the seed** for `github.*` and most other keys, so change both | | `/secrets/gh-app-key.pem` | GitHub App private key, mounted at `/secrets` | -| `bin/` | Fork builds, `hive-`; earlier builds stay for rollback | +| `bin/` | Fork builds, `hive-`, and matching `dashboard-.html`; earlier builds stay for rollback | | `backups/` | Timestamped copies taken before each change: `.` | ### GitHub Apps @@ -81,6 +87,45 @@ For a read-only inventory, run: ssh ubuntu@100.113.75.88 'docker ps --filter name=hives-' ``` +### Ambient code-rain pilot + +The pilot ports upstream's Matrix observer, privacy fixes, JSON/SSE API and +four effects (Rain, Cascade, Ghost coder, Terminal) onto v6 while retaining +the fork's SDLC policies. It is a dashboard feature, not a Twitch deployment. + +After signing in to the corresponding dashboard, open: + +- [Reef kiosk](https://reef.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=rain) +- [School kiosk](https://school.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=rain) + +Use `mx.effect=cascade`, `ghost` or `terminal` to change the effect, and +`mx.fps=15` to lower rendering load. Space/P pauses; sound is explicitly off. +Each spoke shows its own admitted PR patches; this is not a hub-wide +aggregated code feed or a keystroke stream. + +`dashboard.matrix` must be enabled in **both** seed and runtime configs. +`repos` is an explicit allowlist of already-watched, verified-public repos. +The pilot excludes `deploy/**`, `config/**`, `.github/**`, YAML, JSON and TOML +in addition to upstream's built-in secret filtering. Do not add private +repos: the feed has no per-repository viewer permissions. + +An anonymous `/api/matrix/lines?since=0` must return 401/403. +An authenticated response reports `source: "pushed-lines"` and sequence +numbers. Animation can replay buffered patches and is not proof of a new +push. The source is initialized by the sentinel sweep after reconciliation; +a cold start can return 404 even with the flag enabled until that sweep runs. +Do not disable budget, admission or writeback guards to accelerate the feed. + +Before an upgrade, stop the affected service, snapshot its retained data, +copy both configs and the Compose override into `backups/`, then start it +with a commit-matched binary and HTML. The 2026-10-31 Reef canary backup stamp +is `20261031T180544Z`; School's is `20261031T182146Z`. +Both previous binaries are `bin/hive-230f745`. +For rollback, stop the service, restore its matching binary/UI pins and both +config files, validate Compose, and restart. Restore the data snapshot only +when required for downgrade compatibility; do not overwrite newer agent work +as a routine rollback step. + ## Archived cluster guide > **Historical reference only — do not apply or run the Kubernetes, image-build, From 7c698b3238af0d4f00c7b804e14af13b005d43b0 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Sat, 31 Oct 2026 21:57:46 +0000 Subject: [PATCH 3/6] docs: explain Matrix repository-name admission failure Signed-off-by: James Reilly --- docs/src/cluster/hive.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index 2c84d3ca..493e819d 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -23,9 +23,9 @@ tracker is [tuna-os/tunaOS#4072](https://github.com/tuna-os/tunaOS/issues/4072). Since 2026-10-30 the agents use the `omp` backend with `openai-codex/gpt-6-luna` through the `omp-auth-broker` user service, and the ioscan classifier runs through omp on `anthropic/claude-haiku-4-5`. -Reef and School's 2026-10-31 Matrix pilot is pinned to -`deploy/upstream-v6-matrix` at `71ce0ef56889f8f023dc77236b03c1d08611c0a8`, -rather than a moving image tag; Hub stays on `230f745`. +Reef and School's Matrix pilot uses commit-pinned builds from +`deploy/upstream-v6-matrix`, rather than a moving image tag; Hub stays on +`230f745`. Canary and fleet pins can differ during a rollout. See [the fleet ledger](https://github.com/tuna-os/hive/blob/docs/spindle-matrix-rollout/FORK.md#what-the-fleet-runs) for the per-service rollout state and [integration PR #172](https://github.com/tuna-os/hive/pull/172) for CI and provenance. @@ -100,8 +100,9 @@ After signing in to the corresponding dashboard, open: Use `mx.effect=cascade`, `ghost` or `terminal` to change the effect, and `mx.fps=15` to lower rendering load. Space/P pauses; sound is explicitly off. -Each spoke shows its own admitted PR patches; this is not a hub-wide -aggregated code feed or a keystroke stream. +Each spoke shows admitted patches from its watched repositories, not all +hub repositories. Known peer bots can appear where watches overlap. +This is not a hub-wide aggregated code feed or a keystroke stream. `dashboard.matrix` must be enabled in **both** seed and runtime configs. `repos` is an explicit allowlist of already-watched, verified-public repos. @@ -116,6 +117,12 @@ push. The source is initialized by the sentinel sweep after reconciliation; a cold start can return 404 even with the flag enabled until that sweep runs. Do not disable budget, admission or writeback guards to accelerate the feed. +Before `637bae44f`, short `project.repos` names (with `project.org` set) were +passed unchanged to Matrix's qualified `owner/name` allowlist, silently dropping +every patch. The fix qualifies observation names; it does not relax admission. +An active API with `seq: 0` therefore did not prove that these hives were idle. +See the fleet ledger for deployment and live verification of that fix. + Before an upgrade, stop the affected service, snapshot its retained data, copy both configs and the Compose override into `backups/`, then start it with a commit-matched binary and HTML. The 2026-10-31 Reef canary backup stamp From 3849e5f111cd907b52b8c03fc40fce80c59e20e1 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Sat, 31 Oct 2026 22:42:30 +0000 Subject: [PATCH 4/6] docs: clarify Matrix rolling history and fix rollback pins Signed-off-by: James Reilly --- docs/src/cluster/hive.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index 493e819d..a54344a8 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -112,8 +112,10 @@ repos: the feed has no per-repository viewer permissions. An anonymous `/api/matrix/lines?since=0` must return 401/403. An authenticated response reports `source: "pushed-lines"` and sequence -numbers. Animation can replay buffered patches and is not proof of a new -push. The source is initialized by the sentinel sweep after reconciliation; +numbers. The server holds up to 2,000 accepted lines in memory; the browser +retains 120 received lines. Animation can reuse that rolling buffer between +pushes, so motion is not proof of new activity. +The source is initialized by the sentinel sweep after reconciliation; a cold start can return 404 even with the flag enabled until that sweep runs. Do not disable budget, admission or writeback guards to accelerate the feed. @@ -125,9 +127,11 @@ See the fleet ledger for deployment and live verification of that fix. Before an upgrade, stop the affected service, snapshot its retained data, copy both configs and the Compose override into `backups/`, then start it -with a commit-matched binary and HTML. The 2026-10-31 Reef canary backup stamp -is `20261031T180544Z`; School's is `20261031T182146Z`. -Both previous binaries are `bin/hive-230f745`. +with a commit-matched binary and HTML. The initial Matrix rollout backups are +Reef `20261031T180544Z`, School `20261031T182146Z` (previous binary `230f745`). +The repository-name fix backups are Reef `20261031T215350Z`, School +`20261031T223247Z` (previous binary `71ce0ef56`). The fix reuses the unchanged +`dashboard-71ce0ef56.html` mount; do not infer UI drift from that filename alone. For rollback, stop the service, restore its matching binary/UI pins and both config files, validate Compose, and restart. Restore the data snapshot only when required for downgrade compatibility; do not overwrite newer agent work From ec5105cb32dbf19a36c42c7253802308590c7262 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Sat, 31 Oct 2026 23:35:54 +0000 Subject: [PATCH 5/6] docs: record verified two-spoke Matrix playback Signed-off-by: James Reilly --- docs/src/cluster/hive.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index a54344a8..4db0743f 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -125,6 +125,15 @@ every patch. The fix qualifies observation names; it does not relax admission. An active API with `seq: 0` therefore did not prove that these hives were idle. See the fleet ledger for deployment and live verification of that fix. +The fixed build `637bae44f` was deployed to both spokes and visually verified +on 2026-10-31: Rain/Ghost on Reef, Cascade/Terminal on School, and P-key +pause/resume. Both APIs returned 1,200 buffered lines; a sample from each +matched a public PR addition at its reported commit after whitespace trimming. +Anonymous requests remained 401; authenticated responses remained `no-store`. +The Apps currently use polling rather than PR webhooks, so freshness can lag. +Cold-start quota exhaustion can delay the first capture substantially even +when Matrix is enabled; a larger display window does not fix that. + Before an upgrade, stop the affected service, snapshot its retained data, copy both configs and the Compose override into `backups/`, then start it with a commit-matched binary and HTML. The initial Matrix rollout backups are From 1bfa3fda602fb03145496586a424399bf2898457 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Sun, 1 Nov 2026 02:48:02 +0000 Subject: [PATCH 6/6] docs: document the live code activity reader and recovery Signed-off-by: James Reilly --- docs/src/cluster/hive.md | 162 +++++++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 64 deletions(-) diff --git a/docs/src/cluster/hive.md b/docs/src/cluster/hive.md index 4db0743f..2f52bb7e 100644 --- a/docs/src/cluster/hive.md +++ b/docs/src/cluster/hive.md @@ -23,12 +23,13 @@ tracker is [tuna-os/tunaOS#4072](https://github.com/tuna-os/tunaOS/issues/4072). Since 2026-10-30 the agents use the `omp` backend with `openai-codex/gpt-6-luna` through the `omp-auth-broker` user service, and the ioscan classifier runs through omp on `anthropic/claude-haiku-4-5`. -Reef and School's Matrix pilot uses commit-pinned builds from -`deploy/upstream-v6-matrix`, rather than a moving image tag; Hub stays on -`230f745`. Canary and fleet pins can differ during a rollout. +Reef and School's Code activity pilot runs `e0c044e15` from +`feature/matrix-cascade-diffs`, based on `deploy/upstream-v6-matrix`, with +commit-matched binary and dashboard HTML mounts. Hub stays on `230f745`. See [the fleet ledger](https://github.com/tuna-os/hive/blob/docs/spindle-matrix-rollout/FORK.md#what-the-fleet-runs) -for the per-service rollout state and -[integration PR #172](https://github.com/tuna-os/hive/pull/172) for CI and provenance. +for per-service pins, checksums and recovery evidence; +[reader PR #174](https://github.com/tuna-os/hive/pull/174) builds on +[the original Matrix integration #172](https://github.com/tuna-os/hive/pull/172). ### Layout under `/srv/hives` @@ -40,7 +41,7 @@ for the per-service rollout state and | `/data/` | `/data`. `hive.yaml.runtime` is the running config and **wins over the seed** for `github.*` and most other keys, so change both | | `/secrets/gh-app-key.pem` | GitHub App private key, mounted at `/secrets` | | `bin/` | Fork builds, `hive-`, and matching `dashboard-.html`; earlier builds stay for rollback | -| `backups/` | Timestamped copies taken before each change: `.` | +| `backups/` | Timestamped config copies and stopped-service data/temporary-workspace archives; protect as secrets | ### GitHub Apps @@ -87,64 +88,97 @@ For a read-only inventory, run: ssh ubuntu@100.113.75.88 'docker ps --filter name=hives-' ``` -### Ambient code-rain pilot - -The pilot ports upstream's Matrix observer, privacy fixes, JSON/SSE API and -four effects (Rain, Cascade, Ghost coder, Terminal) onto v6 while retaining -the fork's SDLC policies. It is a dashboard feature, not a Twitch deployment. - -After signing in to the corresponding dashboard, open: - -- [Reef kiosk](https://reef.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=rain) -- [School kiosk](https://school.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=rain) - -Use `mx.effect=cascade`, `ghost` or `terminal` to change the effect, and -`mx.fps=15` to lower rendering load. Space/P pauses; sound is explicitly off. -Each spoke shows admitted patches from its watched repositories, not all -hub repositories. Known peer bots can appear where watches overlap. -This is not a hub-wide aggregated code feed or a keystroke stream. - -`dashboard.matrix` must be enabled in **both** seed and runtime configs. -`repos` is an explicit allowlist of already-watched, verified-public repos. -The pilot excludes `deploy/**`, `config/**`, `.github/**`, YAML, JSON and TOML -in addition to upstream's built-in secret filtering. Do not add private -repos: the feed has no per-repository viewer permissions. - -An anonymous `/api/matrix/lines?since=0` must return 401/403. -An authenticated response reports `source: "pushed-lines"` and sequence -numbers. The server holds up to 2,000 accepted lines in memory; the browser -retains 120 received lines. Animation can reuse that rolling buffer between -pushes, so motion is not proof of new activity. -The source is initialized by the sentinel sweep after reconciliation; -a cold start can return 404 even with the flag enabled until that sweep runs. -Do not disable budget, admission or writeback guards to accelerate the feed. - -Before `637bae44f`, short `project.repos` names (with `project.org` set) were -passed unchanged to Matrix's qualified `owner/name` allowlist, silently dropping -every patch. The fix qualifies observation names; it does not relax admission. -An active API with `seq: 0` therefore did not prove that these hives were idle. -See the fleet ledger for deployment and live verification of that fix. - -The fixed build `637bae44f` was deployed to both spokes and visually verified -on 2026-10-31: Rain/Ghost on Reef, Cascade/Terminal on School, and P-key -pause/resume. Both APIs returned 1,200 buffered lines; a sample from each -matched a public PR addition at its reported commit after whitespace trimming. -Anonymous requests remained 401; authenticated responses remained `no-store`. -The Apps currently use polling rather than PR webhooks, so freshness can lag. -Cold-start quota exhaustion can delay the first capture substantially even -when Matrix is enabled; a larger display window does not fix that. - -Before an upgrade, stop the affected service, snapshot its retained data, -copy both configs and the Compose override into `backups/`, then start it -with a commit-matched binary and HTML. The initial Matrix rollout backups are -Reef `20261031T180544Z`, School `20261031T182146Z` (previous binary `230f745`). -The repository-name fix backups are Reef `20261031T215350Z`, School -`20261031T223247Z` (previous binary `71ce0ef56`). The fix reuses the unchanged -`dashboard-71ce0ef56.html` mount; do not infer UI drift from that filename alone. -For rollback, stop the service, restore its matching binary/UI pins and both -config files, validate Compose, and restart. Restore the data snapshot only -when required for downgrade compatibility; do not overwrite newer agent work -as a routine rollback step. +### Code activity pilot + +The pilot is now a passive, readable code activity view, not simulated typing. +After signing in to the corresponding dashboard, click **Code activity** in +the Activity Monitor, or open: + +- [Reef code activity](https://reef.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=cascade) +- [School code activity](https://school.tunaos.org/?kiosk=1&view=matrix&sound=off&mx.effect=cascade) + +Cascade shows complete green `+` additions and red `−` removals with indentation, +blank lines and repeated lines intact. Paragraphs wrap. Each block identifies its +repository, file and observation time: + +- **In progress · workspace vs HEAD** identifies the managed agent workspace. + This is a snapshot, not a keystroke stream or proof of model authorship. +- **Pushed PR** identifies a published checkpoint and links its actual PR. + Existing sentinel author checks, change detection, polling and quotas apply; + pushed checkpoints can lag or remain quiet until an eligible new head appears. + +Space/P or **Pause** stops motion; scroll to inspect. Reduced motion is static +and scrollable. The reader holds when caught up. **Replay buffered changes** is +explicit, labeled and off by default; motion is not proof of new activity. +Rain, Ghost coder and Terminal remain optional decorative effects through +`mx.effect=rain`, `ghost` or `terminal`; `mx.fps=15` reduces their render load. +Sound is off in the links above. This is not a hub-wide feed or a Twitch deployment. + +#### Capture scope and privacy + +`dashboard.matrix.enabled` and the separately consented +`dashboard.matrix.workspaces: true` are enabled in **both** spoke seed and runtime +configs. `repos` remains an explicit allowlist of already-watched, verified-public +repositories. Private repositories are ineligible: the feed has no per-repository +viewer permissions. Unpublished code can still contain sensitive information; +secret filtering is a safeguard, not a guarantee that public broadcasting is safe. + +Workspace discovery includes configured agents under `$HIVE_WORK_DIR` +(`/data/agents` by default) and temporary subtrees owned by registered isolated +agent UIDs. Shared, root, service and ambiguous UIDs cannot authorize temporary +capture. Discovery does not follow symlinked directories; ownership and origin +are rechecked, and existing filesystem permissions remain in force. It does not +collect terminal output or inspect arbitrary host paths. + +Discovery runs every 30 seconds; two workspaces are sampled per two-second batch, +round-robin, with a shared 64-workspace limit. GitHub public visibility must be +verified before publishing a changed snapshot. The pilot still excludes +`deploy/**`, `config/**`, `.github/**`, YAML, JSON and TOML, in addition to built-in +secret filters. Unsafe or oversized changed regions are omitted whole, including +on the removal side. + +An anonymous or forged-role `/api/matrix/lines?since=0` returns 401/403. +An authorized response uses `Cache-Control: no-store`, `source: "code-activity"`, +`workspaces`, continuation `seq`, `latest` and policy `epoch`. The server retains +up to 2,000 accepted lines / 512 KiB of text; reader history is bounded to 1,200 +lines / 256 KiB, and the viewport to 32 whole cards. An enabled cold source now +initializes on an authorized read and can return a valid empty feed immediately. +Do not disable budget, admission or writeback guards to accelerate it. + +#### Verified deployment and recovery + +Both spokes run `e0c044e15` with its matching Node-served HTML. Exact-source full +CI passed 27 jobs (three skipped; no coverage verdict), and both architecture +artifacts passed their version smoke. See the fleet ledger for hashes and CI links. +Hub was not restarted. + +On 2026-11-01, clearly marked controlled changes in genuine public Tavern clones +proved managed-directory capture on Reef and isolated-UID temporary capture on +School. Both feeds advanced from 12 to 24 changed lines after a new filesystem +edit; native browsers showed full green/red paragraphs, blanks, repeated lines, +newly-received provenance and pause-to-inspect. The fake-credential region was +rejected. Native 390px reduced-motion wrapping and the actual toolbar link worked. +Anonymous/forged-role requests remained 401; authorized responses remained `no-store`. +The actual public Tavern #323 diff also exercised published-checkpoint rendering. +No synthetic pushed checkpoint was injected or claimed as native post-rollout activity. + +Controlled fixtures were removed and their transient entries reset. Both clean +feeds returned 200 with `latest: 0` and no verification cards. A quiet view is +intentional, not generated filler. School's two pre-existing temporary Git +subtrees survived recreation with ownership and permissions unchanged. + +Before upgrading, stop only the affected service and snapshot its retained data, +both configs, the Compose override and temporary Git checkouts. Code activity +snapshots are `backups/reef-code-activity-20261101T022412Z/` and +`backups/school-code-activity-20261101T023300Z/`. Restore temporary Git archives +into a newly created, stopped container **before** starting it; an ordinary +container restart retains `/tmp`. Keep backups mode-restricted: they contain secrets. + +The previous spoke pair is `hive-637bae44f` plus `dashboard-71ce0ef56.html`. +For rollback, restore only that spoke's matching binary/UI pins and both configs, +validate Compose, and restart with `--no-deps`. Do not overwrite another service's +pins with a whole old override. Restore a data snapshot only when downgrade +compatibility requires it; never overwrite newer agent work routinely. ## Archived cluster guide