Three changes, all from the owner's call.
The trigger is a tag, deploy/<version>, and nothing else. The code word it replaces could be written by
accident — every document about deploying contains it, this repository included, and so does every
conversation planning one. Defending that needs a rule about where in the subject line it sits, and a
rule like that is one somebody eventually gets wrong. A tag cannot be typed into prose, it names its own
version, and git ls-remote answers "is there one" without fetching.
The record of a deploy is LOCAL — data/deploys/<version>.done — not the pushed report. This is the part
that matters: making the report the marker means a failed push leaves the release looking undeployed and
the next tick rolls it out again. Pushes here fail for reasons unrelated to the rollout — gitea's public
SSH is rate-limited because every connection arrives from one proxy container IP that bots keep
penalised, which cost several retries tonight. So the lock cannot fail for a network reason, and the
report is an artefact: valuable, not load-bearing. Under data/ so a pull cannot clobber it.
And the commander skips the host it runs on ENTIRELY, naming it in the report. Restarting only officer
and leaving its own sidecar behind would work and is worse — one host in a state nobody chose, a step
behind, found later. The owner restarts it deliberately as the last step.
Tonight's deploy is backfilled: the lock file exists and deploy/2026.08.21.01 is tagged at bd41dff5, so
the mechanism has a precedent rather than starting from nothing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
deadpool-rezio-bridge joins the list: 100.64.0.21, checkout /home/br/officerdev/platform, deployed by
hand and verified — 7/7 processes online, username NOT NULL, uq_users_username_lower present, HEAD at
bd41dff5.
Its login is `br` and always will be. That makes the SSH user a per-host fact rather than a constant,
so the table carries it and the deploy prompt reads it. Worth stating plainly because the failure is
misleading: an orchestrator assuming `pastilhas` gets "Permission denied (publickey)", which reads as a
broken key rather than a wrong username.
Also folded in what tonight established. Three hosts answer to names that disagree with
`tailscale status` — edge-bridge and gitea-bridge are the old ones — so the table says which to use.
`edge-bridge` was listed as "not SSH-reachable" and that was wrong: its SSH was down at the moment I
checked, not absent. The pm2/nvm PATH trap is written in, including that `-lc` is not enough and cost
two wrong conclusions, and that macbookpro must not be helped with an exported PATH because doing so
breaks pm2. And a dirty tree means TRACKED changes; plain --porcelain skipped a host over a stray file.
officer.rezio.dev is recorded under "known wrong, waiting on someone else": it points at gateway rather
than deadpool, which is worse than unavailable — it will serve the wrong box the moment gateway answers
on 443.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
First release under yyyy.mm.dd.NN, and the first deploy of the plugin extractions, the regenerated
themes, Spotlight, and the chat fixes.
The plan is deploy/2026.08.21.01.md. Two steps in it are required rather than optional and both would
be easy to skip: bun install, because bun.lock changed and sharp left the platform's dependencies for
atelier's; and db:push, because users.username becomes NOT NULL with a case-insensitive unique index.
That second one can refuse — on a null username, or two names differing only in case. Checked on all
six hosts before writing this rather than discovering it mid-rollout: 12 users, zero nulls, zero
collisions.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Updating plugins was only possible through POST /api/plugins/update-all, which is authenticated — so a
deploy had to mint an API key to update the machine it was already logged into. A credential created,
used and hopefully deleted, on every host, for a local operation.
Same work through the same functions with the HTTP layer removed, not a second implementation beside
it. 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), one plugin's failure does
not stop the rest, and it exits non-zero if any failed so a deploy can stop rather than report a
success it did not have. Verified: 3/3 in 18s.
Its header says the one thing that is not obvious — it runs OUTSIDE the server process, so files,
schema, assets and the SPA bundle are current when it finishes but the route table is not, until
something restarts officer. A deploy restarts anyway, which is exactly why that would otherwise be
found out rather than known.
The prompt had a table of six hosts under a line saying docs/servers.md is authoritative. Both cannot
be true, and the copy is the one people trust while it rots. Removed, with the reason written in its
place so it does not come back.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The agent watches for a commit whose subject BEGINS with the code word, rolls it out to the six
platforms in docs/servers.md, and reports back. It never decides what a deploy needs — the plan is
written for it in deploy/<version>.md, and an agent improvising a db:push is how a database gets a
schema nobody was ready for.
Four traps written in rather than left to be rediscovered, all verified tonight: take the checkout path
from PM2's pm_cwd because alpha has a stale second checkout that pulls successfully and changes
nothing; reach pm2 with `$SHELL -ic` because it lives under nvm in .zshrc and a login shell does not
read that, which is how I concluded twice that a machine had no pm2 while it was plainly running;
remotes differ per host so pull in place rather than assuming a URL; and macbookpro is a laptop that
may be asleep, which is a skip and not a failure.
Idempotence is the report's own existence — deploy/<version>.report.md on origin means deployed. A
watcher that restarts must not roll the same release out twice, and nothing else was standing between
it and doing so. The report's subject deliberately omits the code word, or a report would trigger a
deploy and loop.
Two gaps stated rather than papered over: there is no CLI for updating plugins, only an authenticated
route, so the plan has to say how or the report has to say it was skipped; and nothing wakes the agent
yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
files-app becomes url-state: the file browser is where the work happened, but where
selection lives and who clears a query string are framework questions. The panel
framework's version of the same question moves in beside them, extracted from the
deep-read item, which keeps it as one of its three questions.
Item ids changed with the theme. Done now deliberately — no board reads them yet, and
this is the last cheap moment to move one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Second half of the AskUserQuestion report: "when I answer, the agent does not react — I see the bubble
for a long time and end up sending a message anyway", intermittently and not reproducible.
Two different causes, both invisible from the outside.
A DROPPED answer was silent at every step. user-instance discarded the boolean, sendFire does nothing
when no sidecar is connected, and the lookup returns undefined for both "no such session" and "not
yours". So a lost answer and a slow agent looked identical: a card that does not change. It now warns
with the reason, and where a session exists it emits an error into the durable log — the same channel a
successful answer uses, so a second pane sees it too, rather than confirming to the browser that
clicked.
A LANDED answer had the opposite problem. The card goes read-only the moment you pick, but `sent` is
local and optimistic while `message.output` only arrives once the harness has produced something. In
between there is a real gap, and nothing filled it — so an answered card looked exactly like one that
had timed out. It now says "Answer sent — waiting for the agent", which makes the two states different
without pretending to know when the agent will speak.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reported as: leave an AskUserQuestion unanswered for a while and the chat becomes unusable — refresh,
send another message, the agent is stuck.
armStall knew about compaction and about background tasks but not about a pending gate. Parking on a
question or a plan means emitting nothing until somebody answers; that is what parking IS. So the
watchdog could not tell it from a wedged turn, and at 10 minutes against gates that wait 20, it always
won:
10m the turn is declared dead, isGenerating goes false, an error is emitted, the session is torn down
20m the gate's own timeout would have resolved it truthfully — never reached
That left a ten-minute window to answer. Miss it and the card is still on screen with nothing behind
it, and clicking an answer does nothing at all: an answer's only receipt is the tool:result the gate
emits when it unblocks, and the gate is gone. From the outside that is precisely "unusable, refresh,
send another message".
A session with an outstanding question or plan is now left alone by the watchdog. Not unbounded — each
gate holds its own 20-minute timer and resolves with a sentence written for the agent — and the timer
is re-armed on both resolve paths, the answer and the timeout, so a turn that genuinely wedges AFTER a
question is still caught. armStall skips itself while any gate remains, so answering one of two
questions keeps the reprieve.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The failure this prevents is specific — a sub-agent burns the end of a limit window and the session the
owner is actually sitting in dies mid-turn, because the credits went somewhere nobody was watching. So
it is a condition on spawning rather than a refinement: an endpoint that can start unattended work
without checking is wrong from its first call, and the symptom lands on someone else's conversation.
Wired into POST /command-hq/commanders/new, which — this is the finding — already IS the spawn
mechanism the sub-agents item was asking for. It starts a turn with ws: null, waits only for
session:claude, and returns the transcript id, with command_hq_sessions naming, listing and costing it.
So "commander or something lighter" answers itself: a commander costs nothing extra and a lighter thing
would need its own registry to be visible at all. What is still missing is only the agent-callable
surface.
Refuses rather than queues or downgrades. Queueing means holding work against a window Officer does not
control, and the reset it would wait for is a claim about a shared pool — every claude on the machine
spends these, including terminals and pipelines. A refusal naming the window, the percentage and the
reset is something a caller can act on now.
The floor is 15% and the reasoning is in the file: the interactive failure is not "cannot start a chat",
it is "a turn already in flight is cut off", and a turn costs a fraction of a window.
Fails OPEN, deliberately. The numbers come from an external endpoint with a credential Officer does not
own, so a blip or a signed-out CLI must not stop every spawn on the machine with an error about usage
that has nothing to do with usage. The problem is reported so a caller can say "started, but unchecked".
Seven tests on the pure rule — tightest window decides rather than the average, no limits allowed rather
than blocked, exactly-at-the-ceiling refuses. Verified against the live account, where it correctly
refuses right now at Session 90%.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
TODO.md had reached 1050 lines and 72 open items across 28 sections, read mostly
on a phone. It is now a directory: todo/<theme>/<item>.md, one card per file, with
frontmatter carrying id, status, created date and order, and the prose body copied
across verbatim. TODO.md becomes a generated index (bun run todo:index).
Dates: where an item's prose stated one it is used; otherwise its old section's;
otherwise 2026-08-20, floored at the day before the split rather than invented.
date_source records which.
Shaped for a two-way Kanban board, filed as todo/tooling — a card is a file, id is
the identity, frontmatter is the machine's half and the body is the owner's.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Maintenance had "rebuild the frontend" and "restart the server" — one compiles what is on disk, the
other reloads it, and neither CHANGES what is on disk. Doing that meant ssh, on every server, every
time.
Refuses a dirty tree and a non-fast-forward, the same two refusals as pullPlugin and for the same
reason: this checkout is somebody's working copy on at least one machine, and a button that discards
uncommitted work is worse than no button. Fetches `origin HEAD` rather than a branch name, because a
checkout made before the default branch was renamed is on one the remote no longer has — the trap
plugins/update.ts already hit, and it bites hardest on the installs most in need of updating.
It deliberately does not chain into anything. A pull touching bun.lock means an install, which the
frozen-lockfile rule exists to keep deliberate; one touching a schema means db:push against a live
database. So it REPORTS what the update implies — install, db:push, restart or rebuild — from the file
list, and leaves the decision with whoever pressed it. The commits pulled are shown, because "it
worked" is less useful than knowing what arrived.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The eleven ported themes declared 34 of an 84-token contract. 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
previously applied theme had left behind. They also carried thirteen tokens nothing in this codebase
reads (--chart-1..5, --sidebar-*), which is the tell: they came from a shadcn template, not from the
contract in the README beside them.
So "highlights mask the content" and "text fades into the background" were not taste. They were
absence, and no amount of re-picking colours would have fixed them.
Generated now, from Omarchy 4's colors.toml, which is genuinely semantic — three background depths,
four foreground weights, accent, selection, muted, mode — and consistent: all 24 keys present in all 22
themes, checked. One mapping in scripts/themes/map.ts means one place to be wrong, one place to fix,
and an Omarchy update becomes a re-run.
Every foreground is driven through ensureContrast against the surface it actually sits on, and the
generator then re-checks sixteen pairs per theme and EXITS NONZERO on a failure. It found four real
bugs in my own mapping, which is the argument for having written it first:
- `on(fill)` picked the better of two palette extremes without checking either passed; rose-pine's
tones are all mid and came out between 2.2:1 and 4.2:1
- ensureContrast chose black or white by a luminance>0.5 test rather than by measuring. rose-pine's
rose sits at 0.25, so it drove toward white and capped at 3.5:1 where black reaches 6:1 easily
- --muted-foreground was derived against the raised surface but renders on the high one; everforest
landed at 4.44:1 and miasma at 4.00 — near-misses that look fine in a screenshot
- borders were held to 3:1, which would ring every panel in a hard line. A panel edge is decoration;
what must be discernible is a form field's boundary, so --input is checked and --border is not
35 failures at first run, 0 now.
The registry and the stylesheet imports are written from the same list, because the old port maintained
them by hand and drifted — catppuccin-mocha sat in THEMES after its stylesheet was gone. That file is
now deleted; Omarchy renamed it to catppuccin.
Eleven new themes arrive with this: ethereal, flexoki-light, hackerman, last-horizon, lumon, lupine,
miasma, retro-82, solitude, vantablack, white. Duck and Plain are Officer's own and are never generated.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ctrl-space focuses the address bar in Brave, so it never reached the app.
shift-space is a real 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 is worth stating rather than discovering: 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.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The dock is full and cannot grow. Once navigation lives here it is free to be a short list of what you
actually use rather than a complete one — which is the other half of this and is not done yet.
It INDEXES THE DOCK rather than keeping a list of its own. The dock is already the composed,
permission-filtered answer to "what can this account open here": the shell's screens, plus whatever
installed plugins contribute, minus anything canVisit refuses. A second list would be a second answer
to one question, and it would be wrong the day somebody installs a plugin. So a new plugin appears in
Spotlight for the reason it appears in the dock — because it is installed — and nothing here is edited.
Settings sections are added, because they are what people hunt for and the dock deliberately does not
carry them. Those ARE hand-listed, which is a real cost written down in the file: a section added to
IntegrationsSettings will not appear until someone adds it here. The alternative couples five settings
screens to the shell to save five lines.
Matching is subsequence, not substring, and lives in its own file so it can be tested with strings:
"chq" finds Command HQ, "apik" finds API keys, "fi" gives Files rather than Profile. The weights encode
what "the right result" means — exact label, then prefix, then word boundaries, then adjacency, with
shortness breaking ties so "Chat" beats "Chat history". Labels are worth about three times hints, and
paths almost nothing, so a path fragment finds an item without ever outranking a real label. Nine tests
cover the ORDER rather than the matching, because returning the right set is easy and returning it with
the right thing first is the product.
ctrl-space, not alt-space: the more macOS-shaped chord is already load-bearing for the owner. Not
cmd-k either — that belongs to the browser on some platforms and to text fields on others.
Mounted beside the header and the dock rather than inside the content region, so it still gets you off
a screen that is maximised, erroring or mid-navigation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Added: a Spotlight-style launcher on ctrl-space with the dock pruned behind it, plus dock effects and
auto-hide; a repeating-prompt option on the background-job starter, which is the Nudger in the place
it belongs — attached to a job already running rather than a schedule pointing at a session that may
not exist, and inheriting its three refusals; and a deep read of the Workspace/Panels framework, low
priority and explicitly not pain-driven, with the existing panel items folded into it because they are
symptoms of the same unexamined design.
Closed after checking rather than assuming — five of the seven were already done and the entries
outlived the work. The whole offscale rename debt is finished: panels read "Offscale", the picker
heading is right, console session keys were renamed on 2026-08-16, and there are zero stale
/headscale paths or PLUGIN.md self-references. The one remaining mention is a form placeholder,
https://headscale.example.com, which is correct — that IS a Headscale URL. offscale declares ssh as an
osDependency. The manifest module-cache is fixed by importFresh.
example/manifest.ts named web/Router.tsx as the frontend convention; discovery wants panels.ts and
layout.ts, by those exact names, or it refuses the plugin.
One that was NOT already done, and I nearly closed it by mistake: reindex-music.ts moved into the
music plugin but still read process.env.DATA_PATH, which stopped existing on 2026-08-13. Run from the
repo it looked in platform/data/music/.server — one level too deep — and reported the sidecar as not
running. It now imports DATA_PATH from the platform, which resolves to /home/pastilhas/officer-dev/data.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The good news survives checking. An APNs auth key belongs to the developer account, not a machine, and
a device token belongs to the app, not a server — so N installs holding the same .p8 all push to one
phone with no coordination, and the app posting its token per server is something the multi-server
manager does anyway.
One field is missing: the payload carries no origin. That breaks the deep link (a session id is
meaningful only on the server that issued it), and threading, and — least obviously and most
expensively — `mv`. That is a content hash of THAT server's catalogue, and the client's rule is
`mv !== version → resync`. One stored catalogue and five servers means every push from B invalidates
what was synced from A, forever. It would present as a battery and data problem rather than a bug.
Where the identifier comes from is deliberately left to the sign-on design: the multi-server manager
already needs a key per server, and notifications should adopt it rather than invent a second identity
that drifts the first time a host is renamed.
Records what stays per server on purpose — devices, per-chat mute preferences, the catalogue itself —
because the app is what joins them, which is the same shape as the sign-on work.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
They are global — affordanceBlock() reads every file and is called with no user context, so every
account gets every one in every conversation.
Fine while they are uncontroversial, and not fine straight after. "Wait for the question" was written
today to one owner's taste, is probably what most people want, and nobody asked anyone. An affordance
nobody can see and nobody can decline is a preference imposed as a fact.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Capture every route of a JWT-authenticated dashboard each night, diff against a promoted baseline, and
have an agent look only at what changed.
The blocker is auth, and it fails silently. iris seeds a capture with Cookies, Cookies-wal, Login Data
and Local State — a JWT lives in localStorage, which Chrome keeps in Default/Local Storage/leveldb and
iris does not copy. So an authenticated capture renders the login screen: a real screenshot of a real
page that is the wrong page.
Three ways out, with a recommendation. Copying leveldb works and drags every site's localStorage into
a temp profile. A token in the URL needs no profile at all and removes the desktop plugin from the
plan entirely — that is the one to try first. Seeding through the relay works and needs a browser
paired at 3am, which is the constraint iris exists to avoid.
The rest is deliberate about where the model is spent: pixel diff first, mask what is known to move
rather than raising the threshold, and only changed pairs reach an agent — with "if you cannot tell,
say so" in the prompt, because a confident wrong verdict on night four is how this stops being trusted.
Baselines are promoted by a person, never by a run succeeding, or a regression becomes the baseline on
night two.
Also records what Officer lacks: the queue has retries and no schedules, so this is cron.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
extension.zip says nothing once it is in a Downloads folder — not what it is, not which server it came
from, and not which of two it is. The name comes from the extension's own manifest.json, which already
carries what a browser will show: "Officer Browser Relay" becomes officer-browser-relay.zip.
Generic, since extensions are meant to be a marketplace of them: any plugin shipping extension/ gets a
file named after its own manifest, falling back to <appName>-extension.zip when that cannot be read —
still better than extension.zip, and it never throws, because a broken extension manifest should fail
the install for its own reason rather than because a file could not be named.
Uninstall removes both names. An install from earlier today published extension.zip, and leaving that
behind would serve a stale extension for a plugin that is gone.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The browser relay is the first extension, not the last, so `extension/` is now a directory any plugin
may ship — like `assets/` — and the installer zips it to public/plugins/<name>/extension.zip, served
by the existing /plugins/* wildcard with no auth.
Unauthenticated deliberately. An `<a download>` is a plain navigation with no Bearer header, so an
authenticated URL makes Chrome say "Try to sign in to the site. Then, download again" — advice that
cannot work, because signing in is not what is missing. Nothing in an extension is secret; the pairing
token is, it is entered afterwards, and it is not in the archive.
Built at install rather than committed. The file it replaces was hand-built and had drifted 58 lines
behind its source, serving an extension missing the multi-session recovery path.
zip.ts writes stored entries with fixed timestamps — no host `zip` binary, and identical bytes for an
unchanged directory.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The last two pieces the extraction missed. IntegrationsSettings/BrowserRelay.tsx drove the plugin's
pairing from a platform screen, calling /browser/relay-token and working only because the plugin
happens to serve that path — the same coupling removed everywhere else this morning.
public/browser-relay-extension.zip was a hand-built snapshot that had drifted 58 lines behind the
extension it claimed to be: built in August from something predating a February commit, never rebuilt,
and missing the multi-session recovery path. The plugin builds the archive from its own directory per
request now, so there is nothing left to fall behind.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
plugins/browser now owns the extension, the relay, the CDP bridge, the pairing routes and the two
panels. All of it was on disk and switched off since 2026-08-13 — nothing was recovered from history,
and nothing regressed, because none of it had been running.
What the platform keeps is /scrape, and the two were never one feature split in half. Scrape launches
a headless chromium through playwright as the OWNER and knows nobody; the plugin attaches to the
browser a person is already signed into, scoped per pairing. The permission is renamed "Scraping" so
the registry stops describing one thing in the other's words, and it drops the /browser frontend route
it could no longer serve.
Two dead screens went with it. BrowserScreen and DesktopScreen were officer-web screens rendering
panels through appType placeholders — a plugin supplies its own route and panels through
Plugins.gen.tsx, so both were redundant the moment their plugins existed. DesktopScreen was a leftover
from this morning's extraction that typechecked cleanly while rendering a panel the AppRegistry no
longer had: dead at runtime, invisible to the compiler.
The long comment in server.tsx explaining BROWSER_RELAY_PORT goes too, replaced by a pointer to where
it lives now. It was written for whoever did this extraction, and this is that.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Websockets: a plugin's socket has no door at all — mount.ts never sets `ws` and server.tsx's handler
map is a literal. Desktop ships one that cannot be mounted and will not be the last plugin to want one.
Host setup: a manifest declares packages, not a reconfigured display manager. Left manual for desktop.
Noted that a mechanism for this apparently existed months ago and was removed — history first, design
second.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The catalogue row and the bundled offline fallback, so the plugin installs from the marketplace like
every other. Listed honestly: its permission is owner-only at every path, and its websocket is not
mounted yet — the README and BLOCKERS.md say so rather than letting an install discover it.
marketplace-sync globs plugins/ itself rather than going through discoverPlugins, so the node_modules
skip added there did not cover it. Same fix, second place: it was reporting 15/16 and 16/17.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Desktop is a plugin as of today, and this is the half that leaves. sidecar/vnc/, api/desktop/ and
apps/Desktop/ are gone from src/, along with the vocabulary that was the real problem.
sidecar/protocol.ts had a VNC section: vnc:start, vnc:ensure-password, vnc:stop, four reply variants
and two types. sidecar-registry.ts had startVnc, ensureVncPassword, stopVnc, isVncConnected. Four
functions and a dozen message types in the platform, describing a feature that is not the platform's —
the rule CLAUDE.md states most plainly, and its clearest breach.
What replaced them is generic. sendSidecarCommand(kind, cmd) and isSidecarConnected(kind) know that a
command has a type and an id and that a reply carries the same id. A plugin's sidecar speaks whatever
it likes through them and nothing here has to be edited when it adds a message.
The desktop PERMISSION leaves too, and that is the interesting part: it was kind: 'execution', a kind
a plugin permission cannot have and never will, because a permission nobody can delegate is a
contradiction. The plugin expresses the same refusal as ownerOnly: ['/'] — every path under it denied
to anyone but the owner. Verified: /api/desktop, /api/desktop/vnc-password and a path that does not
exist all resolve owner-only. registry.test.ts records the round trip rather than just dropping the
key from its list.
Also gone: the app store's `vnc` entry, which would have offered an older second way to install the
same thing against a process PM2 no longer has, and four commented-out mounts left from 2026-08-13.
The disconnect-scope test used startVnc as its stand-in for "another sidecar's long-running request".
It now uses the generic door, which is the better instrument — that file is about the blast radius of
a disconnect and never had anything to do with VNC.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The shared install target for plugin npm packages lives in plugins/ because bun resolves node_modules
up the tree. Discovery then found it, failed to read a manifest, and reported it as broken on every
call — a warning nobody can act on, and a denominator that made the marketplace sync report 15/16.
Mine, from the npm-dependencies work.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The probe asked the owner's login shell where a binary was, and the install reported that as a fact
about the machine. For a confined plugin the work happens as the member's own Linux user, in their own
home, where the owner's ~/.local/bin is neither on PATH nor reliably reachable.
On alpha it worked — because /home/pastilhas happens to be mode 751, world-traversable, so an
absolute path resolved. At 750, the more usual default, every member would have lost every binary with
nothing reporting it: the install would still have said satisfied, having only ever asked the owner.
Nobody chose 751, and that is the part worth fixing.
`scope: 'owner' | 'shared'` on an osDependency, defaulting to owner, an unrecognised value being a
manifest error rather than a silent fall back to the permissive one.
Shared changes three things. It is searched for on system directories only — asking the owner's shell
would find the copy in the owner's home and call it satisfied, the exact false pass this exists to
stop. Reachability is checked as world-executable AND every parent traversable to the root, because a
binary at 755 inside a home at 700 is unreachable and stat on the file alone says it is fine. And a
release binary goes to /usr/local/bin through sudo -n install, staged in the owner's space first so
the download itself never runs as root.
An unreachable shared dependency gets its own state and refuses the install ahead of every other
check, because no package manager fixes it: the binary is installed and works, and what is wrong is
where it lives — reinstalling would report success and change nothing.
Not a security boundary, and docs/plugin-dependency-scope.md says so: anything in /usr/local/bin is
runnable by any account with a shell, grant or no grant. That is already true of ffmpeg. The plugin's
data is gated; its executable is not.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`Bun.which` reads the PATH this process started with, and under PM2 that is minimal — a release binary
fetched during an install was reported missing seconds later by the same install. The fix was
prepending ~/.local/bin here.
That is guessing at somebody's environment from inside a crippled one, and guessing does not converge.
rustup puts cargo in ~/.cargo/bin, nvm puts node elsewhere, and every per-user installer adds a
directory nobody listed. The iris plugin duly wrote its own copy of the function with ~/.cargo/bin
bolted on, which then disagreed with this one: the manifest probe refused a rustup-only machine that
the sidecar could build on perfectly well.
There is nothing to guess. The platform runs as the owner, plugins are installed by the owner, and the
owner has a shell whose rc files already put all of it on PATH — that is what those files are for. So
ask it: `$SHELL -lc 'command -v <binary>'`, with the shell taken from passwd rather than
process.env.SHELL, which under PM2 is whatever started the daemon. sessions.mjs already draws that
distinction for terminals; this is the same fact applied to dependency probing.
A login shell because ~/.cargo/env and friends are sourced from profile files an interactive-only
shell may skip. `command -v` because it is a POSIX builtin whatever the shell is. Two-second timeout
so an rc file that waits for input cannot hang an install. Bun.which stays as the fallback, with
~/.local/bin prepended there and only there, for an account with no usable shell.
Exported as locateBinary so a plugin's sidecar asks the same question the install did, rather than
writing a second answer.
Verified on this machine: the login shell resolves ~/.local/bin and ~/.opencode/bin, neither of which
is on this process's PATH, and finds a binary Bun.which cannot see.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Five revoked keys, no live ones, and no way to remove any of them — which is what the screen looks
like after a few rounds of testing. `listApiKeys` returns every row and nothing filtered them, so a
list whose job is "which of my keys still work" answered with a wall of dead ones.
Nobody decided that. Revoke was implemented and the list was never taught the difference.
Dead keys — revoked or past expiry — are now hidden behind a "Show 5 revoked or expired keys"
toggle rather than merely dimmed, because on any account in use for a while they outnumber the live
ones. The empty state distinguishes "No keys yet" from "No keys in use": the first is false on an
account whose keys are all revoked, and it is exactly the sentence that sends somebody hunting for a
bug in the list.
DELETE /:id/record removes the row for good, and only after it is revoked. The `revokedAt is not
null` clause is in the statement rather than checked before it, so there is no ordering in which a
live key is deleted by a request that raced a revoke. Nothing is weakened by allowing it: the key
cannot be honoured again either way, since authentication matches a hash and a deleted row has none.
What goes is the history — `lastUsedAt`, the only evidence of whether a leaked key was used before it
was killed — which is why it stays a second, deliberate step rather than what revoke does.
Also corrected the copy, which claimed keys are per-app. They are not scoped to anything: one key
works everywhere, and per-device is a revocation convenience, not a requirement. The owner had to ask.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reported by the owner, who went looking for them in user management and then in profile, and found
them in neither. They were under Integrations.
A key is not an integration with anything. It is a second way to present the authority the account
already has, and the permission registry already says exactly that: `/api-keys` is `core`, sitting
beside `/user` and `/dock`, with the comment "a key is not new authority". Profile, next to the
password it stands in for, is where somebody looks.
Moved rather than duplicated, and the route moves with it — /settings/profile/api-keys. Nothing
linked to the old path, so there is no redirect to keep.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A plugin worth granting to a Member can also hold the credential the rest of it runs on. Jellyfin's
/_config stores a server's admin token and drives account provisioning; the rest of the plugin is
exactly what a Member should have. The choice was all of it or none of it.
`ownerOnly` on a plugin permission takes sub-paths relative to the mount prefix. The permission stays
fully grantable — this is not the ownerOnly PERMISSION that manifest.ts refuses, and that refusal
still stands: a permission nobody can delegate is a contradiction. This says a few paths administer
the plugin rather than use it.
Declared by the plugin, enforced by the platform. A plugin could check this itself and the first one
would; the tenth would add a route and forget, with no boot failure and no warning — the shape
assertPermissionTotality exists to prevent. In the gate it is enforced once, on the door they all
pass through, and a route added later by someone who never read the manifest is covered by default.
Checked before selfService and before kind. A path that is somehow both self-service and owner-only
is a contradiction, and the safe reading has to win. A write grant does not unlock it either — level
is not the question this answers.
Also forwards X-Officer-Owner and X-Officer-Level to a sidecar whose proxy names its permission key,
for the finer decisions the platform cannot make for it: whose rows a read returns, which fields a
level may see. Facts, never the role name — a plugin branching on "Super Admin" would give every
plugin repository an opinion about the platform's role vocabulary, and renaming a role would change
authorization in code the platform does not own. These are safe to trust only because the proxy
copies a three-item allowlist off the inbound request; that is now written where it would be changed.
The owner's level is reported as write rather than the absent 'none': they hold everything implicitly
and appear in no grants map, so the raw lookup inverts the meaning for the one account that can do
anything.
No plugin declares one yet. Jellyfin cannot until connections stop being per-user — locking /_config
today leaves a Member with a plugin that only shows a connect form they may not submit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A plugin's settings routes should be owner-only while the plugin itself stays grantable — jellyfin's
/_config holds a server's admin token and drives provisioning, and a Member granted the plugin can
reach it today.
Agreed: the platform says who is asking, the plugin decides what that means inside its own surface.
That is not new — manifest.ts already refuses an ownerOnly permission on the grounds that finer
visibility is the plugin's business.
Two refinements recorded rather than assumed. Pass isOwner and the effective level, never the role
name: roles are the platform's vocabulary and a plugin branching on "Super Admin" gives every plugin
repository an opinion about it, so renaming a role would change authorization in code the platform
does not own. And nothing may be trusted from the caller — the proxy's three-item header allowlist is
what makes X-Officer-User safe, and a new header inherits that only while it stays an allowlist.
One disagreement, recorded as a proposal rather than settled: pure plugin-side enforcement is the
shape assertPermissionTotality exists to prevent. Jellyfin will check because we are about to write
the check; the next plugin's author forgets a route and nothing notices. So: declare owner-only path
prefixes in the manifest, enforce them in the proxy, and pass the facts to the sidecar as well.
The real prerequisite is not the guard. Connections are per-user, so locking /_config leaves a Member
with a plugin that can only show them a connect form they are forbidden to submit. The fix that fits
what exists is the owner's server URL with the member's own token from jellyfin_accounts — which is
arguably why provisioning mints those tokens.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Delete jellyfin, install it again at a newer commit, connect a server — and no accounts were created,
no mapping rows written, and no error anywhere. Every step reported success.
The new checkout writes manifest.ts at exactly the path the old one occupied, and `await import(path)`
returns the module it already has: ESM caches by resolved specifier, and the specifier did not change.
So the platform kept obeying the manifest of a plugin that was no longer on disk. That manifest
predates `userProvisioning`, so the plugin was judged not entitled to the account list, the sidecar
was sent nothing, and provisioning skipped with "the platform has not sent the account list yet" —
a report that goes into the response body nobody reads.
It began working four minutes later for a reason that had nothing to do with the plugin: officer was
restarted for an unrelated deploy, which emptied the module registry.
`importFresh` keys the import on the file's mtime, so a file that changed is evaluated again and one
that did not is still a cache hit — `discoverPlugins` runs on every sidecar registration, every mount
and every plugins page load, so a Date.now() key would leak a module instance each time.
Used for the manifest, the api router and the db schema. For manifests it is complete: every manifest
imports one thing, `import type { PluginManifest }`, which is erased before it runs, so they are leaf
modules. For the other two it narrows the window rather than closing it — only the named file is
re-read, and its own static imports come back from the cache. A restart is still the only thing that
guarantees a plugin's whole module graph is the one on disk, and that is written down in the file
rather than left to be rediscovered.
The test pins the failure and not the mechanism: one case proves a plain import keeps serving a
manifest that is no longer on disk, the next proves importFresh sees the replacement, and a third
proves an unchanged file is evaluated once. mtimes are set explicitly, because two writes inside one
millisecond would otherwise decide the result.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A disabled plugin keeps its directory, and the directory is what the next start runs. The longer it
stays off the more certainly it is stale, and enabling would quietly run whatever was current on the
day it was switched off — with every step reporting success, which is exactly how the jellyfin
install on alpha re-applied a two-day-old checkout.
Deleting no longer has that problem, since it takes the directory with it and installing is always a
fresh clone. That left disable/enable as the one remaining way to run old code without being told.
The pull is best-effort and the enable is not. `updatePlugin` returns ok:false when a pull is
refused, and it is refused for reasons that say nothing about whether the plugin can run: a dirty
working tree — every plugin directory on this machine is one — an unreachable forge, or a directory
copied in rather than cloned. Enable is the reversible half of a pair with disable, and a switch that
will not turn back on because a network is down is worse than one running last week's code. So the
refresh reports which of those happened and the enable proceeds regardless; a re-apply that fails
falls back to the code already on disk, which was running before it was disabled.
Tested by the refusal path rather than the happy one: a directory that is not a checkout comes back
having reported "not refreshed", and the error that surfaces is about not being installed rather than
about git — which is only possible if the refusal was stepped past instead of returned.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three states all read as "stopped": disabled, uninstalled, and uninstalled-with-the-directory-still-
there. Nothing on screen distinguished them, and the one that mattered was invisible — an uninstalled
plugin kept its directory, which silently decided what the next install would run. That is how a
jellyfin install on alpha re-applied a checkout from two days earlier while reporting success at
every step.
So uninstall stops being a verb. What it did survives as the first half of deleting: it stops the
sidecar, removes the install row and the PM2 entry, unpublishes the copies, and revokes grants naming
permissions that are about to stop existing.
Delete is offered only on a plugin that is not running — disable is one reversible click, so a live
plugin is always two deliberate steps from gone. It opens a confirmation carrying a checkbox, "also
delete all its data", unticked and never inherited from last time. Unticked, the directory goes and
the rows stay, and they appear in the orphan list further down the same screen. Ticked, the tables go
with it, which is the only way to a machine that has never had the plugin.
The checkbox picks between two ROUTES, not a body flag on one: a flag can be added to a request by
anything that already knows how to call the safe verb, and the difference here is somebody's rows.
Grants are revoked either way, which is load-bearing until the permissions work tomorrow: a grant
naming a key the platform no longer recognises made the whole permissions screen unsaveable, because
the page submits every grant it loaded.
Also corrected two rationales that the change made false — the runbook's "uninstall never destroys
data" verification table, and npm-deps.ts explaining directory survival in terms of uninstall.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Uninstalling a plugin left it under a heading that said "Installed", with a caption saying "not
installed". It never moved, so a successful uninstall read as a failed one — and nothing on screen
said the directory was still sitting there deciding what a reinstall would run.
That mattered more than the wording. Install skips the clone when the directory exists (install.ts
findPlugin, fetch.ts refusing an existing dir) and never pulls, so reinstalling jellyfin on alpha
silently re-applied a checkout from two days earlier. The provisioning code was not on the machine,
jellyfin_accounts was never created, and connecting a server did nothing at all — with no error
anywhere, because every step it did run succeeded.
Two changes, both UI:
- The heading is "On this machine", which is what the list is: every plugin DIRECTORY, installed or
not. Delete is what moves a plugin back to the marketplace, and now the screen shows why.
- Delete is gated on being uninstalled and is a button rather than a small underlined link. It was
previously offered in every state, so two clicks separated a running plugin from its tables being
dropped. Uninstall, then delete — the order the buttons now teach.
Still true and not addressed here: uninstall followed by install reuses the existing directory as it
stands. The detail pane says so now; making install fast-forward a clean checkout is a separate call.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
two platform fixes that make a plugin's job smaller, both from the owner:
downstream services identify a person by name, so the platform has to be the
one holding that name to a single meaning.
`getUserByUsername` compared with `eq`, so `diogo` and `DIOGO` were two
accounts. create-user.ts asks "is this taken?" through that function, which
means the check could not see its own collision. it compares on `lower()` now.
and the constraint is on `lower(username)`, not the column — a plain unique
index is what allowed both to exist. it sits in the schema rather than only in
create-user.ts so a second code path, a migration, or someone at a psql prompt
cannot get around it.
the column is NOT NULL. `validateUsername` has always demanded one, but the
column allowed null, so anything skipping validation could write a user nobody
could name — and a Linux account or a Jellyfin login then has nothing to work
with.
both databases were checked before the change: zero null usernames, zero
case-collisions on either, so no migration was needed.
proved rather than assumed, inside a transaction that was rolled back on the
live database: `PROBEUSER` refused against `probeuser` by
uq_users_username_lower, and a null username refused by the not-null. no rows
written.
this also removes a case the jellyfin reconcile had to carry: an officer
account with no username could not be matched or created there, because
jellyfin authenticates by name and has no email login.
pastilhasandClaude Opus 5