2026.08.21.01 deployed — 6/6 hosts

Every platform on eee73e77, schema pushed, processes online, domains answering. Rolled out by hand
one host at a time, since nothing wakes the commander yet.

Three things the report records rather than glosses. officer-claude-code was NOT restarted on
officer-dev — that sidecar holds the session running the deploy, so restarting it would have ended the
rollout mid-flight; every other host got it and it is outstanding here. fofos failed to sync
capabilities with a "dubious ownership" refusal whose stated cause is wrong (ownership is correct), so
it is left unexplained rather than silenced with a safe.directory entry. And macbookpro has no plugins
installed at all, which is worth knowing before somebody expects one there.

Two lessons for the prompt. The dirty-tree check counted untracked files and skipped fofos over one
stray script a fast-forward could never touch — it wants --untracked-files=no. And macbookpro needs
$SHELL -ic and no help: exporting a PATH to reach bun broke pm2, which lives only on the interactive
shell's path.

The pre-flight earned its place: username became NOT NULL with a case-insensitive unique index, and
checking all six first — 12 users, zero nulls, zero collisions — is why db:push applied everywhere
instead of failing on the third host.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitignore

@@ -105,6 +105,13 @@ src/databases/officer_db/migrations/
 # to the platform; the plugins do not.
 /plugins/*/
 
+# Generated by src/servers/plugins/npm-deps.ts from every plugin's `npmDependencies`, and installed into
+# plugins/node_modules/. It describes whichever plugins are on THIS machine, so committing one would
+# claim a dependency set nobody chose. The rule above only ignores directories, so these need naming.
+/plugins/package.json
+/plugins/bun.lock
+/plugins/bun.lockb
+
 # Visual baselines for the theme extraction — large, machine-specific, regenerate with scripts/theme-snapshot.ts
 .snapshots/
 

BLOCKERS.md

@@ -0,0 +1,190 @@
+# Atelier extraction — blockers and decisions made without asking
+
+Unattended run, started 2026-08-20. Per the kickoff prompt: decisions made here without being able to
+ask, in the order found. Nobody is awake; each entry says what I did and why, then the run continues.
+
+## Map, before anything moved
+
+Grepped the whole platform for `atelier` (case-insensitive, every `.ts`/`.tsx`/`.md`/`.json`/`.cjs`
+file). Two hits, both incidental:
+
+- `src/workspaces/officerdev/src/apps/Chat/components/chat-images.test.ts:10` — a test fixture using
+  `https://atelier.officer.dev/images/....png` as an example markdown image URL. Not a dependency.
+- `src/servers/api/chat/task-restart.ts:181` — a comment mentioning a stray `bun dev` process that once
+  ran from `~/dockers/officer-atelier` and got respawned by accident. Historical, not a dependency.
+
+**No platform code imports anything from Atelier, and Atelier imports nothing from the platform.**
+Unlike music/offscale, there is no reverse dependency to find and no "this stays behind" piece. It comes
+out whole, the way offscale did before the imports were found — except here there really are none.
+
+Also checked: `ecosystem.config.cjs` (platform's own) has no `atelier` entry — the standalone service is
+managed by its OWN `ecosystem.config.cjs` inside `~/officer-dev/dockers/officer-atelier/`, entirely
+outside this repository.
+
+## The standalone service stays running, untouched
+
+`officer-atelier` (PM2, port 3002) is a **live production service** — its own `ecosystem.config.cjs` says
+plainly "this is the instance the mobile app talks to, so it holds still." It serves
+`https://atelier.officer.dev` via nginx and holds real data (87 generations, 2 collections, 5 providers,
+1 provider_settings row, checked directly against Postgres).
+
+I am not stopping it, not touching its nginx config, not touching its PM2 entry, and not touching the
+mobile app. This extraction adds a new, additive plugin inside the platform; cutting the mobile app over
+to it (or deciding whether to) is the owner's call, not mine to make unattended. Recorded here so nobody
+reads the plugin's existence as "the old service is now redundant, kill it" — it is not redundant until
+someone repoints the mobile app.
+
+## Decision 3 — database rows checked, both non-empty → database stays separate
+
+Queried the live `atelier` Postgres database directly (via a throwaway `postgres` client, same
+credentials as `.env.production.local`):
+
+```
+collections         2
+collection_items    73
+provider_settings    1
+providers            5
+generations          87
+```
+
+`collections` (2) and `provider_settings` (1) are the two tables the brief named — both non-empty. Per
+decision 3: **the `atelier` database stays separate**, not folded into `officer_db`. No
+`plugins/atelier/db/schema.ts` (that convention is for `officer_db`-prefixed tables); the sidecar keeps
+its own Postgres connection to the `atelier` database, exactly as today, just running from inside the
+plugin's `sidecar/` directory instead of a standalone repo.
+
+**The brief undersold the schema.** It says "tables: collections, provider_settings" — the real schema
+has five: `generations` (the actual data — 87 rows, prompts/images/costs), `collection_items` (the join
+table), `providers` (configured adapter+model+key rows — 5 of them; a newer, richer replacement for
+`provider_settings` that the brief doesn't mention at all), plus the two named. `generations` alone
+being non-empty would have settled decision 3 on its own. Following the letter of decision 3 (check the
+two named tables) rather than re-deriving it from the fuller schema, since both answers point the same
+way here.
+
+**Migration to `officer_db` is a real follow-up**, not done here: fold `collections`, `collection_items`,
+`providers`, `provider_settings`, `generations` into `officer_db` as `atelier_*`-prefixed tables once
+someone is awake to watch a real data migration. Until then the plugin's sidecar owns a second Postgres
+connection, to a second database, which is new territory for this plugin system (every other plugin's
+`db/` is officer_db-prefixed tables) — documented in PLUGIN.md.
+
+## Postgres connection for the separate database
+
+The sidecar needs its own connection string. Added `ATELIER_POSTGRES_URL` as a new platform `.env`
+variable (same pattern as `OFFICERDEV_POSTGRES_URL` for officer's own database) rather than routing it
+through the secret store — a database URL carrying a password is handled as a plain `.env` value
+everywhere else in this codebase (`OFFICERDEV_POSTGRES_URL` itself), and the secret store's own docs
+scope it to "every encryption and signing key the platform uses" plus foreign bearer credentials
+(APNs, FCM, webhooks) — not connection strings. Kept consistent with the existing convention rather than
+inventing a new one.
+
+**Not set automatically.** I don't have a safe way to guess whether the owner wants the plugin sidecar
+to point at the _existing_ `atelier` database (sharing state with the still-running standalone service —
+two writers to one queue table, which `generations.status` and the `claimableGenerations`/`markRunning`
+claim logic were written assuming is single-process) or a fresh one. Left unset, with a clear startup
+error, and documented in PLUGIN.md. **Do not just paste the standalone service's `POSTGRES_URL` in and
+restart both** — two processes racing the same `generations` queue is exactly the hazard `markRunning`'s
+atomic claim exists to prevent for restarts of _one_ process, not for two live ones.
+
+## Decision 2 — Providers as an Officer settings screen, against a direct precedent
+
+Found `IntegrationsSettings/index.tsx`'s own comment, written when email was extracted on 2026-08-18:
+
+> "Email account management left with the feature (`plugins/email/`). A plugin contributes panels, not
+> settings sections, so it now lives inside the email workspace itself."
+
+That is the opposite of decision 2, written five days before this run, in the exact settings screen
+decision 2 points Atelier's Providers into. Per the brief's own instructions ("if you find evidence one
+is wrong, write it down, follow the decision anyway"): implemented Providers as a genuine platform
+settings section — `IntegrationsSettings` gained an "Atelier" entry under the Enterprise tab — as new
+**platform** code (`src/apps/officer-web/...`) that talks to `/api/atelier/providers` over HTTP via
+`useClient`, same as any other authenticated screen. It does not import anything from
+`plugins/atelier/`, so it does not violate "a plugin importing platform code is fine; the reverse is
+not" — there is no import in either direction, only an HTTP call, which is what every frontend/backend
+pair in this codebase already is.
+
+Recording the contradiction here rather than silently picking the email precedent, since decision 2 was
+explicit and pre-made.
+
+## Images served through an authenticated route, not the old `PUBLIC_URL` scheme
+
+The standalone service served `/images/*` unauthenticated, off Bun's top-level route table, with
+`PUBLIC_URL` baked into every response so the URL was durable outside the process. Per "What you may NOT
+do", that is gone: images are served from `GET /api/atelier/files/:filename`, mounted like every other
+route, behind the permission gate. Named `files` rather than `images` so it cannot sit one path segment
+away from `/api/atelier/images/generations/:id` — the JSON job API already owns `/images`.
+
+The frontend needs `<img src>` to carry a credential a browser cannot put in an `Authorization` header.
+Used the platform's existing `?token=` escape hatch — already read by both
+`permission-gate.ts:37` and `user-middleware.ts:22`, already used by `FileViewer/file-types.ts` for
+exactly this (`getRawUrl`, `getAudioTracksUrl`, ...) for the file browser's raw/audio/subtitle routes.
+Not a new mechanism, not an unauthenticated route: the same query-token path every other authenticated
+media URL in this app already takes.
+
+## `sharp` added as a direct dependency
+
+Atelier's `inspect.ts` uses `sharp` to measure width/height/alpha-channel/opacity of a written image —
+load-bearing (it is how a `background: transparent` request that silently produced an opaque image gets
+caught). `sharp@0.33.5` was already resolved in `bun.lock` as an optional transitive dependency of
+`next`, so promoting it to a direct dependency of the platform added no new resolution — verified the
+lockfile diff is exactly that promotion, nothing else moved. Done via the documented dance:
+`frozenLockfile` commented out in `bunfig.toml` for one `bun install`, restored immediately after,
+diff reviewed before committing both files.
+
+## Publishing to the Marketplace — not done, left as the one open step
+
+`plugins/atelier/` is its own local git repository (`git init`, per "Done means"), but I did not create
+`gitea.officer.dev/plugins/atelier` or push to it. I found no Gitea API token or credential available to
+this session, and creating a new repository on a shared Gitea instance and registering it in the
+marketplace catalogue (`scripts/marketplace-sync.ts`, `BUNDLED` in `src/servers/plugins/marketplace.ts`)
+is exactly the kind of action with effects beyond this local checkout that the run's own ground rules
+say to flag rather than take unilaterally, especially with no verified way to confirm it succeeded.
+
+Left for the owner:
+
+```
+cd plugins/atelier
+git remote add origin git@gitea.officer.dev:plugins/atelier.git   # after creating the repo on Gitea
+git push -u origin main
+cd ../..
+bun --env-file=.env scripts/marketplace-sync.ts
+```
+
+Then add a `BUNDLED` entry in `src/servers/plugins/marketplace.ts` (offline fallback), matching the
+other three plugins' entries.
+
+Until that happens, the plugin still installs fine from a checkout that already has the directory
+(`plugins/atelier/` committed to its own local repo, present on disk) — it just cannot be discovered by
+the Marketplace screen on a machine that has never had it, per "Done means" #2. This is the one piece of
+"done" I could not complete unattended.
+
+## No `plugins/atelier/db/`, on purpose
+
+"Done means" lists `db/` among the plugin's expected pieces, matching offscale's and music's shape. This
+plugin has no `db/schema.ts` at all — `discoverPlugins()` correctly reports `schema: null` for it. That
+convention is specifically for `officer_db`-prefixed tables pushed by `pushPluginSchema`; decision 3
+keeps Atelier's tables in their own separate Postgres database instead, so there is nothing for that
+convention to describe. The database code lives inside `sidecar/db/` as an internal implementation
+detail of the sidecar process, not as a platform-recognised `db/` directory. Documented in full in
+`plugins/atelier/PLUGIN.md`, under "The database".
+
+## What I verified, and what I deliberately did not
+
+- `bunx tsgo`: clean throughout.
+- `bun test`: baseline 1041 pass / 0 fail / 90 files → after this run, 1069 pass / 0 fail / 92 files.
+  The two new files are the ported `serialize.test.ts` and `generations/response.test.ts`. No
+  regressions, file count only grew.
+- `discoverPlugins()` finds the plugin and the manifest validates with no problems.
+- The platform-side proxy router mounts and correctly 503s with no sidecar running.
+- The sidecar's own Hono app was exercised directly against the real `atelier_dev` Postgres database
+  (not `officer_db`, not the production `atelier` database) with real HTTP requests and no port bound:
+  providers, providers/adapters, collections and images all answered correctly; a missing file 404s; an
+  unknown route gets the OpenAI-shaped error envelope; provider rows whose keys were encrypted under the
+  standalone service's own key correctly fail to decrypt rather than crashing (a fresh `secret.key` was
+  generated for this checkout at `$OFFICER_ROOT/data/atelier/secret.key`, which is expected and correct
+  — see PLUGIN.md).
+- **Deliberately not done**: installing the plugin through the live, running `officer` PM2 process. That
+  process serves the owner's real session, its `plugins/` directory is the main checkout (not this
+  worktree, so it would not even find this code), and going through its install flow would write a real
+  `plugin_installs` row into the shared production `officer` Postgres database from a session with no way
+  to confirm the result against a live browser. Full PM2 install/enable/disable/uninstall/purge cycle,
+  per the runbook's verification table, is left for the owner — noted as open item 5 in PLUGIN.md.

CLAUDE.md

@@ -421,6 +421,9 @@ explaining why it was safe.
 
 - `docs/navigation-audit.md` — **authoritative** on routing/navigation: the opaque-click anti-pattern,
   a severity-ranked findings table, the channel-selection map and the four-phase plan
+- `docs/email-recall.md` — **design, not built**: recall over your own correspondence. The split that
+  matters is counting (needs every message judged) versus retrieval (needs the best few, fast) — and why
+  a number produced by searching is confidently wrong with no signal that it is
 - `docs/find-my-device.md` — **design, not built**: locating your own devices from Officer. What is
   assembly (most of it), what is impossible (offline finding — there is no crowd to relay it), and the
   question to settle first, which is retention rather than anything technical
@@ -435,6 +438,21 @@ explaining why it was safe.
   mounted and what it knows, the URL-vs-channel split for panel-to-panel communication, and the
   persistence key families. Read before building a panel app. Its defect list is
   `docs/workspace-panel-todo.md`.
+- `docs/multi-server-push.md` — **design, not built**: one Officer app receiving notifications from every
+  server it is signed into. Works already, bar one missing field — and why the `mv` catalogue-version
+  check turns into an endless resync between servers without it. The server identifier is an SSO decision
+- `docs/visual-regression-plan.md` — **plan, not built**: nightly screenshot regression against a JWT
+  dashboard on a second server. The blocker is that a JWT lives in `localStorage` and iris copies only
+  cookies, so an authenticated capture silently renders the login page — plus why diffing must happen
+  before any agent is asked to look
+- `docs/plugin-dependency-scope.md` — a plugin declares WHO must be able to run each host binary. Why the
+  owner's login shell is the wrong question for a `confined` plugin, the two-part reachability check
+  (world-executable AND every parent traversable), and why members' binaries on alpha worked only because
+  one home directory happened to be mode 751
+- `docs/plugin-route-authorization.md` — **design, not built**: making a plugin's settings routes
+  owner-only while the plugin itself stays grantable. What the proxy should pass (`isOwner` and a level,
+  never the role name), why declaring owner-only paths in the manifest beats trusting every plugin to
+  remember, and the credential-resolution work that has to land first
 - `docs/secret-store.md` — **design, not built**: moving the encryption and signing keys out of `.env`
   into a SQLite store, why they cannot live in Postgres, and key rotation. Also records the core/plugin
   split it assumes — light plus `officer-headscale` is the core; Vaultwarden and the wallet are plugins

TODO.md

@@ -1,713 +1,74 @@
-# TODO
+# TODO — the index
 
-Deferred work.
+Deferred work. **The items live in `todo/`, one file each**, grouped by theme; this file is the map
+over them and is GENERATED — run `bun run todo:index` after any change rather than editing it here.
+Format and the two-way-sync contract: `todo/README.md`.
 
-**Context, corrected 2026-08-07.** This file used to open by saying Officer was "collapsing from
+**Context, corrected 2026-08-07.** This list used to open by saying Officer was "collapsing from
 multi-tenant / open-source-ready to a **single-user platform**", and told you to treat multi-tenant
-indirection as accidental complexity. **That direction was reversed.** The permission permission model
+indirection as accidental complexity. **That direction was reversed.** The permission model shipped on
-shipped on 2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each
+2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each one their own
-one their own Gitea account through the platform. Per-user scoping is now a requirement, and the items
+Gitea account through the platform. Per-user scoping is now a requirement, and the items that proposed
-below that proposed deleting it have been removed rather than left to mislead the next reader.
+deleting it have been removed rather than left to mislead the next reader.
 
 What did NOT reverse: `execution` permissions (terminal, chat, tasks, files, desktop, browser) run as
 the owner's OS user and can never be granted. Indirection there really is accidental complexity.
 
-## Multi-user
+## Urgent
-
+
-- [ ] **`deprovisionOsAccount` is written but has never run against a real account.** Landed 2026-08-12 in
+- **due 2026-08-22** — **Settings to choose which server each feature uses** — [fleet/settings-to-choose-which-server-each-feature](todo/fleet/settings-to-choose-which-server-each-feature.md)
-      `os-user-deprovision.ts` and wired into `deleteUserHandler`, which now refuses to delete the row when
+
-      the Linux teardown fails — so a failure is retryable instead of forgotten. Only the pure guards
+## Themes
-      (`guardDeletable`, `guardMemberTree`, `parseSubUidEntry`) have tests; the reap loop, the `chown -R`
+
-      sever and `userdel` have been exercised by nobody. `docs/deprovision-os-account.md` → "What is still
+**78 open, 20 closed**, across 28 themes.
-      unproven" has the five-step validation, and it has to happen on the production host with a throwaway
+
-      account that has **a shell left open** and **a container writing as a non-root user** — those are the
+| Theme                                                                                      | Open | Closed |
-      two cases the quiet path passes vacuously.
+| ------------------------------------------------------------------------------------------ | ---- | ------ |
-
+| [Affordances](todo/affordances/)                                                           | 1    | 0      |
-- [ ] **The terminal replays terminal QUERIES, which get typed into the shell.** `sidecar/pty/sessions.mjs`
+| [Speaking into a session from the backend](todo/agent-delivery/)                           | 2    | 0      |
-      replays the whole scrollback on attach; query sequences in the buffer get re-asked, xterm.js answers,
+| [Backburner](todo/backburner/)                                                             | 2    | 0      |
-      and the answers arrive as keystrokes. Visible to a member daily. Fix is to strip query sequences in
+| [Background jobs](todo/background-jobs/)                                                   | 1    | 0      |
-      `appendBuffer`, so a replay reproduces output and never re-issues requests.
+| [Chat interface](todo/chat/)                                                               | 1    | 0      |
-
+| [Code editor](todo/code-editor/)                                                           | 1    | 0      |
-- [ ] **The web terminal renders a long URL as unreadable fragments.** Claude Code's first-run login prints
+| [Components — the shared UI layer](todo/components/)                                       | 1    | 0      |
-      a ~400-character OAuth URL; the web terminal shows scattered characters with large gaps, nothing
+| [File watchers](todo/file-watchers/)                                                       | 1    | 0      |
-      selectable. Half worked around by `2a8f004` (OSC 52, so "press c to copy" reaches the clipboard) — the
+| [Fleet — one command across every server](todo/fleet/)                                     | 3    | 0      |
-      rendering itself is undiagnosed. This is every new member's first five minutes.
+| [Headscale](todo/headscale/)                                                               | 0    | 5      |
-      `docs/open-threads-after-per-user-claude.md` §1 has what is known and where to start.
+| [Infra (alpha)](todo/infra/)                                                               | 6    | 0      |
-
+| [Known bugs](todo/known-bugs/)                                                             | 2    | 1      |
-- [ ] **Agent sessions are not durable, and it is one property behind three symptoms.** A sidecar restart
+| [Mobile apps](todo/mobile-apps/)                                                           | 2    | 0      |
-      loses session identity, which is why `endTurnIfAgentIsGone` must skip sessions with no recorded
+| [Multi-user](todo/multi-user/)                                                             | 17   | 3      |
-      `userId`, why a stuck "generating" spinner survives until a reconnect, and why any crash in that process
+| [Notifications](todo/notifications/)                                                       | 1    | 0      |
-      is destructive rather than merely inconvenient. Fixing the three separately would miss that they are one
+| [Plugin ecosystem — before it opens to third parties (2026-08-18)](todo/plugin-ecosystem/) | 3    | 0      |
-      missing property. `docs/open-threads-after-per-user-claude.md` §2.
+| [Plugin infrastructure](todo/plugin-infrastructure/)                                       | 2    | 0      |
-
+| [Plugin repos — what writing their READMEs turned up](todo/plugin-repos/)                  | 10   | 9      |
-- [ ] **`ProcessTransport is not ready for writing` — survivable since `8c4f150`, still unexplained.** A
+| [Plugin system — gaps the email extraction found (2026-08-18)](todo/plugin-system/)        | 3    | 0      |
-      floating rejection inside the SDK's own input pump, with no frames from our code, so no `await` of ours
+| [Prompt library](todo/prompt-library/)                                                     | 1    | 0      |
-      can catch it. It crashed `officer-agent` four times on 2026-08-11, once truncating a turn mid-sentence;
+| [Shell — spotlight and the dock](todo/shell/)                                              | 1    | 1      |
-      the `unhandledRejection` backstop has caught it once since. Best hypothesis is the `claude` CLI exiting
+| [Sub-agents — agents spawning agents](todo/sub-agents/)                                    | 1    | 1      |
-      while `streamInput` is still pumping. It needs looking at after the next occurrence, not catching in the
+| [Sudo terminal modal](todo/sudo-terminal-modal/)                                           | 1    | 0      |
-      act — markers to grep in `docs/open-threads-after-per-user-claude.md` §3.
+| [Tooling — the list about the list](todo/tooling/)                                         | 1    | 0      |
-
+| [Transmission](todo/transmission/)                                                         | 6    | 0      |
-- [x] **No way to create a second account.** Fixed 2026-08-11 on `sidecar-app-store`: `POST /api/users`
+| [URL state — routing, query strings and selection](todo/url-state/)                        | 4    | 0      |
-      (`api/users/create-user.ts`, owner-gated) plus an Add-account form in
+| [Waiting on the owner to run it](todo/waiting-on-owner/)                                   | 2    | 0      |
-      Settings → User management. Created accounts are `status: 'Active'` — the column defaults to
+| [Workspaces & Panels](todo/workspaces-panels/)                                             | 2    | 0      |
-      `'Unverified'` and `signin.ts` refuses anything else with a bare UNAUTHORIZED, which is the trap
+
-      the hand-INSERT route fell into. The owner sets the password and reads it out; `passwordChangedAt`
+## Records — no items, kept for the reasoning
-      stays null. Directories come from the shared `provisionUserDirs`/`USER_DIRS` in `data-path.ts`,
+
-      which `scripts/provision-user-dirs.ts` now imports rather than restating.
+- [Affordances (2026-08-19)](todo/affordances-runtime/_index.md)
-
+- [Email](todo/email/_index.md)
-- [ ] **Still no invite flow, and no password reset for a member.** The owner types the password and
+- [Inputs outside forms (2026-08-19) — swept, fixed, closed](todo/inputs-outside-forms/_index.md)
-      tells the person, which means the owner knows it and the member cannot change it back if they
+- [Release-binary dependencies (2026-08-19)](todo/release-binaries/_index.md)
-      forget theirs — recovery today is delete-and-recreate. An invite (token, expiry, member sets
+
-      their own) needs a mail path. This is the next piece, not a nice-to-have.
+## Newest ten
-
+
-- [x] **A second Super Admin was storable, and made the owner nondeterministic.** Fixed 2026-08-11.
+- `2026-08-21` **No way to see which affordances are reaching your agents, or to turn one off** — [affordances/no-way-to-see-which-affordances-are-reaching](todo/affordances/no-way-to-see-which-affordances-are-reaching.md)
-      `ck_users_owner_is_super_admin` pins user 1's role but a row-level CHECK cannot see other rows, and
+- `2026-08-21` **Generalise it: deliver a turn to a named session, from anywhere in the backend** — [agent-delivery/generalise-it-deliver-a-turn-to-a-named](todo/agent-delivery/generalise-it-deliver-a-turn-to-a-named.md)
-      `updateUserRoleHandler` happily promoted anyone — while `getOwnerUser()` was
+- `2026-08-21` **The cost of resuming grows with the transcript** — [agent-delivery/the-cost-of-resuming-grows-with-the-transcript](todo/agent-delivery/the-cost-of-resuming-grows-with-the-transcript.md)
-      `WHERE role='Super Admin' LIMIT 1` with no ORDER BY. Two holders would have made "who owns this
+- `2026-08-21` **Show how long a turn took, beside its cost and tokens** — [chat/show-how-long-a-turn-took-beside-its-cost](todo/chat/show-how-long-a-turn-took-beside-its-cost.md)
-      server" a question the query plan answered, and that answer feeds the agent sidecar's identity,
+- `2026-08-21` **Map every custom component, centralise it, and let a theme override it** — [components/map-every-custom-component-and-centralise-it](todo/components/map-every-custom-component-and-centralise-it.md)
-      vault access and origin scoping. Both write paths now refuse the role, the list endpoint offers
+- `2026-08-21` **Watch a directory, and attach actions to what lands in it** — [file-watchers/watch-a-directory-and-attach-actions-to-what](todo/file-watchers/watch-a-directory-and-attach-actions-to-what.md)
-      `assignableRoles` without it, and `getOwnerUser()` orders by id.
+- `2026-08-21` **Settings to choose which server each feature uses** — [fleet/settings-to-choose-which-server-each-feature](todo/fleet/settings-to-choose-which-server-each-feature.md)
-
+- `2026-08-21` **A way to mark a commit "this one ships", so a release is not just `master`'s tip** — [fleet/a-way-to-mark-a-commit-this-one-ships-so-a](todo/fleet/a-way-to-mark-a-commit-this-one-ships-so-a.md)
-- [ ] **`dashboards.id` is a global primary key, and ids are `slugify(name)`.** Two accounts cannot
+- `2026-08-21` **OPM — Officer's own process manager, or at least its own PM2** — [infra/opm-officer-s-own-process-manager](todo/infra/opm-officer-s-own-process-manager.md)
-      both have a dashboard named "Home". Reachable today: six accounts exist. The recommendation on
+- `2026-08-21` **iPhone Action Button → run an Officer task from a locked phone** — [mobile-apps/iphone-action-button-run-an-officer-task-from](todo/mobile-apps/iphone-action-button-run-an-officer-task-from.md)
-      the table is a composite PK `(user_id, id)` — it matches the `uq_dashboards_user_id` index
-      already there and keeps every stored `ws-layout-<id>` address valid, which uuid ids would not.
-      Note the drizzle composite-PK re-diff quirk in `databases/CLAUDE.md`. Full analysis in
-      `docs/workspace-panel-todo.md` §3.
-
-- [ ] **`permissions/authorize.ts` has no automated tests.** `registry.test.ts` covers the pure
-      registry functions and the totality check; the resolver that does the owner bypass, the grant
-      lookup, the role cache and the fail-closed catches is exercised only by hand. It is the file
-      standing between a Member and a shell.
-
-- [ ] **`assertPermissionTotality` checks the wrong list, and `registry.test.ts` has been red since
-      2026-08-13.** It is fed `Object.keys(handlers)` from `server.tsx`, but Bun serves the _route table_.
-      Those diverged when the cliamp/desktop/vault plugins were switched off: `/api/cliamp/ws` and
-      `/api/cliamp/audio/ws` are still live routes with their handlers and registry claims commented out.
-      Not exploitable — `isWsProviderAllowed` finds no permission and 403s a member; the owner upgrades onto
-      a dead socket. But the boot check that exists to stop exactly this cannot see it. Two fixes: point
-      totality at the route table, and either delete the dead routes or restore their claims. The 8 failing
-      tests in `registry.test.ts` are the same drift — `REAL_WS` still lists all nine providers as served,
-      which is why nobody noticed. Found 2026-08-14.
-
-- [ ] **No empty state for a denied screen.** A member who reaches a route their role lacks gets a
-      broken panel or an endless spinner rather than a clean refusal.
-
-- [ ] **`getOwnerHomeDir(email)` ignores its argument** whenever `HOME_DIR` is set, which it is here —
-      every caller resolves to the owner's real login home. Safe only because all seven callers sit
-      behind `execution` permissions. If per-user home confinement is ever attempted, this is the
-      function to start from.
-
-- [ ] **`pty`, `vault` and `opencode` receive no identity at all.** Every other sidecar validates
-      `X-Officer-User`. The pty sidecar keys purely on a `sessionId` from the query string and its
-      `/_officer/sessions` endpoints list and kill _every_ session on the box; vault and opencode take
-      no user argument. All three are covered today only because `terminal`, `vault` and the agent are
-      owner-only permissions — that is a correct outcome resting on the wrong layer, and it is the
-      thing to fix first if any of them is ever granted.
-
-- [ ] **Radicale is configured `type = owner_only`** (`sidecar/caldav/radicale.ts:54`) while the caldav
-      sidecar itself is fully per-user and confines every JSON read to `/dav/<userId>/`. The platform
-      side is ready for members; the CalDAV server underneath is not.
-
-- [ ] **The music library is one global index.** `sidecar/music/indexer.ts` reads `HOME_DIR` and serves
-      every account from it. Favourites, playlists and now-playing _are_ per-user. Deliberate for now
-      (one household, one library) but worth stating rather than discovering.
-
-- [ ] **`markInterruptedJobs()` and `getOldestPendingJob()` are platform-wide.** The pipeline queue is a
-      single global lane; ownership is enforced one layer up, in `pipeline-jobs-routes.ts`, by an
-      explicit `job.userId !== user.id → 404` on every by-id route. Correct today, but the queue itself
-      has no notion of whose work it is running.
-
-- [x] **Cross-user writes in the notify sidecar** (fixed 2026-08-07, this session).
-      `DELETE /_officer/devices/:token` deleted by token with no user predicate, so any account with the
-      `notify` permission could deregister another's device; and `POST /_officer/notify` let a request
-      body's `userId` override the proxy-injected `X-Officer-User`, so the same account could push to
-      another's devices. `deletePushDevice` now takes an optional `userId` (the route passes it, the
-      APNs/FCM dead-token paths deliberately do not) and the header now wins over the body.
-
-- [ ] **Remove dead `username` plumbing.** `send-claude-code.ts` declares `username` in two types
-      without using it. (`toShellUsername` is NOT dead — `server.tsx:190` and
-      `pipeline-job-manager.ts:267` both call it. The `provision.ts` caller this item used to name no
-      longer exists.)
-
-## Email
-
-Email became a plugin on 2026-08-18 (`plugins/email/`, `gitea.officer.dev/plugins/email`). Its work queue
-went with it — the open items pointed at `sidecar/email/store.ts`, a path in another repository, which is
-exactly the way a leftover list sends someone to edit files that are not there.
-
-Anything still owed to the mail client belongs in that repository's own TODO.
-
-## Transmission
-
-Phase 1 (parity with `_references/transmission-web`) shipped 2026-07-30: the `officer-transmission`
-sidecar plus `/transmission` (torrents / stats / settings). Everything below is **phase 2** — none of
-it exists in the reference app, so none of it was in scope for parity.
-
-### Probably needed regardless
-
-- [ ] **Resizable detail pane.** `TorrentsView` pins it at `DETAIL_HEIGHT = '45%'`, which is a guess.
-      Either a drag handle or a persisted height in `useLocalStorageState`, alongside the column set.
-- [ ] **Revisit `DEFAULT_VISIBLE_COLUMNS`.** Eleven of thirty, chosen before ever seeing the table
-      rendered against the real 43-torrent library. Likely wrong in both directions.
-- [ ] **Files tab on huge torrents.** `detail/FilesTab.tsx` builds the whole tree and renders every
-      node — no virtualisation. Fine at 14 files; unknown at a few thousand. If it stalls, the fix is
-      `useVirtualizer` over a flattened visible-node list, the same shape as `TorrentTable`.
-
-### Ideas, unprioritised
-
-- [ ] **Container→host path mapping.** The daemon reports its own namespace (`/downloads/complete`),
-      which is not a path on this host. A mapping table (`/downloads` → `~/hdds/08_TB_01/Torrents`,
-      `/downloadsTV` → `14_TB_02/Torrents`) would make locations clickable through to `/files` and
-      make "Set location" offer real destinations. Deliberately dropped from phase 1: the reference
-      app has no such feature, so it would have been config nothing read.
-- [ ] **Push instead of poll.** Transmission RPC has no push channel, so `useTransmissionData` polls
-      every 5s. The sidecar could poll once and fan out over a WebSocket, which is both cheaper and
-      what every other live surface in the platform already does.
-- [ ] **Cross-surface links.** Soulseek and `download-media` both land files in the same library;
-      Transmission is the third door to it. Worth a think about whether they should know about each
-      other at all.
-
-## Headscale
-
-Gaps against headscale's own API, found while reading the app on 2026-08-05 — all closed the same
-day. Kept here for what the policy work turned up, which is not obvious from the code.
-
-- [x] **ACL policy.** `/api/v1/policy` GET/PUT behind `/_officer/policy`, with a plain HuJSON textarea
-      that sends the text byte for byte and shows headscale's verdict verbatim (line and column
-      included). Officer does not pre-validate: headscale owns the only parser that resolves groups,
-      tags and hosts, and a second weaker one would disagree with the thing that actually enforces.
-      **The mode cannot be read.** A file-backed policy is still served over GET; only a PUT refuses,
-      with "update is disabled for modes other than 'database'". So the first save is what discovers
-      writability, and a refusal becomes a persistent read-only banner. Verified live, not inferred.
-
-- [x] **A node can be moved between users.** `/api/v1/node/{id}/user`, in the expanded node card next
-      to the tag editor — both being the things that decide which policy rules apply to a node.
-
-- [x] **User rename** — was already shipped end to end (`/users/:id/rename`, `UsersView`); this entry
-      was stale when it was written.
-
-- [x] **Polling** — `useHeadscaleNodes` has had `refetchInterval: 20_000` all along; also stale.
-
-- [x] **Device invites, platform side** (`COMMS/OFFSCALE_INVITE_ENROLLMENT.md` §5, built 2026-08-05).
-      Authorize-new-device form, the one-time link with copy/share/QR, and the invite list with revoke —
-      `/_officer/enroll/invites` in `invites.ts`, `InvitesView`. **The records are not Officer's.** They
-      proxy to the server's Officer Companion, because the joining phone has to claim without an Officer
-      account and this sidecar is loopback-only behind our auth; the spec's own "an invite must work when
-      the platform is down" argument says the same. Officer stores no invite and no claim token.
-      **Live on all four servers since 2026-08-05.** The 401 that blocked it was a companion-side prefix
-      parse (a Headscale key prefix is a fixed 12 chars and may contain `-`; they split on the first one);
-      fixed upstream. Verified end to end against pastilhas-eu: create returns the
-      `officer-offscale://join#…` link, list shows the record, revoke flips it to `revoked`. The list
-      envelope is not in the spec, so `pickInvites` takes the body's array whatever it is keyed under.
-      Four gaps were sent back to the spec author: `keys.ts` has no
-      sub-day key TTL for the 5-minute claim key, "the sidecar must refuse plaintext" is unenforceable
-      behind nginx, `tailnet` is not a headscale concept and has to be recorded on the invite, and
-      `/api/v1/enroll/*` collides with headscale's own namespace.
-
-## Workspaces & Panels
-
-Its own list — **`docs/workspace-panel-todo.md`** — because it is long and actively worked. Full
-analysis behind it: `COMMS/workspace-panel-framework-analysis-2026-08-07.md`.
-
-Headlines: the framework has **no panel lifecycle** (a panel can be destroyed but never told, which is
-the real cause of the terminal orphan leak); three state-key families are **silently dropped on every
-write**, orphaning a pty per reload; Running Shells has **404'd since 2026-07-31**; there are **zero
-error boundaries** anywhere in the repo; and `dashboards.id` is a **global** primary key fed by
-`slugify(name)`, so two members naming a dashboard the same thing collide.
-
-- [ ] **Renaming a panel key is a silent data migration, and the repair is destructive.** A saved layout
-      holds `appType` strings. `normalizeLayout` replaces any appType not in the allow-list with the
-      caller's `fallback`, and `WorkspaceView.tsx:97` writes that back — so a renamed key turns every
-      saved layout into N copies of whichever panel is `allowed[0]`, permanently, on one page load.
-      Renaming `headscale-*` → `offscale-*` did exactly this: `/offscale` rendered three server pickers,
-      `ServersView` never mounted, and it survived every restart because the code was correct and the
-      data was not (2026-08-17, `ed3806f9`).
-
-      Plugin screens are now cleared at install, which covers plugins and nothing else. The general fix
-      is a rule about wholesale mismatch: **a layout in which NO panel has a recognised appType is
-      residue from older code — discard it and use the screen's default**, rather than collapsing it.
-      `fallback: allowed[0]` is arbitrary (it is whatever `panels.ts` happens to list first) and should
-      probably not be a per-panel substitution at all.
-
-## Code editor
-
-- [ ] **The owner wants to go deeper here — ideas pending (noted 2026-08-15).** Raised right after the file
-      browser gained its first links into `/code-editor`. Do this after the file-browser test pass.
-
-      What is worth knowing before starting, all established on 2026-08-15:
-
-      **It has been effectively invisible for six months.** The app landed 2026-02-21 (`9e9acd96`), the
-      screen 2026-02-17, and `1fa3a659` on 2026-07-25 is titled "**restore** the code editor screen" — so
-      it was dropped and brought back at least once. It IS in `CORE_DOCK_ITEMS` as "Editor", but
-      `DEFAULT_DOCK_PATHS` is `['/', '/files', '/terminal', '/dashboards', '/chat']` and the owner's own
-      `dock_configs` row does not list it either. Until today the only way in was typing the URL.
-
-      **So it has no users, and that is the risk.** A surface nobody reached for six months is where things
-      rot quietly. Nothing about the editor itself has been verified — whether saving works, how the file
-      tree behaves, what closing the last tab does, what an unsaved-changes navigation does. Only the
-      plumbing was checked: `?file=` is read (`EDITOR_FILE_PARAM`), `/code-editor` renders with `urlState`,
-      and `CodeEditor.tsx:60-76` fetches a path that arrives in the URL rather than only matching already
-      open tabs.
-
-      **One bug of exactly this kind was already found and fixed** in the FileViewer's editor on the same
-      day: the Edit toggle was gated on `content` rather than `content !== null`, so an empty file — the
-      one "New file" produces — could not be edited at all. Assume siblings.
-
-      **Open question, deliberately not decided:** `Open in editor` in the file browser's row menu still
-      navigates to `/code-editor`, which is the last action that leaves the browser. Editing now happens
-      in place via double-click → the viewer's pane. Either `/code-editor` earns its keep as a genuinely
-      different tool (tree, tabs, multi-file) or that menu item should go.
-
-## Files app — routing
-
-**The URL model is done (2026-08-15).** The folder is the pathname —
-`/files/archive/Tests/platform/docs` — and `?view=` is a NAME within it, not a second copy of the path.
-Deep links and refresh work, which they never had. Landed across `559560de`, `98ba604a`, `7e31564c`,
-`0dc88b51`, `7359af2f`, with `files-route.ts` + 23 tests as the one owner of encoding and of which params
-belong to the overlay.
-
-Four bugs came out of that work and are fixed: closing a pane sent you home; `?view=` was stripped on
-every page load by a mount effect that had made deep links impossible since 2026-02-23; navigating kept a
-pane belonging to the folder you left; and the breadcrumb opted out of that last rule because it is a
-`<Link>` and never called the function enforcing it.
-
-- [ ] **Rows are still not links.** This is the half that did not get done, and it is the original
-      finding. Both list and grid render `<div onDoubleClick>` (`FileItem.tsx:701,748`), and search
-      results render `<div onClick>` (`FileViewContainer.tsx:187`) — the "opaque click" that
-      `docs/navigation-audit.md` names. No cmd-click into a new tab, no middle-click, not
-      link-focusable, and the target lives in a closure rather than the DOM.
-
-      It is now much easier than it was: `folderHref(path)` gives a folder's URL and `hrefForPath` gives
-      a full `To` with the overlay already stripped, so a row becomes
-      `<Link to={hrefForPath(childPath)}>` and a file row becomes a link that sets `?view=<name>`. The
-      breadcrumb has done exactly this since before today and is the model.
-
-      Watch for: a row is also a click target for SELECTION (single click selects, double opens,
-      shift/cmd extend). An anchor changes what those gestures mean by default, so the selection
-      handlers have to keep working and `preventDefault` where they win.
-
-- [ ] **The acts that clear the overlay have no owner, only the list does.** `VIEWER_PARAMS` and
-      `withoutViewerParams` live in `files-route.ts` and are shared. But every site still decides FOR
-      ITSELF whether to call them, which is precisely how the breadcrumb shipped wrong an hour after the
-      rule was written. Three bugs in a row came from this. A single `navigateToFolder()` that every
-      caller must go through — rather than a helper they may remember — is the fix if a fourth appears.
-
-- [ ] **A panel's folder is still not addressable.** `urlPath` is true only on the `/files` screen;
-      panels keep the path in local state, so they always open at their base and cannot be linked or
-      restored. Deliberate as written — a dashboard can hold two browsers and one URL cannot serve both —
-      but worth re-deciding rather than inheriting.
-
-## Release-binary dependencies (2026-08-19)
-
-Built: a plugin can declare `release: { url, identify }` for a dependency no package manager carries.
-Gitea's `tea` is the motivating case and the first user.
-
-Two things it does NOT do, both deliberate and both worth knowing:
-
-- **No checksum.** The download is verified by RUNNING it through the same `identify` rule the probe
-  uses, which catches an HTML error page, a truncated file and a wrong-architecture build — none of them
-  print what the plugin said to look for. It does not catch a compromised upstream. A checksum per
-  os/arch is a table that goes stale every release and would stop installs the day upstream re-cuts a
-  tag; HTTPS and a URL the owner reads in the install dialog is what stands behind it today.
-- **The version is pinned in the manifest.** `tea` is fixed at 0.15.1, so a new release needs a plugin
-  update. That is the right default — an install that silently fetches whatever is latest is not
-  reproducible — but there is no "check for a newer one" anywhere.
-
-## Inputs outside forms (2026-08-19) — swept, fixed, closed
-
-The "19 files" count in the previous version of this entry came from one grep
-(`components/ui/input`) and was a starting point, not the answer. A wider sweep — bare `<input>` and
-`<textarea>` too, across the platform and every installed plugin — found **87 files with a matching
-element and no enclosing `<form>`**. Three were false positives (the `Input`/`Textarea` primitives
-themselves, and a `DataTable` test file). Of the remaining 84, **41 were fixed** (real forms, single
-fields with an obvious action, or multi-field editors) and **43 were left alone**, almost all because
-they're a search/filter box with nothing to submit.
-
-**Fixed — platform (24 files, one commit):** `CapabilityPage`, `ApifyConfig`, `ApiKeys`,
-`DavAppPasswords`, `GoogleOAuthConfig`, `AIHarnessesSection` (local-provider connect, its auth step,
-and both API-key edit rows), `OCRSection`, `SMTPSection` (split into two independent forms — save vs.
-send-test-email, since one form would have made Enter in the test-email field trigger Save),
-`STTSection`, `TTSSection`, `AppStoreDetail`, `ChatHeader`, `BackgroundJobDialog`, `QuestionActivity`,
-`WebpageDialog`, `DirPickerModal`, `SessionRow`, `CommandHqCategories`, `FileItem`, `NewEntryDialog`,
-`TaskRunnerModal` (the Agentic and Pipeline ready phases), `PreviewHeader`, `widgets/DailyGoals`,
-`widgets/Pomodoro`.
-
-**Fixed — plugins (17 files, one commit per plugin, each pushed to its own remote):**
-`bitcoin-wallet` (`ChainSourceCard`, `RescanCard`, `WalletSettingsView`), `email` (`Compose`,
-`EmailAccounts`), `invoices` (`DocumentEditor`, `RecordEditors`, `SendDocumentDialog`), `offscale`
-(`NodesView` — rename and tags fields), `soulseek` (`SoulseekConnection`), `transmission`
-(`ConnectionView`, `SettingsView`, `AddTorrentDialog`, `MoveTorrentDialog`, `RenameDialog`,
-`TorrentOptionsDialog`), `vault` (`VaultPanel`). `jellyfin` and `music` needed no changes.
-
-**Left alone — search/filter boxes with no submit action** (the large majority of the 43): `JobsPage`,
-`SettingsPanel`, `SearchInput`, `sounds/Catalog`, `widgets/QuickNotes`, `Dashboards/DashboardListApp`,
-`SystemMonitor/DockerView`, `FileBrowser*` toolbar/header/view-container files, `ChatHistory` list
-filters, `invoices`' six list views (`CustomersListView`, `EstimatesListView`, `ExpensesListView`,
-`InvoicesListView`, `ItemsListView`, `ReportsView`, `components.tsx`), `jellyfin` (`PlayerControls` —
-range sliders, not text fields — and `SearchSection`), `music` (`MusicBrowser`, `MusicPlayerHost`),
-`offscale` (`Cards`, `PolicyAssistant` — already handles Enter/Shift+Enter correctly, `PolicyView` — a
-textarea, never auto-submits), `soulseek` (`SearchResults`, `SharesBrowser`), `transmission`
-(`TorrentToolbar`), `FileViewer` renderers (`AudioRenderer`/`VideoRenderer` — volume/seek sliders), and
-the main chat composers (`InputArea`, `ChatLauncher`, `SoulseekChat`) — all textareas with their own
-Enter-sends/Shift+Enter-newlines handling, where a `<form>` would add nothing and risks regressing that
-handling.
-
-**Left alone — genuinely ambiguous, flagged rather than guessed:**
-
-- `TaskRunnerModal`'s `ScriptRunner` ready phase offers three simultaneously-visible, non-equivalent
-  primary actions ("Run here" / "Queue" / "Run as job"); there's no single canonical action for Enter to
-  trigger.
-- `Dashboards/DashboardPreview`'s `NamePanel` (name + description) has its submit button in a
-  _different_, independently-mounted panel (`CreatePanel`) elsewhere in the workspace layout tree — a
-  `<form>` can't span two panels without restructuring the wizard.
-- `ColorPicker` and `MarkdownEditor` have zero call sites anywhere in the repo right now; both are
-  shaped to be embedded in a future caller's own form (uncontrolled inputs with `name` attributes, or a
-  plain controlled textarea with no submit of its own), so there's nothing to wrap yet.
-- `widgets/Weather`'s `LocationSetup` is a live autocomplete with several result rows and no single
-  obvious Enter target (which of N matches?).
-
-**Noticed, out of scope, not fixed:**
-
-- `ModelSelector`'s provider-picker button has no `type` attribute — harmless today only because it
-  currently sits outside every `<form>`; a landmine if that layout changes.
-- `MusicBrowser`'s filter input uses `(e) =>` instead of the house `ev` convention — pre-existing, not
-  touched since the file needed no fix.
-- `EmailList.tsx`, and a few plugin files touched by this sweep (`VaultPanel`, `ConnectionView`,
-  `SoulseekConnection`, `ChainSourceCard`), have pre-existing `prettier --check` drift outside the lines
-  this pass touched — left as found, not reformatted, per "don't reformat what you're not fixing."
-  Relatedly: **`prettier --write` on a `plugins/<name>/…` path silently no-ops when run from the
-  platform root**, because Prettier v3 respects the root `.gitignore` and `/plugins/*/` is in it — it
-  exits 0 with no diff and no error. Formatting a plugin file requires running prettier from inside
-  that plugin's own directory (still resolves the platform's `.prettierrc` by walking up).
-- A few "Save"/"I've saved it"-style buttons (`ApiKeys`, `DavAppPasswords`, `DirPickerModal`) have no
-  `type` attribute but currently sit outside any `<form>`, so it's harmless today — worth remembering if
-  a future edit wraps that region.
-
-## Affordances (2026-08-19)
-
-Agreed and written down in `plugins/CLAUDE.md`; **nothing is built**. An affordance is what the surface
-on the other end offers the agent — declared by the code that implements it, read at runtime. The first
-two are image rendering (core) and gitea (`git` for git, `tea` for everything else).
-
-Built 2026-08-19: `servers/affordances/load.ts` reads the tree and compiles one block, and
-`claude-manager.ts` appends it to every Claude session via
-`systemPrompt: { type: 'preset', preset: 'claude_code', append }`. Read per session, so a plugin
-installed an hour ago is live on the next message.
-
-Still to build:
-
-- `capabilities/affordances/` created by the setup script, with `officer/core/` populated from an
-  officer-capabilities repository. The directory exists on this machine by hand; a fresh install gets
-  nothing, so the first affordance is currently a local artefact rather than a shipped one.
-- **Opencode delivery.** It has its own driver and gets nothing, so image rendering is currently a claim
-  that holds on one harness — exactly the drift affordances exist to remove. Deliberate: opencode work is
-  paused pending its v2 migration and this would be thrown away. Revisit when v2 lands.
-- A bare `claude` run in a terminal on the host gets nothing either, since it never passes through
-  `claude-manager`. Would need a generated file, which is the thing `user-instance.ts` refuses to write
-  for the owner.
-- ~~Plugin contribution~~ — built 2026-08-19 (`affordances/publish.ts`). An `affordances/` directory in
-  the plugin repository is copied to `capabilities/affordances/<publisher>/<plugin>/` on install and
-  removed on uninstall. Gitea is the first to ship one.
-- **The other categories.** A plugin can contribute affordances and nothing else. Skills, tools, tasks
-  and processes are the obvious next ones and were deliberately left out — one mechanism, proven, before
-  five. When they land, `publishAffordances` generalises rather than gaining siblings.
-- **`officer/core` and `officerdev/<plugin>` are both correct — do not normalise them.** The path uses
-  `publisher` verbatim, so a plugin published by officerdev lands under `officerdev/`. `officer/core` is
-  not a plugin at all: it is the PLATFORM's own, shipped by the setup script from the capabilities
-  repository. Two spellings marking two different things, arrived at by accident and kept on purpose.
-  Anyone tidying this into one name is removing the distinction, not the inconsistency.
-
-Open, and deliberately deferred:
-
-- **Scoping.** Everything is loaded into every conversation. Fine at two files, not at twenty. A
-  `surface` field was drafted and dropped because it was doing two jobs at once: for image rendering it
-  means _what the client renders_ (a phone, a web bubble, a cron run with nobody watching), for gitea
-  _what tooling exists on this machine_. Those are different axes and one field cannot be both. Decide
-  the axis before adding the field — and note this codebase has already been bitten by a field that
-  validated itself and was never consumed (`unauthenticatedPaths`, see `plugins/public-paths.ts`).
-- **Drift.** The rule is "declared where implemented", but a hand-authored markdown file in a repository
-  is not that — `ChatImage` could stop rendering images and no file would notice. Accepted for now
-  because prose that reaches every harness beats a registry that reaches one; revisit if it bites.
-
-## Plugin ecosystem — before it opens to third parties (2026-08-18)
-
-Not now. Months away. Recorded so it is not re-derived.
-
-- [ ] **A plugin install is not pinned, so a review would bind a repository rather than code.**
-      `fetch.ts:70` is `git clone --depth 1 <source>` — no ref — so it takes whatever the default branch
-      points at when the install runs. A plugin reviewed at commit X installs at whatever was pushed
-      since, and `--depth 1` leaves no history to compare against.
-
-      This is the shape of the npm attack already documented in `CLAUDE.md` (2026-08-04), and the same
-      shape as the Chrome Web Store's real failures — not bad extensions passing review, but good ones
-      sold or compromised and then pushing an update to users who had already accepted them.
-
-      Fix: a `reviewedCommit` on the catalogue entry, checkout detached at that SHA, and **verify
-      `rev-parse HEAD` matches or refuse**. The verification is the part that matters. An update then
-      becomes "a new reviewed SHA exists" — a catalogue change rather than something the author triggers.
-
-- [ ] **Third-party plugin sidecars are unconfined.** A plugin sidecar runs `bun run <script>` with
-      `cwd: PLATFORM_DIR`, so Bun auto-loads `.env` and it gets `POSTGRES_URL`; it runs as the service
-      user, which owns `secrets/officer-keys.db` and can therefore mint an owner JWT. Fine for
-      first-party plugins, total compromise for anyone else's.
-
-      The mechanism to fix it already exists and is pointed elsewhere: `spawn-as-member.ts` drops
-      privileges with `setpriv --reset-env` and a six-name allowlist for exactly this reason.
-
-- [ ] **No install-from-git-URL.** The catalogue is the only route for a remote plugin, so the
-      "build your own, give it to a friend" path has no affordance. Small, and needed before the
-      unofficial channel is real.
-
-## Plugin system — gaps the email extraction found (2026-08-18)
-
-- [ ] **A plugin cannot declare its own npm dependencies, so the PLATFORM is carrying them.** `imapflow`,
-      `mailparser` and `@types/mailparser` are in the platform's `package.json` and are imported by nothing
-      in `src/` — they exist solely for `plugins/email/sidecar/`. Plugins have no `package.json`, run with
-      `cwd: PLATFORM_DIR`, and resolve from the platform's `node_modules`, so deleting those three lines
-      breaks the installed plugin on its first sync.
-
-      This does not scale and it is the wrong party holding the risk: the platform cannot be answerable for
-      what an arbitrary plugin decides to install, and `bunfig.toml` sets `frozenLockfile = true` precisely
-      so a dependency change is a deliberate, reviewed act. Publishing will be reviewed rather than a
-      free-for-all, which narrows the threat but does not move the responsibility.
-
-      What it probably needs: a `dependencies` field in the manifest (the manifest already holds
-      `osDependencies` for host binaries, which is the same shape of problem solved once), installed into
-      the plugin's own directory at install time rather than merged into the platform's tree. Note the
-      install path already learned not to trust `$PATH` — `pushPluginSchema` resolves a binary rather than
-      spawning `bunx` — so whatever runs the install has to do the same.
-
-      Until then: `imapflow` and `mailparser` STAY. Removing them is not tidying, it is breaking email.
-
-- [ ] **`email_accounts/` is created by the PLATFORM for every account, and should be the plugin's job.**
-      `USER_DIRS` in `data-path.ts` pre-creates it at 0700 for every user, whether or not the email plugin
-      is installed — so a core install provisions a directory named for a plugin it does not have.
-
-      Ownership should invert: the plugin provisions its own storage, in all three moments —
-
-      1. **on plugin install**, for accounts that already exist;
-      2. **on user provisioning**, for accounts created afterwards;
-      3. **lazily**, the first time a provisioned user opens the plugin, so a machine that missed either of
-         the above still heals itself.
-
-      The third is the one that makes the other two non-critical, and it belongs in the email sidecar
-      rather than in the platform's account handler.
-
-      This is entangled with the `email_db` leak below — core reads that directory today, so the plugin
-      cannot become its sole owner until that is resolved too. Do them together.
-
-- [ ] **The platform still knows email's on-disk vocabulary, deliberately, and it is untested by anything.**
-      `findEmailAccountName` in `data-path.ts` reads `DATA_PATH/<user>/email_accounts/*/emails.db` and picks
-      the newest by mtime. Two core callers use it: `user-instance.ts` (`OFFICER_EMAIL_DB`, for the agent's
-      `email_db` MCP tool) and `chat/websocket.ts` (`resolveEmailCwd`, for a chat opened against a mailbox).
-      `ChatPanelWrapper.tsx` hardcodes `workspace.id === 'email'` to trigger the second.
-
-      This traded a CODE dependency for a CONVENTION, which was the right trade at the time — the code
-      dependency is what put `officer-agent` into a restart loop on 2026-08-13 (`fbb6d6c7`). But the
-      convention has no enforcement on either side: if the plugin ever renames `emails.db`, moves to one
-      database per folder, or nests differently, core silently points the agent at a path that does not
-      exist. No import breaks, no type fails, no test covers it. The tool just goes quiet.
-
-      The clean version needs two things the platform does not have: a way for a plugin to ship an MCP tool,
-      and a way for a plugin to declare a chat context. Until both exist this stays — but it should be a
-      decision someone re-takes, not one that is inherited.
-
-## Plugin repos — what writing their READMEs turned up
-
-Three READMEs were written on 2026-08-16 (`music`, `offscale`, `example`) and pushed to their own repos.
-Writing them meant reading each plugin against its own documentation, which is the cheapest audit there
-is. Everything below was found that way and none of it is fixed.
-
-**Offscale is still branded headscale in shipped, user-visible places.**
-
-- [ ] `web/panels.ts` registers three panels named "Headscale servers", "Headscale", "Headscale" — these
-      are what a user reads in the panel picker.
-- [ ] `web/OffscaleServerPicker.tsx:26` renders the literal heading `Headscale`.
-- [ ] `web/ConsoleView.tsx:22` mints terminal session ids as `headscale-console-<id>`. That is persisted
-      state rather than a comment, so renaming it orphans live console sessions — cheap now, less so later.
-- [ ] ~12 stale `/headscale` route paths in comments across `web/`, plus `App.tsx:78` in the platform.
-- [ ] `PLUGIN.md` has ~11 stale self-references (`headscale_servers`, `listHeadscaleServers`, permission
-      key `headscale`, `/api/headscale`, panel keys, `useHeadscaleSection()`).
-
-**Documentation that actively lies.**
-
-- [ ] `plugins/offscale/PLUGIN.md:445-449` says the ACL assistant is deliberately unwired and must not be
-      wired up. It IS wired — `sidecar/assist.ts`, `claude-proxy.ts`, `web/PolicyAssistant.tsx` and the
-      manifest's `readOnlyWrites` all ship.
-- [ ] `plugins/offscale/OFFSCALE_API.md` claims to publish the contract "in full" and omits six live
-      surfaces, including all of `/_officer/companion/*` and `/_officer/enroll/invites`.
-- [ ] `plugins/music/MUSIC_API.md` says favourites and now-playing are served by the platform from
-      Postgres; the sidecar serves them itself, scoped by `X-Officer-User`. It also documents the playlist
-      item key as `<albumRel>/<file>` while the schema and favourites use the home path — the same file
-      contradicts itself.
-- [ ] `plugins/music/MUSIC_API.md` documents now-playing as one snapshot per user with no mention of
-      `?device=`, which the schema makes part of the primary key. A mobile client written to that doc is
-      correct only by accident.
-- [ ] `plugins/example/manifest.ts:12` lists `web/Router.tsx` as the frontend convention; discovery
-      requires `web/panels.ts` AND `web/layout.ts`. The same file documents an `ownerOnly` field that does
-      not exist and never did.
-- [ ] The Companion contract docs the offscale code cites (`COMMS/OFFSCALE_COMPANION_API.md`,
-      `COMMS/OFFSCALE_INVITE_ENROLLMENT.md`) exist nowhere — `COMMS/` was deleted. Two of the plugin's
-      eight sections depend on a service with no published spec.
-
-**Conventions a plugin author has to guess.** All verified in `discover.ts`/`mount.ts`, none documented
-outside the example's new README:
-
-- [ ] Panel `key`s and layout `appType`s must agree, and a mismatch fails SILENTLY — `PluginScreen.tsx`
-      pins `appTypes.allowed` with `fallback: allowed[0]`, so a typo renders the first panel.
-- [ ] The `<appName>_` table prefix is unenforced. The barrel is `export *` across every plugin into one
-      `public` schema, so two plugins choosing the same unprefixed name collide with no error until push.
-- [ ] A manifest is module-cached for the process lifetime: editing it does nothing until
-      `pm2 restart officer`, and `outdated` cannot see a version bump either.
-- [ ] Permission-key prefixing is convention, not validation. Only a collision with a CORE key is refused,
-      silently, at mount, with a console error.
-
-**Genuinely missing.**
-
-- [ ] `plugins/offscale` spawns the `ssh` binary (`sidecar/ssh.ts`) but declares no `osDependencies`, so
-      install never checks for it and the Console fails at runtime instead of refusing at install.
-      `PLUGIN.md:421` already lists it as a host dependency — the manifest is the file that is wrong.
-- [ ] `scripts/reindex-music.ts` resolves its port file from `process.env.DATA_PATH ?? cwd/data`, and
-      `DATA_PATH` stopped being an env var on 2026-08-13. Run from the repo it looks in
-      `platform/data/music/.server` and never finds it. One line.
-- [ ] `plugins/music/web/MusicPlayerHost.tsx` header says it is mounted once in the persistent
-      DashboardLayout; it moved into `MusicDetail`. That is exactly the comment that would mislead
-      someone about why playback stops off-route.
-- [ ] A plugin's `assets/icon.png` is only published while installed, so its real icon is invisible in the
-      store before install. The catalogue's `iconUrl` works around it, and an author has to know to add one.
-
-## Waiting on the owner to run it
-
-- [ ] **The AI usage panel works for one account; the multi-account half is unproven.** Landed and verified
-      live 2026-08-18 — click the harness pill in the chat composer and it shows Claude Code's own usage
-      display, limits with countdowns, tokens by day and by model.
-
-      What is NOT proven is the reason it was built: a second Anthropic login, the account tabs, and a
-      stored row surviving a switch. **Group C of `docs/ai-usage-panel.md`** is that, and test 10 is the one
-      most likely to be wrong — a refresh must not overwrite an account it could not measure, and that
-      failure is silent.
-
-      Deliberately deferred rather than forgotten: the owner switches accounts when the work needs it, and
-      the worst case is one wrong tab. Run Group C the first time a second login lands on this machine.
-
-      Also unexercised: the model dropdown no longer renders the literal string `claude-code` for a chat
-      that named no tier. Needs `officer-claude-code` restarted, not just `officer` — the parser in the
-      sidecar is what emits it.
-
-- [ ] **Plan mode is live and has never been exercised.** Landed `1b811dfa` on 2026-08-17; all three
-      processes were restarted the same evening, so the code IS running. Not one part of it has been used:
-      not the toggle, not the plan card, not the round trip from the sidecar's pending promise to a browser
-      and back, not the stored column, not `settleAllPlans`.
-
-      **`docs/chat-plan-mode-test-plan.md` is the checklist** — eleven ordered tests, what each should show,
-      and what its failure looks like. Test 4 (approve) is the one most likely to be wrong: it is the case
-      that changed the design, because approving `ExitPlanMode` drops the harness into `default` rather than
-      back into `bypassPermissions`.
-
-      Safe to leave untested. Plan mode is opt-in and off by default, so a conversation that never touches
-      the toggle behaves exactly as it did before. The one failure worth knowing in advance is a turn that
-      never ends after a plan is answered — that would be a leaked `canUseTool` promise, and
-      `pm2 restart officer-claude-code` clears it.
-
-      Design and the probe results behind it: `docs/chat-plan-mode.md`.
-
-## Known bugs
-
-- [ ] **Background job logs appeared INSIDE an open file in the code editor.** Reported 2026-08-16 by the
-      owner, on the production host, running as a member with a `bun dev` background job streaming. The
-      editor had a file open; the runner's log output was rendered into that file's buffer. **It was never
-      saved** — the file on disk was intact, and the editor was not marked dirty as far as the report goes.
-      So this is a DISPLAY-layer mixing, not a write path: the bytes reached a buffer that only exists in
-      the browser.
-
-      Not reproduced, not diagnosed, and deliberately not guessed at further than this. What is worth
-      recording is where the two streams could meet, because both were added in the same week and they are
-      the only two things writing text into a panel:
-
-      - `useTaskDetail` polls `GET /chat/tasks/:id` every 2s while a job runs and returns `{kind:'log', text}`.
-        `CodeSurface` renders it — and `CodeSurface` is shared with the editor's own surfaces.
-      - The editor keys open files by PATH (`useEditorState`), while the task panel keys by TASK ID, and
-        several panel-scoped stores in between are keyed by `panelId` through `useGlobal` /
-        `usePanelMemory`. A key collision between those namespaces would produce exactly this: one panel's
-        text arriving in another's buffer, with no server involvement and nothing persisted.
-
-      **Screenshot 2026-08-16 answers the first question and kills two theories.** The tab carries a DIRTY
-      dot, and the log lines have Monaco line numbers continuing the file's own sequence (…180, then eight
-      lines of dotenv/POSTGRES_URL output, then 189 `</Link>`). So the MODEL was mutated — this is the
-      editor's content state, not its render, and the earlier "the file was okay" means it was simply never
-      saved. Note the splice is mid-file, not a replacement: JSX text and log text share line 180
-      (`Forgot?--env-file=.env --watch src/server.tsx`).
-
-      Ruled out by that: `CodeSurface` renders with shiki, not Monaco, so the two cannot share an editor
-      instance. And the app's only other Monaco mount (`FileViewer/renderers/EditorRenderer.tsx`) passes no
-      `path`, so its model URI is `inmemory://model/N` and cannot collide with the editor's `file:///…`.
-
-      So the pollution arrives as TEXT through the editor's own content path — `openFile`, `setContent`, or
-      the end-of-turn refresh that re-reads every clean file. That last one is the prime suspect: it is the
-      only thing that writes a buffer without a keystroke, it runs exactly when a background job is
-      producing output, and it lands its result by path.
-
-      **Narrowed 2026-08-16, and a trap is now set.** `reloadFile` sets `originalContent` and clears
-      `isDirty`, so the end-of-turn refresh CANNOT produce the dirty dot in the screenshot — the refresh
-      path is out. Nothing in the app injects text into the page either: no `execCommand('insertText')`,
-      no synthetic keyboard events, no clipboard writes near the editor. That leaves Monaco's own change
-      event, which means it looks like a paste or a programmatic `executeEdits`.
-
-      **`docs/editor-buffer-corruption.md` is the procedure — read that when someone reports this.** A
-      trap is set: `reportSuspiciousEdit` in CodeEditor.tsx records any insertion over 200 characters
-      arriving while the editor is NOT focused, with the stack at that moment, into
-      `localStorage['officer:editor-buffer-trap']` (last five). It persists rather than only logging
-      because this arrives as a report hours later, when the console is long gone — the question becomes
-      "paste this key" instead of "what did you see?". Delete all of it once the cause is known.
-
-      One thing to rule out first, because it is mine and it is recent: `2b70a570` gave `<Editor>` a real
-      `path`, so models are now keyed by file URI globally rather than being per-mount `inmemory://`. Two
-      panels open on the same file now share one model. That should be an improvement, but it is a change
-      in exactly the layer that turned out to be involved.
-
-      Worth noting because it is the reason to look at all: an editor that can show content the file does
-      not contain is a correctness problem even when it never writes — the next person's instinct will be to
-      save the file to "fix" it.
-
-- [ ] **`bootstrap.ts` runs `npm install -g` for Pi on every boot.** `findPiPackageDir` checks stale
-      paths and an outdated package name, so `installPi` always fires and floods the logs with
-      `EEXIST` noise. Should detect `@earendil-works/pi-coding-agent` at the real npm prefix.
-
-- [x] **VNC mirror can orphan/duplicate x11vnc across sidecar restarts.** FIXED 2026-08-01 in the
-      Xvnc rewrite. The diagnosis was right and survived the move off mirroring: the running desktop is
-      tracked in module-level state, so a sidecar restart forgot it while the server kept running
-      orphaned, and `waitForPort` treated ANY listener on 5900 as success — so the next start reported
-      success while the browser talked to the stale process. Now `reclaimPort` frees 5900 (TERM, then
-      KILL after 2s) before spawning, and `waitForPort` also fails if the process we spawned has
-      exited, so a listener that is not ours can no longer be mistaken for a healthy start.
-
-## Infra (alpha)
-
-- [ ] **Delete `/etc/systemd/system/officer-vnc.service`.** Hand-installed unit (not in this repo)
-      that ran `vncserver :1 -geometry 1920x1080 -localhost yes -fg` with `Restart=on-failure`,
-      enabled at boot — it kept a whole parallel XFCE session alive on `:1` (283 MB, 166 tasks)
-      independently of the platform, and silently respawned it whenever the display was killed.
-      Obsolete now that the Desktop panel mirrors `:0` via x11vnc. Disabled 2026-07-15
-      (`systemctl disable --now`), but the unit file is still on disk. Nothing in the codebase
-      recreates it and nothing documents it, so delete the file rather than leave a mystery service
-      one `systemctl enable` away from returning.
-
-- [ ] **`ufw` blocks port 9010 on the LAN.** Default deny incoming; only `22/tcp`, `80/tcp`,
-      `443/tcp`, and everything on `tailscale0` are allowed — so `http://192.168.47.196:9010` is
-      unreachable from the LAN while localhost and Tailscale work.
-      Fix: `sudo ufw allow from 192.168.47.0/24 to any port 9010 proto tcp`
-
-- [ ] **Move the remaining env credentials into the secret store.** `putSecret`/`getSecret` and
-      `bun run secret:set` landed 2026-08-19, and notify now reads `apns-p8`, `apns-key-id`,
-      `apns-team-id`, `fcm-service-account` and `discord-webhook` from the store with env as a
-      fallback. Every other plugin credential is still env-only — same argument applies: bun
-      auto-loads `.env` into every PM2 process, so each one is readable from `/proc/<pid>/environ`
-      of twenty processes that have no business with it.
-
-## Backburner
-
-- [ ] **Music tagging feature** (`/music`, Mp3tag-inspired). v1 was scoped as a two-panel workspace —
-      file browser left, table right, single "Load" context-menu item flattening audio files into the
-      table. Discarded before completion; would need `GET /file-browser/flatten-audio`, a
-      `useFilesAPI.flattenAudio` method, and the Music app panel rebuilt from scratch.

deploy/2026.08.21.01.md

@@ -0,0 +1,43 @@
+# 2026.08.21.01
+
+The first release under this scheme, and the first deploy of the night's work. Everything since
+`0.1.0`, which is to say everything.
+
+## What is in it
+
+- **Two plugins extracted**: `desktop` (VNC) and `browser` (the relay, its extension and its panels),
+  with the platform losing the VNC vocabulary it should never have had.
+- **Themes regenerated** — all 22 from Omarchy, 84 tokens each, contrast-checked. The eleven that
+  shipped with 34 of an 84-token contract are replaced.
+- **Spotlight**, on `shift-space`.
+- **Chat fixes**: a turn waiting on a person is no longer killed as stalled, and an answer that goes
+  nowhere now says so.
+- **Plugin infrastructure**: `importFresh` (a reinstalled plugin was being read from the deleted one),
+  `ownerOnly` paths, dependency `scope`, extensions published unauthenticated, `plugins:update`.
+- An **Update button** in maintenance, and the **sub-agent budget guard**.
+
+## Steps, in order, on every host
+
+Same on all six — nothing here is host-specific.
+
+1. `git pull --ff-only`
+2. `bun install` — **required.** `bun.lock` changed and `sharp` was removed from the platform's
+   dependencies (it moved into atelier's `npmDependencies`). Without this the lockfile and the tree
+   disagree, and the frozen-lockfile rule turns that into a failed install later rather than now.
+3. `bun run plugins:update`
+4. `bun db:push` — **required.** `users.username` becomes `NOT NULL` and gains a case-insensitive
+   unique index.
+5. `pm2 restart officer`
+6. Then, and only for hosts that have them: `pm2 restart officer-claude-code officer-pty` — both load
+   changed sidecar code. **Not** the whole ecosystem, ever.
+
+## The one thing that could have gone wrong, and did not
+
+`db:push` refuses if any account has a null username, or if two differ only by case. **Checked on all
+six before writing this**: 12 users across the fleet, zero nulls, zero case-collisions. If a future
+host fails here, that is why, and the fix is data rather than schema.
+
+## Post-deploy check
+
+`pm2 jlist` — every restarted process `online` with a moved `restart_time`, and the platform's own
+domain answering 200. `docs/servers.md` has the domain per host.

deploy/2026.08.21.01.report.md

@@ -0,0 +1,42 @@
+# 2026.08.21.01 — deployed
+
+**6/6 hosts.** Every platform is on `eee73e77`, schema pushed, processes online and every domain
+answering 200.
+
+Rolled out by hand from `officer-dev`, one host at a time, because nothing wakes the commander yet.
+
+| Host                         | Before     | After      | install | db:push | plugins        | restarted                 | domain |
+| ---------------------------- | ---------- | ---------- | ------- | ------- | -------------- | ------------------------- | ------ |
+| `alpha`                      | `44f6c6d6` | `eee73e77` | ok      | applied | 12/12          | officer, claude-code, pty | 200    |
+| `fofos`                      | `6db26ae4` | `eee73e77` | ok      | applied | 1/1            | officer, claude-code, pty | 200    |
+| `edge-pertento-bridge`       | —          | `eee73e77` | ok      | applied | 2/2            | officer, claude-code, pty | —      |
+| `production-pertento-bridge` | —          | `eee73e77` | ok      | applied | 1/1            | officer, claude-code, pty | —      |
+| `macbookpro`                 | `2e76cabf` | `eee73e77` | ok      | applied | none installed | officer, claude-code, pty | —      |
+| `officer-dev`                | `eee73e77` | `eee73e77` | ok      | applied | 3/3            | officer, pty              | 200    |
+
+`bun install` reported no changes everywhere — the lockfile diff was `sharp` leaving, and nothing had
+it as a transitive need.
+
+## What was NOT done, and why
+
+- **`officer-claude-code` was not restarted on `officer-dev`.** That sidecar holds the session doing
+  the deploy; restarting it would have ended the conversation mid-rollout. Every other host got it.
+  **Outstanding — run it when convenient.**
+- **`fofos` did not sync its capabilities.** `git` refused the checkout as "dubious ownership" and
+  printed the usual `safe.directory` remedy. Ownership is actually correct (`pastilhas:pastilhas`,
+  running as `pastilhas`), so the cause is not what the message suggests and papering over it with a
+  config entry would hide a real question. Its one plugin updated fine. **Unexplained.**
+- **`macbookpro` has no plugins installed**, so `plugins:update` was a no-op there. Not a failure —
+  worth knowing before someone expects the browser relay on it.
+
+## Notes for the next one
+
+- **The dirty-tree check was too strict.** `git status --porcelain` counts UNTRACKED files, and
+  `fofos` was skipped on the first pass for one stray `scripts/chk.ts` that a fast-forward could never
+  touch. The rule is `--untracked-files=no`; untracked files get a note, not a skip.
+  `prompts/deploy-commander.md` says "refuse a dirty tree" and should say which kind.
+- **`macbookpro` needs `$SHELL -ic` and nothing else.** Exporting a PATH to reach `bun` broke `pm2`,
+  which is only on the interactive shell's path. Do not help it.
+- **The pre-flight was worth it.** `users.username` became `NOT NULL` with a case-insensitive unique
+  index; checked across all six first — 12 users, zero nulls, zero collisions — so `db:push` applied
+  everywhere without a data fix.

deploy/README.md

@@ -0,0 +1,17 @@
+# `deploy/`
+
+One file per release, and one report per release.
+
+```
+deploy/
+├── 2026.08.21.01.md         the plan — what to run, in order, on which hosts
+└── 2026.08.21.01.report.md  what actually happened, written by the commander
+```
+
+The plan is written by hand before the release commit. The report is written by the deploy commander
+afterwards and pushed back here.
+
+**The report's presence is what marks a release deployed.** That is the whole idempotence mechanism: a
+watcher that restarts checks for the report before acting, so it cannot roll the same release out twice.
+
+See `prompts/deploy-commander.md`.

docs/email-recall.md

@@ -0,0 +1,159 @@
+# Recall over your own correspondence
+
+**Status: DESIGN, NOT BUILT.** Sketched 2026-08-20, for the email plugin.
+
+## The goal, which is not the technology
+
+Someone is on a phone call with their ex-wife. She says something about the weekend arrangement. He has
+eight years of email with her, and he needs the fact **now** — not after a search, not after reading
+twenty messages.
+
+That is the whole requirement. Everything below is in service of it, and any part of this that does not
+make that moment faster or more accurate is decoration.
+
+The user will never write a query. They ask the agent a question in their own words, and the agent picks
+its tools. So the design question is not "what can the user search" — it is **"what does the agent have
+to work with, and which of its answers can be trusted"**.
+
+## Two mechanisms, because there are two kinds of question
+
+The examples that prompted this split cleanly, and they need different machinery:
+
+| the question                                                     | what it needs                         |
+| ---------------------------------------------------------------- | ------------------------------------- |
+| _"how many times did she ask me to break the weekend agreement"_ | **exhaustion** — every message judged |
+| _"what did she say about the school run"_                        | **retrieval** — the best few, fast    |
+
+```
+COMPILE    exhaustive, once, expensive   → counting, timelines, "show me all of them"
+RETRIEVE   cheap, approximate, always    → exploring, mid-call, "what did she say about…"
+```
+
+They are not competing designs. The agent should have both and choose.
+
+### Counting cannot be done by searching
+
+This is the load-bearing point, and it is the one most likely to be skipped.
+
+An agent asked "how many times" will search, find some, and answer with a number. That number is bounded
+by the phrasings it happened to think of. **"I found four" is indistinguishable from "there were nine"**,
+and nothing in the output signals which it was.
+
+Vector search does not fix this. Top-k also misses — it just misses differently. Ask for the top 20 and
+the 21st is silently gone.
+
+The only honest way to count is to judge every message once and store the verdict. Then counting is
+`SELECT count(*)`: exact, instant, and re-askable a hundred ways without re-reading anything.
+
+**A stored verdict is a judgement a model made about someone's divorce.** It records what it was asked,
+which message it read, and when — so the answer can be inspected, disbelieved and redone. A number with
+no provenance is worse than no number, because it will be quoted.
+
+### Retrieval is where embeddings earn their place
+
+Keyword search finds `school run`. It will never find it from _"the pickup arrangement"_ or _"when I
+collect her on Fridays"_. Over eight years, the same thing is described twenty ways and never once in the
+words you would search for.
+
+An agent closes some of that gap by itself — it knows those are synonyms and can fire several searches.
+But that is **guess-bounded**: it finds the phrasings it thought of, and cannot know the ones it did not.
+
+Two things decide it in favour of embeddings anyway:
+
+- **Latency.** Five keyword searches and twenty candidate reads is thirty seconds. On a live call that is
+  a lost moment. A vector query is milliseconds plus one read.
+- **What comes later.** WhatsApp and audio transcripts share no vocabulary, schema or structure with
+  email. Embeddings collapse all of it into one space. ASR output is noisy in a way keyword search is
+  brittle against and embeddings are not.
+
+**But we do not have WhatsApp or transcripts.** They shape exactly one decision — see the schema — and
+nothing else. Build against email.
+
+## It has to run locally
+
+Every message passes through an embedding model. Doing that through an API means uploading eight years of
+private correspondence to a third party.
+
+For this content that is not a trade-off, it is a disqualification. **Local embedding is a requirement,
+not a preference.**
+
+Today there is no ollama and no embedding code on any of these machines. **That is the real new
+dependency — not the database.**
+
+## Not a vector database
+
+`sqlite-vec` is an extension to the SQLite already in use. Same file as `emails.db`, no service, no
+sidecar, no Docker, no port, nothing to supervise or back up separately.
+
+For a plugin that already owns that file, this is **a table, not an architecture**. A separate vector
+database would add an operational surface for a corpus of 19,000 rows, which is small — vector stores
+begin earning their keep in the millions. What is being bought here is recall on paraphrase and speed on
+a phone call, not scale.
+
+## The genuinely hard part is chunking
+
+Not the vectors. **Quoted reply chains.**
+
+The same paragraph exists in forty messages of one thread. Embed naively and every query returns that
+thread forty times, and it will feel worse than what exists today.
+
+So: strip quoted history, thread properly, embed the new text of each message. `emails` already has
+`thread_id`. This is the work.
+
+Two other email-specific traps measured on the real 19,097-message store:
+
+- **Bodies are ~0.5 GB of HTML.** Embed the text, not the markup.
+- **`labels` is a comma-separated string**, and `read` is populated on 93 rows. Neither is a filter to
+  build on. See the `email-db` skill.
+
+## Schema sketch
+
+Deliberately **not** email-shaped. That is the one concession to a future that does not exist yet, and it
+costs nothing now:
+
+```
+recall_chunks
+  id            integer pk
+  source        text      -- 'email' today. 'whatsapp', 'transcript' later.
+  source_id     text      -- the message id in ITS store — no foreign key across sources
+  account       text      -- which mailbox/number this came from
+  thread_id     text      -- for dedupe and for showing context
+  author        text      -- who said it
+  said_at       timestamp
+  text          text      -- quoted history stripped
+  embedding     float[]   -- sqlite-vec
+
+recall_verdicts             -- the COMPILE half
+  id            integer pk
+  question      text      -- what the model was asked, verbatim
+  source        text
+  source_id     text
+  verdict       boolean
+  reasoning     text
+  model         text      -- which model, so a re-run is comparable
+  judged_at     timestamp
+```
+
+Everything else assumes email until something else exists.
+
+## Build order
+
+1. **Chunking and dedupe**, with no embeddings at all. Strip quotes, thread, count what is left. If this
+   is wrong nothing after it can be right, and it is testable on its own.
+2. **A local embedding model**, and a decision about which. The new dependency.
+3. **`sqlite-vec` + backfill** of the existing corpus. One-off, slow, resumable.
+4. **A retrieval tool** the agent can call, returning chunks with their message ids so it can go read the
+   original.
+5. **The compile half** — a verdict table and a way to ask "judge every message against this question".
+6. Multi-source, if and when WhatsApp or transcripts exist.
+
+Steps 1 and 5 are useful without any of the others. Step 5 in particular answers the questions that
+prompted this, and needs no vectors at all.
+
+## Open questions
+
+- **Which local model**, and how big. Quality against a laptop-or-server-sized footprint.
+- **Re-embedding.** Changing model means re-embedding everything. Store which model produced each vector.
+- **Retention and deletion.** A deleted email should lose its chunks and its verdicts. Nothing here
+  currently cascades.
+- **Who can query it.** This is the most sensitive data in the platform, and it is per-account.

docs/multi-server-push.md

@@ -0,0 +1,112 @@
+# Notifications from more than one server
+
+**Design, not built.** Written 2026-08-21, for the single-sign-on work.
+
+The good news first, because it is the part that needed checking and it holds: **one Officer app can
+receive notifications from every server you are signed into, and almost nothing has to change to allow
+it.** One field is missing. This is what it is and why it matters more than it looks.
+
+## Why it works at all
+
+An APNs auth key (`.p8`) belongs to the **developer account**, not to a machine. There is no server
+binding in it. So every Officer install can hold the same key, mint its own provider token from it, and
+push to the same app.
+
+The device token belongs to the **app**, not to a server either. One Officer app has one token, whichever
+servers it talks to.
+
+So N servers pushing to one phone needs no coordination between them. Each just needs the token, which the
+app posts when it signs in — which the multi-server manager is doing anyway.
+
+Two facts about the shared key, neither blocking:
+
+- **Apple allows 2 active auth keys per account.** Sharing one across servers is the intended pattern;
+  one key per server is not an option past two.
+- **Revoking it kills push everywhere**, with no way to tell which machine leaked it. That is the real
+  cost of copying it to ten boxes, and the reason it belongs in each one's secret store rather than
+  in `.env`.
+
+## The missing field
+
+A payload today:
+
+```json
+{
+  "aps": { "alert": { "title": "Officer" }, "thread-id": "chat:abc", "mutable-content": 1 },
+  "officer": { "c": "officer/core:chat.turn-ended", "id": 42, "mv": 1873 }
+}
+```
+
+There is no origin. With one server that is correct and minimal. With five it breaks three things, and
+only the first is obvious.
+
+**1. The deep link opens the wrong thing.** `officer-chat://session/{id}` — that id is meaningful only on
+the server that issued it. The app has no way to know which, so it picks one. Sometimes it opens nothing;
+sometimes it opens somebody else's conversation with a matching id, which is worse.
+
+**2. `mv` starts a resync fight.** `mv` is a content hash of **that server's** catalogue, and servers with
+different plugins have genuinely different catalogues. The client's rule is `mv !== version → resync`.
+With one stored catalogue and five servers, every push from server B invalidates the copy synced from
+server A, and the app resyncs forever, always against whichever pushed last.
+
+This is the one that would look like a mysterious battery and data problem rather than a bug.
+
+**3. Threading collapses across servers.** `chat:{id}` groups per conversation. Two servers' ids
+coinciding is unlikely with UUIDs and not impossible, and "these two unrelated chats are one banner" is a
+confusing failure to diagnose.
+
+## The change
+
+**A server identifier in the `officer` block**, and the app keeping **one catalogue per server** keyed on
+it:
+
+```json
+"officer": { "s": "<server-id>", "c": "officer/core:chat.turn-ended", "id": 42, "mv": 1873 }
+```
+
+`mv` then means "version of that server's catalogue", threading becomes `<server>:chat:{id}`, and the deep
+link resolves against a known server.
+
+### Where the identifier comes from is an SSO decision, not a notifications one
+
+This is the part to settle tomorrow, and it belongs to the sign-on design rather than to this file.
+
+The multi-server manager already needs a key for each server — to store its API key against, to label it
+in a switcher, to route a deep link. **Whatever that key is, notifications should adopt it.** Inventing a
+second identity here means two ids for one server, drifting the first time somebody renames a host.
+
+It has to survive a hostname change, be stable across reinstalls of the app, and not be a secret — it
+travels in a push payload, which is the one place content is deliberately withheld. A server-generated
+opaque id created at bootstrap fits; a URL does not, because URLs change.
+
+## What stays per server, correctly
+
+Worth stating so nobody tries to unify it:
+
+- **`push_devices`** — each server holds its own registrations. The same phone appears once per server.
+- **`chat_notification_prefs`** — muting a conversation is per server, because the conversation is.
+- **The catalogue** — a server's codes come from its own plugins. Two installs with different plugins
+  legitimately have different vocabularies.
+
+None of that wants a shared store. The app is what joins them, which is the same shape as the sign-on
+work: the app holds the list, each server holds its own truth.
+
+## Current state, verified 2026-08-21
+
+|                        | alpha          | officer-dev |
+| ---------------------- | -------------- | ----------- |
+| iOS devices registered | 2              | 0           |
+| APNs credentials       | partly present | absent      |
+
+So only alpha can push today, and notifications seen elsewhere are the in-app bell rather than push. That
+is not a limitation of the design — it is two things absent on the other machines.
+
+## Order of work
+
+1. **Settle the server identifier** with the SSO design. Everything else waits on it, and it is a
+   half-hour conversation rather than a build.
+2. Add `s` to the payload; keep it optional so an older app ignores it.
+3. Per-server catalogue storage in the app, keyed on `s`. **This is the one that must land before a
+   second server starts pushing**, or the resync fight above begins.
+4. Thread ids become `<server>:chat:{id}`.
+5. Copy the `.p8` into the other servers' secret stores, and have the app register its token per server.

docs/plugin-dependency-scope.md

@@ -0,0 +1,91 @@
+# Plugin dependency scope
+
+**Built 2026-08-21.** A plugin declares WHO has to be able to run each host binary, and the platform
+installs and checks accordingly.
+
+## The bug
+
+`os-deps.ts` probes a dependency by asking the owner's login shell where the binary is. That is the right
+question for most plugins and the wrong one for some, and nothing distinguished them — a per-user answer
+was reported as a fact about the machine.
+
+It matters because `confined` plugins do their work as **the member's own Linux user**, in their own home.
+A binary in the owner's `~/.local/bin` is not on that user's PATH, and reaching it means traversing the
+owner's home directory.
+
+On alpha it happened to work. `/home/pastilhas` is mode **751** — world-traversable, not readable — so an
+absolute path resolved for members. Mode 750, which is the more usual default, would have broken every
+member's binary with nothing reporting anything: the install would still say satisfied, because the
+install only ever asked the owner.
+
+Working by accident is the part worth fixing. Nobody chose 751.
+
+## The field
+
+```ts
+osDependencies: [{ binary: 'iris', reason: '…', packages: {…}, scope: 'shared' }]
+```
+
+`owner` is the default and stays right for most things — anything an `execution` plugin uses runs as the
+owner in the owner's home by definition. `shared` says every account with a Linux user must be able to run
+it, which changes both the install target and the check.
+
+An unrecognised value is a manifest error rather than a silent fallback to `owner`, because the fallback
+is the permissive one.
+
+## What changes when it is `shared`
+
+**Where it is looked for.** System directories only — `/usr/local/bin`, `/usr/bin`, `/bin`, and the sbin
+trio. Deliberately not the owner's login shell: that shell finds the copy in the owner's home and reports
+the dependency satisfied, which is the exact false answer this exists to stop.
+
+**What counts as reachable.** Two things, and checking only the first is how this hid:
+
+- the file is world-executable (`0o001` — group is not enough, members are not in the owner's group)
+- **every directory above it is traversable**, walked to the root
+
+A binary at 755 inside a home at 700 is unreachable, and `stat` on the file alone says it is fine.
+
+**Where a release binary is installed.** `/usr/local/bin`, via `sudo -n install -m 0755`. The download is
+still staged in the owner's own space — fetching straight into a root-owned directory would mean running
+the download as root, which is a bigger ask than moving the result. `-n` so a plugin install never blocks
+on an invisible password prompt.
+
+**What blocks an install.** A shared dependency that is present and working but unreachable gets its own
+state, `unreachable`, and its own refusal — checked before everything else, because no package manager
+fixes it. The binary is installed; what is wrong is where it lives. Reinstalling the package would report
+success and change nothing.
+
+## What this deliberately does not do
+
+**It does not gate execution on a grant.** A binary in `/usr/local/bin` is runnable by any account with a
+shell, whether or not they hold the plugin's permission. The kernel does not know about `role_permissions`
+and never will.
+
+That is the same boundary `ffmpeg` and everything else in `/usr/bin` already has, and it is the right one:
+the plugin's **data** is gated by the permission system, its **executable** is not. For iris it is benign —
+a member who runs it captures their own `$HOME` profile and their own sessions, which is the isolation the
+wrapper already depends on.
+
+If a binary must not merely be _reachable_ but _unusable_ without a grant, `scope` is not the mechanism.
+That needs the plugin's own surface behind the permission gate, and the binary not on anyone's PATH.
+
+## Iris
+
+The motivating case, and still the only `shared` one. `PLUGIN.md` had already recorded it as open item 3 —
+"the binary lands in the owner's `~/.local/bin`, and a confined member's agent cannot read it there" — but
+that had not been connected to the probe being owner-scoped, so the install reported success either way.
+
+`iris` and `iris-browser` are built by the sidecar rather than fetched, so declaring `scope: 'shared'`
+makes the probe honest about who can run them; moving the sidecar's build output into `/usr/local/bin` is
+the remaining half, and it is a change to the sidecar rather than to this.
+
+## Status
+
+|       |                                                                            |
+| ----- | -------------------------------------------------------------------------- |
+| Built | `scope` on a dependency, validated, defaulting to `owner`                  |
+| Built | shared probing on system paths, with a traversal walk to the root          |
+| Built | shared release binaries installed to `/usr/local/bin` via `sudo -n`        |
+| Built | an unreachable shared dependency refuses the install, naming the directory |
+| Open  | iris's sidecar still builds into `~/.local/bin` — see above                |

docs/plugin-route-authorization.md

@@ -0,0 +1,140 @@
+# Plugin route authorization
+
+**Platform half built 2026-08-21.** The gate enforces `ownerOnly`, the manifest accepts it, and the proxy
+forwards `X-Officer-Owner` / `X-Officer-Level`. **No plugin declares it yet** — jellyfin's `/_config` is
+still reachable by anyone granted the plugin, and cannot be locked until the credential question at the
+bottom of this file is answered.
+
+The question: a plugin's **settings** routes should be reachable only by the owner, even when the plugin
+itself is granted to other accounts. Jellyfin is the case that raised it — connecting a server, storing
+its admin token and provisioning accounts is not something a Member should reach, but Jellyfin as a whole
+is exactly the sort of plugin a Member should have.
+
+## The shape we agreed
+
+Authorization stays where the platform already puts it — the gate answers "may this account reach this
+plugin, and at what level" — and the plugin decides what that means **inside** its own surface. That is
+not a new principle. `src/servers/plugins/manifest.ts` already says it, in the comment refusing an
+`ownerOnly` field on a permission:
+
+> Every plugin permission is grantable, per role, at read or write … Finer visibility — whose rows a
+> member sees, what a read means for this plugin's data — is the PLUGIN's business and lives in its own
+> queries.
+
+"Which of my routes are administrative" is the same kind of question as "whose rows does a read return".
+It belongs to the plugin, because only the plugin knows that `/_config` is settings and `/_jf` is bytes.
+
+So: **the platform tells the plugin who is asking; the plugin decides what they may do.**
+
+### What gets passed, and what does not
+
+Today the proxy sends exactly one fact (`src/servers/sidecar/create-proxy.ts`):
+
+```
+X-Officer-User: <id>
+```
+
+The extension is one or two more headers alongside it. Two points about how, both load-bearing:
+
+**Pass derived facts, not the role name.** The instinct is to send `X-Officer-Role: Super Admin`. Don't.
+Roles are the platform's vocabulary and they are not frozen — `Admin`, `Member`, `Developer` today, with
+grants keyed on the role string in `role_permissions`. A plugin that branches on a role name gives every
+plugin repository an opinion about that vocabulary, and renaming a role silently changes authorization
+in code the platform does not own and cannot see.
+
+Send instead what a plugin can act on without knowing anything:
+
+```
+X-Officer-User:  <id>
+X-Officer-Owner: 1 | 0            — is this the server owner
+X-Officer-Level: none|read|write  — this account's effective level for THIS plugin's permission
+```
+
+`isOwner` is the fact that is structurally stable: user id 1, pinned by a CHECK constraint, bypassing
+every permission check. It will mean the same thing in a year. `Super Admin` might not.
+
+A plugin that genuinely needs a third tier — "Admins may also do this" — should not get it by reading a
+role. It should declare a second permission key and let the owner grant it. That keeps the answer to
+"who may do this" on the permissions page, where the owner can see and change it, rather than compiled
+into a plugin's `if`.
+
+**Nothing may be trusted from the caller.** The proxy builds a fresh header object and copies a
+three-item allowlist; it does not forward arbitrary inbound headers. That is why `X-Officer-User` is
+safe to trust, and any new header inherits the same safety **only for as long as the allowlist stays an
+allowlist**. If that loop is ever changed to a copy-everything-except, a client-supplied
+`X-Officer-Owner: 1` becomes a privilege escalation against every plugin at once.
+
+**Absent means denied.** A sidecar that does not see the headers — reached directly, an older platform,
+a bug — must resolve to no privileges rather than to the owner. Same rule as `authorize.ts`, where every
+catch returns deny.
+
+## Where I disagree, and it is one point
+
+Plugin-side enforcement has a failure mode the platform has already been bitten by, and it is worth
+naming before it happens again rather than after.
+
+`assertPermissionTotality` exists because a Member could 403 on `GET /api/tasks` and open
+`/api/tasks/pipeline/ws` with a 101 in the same minute. The lesson written down at the time was
+"**a patch does not survive the next door; refusing to boot does.**" Pure plugin-side authorization is
+that same shape: jellyfin will check, because we are about to write the check. The next plugin's author
+forgets one route, and nothing anywhere notices — no boot failure, no warning, no test.
+
+So the recommendation is not "platform enforces instead". It is **declare in the manifest, enforce in the
+proxy, and pass the facts to the sidecar as well**:
+
+Built as a field on the permission rather than at the manifest root, following `readOnlyWrites` — both
+are sub-paths written relative to the plugin's prefix with a rule attached, and one precedent is better
+than two shapes:
+
+```ts
+// manifest.ts
+permissions: [{ key: 'jellyfin', label: 'Jellyfin', description: '…', ownerOnly: ['/_config'] }],
+```
+
+- **Declared by the plugin**, because the plugin knows which of its paths are administrative.
+- **Enforced by the platform**, in the proxy, before the request reaches the sidecar — so forgetting the
+  check inside the plugin is not a hole, and the rule holds for a route added later by someone who never
+  read this file.
+- **Visible at install**, next to the permissions the owner already reviews, and greppable across every
+  plugin from one place.
+- **Still passed to the sidecar**, because the plugin's own finer rules — whose rows, which fields — are
+  genuinely its business and cannot be expressed as a path prefix.
+
+This does not contradict the `manifest.ts` comment above. That comment refuses to make a **permission**
+owner-only, because a permission is a thing the owner delegates and one nobody can delegate is a
+contradiction. A path prefix is not a grant; it is a statement that a route administers the plugin
+rather than uses it.
+
+## The frontend is a courtesy, not the lock
+
+Hiding the Settings entry in the plugin's nav for a non-owner is worth doing, and it is not security.
+Same rule as `usePermissions`, which fails open on purpose: hiding an entry is politeness, the 403 is the
+lock. Write the guard on the route first and the nav second, never only the second.
+
+## What must be settled before any of this lands
+
+**A member with no server has no Jellyfin.** Connections are stored strictly per user — every query in
+`plugins/jellyfin/db/queries.ts` filters on `eq(jellyfinServers.userId, userId)`. Lock `/_config` to the
+owner today and a Member gets a plugin that can only ever show them the connect form they are forbidden
+to submit.
+
+The resolution that fits what already exists: a non-owner resolves to the **owner's active server URL**
+authenticated with **their own token**, which provisioning already mints and stores in
+`jellyfin_accounts`. That is arguably why those tokens are minted at all — per-user identity upstream, so
+resume points, watched marks and next-up stay each person's own rather than everyone sharing the owner's.
+
+That is a change to credential resolution, not to authorization, and it is the actual prerequisite. The
+guard is a few lines; this is the work.
+
+## Status
+
+|             |                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------- |
+| Agreed      | plugin decides what a level means inside its own surface                              |
+| Agreed      | pass `isOwner` and the effective level; never the role name                           |
+| Agreed      | fail closed when the headers are absent                                               |
+| Built       | `ownerOnly` on a plugin permission, enforced by the gate before self-service and kind |
+| Built       | `X-Officer-Owner` and `X-Officer-Level`, sent when a proxy names its permission key   |
+| Built       | manifest validation — a sub-path without a leading slash is a manifest error          |
+| Blocked on  | credential resolution for non-owners, above                                           |
+| Not started | any plugin actually declaring one                                                     |

docs/servers.md

@@ -0,0 +1,62 @@
+# Servers — the running list
+
+Every machine the owner runs, how to reach it, and what of Officer is on it. Kept here so an
+orchestrator ("pull and update every platform", "restart officer everywhere", "which host is behind")
+has one place to read rather than a fact re-derived per session.
+
+**Started 2026-08-21.** Everything below was verified from `officer-dev` on that date by SSH and
+`pm2 jlist`, except where marked assumed. Commit SHAs are a snapshot and go stale immediately — they
+are here to show which checkout is live, not as a status board.
+
+## How access works
+
+All of it is over the tailnet. There is **no `~/.ssh/config`** — names resolve by MagicDNS and the
+login is key-based, so `ssh <name>` as `pastilhas` is the whole story:
+
+```bash
+ssh alpha
+ssh fofos
+```
+
+Nothing here needs a password, a jump host or a port. A host that refuses port 22 is not
+misconfigured — see "Not SSH-reachable" below.
+
+## Officer platforms
+
+| Host | Tailnet IP | Live checkout | Runs `officer` | Git remote |
+| --- | --- | --- | --- | --- |
+| `officer-dev` | 100.64.0.13 | `~/officer-dev/platform` | yes (this host) | `git@gitea.officer.dev:officerdev/platform.git` |
+| `alpha` | 100.64.0.1 | `~/officerdev/platform` | yes | `git@gitea.officer.dev:officerdev/platform.git` |
+| `fofos` | 100.64.0.17 | `~/officerdev/platform` | yes | `https://gitea.officer.dev/officerdev/platform.git` |
+| `headscale` | 100.64.0.2 | `~/dockers/officerdev/platform` | no | `ssh://git@gitea.pastilhas.dev:2222/officerdev/platform.git` |
+| `omega` | 100.64.0.3 | `~/projects/officerdev/platform` | no | none set |
+
+Three things an orchestrator has to handle, all verified and none of them cosmetic:
+
+- **The checkout path differs per host.** There is no single path to hard-code. Take it from PM2 —
+  `pm2 jlist` gives the `officer` process's `pm_cwd`, which is the checkout that is actually serving.
+- **`alpha` has a SECOND, stale checkout** at `~/dockers/officer.dev/platform` (same remote, different
+  HEAD). Pulling the wrong one updates nothing and looks like success. PM2's `pm_cwd` is the tiebreak.
+- **The remotes are not the same URL.** `fofos` pulls over HTTPS and `headscale` points at a different
+  Gitea entirely (`gitea.pastilhas.dev:2222`). An orchestrator that assumes SSH to `gitea.officer.dev`
+  breaks on two of five.
+
+`headscale` and `omega` hold a checkout but run no `officer` process (no PM2 on either). Whether those
+are retired, staging or half-installed is **not established** — ask before treating them as targets.
+
+## Other machines on the tailnet
+
+- `gateway` (100.64.0.4) — reachable over SSH as `pastilhas`, no platform checkout, no PM2.
+- **Not SSH-reachable** (port 22 refused): `edge-dns` (100.64.0.8), `edge-bridge` (100.64.0.15),
+  `gitea-bridge` (100.64.0.12), `officer-bridge` (100.64.0.5). Assumed to be service-only
+  containers rather than hosts to log into — not confirmed.
+- **Client devices, not servers:** `macbookpro`, `iphone16`, `andres-ipad`, `pixel9a`, plus other
+  people's devices in the tailnet (`diogos-ipad`, `iphone-diogo`, `iphone-bruno`,
+  `guilhermes-macbook-pro`, `macbook-pro-de-joo`).
+
+## Keeping this list true
+
+It is a running list, so it is worth saying what makes it rot: a new server, a moved checkout, a
+platform retired, or a remote changed. Re-verify with the same three commands the list was built from
+— `tailscale status`, `pm2 jlist` for the `officer` entry's `pm_cwd`, and `git -C <cwd> remote get-url
+origin`.

docs/visual-regression-plan.md

@@ -0,0 +1,149 @@
+# Nightly visual regression, on a second server
+
+**Plan, not built.** Written 2026-08-21.
+
+Capture every route of a dashboard behind a JWT login, every night, on a machine nobody is sitting at —
+and have an agent look only at what changed.
+
+The target is **not** Officer and **not** this machine: a separate box running Officer with the `iris` and
+`browser` plugins, pointed at a dashboard the owner runs elsewhere. Its login is a JWT, like Officer's.
+
+## The shape
+
+```
+target server (Officer + iris + browser)
+  │
+  ├─ cron, 03:00 ──▶ capture N routes with iris        → runs/<date>/<route>.png
+  │                  compare against runs/baseline/    → changed[]
+  │                  if changed is empty → record and stop, wake nobody
+  │                  else → open a chat turn with the changed pairs attached
+  │
+  └─ agent reads only the changed images, judges each: intended, or regression
+                     → notification with the verdict, and a link to the run
+```
+
+The expensive, fuzzy step happens only where pixels actually moved. On a quiet night the run costs a few
+seconds of Chrome and nothing else.
+
+## The hard part: a JWT lives in localStorage, and iris cannot put it there
+
+This is the thing to solve first, because everything else is plumbing.
+
+Cookie-authenticated sites work today: `iris-browser` copies `Cookies`, `Cookies-wal`, `Login Data` and
+`Local State` out of a signed-in profile, so a capture rides the same session.
+
+**A JWT dashboard is not cookie-authenticated.** The token sits in `localStorage`, which Chrome keeps in
+`Default/Local Storage/leveldb/` — a directory `iris-browser` does not copy. So a capture of a
+token-authenticated app renders the login screen, and does it silently: the screenshot is real, the page
+is real, and it is the wrong page.
+
+Three ways out, worth choosing between deliberately.
+
+### A. Copy `Local Storage/leveldb` too — smallest change, biggest blast radius
+
+One more entry in `seed_sessions`. It works, and it copies **every** site's localStorage into the
+capture profile, not just the target's. That is someone's whole browser state in a temp directory, and
+the directory is a LevelDB — copying it under a live browser can catch a compaction mid-write, which
+Cookies-the-file mostly cannot.
+
+Viable, and the least attractive of the three.
+
+### B. Log in during the capture — no profile at all
+
+Most JWT dashboards accept a token in the URL, or can be given one by a first-run page. If the target
+does, then:
+
+```
+iris 'https://dash.example.com/?token=<jwt>' -o run/home.png
+```
+
+and there is no profile, no desktop, no signed-in browser anywhere. The token comes from a service
+account minted for this, stored in Officer's secret store, and never appears in a screenshot.
+
+**This is the recommended path** when the target supports it. It removes desktop from the picture
+entirely, which removes the only reason that plugin was in this plan.
+
+### C. Seed via the relay, capture via iris
+
+Pair a browser once, use the relay to `evaluate` the token into `localStorage`, and let iris capture from
+that profile. Works without changing either plugin, and needs a browser paired at 3am — which is exactly
+the constraint iris exists to avoid.
+
+Keep as the fallback for a target that supports neither a token URL nor a clean profile copy.
+
+## What to capture
+
+**Routes come from a list the repo owns**, not from crawling. A crawler finds what exists; a list says
+what is supposed to exist, and a route disappearing is the regression you most want caught.
+
+```jsonc
+// routes.json, in the dashboard's own repository
+[
+  { "path": "/", "name": "home" },
+  { "path": "/reports", "name": "reports", "waitFor": "[data-ready]" },
+  { "path": "/reports/42", "name": "report-detail" },
+]
+```
+
+`waitFor` maps to iris's `--wait-for`, which is what stops a spinner being the thing under test.
+
+Two viewports — one desktop, one phone — doubles the run and catches the majority of layout breakage.
+`--jobs` renders them in parallel.
+
+## Diffing, before any agent is involved
+
+Compare each capture with the same route's baseline. A pixel count, a threshold, nothing clever:
+
+- **identical** → nothing happens
+- **differs under threshold** (antialiasing, a clock, a random avatar) → nothing happens, but log it
+- **differs over threshold** → into `changed[]`
+
+The threshold exists because something on the page always moves. **Mask what is known to move** rather
+than raising the threshold until it passes — a timestamp region is a rectangle to blank before comparing,
+not a reason to accept 3% drift everywhere.
+
+Officer has no image diff today. `sharp` is already a plugin dependency (atelier) and can do it; a raw
+pixel loop over two decoded buffers is about thirty lines and needs nothing.
+
+**Baselines are promoted, never automatic.** A run does not overwrite the baseline because it succeeded —
+it does so when someone says "yes, that is the new correct". Otherwise a regression becomes the baseline
+on night two and disappears.
+
+## What reaches the agent
+
+Only changed pairs, and each one as **two images plus the route name**: baseline and current. The
+question asked is narrow, because a broad one gets a broad answer:
+
+> This is `/reports` before and after. Describe what changed, then say whether it is a layout break, a
+> content change, or noise. If you cannot tell, say so.
+
+"If you cannot tell, say so" earns its place — a model asked to judge will judge, and a confident wrong
+verdict on night four is how the whole thing stops being trusted.
+
+The verdicts land in a notification (`officer-notify` is already core) with a count and a link, not the
+images. Nobody wants twenty pictures on a phone at 3am.
+
+## What does not exist yet
+
+In rough order of how much they block:
+
+1. **`--wait-for` against a JWT app** — solve auth first (§B), everything else is downstream.
+2. **An image diff.** Thirty lines, or `sharp`.
+3. **A scheduler.** Officer's queue has retries, not schedules — `scheduleRetry` is the only timed thing
+   in it. So this is system cron calling a script, or a `setInterval` in a plugin sidecar the way the
+   nudger does it. Cron is the honest answer for something that runs once a night.
+4. **A place for runs and baselines.** `$OFFICER_ROOT/data/visual-regression/{baseline,runs}/` — outside
+   any plugin directory, because a plugin update replaces that.
+5. **Whatever holds this.** A plugin of its own on that server, with `routes.json` as its config and a
+   panel showing the last run. It is not iris and it is not the relay; it is the thing that uses them.
+
+## What this deliberately is not
+
+**Not a test runner.** It proves a page renders and looks like it did yesterday. It cannot tell you a
+button is wired to the wrong handler, and it should not be stretched to try — that is a real test suite,
+and the two answer different questions.
+
+**Not a crawler.** See routes, above.
+
+**Not the browser relay.** The relay drives a live browser someone is signed into; this runs when nobody
+is. They overlap only in that both produce screenshots. If §B holds, the relay has no role in this at all.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "officer",
-  "version": "0.1.0",
+  "version": "2026.08.21.01",
   "private": true,
   "type": "module",
   "workspaces": [
@@ -11,6 +11,10 @@
     "preinstall": "node -e \"var v = +process.versions.node.split('.')[0]; if (v < 22) { console.error('Node 22 or newer required (got ' + process.versions.node + '). Run: nvm use 22'); process.exit(1); }\"",
     "gen:index": "bun run ./scripts/gen-index.ts",
     "fix:env": "bun run ./scripts/fix-env.ts",
+    "todo:index": "bun run ./scripts/todo-index.ts",
+    "plugins:update": "bun run ./scripts/update-plugins.ts",
+    "nudge": "bun run --env-file=.env ./scripts/nudge-agent.ts",
+    "doctor": "bun run --env-file=.env ./scripts/doctor.ts",
     "secret:set": "bun run --env-file=.env ./scripts/secret-set.ts",
     "notify:test": "bun run --env-file=.env ./scripts/notify-test.ts",
     "gen:ecosystem": "bun run --env-file=.env ./scripts/gen-ecosystem.ts",

plugins/EXTRACT-ATELIER-PROMPT.md

@@ -0,0 +1,181 @@
+# Kickoff prompt: extract Atelier into a plugin
+
+Written 2026-08-20 for an **unattended overnight run**. That changes two things from
+`EXTRACT-A-PLUGIN-PROMPT.md`, which assumes the owner is awake:
+
+- **It does not say "ask and wait".** Nobody is there. Decisions that would normally be questions are
+  pre-made below, with reasoning, so the run does not stall on them.
+- **It assumes you may be restarted.** Commit after every task, so whoever picks this up — including you,
+  an hour later, with no memory of it — finds a clean tree and a readable history.
+
+Paste everything below the line into a fresh agent.
+
+---
+
+You are extracting **Atelier** out of `~/officer-dev/dockers/officer-atelier` and into an Officer plugin,
+the way `music`, `offscale` and `gitea` were extracted before it.
+
+**Work in a git worktree, not the main checkout.** Another agent is watching
+`/home/pastilhas/officer-dev/platform` and pulling into it as you push. Two processes in one working tree
+is how work gets lost — on 2026-08-20 it nearly did.
+
+```
+git -C /home/pastilhas/officer-dev/platform worktree add /home/pastilhas/officer-dev/atelier-work -b atelier-plugin
+```
+
+Everything below happens in `~/officer-dev/atelier-work`.
+
+**Push every commit straight to master**, from the worktree:
+
+```
+git push origin HEAD:master
+```
+
+The branch is only there to keep your files out of the other checkout. Master is what is being reviewed.
+Push after every task — a reviewer reading five small commits can tell you what went wrong on the second
+one; nobody can do that with one commit at the end.
+
+**Your final commit message must contain `ATELIER-COMPLETE` on its own line**, and no earlier commit may
+contain that string. It is the signal that the run is finished and the review can start. Do not use it to
+mean "this part is done".
+
+## Read first, in this order
+
+1. **`plugins/EXTRACTING-A-PLUGIN.md`** — the runbook and the authority. Read "What changed on
+   2026-08-16" carefully; it contradicts an earlier instruction in the same file, deliberately.
+2. **`plugins/example/README.md`** — what a plugin is, as conventions.
+3. **`src/servers/plugins/`** — `discover.ts`, `manifest.ts`, `mount.ts`, `install.ts`, `ecosystem.ts`.
+   Where this prompt and that code disagree, **the code is right**.
+4. **`CLAUDE.md`** — house rules, the permission model, and why `assertPermissionTotality` refuses to boot.
+5. **`docs/secret-store.md`** — Atelier holds an OpenAI key.
+6. **`src/workspaces/officerdev/APP_CONVENTIONS.md`** and `HOOK_CONVENTIONS.md` — you are writing panels.
+
+## What Atelier is
+
+Image generation as a service: a provider-shaped API over OpenAI's image endpoints, storing what it makes
+so every image has a permanent URL. Bun · Hono · Postgres/Drizzle · htmx with Hono JSX · a React SPA.
+
+```
+84 ts/tsx files, ~6,400 lines
+tables      collections, provider_settings        (its own `atelier` database)
+routes      /generations, /generations/:id, /edits, /adapters,
+            /:id/items, /:id/items/:generationId, mask
+env         BUN_PORT, PUBLIC_URL, POSTGRES_URL, ATELIER_DATA_DIR,
+            OPENAI_API_KEY, ATELIER_MAX_CONCURRENCY
+runs as     pm2 `officer-atelier`, cwd ~/officer-dev/dockers/officer-atelier
+```
+
+It is a **sidecar** plugin for one reason that survives the UI moving into Officer: generation is
+long-running, capped by `ATELIER_MAX_CONCURRENCY`, and holds a credential the platform must not. The UI
+is Officer's; the work is the sidecar's.
+
+## Decisions already made — do not re-open these
+
+Each of these would normally be a question. They are answered so you can keep moving. If you find
+evidence that one is wrong, **write it in `BLOCKERS.md`, follow the decision anyway, and carry on** — a
+half-applied decision is worse than a wrong one consistently applied.
+
+**1. The UI is PORTED into Officer. No proxy, no iframe, no sidecar-served UI.** Atelier was a separate
+server because that was the quick answer at the time; this extraction is what undoes that. It becomes part
+of Officer, not something Officer frames.
+
+It is smaller than the repository suggests:
+
+```
+src/apps/frontend      1,736 lines / 25 files
+  6 of those           components/ui/*  — shadcn Officer ALREADY HAS. Delete, import from @/components/ui.
+  real work            Generate · Gallery (+ Lightbox) · Collections · Providers   ≈1,200 lines
+src/apps/web           the htmx half — 8 files, DELETED, not ported
+```
+
+So: three panel apps — **Generate**, **Gallery**, **Collections** — under
+`plugins/atelier/web/`, each exporting `appRegistryMetas`, with a `layout.ts` composing them. Follow the
+frontend route conventions in `CLAUDE.md`: selection lives in the URL, rows are real links, no
+`usePanelChannel` for "which thing is open".
+
+The fourth feature, **Providers**, is not a panel — see the next decision.
+
+**2. Providers become Officer settings, with more than one.** `features/Providers/` is a settings screen,
+and Officer has a settings surface already. It moves there rather than becoming a panel.
+
+`src/servers/providers/` is already adapter-shaped — `types.ts`, `openai.ts`, `credentials.ts`, an
+`index.ts` that dispatches. Keep that shape and keep the seam: today OpenAI is the only adapter, and the
+point of moving the settings is that a second one is a new file rather than a new screen. **Do not add a
+second provider in this run** — leave the shape able to take one and say so in `PLUGIN.md`.
+
+**3. The database: check the rows, then decide.** Atelier uses a separate `atelier` Postgres database,
+deliberately — `src/databases/atelier_db/drizzle.config.ts` says why. Plugin tables normally live in
+`officer_db` with a prefix.
+
+- Count the rows in `collections` and `provider_settings` first.
+- **If both are empty**, fold them into `officer_db` as `atelier_collections` and
+  `atelier_provider_settings`, following `plugins/*/db/schema.ts`. Two tables do not earn a second
+  database.
+- **If either has rows**, keep the separate database for now and record the migration as a follow-up in
+  `BLOCKERS.md`. Losing someone's generated images to a schema decision at 4am is not a trade worth making.
+
+**4. Artefacts: `$OFFICER_ROOT/data/atelier/`.** Generated images are files, and `ATELIER_DATA_DIR`
+currently points wherever its `.env` says. A plugin directory is a git clone that an update replaces, so
+artefacts kept there vanish on upgrade with nothing logging it. `plugins/kiosk/artefacts.ts` has the same
+problem solved and the comment explaining it.
+
+**5. `OPENAI_API_KEY` goes in the secret store**, not `.env`. `putSecret`/`getSecret` landed 2026-08-19;
+`bun run secret:set atelier-openai-key` puts it there. Read with `getSecret`, **never `getKey`** — `getKey`
+mints a random value for an absent purpose, which for a foreign credential means silently authenticating
+with a fake. Fall back to env when the store has nothing, so an install that predates this keeps working.
+
+**6. One permission, `atelier`, `kind: 'app'`.** Image generation is not `execution` — it does not run as
+the owner's OS user in the owner's home.
+
+## How to work
+
+**Map before you move.** The first task is not a file move. Find every line in the platform that names
+atelier, and every import pointing INTO it. A plugin may import platform code (`@@/…`); the reverse cannot
+happen. Report what you find before moving anything.
+
+**Commit after every task, and push.** You may be restarted at any point by a scheduler that has no idea
+what you were doing. A clean tree and a commit message are how the next attempt — possibly you — knows
+where it is. Commit messages: simple lowercase, no prefixes.
+
+**Do not restart the platform.** `pm2 restart officer` breaks the owner's chat session. Write the command
+down instead; they will run it.
+
+**Do not `git add -A`.** Add the paths you touched. This has caused two commits to swallow another
+agent's work in one day.
+
+**Format only what you touched** — `bunx prettier --write <paths>`, never `bun format`.
+
+**`bunx tsgo` must be clean** before every commit. Not `tsc`.
+
+## When you get stuck
+
+Write it in `BLOCKERS.md` at the worktree root — what you were doing, what stopped you, what you did
+instead, and whether it is reversible. Then **move to the next task**. Do not wait, do not invent a
+workaround that changes behaviour without saying so, and do not stop the run.
+
+If invented content ends up anywhere durable — copy, defaults, seed data — mark it `[placeholder]` so it
+can be found later with a grep.
+
+## Done means
+
+- `plugins/atelier/` with `manifest.ts`, `api/router.ts`, `sidecar/index.ts`, `web/panels.ts`,
+  `web/layout.ts`, `db/`, `assets/icon.png`, `assets/splash.png`, and its own git repository.
+- It installs from the Marketplace onto a machine that has never had it, and the panel renders.
+- `bunx tsgo` clean, `bun test` passing.
+- A `PLUGIN.md` in the plugin recording what moved, what did not, and why — the way `music` and `offscale`
+  did. This is the part that is worth most in three months.
+- `BLOCKERS.md` listing every decision you made without being able to ask.
+
+## What you may NOT do
+
+- No unauthenticated routes. A plugin cannot serve one; `UNPROTECTED_API_PREFIXES` is hardcoded in the
+  platform. If Atelier needs one, that is a blocker, not something to work around. (`plugins/kiosk`
+  is stuck on exactly this — read its README before concluding you have found a way.)
+- **Generated images are served through an authenticated route**, like every other plugin artefact. Every
+  image having "a permanent URL" was true of a standalone server with its own `PUBLIC_URL`; inside Officer
+  the URL is behind the session. If something needs an image without one — an `<img>` in an email, a
+  share link — that is a blocker to write down, not a route to open. See the image-rendering affordance
+  in `capabilities/affordances/officer/core/` for why an `<img>` cannot carry a token.
+- No changes to `src/servers/plugins/` to make Atelier fit. If the contract does not accommodate it, that
+  is a finding worth more than the workaround.
+- No second agent, no second worktree, no background job that writes to this tree.

plugins/EXTRACTING-A-PLUGIN.md

@@ -78,9 +78,11 @@ Music added the field; see its PLUGIN.md for what it is guarding against.
 **Nothing may branch on provenance** except `mountPrefix()`. First-party and third-party differing
 anywhere else means two systems, and only one gets tested.
 
-**Uninstall never destroys data.** The generated schema barrel follows plugin **directories**, not the
+**Only an explicit tick destroys data.** The generated schema barrel follows plugin **directories**, not
-install table — `db:push` drops what it cannot see, so following installs would delete a plugin's tables
+the install table — `db:push` drops what it cannot see, so following installs would delete a plugin's
-on uninstall. Only deleting a plugin's source can lose its data.
+tables the moment it was stopped. Deleting a plugin removes its directory, and the confirmation's
+"also delete all its data" checkbox is the one thing that drops its tables. Unticked, the rows outlive
+the plugin and show up in the orphan list on the same screen.
 
 ---
 
@@ -125,9 +127,9 @@ Then through `/plugins`, watching PM2 and the browser at each step:
 | permissions page                | its permission is listed, read/write/none                   |
 | disable                         | route 404s, sidecar stops, **tables and rows survive**      |
 | enable                          | comes back                                                  |
-| uninstall                       | route gone, `pm2 list` loses it, **data still there**       |
+| delete, checkbox unticked       | route gone, `pm2 list` loses it, directory gone, **data still there** |
-| `bun db:push` while uninstalled | **do not run this — see "What changed on 2026-08-16"**      |
+| install again                   | fresh clone, and it finds those rows                        |
-| install again                   | identical to the first install                              |
+| delete, checkbox ticked         | tables dropped too — a machine that never had it            |
 
 A normal refresh is enough; the shell is `no-store`. When the log's last line appears, the bundle exists.
 
@@ -220,15 +222,21 @@ no terminal it applies NOTHING and exits 0, so an install reports success and th
 query with 42P01. `--force` would be worse if it worked: the destructive statements are `drop table` for
 every plugin whose directory is absent.
 
-So: the row in the verification table that says to run `bun db:push` while uninstalled is struck out. The
+So: the row in the verification table that said to run `bun db:push` while stopped is gone. The property
-property it was checking — uninstall does not destroy data — is now checked by reinstalling and finding
+it was checking — stopping a plugin does not destroy data — is now checked by deleting it with the
-your rows still there.
+checkbox unticked, installing again, and finding your rows still there.
 
-**Use `purge` to test the install twice.** Uninstall deliberately keeps the directory and the tables, so a
+**Delete WITH the checkbox to test the install twice.** Anything less is not a fresh install: the
-second install is not a fresh one: the marketplace hides a plugin whose directory exists, and the tables
+marketplace hides a plugin whose directory exists, and tables that are already there make `db:push` a
-are already there. The Marketplace screen has "Delete <plugin> and all its data" — it drops the tables,
+no-op, so a broken schema stays broken and passes. Ticked, it drops the tables, deletes the directory and
-deletes the directory and regenerates the barrel, and afterwards the plugin installs from the catalogue
+regenerates the barrel — and afterwards the plugin installs from the catalogue exactly as a stranger's
-exactly as a stranger's machine would. **That is the only honest test of an install.**
+machine would. **That is the only honest test of an install.**
+
+**Uninstall was removed on 2026-08-21.** It sat between disable and delete, keeping the directory and the
+data, and the screen could not show the difference: an uninstalled plugin stayed in the list under a
+heading that said "Installed" while its directory silently decided what the next install would run. That
+is not hypothetical — it is how a jellyfin install on alpha re-applied a checkout from two days earlier,
+reporting success at every step. The verbs are now enable, disable and delete.
 
 **The install now verifies its own tables.** After the push it asks Postgres whether each declared table
 exists and fails the install naming what is missing. If your extraction reports "schema push reported

plugins/USER_PROVISIONING.md

@@ -0,0 +1,240 @@
+# Provisioning a user in a plugin's upstream service
+
+> **Handing this to a fresh agent?** Everything below was verified against a live instance on
+> 2026-08-19 — every status code, every error body. Trust it over the upstream's own docs, which
+> lag. Re-verify with the probe sequence at the end if the upstream has been upgraded since.
+
+Officer creates the account; the upstream service owns it. This is the contract for doing that
+safely, written from the **`photos` plugin** (Immich) as the first worked example. The shape
+generalises: authenticate as an admin, check-then-create, verify the result, hand over a one-time
+password.
+
+**This directory holds documentation, not plugins.** The plugin itself lives in
+[`plugins/photos`](https://gitea.officer.dev/plugins/photos).
+
+---
+
+## The four rules
+
+1. **Never hardcode the admin credential.** Read it from the environment or the platform's
+   credential store, and never log it. Docs and repos get shared; credentials must not travel
+   with them.
+2. **Check before you create.** None of these APIs upsert. A second call with the same email is
+   an error, not a no-op — so provisioning must be re-runnable by listing first.
+3. **Force a password change.** Generate a strong random password, mark it as
+   must-change, and treat it as a one-time handover value. It stops being a secret the moment
+   the user logs in.
+4. **Verify by logging in.** A `201` means the row was written, not that the account works. Do a
+   real login before reporting success, so failures surface at provisioning time rather than when
+   the person first tries to use it.
+
+---
+
+## Worked example — Immich (`photos` plugin)
+
+Verified against **Immich 3.1.0**.
+
+| | |
+|---|---|
+| API root | `<base>/api` — e.g. `http://127.0.0.1:2283/api` |
+| Auth | header `x-api-key: <ADMIN_API_KEY>` |
+| Admin routes | `/api/admin/*` — reject non-admin keys with `401` |
+
+Immich stores API keys **SHA-256 hashed**, so a lost key can only be replaced, never recovered.
+Mint one in the UI → Account Settings → API Keys.
+
+### 1. Check (idempotency guard)
+
+```http
+GET /api/admin/users
+x-api-key: <ADMIN_API_KEY>
+```
+→ `200`, JSON array. If the target email is present, stop — already provisioned.
+
+### 2. Create
+
+```http
+POST /api/admin/users
+x-api-key: <ADMIN_API_KEY>
+Content-Type: application/json
+
+{
+  "email": "person@example.com",
+  "password": "<generated>",
+  "name": "Full Name",
+  "shouldChangePassword": true
+}
+```
+
+**Required:** `email`, `password`, `name`.
+
+| Optional field | Type | Notes |
+|---|---|---|
+| `shouldChangePassword` | bool | `true` ⇒ forced reset at first login. Always send it. |
+| `quotaSizeInBytes` | int | e.g. `1073741824` = 1 GiB. Omit for unlimited. |
+| `storageLabel` | string | Folder name used by the storage template. |
+| `notify` | bool | Emails the new user. Requires SMTP configured upstream. |
+
+→ **`201 Created`**, body carries the new `id`:
+
+```json
+{ "id": "70ee4cd2-…", "email": "person@example.com", "name": "Full Name",
+  "isAdmin": false, "shouldChangePassword": true, "quotaSizeInBytes": null }
+```
+
+`isAdmin` cannot be set at creation — promote afterwards via the admin update endpoint.
+Names are full Unicode (`Bruno Conceição`); send UTF-8, no escaping.
+
+### 3. Verify
+
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{ "email": "person@example.com", "password": "<generated>" }
+```
+→ `200` with `{"name":…,"userEmail":…,"isAdmin":false,"shouldChangePassword":true}`.
+No API key — this is the ordinary user login path, which is exactly why it proves the account works.
+
+### Errors (observed, not guessed)
+
+| Condition | Status | Body |
+|---|---|---|
+| Email already exists | `400` | `{"message":"Email is not available"}` |
+| Missing `password` / `name` | `400` | `{"message":"Validation failed","errors":[{"path":["password"],…}]}` |
+| Bad or missing API key | `401` | — |
+
+### Deprovisioning
+
+```http
+DELETE /api/admin/users/{id}
+Content-Type: application/json
+
+{ "force": true }
+```
+→ `200` with `{"status":"removing","deletedAt":"…"}`. Soft-delete; `force` skips the grace period.
+
+---
+
+## Worked example — Jellyfin (`jellyfin` plugin)
+
+Same four rules, **different shape**. Read this section as: the route surface and auth model are
+**verified** against Jellyfin **10.11.11**; the request bodies are from working knowledge and
+marked as such — confirm them with the probe recipe below before relying on them in code.
+
+### How it differs from Immich — read this first
+
+| | Immich | Jellyfin |
+|---|---|---|
+| Auth header | `x-api-key: <key>` | `Authorization: MediaBrowser Token="<key>"` |
+| Create + configure | one call | **two or three** — create, then policy, sometimes password |
+| Force password change | `shouldChangePassword: true` | **no equivalent** — see below |
+| Scope of an account | one server | **per instance** — see below |
+
+Two consequences that bite:
+
+1. **There is no "must change password" flag.** Rule 3 cannot be enforced by the server.
+   **Decision for this deployment (2026-08-20): set a generated password at creation and tell the
+   user to change it.** Do *not* use the blank-password alternative — Jellyfin permits it, but the
+   account is then open to anyone who can reach the port until the user sets one.
+   So for Jellyfin, rule 3 becomes: still generate a strong unique password, still treat it as a
+   handover value, but the change is advisory rather than forced — which means **never reuse a
+   generated password across users or instances**, since it may stay valid indefinitely.
+2. **Users are per-instance, not global.** This deployment runs **four** independent Jellyfin
+   servers, each with its own user database and its own API keys:
+
+   | Instance | Port | Server name |
+   |---|---|---|
+   | `jellyfin` | 9301 | Jelly |
+   | `jellyfin_music` | 9302 | Albums |
+   | `jellyfin_dj_sets` | 9303 | DJ_Sets |
+   | `jellyfin_diogo` | 9399 | JellyDiogo |
+
+   Provisioning "a Jellyfin user" therefore means looping over whichever instances that person
+   should reach, with a **separate API key per instance**. There is no cross-server account.
+
+### Getting an API key
+
+Unlike Immich, Jellyfin has **no admin-token bootstrap from nothing** — creating a key requires
+an already-authenticated session. Two routes:
+
+- **UI:** Dashboard → API Keys → `+`. Simplest, and the one to use for first setup.
+- **API:** `POST /Auth/Keys?App=<name>` (verified: route exists, `401` unauthenticated), using a
+  token obtained from `POST /Users/AuthenticateByName` with an admin username/password
+  (verified: route exists; returns `415` if you omit the JSON content type).
+
+`GET /Auth/Keys` lists them (verified: exists, `401` unauthenticated). Keys are stored in
+`config/data/jellyfin.db`, table `ApiKeys`. **This deployment currently has zero API keys** — one
+must be created before any of the flow below will work.
+
+### The flow
+
+```http
+GET /Users
+Authorization: MediaBrowser Token="<API_KEY>"
+```
+→ verified: exists, `401` without auth. Use it as the **check** step (rule 2) — match on `Name`.
+
+```http
+POST /Users/New
+Authorization: MediaBrowser Token="<API_KEY>"
+Content-Type: application/json
+
+{ "Name": "Full Name", "Password": "<generated>" }
+```
+→ verified: route exists (`401` unauthenticated). Body shape from working knowledge. Returns the
+created user object including its `Id` (a GUID), which the next calls need.
+
+Then, as needed:
+
+| Purpose | Endpoint | Notes |
+|---|---|---|
+| Library access, admin rights, parental rating | `POST /Users/{id}/Policy` | Full policy object; **send the whole thing**, it replaces rather than merges. This is where `IsAdministrator` and `EnabledFolders` live. |
+| Set/replace password | `POST /Users/{id}/Password` | Needed if you created the user without one. |
+| Delete | `DELETE /Users/{id}` | Hard delete — no soft-delete/grace period, unlike Immich. |
+
+**Verify (rule 4)** with a real login rather than trusting the create:
+
+```http
+POST /Users/AuthenticateByName
+Content-Type: application/json
+
+{ "Username": "Full Name", "Pw": "<generated>" }
+```
+→ returns an `AccessToken` and the `User` object on success. Note the field is `Pw`, not
+`Password`, and Jellyfin authenticates by **username**, not email — Jellyfin has no concept of an
+email login.
+
+### A public endpoint worth knowing
+
+`GET /Users/Public` needs **no authentication at all** (verified: `200`). It lists users flagged
+as visible on the login screen. On this deployment it returns `[]` on all four instances, so
+nothing is currently exposed — but if you provision users, be aware that leaving them
+login-screen-visible publishes their names to anyone who can reach the port.
+
+### Probe recipe (Jellyfin)
+
+Same spirit as the Immich one, but you need a key first, and there is no soft-delete — so probe on
+a **non-production instance** or be prepared to hard-delete:
+
+1. `GET /Users` with the key → `200` and an array. Wrong key → `401`.
+2. `POST /Users/New` with a throwaway name → expect the created object; keep the `Id`.
+3. Repeat the identical call → observe the duplicate-name behaviour and **record the exact status
+   and body here**, since it is the guard rule 2 depends on.
+4. `POST /Users/AuthenticateByName` with the throwaway credentials → expect an `AccessToken`.
+5. `DELETE /Users/{id}` → then `GET /Users` to confirm it is gone.
+
+---
+
+## Re-verifying after an upstream upgrade
+
+Cheap and non-destructive — create a probe user on an unroutable domain, exercise it, delete it:
+
+1. `POST /api/admin/users` with `probe-delete-me@example.invalid` → expect `201`, keep the `id`.
+2. Repeat the identical call → expect the duplicate-email `400`.
+3. `POST` with `password`/`name` omitted → expect the validation `400`.
+4. `POST` with a bogus key → expect `401`.
+5. `DELETE /api/admin/users/{id}` with `{"force":true}` → expect `200`, then `GET` to confirm it's gone.
+
+Use `.invalid` (RFC 2606 — guaranteed never to resolve) so a stray notification email can never
+reach a real person.

prompts/deploy-commander.md

@@ -0,0 +1,113 @@
+# Deploy commander
+
+Start a commander with this. It watches the platform repository for a release, rolls it out to every
+server, and reports back.
+
+**It never decides what a deploy needs.** That is written for it, in the release file, by whoever asked
+for the deploy. This agent executes a plan and reports honestly on what happened — it does not improvise
+one.
+
+---
+
+## What wakes you
+
+You are not a loop. Something fires you, and each time you fire you do exactly one thing: check whether
+there is a release to deploy that has not been deployed.
+
+```bash
+cd ~/officer-dev/platform && git fetch --quiet origin HEAD
+git log --oneline HEAD..FETCH_HEAD | grep DEPLOY_NOW
+```
+
+- **Nothing matching** → say "no release pending" and stop. Do not pull, do not touch a server.
+- **A commit whose subject begins `DEPLOY_NOW`** → that is the release. Continue.
+
+`DEPLOY_NOW` must be at the **start of the subject line**, not merely present. This document contains the
+word repeatedly and must never trigger a deploy; so must any commit that discusses one.
+
+**Already deployed?** A release is deployed when `deploy/<version>.report.md` exists on `origin`. Check
+before acting. A watcher that restarts must not redeploy, and this is the only thing standing between it
+and doing so.
+
+---
+
+## The release
+
+The triggering commit carries everything:
+
+- `package.json` — `version` bumped to `yyyy.mm.dd.NN` (`2026.08.21.01`), the mobile apps' scheme. `NN`
+  increments for a second deploy on the same day.
+- `deploy/<version>.md` — **the plan**. What to run, in order, and on which hosts. Written by hand.
+
+If the plan file is missing, **stop and say so**. A release with no plan is not a release you can guess
+at, and guessing is how a database gets a schema it was not ready for.
+
+---
+
+## The servers
+
+**Read `docs/servers.md`.** Do not take a list of hosts from this file — there is deliberately none here,
+because a copy rots the day a server moves and the copy is always the one somebody trusts.
+
+That document holds every machine, its tailnet name, its checkout and whether a platform runs on it. Read
+it at the start of every deploy, and treat the hosts marked as having no platform as out of scope.
+
+Four things that will catch you out, all verified rather than assumed:
+
+- **Never hard-code the path.** Take it from PM2: the `officer` process's `pm_cwd`. `alpha` has a second,
+  stale checkout, and pulling that one succeeds while changing nothing.
+- **`pm2` is not on a non-interactive PATH.** It is installed under nvm, and nvm lives in `.zshrc`, which
+  a _login_ shell does not read. Use `ssh <host> '$SHELL -ic "pm2 jlist"'`. `-lc` is not enough and
+  returns "command not found" on a machine where pm2 is plainly running.
+- **The git remotes differ.** `fofos` pulls over HTTPS; others over SSH. Never assume a URL — just
+  `git pull --ff-only` in place.
+- **`macbookpro` is macOS and is a laptop.** It may be asleep. Unreachable is a SKIP with a note, not a
+  failure of the deploy.
+
+---
+
+## Rolling it out
+
+Per host, in this order. Do them **one host at a time** and keep a record as you go — a report you
+assemble at the end from memory is a report that will be wrong about the host that failed.
+
+1. **Refuse a dirty tree.** `git status --porcelain` — if anything is uncommitted, skip this host and say
+   so. Never discard someone's work to ship a release.
+2. `git pull --ff-only`. A non-fast-forward means that checkout has diverged: skip and report.
+3. **Update the plugins.** `bun run plugins:update`. Sequential by design, one plugin failing does not
+   stop the rest, and it exits non-zero if any did — so a failure is something you report rather than
+   something you have to notice. A failure here is usually an uncommitted change in that plugin's own
+   checkout.
+4. **Run the plan's commands** for that host, in the order given. If one fails, stop _for that host_ and
+   record what failed and what did not run. Do not continue past a failed `bun install` or `db:push`.
+5. **Restart what the plan names**, and nothing else. Never `pm2 restart ecosystem.config.cjs` — it
+   bounces every sidecar including the vault.
+6. **Check it came back.** `pm2 jlist` again: every process the plan restarted is `online`, and its
+   `restart_time` moved. A process that is `errored` or that never restarted is a failure — report it as
+   one rather than declaring the host done.
+
+If a host fails, **continue to the next one**. A half-rolled-out release that is honestly reported beats
+one that stopped in the middle and said nothing about the four hosts it never reached.
+
+---
+
+## The report
+
+Commit `deploy/<version>.report.md` to the platform repository and push it. Subject line: the version and
+the outcome, **without the code word** — a report is not a release, and a report that triggers a deploy
+would loop forever.
+
+Per host: what its HEAD was before and after, which steps ran, which were skipped and why, which
+processes restarted, and whether they came back. Then one line at the top saying how many hosts
+succeeded out of how many.
+
+Say what you did not do. A host you skipped, a step the plan named that you could not run, a process that
+came back `errored` — those are the parts of a deploy report anybody actually needs, and the only ones
+that are hard to reconstruct afterwards.
+
+---
+
+## What is missing, as of writing
+
+**Nothing wakes you yet.** A watcher, a cron entry or a repeating prompt has to exist and does not. Until
+then this runs when a person starts it.

public/officer-logo.svg

@@ -1,4 +1,4 @@
-<svg width="1200" height="240" viewBox="-20 40 1200 260" xmlns="http://www.w3.org/2000/svg">
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="300" viewBox="60 40 900 300">
   <defs>
     <filter id="shadow3d-main-officer">
       <feOffset dx="6" dy="6" in="SourceGraphic" result="offset1"/>
@@ -25,25 +25,26 @@
     </pattern>
 
     <mask id="textMaskOfficer">
-      <text x="580" y="220" text-anchor="middle" class="officer-text-main" fill="white">o<tspan dx="6" dy="30" letter-spacing="14">ff</tspan><tspan dx="-2" dy="-30">icer.dev</tspan></text>
+      <text x="510" y="220" text-anchor="middle" class="officer-text-main" fill="white">Of<tspan dx="16">f</tspan><tspan dx="10">i</tspan><tspan dx="10">c</tspan><tspan dx="10">e</tspan><tspan dx="10">r</tspan></text>
     </mask>
 
     <style>
       .officer-text-main {
-        font-family: system-ui, -apple-system, sans-serif;
+        font-family: system-ui, -apple-system, "System Font", ".SF NS", "Helvetica Neue", sans-serif;
         font-size: 140px;
-        font-weight: 900;
+        font-weight: 700;
         fill: #F4C430;
         stroke: #14532D;
         stroke-width: 3;
         paint-order: stroke fill;
-        letter-spacing: -2px;
+        letter-spacing: 8px;
-        text-transform: lowercase;
+        font-variant-ligatures: none;
+        font-feature-settings: "liga" 0, "clig" 0, "dlig" 0;
       }
     </style>
   </defs>
 
-  <text x="580" y="220" text-anchor="middle" class="officer-text-main" filter="url(#shadow3d-main-officer)">o<tspan dx="6" dy="30" letter-spacing="14">ff</tspan><tspan dx="-2" dy="-30">icer.dev</tspan></text>
+  <text x="510" y="220" text-anchor="middle" class="officer-text-main" filter="url(#shadow3d-main-officer)">Of<tspan dx="16">f</tspan><tspan dx="10">i</tspan><tspan dx="10">c</tspan><tspan dx="10">e</tspan><tspan dx="10">r</tspan></text>
 
   <rect x="0" y="0" width="1160" height="300" fill="url(#gridPatternOfficer)" mask="url(#textMaskOfficer)"/>
 </svg>

scripts/doctor.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+/**
+ * `bun run doctor` — check the invariants that provisioning cannot check for itself.
+ *
+ * ── Why ──
+ *
+ * Every step in `provisionOsAccount` is deliberately non-fatal, so "nothing reported an error" is much
+ * weaker than it sounds. The 2026-08-19 case: a fresh server, an Admin granted files, chat and terminal,
+ * every named ACL entry correct, provisioning clean — and the account reached nothing, because a later
+ * `chmod 700` had recomputed the ACL mask to `---`. It was found by a person, three days and one
+ * confusing UI message later.
+ *
+ * This is the same posture as `assertPermissionTotality`: state the invariant, verify it, name the fix.
+ * The difference is that this reports rather than refusing to boot — a broken member must not stop the
+ * platform serving everyone else.
+ *
+ * Read-only. It changes nothing, so it is safe on a production box.
+ *
+ * Exit 1 if anything is wrong, so it can gate the end of a setup run.
+ */
+import { getUsers, getAllRoleGrants, OWNER_USER_ID } from 'officerdb';
+import { checkOsAccount } from '../src/servers/os-user-verify';
+import { PERMISSIONS } from '../src/servers/permissions/registry';
+
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+let problems = 0;
+const fail = (what: string, fix: string) => {
+  problems++;
+  console.log(`${red('✗')} ${what}`);
+  console.log(`  ${dim(fix)}`);
+};
+const pass = (what: string) => console.log(`${green('✓')} ${what}`);
+
+console.log('\n── Accounts ──\n');
+
+const users = await getUsers();
+
+for (const user of users) {
+  if (user.id === OWNER_USER_ID) {
+    // The owner runs AS the service user, in the service user's own home. There is no Linux account to
+    // check and no ACL to get wrong — `osUser: null` is correct here, not a finding.
+    pass(`${user.email} ${dim('(owner — runs as the service account)')}`);
+    continue;
+  }
+
+  const check = await checkOsAccount(user.email, user.osUser ?? null);
+  if (check.ok) {
+    pass(`${user.email} ${dim(`(${user.role}, os_user=${check.osUser}, home readable)`)}`);
+  } else {
+    fail(`${user.email} (${user.role}) — ${check.problem}`, `home: ${check.home}`);
+  }
+}
+
+console.log('\n── Grants that cannot take effect ──\n');
+
+// A `confined` grant is silently dropped for an account with no Linux user. That is correct behaviour and
+// completely invisible: the grant is in the table, the UI shows it ticked, and it resolves to nothing.
+const confinedKeys = new Set(PERMISSIONS.filter((p) => p.kind === 'confined').map((p) => p.key));
+const grants = await getAllRoleGrants();
+const unconfined = users.filter((u) => u.id !== OWNER_USER_ID && !u.osUser);
+
+if (!unconfined.length) {
+  pass('every non-owner account has a Linux user');
+} else {
+  for (const user of unconfined) {
+    const dropped = grants
+      .filter((g) => g.role === user.role && confinedKeys.has(g.permission))
+      .map((g) => g.permission);
+    if (!dropped.length) continue;
+    fail(
+      `${user.email} (${user.role}) holds ${dropped.join(', ')} — all dropped, because the account has no Linux user`,
+      'Fix: Settings → User management → provision, or POST /api/users/<id>/provision-linux',
+    );
+  }
+}
+
+console.log('');
+if (problems === 0) {
+  console.log(green('No problems found.\n'));
+  process.exit(0);
+}
+console.log(red(`${problems} problem${problems === 1 ? '' : 's'} found.\n`));
+process.exit(1);

scripts/generate-themes.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env bun
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadPalette } from './themes/palette';
+import { mapPalette } from './themes/map';
+import { TEXT, UI, contrast } from './themes/contrast';
+
+// Generate Officer themes from Omarchy's, and refuse to write an unreadable one.
+//
+//   bun scripts/generate-themes.ts <path-to-omarchy-checkout> [--check]
+//
+// `--check` writes nothing and reports what would change, which is what a test runs.
+//
+// ── Why generated rather than authored ──
+//
+// Twenty-two themes hand-written against an 84-token contract will disagree, and the previous attempt
+// proved it: eleven themes, 34 tokens each, every surface missing. One mapping means one place to be
+// wrong and one place to fix — and a palette that Omarchy updates is a re-run rather than a rewrite.
+//
+// The Duck and Plain themes are NOT generated. They are Officer's own, authored, and this must never
+// overwrite them.
+
+const OMARCHY = process.argv[2];
+const CHECK = process.argv.includes('--check');
+const THEME_DIR = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'css', 'themes');
+
+if (!OMARCHY || !existsSync(join(OMARCHY, 'themes'))) {
+  console.error('usage: bun scripts/generate-themes.ts <path-to-omarchy-checkout> [--check]');
+  process.exit(1);
+}
+
+/** Officer's own. Generated themes may never take these names. */
+const AUTHORED = new Set(['duck-light', 'duck-dark', 'plain']);
+
+const title = (id: string): string =>
+  id
+    .split('-')
+    .map((w) => (w.length <= 2 ? w.toUpperCase() : w[0]!.toUpperCase() + w.slice(1)))
+    .join(' ');
+
+/**
+ * The pairs that must be readable, checked after mapping rather than trusted.
+ *
+ * `ensureContrast` already guarantees most of these — this is the belt to that braces. A mapping change
+ * that quietly breaks one shows up here as a failure instead of as somebody squinting at a screenshot.
+ */
+const PAIRS: [string, string, number][] = [
+  ['--foreground', '--background', TEXT],
+  ['--card-foreground', '--card', TEXT],
+  ['--popover-foreground', '--popover', TEXT],
+  ['--muted-foreground', '--muted', TEXT],
+  ['--accent-foreground', '--accent', TEXT],
+  ['--primary-foreground', '--primary', TEXT],
+  ['--secondary-foreground', '--secondary', TEXT],
+  ['--cta-foreground', '--cta', TEXT],
+  ['--success-foreground', '--success', TEXT],
+  ['--warning-foreground', '--warning', TEXT],
+  ['--destructive-foreground', '--destructive', TEXT],
+  ['--info-foreground', '--info', TEXT],
+  ['--busy-foreground', '--busy', TEXT],
+  ['--busy-ink', '--background', TEXT],
+  // Not `--border` at UI: a panel edge is decoration and 3:1 would ring everything in a hard line. What
+  // must be visible is a form field's boundary and the focus ring — the two that carry information.
+  ['--input', '--background', 1.35],
+  ['--ring', '--background', UI],
+];
+
+let failures = 0;
+let written = 0;
+const generated: { id: string; name: string; dark: boolean }[] = [];
+
+for (const id of readdirSync(join(OMARCHY, 'themes')).sort()) {
+  const toml = join(OMARCHY, 'themes', id, 'colors.toml');
+  if (!existsSync(toml)) continue;
+  if (AUTHORED.has(id)) {
+    console.log(`  ${id}: SKIPPED — Officer's own theme, never generated`);
+    continue;
+  }
+
+  const palette = loadPalette(toml);
+  const tokens = mapPalette(palette);
+
+  for (const [fgKey, bgKey, min] of PAIRS) {
+    const fg = tokens[fgKey]!;
+    const bg = tokens[bgKey]!;
+    // Only flat hex pairs are checkable — a translucent surface depends on what is behind it.
+    if (!fg.startsWith('#') || !bg.startsWith('#')) continue;
+    const ratio = contrast(fg, bg);
+    if (ratio < min) {
+      console.error(`  ${id}: ${fgKey} on ${bgKey} is ${ratio.toFixed(2)}:1, needs ${min}:1`);
+      failures++;
+    }
+  }
+
+  const body = Object.entries(tokens)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n');
+  const css = `/*
+  ${title(id)} — generated from Omarchy's palette by scripts/generate-themes.ts.
+
+  DO NOT EDIT BY HAND. Change the mapping in scripts/themes/map.ts and re-run, so every theme moves
+  together — the previous port drifted precisely because each file was edited on its own.
+
+  Source: basecamp/omarchy themes/${id}/colors.toml (mode: ${palette.mode})
+*/
+[data-theme='${id}'] {
+${body}
+}
+`;
+
+  const path = join(THEME_DIR, `${id}.css`);
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (before !== css) {
+    if (!CHECK) writeFileSync(path, css);
+    written++;
+  }
+  generated.push({ id, name: title(id), dark: palette.mode === 'dark' });
+}
+
+console.log(`\n  ${generated.length} themes, ${written} ${CHECK ? 'would change' : 'written'}, ${failures} contrast failures`);
+
+if (!CHECK) {
+  // The registry and the stylesheet index, rewritten from what was generated so a theme cannot exist as
+  // a file nobody imports — which is a theme that silently does not work.
+  const imports = generated.map((t) => `@import './themes/${t.id}.css';`).join('\n');
+  const indexPath = join(THEME_DIR, '..', 'index.css');
+  const index = readFileSync(indexPath, 'utf8');
+  const marker = '/* Palette themes';
+  const head = index.slice(0, index.indexOf(marker));
+  writeFileSync(
+    indexPath,
+    `${head}/* Palette themes — generated from Omarchy by scripts/generate-themes.ts. Do not edit this block. */\n${imports}\n\n@import './chrome.css';\n`,
+  );
+  console.log(`  index.css: ${generated.length} imports`);
+
+  // The REGISTRY, from the same list. A theme file nothing imports does not work; a theme imported but
+  // absent from here does not appear in the picker. Both were true of the previous port — catppuccin-mocha
+  // outlived its stylesheet — so both halves are written from one source rather than maintained by hand.
+  //
+  // Display names get a pass for the ones a slug cannot spell.
+  const NICER: Record<string, string> = {
+    'rose-pine': 'Rosé Pine',
+    'retro-82': 'Retro 82',
+    'tokyo-night': 'Tokyo Night',
+    'catppuccin': 'Catppuccin Mocha',
+    'catppuccin-latte': 'Catppuccin Latte',
+  };
+  const FAMILY: Record<string, string> = { catppuccin: 'Catppuccin', 'catppuccin-latte': 'Catppuccin' };
+
+  const rows = generated
+    .map((t) => {
+      const name = NICER[t.id] ?? t.name;
+      const family = FAMILY[t.id] ?? name;
+      return `  { id: '${t.id}', name: '${name}', family: '${family}', applyDarkClass: ${t.dark} },`;
+    })
+    .join('\n');
+
+  const registryPath = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'src', 'themes.ts');
+  const registry = readFileSync(registryPath, 'utf8');
+  const START = '  /* GENERATED THEMES — start */';
+  const END = '  /* GENERATED THEMES — end */';
+  if (!registry.includes(START)) {
+    console.error('  themes.ts: missing the GENERATED THEMES markers — not touching it');
+    process.exit(1);
+  }
+  const registryHead = registry.slice(0, registry.indexOf(START) + START.length);
+  const registryTail = registry.slice(registry.indexOf(END));
+  writeFileSync(registryPath, `${registryHead}\n${rows}\n${registryTail}`);
+  console.log(`  themes.ts: ${generated.length} entries`);
+}
+
+process.exit(failures > 0 ? 1 : 0);

scripts/marketplace-sync.ts

@@ -147,7 +147,11 @@ function rawUrl(repoUrl: string, path: string): string {
 }
 
 const dirs = existsSync(PLUGINS_DIR)
-  ? [...new Bun.Glob('*/').scanSync({ cwd: PLUGINS_DIR, onlyFiles: false })].map((d) => join(PLUGINS_DIR, d))
+  ? [...new Bun.Glob('*/').scanSync({ cwd: PLUGINS_DIR, onlyFiles: false })]
+      // Not a plugin: the shared install target for plugin npm packages, which lives here because bun
+      // resolves node_modules up the tree. `discoverPlugins` skips it for the same reason.
+      .filter((d) => d.replace(/\/$/, '') !== 'node_modules')
+      .map((d) => join(PLUGINS_DIR, d))
   : [];
 
 if (dirs.length === 0) {

scripts/nudge-agent.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env bun
+/**
+ * Poke a chat session on a timer, but ONLY when it is idle.
+ *
+ *   bun run nudge -- --session <id> --every 3600 --message "Continue. If blocked, write it down and move on."
+ *   bun run nudge -- --list                       # which sessions exist, and which are working
+ *
+ * ── What this is for ──
+ *
+ * An agent left running overnight. It is told to record blockers and continue rather than wait for a human,
+ * and mostly it does — but a turn that ends leaves it idle until someone types, and at 3am nobody does.
+ * This is the someone.
+ *
+ * ── Why it is a script and not a queue job ──
+ *
+ * The platform has no recurring scheduler and no way to put a prompt into a live session: `pushTurn` has
+ * exactly one caller, the chat websocket. Adding both is real work in the queue engine and the chat API,
+ * and doing it tonight would mean editing a repository an agent is currently working in.
+ *
+ * So this talks to the same doors a browser does — `GET /api/chat/sessions` to see the state, then the chat
+ * websocket to speak. Nothing new is exposed and nothing in the platform changes. If the loop is ever worth
+ * making permanent, it belongs in the queue with a real trigger, and this script is what that would replace.
+ *
+ * ── The one rule ──
+ *
+ * NEVER interrupt work. A nudge sent mid-turn is at best noise and at worst a derail, so `isGenerating` is
+ * checked immediately before speaking and a working session is skipped silently. The point is to restart a
+ * stopped agent, not to hurry a busy one.
+ */
+import { sign } from '@@/jwt';
+import { getOwnerUser } from 'officerdb';
+
+const arg = (name: string): string | undefined => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const has = (name: string) => process.argv.includes(`--${name}`);
+
+const PORT = process.env.OFFICERDEV_PORT ?? process.env.PORT ?? '9000';
+const BASE = `http://127.0.0.1:${PORT}`;
+
+const owner = await getOwnerUser();
+if (!owner) {
+  console.error('[nudge] no owner account — nothing to sign as');
+  process.exit(1);
+}
+// Minted here rather than asked for: this runs on the box, as the owner, and a token pasted into a shell
+// is a token in the shell history.
+const token = await sign({ id: owner.id, email: owner.email, username: owner.username }, '2d');
+
+type Session = { id: string; title?: string; isGenerating?: boolean; updatedAt?: string };
+
+async function sessions(): Promise<Session[]> {
+  // `?all=1` — every working directory, not just the default one. Without it the list is scoped to the
+  // owner's home and an agent started in a project directory is simply absent, which reads as "the session
+  // is gone" and stops the loop. This is the list's own Latest tab, so the shape is identical.
+  const res = await fetch(`${BASE}/api/chat/sessions?all=1`, {
+    headers: { authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) throw new Error(`GET /api/chat/sessions → ${res.status}`);
+  const body = (await res.json()) as { sessions?: Session[] } | Session[];
+  return Array.isArray(body) ? body : (body.sessions ?? []);
+}
+
+if (has('list')) {
+  for (const s of await sessions()) {
+    console.log(`${s.isGenerating ? 'WORKING ' : 'idle    '} ${s.id}  ${s.title ?? ''}`);
+  }
+  process.exit(0);
+}
+
+const sessionId = arg('session');
+const message =
+  arg('message') ?? 'Continue with the next task. If you are blocked, write the blocker down and move on.';
+const every = Number(arg('every') ?? 3600);
+/** A ceiling, because a loop nobody is watching should end on its own. Twelve hours by default. */
+const max = Number(arg('max') ?? 12);
+
+if (!sessionId) {
+  console.error('[nudge] --session <id> is required. Use --list to find one.');
+  process.exit(2);
+}
+
+/** Send one prompt, the way the browser does. Resolves once the server acknowledges the turn. */
+function nudge(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proto = 'ws';
+    const ws = new WebSocket(`${proto}://127.0.0.1:${PORT}/api/chat/ws?token=${token}&sessionId=${sessionId}`);
+    const done = (err?: Error) => {
+      try {
+        ws.close();
+      } catch {
+        /* already closing */
+      }
+      err ? reject(err) : resolve();
+    };
+
+    const timer = setTimeout(() => done(new Error('no acknowledgement within 30s')), 30_000);
+
+    ws.onopen = () => ws.send(JSON.stringify({ type: 'chat', prompt: message, sessionId }));
+    ws.onmessage = (ev) => {
+      // Anything that is not an error means the turn was taken. We do not wait for it to FINISH — that is
+      // the agent's night, not ours.
+      try {
+        const msg = JSON.parse(String(ev.data)) as { type?: string; message?: string };
+        if (msg.type === 'error') {
+          clearTimeout(timer);
+          return done(new Error(msg.message ?? 'server refused the prompt'));
+        }
+        if (msg.type === 'assistant:delta' || msg.type === 'assistant:text' || msg.type === 'tool:start') {
+          clearTimeout(timer);
+          return done();
+        }
+      } catch {
+        /* not json — ignore */
+      }
+    };
+    ws.onerror = () => {
+      clearTimeout(timer);
+      done(new Error('websocket error'));
+    };
+  });
+}
+
+const stamp = () => new Date().toISOString().slice(11, 19);
+
+console.log(`[nudge] session ${sessionId} — every ${every}s, at most ${max} times`);
+console.log(`[nudge] message: ${message}`);
+
+for (let sent = 0, tick = 0; sent < max; tick++) {
+  if (tick > 0) await Bun.sleep(every * 1000);
+
+  let state: Session | undefined;
+  try {
+    state = (await sessions()).find((s) => s.id === sessionId);
+  } catch (err) {
+    console.error(`[nudge ${stamp()}] could not read sessions: ${err instanceof Error ? err.message : err}`);
+    continue; // a server restart is not a reason to give up on the night
+  }
+
+  if (!state) {
+    console.error(`[nudge ${stamp()}] session ${sessionId} is gone — stopping`);
+    break;
+  }
+
+  if (state.isGenerating) {
+    console.log(`[nudge ${stamp()}] working — skipped`);
+    continue;
+  }
+
+  try {
+    await nudge();
+    sent++;
+    console.log(`[nudge ${stamp()}] idle — nudged (${sent}/${max})`);
+  } catch (err) {
+    console.error(`[nudge ${stamp()}] failed: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+console.log(`[nudge ${stamp()}] finished`);
+process.exit(0);

scripts/themes/contrast.ts

@@ -0,0 +1,96 @@
+// WCAG contrast, so "is this readable" stops being a matter of taste.
+//
+// Every complaint about the current themes reduces to one of two failures: a highlight so strong it
+// masks the content on it, or text so close to its background it disappears. Both are a contrast ratio,
+// and a ratio is checkable. This file is what turns the whole exercise from opinion into a test.
+
+export type Rgb = { r: number; g: number; b: number };
+
+export function parseHex(hex: string): Rgb {
+  const h = hex.trim().replace('#', '');
+  const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+  return {
+    r: Number.parseInt(full.slice(0, 2), 16),
+    g: Number.parseInt(full.slice(2, 4), 16),
+    b: Number.parseInt(full.slice(4, 6), 16),
+  };
+}
+
+export const toHex = ({ r, g, b }: Rgb): string =>
+  `#${[r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('')}`;
+
+/** Relative luminance, per WCAG 2.1. */
+export function luminance(c: Rgb): number {
+  const channel = (v: number) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(c.r) + 0.7152 * channel(c.g) + 0.0722 * channel(c.b);
+}
+
+/** 1 (identical) to 21 (black on white). */
+export function contrast(a: string, b: string): number {
+  const [x, y] = [luminance(parseHex(a)), luminance(parseHex(b))];
+  const [hi, lo] = x > y ? [x, y] : [y, x];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * The thresholds, and why these ones.
+ *
+ * `TEXT` is WCAG AA for body text. `UI` is AA for large text and non-text contrast — borders, icons, the
+ * edge of a control. A border at 4.5 would be a hard line around everything, which is a different design
+ * rather than a more accessible one.
+ */
+export const TEXT = 4.5;
+export const UI = 3;
+
+/**
+ * Push a foreground away from its background until it is readable.
+ *
+ * Moves toward black or white — whichever the background is further from — in small steps, so a colour
+ * that is nearly readable keeps almost all of its hue and only a hopeless one ends up monochrome. That
+ * matters: the point is a theme that still looks like Nord, not one that passes and looks like nothing.
+ *
+ * Returns the original when it already passes, so a well-chosen palette is untouched.
+ */
+export function ensureContrast(fg: string, bg: string, min = TEXT): string {
+  if (contrast(fg, bg) >= min) return fg;
+
+  // Whichever extreme is FURTHER from the background, not whichever side of mid-grey it falls on.
+  // Those differ for a mid-tone fill and the difference is the whole answer: rose-pine's rose is at
+  // luminance 0.25, so a `> 0.5` test sends this toward white and caps at 3.5:1, while black reaches
+  // 6:1 easily. Six of its tones were unfixable until this stopped guessing and measured.
+  const black = '#000000';
+  const white = '#ffffff';
+  const target = parseHex(contrast(black, bg) >= contrast(white, bg) ? black : white);
+  const start = parseHex(fg);
+
+  // 40 steps of 2.5% each. Fine enough that the first passing value is close to the original.
+  for (let i = 1; i <= 40; i++) {
+    const t = i / 40;
+    const moved = toHex({
+      r: start.r + (target.r - start.r) * t,
+      g: start.g + (target.g - start.g) * t,
+      b: start.b + (target.b - start.b) * t,
+    });
+    if (contrast(moved, bg) >= min) return moved;
+  }
+  return toHex(target);
+}
+
+/** Blend two colours. `amount` is how much of `b`. */
+export function mix(a: string, b: string, amount: number): string {
+  const [x, y] = [parseHex(a), parseHex(b)];
+  return toHex({
+    r: x.r + (y.r - x.r) * amount,
+    g: x.g + (y.g - x.g) * amount,
+    b: x.b + (y.b - x.b) * amount,
+  });
+}
+
+/** `#rrggbb` → `r g b` for `rgb(var(--x) / 0.5)`, which is how the surfaces get their opacity. */
+export const rgbTriplet = (hex: string): string => {
+  const { r, g, b } = parseHex(hex);
+  return `${r} ${g} ${b}`;
+};

scripts/themes/map.ts

@@ -0,0 +1,193 @@
+import type { Palette } from './palette';
+import { UI, contrast, ensureContrast, mix, rgbTriplet } from './contrast';
+
+// Omarchy palette → Officer's 84 declarations.
+//
+// This file is the whole port. It exists once so that twenty-two themes cannot disagree about what
+// "muted" means, and so that improving the mapping improves all of them at once.
+//
+// ── What went wrong before, and what this fixes ──
+//
+// The previous port produced 34 declarations per theme against a contract of 84. The missing fifty were
+// every surface (`--panel-bg`, `--card-bg`, `--glass-bg`), every state colour (`--success`, `--warning`,
+// `--busy`, `--info`), the header, the scrollbars and the grid — so they fell back to whatever the base
+// stylesheet or the previous theme left behind. That is why highlights masked content and text faded
+// out: not taste, absence. It also shipped thirteen tokens nothing reads (`--chart-1..5`, `--sidebar-*`),
+// which is the tell that it came from a shadcn template rather than from this codebase's contract.
+//
+// ── The rule that makes them readable ──
+//
+// Every foreground is run through `ensureContrast` against the surface it actually sits on. A palette
+// whose colours are already readable is untouched; one that is not gets nudged toward black or white
+// until it passes, keeping as much hue as it can. So a theme cannot ship with invisible text, no matter
+// what its author chose.
+
+export type Tokens = Record<string, string>;
+
+/** Depth ordering differs by mode: a light theme's "darker" is its raised surface, not its page. */
+function surfaces(p: Palette) {
+  const dark = p.mode === 'dark';
+  return {
+    /** The page. The deepest surface in dark, the plainest in light. */
+    page: dark ? p.darkerBackground : p.background,
+    /** Panels and cards sit one step up from the page, so a tile reads as a tile. */
+    raised: dark ? p.background : p.lighterBackground,
+    /** Hovers, secondary fills, the header. One step up again. */
+    high: dark ? p.lighterBackground : p.darkBackground,
+    dark,
+  };
+}
+
+export function mapPalette(p: Palette): Tokens {
+  const s = surfaces(p);
+
+  // Text, checked against the surface each weight actually appears on.
+  const fg = ensureContrast(p.foreground, s.page);
+  const fgRaised = ensureContrast(p.foreground, s.raised);
+  // Checked against `s.high`, not `s.raised`: `--muted-foreground` is the text ON `--muted`, and
+  // `--muted` is the high surface. Deriving it against the wrong one left everforest at 4.44:1 and
+  // miasma at 4.00 — close enough to look fine and still fail, which is the kind of near-miss that a
+  // person eyeballing a screenshot would have shipped.
+  const fgMuted = ensureContrast(p.lightForeground, s.high);
+  const fgFaint = ensureContrast(p.darkForeground, s.raised, UI);
+
+  /**
+   * Text for a solid fill of `bg`.
+   *
+   * Tries the palette's own extremes first, so a button's label still belongs to the theme, and only
+   * falls through to `ensureContrast` when neither is readable. Both steps are needed: picking the
+   * better of two candidates does NOT guarantee either passes — rose-pine's fills are all mid-tone and
+   * every one came out between 2.2:1 and 4.2:1 until this drove it the rest of the way.
+   */
+  const on = (bg: string): string => {
+    const light = p.brightForeground;
+    const dark = p.darkerBackground;
+    const better = contrast(light, bg) >= contrast(dark, bg) ? light : dark;
+    return ensureContrast(better, bg);
+  };
+
+  const accent = p.accent;
+  // Borders are DECORATION, not information, so they are not held to a text ratio — a 3:1 line drawn
+  // around every panel is a different design, not a more accessible one. What they must be is
+  // discernible, which `--input` below is checked for: a form field whose boundary you cannot see is a
+  // real accessibility failure, unlike a subtle panel edge.
+  const border = mix(s.raised, s.dark ? p.lightForeground : p.darkForeground, 0.28);
+
+  return {
+    // ── Ground ──
+    '--background': s.page,
+    '--foreground': fg,
+
+    // ── Surfaces ──
+    '--card': s.raised,
+    '--card-foreground': fgRaised,
+    '--popover': s.raised,
+    '--popover-foreground': fgRaised,
+    // `muted` is a SURFACE here, not the palette's `muted` colour — that one is a mid-grey meant for
+    // dimmed text, and using it as a fill is precisely how a highlight ends up masking its content.
+    '--muted': s.high,
+    '--muted-foreground': fgMuted,
+    '--accent': s.high,
+    '--accent-foreground': fgRaised,
+
+    // ── Actions ──
+    '--primary': accent,
+    '--primary-foreground': on(accent),
+    '--secondary': s.high,
+    '--secondary-foreground': fgRaised,
+    '--cta': accent,
+    '--cta-foreground': on(accent),
+    '--ctahover': mix(accent, s.dark ? '#ffffff' : '#000000', 0.12),
+
+    // ── State — five tones, each readable on its own fill ──
+    '--success': p.green,
+    '--success-foreground': on(p.green),
+    '--warning': p.yellow,
+    '--warning-foreground': on(p.yellow),
+    '--destructive': p.red,
+    '--destructive-foreground': on(p.red),
+    '--info': p.blue,
+    '--info-foreground': on(p.blue),
+    '--busy': p.orange,
+    '--busy-foreground': on(p.orange),
+    // The odd one, per the contract: a fill bright enough for black text is too light to BE text. So ink
+    // is the same hue pushed until it reads on the page.
+    '--busy-ink': ensureContrast(p.orange, s.page),
+
+    // ── Lines ──
+    '--border': border,
+    '--input': border,
+    '--ring': accent,
+    '--radius': '0.625rem',
+
+    // ── Data ──
+    '--chart-primary': accent,
+    '--chart-secondary': p.magenta,
+    '--status-success': p.green,
+    '--status-warning': p.yellow,
+    '--status-in-progress': p.blue,
+
+    // ── Surfaces, as complete CSS values ──
+    '--page-bg': s.page,
+    '--page-bg-src': "''",
+    '--panel-bg': `rgb(${rgbTriplet(s.raised)} / 0.72)`,
+    '--panel-border': `rgb(${rgbTriplet(border)} / 0.9)`,
+    '--panel-border-bare': `rgb(${rgbTriplet(border)} / 0.55)`,
+    // DENSER, not darker — panel chrome is dark text and a heavy fill hides every icon. The contract
+    // says so; this is the one place a value is chosen to obey a sentence rather than a ratio.
+    '--panel-raised-bg': `rgb(${rgbTriplet(s.raised)} / 0.95)`,
+    '--panel-raised-border': `rgb(${rgbTriplet(border)} / 1)`,
+    '--panel-accent': accent,
+    '--panel-header-bg': `rgb(${rgbTriplet(s.high)} / 0.6)`,
+    '--panel-header-fg': fgRaised,
+    '--panel-radius': '0.75rem',
+    '--panel-blur': '12px',
+    '--card-bg': s.raised,
+    '--glass-bg': `rgb(${rgbTriplet(s.raised)} / 0.55)`,
+    '--glass-border': `rgb(${rgbTriplet(border)} / 0.7)`,
+    '--dock-bg': `rgb(${rgbTriplet(s.raised)} / 0.7)`,
+    '--dock-border': `rgb(${rgbTriplet(border)} / 0.8)`,
+    '--dock-tooltip-bg': s.high,
+    '--header-bg': `rgb(${rgbTriplet(s.raised)} / 0.8)`,
+    '--header-border': `rgb(${rgbTriplet(border)} / 0.9)`,
+    '--header-fg': fgRaised,
+    '--header-blur': '12px',
+
+    // Grid lines are a texture, not a colour anyone should notice — kept just above the surface.
+    '--pixel-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.07)`,
+    '--card-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.05)`,
+    '--panel-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.06)`,
+
+    '--scrollbar-thumb': `rgb(${rgbTriplet(p.muted)} / 0.6)`,
+    '--scrollbar-thumb-hover': `rgb(${rgbTriplet(p.muted)} / 0.85)`,
+    '--scrollbar-thin-thumb': `rgb(${rgbTriplet(p.muted)} / 0.45)`,
+    '--scrollbar-thin-thumb-hover': `rgb(${rgbTriplet(p.muted)} / 0.7)`,
+
+    // ── Brand slots ──
+    //
+    // A ported theme has no brand of its own, so these follow its accent rather than importing Duck's
+    // green into somebody else's palette. `--ink` is the app's text colour and is used ~950 times.
+    '--brand': accent,
+    '--brand-foreground': on(accent),
+    '--brand-primary': accent,
+    '--brand-accent': p.cyan,
+    '--brand-warm': p.orange,
+    '--brand-deep': s.dark ? p.darkerBackground : p.darkBackground,
+    '--brand-muted': p.muted,
+    '--ink': fg,
+    '--surface-warm': s.raised,
+    '--naturegreen': p.green,
+    '--naturegreen-foreground': on(p.green),
+
+    // Legacy aliases the contract keeps until the utility rename lands — `prose.css` and some plugins
+    // read them directly, so a theme without them has unstyled prose.
+    '--duck-dark': fg,
+    '--duck-teal': p.cyan,
+    '--duck-yellow': p.yellow,
+    '--duck-orange': p.orange,
+    '--duck-forest': p.green,
+    '--duck-beige': mix(s.raised, fg, 0.1),
+
+    '--logo-src': "'/officer-logo.svg'",
+  };
+}

scripts/themes/palette.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+
+// Reading an Omarchy theme's `colors.toml`.
+//
+// Omarchy 4 ships a genuinely semantic palette rather than sixteen ANSI slots: three background depths,
+// four foreground weights, an accent, a selection and a muted, plus the named hues. That is why this port
+// can be a mapping at all — the previous one had to guess, and the guessing is what produced themes with
+// no surfaces and unreadable highlights.
+//
+// Verified across all 22 themes in basecamp/omarchy@master: every one declares the 24 keys below.
+
+export type Palette = {
+  mode: 'dark' | 'light';
+  accent: string;
+  selection: string;
+  muted: string;
+  background: string;
+  darkBackground: string;
+  darkerBackground: string;
+  lighterBackground: string;
+  foreground: string;
+  darkForeground: string;
+  lightForeground: string;
+  brightForeground: string;
+  red: string;
+  yellow: string;
+  green: string;
+  cyan: string;
+  blue: string;
+  magenta: string;
+  /** Not in every theme — 19 of 22. Falls back to yellow-red mid, which is what orange is. */
+  orange: string;
+  brightRed: string;
+  brightYellow: string;
+  brightGreen: string;
+  brightCyan: string;
+  brightBlue: string;
+  brightMagenta: string;
+};
+
+/** A deliberately small TOML reader: this file is flat `key = "value"` and nothing else. */
+function readToml(path: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const m = line.match(/^\s*([a-z_0-9]+)\s*=\s*"([^"]*)"/i);
+    if (m) out[m[1]!] = m[2]!;
+  }
+  return out;
+}
+
+export function loadPalette(tomlPath: string): Palette {
+  const t = readToml(tomlPath);
+  const need = (key: string): string => {
+    const v = t[key];
+    if (!v) throw new Error(`${tomlPath}: missing "${key}"`);
+    return v;
+  };
+
+  return {
+    mode: t.mode === 'light' ? 'light' : 'dark',
+    accent: need('accent'),
+    selection: need('selection'),
+    muted: need('muted'),
+    background: need('background'),
+    darkBackground: need('dark_background'),
+    darkerBackground: need('darker_background'),
+    lighterBackground: need('lighter_background'),
+    foreground: need('foreground'),
+    darkForeground: need('dark_foreground'),
+    lightForeground: need('light_foreground'),
+    brightForeground: need('bright_foreground'),
+    red: need('red'),
+    yellow: need('yellow'),
+    green: need('green'),
+    cyan: need('cyan'),
+    blue: need('blue'),
+    magenta: need('magenta'),
+    orange: t.orange ?? need('yellow'),
+    brightRed: need('bright_red'),
+    brightYellow: need('bright_yellow'),
+    brightGreen: need('bright_green'),
+    brightCyan: need('bright_cyan'),
+    brightBlue: need('bright_blue'),
+    brightMagenta: need('bright_magenta'),
+  };
+}

scripts/todo-index.ts

@@ -0,0 +1,140 @@
+/**
+ * Regenerate `TODO.md` — the index over `todo/`.
+ *
+ * The index is the one file everybody reads, so it is the one most able to lie. It is generated rather
+ * than maintained: `bun run todo:index` after any change to `todo/`, and it cannot drift from the tree
+ * it describes.
+ */
+import { readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = new URL('..', import.meta.url).pathname;
+const OUT = join(ROOT, 'todo');
+
+export type Item = {
+  id: string;
+  title: string;
+  theme: string;
+  status: string;
+  created: string;
+  /** `urgent` or empty — see todo/README.md for why there is no scale. */
+  priority: string;
+  due: string;
+  order: number;
+  file: string;
+};
+
+/** Minimal frontmatter reader — `key: value`, values optionally JSON-quoted. No YAML dependency. */
+export function frontmatter(text: string): Record<string, string> {
+  const end = text.indexOf('\n---', 4);
+  if (!text.startsWith('---') || end === -1) return {};
+  const out: Record<string, string> = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (!m || !m[1]) continue;
+    const raw = (m[2] ?? '').trim();
+    out[m[1]] = raw.startsWith('"') ? (JSON.parse(raw) as string) : raw;
+  }
+  return out;
+}
+
+export function readTree(): { themes: { theme: string; heading: string; items: Item[] }[] } {
+  const themes = readdirSync(OUT)
+    .filter((d) => statSync(join(OUT, d)).isDirectory())
+    .sort()
+    .map((theme) => {
+      const files = readdirSync(join(OUT, theme)).filter((f) => f.endsWith('.md'));
+      const meta = frontmatter(readFileSync(join(OUT, theme, '_index.md'), 'utf8'));
+      const items = files
+        .filter((f) => f !== '_index.md')
+        .map((f) => {
+          const fm = frontmatter(readFileSync(join(OUT, theme, f), 'utf8'));
+          return {
+            id: fm.id ?? `${theme}/${f.replace(/\.md$/, '')}`,
+            title: fm.title ?? f,
+            theme,
+            status: fm.status ?? 'open',
+            created: fm.created ?? '',
+            priority: fm.priority ?? '',
+            due: fm.due ?? '',
+            order: Number(fm.order ?? 0),
+            file: `todo/${theme}/${f}`,
+          };
+        })
+        .sort((a, b) => a.order - b.order);
+      return { theme, heading: meta.heading ?? theme, items };
+    });
+  return { themes };
+}
+
+const HEADER = `# TODO — the index
+
+Deferred work. **The items live in \`todo/\`, one file each**, grouped by theme; this file is the map
+over them and is GENERATED — run \`bun run todo:index\` after any change rather than editing it here.
+Format and the two-way-sync contract: \`todo/README.md\`.
+
+**Context, corrected 2026-08-07.** This list used to open by saying Officer was "collapsing from
+multi-tenant / open-source-ready to a **single-user platform**", and told you to treat multi-tenant
+indirection as accidental complexity. **That direction was reversed.** The permission model shipped on
+2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each one their own
+Gitea account through the platform. Per-user scoping is now a requirement, and the items that proposed
+deleting it have been removed rather than left to mislead the next reader.
+
+What did NOT reverse: \`execution\` permissions (terminal, chat, tasks, files, desktop, browser) run as
+the owner's OS user and can never be granted. Indirection there really is accidental complexity.
+`;
+
+function render(): string {
+  const { themes } = readTree();
+  const open = themes.reduce((n, t) => n + t.items.filter((i) => i.status !== 'done').length, 0);
+  const done = themes.reduce((n, t) => n + t.items.filter((i) => i.status === 'done').length, 0);
+
+  const rows = themes
+    .filter((t) => t.items.length)
+    .map((t) => {
+      const o = t.items.filter((i) => i.status !== 'done').length;
+      const d = t.items.length - o;
+      return `| [${t.heading}](todo/${t.theme}/) | ${o} | ${d} |`;
+    });
+
+  const recent = themes
+    .flatMap((t) => t.items)
+    .filter((i) => i.status !== 'done')
+    .sort((a, b) => b.created.localeCompare(a.created))
+    .slice(0, 10)
+    .map((i) => `- \`${i.created}\` **${i.title}** — [${i.id}](${i.file})`);
+
+  // A theme holding only prose has no row above, and an entry nobody can see is the failure mode this
+  // whole split risks. List them explicitly rather than letting them age out of view.
+  const notes = themes.filter((t) => !t.items.length).map((t) => `- [${t.heading}](todo/${t.theme}/_index.md)`);
+
+  // Urgent goes above everything. An item the owner called urgent, sorted in among seventy-five others
+  // by theme, is an item nobody sees on the day it matters.
+  const urgent = themes
+    .flatMap((t) => t.items)
+    .filter((i) => i.status !== 'done' && i.priority === 'urgent')
+    .sort((a, b) => (a.due || '9999').localeCompare(b.due || '9999'))
+    .map((i) => `- ${i.due ? `**due ${i.due}** — ` : ''}**${i.title}** — [${i.id}](${i.file})`);
+
+  return [
+    HEADER,
+    ...(urgent.length ? [`## Urgent\n`, ...urgent, ``] : []),
+    `## Themes\n`,
+    `**${open} open, ${done} closed**, across ${rows.length} themes.\n`,
+    `| Theme | Open | Closed |`,
+    `| --- | --- | --- |`,
+    ...rows,
+    ``,
+    `## Records — no items, kept for the reasoning\n`,
+    ...notes,
+    ``,
+    `## Newest ten\n`,
+    ...recent,
+    ``,
+  ].join('\n');
+}
+
+if (import.meta.main) {
+  writeFileSync(join(ROOT, 'TODO.md'), render());
+  console.log('TODO.md regenerated');
+}

scripts/update-plugins.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+import { snapshotPlugins } from '../src/servers/plugins/mount';
+import { updatePlugin, syncCapabilities } from '../src/servers/plugins/update';
+
+// Update every installed plugin, from a terminal.
+//
+//   bun run plugins:update
+//
+// ── Why this exists ──
+//
+// The only way to do this was `POST /api/plugins/update-all`, which is authenticated — so a deploy had to
+// mint an API key to update the plugins on the machine it was already logged into. That is a credential
+// created, used and hopefully deleted, on every host, for a local operation.
+//
+// This is the same work through the same functions, with the HTTP layer removed rather than a second
+// implementation beside it. `prompts/deploy-commander.md` calls it.
+//
+// ── It runs OUTSIDE the server process ──
+//
+// Which matters, and is the one thing to know before reading the output. `updatePlugin` pulls, re-applies
+// and rebuilds the frontend — all of which touch disk and are picked up by the running server. But
+// remounting happens in the process that calls it, and this is not that process, so the routes the
+// server is serving do not change until it restarts.
+//
+// So: the files, the schema, the assets and the SPA bundle are all current when this finishes. The route
+// table is not. A deploy restarts `officer` afterwards, which is what makes the difference invisible —
+// and the reason this says so rather than leaving somebody to find out.
+
+const started = Date.now();
+const { states } = await snapshotPlugins();
+const installed = states.filter((st) => st.install).map((st) => st.plugin.appName);
+
+if (installed.length === 0) {
+  console.log('no plugins installed — nothing to update');
+  process.exit(0);
+}
+
+console.log(`updating ${installed.length} plugin(s): ${installed.join(', ')}\n`);
+
+let failed = 0;
+
+// SEQUENTIAL, like the route: each update pushes a schema, republishes assets, rewrites the ecosystem
+// file and rebuilds the frontend. Two at once is a race over one file each.
+for (const appName of installed) {
+  process.stdout.write(`→ ${appName}\n`);
+  // One plugin failing must not stop the rest. A dirty checkout is the EXPECTED failure — every plugin
+  // directory on a developer machine is a live one — and it should not hold back the other eleven.
+  const result = await updatePlugin(appName, async (step) => console.log(`    ${step}`));
+  if (!result.ok) {
+    failed++;
+    console.error(`    FAILED: ${result.error}`);
+  }
+}
+
+// The capabilities repository rides along, the same as it does through the button: it is one question —
+// "get me what has been published since I installed" — and a second gesture for it is one nobody remembers.
+const capabilities = await syncCapabilities();
+console.log(`\ncapabilities: ${capabilities.action}${capabilities.error ? ` — ${capabilities.error}` : ''}`);
+
+const ok = installed.length - failed;
+console.log(`${ok}/${installed.length} updated in ${Math.round((Date.now() - started) / 1000)}s`);
+if (failed) console.log("a failure above is usually an uncommitted change in that plugin's checkout");
+
+// Non-zero on failure, so a deploy script can stop rather than reporting a success it did not have.
+process.exit(failed > 0 ? 1 : 0);

src/apps/officer-web/App.tsx

@@ -120,10 +120,7 @@ export function App() {
             <Route path="/jobs/:id" element={<Dashboard.JobsPage />} />
             <Route path="/dashboards" element={<Dashboard.DashboardsScreen />} />
             <Route path="/dashboards/:id" element={<Dashboard.DashboardScreen />} />
-            <Route path="/browser" element={<Dashboard.BrowserScreen />} />
-            <Route path="/browser/:tabId" element={<Dashboard.BrowserScreen />} />
             <Route path="/terminal" element={<Dashboard.TerminalScreen />} />
-            <Route path="/desktop" element={<Dashboard.DesktopScreen />} />
             <Route path="/auth/signout" element={<Authentication.SignoutScreen />} />
             <Route path="*" element={<Navigate to="/" replace />} />
           </Routes>

src/apps/officer-web/Screens/Dashboard/Activity/ActivityScreen.tsx

@@ -102,7 +102,7 @@ export const ActivityScreen = () => {
             title={t.cwd}
           >
             <span
-              className={`inline-block h-2 w-2 shrink-0 rounded-full ${t.active ? 'bg-emerald-500 animate-pulse' : 'bg-muted-foreground/40'}`}
+              className={`inline-block h-2 w-2 shrink-0 rounded-full ${t.active ? 'bg-success animate-pulse' : 'bg-muted-foreground/40'}`}
             />
             <span className="truncate font-mono text-xs">{t.id}</span>
           </Link>

src/apps/officer-web/Screens/Dashboard/Browser/BrowserScreen.tsx

@@ -1,48 +0,0 @@
-import { useMemo, useCallback } from 'react';
-import { useNavigate } from 'react-router';
-import type { LayoutNode, PanelComponents } from 'officerdev';
-import { WorkspaceView, ChatPanelWrapper } from 'officerdev';
-import { useDashboardState } from 'state/useDashboardState';
-import { useIsMobile } from 'hooks/useIsMobile';
-import { defaultLayout } from './defaultLayout';
-import { TabList } from './TabList';
-import { TabPreview } from './TabPreview';
-import { useSelectedTabId } from './shared';
-
-const PROMPT_PREFIX = `You are a browser assistant. The user has connected Chrome tabs via the Officer Browser Relay. You have a 'browser' tool — use it to list tabs, take screenshots, navigate, evaluate JavaScript, and get page info. When asked about a page, take a screenshot first.`;
-
-// This screen's prompt, so this screen's chat panel. See the note in `EmailScreen`.
-const BrowserChatPanel = () => <ChatPanelWrapper panelId="browser-chat" promptPrefix={PROMPT_PREFIX} />;
-
-export const BrowserScreen = () => {
-  const isMobile = useIsMobile();
-  const navigate = useNavigate();
-  // No redirect guard: like /email, the bare /browser is the list with nothing open, and a tab id that
-  // no longer resolves gets the preview's "no longer attached" state rather than a rewritten address.
-  const selectedId = useSelectedTabId();
-  const workspace = useDashboardState<LayoutNode>('screens/browser', defaultLayout);
-
-  const components: PanelComponents = useMemo(
-    () => ({
-      'browser-tabs': TabList,
-      'browser-preview': TabPreview,
-      'browser-chat': BrowserChatPanel,
-    }),
-    [],
-  );
-
-  const mobilePanelId = isMobile && selectedId ? 'browser-preview' : undefined;
-  const onMobileBack = useCallback(() => navigate('/browser'), [navigate]);
-
-  return (
-    <div className="h-full w-full pt-2">
-      <WorkspaceView
-        workspace={workspace}
-        locked
-        components={components}
-        mobilePanelId={mobilePanelId}
-        onMobilePanelChange={mobilePanelId ? () => onMobileBack() : undefined}
-      />
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Browser/TabList.tsx

@@ -1,117 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-import { Link } from 'react-router';
-import { Globe, Loader2, X, Eye } from 'lucide-react';
-import { toast } from 'sonner';
-import { useClient } from 'hooks/useClient';
-import { browserTabPath, useBrowserTargets, useSelectedTabId, type BrowserTarget } from './shared';
-
-export const TabList = () => {
-  const client = useClient();
-  const selectedId = useSelectedTabId();
-
-  const { data: status } = useQuery({
-    queryKey: ['browser-status'],
-    queryFn: () => client.get<{ extensionConnected: boolean; targetCount: number }>('/browser/status'),
-    refetchInterval: 5000,
-  });
-
-  const { data: targets, isLoading } = useBrowserTargets(!!status?.extensionConnected);
-
-  const targetList: BrowserTarget[] = targets ?? [];
-
-  const handleClose = async (targetId: string) => {
-    try {
-      await client.post(`/browser/targets/${targetId}/close`);
-    } catch {
-      toast.error('Failed to close tab');
-    }
-  };
-
-  const handleActivate = async (targetId: string) => {
-    try {
-      await client.post(`/browser/targets/${targetId}/activate`);
-    } catch {
-      toast.error('Failed to activate tab');
-    }
-  };
-
-  const isConnected = status?.extensionConnected ?? false;
-
-  return (
-    <div className="flex h-full flex-col overflow-y-auto">
-      <div className="flex items-center gap-2 border-b px-3 py-2">
-        <Globe className="h-4 w-4 opacity-60" />
-        <span className="text-sm font-medium">Browser</span>
-        <div
-          className={`ml-auto h-2 w-2 rounded-full ${isConnected ? 'bg-green-500' : 'bg-red-500'}`}
-          title={isConnected ? 'Extension connected' : 'Extension not connected'}
-        />
-      </div>
-
-      {!isConnected && (
-        <div className="flex flex-col items-center justify-center gap-3 p-4 text-sm flex-1">
-          <Globe className="h-8 w-8 opacity-30" />
-          <p className="opacity-60 text-center">Extension not connected</p>
-          {/* A <Link>, not an <a href>: a raw href to an in-app route reloads the whole SPA. */}
-          <Link to="/settings/integrations" className="text-xs text-duck-teal underline">
-            Set up in Integrations
-          </Link>
-        </div>
-      )}
-
-      {isConnected && isLoading && (
-        <div className="flex h-32 items-center justify-center">
-          <Loader2 className="h-5 w-5 animate-spin opacity-50" />
-        </div>
-      )}
-
-      {isConnected && !isLoading && targetList.length === 0 && (
-        <div className="flex h-32 flex-col items-center justify-center gap-2 text-sm opacity-50">
-          <Globe className="h-6 w-6" />
-          <span>No tabs attached</span>
-          <span className="text-xs">Click the extension icon on a tab</span>
-        </div>
-      )}
-
-      {isConnected && targetList.length > 0 && (
-        <div className="flex flex-1 flex-col divide-y divide-white/10">
-          {/* Focus and Close are siblings of the anchor, not children of it: an <a> may not contain a
-              <button>, and the old row was a <button> containing two more — invalid either way, and it
-              was only the stopPropagation calls holding it together. */}
-          {targetList.map((target) => (
-            <div
-              key={target.id}
-              className={`group relative flex transition-colors ${
-                selectedId === target.id ? 'bg-accent' : 'hover:bg-accent/50'
-              }`}
-            >
-              <Link
-                to={browserTabPath(target.id)}
-                className="flex min-w-0 flex-1 flex-col gap-0.5 px-3 py-2.5 text-left"
-              >
-                <span className="truncate pr-14 text-sm font-medium">{target.title || 'Untitled'}</span>
-                <span className="truncate text-xs opacity-50">{target.url}</span>
-              </Link>
-              <div className="absolute right-3 top-2.5 flex shrink-0 items-center gap-1 opacity-0 transition-opacity group-hover:opacity-100">
-                <button
-                  onClick={() => handleActivate(target.id)}
-                  className="rounded p-0.5 hover:bg-black/10 cursor-pointer"
-                  title="Focus tab"
-                >
-                  <Eye className="h-3.5 w-3.5" />
-                </button>
-                <button
-                  onClick={() => handleClose(target.id)}
-                  className="rounded p-0.5 hover:bg-black/10 cursor-pointer"
-                  title="Close tab"
-                >
-                  <X className="h-3.5 w-3.5" />
-                </button>
-              </div>
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Browser/TabPreview.tsx

@@ -1,174 +0,0 @@
-import { useState, useCallback } from 'react';
-import { Link } from 'react-router';
-import { useQuery } from '@tanstack/react-query';
-import { Globe, RefreshCw, Send, Terminal, Loader2 } from 'lucide-react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import { useClient } from 'hooks/useClient';
-import { useBrowserTargets, useSelectedTabId } from './shared';
-
-export const TabPreview = () => {
-  const client = useClient();
-  // Reads the URL itself rather than being told by the list.
-  const selectedId = useSelectedTabId();
-  const { data: targets } = useBrowserTargets(!!selectedId);
-  // A target id dies with the browser session, so a link or a reload can name a tab that is no longer
-  // attached. Screenshotting it would 404 every ten seconds; better to say so once.
-  const isKnownTab = !!selectedId && !!targets?.some((t) => t.id === selectedId);
-  const [navUrl, setNavUrl] = useState('');
-  const [evalExpr, setEvalExpr] = useState('');
-  const [evalResult, setEvalResult] = useState<string | null>(null);
-  const [isNavigating, setIsNavigating] = useState(false);
-  const [isEvaluating, setIsEvaluating] = useState(false);
-
-  const {
-    data: screenshot,
-    isLoading,
-    refetch,
-    isFetching,
-  } = useQuery({
-    queryKey: ['browser-screenshot', selectedId],
-    queryFn: () => client.get<{ data: string; format: string }>(`/browser/targets/${selectedId}/screenshot`),
-    enabled: isKnownTab,
-    refetchInterval: 10000,
-  });
-
-  const handleNavigate = useCallback(async () => {
-    if (!selectedId || !navUrl.trim()) return;
-    setIsNavigating(true);
-    try {
-      await client.post(`/browser/targets/${selectedId}/navigate`, { url: navUrl.trim() });
-      setTimeout(() => void refetch(), 1000);
-    } catch {
-      toast.error('Navigation failed');
-    } finally {
-      setIsNavigating(false);
-    }
-  }, [client, selectedId, navUrl, refetch]);
-
-  const handleEvaluate = useCallback(async () => {
-    if (!selectedId || !evalExpr.trim()) return;
-    setIsEvaluating(true);
-    try {
-      const res = await client.post<{ result: unknown }>(`/browser/targets/${selectedId}/evaluate`, {
-        expression: evalExpr.trim(),
-      });
-      setEvalResult(JSON.stringify(res.result, null, 2));
-    } catch (err) {
-      setEvalResult(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    } finally {
-      setIsEvaluating(false);
-    }
-  }, [client, selectedId, evalExpr]);
-
-  if (!selectedId) {
-    return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 text-sm opacity-50">
-        <Globe className="h-8 w-8" />
-        <span>Select a tab to preview</span>
-      </div>
-    );
-  }
-
-  // Waiting on the list is not the same as knowing the tab is gone, so only say so once it has arrived.
-  if (targets && !isKnownTab) {
-    return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 text-sm opacity-50">
-        <Globe className="h-8 w-8" />
-        <span>That tab is no longer attached</span>
-        <Link to="/browser" className="text-xs underline">
-          Back to the tab list
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex h-full flex-col overflow-hidden">
-      {/* URL bar */}
-      <div className="flex items-center gap-2 border-b px-3 py-2">
-        <Button
-          variant="ghost"
-          size="sm"
-          className="h-7 w-7 p-0 shrink-0"
-          onClick={() => void refetch()}
-          disabled={isFetching}
-        >
-          {isFetching ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <RefreshCw className="h-3.5 w-3.5" />}
-        </Button>
-        <form
-          className="flex flex-1 items-center gap-2"
-          onSubmit={(ev) => {
-            ev.preventDefault();
-            void handleNavigate();
-          }}
-        >
-          <input
-            type="text"
-            value={navUrl}
-            onChange={(ev) => setNavUrl(ev.target.value)}
-            placeholder="Navigate to URL..."
-            className="flex-1 rounded-md border bg-transparent px-2 py-1 text-sm outline-none focus:border-cyan-500"
-          />
-          <Button
-            variant="ghost"
-            size="sm"
-            className="h-7 w-7 p-0 shrink-0"
-            type="submit"
-            disabled={isNavigating || !navUrl.trim()}
-          >
-            <Send className="h-3.5 w-3.5" />
-          </Button>
-        </form>
-      </div>
-
-      {/* Screenshot */}
-      <div className="flex-1 overflow-auto p-2">
-        {isLoading && !screenshot && (
-          <div className="flex h-full items-center justify-center">
-            <Loader2 className="h-6 w-6 animate-spin opacity-50" />
-          </div>
-        )}
-        {screenshot && (
-          <img
-            src={`data:image/${screenshot.format};base64,${screenshot.data}`}
-            alt="Tab screenshot"
-            className="w-full rounded-md border"
-          />
-        )}
-      </div>
-
-      {/* JS Console */}
-      <div className="border-t">
-        <form
-          className="flex items-center gap-2 px-3 py-2"
-          onSubmit={(ev) => {
-            ev.preventDefault();
-            void handleEvaluate();
-          }}
-        >
-          <Terminal className="h-3.5 w-3.5 shrink-0 opacity-50" />
-          <input
-            type="text"
-            value={evalExpr}
-            onChange={(ev) => setEvalExpr(ev.target.value)}
-            placeholder="Evaluate JavaScript..."
-            className="flex-1 bg-transparent text-sm outline-none font-mono"
-          />
-          <Button
-            variant="ghost"
-            size="sm"
-            className="h-6 px-2 shrink-0"
-            type="submit"
-            disabled={isEvaluating || !evalExpr.trim()}
-          >
-            {isEvaluating ? <Loader2 className="h-3 w-3 animate-spin" /> : 'Run'}
-          </Button>
-        </form>
-        {evalResult !== null && (
-          <pre className="max-h-32 overflow-auto border-t px-3 py-2 text-xs font-mono opacity-70">{evalResult}</pre>
-        )}
-      </div>
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Browser/defaultLayout.ts

@@ -1,22 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-
-export const defaultLayout: LayoutNode = {
-  type: 'group',
-  id: 'browser-root',
-  direction: 'horizontal',
-  children: [
-    { node: { type: 'panel', id: 'browser-tabs', appType: null }, size: 25 },
-    {
-      node: {
-        type: 'group',
-        id: 'browser-right',
-        direction: 'vertical',
-        children: [
-          { node: { type: 'panel', id: 'browser-preview', appType: null }, size: 60 },
-          { node: { type: 'panel', id: 'browser-chat', appType: 'officerdev/chat' }, size: 40 },
-        ],
-      },
-      size: 75,
-    },
-  ],
-};

src/apps/officer-web/Screens/Dashboard/Browser/index.tsx

@@ -1 +0,0 @@
-export { BrowserScreen } from './BrowserScreen';

src/apps/officer-web/Screens/Dashboard/Browser/shared.ts

@@ -1,34 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-import { useParams } from 'react-router';
-import { useClient } from 'hooks/useClient';
-
-// Which attached tab is being previewed is `/browser/:tabId`. It used to be a `BROWSER_SELECTED_TAB`
-// global read by three components, which meant the address bar said `/browser` no matter what you were
-// looking at, and a tab row was a `<button>` with the id in its onClick closure.
-
-export type BrowserTarget = {
-  id: string;
-  sessionId: string;
-  type: string;
-  title: string;
-  url: string;
-};
-
-export const browserTabPath = (id: string) => `/browser/${encodeURIComponent(id)}`;
-
-/** The previewed tab, or null on the bare `/browser` route — the list with nothing open. */
-export const useSelectedTabId = (): string | null => useParams<{ tabId?: string }>().tabId ?? null;
-
-// Both panels want this list and React Query serves both observers from one key, so the preview being
-// able to tell "no tab open" from "that tab is gone" costs no extra request. It needs to: a CDP target
-// id dies with the browser session, and now that the id is in the URL a reload can carry a stale one in
-// — which the old global, living in memory, could never do.
-export const useBrowserTargets = (enabled: boolean) => {
-  const client = useClient();
-  return useQuery({
-    queryKey: ['browser-targets'],
-    queryFn: () => client.get<BrowserTarget[]>('/browser/targets'),
-    refetchInterval: 3000,
-    enabled,
-  });
-};

src/apps/officer-web/Screens/Dashboard/Desktop/DesktopScreen.tsx

@@ -1,18 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-import { WorkspaceView } from 'officerdev';
-import { useDashboardState } from 'state/useDashboardState';
-import { defaultLayout } from './defaultLayout';
-
-export const DesktopScreen = () => {
-  const workspace = useDashboardState<LayoutNode>('screens/desktop', defaultLayout);
-
-  return (
-    <div className="h-full w-full">
-      <WorkspaceView
-        workspace={workspace}
-        locked
-        appTypes={{ allowed: ['officerdev/desktop'], fallback: 'officerdev/desktop' }}
-      />
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Desktop/defaultLayout.ts

@@ -1,7 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-
-export const defaultLayout: LayoutNode = {
-  type: 'panel',
-  id: 'desktop-screen',
-  appType: 'officerdev/desktop',
-};

src/apps/officer-web/Screens/Dashboard/Desktop/index.tsx

@@ -1 +0,0 @@
-export * from './DesktopScreen';

src/apps/officer-web/Screens/Dashboard/Jobs/JobDetail.tsx

@@ -142,7 +142,7 @@ const StatusIcon = ({ status, className }: { status: string; className?: string
   switch (status) {
     case 'completed':
     case 'complete':
-      return <CheckCircle2 className={`${base} text-green-500`} />;
+      return <CheckCircle2 className={`${base} text-success`} />;
     case 'failed':
     case 'error':
       return <AlertCircle className={`${base} text-red-500`} />;

src/apps/officer-web/Screens/Dashboard/Jobs/JobsPage.tsx

@@ -44,7 +44,7 @@ const formatDate = (iso: string) =>
 const StatusIcon = ({ status }: { status: JobSummary['status'] }) => {
   switch (status) {
     case 'completed':
-      return <CheckCircle2 className="h-4 w-4 text-green-500 shrink-0" />;
+      return <CheckCircle2 className="h-4 w-4 text-success shrink-0" />;
     case 'failed':
       return <AlertCircle className="h-4 w-4 text-red-500 shrink-0" />;
     case 'running':

src/apps/officer-web/Screens/Dashboard/Layout/DashboardLayout.tsx

@@ -7,6 +7,7 @@ import { ScreenErrorFallback } from './ScreenErrorFallback';
 import { Background } from './Background';
 import { Header } from './Header';
 import { Dock, CORE_DOCK_ITEMS, dockItemsFromPlugins, defaultDockPaths } from './Dock';
+import { Spotlight } from './Spotlight/Spotlight';
 import { useIsTouch } from './useIsTouch';
 import { usePageTitleSync } from '@/state/usePageTitle';
 import { RouteGate } from './RouteGate';
@@ -47,6 +48,9 @@ export function DashboardLayout({ children }: DashboardLayoutProps) {
   return (
     <div className="relative flex h-dvh flex-col overflow-hidden outline-none inset-0">
       <Header dockItems={visibleItems} hidden={panelFullscreen} />
+      {/* Outside the content region on purpose, like the header and the dock: whatever a screen is doing
+          — maximised panel, error boundary, mid-navigation — ctrl-space still gets you off it. */}
+      <Spotlight />
       {/* overflow-CLIP, not hidden: `hidden` still makes this a scroll container, and the nav Dock —
           absolute, parked below the bottom edge by translateY while hidden — adds its transformed box to
           the scrollable overflow. So clicking a link let the browser scroll this section ~70px to reveal

src/apps/officer-web/Screens/Dashboard/Layout/Header/Header.tsx

@@ -81,7 +81,10 @@ export function Header({ dockItems, hidden }: HeaderProps) {
               role="img"
               aria-label="Officer"
               className="h-8 md:h-12 w-24 md:w-36 bg-contain bg-left bg-no-repeat"
-              style={{ backgroundImage: logo ? `url(${logo})` : 'none', transform: 'skew(-15deg, -2deg)' }}
+              /* No skew. The wordmark is drawn, kerned pair by pair, and shipped as the finished mark —
+                 shearing it in CSS was how the OLD logo got its slant, and doing it to this one distorts
+                 letterforms that were adjusted by hand. See landing/assets/brand/WORDMARK.md. */
+              style={{ backgroundImage: logo ? `url(${logo})` : 'none' }}
             />
           </Link>
         </div>

src/apps/officer-web/Screens/Dashboard/Layout/Rescan/RescanButton.tsx

@@ -33,7 +33,28 @@ export function RescanButton() {
       await Promise.all(ITEM_QUERY_KEYS.map((key) => qc.invalidateQueries({ queryKey: [key], refetchType: 'all' })));
       const c = res.counts ?? {};
       toast.success(
-        `Rescanned items — ${c.tasks ?? 0} tasks, ${c.agents ?? 0} agents, ${c.tools ?? 0} tools, ${c.skills ?? 0} skills, ${c.processes ?? 0} processes`,
+        `Rescanned items — ${c.tasks ?? 0} tasks, ${c.agents ?? 0} agents, ${c.tools ?? 0} tools, ${c.skills ?? 0} skills, ${c.processes ?? 0} processes, ${c.affordances ?? 0} affordances`,
+        {
+          // Two things said here rather than left to be discovered.
+          //
+          // A rescan cannot reach a chat that is already open — its system prompt was assembled when it
+          // started. And a SKILL.md with no `description` is COUNTED as a skill but never offered to an
+          // agent, because the loader skips it: a line that does not say when to reach for something
+          // costs context in every conversation and earns nothing. So a skill can be present, listed and
+          // editable while being invisible to every agent, and the only symptom is two numbers
+          // disagreeing where nobody is comparing them.
+          description:
+            [
+              c.affordances || c.skillsOffered
+                ? 'Applies to new chats — an open one keeps what it started with.'
+                : null,
+              typeof c.skills === 'number' && typeof c.skillsOffered === 'number' && c.skillsOffered < c.skills
+                ? `${c.skills - c.skillsOffered} skill(s) have no description, so no agent is offered them.`
+                : null,
+            ]
+              .filter(Boolean)
+              .join(' ') || undefined,
+        },
       );
     } catch {
       toast.error('Failed to rescan items');

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/Spotlight.tsx

@@ -0,0 +1,210 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { Search } from 'lucide-react';
+import { rank } from './match';
+import { useSpotlightItems, type SpotlightItem } from './useSpotlightItems';
+
+// Spotlight: type a few letters, go somewhere.
+//
+// The dock is full and cannot grow, which is what this is for — once navigation lives here, the dock is
+// free to be a short list of what you actually use rather than a complete one.
+//
+// ── Keyboard first, and the trigger ──
+//
+// `shift-space`. The two obvious chords were both taken: `ctrl-space` focuses the address bar in Brave,
+// and `alt-space` is load-bearing for the owner elsewhere. `cmd-k` belongs to the browser on some
+// platforms and to text fields on others.
+//
+// **Shift-space is a real key combination inside a text field** — it types a space, and people hold shift
+// through one more often than they think while typing capitals. So the trigger is IGNORED when focus is
+// in an input, a textarea or anything contenteditable, and the space is typed as normal.
+//
+// The cost of that is worth stating: focus usually IS in the chat composer, so opening Spotlight from
+// there means clicking out first. If that turns out to be the common case, a double-tap of shift is the
+// escape hatch — it conflicts with nothing anywhere.
+//
+// Escape closes, arrows move, enter goes. The mouse works, but nothing here is designed around it.
+
+const MAX_RESULTS = 8;
+
+/**
+ * Is the user typing into something?
+ *
+ * `shift-space` types a space in any text field, so the trigger has to stand down there or it eats a
+ * keystroke people make by accident all day. `isContentEditable` covers the editor and any rich input a
+ * panel brings with it.
+ */
+function isTyping(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el || !el.tagName) return false;
+  return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable === true;
+}
+
+/** Label with the matched characters picked out, so it is obvious WHY a result is here. */
+const Highlighted = ({ label, hits }: { label: string; hits: number[] }) => {
+  if (!hits.length) return <>{label}</>;
+  const set = new Set(hits);
+  return (
+    <>
+      {label.split('').map((char, i) =>
+        set.has(i) ? (
+          <span key={i} className="text-duck-teal">
+            {char}
+          </span>
+        ) : (
+          <span key={i}>{char}</span>
+        ),
+      )}
+    </>
+  );
+};
+
+const Row = ({
+  item,
+  hits,
+  active,
+  onPick,
+}: {
+  item: SpotlightItem;
+  hits: number[];
+  active: boolean;
+  onPick: () => void;
+}) => {
+  const Icon = item.icon;
+  return (
+    <button
+      type="button"
+      // `onMouseDown`, not `onClick`: the input holds focus and a click would blur it first, closing the
+      // overlay on the blur handler before the navigation ever ran.
+      onMouseDown={(ev) => {
+        ev.preventDefault();
+        onPick();
+      }}
+      className={`flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors ${
+        active ? 'bg-accent' : 'hover:bg-accent/50'
+      }`}
+    >
+      <span
+        className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md"
+        style={item.color ? { backgroundColor: `${item.color}22`, color: item.color } : undefined}
+      >
+        {item.image ? (
+          <img src={item.image} alt="" className="h-5 w-5 object-contain" />
+        ) : Icon ? (
+          <Icon className="h-4 w-4" />
+        ) : (
+          <Search className="h-4 w-4" />
+        )}
+      </span>
+      <span className="min-w-0 flex-1">
+        <span className="block truncate text-sm text-foreground">
+          <Highlighted label={item.label} hits={hits} />
+        </span>
+        {item.hint ? <span className="block truncate text-xs text-muted-foreground">{item.hint}</span> : null}
+      </span>
+      <span className="shrink-0 font-mono text-[10px] text-muted-foreground/60">{item.to}</span>
+    </button>
+  );
+};
+
+export const Spotlight = () => {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [active, setActive] = useState(0);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const navigate = useNavigate();
+  const items = useSpotlightItems();
+
+  const results = useMemo(() => rank(items, query).slice(0, MAX_RESULTS), [items, query]);
+
+  const close = useCallback(() => {
+    setOpen(false);
+    setQuery('');
+    setActive(0);
+  }, []);
+
+  const pick = useCallback(
+    (item: SpotlightItem | undefined) => {
+      if (!item) return;
+      close();
+      navigate(item.to);
+    },
+    [close, navigate],
+  );
+
+  // The trigger. Bound to the window rather than to a container, because it has to work while focus is
+  // anywhere — including inside a panel that has its own key handling.
+  useEffect(() => {
+    const onKey = (ev: KeyboardEvent) => {
+      if (ev.shiftKey && ev.code === 'Space' && !isTyping(ev.target)) {
+        ev.preventDefault();
+        setOpen((wasOpen) => !wasOpen);
+        return;
+      }
+      if (ev.key === 'Escape' && open) close();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, close]);
+
+  useEffect(() => {
+    if (open) inputRef.current?.focus();
+  }, [open]);
+
+  // Reset the cursor whenever the result set changes, so it never points past the end.
+  useEffect(() => setActive(0), [query]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center bg-black/40 pt-[12vh] backdrop-blur-sm"
+      onMouseDown={close}
+    >
+      <div
+        className="w-[min(92vw,560px)] overflow-hidden rounded-2xl border border-border bg-background/95 shadow-2xl"
+        // The backdrop closes on mousedown; this stops a click INSIDE the panel counting as one.
+        onMouseDown={(ev) => ev.stopPropagation()}
+      >
+        <div className="flex items-center gap-2 border-b border-border px-4">
+          <Search className="h-4 w-4 shrink-0 text-muted-foreground" />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(ev) => setQuery(ev.target.value)}
+            onKeyDown={(ev) => {
+              if (ev.key === 'ArrowDown') {
+                ev.preventDefault();
+                setActive((i) => Math.min(i + 1, results.length - 1));
+              } else if (ev.key === 'ArrowUp') {
+                ev.preventDefault();
+                setActive((i) => Math.max(i - 1, 0));
+              } else if (ev.key === 'Enter') {
+                ev.preventDefault();
+                pick(results[active]?.item);
+              }
+            }}
+            placeholder="Go to…"
+            className="w-full bg-transparent py-3.5 text-sm text-foreground outline-none placeholder:text-muted-foreground"
+          />
+        </div>
+
+        <div className="max-h-[52vh] overflow-y-auto p-2">
+          {results.length === 0 ? (
+            <p className="px-3 py-6 text-center text-sm text-muted-foreground">Nothing matches “{query}”.</p>
+          ) : (
+            results.map((result, i) => (
+              <Row
+                key={result.item.id}
+                item={result.item}
+                hits={result.hits}
+                active={i === active}
+                onPick={() => pick(result.item)}
+              />
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/match.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test';
+import { rank } from './match';
+import type { SpotlightItem } from './useSpotlightItems';
+
+// The behaviours a launcher is judged on, which are all about ORDER rather than about matching. Anyone
+// can return the right set; returning it with the right thing first is the whole product.
+
+const item = (label: string, to: string, hint?: string): SpotlightItem => ({ id: to, label, to, hint });
+
+const ITEMS: SpotlightItem[] = [
+  item('Home', '/'),
+  item('Files', '/files'),
+  item('Chat', '/chat'),
+  item('Command HQ', '/command-hq'),
+  item('Editor', '/code-editor'),
+  item('Profile', '/settings/profile', 'avatar, name, email'),
+  item('API keys', '/settings/profile/api-keys', 'per-app keys'),
+  item('App store', '/app-store'),
+  item('Dashboards', '/dashboards'),
+];
+
+const top = (query: string, n = 1) =>
+  rank(ITEMS, query)
+    .slice(0, n)
+    .map((s) => s.item.label);
+
+describe('spotlight ranking', () => {
+  test('an exact label wins', () => {
+    expect(top('chat')).toEqual(['Chat']);
+  });
+
+  test('a prefix beats a scattered match — "fi" is Files, not Profile', () => {
+    expect(top('fi')).toEqual(['Files']);
+  });
+
+  test('initials find a two-word label — "chq" is Command HQ', () => {
+    expect(top('chq')).toEqual(['Command HQ']);
+  });
+
+  test('a subsequence works, so you can type the shape of a word', () => {
+    expect(top('apik')).toEqual(['API keys']);
+  });
+
+  test('a hint matches, but never outranks a label', () => {
+    // "keys" is API keys' own label AND its hint. It must not be beaten by anything mentioning keys.
+    expect(top('keys')).toEqual(['API keys']);
+  });
+
+  test('a path fragment finds the item without outranking labels', () => {
+    expect(rank(ITEMS, 'settings').map((s) => s.item.label)).toContain('Profile');
+    // "app" is a prefix of "App store" and appears in API keys' hint ("per-app keys"). Label wins.
+    expect(top('app')).toEqual(['App store']);
+  });
+
+  test('nothing matches means nothing returned, not everything', () => {
+    expect(rank(ITEMS, 'zzzzz')).toHaveLength(0);
+  });
+
+  test('an empty query keeps the given order rather than sorting it', () => {
+    expect(rank(ITEMS, '').map((s) => s.item.label)).toEqual(ITEMS.map((i) => i.label));
+  });
+
+  test('shorter labels break ties — "Chat" over "Chat history"', () => {
+    const withLonger = [...ITEMS, item('Chat history', '/chat-history')];
+    expect(rank(withLonger, 'chat')[0]!.item.label).toBe('Chat');
+  });
+});

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/match.ts

@@ -0,0 +1,93 @@
+import type { SpotlightItem } from './useSpotlightItems';
+
+// Ranking, kept apart from React so it can be tested with strings.
+//
+// Subsequence matching, not substring: "cmdhq" should find "Command HQ" and "apik" should find
+// "API keys". Anyone who has used a launcher expects to type the shape of a word rather than a prefix
+// of it, and a substring match makes them type more to get less.
+
+export type Scored = { item: SpotlightItem; score: number; hits: number[] };
+
+/**
+ * Where each character of `query` lands in `text`, or null if it does not fit.
+ *
+ * Greedy left-to-right, which is what makes it cheap and predictable. It can miss a better alignment —
+ * "ao" against "app store" takes the first `o` in the first word rather than the one in "store" — and
+ * that costs a slightly worse score, never a wrong answer, because the item still matches.
+ */
+function subsequence(text: string, query: string): number[] | null {
+  const hits: number[] = [];
+  let at = 0;
+  for (const char of query) {
+    const found = text.indexOf(char, at);
+    if (found === -1) return null;
+    hits.push(found);
+    at = found + 1;
+  }
+  return hits;
+}
+
+/** Start of the string, or the character after a space, dash or slash. */
+const isBoundary = (text: string, i: number): boolean => i === 0 || /[\s\-/]/.test(text[i - 1]!);
+
+/**
+ * Higher is better. The weights encode what a person means by "the right result":
+ *
+ * - **an exact label** is what they typed, so nothing beats it
+ * - **a prefix** beats a scattered match — typing "fi" should rank Files above Profile
+ * - **word boundaries** are why "chq" finds Command HQ at all, and should rank it above an item where
+ *   those letters happen to fall mid-word
+ * - **adjacency** rewards a run of letters, which is what a substring match would have found
+ * - **shortness** breaks ties toward the more specific label: "Chat" over "Chat history"
+ *
+ * The label is worth roughly three times the hint, so typing a word that IS a label beats an item that
+ * merely mentions it in passing.
+ */
+function scoreOne(text: string, query: string, weight: number): { score: number; hits: number[] } | null {
+  const hits = subsequence(text, query);
+  if (!hits) return null;
+
+  let score = 0;
+  if (text === query) score += 1000;
+  else if (text.startsWith(query)) score += 400;
+
+  for (let i = 0; i < hits.length; i++) {
+    const at = hits[i]!;
+    if (isBoundary(text, at)) score += 30;
+    if (i > 0 && at === hits[i - 1]! + 1) score += 15;
+  }
+
+  // Shorter labels win ties. Capped so a very long one is not driven negative.
+  score += Math.max(0, 40 - text.length);
+  return { score: score * weight, hits };
+}
+
+/**
+ * Rank items against a query.
+ *
+ * An empty query returns everything in its given order — the index is already in a sensible one (dock
+ * first, settings after), and imposing an alphabetical sort on an empty box would move Home away from
+ * the top for no reason.
+ */
+export function rank(items: SpotlightItem[], query: string): Scored[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return items.map((item) => ({ item, score: 0, hits: [] }));
+
+  const scored: Scored[] = [];
+  for (const item of items) {
+    const label = scoreOne(item.label.toLowerCase(), q, 1);
+    const hint = item.hint ? scoreOne(item.hint.toLowerCase(), q, 0.3) : null;
+    // The PATH is matched too, unweighted almost to nothing: it is how "/settings/profile" finds Profile
+    // when somebody types a URL fragment, without letting a path ever outrank a real label.
+    const path = scoreOne(item.to.toLowerCase(), q, 0.15);
+
+    const best = [label, hint, path]
+      .filter((s): s is { score: number; hits: number[] } => !!s)
+      .sort((a, b) => b.score - a.score)[0];
+    if (!best) continue;
+    // `hits` is only meaningful for the label, since that is the only string rendered with highlighting.
+    scored.push({ item, score: best.score, hits: label?.hits ?? [] });
+  }
+
+  return scored.sort((a, b) => b.score - a.score || a.item.label.length - b.item.label.length);
+}

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/useSpotlightItems.ts

@@ -0,0 +1,81 @@
+import { useMemo } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { Settings, User, Puzzle, Server, Cpu, Users } from 'lucide-react';
+import { usePermissions } from 'hooks/usePermissions';
+import { CORE_DOCK_ITEMS, dockItemsFromPlugins } from '../Dock';
+
+// What Spotlight can take you to.
+//
+// ── It indexes the DOCK, rather than a list of its own ──
+//
+// The dock is already the composed, permission-filtered answer to "what can this account open here":
+// the shell's own screens, plus whatever installed plugins contribute, minus anything `canVisit` refuses.
+// Building a second list would mean two answers to one question, and the second would be wrong the day
+// somebody installs a plugin — which is the whole failure the dock's own comment warns about, arrived at
+// from a third direction.
+//
+// So a new plugin appears in Spotlight for the same reason it appears in the dock: because it is
+// installed. Nothing here is edited.
+//
+// Settings sections are added because they are the things people hunt for and the dock deliberately does
+// not carry. They are static: a settings screen is shell, not a plugin.
+
+export type SpotlightItem = {
+  /** Stable across renders — used as the React key and for the recency store. */
+  id: string;
+  label: string;
+  /** Where it goes. Matched against `canVisit` for anything not already filtered. */
+  to: string;
+  /** Shown small beside the label, so two "Profile"s are distinguishable. */
+  hint?: string;
+  icon?: LucideIcon;
+  /** Plugin artwork, when the tile has some. */
+  image?: string;
+  color?: string;
+};
+
+/**
+ * The settings sections, which the dock does not carry.
+ *
+ * Hand-listed rather than derived, and that is a real cost: a section added to `IntegrationsSettings`
+ * will not appear here until someone adds it. The alternative is exporting every settings screen's
+ * section array up into the shell, which couples five screens to this one to save five lines.
+ *
+ * Worth revisiting if it drifts. `hint` is what makes them findable — typing "keys" should reach the API
+ * keys screen, and the label alone does not say where it lives.
+ */
+const SETTINGS_ITEMS: SpotlightItem[] = [
+  { id: 'set:profile', label: 'Profile', to: '/settings/profile', hint: 'avatar, name, email', icon: User },
+  { id: 'set:password', label: 'Change password', to: '/settings/profile/change-password', icon: User },
+  { id: 'set:api-keys', label: 'API keys', to: '/settings/profile/api-keys', hint: 'per-app keys', icon: User },
+  { id: 'set:dock', label: 'Dock', to: '/settings/profile/dock', hint: 'choose and reorder', icon: User },
+  { id: 'set:integrations', label: 'Integrations', to: '/settings/integrations', icon: Puzzle },
+  { id: 'set:server', label: 'Server settings', to: '/settings/server', icon: Server },
+  { id: 'set:system', label: 'System', to: '/settings/system', icon: Cpu },
+  { id: 'set:users', label: 'Users', to: '/settings/users', hint: 'accounts and permissions', icon: Users },
+  { id: 'set:ai', label: 'AI', to: '/settings/ai', hint: 'models and harnesses', icon: Settings },
+];
+
+/** Everything Spotlight can offer this account, in a stable order. */
+export function useSpotlightItems(): SpotlightItem[] {
+  const { canVisit, plugins } = usePermissions();
+
+  return useMemo(() => {
+    const fromDock: SpotlightItem[] = [...CORE_DOCK_ITEMS, ...dockItemsFromPlugins(plugins)]
+      .filter((item) => canVisit(item.to))
+      .map((item) => ({
+        id: `nav:${item.to}`,
+        label: item.label,
+        to: item.to,
+        icon: item.icon,
+        image: item.image,
+        color: item.color,
+      }));
+
+    // Settings go through `canVisit` too. `usePermissions` fails OPEN by design — hiding a door is a
+    // courtesy and the 403 is the lock — so this cannot lock anyone out of their own settings.
+    const settings = SETTINGS_ITEMS.filter((item) => canVisit(item.to));
+
+    return [...fromDock, ...settings];
+  }, [canVisit, plugins]);
+}

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/ApifyConfig.tsx

@@ -54,7 +54,7 @@ export const ApifyConfig = () => {
       {status && (
         <div className="flex items-center gap-2 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-3">
           <div
-            className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.configured ? 'bg-green-500' : 'bg-duck-dark/20 dark:bg-foreground/20'}`}
+            className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.configured ? 'bg-success' : 'bg-duck-dark/20 dark:bg-foreground/20'}`}
           />
           <span className="text-sm text-duck-dark dark:text-foreground">
             {status.configured ? 'API token configured' : 'Not configured'}

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/BrowserRelay.tsx

@@ -1,199 +0,0 @@
-import { useState } from 'react';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { Copy, Check, Download, ExternalLink, RefreshCw, Trash2 } from 'lucide-react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import { useClient } from 'hooks/useClient';
-import { copyToClipboard } from 'helpers/clipboard';
-
-type RelayToken = {
-  token: string;
-  port: number;
-};
-
-export const BrowserRelay = () => {
-  const client = useClient();
-  const queryClient = useQueryClient();
-  const [copiedField, setCopiedField] = useState<string | null>(null);
-
-  const { data: status } = useQuery({
-    queryKey: ['browser-status'],
-    queryFn: () => client.get<{ extensionConnected: boolean; targetCount: number }>('/browser/status'),
-    refetchInterval: 5000,
-  });
-
-  const { data: tokenData } = useQuery({
-    queryKey: ['browser-relay-token'],
-    queryFn: () => client.get<RelayToken>('/browser/relay-token'),
-  });
-
-  const regenerate = useMutation({
-    mutationFn: () => client.post<RelayToken>('/browser/relay-token/regenerate'),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['browser-relay-token'] });
-      toast.success('Token regenerated — update the extension with the new token');
-    },
-    onError: () => toast.error('Failed to regenerate token'),
-  });
-
-  const revoke = useMutation({
-    mutationFn: () => client.delete('/browser/relay-token'),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['browser-relay-token'] });
-      toast.success('Token revoked');
-    },
-    onError: () => toast.error('Failed to revoke token'),
-  });
-
-  const handleCopy = async (value: string, field: string) => {
-    try {
-      await copyToClipboard(value);
-      setCopiedField(field);
-      toast.success('Copied to clipboard');
-      setTimeout(() => setCopiedField(null), 2000);
-    } catch {
-      toast.error('Failed to copy');
-    }
-  };
-
-  const isConnected = status?.extensionConnected ?? false;
-  const serverAddress = window.location.hostname;
-
-  return (
-    <div className="grid gap-4">
-      {isConnected ? (
-        <div className="flex items-center gap-3 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4">
-          <div className="h-2.5 w-2.5 rounded-full bg-green-500 shrink-0" />
-          <div className="min-w-0 flex-1">
-            <p className="text-sm font-medium text-duck-dark dark:text-foreground">Connected</p>
-            <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-              {status?.targetCount ?? 0} tab{(status?.targetCount ?? 0) !== 1 ? 's' : ''} attached
-              {' — '}
-              <a href="/browser" className="text-duck-teal underline">
-                view tabs
-              </a>
-            </p>
-          </div>
-        </div>
-      ) : (
-        <p className="text-sm text-duck-dark/60 dark:text-foreground/60">
-          Connect your Chrome browser to Officer so AI agents can view and interact with your tabs.
-        </p>
-      )}
-
-      {/* Step 1: Install */}
-      <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-        <p className="text-sm font-medium text-duck-dark dark:text-foreground">1. Install the extension</p>
-        <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-          Download and unzip the extension, then load it in Chrome:
-        </p>
-        <a
-          href="/browser-relay-extension.zip"
-          download
-          className="flex items-center justify-center gap-2 w-full h-11 rounded-md border border-duck-dark/15 dark:border-foreground/15 text-sm font-medium hover:bg-duck-dark/5 dark:hover:bg-foreground/5 transition-colors"
-        >
-          <Download className="h-4 w-4" />
-          Download Extension
-        </a>
-        <ol className="list-decimal list-inside space-y-1.5 text-xs text-duck-dark/50 dark:text-foreground/50">
-          <li>
-            Open{' '}
-            <code className="bg-duck-dark/5 dark:bg-foreground/5 px-1.5 py-0.5 rounded text-[11px]">
-              chrome://extensions
-            </code>{' '}
-            in Chrome
-          </li>
-          <li>
-            Enable <strong>Developer mode</strong> (top-right toggle)
-          </li>
-          <li>
-            Click <strong>Load unpacked</strong> and select the unzipped folder
-          </li>
-        </ol>
-      </div>
-
-      {/* Step 2: Configure */}
-      {tokenData && (
-        <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-          <p className="text-sm font-medium text-duck-dark dark:text-foreground">2. Configure the extension</p>
-          <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-            Open the extension options (right-click icon → Options) and enter these values:
-          </p>
-
-          <div className="grid gap-2">
-            <CredentialRow
-              label="Server address"
-              value={serverAddress}
-              copied={copiedField === 'host'}
-              onCopy={() => handleCopy(serverAddress, 'host')}
-            />
-            <CredentialRow
-              label="Port"
-              value={String(tokenData.port)}
-              copied={copiedField === 'port'}
-              onCopy={() => handleCopy(String(tokenData.port), 'port')}
-            />
-            <CredentialRow
-              label="Relay token"
-              value={tokenData.token}
-              masked
-              copied={copiedField === 'token'}
-              onCopy={() => handleCopy(tokenData.token, 'token')}
-            />
-          </div>
-
-          <div className="flex gap-2">
-            <Button variant="outline" size="sm" onClick={() => regenerate.mutate()} disabled={regenerate.isPending}>
-              <RefreshCw className="h-3.5 w-3.5 mr-1.5" />
-              Regenerate
-            </Button>
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => revoke.mutate()}
-              disabled={revoke.isPending}
-              className="text-red-500 hover:text-red-600"
-            >
-              <Trash2 className="h-3.5 w-3.5 mr-1.5" />
-              Revoke
-            </Button>
-          </div>
-        </div>
-      )}
-
-      {/* Step 3: Attach */}
-      <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-        <p className="text-sm font-medium text-duck-dark dark:text-foreground">3. Attach a tab</p>
-        <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-          Navigate to any webpage and click the Officer extension icon in the toolbar. A cyan <strong>ON</strong> badge
-          means the tab is connected. Then go to{' '}
-          <a href="/browser" className="text-duck-teal underline inline-flex items-center gap-0.5">
-            /browser <ExternalLink className="h-3 w-3" />
-          </a>{' '}
-          to view your tabs.
-        </p>
-      </div>
-    </div>
-  );
-};
-
-type CredentialRowProps = {
-  label: string;
-  value: string;
-  masked?: boolean;
-  copied: boolean;
-  onCopy: () => void;
-};
-
-const CredentialRow = ({ label, value, masked, copied, onCopy }: CredentialRowProps) => (
-  <div className="flex items-center gap-2 rounded-md bg-duck-dark/5 dark:bg-foreground/5 px-3 py-2">
-    <span className="text-xs text-duck-dark/50 dark:text-foreground/50 shrink-0 w-24">{label}</span>
-    <code className="flex-1 text-xs truncate">{masked ? `${value.slice(0, 8)}${'•'.repeat(16)}` : value}</code>
-    <button
-      onClick={onCopy}
-      className="shrink-0 p-1 rounded hover:bg-duck-dark/10 dark:hover:bg-foreground/10 cursor-pointer"
-    >
-      {copied ? <Check className="h-3.5 w-3.5 text-green-500" /> : <Copy className="h-3.5 w-3.5 opacity-50" />}
-    </button>
-  </div>
-);

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/GoogleAccount.tsx

@@ -71,7 +71,7 @@ export const GoogleAccount = () => {
       {status.connected ? (
         <>
           <div className="flex items-center gap-3 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4">
-            <div className="h-2.5 w-2.5 rounded-full bg-green-500 shrink-0" />
+            <div className="h-2.5 w-2.5 rounded-full bg-success shrink-0" />
             <div className="min-w-0 flex-1">
               <p className="text-sm font-medium text-duck-dark dark:text-foreground">Connected</p>
               <p className="text-xs text-duck-dark/50 dark:text-foreground/50 truncate">{status.email}</p>

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/GoogleOAuthConfig.tsx

@@ -221,7 +221,7 @@ const CredentialStatus = ({ status, isVerifying }: { status: VerifyStatus; isVer
 
   return (
     <div className="flex items-center gap-2 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-3">
-      <div className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.valid ? 'bg-green-500' : 'bg-red-500'}`} />
+      <div className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.valid ? 'bg-success' : 'bg-red-500'}`} />
       <span className={`text-sm ${status.valid ? 'text-duck-dark dark:text-foreground' : 'text-red-500'}`}>
         {status.valid ? 'Credentials valid' : (status.error ?? 'Invalid credentials')}
       </span>

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/index.tsx

@@ -8,10 +8,8 @@ import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { SettingsRoute, SettingsSidebar, SettingsContent, type SettingsSection } from '../SettingsPanel';
 import { GoogleOAuthConfig } from './GoogleOAuthConfig';
 // import { GoogleAccount } from './GoogleAccount'; // hidden — email uses IMAP app password now
-import { BrowserRelay } from './BrowserRelay';
 import { ApifyConfig } from './ApifyConfig';
 import { DavAppPasswords } from './DavAppPasswords';
-import { ApiKeys } from './ApiKeys';
 
 const BASE_PATH = '/settings/integrations';
 
@@ -51,20 +49,6 @@ const personalSections: SettingsSection[] = [
     description: 'Per-device passwords for CalDAV/CardDAV clients',
     content: <DavAppPasswords />,
   },
-  {
-    key: 'api-keys',
-    icon: KeyRound,
-    title: 'API keys',
-    description: 'Per-app keys that sign in as you, revocable one at a time',
-    content: <ApiKeys />,
-  },
-  {
-    key: 'browser-relay',
-    icon: Globe,
-    title: 'Browser Relay',
-    description: 'Connect your Chrome browser',
-    content: <BrowserRelay />,
-  },
 ];
 
 // The Enterprise/Personal tab is not a second thing to remember — it is a fact about which section is

src/apps/officer-web/Screens/Dashboard/Settings/ProfileSettings/ApiKeys.tsx

@@ -2,7 +2,7 @@ import type { FormEvent } from 'react';
 import { useState } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { toast } from 'sonner';
-import { Copy, Ban, Plus, KeyRound, Loader2 } from 'lucide-react';
+import { Copy, Ban, Plus, KeyRound, Loader2, Trash2 } from 'lucide-react';
 import { useClient } from 'hooks/useClient';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -53,6 +53,7 @@ export const ApiKeys = () => {
   const queryClient = useQueryClient();
   const [name, setName] = useState('');
   const [isCreating, setIsCreating] = useState(false);
+  const [showRevoked, setShowRevoked] = useState(false);
   const [minted, setMinted] = useState<Minted | null>(null);
 
   const { data, isLoading } = useQuery<{ keys: ApiKey[] }>({
@@ -79,6 +80,15 @@ export const ApiKeys = () => {
     }
   };
 
+  const forget = async (id: number) => {
+    try {
+      await client.delete(`/api-keys/${id}/record`);
+      await refresh();
+    } catch {
+      toast.error('Could not remove it');
+    }
+  };
+
   const revoke = async (id: number) => {
     try {
       await client.delete(`/api-keys/${id}`);
@@ -89,7 +99,19 @@ export const ApiKeys = () => {
     }
   };
 
-  const keys = data?.keys ?? [];
+  const allKeys = data?.keys ?? [];
+
+  // Dead means revoked OR past its expiry — the same test the row rendering uses, lifted here so the
+  // count in the toggle and the rows it reveals can never disagree.
+  const isDead = (entry: ApiKey) =>
+    !!entry.revokedAt || (!!entry.expiresAt && new Date(entry.expiresAt).getTime() <= Date.now());
+
+  // Dead keys are HIDDEN by default rather than merely dimmed. Revoking is the normal end of a key's
+  // life, so on any account that has been used for a while the dead ones outnumber the live ones and the
+  // screen stops answering the question it exists for — which of my keys still work. The rows are kept
+  // and reachable; they are just not the first thing shown.
+  const deadKeys = allKeys.filter(isDead);
+  const keys = showRevoked ? allKeys : allKeys.filter((entry) => !isDead(entry));
 
   if (isLoading) {
     return (
@@ -102,8 +124,8 @@ export const ApiKeys = () => {
   return (
     <div className="grid gap-5">
       <p className="text-sm text-duck-dark/70 dark:text-foreground/70">
-        An API key signs in as you, without a password and without expiring. Give each app or device its own, so you can
+        An API key signs in as you, without a password and without expiring. One key works everywhere — a key is not
-        cut one off without touching the rest. Send it as{' '}
+        tied to an app. Giving each device its own is only so you can cut one off without touching the rest. Send it as{' '}
         <code className="font-mono text-xs">Authorization: Bearer …</code>.
       </p>
 
@@ -150,7 +172,9 @@ export const ApiKeys = () => {
 
       {keys.length === 0 ? (
         <div className="rounded-lg border border-dashed border-duck-dark/15 dark:border-foreground/15 p-6 text-center text-sm text-duck-dark/40 dark:text-foreground/40">
-          No keys yet.
+          {/* "No keys yet" would be false on an account whose keys are all revoked, and it is the sentence
+              that would send somebody looking for a bug in the list. */}
+          {allKeys.length === 0 ? 'No keys yet.' : 'No keys in use.'}
         </div>
       ) : (
         <div className="grid gap-2">
@@ -181,11 +205,23 @@ export const ApiKeys = () => {
                     {lastUsed ? `last used ${lastUsed}` : 'never used'}
                   </div>
                 </div>
-                {!dead && (
+                {dead ? (
+                  // Only offered once the key is already dead — the server refuses it otherwise, and the
+                  // button matching that rule is what keeps the two from drifting.
                   <Button
                     variant="ghost"
                     size="sm"
-                    onClick={() => revoke(entry.id)}
+                    onClick={() => void forget(entry.id)}
+                    title="Remove this record"
+                    className="hover:text-red-500"
+                  >
+                    <Trash2 className="h-3.5 w-3.5" />
+                  </Button>
+                ) : (
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => void revoke(entry.id)}
                     title="Revoke"
                     className="hover:text-red-500"
                   >
@@ -197,6 +233,18 @@ export const ApiKeys = () => {
           })}
         </div>
       )}
+
+      {deadKeys.length > 0 && (
+        <button
+          type="button"
+          onClick={() => setShowRevoked((v) => !v)}
+          className="mt-3 cursor-pointer text-xs text-duck-dark/40 underline underline-offset-2 transition-colors hover:text-duck-dark/70 dark:text-foreground/40 dark:hover:text-foreground/70"
+        >
+          {showRevoked
+            ? 'Hide revoked and expired'
+            : `Show ${deadKeys.length} revoked or expired key${deadKeys.length === 1 ? '' : 's'}`}
+        </button>
+      )}
     </div>
   );
 };

src/apps/officer-web/Screens/Dashboard/Settings/ProfileSettings/index.tsx

@@ -1,11 +1,12 @@
 import { useMemo } from 'react';
-import { User, Lock, Globe, LayoutGrid, Volume2 } from 'lucide-react';
+import { User, Lock, Globe, KeyRound, LayoutGrid, Volume2 } from 'lucide-react';
 import type { LayoutNode, PanelComponents } from 'officerdev';
 import { WorkspaceLayout } from 'officerdev';
 
 import { SettingsRoute, createSettingsPanelComponents, type SettingsSection } from '../SettingsPanel';
 import { UserData } from './UserData';
 import { ChangePassword } from './ChangePassword';
+import { ApiKeys } from './ApiKeys';
 import { Languages } from './Languages';
 import { DockSettings } from './DockSettings';
 import { VoicePreference } from './VoicePreference';
@@ -21,6 +22,17 @@ const sections: SettingsSection[] = [
     description: 'Update your password',
     content: <ChangePassword />,
   },
+  // Beside the password rather than under Integrations, where it was until 2026-08-21. A key is not an
+  // integration with anything — it is a second way to present the authority this account already has, and
+  // the permission registry says so: `/api-keys` is `core`, sitting with `/user` and `/dock`. Somebody
+  // looking for it went to user management and then to profile, which is where it should have been.
+  {
+    key: 'api-keys',
+    icon: KeyRound,
+    title: 'API keys',
+    description: 'Keys that sign in as you, revocable one at a time',
+    content: <ApiKeys />,
+  },
   {
     key: 'languages',
     icon: Globe,

src/apps/officer-web/Screens/Dashboard/Settings/ServerSettings/AIHarnessesSection.tsx

@@ -290,7 +290,7 @@ export const AIHarnessesSection = () => {
                 {localProviders.map((lp: LocalProviderEntry) => (
                   <div key={lp.id} className="flex items-center gap-2">
                     <span
-                      className={`inline-block h-2 w-2 shrink-0 rounded-full ${lp.id in localHealth ? (localHealth[lp.id] ? 'bg-green-500' : 'bg-red-500') : 'bg-duck-dark/20'}`}
+                      className={`inline-block h-2 w-2 shrink-0 rounded-full ${lp.id in localHealth ? (localHealth[lp.id] ? 'bg-success' : 'bg-red-500') : 'bg-duck-dark/20'}`}
                       title={lp.id in localHealth ? (localHealth[lp.id] ? 'Online' : 'Offline') : 'Checking...'}
                     />
                     <span className="text-duck-dark/70 dark:text-foreground/70 font-medium">{lp.name}</span>
@@ -439,7 +439,7 @@ export const AIHarnessesSection = () => {
                       <span
                         className={`inline-block h-2 w-2 shrink-0 rounded-full ${
                           remoteHealth[provider.providerId] === true
-                            ? 'bg-green-500'
+                            ? 'bg-success'
                             : remoteHealth[provider.providerId] === false
                               ? 'bg-red-500'
                               : 'bg-duck-dark/20'

src/apps/officer-web/Screens/Dashboard/Settings/ServerSettings/MaintenanceSection.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { Hammer, Loader2, RotateCw } from 'lucide-react';
+import { Download, Hammer, Loader2, RotateCw } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import { useClient } from 'hooks/useClient';
@@ -31,10 +31,45 @@ export function errorMessage(err: unknown, fallback: string): string {
 
 export const MaintenanceSection = () => {
   const client = useClient();
+  const [pulling, setPulling] = useState(false);
+  const [pulled, setPulled] = useState<{ from: string; to: string; commits: string[]; needs: string[] } | null>(null);
   const [rebuilding, setRebuilding] = useState(false);
   const [restarting, setRestarting] = useState(false);
   const [lastBuild, setLastBuild] = useState<string | null>(null);
 
+  /**
+   * Pull, and then say what the pull implies rather than acting on it.
+   *
+   * Deliberately does not chain into a rebuild or a restart. A pull that touched `bun.lock` means an
+   * install, which the frozen-lockfile rule exists to keep deliberate; one that touched a schema means
+   * `db:push` against a live database. Neither is a thing a button should decide, so `needs` is reported
+   * and the buttons below stay where they are.
+   */
+  const pull = async () => {
+    setPulling(true);
+    try {
+      const res = await client.post<{
+        ok: boolean;
+        updated: boolean;
+        from?: string;
+        to?: string;
+        commits: string[];
+        needs: string[];
+      }>('/server-settings/pull', {});
+      if (!res.updated) {
+        setPulled(null);
+        toast.success('Already up to date');
+        return;
+      }
+      setPulled({ from: res.from ?? '', to: res.to ?? '', commits: res.commits, needs: res.needs });
+      toast.success(`Pulled ${res.commits.length} commit${res.commits.length === 1 ? '' : 's'}`);
+    } catch (err) {
+      toast.error(errorMessage(err, 'Pull failed'));
+    } finally {
+      setPulling(false);
+    }
+  };
+
   const rebuild = async () => {
     setRebuilding(true);
     try {
@@ -90,6 +125,43 @@ export const MaintenanceSection = () => {
   return (
     <div className="flex flex-col gap-6">
       <div className="flex items-start justify-between gap-6">
+        <div className="min-w-0">
+          <div className="text-sm font-medium text-foreground">Update the platform</div>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Pulls this server&rsquo;s repository. Refuses if anything is uncommitted or the checkout has diverged — it
+            will never discard local work.
+          </p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Changes nothing that is running. Whatever the update needs is listed here, and stays your call.
+          </p>
+          {pulled && (
+            <div className="mt-2 rounded-md border border-border bg-muted/40 p-2">
+              <p className="font-mono text-[11px] text-muted-foreground">
+                {pulled.from} → {pulled.to}
+              </p>
+              <ul className="mt-1 space-y-0.5">
+                {pulled.commits.slice(0, 5).map((line) => (
+                  <li key={line} className="truncate text-[11px] text-foreground/80">
+                    {line}
+                  </li>
+                ))}
+                {pulled.commits.length > 5 && (
+                  <li className="text-[11px] text-muted-foreground">+{pulled.commits.length - 5} more</li>
+                )}
+              </ul>
+              {pulled.needs.length > 0 && (
+                <p className="mt-1.5 text-[11px] text-warning">Needs: {pulled.needs.join(', ')}</p>
+              )}
+            </div>
+          )}
+        </div>
+        <Button disabled={pulling || rebuilding || restarting} onClick={() => void pull()} className="shrink-0">
+          {pulling ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Download className="mr-2 h-4 w-4" />}
+          {pulling ? 'Pulling…' : 'Update'}
+        </Button>
+      </div>
+
+      <div className="flex items-start justify-between gap-6 border-t border-border pt-6">
         <div className="min-w-0">
           <div className="text-sm font-medium text-foreground">Rebuild the frontend</div>
           <p className="mt-1 text-xs text-muted-foreground">
@@ -98,7 +170,7 @@ export const MaintenanceSection = () => {
           </p>
           {lastBuild && <p className="mt-1 text-xs text-muted-foreground/70">Last build: {lastBuild}</p>}
         </div>
-        <Button disabled={rebuilding || restarting} onClick={() => void rebuild()} className="shrink-0">
+        <Button disabled={pulling || rebuilding || restarting} onClick={() => void rebuild()} className="shrink-0">
           {rebuilding ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Hammer className="mr-2 h-4 w-4" />}
           {rebuilding ? 'Building…' : 'Rebuild'}
         </Button>
@@ -118,7 +190,7 @@ export const MaintenanceSection = () => {
         </div>
         <Button
           variant="destructive"
-          disabled={rebuilding || restarting}
+          disabled={pulling || rebuilding || restarting}
           onClick={() => void restart()}
           className="shrink-0"
         >

src/apps/officer-web/Screens/Dashboard/index.tsx

@@ -20,7 +20,5 @@ export * from './CodeEditor';
 export * from './ChatHistory';
 export * from './Dashboards';
 export * from './Terminal';
-export * from './Browser';
-export * from './Desktop';
 export * from './Jobs';
 export * from './QrTransfer';

src/apps/officer-web/styles/prose.css

@@ -169,8 +169,11 @@
 .code-surface pre {
   margin: 0;
   padding: 0.75em 1em;
-  /* Room for the two copy buttons, so a long first line scrolls up to them rather than under them. */
+  /* Room for the copy controls, which sit absolutely at the bottom-right of the block. Horizontal so a
+     long line scrolls past them rather than under them; vertical so the LAST line — the one they now
+     overlap — keeps its own space. */
   padding-right: 5.5em;
+  padding-bottom: 2em;
   border-radius: 0.5rem;
   background: #0d1117;
   /* Scroll, never wrap: wrapping folds `ls -la`, `git log --oneline` and any other columnar output into
@@ -186,6 +189,12 @@
   padding-right: 10em;
 }
 
+/* The positioning context for those controls. Without it they escape to the nearest positioned ancestor,
+   which is how a copy button ends up floating below the block it belongs to. */
+.code-surface {
+  position: relative;
+}
+
 .code-surface pre code {
   padding: 0;
   border-radius: 0;

src/databases/officer_db/src/api-keys/index.ts

@@ -3,6 +3,7 @@ export {
   createApiKey,
   listApiKeys,
   revokeApiKey,
+  deleteApiKey,
   touchApiKey,
   type ApiKeyIdentity,
 } from './queries';

src/databases/officer_db/src/api-keys/queries.ts

@@ -1,4 +1,4 @@
-import { eq, and, isNull, sql } from 'drizzle-orm';
+import { eq, and, isNull, isNotNull, sql } from 'drizzle-orm';
 import { db } from '../db';
 import { apiKeys } from './schema';
 import { users } from '../auth/schema';
@@ -99,6 +99,32 @@ export async function revokeApiKey(id: number, userId: number): Promise<boolean>
   return rows.length > 0;
 }
 
+/**
+ * Delete a revoked key's row for good.
+ *
+ * Separate from revoking, and only reachable AFTER it — the `revokedAt is not null` clause is in the
+ * statement rather than checked before it, so there is no window where a live key is deleted by a request
+ * that raced a revoke.
+ *
+ * ── Why this is a second step and not what revoke does ──
+ *
+ * The row IS the record that the key existed. `lastUsedAt` is the only evidence of whether a leaked key
+ * was used before it was killed, and on what date; deleting on revoke would throw that away at exactly
+ * the moment somebody most wants it. So revoke keeps everything and this exists for afterwards, when the
+ * question has been answered and the row is only clutter.
+ *
+ * Deleting is safe in a way it would not be for a password: the key can never be honoured again either
+ * way, because `authenticate` matches on a hash that no longer has a row. Losing the row loses the
+ * history, not the protection.
+ */
+export async function deleteApiKey(id: number, userId: number): Promise<boolean> {
+  const rows = await db
+    .delete(apiKeys)
+    .where(and(eq(apiKeys.id, id), eq(apiKeys.userId, userId), isNotNull(apiKeys.revokedAt)))
+    .returning({ id: apiKeys.id });
+  return rows.length > 0;
+}
+
 /** How stale last_used_at is allowed to get. A write per request is not worth this column's value. */
 const TOUCH_DEBOUNCE_MS = 60_000;
 

src/databases/officer_db/src/auth/index.ts

@@ -25,3 +25,5 @@ export {
 export { USER_ROLES, OWNER_USER_ID } from './schema';
 
 export type { UserRole } from './schema';
+export { listProvisionableUsers } from './queries';
+export type { ProvisionableUser } from './queries';

src/databases/officer_db/src/auth/queries.ts

@@ -1,4 +1,4 @@
-import { eq, and, lt, sql } from 'drizzle-orm';
+import { eq, ne, and, lt, sql } from 'drizzle-orm';
 import { db } from '../db';
 import { users, passkeys, passkeyChallenges, tokenBlacklist, OWNER_USER_ID } from './schema';
 import type { UserSelect, UserInsert, PasskeySelect, PasskeyInsert } from '../types';
@@ -9,6 +9,40 @@ export async function getUsers(): Promise<UserSelect[]> {
   return db.select().from(users);
 }
 
+/** What a plugin is told about an account. Deliberately not a `UserSelect`. */
+export type ProvisionableUser = {
+  id: number;
+  email: string;
+  username: string | null;
+  name: string | null;
+  role: string;
+};
+
+/**
+ * The accounts a plugin may provision in its upstream service.
+ *
+ * A hand-written projection, NOT `select *`. `users` holds `password` (the hash) and `os_user`, and
+ * `getUsers()` returns both — so a plugin reaching for the obvious function gets every account's
+ * password hash. The columns are named here so that cannot happen by accident: adding a secret to the
+ * table does not silently add it to what plugins receive.
+ *
+ * The OWNER is excluded. They are user 1 by CHECK constraint, they bypass every permission check, and
+ * they already have whatever account they want upstream — provisioning them is at best a no-op and at
+ * worst a second admin nobody asked for.
+ */
+export async function listProvisionableUsers(): Promise<ProvisionableUser[]> {
+  return db
+    .select({
+      id: users.id,
+      email: users.email,
+      username: users.username,
+      name: users.name,
+      role: users.role,
+    })
+    .from(users)
+    .where(ne(users.id, OWNER_USER_ID));
+}
+
 export async function getUserById(id: number): Promise<UserSelect | undefined> {
   const [user] = await db.select().from(users).where(eq(users.id, id));
   return user;
@@ -22,8 +56,23 @@ export async function getUserByEmail(email: string): Promise<UserSelect | undefi
 // `username` is unique in the schema, so this exists to turn a would-be constraint violation into a
 // sentence. Creating an account is a form someone fills in, and "duplicate key value violates unique
 // constraint users_username_unique" is not an answer to give them.
+/**
+ * Case-INSENSITIVE, deliberately.
+ *
+ * This compared with `eq` until 2026-08-20, which made `diogo` and `DIOGO` two different accounts. That
+ * is a problem on its own — a person typing their own name with the wrong shift key is not a different
+ * person — and it becomes a real one downstream: Jellyfin enforces uniqueness on an uppercased
+ * `NormalizedUsername`, so two Officer accounts that Officer thinks are distinct collide there and the
+ * second cannot be provisioned at all.
+ *
+ * The unique index in `schema.ts` is on `lower(username)` for the same reason, so this cannot be the only
+ * thing standing between two colliding names.
+ */
 export async function getUserByUsername(username: string): Promise<UserSelect | undefined> {
-  const [user] = await db.select().from(users).where(eq(users.username, username));
+  const [user] = await db
+    .select()
+    .from(users)
+    .where(sql`lower(${users.username}) = lower(${username})`);
   return user;
 }
 

src/databases/officer_db/src/auth/schema.ts

@@ -34,7 +34,14 @@ export const users = pgTable(
     // authorisation cannot accidentally mint an admin.
     role: text('role', { enum: USER_ROLES }).notNull().default('Member'),
     name: text('name'),
-    username: text('username').unique(),
+    /**
+     * Required, and unique case-INSENSITIVELY — see the index below.
+     *
+     * `validateUsername` has always demanded one, but the column allowed null, so a code path that
+     * skipped validation could write a user nobody could name. Anything downstream that identifies a
+     * person by username — a Linux account, a Jellyfin login — then has nothing to work with.
+     */
+    username: text('username').notNull(),
     /**
      * The Linux account this platform account runs as, when per-user OS accounts are enabled.
      *
@@ -69,6 +76,15 @@ export const users = pgTable(
     // Two accounts must not share one Linux user — that would make "whose uid is this" ambiguous for a
     // shell. An index rather than a constraint: see the note on the column.
     uniqueIndex('uq_users_os_user').on(table.osUser),
+    // Usernames are unique CASE-INSENSITIVELY. `diogo` and `DIOGO` are one name.
+    //
+    // On `lower(username)` rather than the column, because a plain unique index would let both exist —
+    // which was the state until 2026-08-20. Two consequences, and the second is why it is a constraint
+    // rather than a check in `create-user.ts`: a person cannot accidentally register a shadow of their
+    // own account, and anything identifying them downstream by name gets one answer. Jellyfin enforces
+    // uniqueness on an uppercased `NormalizedUsername`, so two Officer accounts Officer thought were
+    // distinct collide there, and the second is unprovisionable with no way to see why from this side.
+    uniqueIndex('uq_users_username_lower').on(sql`lower(${table.username})`),
     // The owner cannot be demoted. Enforced here rather than in application code because the whole
     // point is that it holds "whatever happens" — a stray UPDATE, a migration script, someone at a psql
     // prompt. Postgres rejects the write; there is no path around it.

src/databases/officer_db/src/index.ts

@@ -35,6 +35,7 @@ export * from './permissions';
 export * from './chat-events';
 export * from './chat-session-models';
 export * from './chat-notification-prefs';
+export * from './nudges';
 export * from './ai-provider-usage';
 export * from './command-hq';
 export * from './dashboards';

src/databases/officer_db/src/nudges/index.ts

@@ -0,0 +1 @@
+export { setNudge, getNudge, cancelNudge, dueNudges, recordNudgeSent } from './queries';

src/databases/officer_db/src/nudges/queries.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'bun:test';
+import { dueNudges } from './queries';
+
+describe('dueNudges', () => {
+  // It failed on EVERY tick and the only symptom was a log line nobody was reading: the row sat there
+  // enabled, with sent_count 0, looking perfectly armed. A JS Date bound as a parameter on the left of an
+  // interval subtraction is a type Postgres will not infer, so it refused the whole statement.
+  //
+  // Asserting only that it EXECUTES. The due-ness logic is Postgres arithmetic; what broke was the SQL
+  // being invalid, which no amount of reasoning about intervals would have caught.
+  test('is valid SQL against the real database', async () => {
+    expect(Array.isArray(await dueNudges())).toBe(true);
+  });
+});

src/databases/officer_db/src/nudges/queries.ts

@@ -0,0 +1,83 @@
+import { and, eq, lt, or, isNull, sql } from 'drizzle-orm';
+import { db } from '../db';
+import { nudges } from './schema';
+import type { NudgeSelect } from '../types';
+
+/** Create or replace the schedule for one session. Re-arming resets the count — it is a new night. */
+export async function setNudge(params: {
+  userId: number;
+  sessionId: string;
+  message: string;
+  everySeconds: number;
+  maxCount: number;
+}): Promise<NudgeSelect> {
+  const [row] = await db
+    .insert(nudges)
+    .values({ ...params, enabled: true, sentCount: 0, lastFiredAt: null })
+    .onConflictDoUpdate({
+      target: [nudges.userId, nudges.sessionId],
+      set: {
+        message: params.message,
+        everySeconds: params.everySeconds,
+        maxCount: params.maxCount,
+        enabled: true,
+        sentCount: 0,
+        lastFiredAt: null,
+        updatedAt: new Date(),
+      },
+    })
+    .returning();
+  return row!;
+}
+
+export async function getNudge(userId: number, sessionId: string): Promise<NudgeSelect | null> {
+  const [row] = await db
+    .select()
+    .from(nudges)
+    .where(and(eq(nudges.userId, userId), eq(nudges.sessionId, sessionId)))
+    .limit(1);
+  return row ?? null;
+}
+
+export async function cancelNudge(userId: number, sessionId: string): Promise<void> {
+  await db.delete(nudges).where(and(eq(nudges.userId, userId), eq(nudges.sessionId, sessionId)));
+}
+
+/**
+ * Everything the scheduler should consider this tick.
+ *
+ * Due means: enabled, under its ceiling, and either never fired or last fired at least `every_seconds`
+ * ago. Whether the session is actually IDLE is not asked here — that lives in the sidecar, not the
+ * database, and the scheduler checks it immediately before speaking.
+ */
+export async function dueNudges(): Promise<NudgeSelect[]> {
+  return db
+    .select()
+    .from(nudges)
+    .where(
+      and(
+        eq(nudges.enabled, true),
+        lt(nudges.sentCount, nudges.maxCount),
+        or(
+          isNull(nudges.lastFiredAt),
+          // `now()` in SQL rather than a JS Date bound as a parameter. Postgres cannot infer the type of
+          // a parameter on the left of an interval subtraction and refuses the whole statement — which
+          // failed EVERY tick, silently, with the row sitting there looking armed.
+          lt(nudges.lastFiredAt, sql`now() - (${nudges.everySeconds} * interval '1 second')`),
+        ),
+      ),
+    );
+}
+
+/** One nudge delivered. Disables itself on reaching the ceiling rather than leaving a spent row armed. */
+export async function recordNudgeSent(id: number): Promise<void> {
+  await db
+    .update(nudges)
+    .set({
+      sentCount: sql`${nudges.sentCount} + 1`,
+      lastFiredAt: new Date(),
+      updatedAt: new Date(),
+      enabled: sql`${nudges.sentCount} + 1 < ${nudges.maxCount}`,
+    })
+    .where(eq(nudges.id, id));
+}

src/databases/officer_db/src/nudges/schema.ts

@@ -0,0 +1,42 @@
+import { pgTable, serial, integer, text, boolean, timestamp, check, uniqueIndex } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+import { users } from '../auth/schema';
+
+// Nudger: keep a chat moving while nobody is watching it.
+//
+// An agent told to record blockers and continue will still stop at the end of a turn, and at 3am nobody
+// types the next message. This is the schedule that does.
+//
+// One nudge per (user, session). A second schedule for the same conversation is not a feature — it is two
+// alarms for one sleeper, and the only thing it reliably produces is a doubled prompt.
+
+export const nudges = pgTable(
+  'nudges',
+  {
+    id: serial('id').primaryKey(),
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    /** The chat session's transcript uuid — the same key `chat_session_models` uses. */
+    sessionId: text('session_id').notNull(),
+    message: text('message').notNull(),
+    everySeconds: integer('every_seconds').notNull().default(3600),
+    /** A loop nobody is watching should end on its own. */
+    maxCount: integer('max_count').notNull().default(12),
+    sentCount: integer('sent_count').notNull().default(0),
+    enabled: boolean('enabled').notNull().default(true),
+    /** Null until the first send. The scheduler treats null as "due now". */
+    lastFiredAt: timestamp('last_fired_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    // uniqueIndex, not unique().on() — drizzle-kit re-creates named composite CONSTRAINTS on every push.
+    // See src/databases/CLAUDE.md → "Composite keys".
+    uniqueIndex('uq_nudges_user_session').on(table.userId, table.sessionId),
+    // A floor, because the scheduler ticks once a minute and anything under that is a lie about cadence
+    // rather than a faster nudge.
+    check('ck_nudges_every_seconds', sql`${table.everySeconds} >= 60`),
+    check('ck_nudges_max_count', sql`${table.maxCount} > 0`),
+  ],
+);

src/databases/officer_db/src/schema.ts

@@ -45,6 +45,7 @@ export * from './app-store/schema'; // sidecar_installs
 export * from './plugins/schema'; // plugin_installs — core: the plugin system is the platform's own
 export * from './service-connections/schema'; // service_connections
 export * from './notify/schema'; // push_devices — core since 2026-08-19, see docs/push-notifications.md
+export * from './nudges/schema'; // nudges — the Nudger schedule
 
 // ── Plugins — uncomment when the plugin is installed ─────────────────────────────────────────────
 

src/databases/officer_db/src/types.ts

@@ -82,6 +82,7 @@ export type PipelineJobSelect = typeof Schema.pipelineJobs.$inferSelect;
 export type PipelineJobInsert = typeof Schema.pipelineJobs.$inferInsert;
 
 // Notifications
+export type NudgeSelect = typeof Schema.nudges.$inferSelect;
 export type PushDeviceSelect = typeof NotifySchema.pushDevices.$inferSelect;
 export type PushDeviceInsert = typeof NotifySchema.pushDevices.$inferInsert;
 

src/extensions/browser-relay/SETUP.md

@@ -1,45 +0,0 @@
-# Officer Browser Relay — Setup Guide
-
-## Prerequisites
-- Officer server running (`bun dev`)
-- Google Chrome or Chromium-based browser on your machine
-- Both machines on the same Tailscale network (or localhost for local dev)
-
-## Steps
-
-### 1. Verify relay is running
-Check the server logs for `[browser-relay] listening on port 18792`.
-
-### 2. Get your relay credentials
-Open Officer dashboard → **Browser** screen (or `/browser`).
-The setup card shows your **server address**, **port**, and **relay token**.
-
-### 3. Load the extension in Chrome
-1. Open `chrome://extensions`
-2. Enable **Developer mode** (top-right toggle)
-3. Click **Load unpacked**
-4. Select `src/extensions/browser-relay/`
-
-### 4. Configure the extension
-1. The options page opens automatically after install (or right-click extension → Options)
-2. Enter the **Server address** (Officer's IP — e.g. your Tailscale IP, or `127.0.0.1` for local)
-3. Enter the **Port** (default `18792`)
-4. Paste your **Relay token** from step 2
-5. Click **Save** — status should show green "Relay reachable and authenticated"
-
-### 5. Attach a tab
-1. Navigate to any webpage in Chrome
-2. Click the Officer Browser Relay extension icon in the toolbar
-3. Badge shows **ON** (cyan) = attached
-
-### 6. Use from the dashboard
-1. Open `/browser` in Officer
-2. Your attached tab appears in the left panel
-3. Click it to see a live screenshot in the right panel
-4. Use the URL bar to navigate, or the JS console to evaluate expressions
-
-## Troubleshooting
-- **Red `!` badge**: Relay not reachable — check server address/port/token
-- **`…` badge**: Reconnecting — relay was temporarily unavailable
-- **Tab not appearing**: Make sure the extension badge shows ON, and refresh the dashboard
-- **Screenshot blank**: The tab may be on a `chrome://` page (not supported by CDP)

src/extensions/browser-relay/background-utils.js

@@ -1,51 +0,0 @@
-// Based on OpenClaw Browser Extension Relay (MIT License)
-// https://github.com/nicepkg/openclaw
-
-export function reconnectDelayMs(
-  attempt,
-  opts = { baseMs: 1000, maxMs: 30000, jitterMs: 1000, random: Math.random },
-) {
-  const baseMs = Number.isFinite(opts.baseMs) ? opts.baseMs : 1000;
-  const maxMs = Number.isFinite(opts.maxMs) ? opts.maxMs : 30000;
-  const jitterMs = Number.isFinite(opts.jitterMs) ? opts.jitterMs : 1000;
-  const random = typeof opts.random === "function" ? opts.random : Math.random;
-  const safeAttempt = Math.max(0, Number.isFinite(attempt) ? attempt : 0);
-  const backoff = Math.min(baseMs * 2 ** safeAttempt, maxMs);
-  return backoff + Math.max(0, jitterMs) * random();
-}
-
-export async function deriveRelayToken(gatewayToken, port) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    enc.encode(gatewayToken),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"],
-  );
-  const sig = await crypto.subtle.sign(
-    "HMAC",
-    key,
-    enc.encode(`officer-browser-relay-v1:${port}`),
-  );
-  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-
-export async function buildRelayWsUrl(host, port, gatewayToken) {
-  const token = String(gatewayToken || "").trim();
-  if (!token) {
-    throw new Error(
-      "Missing relay token in extension settings (chrome.storage.local.relayToken)",
-    );
-  }
-  // Token is already derived server-side — use it directly
-  return `ws://${host}:${port}/extension?token=${encodeURIComponent(token)}`;
-}
-
-export function isRetryableReconnectError(err) {
-  const message = err instanceof Error ? err.message : String(err || "");
-  if (message.includes("Missing relay token")) {
-    return false;
-  }
-  return true;
-}

src/extensions/browser-relay/background.js

@@ -1,978 +0,0 @@
-// Based on OpenClaw Browser Extension Relay (MIT License)
-// https://github.com/nicepkg/openclaw
-
-import { buildRelayWsUrl, isRetryableReconnectError, reconnectDelayMs } from './background-utils.js'
-
-const DEFAULT_PORT = 18792
-const DEFAULT_HOST = '127.0.0.1'
-
-const BADGE = {
-  on: { text: 'ON', color: '#06b6d4' },
-  off: { text: '', color: '#000000' },
-  connecting: { text: '…', color: '#F59E0B' },
-  error: { text: '!', color: '#B91C1C' },
-}
-
-/** @type {WebSocket|null} */
-let relayWs = null
-/** @type {Promise<void>|null} */
-let relayConnectPromise = null
-let relayGatewayToken = ''
-/** @type {string|null} */
-let relayConnectRequestId = null
-
-let nextSession = 1
-
-/** @type {Map<number, {state:'connecting'|'connected', sessionId?:string, targetId?:string, attachOrder?:number}>} */
-const tabs = new Map()
-/** @type {Map<string, number>} */
-const tabBySession = new Map()
-/** @type {Map<string, number>} */
-const childSessionToTab = new Map()
-
-/** @type {Map<number, {resolve:(v:any)=>void, reject:(e:Error)=>void}>} */
-const pending = new Map()
-
-/** @type {Set<number>} */
-const tabOperationLocks = new Set()
-
-/** @type {Set<number>} */
-const reattachPending = new Set()
-
-/** @type {Set<number>} */
-const reattachingTabs = new Set()
-
-let reconnectAttempt = 0
-let reconnectTimer = null
-
-async function getRelayPort() {
-  const stored = await chrome.storage.local.get(['relayPort'])
-  const raw = stored.relayPort
-  const n = Number.parseInt(String(raw || ''), 10)
-  if (!Number.isFinite(n) || n <= 0 || n > 65535) return DEFAULT_PORT
-  return n
-}
-
-async function getRelayHost() {
-  const stored = await chrome.storage.local.get(['relayHost'])
-  const host = String(stored.relayHost || '').trim()
-  return host || DEFAULT_HOST
-}
-
-async function getRelayToken() {
-  const stored = await chrome.storage.local.get(['relayToken'])
-  const token = String(stored.relayToken || '').trim()
-  return token || ''
-}
-
-function setBadge(tabId, kind) {
-  const cfg = BADGE[kind]
-  void chrome.action.setBadgeText({ tabId, text: cfg.text })
-  void chrome.action.setBadgeBackgroundColor({ tabId, color: cfg.color })
-  void chrome.action.setBadgeTextColor({ tabId, color: '#FFFFFF' }).catch(() => {})
-}
-
-async function persistState() {
-  try {
-    const tabEntries = []
-    for (const [tabId, tab] of tabs.entries()) {
-      if (tab.state === 'connected' && tab.sessionId && tab.targetId) {
-        tabEntries.push({ tabId, sessionId: tab.sessionId, targetId: tab.targetId, attachOrder: tab.attachOrder })
-      }
-    }
-    await chrome.storage.session.set({
-      persistedTabs: tabEntries,
-      nextSession,
-    })
-  } catch {
-    // chrome.storage.session may not be available in all contexts.
-  }
-}
-
-async function rehydrateState() {
-  try {
-    const stored = await chrome.storage.session.get(['persistedTabs', 'nextSession'])
-    if (stored.nextSession) {
-      nextSession = Math.max(nextSession, stored.nextSession)
-    }
-    const entries = stored.persistedTabs || []
-    for (const entry of entries) {
-      tabs.set(entry.tabId, {
-        state: 'connected',
-        sessionId: entry.sessionId,
-        targetId: entry.targetId,
-        attachOrder: entry.attachOrder,
-      })
-      tabBySession.set(entry.sessionId, entry.tabId)
-      setBadge(entry.tabId, 'on')
-    }
-    for (const entry of entries) {
-      try {
-        await chrome.tabs.get(entry.tabId)
-        await chrome.debugger.sendCommand({ tabId: entry.tabId }, 'Runtime.evaluate', {
-          expression: '1',
-          returnByValue: true,
-        })
-      } catch {
-        tabs.delete(entry.tabId)
-        tabBySession.delete(entry.sessionId)
-        setBadge(entry.tabId, 'off')
-      }
-    }
-  } catch {
-    // Ignore rehydration errors.
-  }
-}
-
-async function ensureRelayConnection() {
-  if (relayWs && relayWs.readyState === WebSocket.OPEN) return
-  if (relayConnectPromise) return await relayConnectPromise
-
-  relayConnectPromise = (async () => {
-    const port = await getRelayPort()
-    const host = await getRelayHost()
-    const token = await getRelayToken()
-    const httpBase = `http://${host}:${port}`
-    const wsUrl = await buildRelayWsUrl(host, port, token)
-
-    try {
-      await fetch(`${httpBase}/`, { method: 'HEAD', signal: AbortSignal.timeout(2000) })
-    } catch (err) {
-      throw new Error(`Relay server not reachable at ${httpBase} (${String(err)})`)
-    }
-
-    const ws = new WebSocket(wsUrl)
-    relayWs = ws
-    relayGatewayToken = token
-    ws.onmessage = (event) => {
-      if (ws !== relayWs) return
-      void whenReady(() => onRelayMessage(String(event.data || '')))
-    }
-
-    await new Promise((resolve, reject) => {
-      const t = setTimeout(() => reject(new Error('WebSocket connect timeout')), 5000)
-      ws.onopen = () => {
-        clearTimeout(t)
-        resolve()
-      }
-      ws.onerror = () => {
-        clearTimeout(t)
-        reject(new Error('WebSocket connect failed'))
-      }
-      ws.onclose = (ev) => {
-        clearTimeout(t)
-        reject(new Error(`WebSocket closed (${ev.code} ${ev.reason || 'no reason'})`))
-      }
-    })
-
-    ws.onclose = (ev) => {
-      if (ws !== relayWs) return
-      if (ev.code === 4000) {
-        onRelayReplaced()
-        return
-      }
-      onRelayClosed('closed')
-    }
-    ws.onerror = () => {
-      if (ws !== relayWs) return
-      onRelayClosed('error')
-    }
-  })()
-
-  try {
-    await relayConnectPromise
-    reconnectAttempt = 0
-  } finally {
-    relayConnectPromise = null
-  }
-}
-
-function onRelayClosed(reason) {
-  relayWs = null
-  relayGatewayToken = ''
-  relayConnectRequestId = null
-
-  for (const [id, p] of pending.entries()) {
-    pending.delete(id)
-    p.reject(new Error(`Relay disconnected (${reason})`))
-  }
-
-  reattachPending.clear()
-
-  for (const [tabId, tab] of tabs.entries()) {
-    if (tab.state === 'connected') {
-      setBadge(tabId, 'connecting')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay: relay reconnecting…',
-      })
-    }
-  }
-
-  scheduleReconnect()
-}
-
-function onRelayReplaced() {
-  relayWs = null
-  relayGatewayToken = ''
-  relayConnectRequestId = null
-
-  for (const [id, p] of pending.entries()) {
-    pending.delete(id)
-    p.reject(new Error('Replaced by another browser session'))
-  }
-
-  reattachPending.clear()
-
-  for (const [tabId, tab] of tabs.entries()) {
-    if (tab.state === 'connected') {
-      setBadge(tabId, 'error')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay: replaced by another browser — click to reconnect',
-      })
-    }
-  }
-  // Do NOT schedule reconnect — user must click to take over again
-}
-
-function scheduleReconnect() {
-  if (reconnectTimer) {
-    clearTimeout(reconnectTimer)
-    reconnectTimer = null
-  }
-
-  const delay = reconnectDelayMs(reconnectAttempt)
-  reconnectAttempt++
-
-  console.log(`Scheduling reconnect attempt ${reconnectAttempt} in ${Math.round(delay)}ms`)
-
-  reconnectTimer = setTimeout(async () => {
-    reconnectTimer = null
-    try {
-      await ensureRelayConnection()
-      reconnectAttempt = 0
-      console.log('Reconnected successfully')
-      await reannounceAttachedTabs()
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err)
-      console.warn(`Reconnect attempt ${reconnectAttempt} failed: ${message}`)
-      if (!isRetryableReconnectError(err)) {
-        return
-      }
-      scheduleReconnect()
-    }
-  }, delay)
-}
-
-function cancelReconnect() {
-  if (reconnectTimer) {
-    clearTimeout(reconnectTimer)
-    reconnectTimer = null
-  }
-  reconnectAttempt = 0
-}
-
-async function reannounceAttachedTabs() {
-  for (const [tabId, tab] of tabs.entries()) {
-    if (tab.state !== 'connected' || !tab.sessionId || !tab.targetId) continue
-
-    try {
-      await chrome.debugger.sendCommand({ tabId }, 'Runtime.evaluate', {
-        expression: '1',
-        returnByValue: true,
-      })
-    } catch {
-      tabs.delete(tabId)
-      if (tab.sessionId) tabBySession.delete(tab.sessionId)
-      setBadge(tabId, 'off')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay (click to attach/detach)',
-      })
-      continue
-    }
-
-    try {
-      const info = /** @type {any} */ (
-        await chrome.debugger.sendCommand({ tabId }, 'Target.getTargetInfo')
-      )
-      const targetInfo = info?.targetInfo
-
-      sendToRelay({
-        method: 'forwardCDPEvent',
-        params: {
-          method: 'Target.attachedToTarget',
-          params: {
-            sessionId: tab.sessionId,
-            targetInfo: { ...targetInfo, attached: true },
-            waitingForDebugger: false,
-          },
-        },
-      })
-
-      setBadge(tabId, 'on')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay: attached (click to detach)',
-      })
-    } catch {
-      setBadge(tabId, 'on')
-    }
-  }
-
-  await persistState()
-}
-
-function sendToRelay(payload) {
-  const ws = relayWs
-  if (!ws || ws.readyState !== WebSocket.OPEN) {
-    throw new Error('Relay not connected')
-  }
-  ws.send(JSON.stringify(payload))
-}
-
-function ensureGatewayHandshakeStarted(payload) {
-  if (relayConnectRequestId) return
-  const nonce = typeof payload?.nonce === 'string' ? payload.nonce.trim() : ''
-  relayConnectRequestId = `ext-connect-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`
-  sendToRelay({
-    type: 'req',
-    id: relayConnectRequestId,
-    method: 'connect',
-    params: {
-      minProtocol: 3,
-      maxProtocol: 3,
-      client: {
-        id: 'officer-browser-relay-extension',
-        version: '1.0.0',
-        platform: 'chrome-extension',
-        mode: 'webchat',
-      },
-      role: 'operator',
-      scopes: ['operator.read', 'operator.write'],
-      caps: [],
-      commands: [],
-      nonce: nonce || undefined,
-      auth: relayGatewayToken ? { token: relayGatewayToken } : undefined,
-    },
-  })
-}
-
-async function maybeOpenHelpOnce() {
-  try {
-    const stored = await chrome.storage.local.get(['helpOnErrorShown'])
-    if (stored.helpOnErrorShown === true) return
-    await chrome.storage.local.set({ helpOnErrorShown: true })
-    await chrome.runtime.openOptionsPage()
-  } catch {
-    // ignore
-  }
-}
-
-function requestFromRelay(command) {
-  const id = command.id
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      pending.delete(id)
-      reject(new Error('Relay request timeout (30s)'))
-    }, 30000)
-    pending.set(id, {
-      resolve: (v) => { clearTimeout(timer); resolve(v) },
-      reject: (e) => { clearTimeout(timer); reject(e) },
-    })
-    try {
-      sendToRelay(command)
-    } catch (err) {
-      clearTimeout(timer)
-      pending.delete(id)
-      reject(err instanceof Error ? err : new Error(String(err)))
-    }
-  })
-}
-
-async function onRelayMessage(text) {
-  /** @type {any} */
-  let msg
-  try {
-    msg = JSON.parse(text)
-  } catch {
-    return
-  }
-
-  if (msg && msg.type === 'event' && msg.event === 'connect.challenge') {
-    try {
-      ensureGatewayHandshakeStarted(msg.payload)
-    } catch (err) {
-      console.warn('gateway connect handshake start failed', err instanceof Error ? err.message : String(err))
-      relayConnectRequestId = null
-      const ws = relayWs
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.close(1008, 'gateway connect failed')
-      }
-    }
-    return
-  }
-
-  if (msg && msg.type === 'res' && relayConnectRequestId && msg.id === relayConnectRequestId) {
-    relayConnectRequestId = null
-    if (!msg.ok) {
-      const detail = msg?.error?.message || msg?.error || 'gateway connect failed'
-      console.warn('gateway connect handshake rejected', String(detail))
-      const ws = relayWs
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.close(1008, 'gateway connect failed')
-      }
-    }
-    return
-  }
-
-  if (msg && msg.method === 'ping') {
-    try {
-      sendToRelay({ method: 'pong' })
-    } catch {
-      // ignore
-    }
-    return
-  }
-
-  if (msg && typeof msg.id === 'number' && (msg.result !== undefined || msg.error !== undefined)) {
-    const p = pending.get(msg.id)
-    if (!p) return
-    pending.delete(msg.id)
-    if (msg.error) p.reject(new Error(String(msg.error)))
-    else p.resolve(msg.result)
-    return
-  }
-
-  if (msg && typeof msg.id === 'number' && msg.method === 'forwardCDPCommand') {
-    try {
-      const result = await handleForwardCdpCommand(msg)
-      sendToRelay({ id: msg.id, result })
-    } catch (err) {
-      sendToRelay({ id: msg.id, error: err instanceof Error ? err.message : String(err) })
-    }
-  }
-}
-
-function getTabBySessionId(sessionId) {
-  const direct = tabBySession.get(sessionId)
-  if (direct) return { tabId: direct, kind: 'main' }
-  const child = childSessionToTab.get(sessionId)
-  if (child) return { tabId: child, kind: 'child' }
-  return null
-}
-
-function getTabByTargetId(targetId) {
-  for (const [tabId, tab] of tabs.entries()) {
-    if (tab.targetId === targetId) return tabId
-  }
-  return null
-}
-
-async function attachTab(tabId, opts = {}) {
-  const debuggee = { tabId }
-  await chrome.debugger.attach(debuggee, '1.3')
-  await chrome.debugger.sendCommand(debuggee, 'Page.enable').catch(() => {})
-
-  const info = /** @type {any} */ (await chrome.debugger.sendCommand(debuggee, 'Target.getTargetInfo'))
-  const targetInfo = info?.targetInfo
-  const targetId = String(targetInfo?.targetId || '').trim()
-  if (!targetId) {
-    throw new Error('Target.getTargetInfo returned no targetId')
-  }
-
-  const sid = nextSession++
-  const sessionId = `cb-tab-${sid}`
-  const attachOrder = sid
-
-  tabs.set(tabId, { state: 'connected', sessionId, targetId, attachOrder })
-  tabBySession.set(sessionId, tabId)
-  void chrome.action.setTitle({
-    tabId,
-    title: 'Officer Browser Relay: attached (click to detach)',
-  })
-
-  if (!opts.skipAttachedEvent) {
-    sendToRelay({
-      method: 'forwardCDPEvent',
-      params: {
-        method: 'Target.attachedToTarget',
-        params: {
-          sessionId,
-          targetInfo: { ...targetInfo, attached: true },
-          waitingForDebugger: false,
-        },
-      },
-    })
-  }
-
-  setBadge(tabId, 'on')
-  await persistState()
-
-  return { sessionId, targetId }
-}
-
-async function detachTab(tabId, reason) {
-  const tab = tabs.get(tabId)
-
-  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
-    if (parentTabId === tabId) {
-      try {
-        sendToRelay({
-          method: 'forwardCDPEvent',
-          params: {
-            method: 'Target.detachedFromTarget',
-            params: { sessionId: childSessionId, reason: 'parent_detached' },
-          },
-        })
-      } catch {
-        // Relay may be down.
-      }
-      childSessionToTab.delete(childSessionId)
-    }
-  }
-
-  if (tab?.sessionId && tab?.targetId) {
-    try {
-      sendToRelay({
-        method: 'forwardCDPEvent',
-        params: {
-          method: 'Target.detachedFromTarget',
-          params: { sessionId: tab.sessionId, targetId: tab.targetId, reason },
-        },
-      })
-    } catch {
-      // Relay may be down.
-    }
-  }
-
-  if (tab?.sessionId) tabBySession.delete(tab.sessionId)
-  tabs.delete(tabId)
-
-  try {
-    await chrome.debugger.detach({ tabId })
-  } catch {
-    // May already be detached.
-  }
-
-  setBadge(tabId, 'off')
-  void chrome.action.setTitle({
-    tabId,
-    title: 'Officer Browser Relay (click to attach/detach)',
-  })
-
-  await persistState()
-}
-
-function describeError(err) {
-  const msg = err instanceof Error ? err.message : String(err)
-  if (msg.includes('not reachable')) return 'relay not reachable — check server address in options'
-  if (msg.includes('Missing relay token')) return 'no token configured — open options to set up'
-  if (msg.includes('401') || msg.includes('Unauthorized')) return 'token rejected — check token in options'
-  if (msg.toLowerCase().includes('timeout')) return 'connection timed out'
-  return msg.length > 80 ? msg.slice(0, 80) + '…' : msg
-}
-
-async function connectOrToggleForActiveTab() {
-  const [active] = await chrome.tabs.query({ active: true, currentWindow: true })
-  const tabId = active?.id
-  if (!tabId) return
-
-  if (tabOperationLocks.has(tabId)) return
-  tabOperationLocks.add(tabId)
-
-  try {
-    if (reattachPending.has(tabId)) {
-      reattachPending.delete(tabId)
-      setBadge(tabId, 'off')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay (click to attach/detach)',
-      })
-      return
-    }
-
-    const existing = tabs.get(tabId)
-    if (existing?.state === 'connected') {
-      await detachTab(tabId, 'toggle')
-      return
-    }
-
-    cancelReconnect()
-
-    tabs.set(tabId, { state: 'connecting' })
-    setBadge(tabId, 'connecting')
-    void chrome.action.setTitle({
-      tabId,
-      title: 'Officer Browser Relay: connecting to relay…',
-    })
-
-    try {
-      await ensureRelayConnection()
-      await attachTab(tabId)
-    } catch (err) {
-      tabs.delete(tabId)
-      setBadge(tabId, 'error')
-      void chrome.action.setTitle({
-        tabId,
-        title: `Officer Browser Relay: ${describeError(err)}`,
-      })
-      void maybeOpenHelpOnce()
-      const message = err instanceof Error ? err.message : String(err)
-      console.warn('attach failed', message)
-    }
-  } finally {
-    tabOperationLocks.delete(tabId)
-  }
-}
-
-async function handleForwardCdpCommand(msg) {
-  const method = String(msg?.params?.method || '').trim()
-  const params = msg?.params?.params || undefined
-  const sessionId = typeof msg?.params?.sessionId === 'string' ? msg.params.sessionId : undefined
-
-  const bySession = sessionId ? getTabBySessionId(sessionId) : null
-  const targetId = typeof params?.targetId === 'string' ? params.targetId : undefined
-  const tabId =
-    bySession?.tabId ||
-    (targetId ? getTabByTargetId(targetId) : null) ||
-    (() => {
-      for (const [id, tab] of tabs.entries()) {
-        if (tab.state === 'connected') return id
-      }
-      return null
-    })()
-
-  if (!tabId) throw new Error(`No attached tab for method ${method}`)
-
-  /** @type {chrome.debugger.DebuggerSession} */
-  const debuggee = { tabId }
-
-  if (method === 'Runtime.enable') {
-    try {
-      await chrome.debugger.sendCommand(debuggee, 'Runtime.disable')
-      await new Promise((r) => setTimeout(r, 50))
-    } catch {
-      // ignore
-    }
-    return await chrome.debugger.sendCommand(debuggee, 'Runtime.enable', params)
-  }
-
-  if (method === 'Target.createTarget') {
-    const url = typeof params?.url === 'string' ? params.url : 'about:blank'
-    const tab = await chrome.tabs.create({ url, active: false })
-    if (!tab.id) throw new Error('Failed to create tab')
-    await new Promise((r) => setTimeout(r, 100))
-    const attached = await attachTab(tab.id)
-    return { targetId: attached.targetId }
-  }
-
-  if (method === 'Target.closeTarget') {
-    const target = typeof params?.targetId === 'string' ? params.targetId : ''
-    const toClose = target ? getTabByTargetId(target) : tabId
-    if (!toClose) return { success: false }
-    try {
-      await chrome.tabs.remove(toClose)
-    } catch {
-      return { success: false }
-    }
-    return { success: true }
-  }
-
-  if (method === 'Target.activateTarget') {
-    const target = typeof params?.targetId === 'string' ? params.targetId : ''
-    const toActivate = target ? getTabByTargetId(target) : tabId
-    if (!toActivate) return {}
-    const tab = await chrome.tabs.get(toActivate).catch(() => null)
-    if (!tab) return {}
-    if (tab.windowId) {
-      await chrome.windows.update(tab.windowId, { focused: true }).catch(() => {})
-    }
-    await chrome.tabs.update(toActivate, { active: true }).catch(() => {})
-    return {}
-  }
-
-  const tabState = tabs.get(tabId)
-  const mainSessionId = tabState?.sessionId
-  const debuggerSession =
-    sessionId && mainSessionId && sessionId !== mainSessionId
-      ? { ...debuggee, sessionId }
-      : debuggee
-
-  try {
-    return await chrome.debugger.sendCommand(debuggerSession, method, params)
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err)
-    if (!message.includes('Session with given id not found')) throw err
-
-    // Chrome's internal debugger session became stale — re-attach and retry once
-    console.warn(`Stale session for tab ${tabId}, re-attaching debugger`)
-    reattachingTabs.add(tabId)
-    try {
-      await chrome.debugger.detach(debuggee).catch(() => {})
-      await chrome.debugger.attach(debuggee, '1.3')
-      await chrome.debugger.sendCommand(debuggee, 'Page.enable').catch(() => {})
-      return await chrome.debugger.sendCommand(debuggee, method, params)
-    } finally {
-      reattachingTabs.delete(tabId)
-    }
-  }
-}
-
-function onDebuggerEvent(source, method, params) {
-  const tabId = source.tabId
-  if (!tabId) return
-  const tab = tabs.get(tabId)
-  if (!tab?.sessionId) return
-
-  if (method === 'Target.attachedToTarget' && params?.sessionId) {
-    childSessionToTab.set(String(params.sessionId), tabId)
-  }
-
-  if (method === 'Target.detachedFromTarget' && params?.sessionId) {
-    childSessionToTab.delete(String(params.sessionId))
-  }
-
-  try {
-    sendToRelay({
-      method: 'forwardCDPEvent',
-      params: {
-        sessionId: source.sessionId || tab.sessionId,
-        method,
-        params,
-      },
-    })
-  } catch {
-    // Relay may be down.
-  }
-}
-
-async function onDebuggerDetach(source, reason) {
-  const tabId = source.tabId
-  if (!tabId) return
-  if (!tabs.has(tabId)) return
-  if (reattachingTabs.has(tabId)) return
-
-  if (reason === 'canceled_by_user' || reason === 'replaced_with_devtools') {
-    void detachTab(tabId, reason)
-    return
-  }
-
-  let tabInfo
-  try {
-    tabInfo = await chrome.tabs.get(tabId)
-  } catch {
-    void detachTab(tabId, reason)
-    return
-  }
-
-  if (tabInfo.url?.startsWith('chrome://') || tabInfo.url?.startsWith('chrome-extension://')) {
-    void detachTab(tabId, reason)
-    return
-  }
-
-  if (reattachPending.has(tabId)) return
-
-  const oldTab = tabs.get(tabId)
-  const oldSessionId = oldTab?.sessionId
-  const oldTargetId = oldTab?.targetId
-
-  if (oldSessionId) tabBySession.delete(oldSessionId)
-  tabs.delete(tabId)
-  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
-    if (parentTabId === tabId) childSessionToTab.delete(childSessionId)
-  }
-
-  if (oldSessionId && oldTargetId) {
-    try {
-      sendToRelay({
-        method: 'forwardCDPEvent',
-        params: {
-          method: 'Target.detachedFromTarget',
-          params: { sessionId: oldSessionId, targetId: oldTargetId, reason: 'navigation-reattach' },
-        },
-      })
-    } catch {
-      // Relay may be down.
-    }
-  }
-
-  reattachPending.add(tabId)
-  setBadge(tabId, 'connecting')
-  void chrome.action.setTitle({
-    tabId,
-    title: 'Officer Browser Relay: re-attaching after navigation…',
-  })
-
-  const delays = [300, 700, 1500]
-  for (let attempt = 0; attempt < delays.length; attempt++) {
-    await new Promise((r) => setTimeout(r, delays[attempt]))
-
-    if (!reattachPending.has(tabId)) return
-
-    try {
-      await chrome.tabs.get(tabId)
-    } catch {
-      reattachPending.delete(tabId)
-      setBadge(tabId, 'off')
-      return
-    }
-
-    if (!relayWs || relayWs.readyState !== WebSocket.OPEN) {
-      reattachPending.delete(tabId)
-      setBadge(tabId, 'error')
-      void chrome.action.setTitle({
-        tabId,
-        title: 'Officer Browser Relay: relay disconnected during re-attach',
-      })
-      return
-    }
-
-    try {
-      await attachTab(tabId)
-      reattachPending.delete(tabId)
-      return
-    } catch {
-      // continue retries
-    }
-  }
-
-  reattachPending.delete(tabId)
-  setBadge(tabId, 'off')
-  void chrome.action.setTitle({
-    tabId,
-    title: 'Officer Browser Relay: re-attach failed (click to retry)',
-  })
-}
-
-chrome.tabs.onRemoved.addListener((tabId) => void whenReady(() => {
-  reattachPending.delete(tabId)
-  if (!tabs.has(tabId)) return
-  const tab = tabs.get(tabId)
-  if (tab?.sessionId) tabBySession.delete(tab.sessionId)
-  tabs.delete(tabId)
-  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
-    if (parentTabId === tabId) childSessionToTab.delete(childSessionId)
-  }
-  if (tab?.sessionId && tab?.targetId) {
-    try {
-      sendToRelay({
-        method: 'forwardCDPEvent',
-        params: {
-          method: 'Target.detachedFromTarget',
-          params: { sessionId: tab.sessionId, targetId: tab.targetId, reason: 'tab_closed' },
-        },
-      })
-    } catch {
-      // Relay may be down.
-    }
-  }
-  void persistState()
-}))
-
-chrome.tabs.onReplaced.addListener((addedTabId, removedTabId) => void whenReady(() => {
-  const tab = tabs.get(removedTabId)
-  if (!tab) return
-  tabs.delete(removedTabId)
-  tabs.set(addedTabId, tab)
-  if (tab.sessionId) {
-    tabBySession.set(tab.sessionId, addedTabId)
-  }
-  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
-    if (parentTabId === removedTabId) {
-      childSessionToTab.set(childSessionId, addedTabId)
-    }
-  }
-  setBadge(addedTabId, 'on')
-  void persistState()
-}))
-
-chrome.debugger.onEvent.addListener((...args) => void whenReady(() => onDebuggerEvent(...args)))
-chrome.debugger.onDetach.addListener((...args) => void whenReady(() => onDebuggerDetach(...args)))
-
-chrome.action.onClicked.addListener(() => void whenReady(() => connectOrToggleForActiveTab()))
-
-chrome.webNavigation.onCompleted.addListener(({ tabId, frameId }) => void whenReady(() => {
-  if (frameId !== 0) return
-  const tab = tabs.get(tabId)
-  if (tab?.state === 'connected') {
-    setBadge(tabId, relayWs && relayWs.readyState === WebSocket.OPEN ? 'on' : 'connecting')
-  }
-}))
-
-chrome.tabs.onActivated.addListener(({ tabId }) => void whenReady(() => {
-  const tab = tabs.get(tabId)
-  if (tab?.state === 'connected') {
-    setBadge(tabId, relayWs && relayWs.readyState === WebSocket.OPEN ? 'on' : 'connecting')
-  }
-}))
-
-chrome.runtime.onInstalled.addListener(() => {
-  void chrome.runtime.openOptionsPage()
-})
-
-chrome.alarms.create('relay-keepalive', { periodInMinutes: 0.5 })
-
-chrome.alarms.onAlarm.addListener(async (alarm) => {
-  if (alarm.name !== 'relay-keepalive') return
-  await initPromise
-
-  if (tabs.size === 0) return
-
-  for (const [tabId, tab] of tabs.entries()) {
-    if (tab.state === 'connected') {
-      setBadge(tabId, relayWs && relayWs.readyState === WebSocket.OPEN ? 'on' : 'connecting')
-    }
-  }
-
-  if (!relayWs || relayWs.readyState !== WebSocket.OPEN) {
-    if (!relayConnectPromise && !reconnectTimer) {
-      console.log('Keepalive: WebSocket unhealthy, triggering reconnect')
-      await ensureRelayConnection().catch(() => {
-        if (!reconnectTimer) {
-          scheduleReconnect()
-        }
-      })
-    }
-  }
-})
-
-const initPromise = rehydrateState()
-
-initPromise.then(() => {
-  if (tabs.size > 0) {
-    ensureRelayConnection().then(() => {
-      reconnectAttempt = 0
-      return reannounceAttachedTabs()
-    }).catch(() => {
-      scheduleReconnect()
-    })
-  }
-})
-
-async function whenReady(fn) {
-  await initPromise
-  return fn()
-}
-
-chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
-  if (msg?.type !== 'relayCheck') return false
-  const { url, token } = msg
-  const headers = token ? { 'x-officer-relay-token': token } : {}
-  fetch(url, { method: 'GET', headers, signal: AbortSignal.timeout(2000) })
-    .then(async (res) => {
-      const contentType = String(res.headers.get('content-type') || '')
-      let json = null
-      if (contentType.includes('application/json')) {
-        try {
-          json = await res.json()
-        } catch {
-          json = null
-        }
-      }
-      sendResponse({ status: res.status, ok: res.ok, contentType, json })
-    })
-    .catch((err) => sendResponse({ status: 0, ok: false, error: String(err) }))
-  return true
-})

src/extensions/browser-relay/manifest.json

@@ -1,25 +0,0 @@
-{
-  "manifest_version": 3,
-  "name": "Officer Browser Relay",
-  "version": "0.1.0",
-  "description": "Connect your Chrome browser to Officer",
-  "icons": {
-    "16": "icons/icon16.png",
-    "32": "icons/icon32.png",
-    "48": "icons/icon48.png",
-    "128": "icons/icon128.png"
-  },
-  "permissions": ["debugger", "tabs", "activeTab", "storage", "alarms", "webNavigation"],
-  "host_permissions": ["<all_urls>"],
-  "background": { "service_worker": "background.js", "type": "module" },
-  "action": {
-    "default_title": "Officer Browser Relay (click to attach/detach)",
-    "default_icon": {
-      "16": "icons/icon16.png",
-      "32": "icons/icon32.png",
-      "48": "icons/icon48.png",
-      "128": "icons/icon128.png"
-    }
-  },
-  "options_ui": { "page": "options.html", "open_in_tab": true }
-}

src/extensions/browser-relay/options-validation.js

@@ -1,66 +0,0 @@
-// Based on OpenClaw Browser Extension Relay (MIT License)
-// https://github.com/nicepkg/openclaw
-
-function hasCdpVersionShape(data) {
-  return !!data && typeof data === 'object' && 'Browser' in data && 'Protocol-Version' in data
-}
-
-export function classifyRelayCheckResponse(res, host, port) {
-  if (!res) {
-    return { action: 'throw', error: 'No response from service worker' }
-  }
-
-  if (res.status === 401) {
-    return { action: 'status', kind: 'error', message: 'Relay token rejected. Check token and save again.' }
-  }
-
-  if (res.error) {
-    return { action: 'throw', error: res.error }
-  }
-
-  if (!res.ok) {
-    return { action: 'throw', error: `HTTP ${res.status}` }
-  }
-
-  const contentType = String(res.contentType || '')
-  if (!contentType.includes('application/json')) {
-    return {
-      action: 'status',
-      kind: 'error',
-      message: `Wrong endpoint: expected Officer browser relay at this address.`,
-    }
-  }
-
-  if (!hasCdpVersionShape(res.json)) {
-    const browser = res.json?.Browser ?? ''
-    if (browser && !browser.startsWith('Officer/')) {
-      return {
-        action: 'status',
-        kind: 'error',
-        message: `Wrong relay: found "${browser}" instead of Officer/browser-relay.`,
-      }
-    }
-    return {
-      action: 'status',
-      kind: 'error',
-      message: `Wrong endpoint: expected relay /json/version response.`,
-    }
-  }
-
-  return { action: 'status', kind: 'ok', message: `Relay reachable and authenticated at http://${host}:${port}/` }
-}
-
-export function classifyRelayCheckException(err, host, port) {
-  const message = String(err || '').toLowerCase()
-  if (message.includes('json') || message.includes('syntax')) {
-    return {
-      kind: 'error',
-      message: `Wrong endpoint: this is not a relay endpoint.`,
-    }
-  }
-
-  return {
-    kind: 'error',
-    message: `Relay not reachable at http://${host}:${port}/. Verify the server address and relay token.`,
-  }
-}

src/extensions/browser-relay/options.html

@@ -1,209 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Officer Browser Relay</title>
-    <style>
-      :root {
-        color-scheme: light dark;
-        --accent: #06b6d4;
-        --panel: color-mix(in oklab, canvas 92%, canvasText 8%);
-        --border: color-mix(in oklab, canvasText 18%, transparent);
-        --muted: color-mix(in oklab, canvasText 70%, transparent);
-        --shadow: 0 10px 30px color-mix(in oklab, canvasText 18%, transparent);
-        font-family: ui-rounded, system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Rounded",
-          "SF Pro Display", "Segoe UI", sans-serif;
-        line-height: 1.4;
-      }
-      body {
-        margin: 0;
-        min-height: 100vh;
-        background:
-          radial-gradient(1000px 500px at 10% 0%, color-mix(in oklab, var(--accent) 30%, transparent), transparent 70%),
-          radial-gradient(900px 450px at 90% 0%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 75%),
-          canvas;
-        color: canvasText;
-      }
-      .wrap {
-        max-width: 820px;
-        margin: 36px auto;
-        padding: 0 24px 48px 24px;
-      }
-      header {
-        display: flex;
-        align-items: center;
-        gap: 12px;
-        margin-bottom: 18px;
-      }
-      .logo {
-        width: 44px;
-        height: 44px;
-        border-radius: 14px;
-        background: color-mix(in oklab, var(--accent) 18%, transparent);
-        border: 1px solid color-mix(in oklab, var(--accent) 35%, transparent);
-        box-shadow: var(--shadow);
-        display: grid;
-        place-items: center;
-        font-size: 24px;
-      }
-      h1 {
-        font-size: 20px;
-        margin: 0;
-        letter-spacing: -0.01em;
-      }
-      .subtitle {
-        margin: 2px 0 0 0;
-        color: var(--muted);
-        font-size: 13px;
-      }
-      .grid {
-        display: grid;
-        grid-template-columns: 1fr;
-        gap: 14px;
-      }
-      .card {
-        background: var(--panel);
-        border: 1px solid var(--border);
-        border-radius: 16px;
-        padding: 16px;
-        box-shadow: var(--shadow);
-      }
-      .card h2 {
-        margin: 0 0 10px 0;
-        font-size: 14px;
-        letter-spacing: 0.01em;
-      }
-      .card p {
-        margin: 8px 0 0 0;
-        color: var(--muted);
-        font-size: 13px;
-      }
-      .row {
-        display: flex;
-        align-items: center;
-        gap: 8px;
-        flex-wrap: wrap;
-      }
-      label {
-        display: block;
-        font-size: 12px;
-        color: var(--muted);
-        margin-bottom: 6px;
-      }
-      input {
-        padding: 10px 12px;
-        border-radius: 12px;
-        border: 1px solid var(--border);
-        background: color-mix(in oklab, canvas 92%, canvasText 8%);
-        color: canvasText;
-        outline: none;
-      }
-      input:focus {
-        border-color: color-mix(in oklab, var(--accent) 70%, transparent);
-        box-shadow: 0 0 0 4px color-mix(in oklab, var(--accent) 20%, transparent);
-      }
-      input.host-input {
-        width: 240px;
-      }
-      input.port-input {
-        width: 100px;
-      }
-      input.token-input {
-        width: min(520px, 100%);
-      }
-      button {
-        padding: 10px 14px;
-        border-radius: 12px;
-        border: 1px solid color-mix(in oklab, var(--accent) 55%, transparent);
-        background: linear-gradient(
-          180deg,
-          color-mix(in oklab, var(--accent) 80%, white 20%),
-          var(--accent)
-        );
-        color: white;
-        font-weight: 650;
-        letter-spacing: 0.01em;
-        cursor: pointer;
-      }
-      button:active {
-        transform: translateY(1px);
-      }
-      .hint {
-        margin-top: 10px;
-        font-size: 12px;
-        color: var(--muted);
-      }
-      code {
-        font-family: ui-monospace, Menlo, Monaco, Consolas, "SF Mono", monospace;
-        font-size: 12px;
-      }
-      a {
-        color: color-mix(in oklab, var(--accent) 85%, canvasText 15%);
-      }
-      .status {
-        margin-top: 10px;
-        font-size: 12px;
-        color: color-mix(in oklab, var(--accent) 70%, canvasText 30%);
-        min-height: 16px;
-      }
-      .status[data-kind='ok'] {
-        color: color-mix(in oklab, #16a34a 75%, canvasText 25%);
-      }
-      .status[data-kind='error'] {
-        color: color-mix(in oklab, #ef4444 75%, canvasText 25%);
-      }
-    </style>
-  </head>
-  <body>
-    <div class="wrap">
-      <header>
-        <div class="logo" aria-hidden="true">&#x1f310;</div>
-        <div>
-          <h1>Officer Browser Relay</h1>
-          <p class="subtitle">Click the toolbar button on a tab to attach / detach.</p>
-        </div>
-      </header>
-
-      <div class="grid">
-        <div class="card">
-          <h2>Getting started</h2>
-          <p>
-            If you see a red <code>!</code> badge on the extension icon, the relay server is not reachable.
-            Make sure Officer is running and enter the correct server address, port, and relay token below.
-          </p>
-          <p>
-            You can find your relay token in the Officer dashboard under <strong>Browser</strong>.
-          </p>
-        </div>
-
-        <div class="card">
-          <h2>Relay connection</h2>
-
-          <label for="host">Server address</label>
-          <div class="row">
-            <input id="host" class="host-input" placeholder="e.g. 100.64.0.1" />
-          </div>
-
-          <label for="port" style="margin-top: 10px">Port</label>
-          <div class="row">
-            <input id="port" class="port-input" inputmode="numeric" pattern="[0-9]*" />
-          </div>
-
-          <label for="token" style="margin-top: 10px">Relay token</label>
-          <div class="row">
-            <input id="token" class="token-input" type="password" autocomplete="off" />
-            <button id="save" type="button">Save</button>
-          </div>
-
-          <div class="hint">
-            Default port: <code>18792</code>. Extension connects to: <code id="relay-url">http://&lt;host&gt;:&lt;port&gt;/</code>.
-          </div>
-          <div class="status" id="status"></div>
-        </div>
-      </div>
-
-      <script type="module" src="options.js"></script>
-    </div>
-  </body>
-</html>

src/extensions/browser-relay/options.js

@@ -1,77 +0,0 @@
-import { classifyRelayCheckException, classifyRelayCheckResponse } from './options-validation.js'
-
-const DEFAULT_PORT = 18792
-const DEFAULT_HOST = '127.0.0.1'
-
-function clampPort(value) {
-  const n = Number.parseInt(String(value || ''), 10)
-  if (!Number.isFinite(n)) return DEFAULT_PORT
-  if (n <= 0 || n > 65535) return DEFAULT_PORT
-  return n
-}
-
-function updateRelayUrl(host, port) {
-  const el = document.getElementById('relay-url')
-  if (!el) return
-  el.textContent = `http://${host}:${port}/`
-}
-
-function setStatus(kind, message) {
-  const status = document.getElementById('status')
-  if (!status) return
-  status.dataset.kind = kind || ''
-  status.textContent = message || ''
-}
-
-async function checkRelayReachable(host, port, token) {
-  const url = `http://${host}:${port}/json/version`
-  const trimmedToken = String(token || '').trim()
-  if (!trimmedToken) {
-    setStatus('error', 'Relay token required. Save your token to connect.')
-    return
-  }
-  try {
-    // Token is already derived server-side — use it directly
-    const res = await chrome.runtime.sendMessage({
-      type: 'relayCheck',
-      url,
-      token: trimmedToken,
-    })
-    const result = classifyRelayCheckResponse(res, host, port)
-    if (result.action === 'throw') throw new Error(result.error)
-    setStatus(result.kind, result.message)
-  } catch (err) {
-    const result = classifyRelayCheckException(err, host, port)
-    setStatus(result.kind, result.message)
-  }
-}
-
-async function load() {
-  const stored = await chrome.storage.local.get(['relayPort', 'relayHost', 'relayToken'])
-  const port = clampPort(stored.relayPort)
-  const host = String(stored.relayHost || '').trim() || DEFAULT_HOST
-  const token = String(stored.relayToken || '').trim()
-  document.getElementById('host').value = host
-  document.getElementById('port').value = String(port)
-  document.getElementById('token').value = token
-  updateRelayUrl(host, port)
-  await checkRelayReachable(host, port, token)
-}
-
-async function save() {
-  const hostInput = document.getElementById('host')
-  const portInput = document.getElementById('port')
-  const tokenInput = document.getElementById('token')
-  const host = String(hostInput.value || '').trim() || DEFAULT_HOST
-  const port = clampPort(portInput.value)
-  const token = String(tokenInput.value || '').trim()
-  await chrome.storage.local.set({ relayHost: host, relayPort: port, relayToken: token })
-  hostInput.value = host
-  portInput.value = String(port)
-  tokenInput.value = token
-  updateRelayUrl(host, port)
-  await checkRelayReachable(host, port, token)
-}
-
-document.getElementById('save').addEventListener('click', () => void save())
-void load()

src/server.tsx

@@ -19,12 +19,12 @@ import { terminalWebsocket } from './servers/api/terminal/websocket';
 import { chatWebsocket } from './servers/api/chat/websocket';
 import { chatNotifyWebsocket } from './servers/api/chat/notify-delivery';
 import { registerChatPushNotifications } from './servers/api/chat/notify-push';
+import { startNudger } from './servers/api/chat/nudger';
 import { taskRunnerWebsocket } from './servers/api/tasks/task-executor';
 import { pipelineWebsocket } from './servers/api/tasks/pipeline-executor';
-// import { desktopWebsocket } from './servers/api/desktop/websocket';
 import officerWeb from './apps/officer-web/index.gen.html';
-// import { startBrowserRelay } from './servers/api/browser/relay';  // switched off — see below
 import { registerSidecar, unregisterSidecar, handleSidecarMessage } from './servers/sidecar-registry';
+import { sendProvisionableUsers } from './servers/plugins/user-provisioning';
 import './servers/api/chat/opencode/sidecar-server'; // subscribe to the opencode sidecar's port report
 import type { SidecarRegistration } from './servers/sidecar/registration-protocol';
 import { toShellUsername } from './servers/data-path';
@@ -55,7 +55,7 @@ type WSData = {
   userId: number;
   email: string;
   username: string;
-  provider: 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline' | 'desktop' | 'sidecar';
+  provider: 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline' | 'sidecar';
   sessionId?: string;
   cwd?: string;
   command?: string;
@@ -77,9 +77,21 @@ const sidecarWebsocket = {
       const msg = JSON.parse(data);
 
       if (msg.type === 'register') {
-        const id = registerSidecar(ws, msg as SidecarRegistration);
+        const registration = msg as SidecarRegistration;
+        const id = registerSidecar(ws, registration);
         sidecarConnections.set(ws, id);
         ws.send(JSON.stringify({ type: 'registered', id }));
+
+        // The account list, for a plugin whose MANIFEST declares `userProvisioning`.
+        //
+        // Read from the manifest and never from this message: `name` and `handles` are self-declared and
+        // believed, so a capability asserted here would be a plugin granting itself one. The manifest was
+        // reviewed when the owner installed it.
+        //
+        // After the ack, not inside it — registration must not wait on a database query. A slow or
+        // unreachable Postgres would otherwise stall every sidecar's startup, and none of them need the
+        // list to start.
+        void sendProvisionableUsers(ws, registration.name);
         return;
       }
 
@@ -147,7 +159,6 @@ const handlers: Record<string, any> = {
   'chat-notify': chatNotifyWebsocket,
   'task-runner': taskRunnerWebsocket,
   pipeline: pipelineWebsocket,
-  // desktop: desktopWebsocket,
   sidecar: sidecarWebsocket,
 };
 
@@ -166,6 +177,10 @@ assertPermissionTotality({
 // module whose only job is a side effect is one an import sweep quietly deletes.
 registerChatPushNotifications();
 
+// Nudger's tick. Here rather than on first use, because a schedule armed before a restart has to survive
+// one — the row is in Postgres and nothing else would ever look at it again.
+startNudger();
+
 // That the working directory is the repo, because every path derives from its parent. First of the three,
 // since a wrong answer here makes the other two check the wrong files.
 assertInstallLayout();
@@ -300,7 +315,7 @@ console.log(
 async function upgradeWs(
   req: Request,
   server: any,
-  provider: 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline' | 'desktop',
+  provider: 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline',
 ) {
   const token = new URL(req.url).searchParams.get('token');
   if (!token) return new Response('Unauthorized', { status: 401 });
@@ -431,7 +446,6 @@ const server = serve({
     '/api/terminal/ws': (req, server) => upgradeWs(req, server, 'terminal'),
     '/api/chat/ws': (req, server) => upgradeWs(req, server, 'chat'),
     '/api/chat/notify/ws': (req, server) => upgradeWs(req, server, 'chat-notify'),
-    // '/api/desktop/ws': (req, server) => upgradeWs(req, server, 'desktop'),
     // CalDAV/CardDAV. These live OUTSIDE /api because DAV clients are given a bare domain and probe
     // fixed, spec-defined paths — `/.well-known/caldav` unauthenticated, before they hold any
     // credential at all. They need naming explicitly here or the `/*` SPA fallback below swallows them
@@ -497,30 +511,13 @@ console.log(`🚀 Server running at ${server.url}`);
 //
 // The Chrome extension, its CDP bridge (api/browser/) and the /browser screen all remain on disk: this
 // is going to be extracted into a plugin, and deleting it would mean writing it again. What is switched
-// off is the second listener and the /api/browser mount (see hono.ts) — the platform serves one port.
+// The browser relay left for `plugins/browser` on 2026-08-21. It ran a SECOND listener from this process,
+// which is why it was switched off here on 2026-08-13 — the platform serves one port. As a plugin it is a
+// sidecar, which is a process allowed its own listeners, so the objection no longer applies.
 //
-// It used to read BROWSER_RELAY_PORT, default 18792. The name is recorded here because there is nothing
+// The port and everything that depended on it moved with it, including the reason it cannot be
-// left to grep for, and whoever does the extraction needs to know what it was called.
+// kernel-assigned: the extension stores the number by hand AND the number is an input to the token HMAC.
-//
+// See plugins/browser/sidecar/protocol.ts.
-// ── Read this before turning it back on ──
-//
-// The port is not only configuration. relay-auth.ts derives each extension's token as
-// HMAC(JWT_SECRET, `officer-browser-relay-v1:${port}:${userId}:${salt}`), so the port is an INPUT TO A
-// CREDENTIAL. Bringing the relay back on a different number silently invalidates every paired browser,
-// and the extension reports it as "Relay not reachable" — which SETUP.md attributes to a wrong address,
-// port or token. Re-pairing means re-copying from Settings → Browser Relay.
-//
-// Whatever it comes back as, it cannot be a kernel-assigned port:0 the way the other sidecars are. The
-// extension is configured by hand and stores the value, so a port that changes each restart breaks the
-// pairing every restart. It has to be predictable — PORT + 2 is the shape the Anthropic proxy already
-// uses for the same reason.
-//
-// try {
-//   await startBrowserRelay(BROWSER_RELAY_PORT);
-//   console.log(`[browser-relay] listening on port ${BROWSER_RELAY_PORT}`);
-// } catch (err) {
-//   console.error('[browser-relay] failed to start:', err instanceof Error ? err.message : err);
-// }
 
 // Initialize queue engine in API server process
 import {

src/servers/api/api-keys/router.ts

@@ -1,5 +1,5 @@
 import { createRouter } from '../../create-router';
-import { createApiKey, listApiKeys, revokeApiKey } from 'officerdb';
+import { createApiKey, listApiKeys, revokeApiKey, deleteApiKey } from 'officerdb';
 import { mintApiKey } from '../../auth-token';
 import * as errors from '../../custom-errors';
 
@@ -60,3 +60,26 @@ apiKeysRouter.delete('/:id', async (ctx) => {
   if (!(await revokeApiKey(id, user.id))) throw errors.NOT_FOUND('no such api key');
   return ctx.json({ ok: true });
 });
+
+// ── Forgetting a key, which is not the same as revoking it ──
+//
+// DELETE /:id revokes and keeps the row, because the row is the record that the key existed and
+// `lastUsedAt` is the only evidence of whether a leaked one was used before it was killed. This removes
+// that record, and it is deliberately a SECOND request after the first: `deleteApiKey` refuses a key that
+// is not already revoked, in the statement rather than before it, so there is no ordering in which a live
+// key is deleted by something that raced a revoke.
+//
+// Nothing is weakened by allowing it. The key cannot be honoured again either way — authentication
+// matches a hash, and a deleted row has none. What goes is the history, not the protection.
+apiKeysRouter.delete('/:id/record', async (ctx) => {
+  const user = ctx.get('user');
+  const id = Number(ctx.req.param('id'));
+  if (!Number.isInteger(id)) throw errors.BAD_REQUEST('invalid id');
+
+  if (!(await deleteApiKey(id, user.id))) {
+    // One message for both "not yours / never existed" and "still live", on purpose: the first must not
+    // be distinguishable from the second by someone probing ids that are not theirs.
+    throw errors.NOT_FOUND('no such revoked api key');
+  }
+  return ctx.json({ ok: true });
+});

src/servers/api/browser/cdp.ts

@@ -1,99 +0,0 @@
-type CdpCommandOptions = {
-  relayPort: number;
-  userToken: string;
-  targetId?: string;
-};
-
-async function sendCdpCommand(opts: CdpCommandOptions, method: string, params?: unknown): Promise<unknown> {
-  const { relayPort, userToken, targetId } = opts;
-  const url = `ws://127.0.0.1:${relayPort}/cdp?token=${encodeURIComponent(userToken)}`;
-
-  return await new Promise<unknown>((resolve, reject) => {
-    const ws = new WebSocket(url);
-    let settled = false;
-    const timeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      ws.close();
-      reject(new Error(`CDP command timeout: ${method}`));
-    }, 30_000);
-
-    ws.addEventListener('open', () => {
-      const cmd: Record<string, unknown> = { id: 1, method };
-      if (params) cmd.params = params;
-      if (targetId) cmd.sessionId = targetId;
-      ws.send(JSON.stringify(cmd));
-    });
-
-    ws.addEventListener('message', (event) => {
-      if (settled) return;
-      try {
-        const msg = JSON.parse(String(event.data)) as { id?: number; result?: unknown; error?: { message: string } };
-        if (msg.id === 1) {
-          settled = true;
-          clearTimeout(timeout);
-          ws.close();
-          if (msg.error) reject(new Error(msg.error.message));
-          else resolve(msg.result);
-        }
-      } catch {
-        // ignore parse errors, wait for correct message
-      }
-    });
-
-    ws.addEventListener('error', () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(new Error('CDP WebSocket connection failed'));
-    });
-
-    ws.addEventListener('close', () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(new Error('CDP WebSocket closed before response'));
-    });
-  });
-}
-
-export async function captureScreenshot(
-  opts: CdpCommandOptions,
-  format: 'png' | 'jpeg' = 'png',
-  quality?: number,
-): Promise<string> {
-  const params: Record<string, unknown> = { format };
-  if (quality !== undefined) params.quality = quality;
-  const result = (await sendCdpCommand(opts, 'Page.captureScreenshot', params)) as { data: string };
-  return result.data;
-}
-
-export async function evaluateJS(opts: CdpCommandOptions, expression: string): Promise<unknown> {
-  const result = (await sendCdpCommand(opts, 'Runtime.evaluate', {
-    expression,
-    returnByValue: true,
-    awaitPromise: true,
-  })) as { result?: { value?: unknown; description?: string }; exceptionDetails?: { text?: string } };
-
-  if (result.exceptionDetails) {
-    throw new Error(result.exceptionDetails.text ?? 'Evaluation failed');
-  }
-  return result.result?.value;
-}
-
-export async function navigateTo(opts: CdpCommandOptions, url: string): Promise<void> {
-  await sendCdpCommand(opts, 'Page.navigate', { url });
-}
-
-export async function getPageInfo(opts: CdpCommandOptions): Promise<{ title: string; url: string }> {
-  const result = (await sendCdpCommand(opts, 'Runtime.evaluate', {
-    expression: 'JSON.stringify({ title: document.title, url: location.href })',
-    returnByValue: true,
-  })) as { result?: { value?: string } };
-
-  try {
-    return JSON.parse(result.result?.value ?? '{}');
-  } catch {
-    return { title: '', url: '' };
-  }
-}

src/servers/api/browser/relay-auth.ts

@@ -1,42 +0,0 @@
-import { createHmac } from 'node:crypto';
-import { getKey } from 'officerdb/secret-store';
-
-const RELAY_TOKEN_CONTEXT = 'officer-browser-relay-v1';
-
-// Nothing imports this file today — the browser relay is switched off pending extraction into a plugin
-// (see server.tsx). Updated with everything else so it is coherent when it comes back: it read
-// JWT_SECRET from the environment, which no longer exists, and would have thrown at module load.
-//
-// When it is extracted it should take its own purpose rather than borrowing 'jwt' — a plugin deriving
-// tokens from the platform's signing key is the coupling the per-purpose split exists to remove.
-
-export function deriveRelayToken(userId: number, port: number, salt: string): string {
-  return createHmac('sha256', getKey('jwt')).update(`${RELAY_TOKEN_CONTEXT}:${port}:${userId}:${salt}`).digest('hex');
-}
-
-const tokenToUser = new Map<string, number>();
-
-export function registerUserToken(userId: number, port: number, salt: string): string {
-  const token = deriveRelayToken(userId, port, salt);
-  tokenToUser.set(token, userId);
-  return token;
-}
-
-export function unregisterUserToken(token: string): void {
-  tokenToUser.delete(token);
-}
-
-export function restoreUserTokens(entries: Array<{ userId: number; salt: string }>, port: number): void {
-  for (const { userId, salt } of entries) {
-    const token = deriveRelayToken(userId, port, salt);
-    tokenToUser.set(token, userId);
-  }
-}
-
-export function resolveUserFromToken(token: string): number | null {
-  return tokenToUser.get(token) ?? null;
-}
-
-export function getRelayAuthHeader(): string {
-  return 'x-officer-relay-token';
-}

src/servers/api/browser/relay-types.ts

@@ -1,89 +0,0 @@
-export type TargetInfo = {
-  targetId: string;
-  type?: string;
-  title?: string;
-  url?: string;
-  attached?: boolean;
-};
-
-export type ConnectedTarget = {
-  sessionId: string;
-  targetId: string;
-  targetInfo: TargetInfo;
-};
-
-export type RelayStatus = {
-  extensionConnected: boolean;
-  targetCount: number;
-};
-
-export type CdpCommand = {
-  id: number;
-  method: string;
-  params?: unknown;
-  sessionId?: string;
-};
-
-export type CdpResponse = {
-  id: number;
-  result?: unknown;
-  error?: { message: string };
-  sessionId?: string;
-};
-
-export type CdpEvent = {
-  method: string;
-  params?: unknown;
-  sessionId?: string;
-};
-
-export type ExtensionForwardCommandMessage = {
-  id: number;
-  method: 'forwardCDPCommand';
-  params: { method: string; params?: unknown; sessionId?: string };
-};
-
-export type ExtensionResponseMessage = {
-  id: number;
-  result?: unknown;
-  error?: string;
-};
-
-export type ExtensionForwardEventMessage = {
-  method: 'forwardCDPEvent';
-  params: { method: string; params?: unknown; sessionId?: string };
-};
-
-export type ExtensionPingMessage = { method: 'ping' };
-export type ExtensionPongMessage = { method: 'pong' };
-
-export type ExtensionMessage = ExtensionResponseMessage | ExtensionForwardEventMessage | ExtensionPongMessage;
-
-export type AttachedToTargetEvent = {
-  sessionId: string;
-  targetInfo: TargetInfo;
-  waitingForDebugger?: boolean;
-};
-
-export type DetachedFromTargetEvent = {
-  sessionId: string;
-  targetId?: string;
-};
-
-export type UserRelay = {
-  extensionWs: unknown | null;
-  cdpClients: Set<unknown>;
-  connectedTargets: Map<string, ConnectedTarget>;
-  pingInterval: Timer | null;
-  gracePeriodTimer: Timer | null;
-  pendingExtension: Map<
-    number,
-    {
-      resolve: (v: unknown) => void;
-      reject: (e: Error) => void;
-      timer: Timer;
-    }
-  >;
-  nextExtensionId: number;
-  extensionReconnectWaiters: Set<(connected: boolean) => void>;
-};

src/servers/api/browser/relay.ts

@@ -1,677 +0,0 @@
-// Based on OpenClaw Browser Extension Relay (MIT License)
-// https://github.com/nicepkg/openclaw
-//
-// Rewritten for Bun.serve() with multi-user support.
-
-import type { ServerWebSocket } from 'bun';
-import type {
-  AttachedToTargetEvent,
-  CdpCommand,
-  CdpEvent,
-  CdpResponse,
-  ConnectedTarget,
-  DetachedFromTargetEvent,
-  ExtensionForwardCommandMessage,
-  ExtensionForwardEventMessage,
-  ExtensionMessage,
-  ExtensionPongMessage,
-} from './relay-types';
-import { getIntegrationsByProvider } from 'officerdb';
-import { getRelayAuthHeader, resolveUserFromToken, restoreUserTokens } from './relay-auth';
-
-const RELAY_AUTH_HEADER = getRelayAuthHeader();
-const DEFAULT_EXTENSION_RECONNECT_GRACE_MS = 5_000;
-const DEFAULT_EXTENSION_COMMAND_RECONNECT_WAIT_MS = 3_000;
-
-type WSData = {
-  kind: 'extension' | 'cdp';
-  userId: number;
-  token: string;
-};
-
-type UserRelay = {
-  extensionWs: ServerWebSocket<WSData> | null;
-  cdpClients: Set<ServerWebSocket<WSData>>;
-  connectedTargets: Map<string, ConnectedTarget>;
-  pingInterval: Timer | null;
-  gracePeriodTimer: Timer | null;
-  pendingExtension: Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: Timer }>;
-  nextExtensionId: number;
-  extensionReconnectWaiters: Set<(connected: boolean) => void>;
-};
-
-const userRelays = new Map<number, UserRelay>();
-
-function getUserRelay(userId: number): UserRelay {
-  let relay = userRelays.get(userId);
-  if (!relay) {
-    relay = {
-      extensionWs: null,
-      cdpClients: new Set(),
-      connectedTargets: new Map(),
-      pingInterval: null,
-      gracePeriodTimer: null,
-      pendingExtension: new Map(),
-      nextExtensionId: 1,
-      extensionReconnectWaiters: new Set(),
-    };
-    userRelays.set(userId, relay);
-  }
-  return relay;
-}
-
-function extensionConnected(relay: UserRelay): boolean {
-  return relay.extensionWs !== null && relay.extensionWs.readyState === WebSocket.OPEN;
-}
-
-function flushExtensionReconnectWaiters(relay: UserRelay, connected: boolean) {
-  if (relay.extensionReconnectWaiters.size === 0) return;
-  const waiters = Array.from(relay.extensionReconnectWaiters);
-  relay.extensionReconnectWaiters.clear();
-  for (const waiter of waiters) waiter(connected);
-}
-
-function clearGracePeriodTimer(relay: UserRelay) {
-  if (!relay.gracePeriodTimer) return;
-  clearTimeout(relay.gracePeriodTimer);
-  relay.gracePeriodTimer = null;
-}
-
-function closeCdpClientsAfterExtensionDisconnect(relay: UserRelay) {
-  relay.connectedTargets.clear();
-  for (const client of relay.cdpClients) {
-    try {
-      client.close(1011, 'extension disconnected');
-    } catch {
-      // ignore
-    }
-  }
-  relay.cdpClients.clear();
-  flushExtensionReconnectWaiters(relay, false);
-}
-
-function scheduleExtensionDisconnectCleanup(relay: UserRelay) {
-  clearGracePeriodTimer(relay);
-  relay.gracePeriodTimer = setTimeout(() => {
-    relay.gracePeriodTimer = null;
-    if (extensionConnected(relay)) return;
-    closeCdpClientsAfterExtensionDisconnect(relay);
-  }, DEFAULT_EXTENSION_RECONNECT_GRACE_MS);
-}
-
-async function waitForExtensionReconnect(relay: UserRelay, timeoutMs: number): Promise<boolean> {
-  if (extensionConnected(relay)) return true;
-  return await new Promise<boolean>((resolve) => {
-    let settled = false;
-    const waiter = (connected: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      relay.extensionReconnectWaiters.delete(waiter);
-      resolve(connected);
-    };
-    const timer = setTimeout(() => waiter(false), timeoutMs);
-    relay.extensionReconnectWaiters.add(waiter);
-  });
-}
-
-function sendToExtension(relay: UserRelay, payload: ExtensionForwardCommandMessage): Promise<unknown> {
-  const ws = relay.extensionWs;
-  if (!ws || ws.readyState !== WebSocket.OPEN) {
-    throw new Error('Chrome extension not connected');
-  }
-  ws.send(JSON.stringify(payload));
-  return new Promise<unknown>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      relay.pendingExtension.delete(payload.id);
-      reject(new Error(`extension request timeout: ${payload.params.method}`));
-    }, 30_000);
-    relay.pendingExtension.set(payload.id, { resolve, reject, timer });
-  });
-}
-
-function broadcastToCdpClients(relay: UserRelay, evt: CdpEvent) {
-  const msg = JSON.stringify(evt);
-  for (const ws of relay.cdpClients) {
-    if (ws.readyState !== WebSocket.OPEN) continue;
-    ws.send(msg);
-  }
-}
-
-function sendResponseToCdp(ws: ServerWebSocket<WSData>, res: CdpResponse) {
-  if (ws.readyState !== WebSocket.OPEN) return;
-  ws.send(JSON.stringify(res));
-}
-
-function ensureTargetEventsForClient(relay: UserRelay, ws: ServerWebSocket<WSData>, mode: 'autoAttach' | 'discover') {
-  for (const target of relay.connectedTargets.values()) {
-    if (mode === 'autoAttach') {
-      ws.send(
-        JSON.stringify({
-          method: 'Target.attachedToTarget',
-          params: {
-            sessionId: target.sessionId,
-            targetInfo: { ...target.targetInfo, attached: true },
-            waitingForDebugger: false,
-          },
-        } satisfies CdpEvent),
-      );
-    } else {
-      ws.send(
-        JSON.stringify({
-          method: 'Target.targetCreated',
-          params: { targetInfo: { ...target.targetInfo, attached: true } },
-        } satisfies CdpEvent),
-      );
-    }
-  }
-}
-
-async function routeCdpCommand(relay: UserRelay, cmd: CdpCommand): Promise<unknown> {
-  switch (cmd.method) {
-    case 'Browser.getVersion':
-      return {
-        protocolVersion: '1.3',
-        product: 'Chrome/Officer-Browser-Relay',
-        revision: '0',
-        userAgent: 'Officer-Browser-Relay',
-        jsVersion: 'V8',
-      };
-    case 'Browser.setDownloadBehavior':
-      return {};
-    case 'Target.setAutoAttach':
-    case 'Target.setDiscoverTargets':
-      return {};
-    case 'Target.getTargets':
-      return {
-        targetInfos: Array.from(relay.connectedTargets.values()).map((t) => ({
-          ...t.targetInfo,
-          attached: true,
-        })),
-      };
-    case 'Target.getTargetInfo': {
-      const params = (cmd.params ?? {}) as { targetId?: string };
-      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
-      if (targetId) {
-        for (const t of relay.connectedTargets.values()) {
-          if (t.targetId === targetId) return { targetInfo: t.targetInfo };
-        }
-      }
-      if (cmd.sessionId && relay.connectedTargets.has(cmd.sessionId)) {
-        const t = relay.connectedTargets.get(cmd.sessionId);
-        if (t) return { targetInfo: t.targetInfo };
-      }
-      const first = Array.from(relay.connectedTargets.values())[0];
-      return { targetInfo: first?.targetInfo };
-    }
-    case 'Target.attachToTarget': {
-      const params = (cmd.params ?? {}) as { targetId?: string };
-      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
-      if (!targetId) throw new Error('targetId required');
-      for (const t of relay.connectedTargets.values()) {
-        if (t.targetId === targetId) return { sessionId: t.sessionId };
-      }
-      throw new Error('target not found');
-    }
-    default: {
-      const id = relay.nextExtensionId++;
-      return await sendToExtension(relay, {
-        id,
-        method: 'forwardCDPCommand',
-        params: {
-          method: cmd.method,
-          sessionId: cmd.sessionId,
-          params: cmd.params,
-        },
-      });
-    }
-  }
-}
-
-function handleExtensionMessage(relay: UserRelay, data: string) {
-  let parsed: ExtensionMessage | null = null;
-  try {
-    parsed = JSON.parse(data) as ExtensionMessage;
-  } catch {
-    return;
-  }
-
-  if (parsed && typeof parsed === 'object' && 'id' in parsed && typeof parsed.id === 'number') {
-    const pending = relay.pendingExtension.get(parsed.id);
-    if (!pending) return;
-    relay.pendingExtension.delete(parsed.id);
-    clearTimeout(pending.timer);
-    if ('error' in parsed && typeof parsed.error === 'string' && parsed.error.trim()) {
-      pending.reject(new Error(parsed.error));
-    } else {
-      pending.resolve(parsed.result);
-    }
-    return;
-  }
-
-  if (parsed && typeof parsed === 'object' && 'method' in parsed) {
-    if ((parsed as ExtensionPongMessage).method === 'pong') return;
-    if ((parsed as ExtensionForwardEventMessage).method !== 'forwardCDPEvent') return;
-
-    const evt = parsed as ExtensionForwardEventMessage;
-    const method = evt.params?.method;
-    const params = evt.params?.params;
-    const sessionId = evt.params?.sessionId;
-    if (!method || typeof method !== 'string') return;
-
-    if (method === 'Target.attachedToTarget') {
-      const attached = (params ?? {}) as AttachedToTargetEvent;
-      const targetType = attached?.targetInfo?.type ?? 'page';
-      if (targetType !== 'page') return;
-      if (attached?.sessionId && attached?.targetInfo?.targetId) {
-        const prev = relay.connectedTargets.get(attached.sessionId);
-        const nextTargetId = attached.targetInfo.targetId;
-        const prevTargetId = prev?.targetId;
-        const changedTarget = Boolean(prev && prevTargetId && prevTargetId !== nextTargetId);
-        relay.connectedTargets.set(attached.sessionId, {
-          sessionId: attached.sessionId,
-          targetId: nextTargetId,
-          targetInfo: attached.targetInfo,
-        });
-        if (changedTarget && prevTargetId) {
-          broadcastToCdpClients(relay, {
-            method: 'Target.detachedFromTarget',
-            params: { sessionId: attached.sessionId, targetId: prevTargetId },
-            sessionId: attached.sessionId,
-          });
-        }
-        if (!prev || changedTarget) {
-          broadcastToCdpClients(relay, { method, params, sessionId });
-        }
-        return;
-      }
-    }
-
-    if (method === 'Target.detachedFromTarget') {
-      const detached = (params ?? {}) as DetachedFromTargetEvent;
-      if (detached?.sessionId) {
-        relay.connectedTargets.delete(detached.sessionId);
-      }
-      broadcastToCdpClients(relay, { method, params, sessionId });
-      return;
-    }
-
-    if (method === 'Target.targetInfoChanged') {
-      const changed = (params ?? {}) as { targetInfo?: { targetId?: string; type?: string } };
-      const targetInfo = changed?.targetInfo;
-      const targetId = targetInfo?.targetId;
-      if (targetId && (targetInfo?.type ?? 'page') === 'page') {
-        for (const [sid, target] of relay.connectedTargets) {
-          if (target.targetId !== targetId) continue;
-          relay.connectedTargets.set(sid, {
-            ...target,
-            targetInfo: { ...target.targetInfo, ...(targetInfo as object) },
-          });
-        }
-      }
-    }
-
-    broadcastToCdpClients(relay, { method, params, sessionId });
-  }
-}
-
-function handleExtensionClose(relay: UserRelay, ws: ServerWebSocket<WSData>) {
-  if (relay.extensionWs !== ws) return;
-  if (relay.pingInterval) {
-    clearInterval(relay.pingInterval);
-    relay.pingInterval = null;
-  }
-  relay.extensionWs = null;
-  for (const [, pending] of relay.pendingExtension) {
-    clearTimeout(pending.timer);
-    pending.reject(new Error('extension disconnected'));
-  }
-  relay.pendingExtension.clear();
-  scheduleExtensionDisconnectCleanup(relay);
-}
-
-function handleExtensionOpen(relay: UserRelay, ws: ServerWebSocket<WSData>) {
-  relay.extensionWs = ws;
-  clearGracePeriodTimer(relay);
-  flushExtensionReconnectWaiters(relay, true);
-
-  relay.pingInterval = setInterval(() => {
-    if (ws.readyState !== WebSocket.OPEN) return;
-    ws.send(JSON.stringify({ method: 'ping' }));
-  }, 5000);
-}
-
-async function handleCdpMessage(relay: UserRelay, ws: ServerWebSocket<WSData>, data: string) {
-  let cmd: CdpCommand | null = null;
-  try {
-    cmd = JSON.parse(data) as CdpCommand;
-  } catch {
-    return;
-  }
-  if (!cmd || typeof cmd !== 'object') return;
-  if (typeof cmd.id !== 'number' || typeof cmd.method !== 'string') return;
-
-  if (!extensionConnected(relay)) {
-    const reconnected = await waitForExtensionReconnect(relay, DEFAULT_EXTENSION_COMMAND_RECONNECT_WAIT_MS);
-    if (!reconnected || !extensionConnected(relay)) {
-      sendResponseToCdp(ws, {
-        id: cmd.id,
-        sessionId: cmd.sessionId,
-        error: { message: 'Extension not connected' },
-      });
-      return;
-    }
-  }
-
-  try {
-    const result = await routeCdpCommand(relay, cmd);
-
-    if (cmd.method === 'Target.setAutoAttach' && !cmd.sessionId) {
-      ensureTargetEventsForClient(relay, ws, 'autoAttach');
-    }
-    if (cmd.method === 'Target.setDiscoverTargets') {
-      const discover = (cmd.params ?? {}) as { discover?: boolean };
-      if (discover.discover === true) {
-        ensureTargetEventsForClient(relay, ws, 'discover');
-      }
-    }
-    if (cmd.method === 'Target.attachToTarget') {
-      const params = (cmd.params ?? {}) as { targetId?: string };
-      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
-      if (targetId) {
-        const target = Array.from(relay.connectedTargets.values()).find((t) => t.targetId === targetId);
-        if (target) {
-          ws.send(
-            JSON.stringify({
-              method: 'Target.attachedToTarget',
-              params: {
-                sessionId: target.sessionId,
-                targetInfo: { ...target.targetInfo, attached: true },
-                waitingForDebugger: false,
-              },
-            } satisfies CdpEvent),
-          );
-        }
-      }
-    }
-
-    sendResponseToCdp(ws, { id: cmd.id, sessionId: cmd.sessionId, result });
-  } catch (err) {
-    sendResponseToCdp(ws, {
-      id: cmd.id,
-      sessionId: cmd.sessionId,
-      error: { message: err instanceof Error ? err.message : String(err) },
-    });
-  }
-}
-
-function getTokenFromUrl(url: string): string | null {
-  try {
-    const parsed = new URL(url, 'http://localhost');
-    return parsed.searchParams.get('token')?.trim() ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function getTokenFromHeaders(headers: Headers): string | null {
-  return headers.get(RELAY_AUTH_HEADER)?.trim() ?? null;
-}
-
-function getTokenFromRequest(req: Request): string | null {
-  return getTokenFromHeaders(req.headers) ?? getTokenFromUrl(req.url);
-}
-
-function authenticateRequest(req: Request): number | null {
-  const token = getTokenFromRequest(req);
-  if (!token) return null;
-  return resolveUserFromToken(token);
-}
-
-let relayServer: ReturnType<typeof Bun.serve> | null = null;
-let relayPort = 0;
-
-export function getRelayPort(): number {
-  return relayPort;
-}
-
-export function getUserRelayStatus(userId: number): { extensionConnected: boolean; targetCount: number } {
-  const relay = userRelays.get(userId);
-  if (!relay) return { extensionConnected: false, targetCount: 0 };
-  return {
-    extensionConnected: extensionConnected(relay),
-    targetCount: relay.connectedTargets.size,
-  };
-}
-
-export function getUserTargets(userId: number): ConnectedTarget[] {
-  const relay = userRelays.get(userId);
-  if (!relay) return [];
-  return Array.from(relay.connectedTargets.values());
-}
-
-export async function startBrowserRelay(port: number) {
-  relayPort = port;
-
-  // Restore persisted relay tokens from DB
-  const integrations = await getIntegrationsByProvider('browser-relay');
-  const entries = integrations
-    .map((i) => ({ userId: i.userId, salt: (i.config as { tokenSalt?: string })?.tokenSalt }))
-    .filter((e): e is { userId: number; salt: string } => Boolean(e.salt));
-  if (entries.length > 0) {
-    restoreUserTokens(entries, port);
-  }
-
-  const server = Bun.serve<WSData>({
-    port,
-    hostname: '0.0.0.0',
-    idleTimeout: 60,
-
-    routes: {
-      '/': (req: Request) => {
-        if (req.method === 'HEAD') return new Response(null, { status: 200 });
-        return new Response('OK', { status: 200, headers: { 'Content-Type': 'text/plain' } });
-      },
-    },
-
-    fetch(req, server) {
-      const url = new URL(req.url);
-      const path = url.pathname;
-
-      // CORS for chrome-extension origins
-      const origin = req.headers.get('origin');
-      const corsHeaders: Record<string, string> = {};
-      if (origin) {
-        corsHeaders['Access-Control-Allow-Origin'] = origin;
-        corsHeaders['Vary'] = 'Origin';
-      }
-
-      if (req.method === 'OPTIONS') {
-        return new Response(null, {
-          status: 204,
-          headers: {
-            ...corsHeaders,
-            'Access-Control-Allow-Methods': 'GET, PUT, POST, OPTIONS',
-            'Access-Control-Allow-Headers': `Content-Type, ${RELAY_AUTH_HEADER}`,
-            'Access-Control-Max-Age': '86400',
-          },
-        });
-      }
-
-      if (path === '/extension/status') {
-        const connectedCount = Array.from(userRelays.values()).filter((r) => extensionConnected(r)).length;
-        return Response.json({ connected: connectedCount > 0, users: connectedCount }, { headers: corsHeaders });
-      }
-
-      // Auth-protected endpoints
-      const token = getTokenFromRequest(req);
-      const userId = token ? resolveUserFromToken(token) : null;
-
-      if (path === '/json/version' || path === '/json/version/') {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const relay = userRelays.get(userId);
-        const payload: Record<string, unknown> = {
-          Browser: 'Officer/browser-relay',
-          'Protocol-Version': '1.3',
-        };
-        if (relay && extensionConnected(relay)) {
-          const hostHeader = req.headers.get('host')?.trim() || `0.0.0.0:${port}`;
-          payload.webSocketDebuggerUrl = `ws://${hostHeader}/cdp?token=${token}`;
-        }
-        return Response.json(payload, { headers: corsHeaders });
-      }
-
-      const listPaths = new Set(['/json', '/json/', '/json/list', '/json/list/']);
-      if (listPaths.has(path)) {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const relay = userRelays.get(userId);
-        const hostHeader = req.headers.get('host')?.trim() || `0.0.0.0:${port}`;
-        const cdpWsUrl = `ws://${hostHeader}/cdp?token=${token}`;
-        const list = relay
-          ? Array.from(relay.connectedTargets.values()).map((t) => ({
-              id: t.targetId,
-              type: t.targetInfo.type ?? 'page',
-              title: t.targetInfo.title ?? '',
-              description: t.targetInfo.title ?? '',
-              url: t.targetInfo.url ?? '',
-              webSocketDebuggerUrl: cdpWsUrl,
-            }))
-          : [];
-        return Response.json(list, { headers: corsHeaders });
-      }
-
-      const activateMatch = path.match(/^\/json\/activate\/(.+)$/);
-      if (activateMatch) {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const targetId = decodeURIComponent(activateMatch[1]!).trim();
-        if (!targetId) return new Response('targetId required', { status: 400, headers: corsHeaders });
-        const relay = userRelays.get(userId);
-        if (relay && extensionConnected(relay)) {
-          void sendToExtension(relay, {
-            id: relay.nextExtensionId++,
-            method: 'forwardCDPCommand',
-            params: { method: 'Target.activateTarget', params: { targetId } },
-          }).catch(() => {});
-        }
-        return new Response('OK', { status: 200, headers: corsHeaders });
-      }
-
-      const closeMatch = path.match(/^\/json\/close\/(.+)$/);
-      if (closeMatch) {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const targetId = decodeURIComponent(closeMatch[1]!).trim();
-        if (!targetId) return new Response('targetId required', { status: 400, headers: corsHeaders });
-        const relay = userRelays.get(userId);
-        if (relay && extensionConnected(relay)) {
-          void sendToExtension(relay, {
-            id: relay.nextExtensionId++,
-            method: 'forwardCDPCommand',
-            params: { method: 'Target.closeTarget', params: { targetId } },
-          }).catch(() => {});
-        }
-        return new Response('OK', { status: 200, headers: corsHeaders });
-      }
-
-      // WebSocket upgrades
-      if (path === '/extension') {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const relay = getUserRelay(userId);
-        // Close existing extension WS (stale or active) — last connection wins
-        if (relay.extensionWs) {
-          try {
-            relay.extensionWs.close(4000, 'replaced by new connection');
-          } catch {
-            // ignore
-          }
-          relay.extensionWs = null;
-        }
-        const ok = server.upgrade(req, { data: { kind: 'extension', userId, token: token! } });
-        if (!ok) return new Response('Upgrade failed', { status: 500, headers: corsHeaders });
-        return undefined as unknown as Response;
-      }
-
-      if (path === '/cdp') {
-        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
-        const relay = userRelays.get(userId);
-        if (!relay || !extensionConnected(relay)) {
-          return new Response('Extension not connected', { status: 503, headers: corsHeaders });
-        }
-        const ok = server.upgrade(req, { data: { kind: 'cdp', userId, token: token! } });
-        if (!ok) return new Response('Upgrade failed', { status: 500, headers: corsHeaders });
-        return undefined as unknown as Response;
-      }
-
-      return new Response('Not found', { status: 404, headers: corsHeaders });
-    },
-
-    websocket: {
-      open(ws) {
-        const { kind, userId } = ws.data;
-        const relay = getUserRelay(userId);
-
-        if (kind === 'extension') {
-          handleExtensionOpen(relay, ws);
-        } else {
-          relay.cdpClients.add(ws);
-        }
-      },
-
-      message(ws, raw) {
-        const { kind, userId } = ws.data;
-        const relay = userRelays.get(userId);
-        if (!relay) return;
-        const data = typeof raw === 'string' ? raw : new TextDecoder().decode(raw as unknown as ArrayBuffer);
-
-        if (kind === 'extension') {
-          handleExtensionMessage(relay, data);
-        } else {
-          void handleCdpMessage(relay, ws, data);
-        }
-      },
-
-      close(ws) {
-        const { kind, userId } = ws.data;
-        const relay = userRelays.get(userId);
-        if (!relay) return;
-
-        if (kind === 'extension') {
-          handleExtensionClose(relay, ws);
-        } else {
-          relay.cdpClients.delete(ws);
-        }
-      },
-    },
-  });
-
-  relayServer = server;
-  return server;
-}
-
-export function stopBrowserRelay() {
-  if (!relayServer) return;
-  for (const [, relay] of userRelays) {
-    clearGracePeriodTimer(relay);
-    if (relay.pingInterval) clearInterval(relay.pingInterval);
-    flushExtensionReconnectWaiters(relay, false);
-    for (const [, pending] of relay.pendingExtension) {
-      clearTimeout(pending.timer);
-      pending.reject(new Error('server stopping'));
-    }
-    relay.pendingExtension.clear();
-    try {
-      relay.extensionWs?.close(1001, 'server stopping');
-    } catch {
-      // ignore
-    }
-    for (const ws of relay.cdpClients) {
-      try {
-        ws.close(1001, 'server stopping');
-      } catch {
-        // ignore
-      }
-    }
-  }
-  userRelays.clear();
-  relayServer.stop();
-  relayServer = null;
-}

src/servers/api/browser/router.ts

@@ -1,185 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { createRouter } from '@@/create-router';
-import * as errors from '@@/custom-errors';
-import { getUserIntegration, upsertUserIntegration, deleteUserIntegration } from 'officerdb';
-import { deriveRelayToken, registerUserToken, unregisterUserToken } from './relay-auth';
-import { getRelayPort, getUserRelayStatus, getUserTargets } from './relay';
-import { captureScreenshot, evaluateJS, navigateTo } from './cdp';
-
-export const browserRouter = createRouter();
-
-async function getOpts(userId: number) {
-  const port = getRelayPort();
-  const integration = await getUserIntegration(userId, 'browser-relay');
-  const salt = (integration?.config as { tokenSalt?: string } | null)?.tokenSalt ?? randomUUID();
-  if (!integration) {
-    await upsertUserIntegration({ userId, provider: 'browser-relay', config: { tokenSalt: salt } });
-  }
-  const token = registerUserToken(userId, port, salt);
-  return { relayPort: port, userToken: token };
-}
-
-// GET /extension-download used to zip the extension directory on the fly, shelling out to `zip`. It had
-// no caller: BrowserRelay.tsx links straight at /browser-relay-extension.zip, a real file in public/.
-
-browserRouter.get('/status', async (ctx) => {
-  const user = ctx.get('user');
-  const status = getUserRelayStatus(user.id);
-  return ctx.json(status);
-});
-
-browserRouter.get('/relay-token', async (ctx) => {
-  const user = ctx.get('user');
-  const port = getRelayPort();
-  let integration = await getUserIntegration(user.id, 'browser-relay');
-  if (!integration) {
-    const salt = randomUUID();
-    integration = await upsertUserIntegration({
-      userId: user.id,
-      provider: 'browser-relay',
-      config: { tokenSalt: salt },
-    });
-  }
-  const salt = (integration.config as { tokenSalt: string }).tokenSalt;
-  const token = registerUserToken(user.id, port, salt);
-  return ctx.json({ token, port });
-});
-
-browserRouter.post('/relay-token/regenerate', async (ctx) => {
-  const user = ctx.get('user');
-  const port = getRelayPort();
-  const oldIntegration = await getUserIntegration(user.id, 'browser-relay');
-  if (oldIntegration) {
-    const oldSalt = (oldIntegration.config as { tokenSalt?: string })?.tokenSalt;
-    if (oldSalt) {
-      const oldToken = deriveRelayToken(user.id, port, oldSalt);
-      unregisterUserToken(oldToken);
-    }
-  }
-  const newSalt = randomUUID();
-  await upsertUserIntegration({ userId: user.id, provider: 'browser-relay', config: { tokenSalt: newSalt } });
-  const token = registerUserToken(user.id, port, newSalt);
-  return ctx.json({ token, port });
-});
-
-browserRouter.delete('/relay-token', async (ctx) => {
-  const user = ctx.get('user');
-  const port = getRelayPort();
-  const integration = await getUserIntegration(user.id, 'browser-relay');
-  if (integration) {
-    const salt = (integration.config as { tokenSalt?: string })?.tokenSalt;
-    if (salt) {
-      const oldToken = deriveRelayToken(user.id, port, salt);
-      unregisterUserToken(oldToken);
-    }
-    await deleteUserIntegration(user.id, 'browser-relay');
-  }
-  return ctx.json({ ok: true });
-});
-
-browserRouter.get('/targets', async (ctx) => {
-  const user = ctx.get('user');
-  const targets = getUserTargets(user.id);
-  return ctx.json(
-    targets.map((t) => ({
-      id: t.targetId,
-      sessionId: t.sessionId,
-      type: t.targetInfo.type ?? 'page',
-      title: t.targetInfo.title ?? '',
-      url: t.targetInfo.url ?? '',
-    })),
-  );
-});
-
-browserRouter.get('/targets/:id/screenshot', async (ctx) => {
-  const user = ctx.get('user');
-  const targetId = ctx.req.param('id');
-  const format = (ctx.req.query('format') as 'png' | 'jpeg') || 'png';
-
-  const opts = await getOpts(user.id);
-  // Find session ID for the target
-  const targets = getUserTargets(user.id);
-  const target = targets.find((t) => t.targetId === targetId);
-  if (!target) throw errors.NOT_FOUND('Target not found');
-
-  try {
-    const data = await captureScreenshot({ ...opts, targetId: target.sessionId }, format);
-    return ctx.json({ data, format });
-  } catch (err) {
-    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Screenshot failed');
-  }
-});
-
-browserRouter.post('/targets/:id/evaluate', async (ctx) => {
-  const user = ctx.get('user');
-  const targetId = ctx.req.param('id');
-  const body = ctx.get('body') as { expression?: string };
-
-  if (!body.expression) throw errors.BAD_REQUEST('expression is required');
-
-  const opts = await getOpts(user.id);
-  const targets = getUserTargets(user.id);
-  const target = targets.find((t) => t.targetId === targetId);
-  if (!target) throw errors.NOT_FOUND('Target not found');
-
-  try {
-    const result = await evaluateJS({ ...opts, targetId: target.sessionId }, body.expression);
-    return ctx.json({ result });
-  } catch (err) {
-    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Evaluation failed');
-  }
-});
-
-browserRouter.post('/targets/:id/navigate', async (ctx) => {
-  const user = ctx.get('user');
-  const targetId = ctx.req.param('id');
-  const body = ctx.get('body') as { url?: string };
-
-  if (!body.url) throw errors.BAD_REQUEST('url is required');
-
-  const opts = await getOpts(user.id);
-  const targets = getUserTargets(user.id);
-  const target = targets.find((t) => t.targetId === targetId);
-  if (!target) throw errors.NOT_FOUND('Target not found');
-
-  try {
-    await navigateTo({ ...opts, targetId: target.sessionId }, body.url);
-    return ctx.json({ ok: true });
-  } catch (err) {
-    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Navigation failed');
-  }
-});
-
-browserRouter.post('/targets/:id/activate', async (ctx) => {
-  const user = ctx.get('user');
-  const targetId = ctx.req.param('id');
-
-  const { relayPort, userToken } = await getOpts(user.id);
-
-  try {
-    const res = await fetch(`http://127.0.0.1:${relayPort}/json/activate/${encodeURIComponent(targetId)}`, {
-      headers: { 'x-officer-relay-token': userToken },
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return ctx.json({ ok: true });
-  } catch (err) {
-    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Activate failed');
-  }
-});
-
-browserRouter.post('/targets/:id/close', async (ctx) => {
-  const user = ctx.get('user');
-  const targetId = ctx.req.param('id');
-
-  const { relayPort, userToken } = await getOpts(user.id);
-
-  try {
-    const res = await fetch(`http://127.0.0.1:${relayPort}/json/close/${encodeURIComponent(targetId)}`, {
-      headers: { 'x-officer-relay-token': userToken },
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return ctx.json({ ok: true });
-  } catch (err) {
-    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Close failed');
-  }
-});

src/servers/api/chat/chat.ts

@@ -14,6 +14,7 @@ import {
   setChatNotifyPreference,
 } from 'officerdb';
 import type { NotifyPreference } from 'officerdb/types';
+import { setNudge, getNudge, cancelNudge } from 'officerdb';
 import {
   listClaudePwds,
   listClaudeSessions,
@@ -548,3 +549,52 @@ chatRouter.post('/stt', async (ctx: Context) => {
 // Lives on this router because it is the same authority `chat` already grants: creating and naming
 // Claude sessions. See servers/api/chat/agent-panels-routes.ts and docs/agent-coordination.md.
 registerAgentPanelRoutes(chatRouter);
+
+// ── Nudger ──
+//
+// A schedule that keeps one chat moving while nobody is watching it. The tick lives in ./nudger.ts; these
+// are only the three verbs the composer needs.
+//
+// Scoped to the caller like every other per-session route here. A nudge is a prompt sent AS someone, so a
+// schedule readable or writable across accounts would be a way to speak in another person's chat.
+
+const MIN_EVERY_SECONDS = 60;
+const MAX_EVERY_SECONDS = 86_400;
+
+// GET /chat/sessions/:id/nudge — the current schedule, or null.
+chatRouter.get('/sessions/:id/nudge', async (ctx) => {
+  const user = ctx.get('user');
+  await chatIdentity(user);
+  return ctx.json({ nudge: await getNudge(user.id, ctx.req.param('id')) });
+});
+
+// PUT /chat/sessions/:id/nudge — arm or re-arm. Re-arming resets the count: it is a new night.
+chatRouter.put('/sessions/:id/nudge', async (ctx) => {
+  const user = ctx.get('user');
+  await chatIdentity(user);
+
+  const body = await ctx.req.json<{ message?: string; everySeconds?: number; maxCount?: number }>();
+  const message = typeof body.message === 'string' ? body.message.trim() : '';
+  if (!message) return ctx.text('message is required', 400);
+
+  const everySeconds = Number(body.everySeconds ?? 3600);
+  const maxCount = Number(body.maxCount ?? 12);
+  // The floor is the tick interval — anything under it is a lie about cadence rather than a faster nudge.
+  if (!Number.isFinite(everySeconds) || everySeconds < MIN_EVERY_SECONDS || everySeconds > MAX_EVERY_SECONDS) {
+    return ctx.text(`everySeconds must be between ${MIN_EVERY_SECONDS} and ${MAX_EVERY_SECONDS}`, 400);
+  }
+  if (!Number.isFinite(maxCount) || maxCount < 1 || maxCount > 100) {
+    return ctx.text('maxCount must be between 1 and 100', 400);
+  }
+
+  const nudge = await setNudge({ userId: user.id, sessionId: ctx.req.param('id'), message, everySeconds, maxCount });
+  return ctx.json({ nudge });
+});
+
+// DELETE /chat/sessions/:id/nudge — disarm. Idempotent: cancelling an absent schedule is success.
+chatRouter.delete('/sessions/:id/nudge', async (ctx) => {
+  const user = ctx.get('user');
+  await chatIdentity(user);
+  await cancelNudge(user.id, ctx.req.param('id'));
+  return ctx.json({ ok: true });
+});

src/servers/api/chat/nudger.ts

@@ -0,0 +1,168 @@
+import { dueNudges, recordNudgeSent, cancelNudge, getUserById } from 'officerdb';
+import * as sidecar from '@@/sidecar-registry';
+import { resolveHomeDir } from '@@/user-home';
+import { startClaudeTurn } from './websocket';
+
+// Nudger: the schedule that keeps a chat moving while nobody is watching it.
+//
+// ── Why this can exist at all ──
+//
+// `startClaudeTurn` already takes `ws: null`. It was extracted that way so `POST /command-hq/commanders/new`
+// could drive a turn over HTTP, and that is the whole door this feature needed — a way into a live session
+// that is not the chat websocket. Nothing new is exposed; this is a second caller of an existing path.
+//
+// ── The rule that matters ──
+//
+// NEVER speak while the agent is working. A prompt delivered mid-turn is noise at best and a derail at
+// worst, and the point of this is to restart a stopped agent rather than hurry a busy one.
+//
+// So `every_seconds` is a FLOOR, not a metronome. When a nudge comes due and the session is generating,
+// the row is left alone and reconsidered on the next tick — which means it fires as soon as the turn ends
+// rather than sleeping through to the next hour. "At most every N seconds, and as soon as idle after
+// that" is what someone asking for this actually wants; a strict hourly alarm would skip an agent that
+// finished four minutes late and leave it idle for the other fifty-six.
+
+const TICK_MS = 60_000;
+
+type Safety = { safe: true } | { safe: false; reason: string; disable: boolean };
+
+/**
+ * May we speak into this session right now?
+ *
+ * ── The failure this replaced ──
+ *
+ * This used to ask one question, "is it generating", and treat NO as permission. That is exactly
+ * backwards, and on 2026-08-20 it cost a working agent its afternoon: the target session had been
+ * garbage-collected, so it was not generating, so the nudge fired — and `startClaudeTurn` given a session
+ * the sidecar no longer holds does not resume it, it starts a NEW one. A second Claude with bypassed
+ * permissions appeared in a repository another agent was mid-build in. Nothing was lost only because that
+ * agent noticed the collision and stopped rather than committing over the work.
+ *
+ * So there are three questions, and only one answer is permission:
+ *
+ *   - **Not live at all** → refuse, and disarm. Nudging it would CREATE an agent, which is not what a
+ *     schedule attached to a conversation means and never was.
+ *   - **Live but generating** → refuse, keep the schedule. It is working; that is the whole rule.
+ *   - **Another session live in the same directory** → refuse, keep the schedule. Two agents with
+ *     bypassed permissions in one working tree is not something to arrange on purpose.
+ */
+async function checkSafe(userId: number, sessionId: string): Promise<Safety> {
+  try {
+    const live = await sidecar.listLiveClaudeSessions(userId);
+    // Matched on BOTH ids on purpose. `sessionKey` is officer's handle for the conversation;
+    // `claudeSessionId` is the transcript's own filename, and only the agent holds the mapping. A schedule
+    // stored against one would silently never match a live row keyed by the other.
+    const mine = live.find((s) => s.sessionKey === sessionId || s.claudeSessionId === sessionId);
+
+    if (!mine) {
+      return {
+        safe: false,
+        reason: 'the session is no longer live — nudging it would start a NEW agent, not continue this one',
+        disable: true,
+      };
+    }
+    if (mine.isGenerating) return { safe: false, reason: 'working', disable: false };
+
+    // Anything else alive belongs to another conversation. It may or may not share this one's directory —
+    // the sidecar does not say — so this refuses on the presence of any other live session rather than on
+    // a directory comparison it cannot actually make.
+    const others = live.filter((s) => s !== mine).length;
+    if (others > 0) {
+      return {
+        safe: false,
+        reason: `${others} other live session(s) — refusing to add a second agent`,
+        disable: false,
+      };
+    }
+
+    return { safe: true };
+  } catch {
+    // Unknown is not permission. A sidecar that cannot answer might be running a turn, and interrupting one
+    // is the failure this exists to avoid — so silence is the safe answer.
+    return { safe: false, reason: 'sidecar did not answer', disable: false };
+  }
+}
+
+async function fire(nudge: { id: number; userId: number; sessionId: string; message: string }): Promise<void> {
+  const user = await getUserById(nudge.userId);
+  const resolved = await resolveHomeDir(nudge.userId);
+  if (!user || !resolved.ok) return;
+
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (!settled) {
+        settled = true;
+        resolve();
+      }
+    };
+    // A turn that never reports back must not wedge the tick — the next one will reconsider the row.
+    const timer = setTimeout(done, 30_000);
+
+    void startClaudeTurn({
+      email: user.email,
+      username: user.username ?? user.email,
+      userId: nudge.userId,
+      // No socket. Whoever is watching the chat gets the turn through their own connection, the same way
+      // they would see a turn started from another tab.
+      ws: null,
+      sessionId: nudge.sessionId,
+      model: 'claude-code/sonnet',
+      msg: { prompt: nudge.message, resumeSessionId: nudge.sessionId },
+      effectivePrompt: nudge.message,
+      onOutcome: (outcome) => {
+        clearTimeout(timer);
+        if (!outcome.ok) console.error(`[nudger] session ${nudge.sessionId}: ${outcome.error}`);
+        done();
+      },
+    }).catch((err) => {
+      clearTimeout(timer);
+      console.error(`[nudger] session ${nudge.sessionId} threw:`, err instanceof Error ? err.message : err);
+      done();
+    });
+  });
+
+  // Counted whether or not the turn reported success. A nudge that failed to start still consumed its slot;
+  // retrying it immediately would be a tight loop against whatever refused it.
+  await recordNudgeSent(nudge.id);
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Start the tick. Called once from `server.tsx`.
+ *
+ * One tick at a time — `running` guards against a slow tick overlapping the next, which would double-fire
+ * a due nudge. `unref` so this never holds the process open on its own.
+ */
+export function startNudger(): void {
+  if (timer) return;
+  let running = false;
+
+  timer = setInterval(async () => {
+    if (running) return;
+    running = true;
+    try {
+      for (const nudge of await dueNudges()) {
+        const check = await checkSafe(nudge.userId, nudge.sessionId);
+        if (!check.safe) {
+          if (check.disable) {
+            console.warn(`[nudger] session ${nudge.sessionId} disarmed — ${check.reason}`);
+            await cancelNudge(nudge.userId, nudge.sessionId);
+          }
+          continue; // otherwise reconsidered next tick
+        }
+        console.log(`[nudger] session ${nudge.sessionId} idle — nudging (${nudge.sentCount + 1}/${nudge.maxCount})`);
+        await fire(nudge);
+      }
+    } catch (err) {
+      // A bad tick must not stop every later one.
+      console.error('[nudger] tick failed:', err instanceof Error ? err.message : err);
+    } finally {
+      running = false;
+    }
+  }, TICK_MS);
+
+  timer.unref?.();
+  console.log('[nudger] armed — checking every 60s');
+}

src/servers/api/command-hq/router.ts

@@ -1,6 +1,7 @@
 import type { Context } from 'hono';
 import { randomUUID } from 'node:crypto';
 import { createRouter } from '../../create-router';
+import { checkBudget } from '../sub-agents/budget';
 import * as errors from '@@/custom-errors';
 import { resolveHomeDir } from '@@/user-home';
 import { getCommandersDir, toShellUsername } from '@@/data-path';
@@ -269,6 +270,17 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
   const prompt = body.prompt?.trim();
   if (!prompt) throw errors.BAD_REQUEST('prompt is required');
 
+  // ── Room to run, before starting work nobody is watching ──
+  //
+  // A commander created here runs unattended. If it burns the last of a window, the session the owner is
+  // actually sitting in dies mid-turn — the credits went somewhere nobody was looking. So the floor is
+  // checked at the one door that starts unattended work, rather than left to whoever calls it.
+  //
+  // It fails OPEN by design (see budget.ts): the numbers come from an external endpoint with a credential
+  // Officer does not own, and a network blip must not stop every spawn on the machine.
+  const budget = await checkBudget();
+  if (!budget.ok) throw errors.TOO_MANY_REQUESTS(budget.reason ?? 'not enough usage headroom to start an agent');
+
   const sessionId = randomUUID();
   const model = (await getUserDefaultModel(user.id)) || DEFAULT_MODEL;
 

src/servers/api/desktop/rest.ts

@@ -1,33 +0,0 @@
-import { createRouter } from '../../create-router';
-import * as sidecar from '@@/sidecar-registry';
-
-export const desktopRouter = createRouter();
-
-// The desktop UI asks for the password before it can open the WebSocket — and that WebSocket is what
-// starts the VNC session. So this cannot wait for a session to exist: on a fresh install nothing has
-// ever written the password, and answering "not configured" deadlocked the page permanently.
-//
-// Officer does not read the password file itself. It lives in the owner's ~/.vnc, next to the rfbauth
-// file x11vnc authenticates against, and the sidecar is the process that writes both — so it is the
-// process that answers for them too. `vnc:ensure-password` is idempotent: it returns the existing
-// pair when both files are already there, and provisions them when they are not.
-desktopRouter.get('/vnc-password', async (ctx) => {
-  const user = ctx.get('user');
-
-  if (!sidecar.isVncConnected()) {
-    return ctx.json({ error: 'VNC sidecar is not connected' }, 503);
-  }
-
-  try {
-    const password = await sidecar.ensureVncPassword(user.email);
-    return ctx.json({ password });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : 'Could not provision the VNC password';
-    console.error('[desktop] VNC password provisioning failed:', message);
-    return ctx.json({ error: message }, 500);
-  }
-});
-
-// GET /vnc-status is gone. It was never called — DesktopView asks only for /vnc-password — and it was
-// the sole reason the `vnc:status` command existed on the sidecar wire protocol at all. Noted as dead
-// by docs/sidecar-audit-2026-07.md months ago.

src/servers/api/desktop/websocket.ts

@@ -1,122 +0,0 @@
-import type { ServerWebSocket } from 'bun';
-import type { Socket } from 'bun';
-import * as sidecar from '@@/sidecar-registry';
-
-type WSData = { userId: number; email: string; username: string; sessionId?: string };
-
-type VncSession = {
-  tcpSocket: Socket<{ ws: ServerWebSocket<WSData> }> | null;
-  pendingMessages: Buffer[];
-};
-
-const sessions = new Map<ServerWebSocket<WSData>, VncSession>();
-
-export const desktopWebsocket = {
-  async open(ws: ServerWebSocket<WSData>) {
-    const session: VncSession = { tcpSocket: null, pendingMessages: [] };
-    sessions.set(ws, session);
-
-    let port: number;
-    try {
-      const result = await sidecar.startVnc({
-        email: ws.data.email,
-        username: ws.data.username,
-      });
-      port = result.port;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : 'Failed to start VNC session';
-      console.error('[desktop] VNC start failed:', message);
-      sessions.delete(ws);
-      ws.close(4004, 'VNC server unavailable');
-      return;
-    }
-
-    try {
-      const tcpSocket = await Bun.connect({
-        hostname: '127.0.0.1',
-        port,
-        socket: {
-          data(_socket, data) {
-            try {
-              ws.sendBinary(Buffer.from(data));
-            } catch {
-              // ws already closed
-            }
-          },
-          close() {
-            sessions.delete(ws);
-            try {
-              ws.close();
-            } catch {
-              /* ignore */
-            }
-          },
-          error(_socket, err) {
-            console.error('[desktop] TCP error:', err.message);
-            sessions.delete(ws);
-            try {
-              ws.close();
-            } catch {
-              /* ignore */
-            }
-          },
-          connectError(_socket, err) {
-            console.error('[desktop] TCP connect error:', err.message);
-            sessions.delete(ws);
-            try {
-              ws.close(4004, 'VNC server unavailable');
-            } catch {
-              /* ignore */
-            }
-          },
-          open(socket) {
-            for (const msg of session.pendingMessages) {
-              socket.write(msg);
-            }
-            session.pendingMessages = [];
-          },
-        },
-        data: { ws },
-      });
-
-      session.tcpSocket = tcpSocket;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : 'Failed to connect to VNC server';
-      console.error('[desktop] VNC connect failed:', message);
-      sessions.delete(ws);
-      ws.close(4004, 'VNC server unavailable');
-    }
-  },
-
-  message(ws: ServerWebSocket<WSData>, raw: string | Buffer) {
-    const session = sessions.get(ws);
-    if (!session) return;
-
-    const data = typeof raw === 'string' ? Buffer.from(raw) : Buffer.from(raw);
-
-    if (!session.tcpSocket) {
-      session.pendingMessages.push(data);
-      return;
-    }
-
-    try {
-      session.tcpSocket.write(data);
-    } catch {
-      // ignore
-    }
-  },
-
-  close(ws: ServerWebSocket<WSData>) {
-    const session = sessions.get(ws);
-    if (session?.tcpSocket) {
-      try {
-        session.tcpSocket.end();
-      } catch {
-        // ignore
-      }
-    }
-    sessions.delete(ws);
-  },
-
-  drain() {},
-};

src/servers/api/items/rescan.ts

@@ -1,13 +1,26 @@
-import { readdirSync, existsSync } from 'node:fs';
+import { readdirSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { createRouter } from '../../create-router';
 import { ITEM_TYPES, itemsDir, ensureItemDirs, type ItemType } from '../../data-path';
 import { ensureToolLoader } from '../../ensure-tool-loader';
+import { AFFORDANCES_DIR, loadAffordances } from '../../affordances/load';
+import { loadSkills } from '../../skills/load';
 
 // Re-applies the boot-time item setup so changes under OFFICER_ITEMS_DIR take effect without a
 // server restart. Item lists are already read fresh from disk on every request; this ensures the
 // type dirs exist and the tool-loader extension is current, and reports the live item counts so the
 // UI can refetch.
+//
+// ── Affordances are counted, NOT applied ──
+//
+// They are not an ITEM_TYPE — no directory per item, no canonical file — so they were invisible here
+// and a newly written one looked like nothing had happened.
+//
+// Counting them is as far as this can honestly go. `affordanceBlock()` is read when a chat session is
+// CREATED (claude-manager.ts), so a new affordance is already live without a server restart — for the
+// next session. Nothing can retrofit one into a conversation that is already running, because its
+// system prompt was assembled when it started. Reporting the count says "the file is on disk and the
+// platform can see it", which is the part that was genuinely unknowable from the UI.
 
 const CANONICAL: Record<ItemType, string> = {
   skills: 'SKILL.md',
@@ -32,9 +45,19 @@ export const rescanRouter = createRouter();
 
 rescanRouter.post('/', async (ctx) => {
   ensureItemDirs();
+  // So the directory is discoverable on a machine that has never had one, the same way the item dirs are.
+  mkdirSync(AFFORDANCES_DIR, { recursive: true });
   ensureToolLoader();
 
   const counts = Object.fromEntries(ITEM_TYPES.map((type) => [type, countItems(type)])) as Record<ItemType, number>;
 
-  return ctx.json({ ok: true, counts });
+  // Loaded rather than file-counted, so the number means "affordances the agent will actually receive"
+  // rather than "markdown files present" — one with no body is skipped by the loader and should not be
+  // reported as though it were working.
+  const affordances = loadAffordances().length;
+  // Loaded, not file-counted, for the same reason: a SKILL.md with no `description` is skipped by the
+  // loader and would otherwise be reported as working.
+  const skillsOffered = loadSkills().length;
+
+  return ctx.json({ ok: true, counts: { ...counts, affordances, skillsOffered } });
 });