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.
a plugin that creates accounts in an upstream service — jellyfin first, immich
next — needs to know who the platform's users are. it now gets told.
DECLARED IN THE MANIFEST, not asserted at registration. `name` and `handles`
arrive on an unauthenticated socket and are believed, so a capability claimed
there would be a plugin granting itself one. the manifest was reviewed when the
owner installed it, and sits beside `permissions` where "this plugin will be
told who your users are" belongs — on the install screen, not discovered later.
PUSHED, not requested. a sidecar has no authenticated way to ask, so a request
could only be answered, never authorised. a push inverts that: the platform
decides who gets it, and a caller registering under a name with no such
manifest gets nothing.
`listProvisionableUsers` is a hand-written projection — id, email, username,
name, role — and NOT `select *`. `users` holds `password` and `os_user`, and
`getUsers()` returns both, so a plugin reaching for the obvious function would
get every account's password hash. naming the columns means adding a secret to
the table cannot silently add it to what plugins receive. pinned by a test that
asserts the key set, not just the absence of today's secrets.
the owner is excluded. they bypass every permission check and already have
whatever upstream account they want; provisioning them is at best a no-op and
at worst a second admin nobody asked for.
sent after the ack rather than inside it, so registration never waits on a
database query — a slow postgres would otherwise stall every sidecar's startup,
and none of them need the list to start.
and re-sent on every account create and delete, because the registration copy
is a snapshot: a plugin still holding a deleted user would keep an upstream
login alive for someone the platform has removed. read once per broadcast, so
two plugins cannot be told different things about the same moment.
Contract for provisioning a user into a plugin's upstream service, with two
worked examples.
Four rules: never hardcode the admin credential; check-then-create (neither
API upserts); force a password change where the server supports it; verify by
actually logging in, since a 201 only means the row was written.
Immich (photos plugin) — verified end to end against a live 3.1.0 instance,
including every error body: duplicate email 400 "Email is not available",
missing field 400 validation, bad key 401. Includes a non-destructive probe
recipe to re-verify after an upgrade.
Jellyfin (jellyfin plugin) — route surface and auth model verified against
10.11.11; request bodies from working knowledge and marked as such. Differs
in shape: MediaBrowser token auth, multi-call create, no forced-password-change
flag, and accounts are per-instance (this deployment runs four independent
servers). Records the decision to set a generated password rather than create
blank-password accounts.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`pluginPackageJsonExists` was exported for an uninstall hook that was never
wired. an export with no caller is an unfinished thought pretending to be a
feature, so it is gone — and the behaviour it would have served is right
anyway: uninstall KEEPS the plugin directory, so its packages are still
declared and still wanted. only "delete and all its data" removes the
directory, after which the next install regenerates the merged file without it.
the packages linger until then and go on their own.
and the thing the owner asked to come back to: CLAUDE.md's frozen-lockfile rule
reads as universal, and npmDependencies does not follow it. ranges resolving
per machine is what lets two plugins share one sharp, and it was chosen
knowingly — but the codebase now holds two postures on one risk with only one
of them written down. recorded in TODO.md with the three specific things worth
settling rather than left as a feeling that something is inconsistent.
replaces the per-plugin package.json from earlier tonight. the owner's call,
and the reason is one i had not weighed: sharp is ~50 MB of platform binaries
and the obvious dependency for anything touching images, so a second and third
plugin wanting it would have meant a second and third copy with no version they
could converge on.
so every plugin's `npmDependencies` merge into ONE generated plugins/package.json,
installed into plugins/node_modules/. bun resolves node_modules up the tree, so
that directory serves every plugin and none of the platform's own code.
ranges intersect rather than alternate. two plugins asking for ^0.33.5 and
^0.33.9 produce "^0.33.5 ^0.33.9", which npm and bun read as AND — the resolved
version must satisfy both. `||` would have meant "either", which is the silent
version of this failure: one plugin quietly getting a version the other cannot
import. incompatible requirements now fail the install with bun's own message,
and both askers are named in the steps either way.
generated from the plugins ON DISK, like generatePluginSchemas, and never
edited — so a package cannot appear there without a plugin having declared it.
what this gives up, knowingly: a committed lockfile. ranges are the whole point
and a range resolves per machine, so plugin packages are resolved at install
time like osDependencies are, and unlike the platform's own. CLAUDE.md is
emphatic about frozen lockfiles and 2026-08-04, so it is named in the manifest
type rather than left to be discovered.
the generated plugins/package.json and lockfile are gitignored — /plugins/*/
only ignores directories, so files at that level needed naming explicitly.
update is a git pull and then the ordinary install path, so the npm step is
picked up for free — a plugin that adds a dependency in a later version gets it
installed on update, with no second implementation to drift.
but pullPlugin refuses on ANY uncommitted change, and node_modules/ that
nothing ignores is one. so a plugin shipping package.json without ignoring it
installs perfectly once and can then never be updated again: the button reports
"N uncommitted changes" forever, about a directory the platform itself created,
and nobody seeing that message has a reason to connect it to a package.json
from three versions ago.
every plugin that exists today ignores node_modules, which is luck rather than
a rule — this makes it a checked one.
asked with `git check-ignore` rather than by reading .gitignore: the rule may
be nested, global, or in .git/info/exclude, and all three count.
warned, not fixed. writing into the plugin's own .gitignore would be the
platform editing a repository it does not own, and would itself dirty the
checkout — which is the exact thing being avoided.
osDependencies covered binaries on PATH — ffmpeg, radicale, tea — and there
was nothing for a javascript package. so a plugin needing one had to add it to
the PLATFORM's package.json, which is what atelier did with sharp, carefully,
with the frozen-lockfile dance documented in BLOCKERS.md.
it still broke on the first machine that was not this one. alpha pulled the
package.json, nobody ran bun install, and officer-atelier crash-looped on
"Cannot find package 'sharp'" — after the install flow had reported success.
three things were wrong with that shape. the platform carried a dependency
only one plugin needs, and uninstalling the plugin would not have removed it.
installing a plugin could not install it, so "installed" and "can start" were
different facts with nothing checking the second. and it forced the platform's
lockfile open, which is precisely the signal frozenLockfile exists to keep rare.
now: a plugin ships its own package.json and lockfile, committed in its own
repository, and the install flow runs `bun install --frozen-lockfile` in the
plugin's directory. bun resolves node_modules up the tree, so
plugins/<name>/node_modules serves that plugin and nothing else, and uninstall
takes the packages with the directory.
the presence of the file is the declaration — no manifest field, same reason
sidecar/index.ts has none: a second place to say it is a second place to be wrong.
verified by RESOLVING, not by the exit code. sharp resolves to a
platform-specific binary package, so a lockfile that installs cleanly on one
machine can leave nothing importable on another — which is the exact failure
being fixed, and checking the exit code would have reproduced it one layer up.
sharp is off the platform's package.json. the lockfile diff is that removal
plus @img/sharp-libvips-* re-resolving 1.0.x → 1.2.4, because the platform no
longer pins sharp; nothing else moved, checked line by line. the platform still
reaches sharp transitively through next, which is where it came from.
`git mv` from src/ into plugins/ staged a rename, and a staged rename beats
.gitignore — so the platform repo committed a file belonging to a plugin that
owns its own repository. the file is unchanged on disk and is committed where
it belongs, in plugins/atelier.
worth knowing generally: moving a file OUT of a tracked directory into an
ignored one needs `git rm --cached` afterwards. the ignore rule does not undo
a rename that is already in the index.
`IntegrationsSettings/index.tsx` has carried the rule since email was extracted
on 2026-08-18: "A plugin contributes panels, not settings sections, so it now
lives inside the email workspace itself."
the atelier extraction brief said the opposite, and the brief was mine and
wrong. sonnet found the contradiction, recorded it in BLOCKERS.md under a
heading that says "against a direct precedent", and followed the instruction
anyway — which is what it was told to do. so the wrong call got implemented
carefully rather than caught.
settings in the platform mean the plugin is not self-contained: it cannot be
configured on an older platform, and uninstalling leaves a dead section in the
settings screen for someone to delete by hand. neither is true of a panel.
the section, its import and its now-unused icon are gone from here. the screen
is `plugins/atelier/web/Providers/` and a fourth panel.
the repo exists now — gitea.officer.dev/plugins/atelier, public, master, in the
plugins org like every other one — so the bundled catalogue can name it.
BUNDLED is the offline floor under marketplace.officer.dev, not a duplicate of
it: a machine that cannot reach the marketplace still sees the plugin. the sync
picks it up from gitea on its own, verified — 14 plugins, atelier among them.
`has` says all four, which is true of it: the proxy router, atelier_* tables in
officer_db, the generation sidecar, and three panels.
the key field was an Input and a Button side by side, outside a form, so Enter
did nothing. pasting a key and pressing enter is the strongest habit there is
in a password field, and when it silently does nothing it reads as "the key
did not save" — which is the one thing this screen must never be ambiguous
about.
TODO.md tracks nineteen panels with the same defect. this is not the twentieth.
everything else in the screen was already right and is left alone: type=password,
autoComplete=off, the server never returning a key, and the field starting
empty with a placeholder that says whether one is set.
Atelier is now plugins/atelier/: manifest, a thin auth-gated proxy router, the sidecar backend
(providers, the generation queue, collections, its own separate Postgres database), three panels
(Generate, Gallery+Lightbox, Collections), and Providers as an Officer settings screen instead of a
fourth panel. Its own local git repository, four commits, not yet pushed anywhere — see BLOCKERS.md.
bunx tsgo is clean. bun test: 1041->1069 pass, 0 fail, 90->92 files (the two new files are ported
tests, no regressions). The real production SPA bundle builds successfully with the plugin included
(Bun.build + Tailwind, 2.2s, zero errors) and the sidecar's HTTP API was exercised end to end against
a real, non-production Postgres database. Not done, and recorded as open: a live PM2 install cycle
against the shared production database, and publishing the plugin's repository to Gitea and the
marketplace — both cross into affecting shared systems beyond this local checkout, which is not a
call to make unattended.
The standalone officer-atelier service — what the mobile app actually talks to today — was not
touched, not stopped, and not migrated. This extraction is additive.
ATELIER-COMPLETE
decision 2 of the atelier extraction: providers (which adapter, which model, whose key) becomes an
Officer settings screen rather than a panel, since it is owner-level configuration in the same shape
as the Apify token beside it. Talks to /api/atelier/providers over HTTP through useClient() — no
import from plugins/atelier/ in either direction.
recorded in BLOCKERS.md: this goes against IntegrationsSettings' own comment from the email
extraction five days earlier ("a plugin contributes panels, not settings sections"). Followed the
pre-made decision anyway per the kickoff prompt's own instructions, and wrote down the
contradiction rather than picking one silently.
same stable-bump shape as useFilesRefresh. Generate and Gallery are independent sibling panels with
no props between them (per the panel contract, components only ever receive panelId), so a finished
job reaching the gallery needs a signal rather than the standalone app's onFinished callback prop.
no platform code references atelier and atelier references no platform code, so this extraction
has no reverse-dependency seam to design around. also records the database-separate decision
(collections and provider_settings both have rows on the live server) and adds sharp as a direct
dependency for the image-inspection code the sidecar needs — promoted from an existing transitive
resolution, no new package versions pulled in.
the first draft said follow gitea — sidecar serves its own ui, plugin proxies
it, one panel renders an iframe. wrong for this one. atelier was a separate
server because that was the quick answer at the time, and this extraction is
what undoes that: it becomes part of officer, not something officer frames.
and it is smaller than the repository suggests. 1,736 lines of react, but six
of the twenty-five files are shadcn components officer already has, and the
htmx half is eight files that get deleted rather than ported. what is left is
generate, gallery, collections and providers — about 1,200 lines.
providers is a settings screen, not a panel, so it moves to officer's settings
surface. src/servers/providers/ is already adapter-shaped, so the point of
moving it is that a SECOND provider becomes a new file rather than a new
screen. the brief says explicitly not to add one in this run — leave the seam,
say so in PLUGIN.md.
still a sidecar, for the one reason that survives the ui moving: 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.
added the trap that follows from all of this: "every image has a permanent
URL" was true of a standalone server with its own PUBLIC_URL, and inside
officer that url is behind the session. an <img> cannot carry a token — the
core affordance says why — so anything needing an unauthenticated image is a
blocker to record, not a route to open.
differs from EXTRACT-A-PLUGIN-PROMPT.md in the two ways that matter when
nobody is awake.
it does not say "ask and wait", because there is no one to ask. the five
decisions that would normally be questions are pre-made with reasoning, and it
says to follow a decision even after finding evidence against it — recording
the evidence instead. a half-applied decision is worse than a wrong one
applied consistently.
and it assumes the agent will be restarted mid-run, so it says commit after
every task: a clean tree and a commit message are how the next attempt, quite
possibly the same agent an hour later with no memory of it, knows where it is.
the substantive call is the UI. atelier ships htmx AND a react spa with its own
build, and porting 84 files into panels is not an overnight job. gitea already
solved this exact problem — sidecar serves its own ui, plugin proxies it
same-origin, one panel renders it in an iframe — so the prompt points there and
says to read sidecar/rewrite.ts first, which is where the traps are recorded.
the database decision is deliberately conditional rather than fixed: count the
rows first, fold two empty tables into officer_db, keep the separate database
if either has data. losing someone's generated images to a schema decision at
4am is not a trade worth making unattended.
it opens with a worktree, and says no second agent in this tree. today two
agents with bypassed permissions ended up in one checkout and nothing was lost
only because one of them noticed and stopped.
it fired once, in anger, and put a second claude with bypassed permissions
into 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. it also found a real bug while it was there, which is not a
defence of any of this.
the guard was exactly backwards. it asked one question — "is this session
generating" — and treated NO as permission. but a session the sidecar no
longer holds is also not generating, and `startClaudeTurn` given one of those
does not resume it, it starts a NEW one. so the check that was meant to
prevent interference is the thing that guaranteed a second agent, and the
likeliest state for an overnight target — garbage collected after 30 idle
minutes — is precisely the dangerous one.
three questions now, 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.
any other live session refuse, keep the schedule. two agents with bypassed
permissions in one tree is not something to arrange
on purpose.
the third is blunter than it needs to be — the sidecar does not report a
session's directory, so it refuses on ANY other live session rather than on a
comparison it cannot make. that will decline some safe nudges. given what the
precise version cost, the blunt one is the right trade until the sidecar can
say where a session is running.
`dueNudges` passed a JS Date as a parameter on the left of an interval
subtraction. postgres will not infer a type there and refused the whole
statement, so the tick threw once a minute and no nudge could ever fire.
the symptom was the worst kind: the row sat in the table enabled, sent_count
0, last_fired_at null — indistinguishable from a schedule that was armed and
simply had not come due yet. it was found by checking the row after arming it
rather than by trusting the log line that said "armed".
`now()` in sql instead, which also means the comparison uses the database's
clock rather than the platform's.
the test asserts only that the query EXECUTES. what broke was the sql being
invalid, and no amount of reasoning about interval arithmetic would have
caught that — only running it against a real postgres does.
an agent told to record blockers and continue still stops at the end of a
turn, and at 3am nobody types the next message. this is the schedule that does.
the door already existed. `startClaudeTurn` takes `ws: null` — extracted that
way so command-hq could drive a turn over http — so this is a second caller of
an existing path rather than a new way into a live session. i had said the
platform lacked that; it did not.
the rule that decides the design: never speak while the agent is working. 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 next tick, which
means it fires as soon as the turn ends rather than sleeping through to the
next hour. a strict alarm would skip an agent that finished four minutes late
and leave it idle for the other fifty-six.
`isGenerating` unknown counts as BUSY. a sidecar that cannot answer might be
mid-turn, and interrupting one is the failure this exists to avoid.
matched on both sessionKey and claudeSessionId: officer's handle and the
transcript's filename are different ids, only the agent holds the mapping, and
a schedule stored against one would silently never match a live row keyed by
the other.
one nudge per (user, session) — a second schedule for one conversation is two
alarms for one sleeper. counted even when the turn fails to start, so a
refusal cannot become a tight loop. disables itself at the ceiling rather than
leaving a spent row armed. the tick starts in server.tsx rather than on first
use, because a schedule armed before a restart has to survive one.
wanted while leaving an agent to work overnight — "continue every hour if you
have stalled", beside the background-job button.
tonight's script does it from outside, polling the sessions api and speaking
over the chat websocket exactly as a browser does, which is why the platform
needed no changes. that is the workaround; this is the feature.
records the two things the platform actually lacks — a recurring trigger, and
any door into a live session that is not the chat websocket — and the three
design notes that are easy to get wrong: never speak while isGenerating, the
schedule cannot be owned by the session it nudges (a chat background job dies
with its session, taking the watchdog with the agent), and bound the loop.
the same trigger is what the watcher-loop proposal in COMMS has been waiting
for, so it is one piece of infrastructure serving two asks.
for an agent left running overnight. it is told to record blockers and carry
on 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.
a script rather than a queue job, deliberately. 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 — so this would be real work in the
queue engine AND the chat api, done tonight, in a repository another agent is
currently working in. instead it talks to the same two doors a browser does
and changes nothing in the platform. if the loop is worth keeping, it belongs
in the queue with a real trigger, and this is what that would replace.
the one rule is that it never interrupts work: `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.
`?all=1` on the session list, because without it the list is scoped to the
owner's home and an agent started in a project directory is simply absent —
which this would have read as "the session is gone" and stopped the night.
mints its own owner token: it runs on the box, as the owner, and a token
pasted into a shell is a token in shell history. `--max` defaults to 12, so a
loop nobody is watching ends on its own.
the use case is someone mid-phone-call who needs a fact from eight years of
correspondence now. everything in here is in service of that moment.
the split that came out of the discussion, and it is the whole document:
counting needs EXHAUSTION, retrieval needs SPEED, and they are different
machinery. an agent asked "how many times did she ask X" will search, find
some, and answer with a number bounded by the phrasings it happened to think
of — "i found four" is indistinguishable from "there were nine", and nothing
in the output says which. vector search does not fix that; top-k misses too,
just differently. the only honest count is to judge every message once and
store the verdict.
which makes the compile half the one that answers the questions that prompted
this, and it needs no vectors at all.
embeddings still earn their place for the other row: keyword search finds
"school run" and never finds it from "the pickup arrangement", and on a live
call thirty seconds of searching is a lost moment. the stronger argument is
whatsapp and transcripts sharing no vocabulary with email — but we do not have
those, so they shape exactly one decision (the store is not email-shaped) and
nothing else.
two constraints stated as constraints rather than preferences: the embedding
model runs LOCALLY, because an api means uploading eight years of private
correspondence to a third party, and there is no ollama or embedding code on
any machine here — that is the real new dependency, not the database. and it
is sqlite-vec in the plugin's own file, not a vector database: 19,097 rows is
small, and a separate service would be operational surface bought for nothing.
the hard part is neither. it is quoted reply chains putting the same paragraph
in forty messages of one thread, which naive embedding turns into forty
identical results. step 1 of the build order is chunking with no embeddings at
all, because if that is wrong nothing after it can be right.
a stored verdict is a judgement a model made about someone's divorce, so it
records what it was asked, what it read and when. a number with no provenance
is worse than none, because it will be quoted.
`OFFICER_EMAIL_DB` points at a single account's sqlite file, chosen by
`findEmailAccountName` as the most recently synced. that is the right guess for
"what did X say yesterday" and a silent lie for anything meaning ALL my mail:
the agent searches one mailbox and reports as though it searched every one,
with nothing available to tell it the others exist.
the layout stopped being one file per user when several addresses became
possible — DATA_PATH/<owner>/email_accounts/<address>/emails.db — and the
reference an agent reads was still describing the old shape.
so `OFFICER_EMAIL_ACCOUNTS_DIR` is handed to the mcp tool env alongside it. the
directory rather than a list, because listing it is discovery the agent can do
itself; deriving the path from a convention would mean documenting the
convention anyway, and then having two things to keep in step.
the skill now leads with the multi-account layout, names `attachment_cache` as
the entry that is not an account, and says to state which accounts were
actually covered. checked against the live tree, which has exactly those two
entries.
the index is unchanged at 608 characters — the whole point of the split is
that the body can grow to meet the truth without any conversation paying for it.
the button counts skills — one directory with a SKILL.md is one skill. it now
also reports how many are actually OFFERED to an agent, which is a different
number: the loader skips any without a `description`, because 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, editable in the UI, and invisible to every
agent, with nothing anywhere saying why. the toast names the gap and the reason
rather than leaving two numbers to be noticed by whoever thinks to compare them.
the inverse of an affordance, and deliberately so:
affordance body always compiled in, description never sent
skill description always compiled in, body read on demand
an affordance is a fact about the surface — short, and every conversation
needs it. a skill is reference material that is dead weight in a conversation
about something else. so what reaches the prompt is the index: name, when to
reach for it, and the path. measured on the first one: 608 characters in the
prompt against 6,070 bytes left on disk.
no protocol. progressive disclosure is normally a harness feature — claude
code discovers .claude/skills, opencode has its own conventions, the next one
will have a third — and pointing at a file needs none of that, because every
harness worth running can already read a file. the cost is that the agent has
to CHOOSE to open it, which is what the description is for and why a vague one
makes a skill useless rather than merely verbose.
the first skill is the email database, moved out of tools/email-db/TOOL.md
where NOTHING has been reading it: the loader parses frontmatter and discards
the body, so that schema and its eight queries have never reached any claude
code session. written for pi, inert since pi left.
it carries two things the schema alone gets wrong, both measured against the
real 19,097-message database rather than copied from the old doc: `read` is
populated on 93 rows, so the documented unread query returns essentially the
whole mailbox; and `labels` is a comma-separated string with real values like
`updates,inbox`, so `labels = 'inbox'` misses most of the inbox.
plugins can ship skills, published and unpublished on install like affordances
and notification catalogues. flat namespace unlike those two — a skill's
directory name is the path an agent reads, and `officerdev/gitea/SKILL.md` in
a prompt is noise. a skill has no authority to usurp, so nothing needs
protecting.
wired to claude code. opencode still gets NOTHING — its runner sends no system
prompt at all, and session create takes only a directory. that needs its own
channel and a guess would be worse than the gap.
three defects, one shape: the code has two names for "which session is this",
and every guard checked the one no caller uses.
`fable` is the FIRST entry in the claude-code catalogue, so it is what
ModelSelector picks whenever it decides a conversation needs a default. On a
key without fable entitlement that lands as a 429, after a real mid-session
switch — the reported header read OPUSPLAN → FABLE.
1. the settings default was applied to RESUMED chats. the guard was
`!initialSessionId`, and no chat caller passes that when resuming — the id
arrives as `options.resumeSessionId`, and ChatPanelWrapper goes as far as
`resume ? undefined : sessionKey`. so a user's default model was written
over sessions that already had one. both names are checked now.
2. `hasStarted` was `!!preloadedMessages?.length`, which is FALSE for the
first frames of a resumed chat — before its messages arrive. ModelSelector
reads "not started" as permission to pick a default, so a reload reassigned
live sessions during that window. a session id is known on the first render
and a chat that has one is by definition not new.
3. harness lock. `crossesHarness` returned false when the current harness was
unknown, which reads as "nothing crosses" and is the opposite of what is
known — with no current harness, everything might. so a started session
offered a switch to opencode while its model was still resolving, a switch
that cannot work: it hands a `ses_…` id to `claude --resume` and dispatches
to the wrong sidecar. unknown is not permission; the strip locks until the
answer arrives.
the settings themselves were never wrong — chat.defaultModel reads
claude-code/opus on the affected server. nothing was ever reading it for the
sessions that got reassigned.
the header's rescan walks ITEM_TYPES, and affordances are not one — no
directory per item, no canonical file — so they were invisible to it. write a
new affordance, press the button, and nothing in the response mentions it.
counted by LOADING them rather than counting .md files, so the number means
"affordances the agent will actually receive" and not "markdown files
present": one with no body is skipped by the loader and should not be reported
as though it were working.
counting is as far as this can honestly go, and the toast now says so.
affordanceBlock() is read when a chat session is CREATED, so a new affordance
is already live without a server restart — for the NEXT session. nothing can
retrofit one into a conversation already running, because its system prompt
was assembled when it started. the button's value here is "the file is on disk
and the platform can see it", which was the part genuinely unknowable from the
UI.
also creates the affordances directory, so it is discoverable on a machine
that has never had one, the same way the item dirs already are.
Fifteen sites across thirteen files where a raw green stood in for a
semantic state: connection dots, health lights, completed-job ticks, the
copied-to-clipboard check, the installed badge, the checksum-matched line.
All of them meant "on / connected / succeeded", and matched each other only
because several people happened to pick the same palette number.
The values do move: --success is #16a34a where green-500 was #22c55e and
emerald-500 #10b981. That is the point — one token, so a theme can change
its mind once, and under plain.css (the leak-detection theme, which greys
--success to #404040) these now go colourless instead of staying green.
Left alone, deliberately: the confetti palette and the Start button in
start-confetti-button, the duck-avatar debug HUD, MetricCard's up/down
delta ramp, CommandBlock's check on its hardcoded dark block, the
react-email template, and the plain.css comment that names the anti-pattern.
Reds are untouched — that is a separate pass, so some ternaries now read
bg-success : bg-red-500 until it happens.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
the connection dot was `bg-green-500` and the bell followed it there to match.
both are `success` now — #16a34a where the palette value was #22c55e.
the raw palette value was the wrong thing for either to hold. tone.ts already
says why: once a view can reach for any of tailwind's twenty-two palettes,
green stops reading as "open" and starts reading as "the author liked green
here". two elements in one header meaning the same thing should say so by
sharing a token, not by two people picking the same number.
Replaces the old mark everywhere it is referenced — the header reads it through
--logo-src and every theme points at the same file, and the auth landing page and
the emailer read it directly, so one asset covers all three.
The CSS skew goes with it. That is where the old logo's slant came from, and
applying it to this one shears letterforms that were kerned pair by pair by hand
and signed off as finished. See landing/assets/brand/WORDMARK.md for the
construction.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
the bell sat on the right between the connection dot and the end-session plug,
which put a SETTING in among the STATUS. everything on the right reports what
the chat is doing now; the bell says what it will do later. it moves to the
left of the header, on its own.
and it is coloured by preference, so the setting is readable without opening
the menu: green for every end of turn, amber for input-needed, muted for none.
green is `green-500` rather than the `text-success` token deliberately — it
has to be the SAME green as the connection dot a few elements away, and a
semantic token that drifted from it would leave two greens in one header
meaning two different things. amber is `text-warning` (#f59e0b), which is the
conditional setting: it will speak, but only sometimes.
`none` keeps the struck-through bell as well as the muted colour. colour alone
is not a state anyone should have to learn, and it is the one setting where
being wrong is silent.
they were sticky at the top, which put them over the first line — and on a
one-line block, which is most of them in a chat, over the whole thing.
absolute bottom-right inside the surface now, with `.code-surface` given the
`position: relative` it never had. that omission is why a control could end up
escaping to the nearest positioned ancestor and floating below the block it
belongs to.
`padding-bottom` on the pre to go with the existing `padding-right`: the last
line is the one they overlap now, and it needs its own room the same way the
first line needed it before.
the trade the old comment was worried about is real but smaller than it reads:
a block taller than the viewport now has its controls at the bottom rather
than the top. that is where you end up after reading it anyway, and it is a
worse place to be only for a block you never scroll — which is exactly the
block whose first line the old position was covering.
the tenth install in a row with something new wrong, and the pattern behind
them is not the individual faults. every step in provisionOsAccount is
deliberately non-fatal — a member whose account provisioned fine should not be
rolled back because their shell config failed. that is right, and it means
"nothing reported an error" is a far weaker statement than it reads as.
the acl-mask bug was the sharp version: a clean provisioning run, every named
entry correct, and an account that could reach nothing. it was found by a
person three days later, through a file browser message three steps removed
from the cause.
so provisioning now VERIFIES rather than assuming, and it verifies by making
the same readdir the file browser makes. deliberately not by inspecting the
acl: reading getfacl and reasoning about masks is exactly how this was missed,
because the acl looked right. a check that tests something adjacent to the
failure is how you get a green report and a broken server.
a failed check is reported FIRST, ahead of keys and shells — an account that
cannot read its own home is broken in a way that working ssh does not make up
for.
and `bun run doctor` for the nine servers that already exist: same check
across every account, plus the one that is invisible by construction — a
confined grant held by an account with no linux user, which sits in the table,
shows as ticked in the UI, and resolves to nothing.
read-only, so it is safe on a production box. exits 1, so it can gate the end
of a setup run. same posture as assertPermissionTotality, except this reports
instead of refusing to boot: one broken member must not stop the platform
serving everyone else.
on a fresh server an Admin granted files, chat and terminal reached none of
them. the grants were right, the linux account existed, the named acl entries
were on the home — and the file browser still raised EACCES.
a posix acl mask is not independent of the mode bits. chmod recomputes it from
the GROUP bits, so a directory closed to 700 gets `mask::---`, which clamps
every named entry to nothing. the platform's grant survived as
`user:pastilhas:rwx #effective:---`: present, correct-looking, and inert. it
reads as a working acl in every place anyone thought to check.
ensureOsUser already knows this and orders itself correctly — chmod, then
setfacl, with a comment saying why. verified that order is right by running
both ways on the affected host: chmod-then-setfacl gives mask::rwx,
setfacl-then-chmod gives mask::---.
what it cannot account for is the steps AFTER it, each of which creates a
directory and then closes it: .ssh at 700 from the key setup, .config and
.local from the claude installer. each inherits the default acl at creation
and clamps its own mask a moment later. the correlation on the live host was
exact — every 770 directory had mask::rwx and every 700 one had mask::---.
so the mask is re-asserted at the very end of provisionOsAccount, recursively,
and nothing else is touched: the named entries were never wrong, and
re-granting them here would hide it if they ever were.
non-fatal if it fails, like every other side effect in that function. but it
is the difference between an account that works and one that only appears to.
repaired on the affected server by hand first, and confirmed: home readable by
the service user, zero `effective:---` entries left under it.
Found while pushing chat_notification_prefs. Harmless — eight extra
statements, no prompt, no data touched — but the database CLAUDE.md told
the next person to expect only the two pk_music_now_playing lines and to
treat anything else as their own change, which is no longer true. Both
corrected; the fix itself is deliberately not done.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
--resume is scoped to the working directory: Claude Code files transcripts under
~/.claude/projects/<slugged cwd>/<id>.jsonl, so resuming from anywhere else fails
with 'No conversation found with session ID' — exit 1, before any output.
Conversations created before the New Chat directory picker carry no cwd, fall
back to HOST_HOME, and could therefore never resume: every message died the same
way, the banner said only 'exited with code 1', and the exit line claimed
stderr=<silent> while the CLI had printed the reason plainly.
The transcript knows its own directory — every line carries cwd — so it is read
from the file rather than guessed, first line only, since these reach 100 MB. An
explicit cwd from the caller still wins. When the same id exists under two project
dirs (a checkout that moved: officerdev/platform and officer-dev/platform both
hold one here) the newest wins and a vanished directory is skipped.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
the browser bell and phone push are now two subscribers to one signal. both
ask shouldNotify(); neither owns the rule.
deliberately a second subscriber rather than a branch inside notify-delivery.
the two channels share only the question "does this account want to hear about
this" — the browser needs an open tab and sends the chat's real title over a
loopback socket on the owner's own tailnet, the phone needs no tab and must
send NO title, because that hop goes through apple. one function doing both
means an `if (isPush)` at every step, and the first thing to go wrong is a
title leaking because the branch was missed in one place.
two codes, officer/core:chat.turn-ended and chat.input-needed. the route is
written out with its scheme rather than derived from the target: the hub has
no chat screen — chat is Butler, a sibling app — so these deep-link OUT over
officer-chat://, and two of the suite's twenty-one schemes already break the
officer-<app> pattern (officer-videos, officer-readaloud). deriving that works
until it silently does not.
`thread` interpolates now, so `chat:{id}` groups per conversation. a static
thread forces a choice between "three pings from one chat collapse" and "two
busy chats stay apart", and the wrong answer is that every chat is the same
chat.
dropped officer/core:agent: chat.turn-ended supersedes it and its route
pointed at officer://chat/{id}, a hub screen that does not exist.
the banner cannot name which conversation. a chat's title is content and
content does not travel; it says what happened, and tapping opens the chat,
which is where the name lives.
review of 73cdc2cb before building the phone half on it. three changes, and
the third is the one that matters for mobile.
1. "every end of turn" was silent when the agent asked you something.
the two kinds are disjoint at the source: turn-ended fires on
result/error/stopped, input-needed at a plan or question gate — which PARK
the turn and never emit a result. matching them one-to-one meant whoever
picked the most inclusive setting got nothing for the most urgent event.
every_turn is a superset now.
2. the preference is keyed on (user_id, session_id), not session_id alone.
the route skipped an ownership check on the reasoning that a preference for
a session you cannot reach is inert. it was not: delivery targets the
userId the sidecar reports while the preference was read globally, so any
account holding `chat` that knew a session uuid could set 'none' on someone
else's conversation and switch off their notifications, or every_turn to
make their phone buzz all night. surrogate id plus a unique INDEX rather
than a composite primary key, which drizzle-kit re-creates on every push.
3. the decision moved out of the browser socket into notify-decision.ts.
it lived inside notify-delivery.ts, which was fine while the browser was
the only listener and stops being fine the moment push subscribes to the
same signal. two copies of the rule drift, and the symptom is a bell and a
phone disagreeing about one conversation — close to undebuggable from
either end. both channels ask the same function now, and the rule is pure
so it is tested without a database.
the rest of the commit reviewed well: the ws upgrade is authenticated AND
permission-gated, there is a registry entry so totality passes, the list query
is batched rather than per-row, reads are defensively caught, and
Notification.requestPermission is requested lazily on opt-in.
alpha was missing the table entirely — reads degraded via .catch but the PATCH
would have 500'd. pushed there too.
Client half of the per-chat notification preference — DetailBar gets a bell
dropdown (every end of turn / only when input is needed / none), a global
useChatNotifications hook holds one connection to /api/chat/notify/ws for
the whole session so a background chat can still ring the bell and fire a
browser Notification, and the session list shows a badge on any row set to
notify. The server side (schema, the notify-delivery socket, the sidecar
signal at turn-end/plan-gate/question-gate) landed already in 5cba1b65,
swept in from a concurrent session sharing this working tree.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
reported from the field on the first real push: it failed with BadDeviceToken
and the server deleted the registration. the build was production-signed and
the row said sandbox — a configuration mismatch, with the device and the app
both perfectly fine.
pruning there destroys the evidence. the phone re-registers on next launch,
the row comes back looking healthy, and the next send fails identically; you
can lose a day to that loop without ever seeing what is actually wrong.
so the one set becomes three. Unregistered/UNREGISTERED/NOT_FOUND prune —
apple and google are saying the app is uninstalled. BadDeviceToken,
DeviceTokenNotForTopic, TopicDisallowed, INVALID_ARGUMENT and
SENDER_ID_MISMATCH are OURS: the row is kept and the log says what to check.
everything else is transient and still counts toward three strikes.
INVALID_ARGUMENT was the sharpest one. it is how fcm reports a malformed
MESSAGE — including a non-string in `data`, which is the mistake this codebase
is most likely to make and already has a test for. deleting on it meant one
bug in the payload builder would wipe every android device from the registry
on a single send, presenting as "android push stopped working" with nothing
left to explain why.
misconfigured is also not counted as a strike. not deleting is not enough on
its own — a persistent mismatch would reach three failures and delete the row
anyway, which is the same bug with a slower fuse.
the apns log now names the mismatch rather than the reason code, since the
code alone sends people to look at the device: it prints the row's environment
and topic and says to check the SHIPPED artefact rather than the intermediate
build, which is exactly where this one hid.
reported from a fresh install: ENOENT spawning radicale, over and over.
two bugs, and the second is the worse one.
`spawn('radicale')` resolves against the PATH THIS PROCESS STARTED WITH, and
under pm2 that is a login-less minimum with no ~/.local/bin. the same trap has
now bitten `tea`, the plugin dependency probe and this, so the search path is
explicit here rather than inherited: ~/.local/bin, /usr/local/bin, /usr/bin,
/bin, then whatever pm2 supplied. /usr/bin is listed even though it is
normally present — it is where the apt package lands, and a PATH mangled by a
shell profile should not break the supported install.
falls back to `python3 -m radicale`, because radicale is a python package: a
pip install --user without ~/.local/bin on PATH, or a distro shipping the
module with no wrapper script, both leave it importable and unfindable. the
module is the thing that matters.
the second bug: startRadicale runs at module top level, so the ENOENT threw
and killed the sidecar, and pm2 restarted it forever. that is the opposite of
what the backoff inside it is for, and it took /_health down with it — so the
one endpoint that could have said what was wrong was the one thing not
answering. a missing dependency is now a value the caller handles: the sidecar
stays up, /_health returns 503 with the install command, and `installed:
false` distinguishes "never installed" from "crashed and backing off". both
are 503 but only one is fixed by waiting.
resolveRadicale takes an optional PATH so the null branch is tested rather
than reasoned about. verified the happy path live: radicale launched, sidecar
registered, zero restarts.
sketched the same day push landed, because push is the piece that makes it
possible at all — there is no other way to reach a sleeping phone.
more of it exists than expected: the wake channel, a working maplibre map with
clustering in the photos plugin, and headscale already reporting online and
lastSeen per node, which covers laptops without an app at all. what is missing
is a table, an endpoint, some app code and a panel.
what it can never do is stated up front rather than discovered later. apple's
offline finding works because a billion strangers' devices relay a lost
phone's bluetooth beacon. there is no self-hosted version of a crowd. off-grid
gets you last-known-position; powered-off gets you nothing.
two things i expect someone to get wrong, so they are called out above the
schema:
- do NOT key location on the push token. apns tokens rotate, the registration
path is already an upsert because of it, and a history keyed to one silently
forks into two devices. this needs a stable on-device uuid and a `devices`
table that is not push_devices — which is worth building anyway, since the
push registry currently has no stable device identity at all.
- store accuracy and draw the circle. ios returns 3km fixes when it is being
cheap, and rendering one as a confident pin sends someone to the wrong street.
the sharpest open question is not technical: the owner bypasses every
permission check by design, so on a family server the owner can see a member's
location structurally, unless location is given an explicit exception. that
falls out of the architecture rather than out of anyone's intent, so it should
be decided deliberately.
retention likewise. a location table is a complete movement record, apple
deliberately cannot build one, and self-hosting means choosing to. the rule
belongs in the design, not in a settings screen added afterwards.
the substance was in plugins/CLAUDE.md marked "DESIGN, NOT BUILT", which
stopped being true the same day it was written — load.ts reads them, publish.ts
copies a plugin's in on install, and claude-manager compiles them into every
session. moved to docs/affordances.md and corrected; plugins/CLAUDE.md keeps
the plugin-specific part and points here.
the new part is a third test, earned today by nearly failing it twice: CAN IT
BE FIXED INSTEAD? an affordance is for something irreducible about the
surface, and a defect is not irreducible.
both candidates drafted today failed it. "links open in the same tab" was one
missing line in MD_COMPONENTS. "AskUserQuestion never returns an answer" was
true when the code comment was written and already fixed by the time i read
it — that one would have shipped a permanent instruction to work around a bug
that no longer existed, in a file whose whole purpose is to be believed
without checking.
names the failure mode: an affordance describing a defect calcifies it. once
there is a document explaining the workaround, the defect has a rationale, and
the rationale outlives anyone's memory that it was a bug.
also records two things that are not built and read as if they were: nothing
is scoped, so every affordance is in every conversation, and affordanceBlock()
has exactly one caller — an opencode turn gets none at all.
officer is a single-page app, so a same-tab navigation to an external url
unloads it — tap a link in a message and you come back to a cold boot with the
scroll position and anything mid-flight gone.
`a` was simply absent from MD_COMPONENTS, so every link rendered as a bare
anchor. all four ReactMarkdown call sites in MessageBubble share that object,
so one override covers assistant messages, user messages, tool output and the
collapsed blocks.
noopener noreferrer with it: a bare target="_blank" hands the opened page a
live window.opener back into the app. target is set AFTER the prop spread so
raw html in a message cannot override it with _self.
putSecret/getSecret, `bun run secret:set`, and notify taking its credentials
from the store with env as the fallback. this was described two messages ago
as a later thing; it is about fifteen lines and it was blocking the honest
answer to "where does the .p8 go", so it is done.
getKey was the wrong door for anything supplied from outside — it MINTS a
random 32-byte value when the purpose is absent, which for a foreign
credential means silently authenticating to apple with a fake. getSecret
returns null instead, which is what lets the env fallback work.
putSecret retires the previous row rather than deleting it: a mistyped paste
over a working key should be recoverable, and retiredKeys already exists for
that shape. one transaction, because the partial unique index means the retire
has to land before the insert.
the CLI reads stdin and has deliberately no --value flag: a secret in argv is
in shell history, in ps output, and in any audit log that records command
lines. offering the flag would make the convenient path the leaky one. it
prints a length and the last four characters, never the value.
also `bun run notify:test`, which fires officer/core:test at a registered
device. the sidecar's port is ephemeral, so it now writes its address to
data/notify-server.url on boot and removes it on clean shutdown; the CLI
treats an unreachable address as "not running" rather than trusting the file,
because a crash leaves one behind.
the script says what actually happened, because the day-waster here is that a
send with nothing configured returns success and delivers nothing — it refuses
up front when channels is empty, and calls out sent:0/failed:0 as "no device
registered" rather than letting it read as success.
verified end to end with a p-256 key generated locally and then deleted from
the store: zero APNS vars in .env, sidecar reported channels: apns, and the
send reached the channel. store is back to jwt and offscale only.
env is the interim. the secret store's own reasoning applies almost verbatim:
bun auto-loads .env into every pm2 process, so the .p8 is readable from
/proc/<pid>/environ of twenty of them. officer-music has no business being
able to read a key that can push to the owner's apps forever and never
expires.
the obstacle is not a missing purpose string, which is what it looks like from
the outside. getKey(purpose) GENERATES a key and returns it — there is no
setter, because everything in the store so far is something the platform
minted itself. the .p8, the key id, the team id and the fcm service account
all come from outside, so this needs putSecret and a decision about who may
call it. same for DISCORD_WEBHOOK_URL and every plugin credential still in env.
recorded in TODO.md and in the design doc rather than left as an intention.
the sidecar now sends what the design describes.
producer contract: { code, userId, n?, id? }. validated on the SHAPE of the
code, never against the catalogue — a producer firing a code the mapping has
not caught up with is sending a real event, and dropping it here would trade a
degraded notification for none when the device already has a defined fallback.
the shape check still catches a typo at the producer instead of on a phone.
`ok` is gone. a failed job is its own code, officer/core:job-failed, which is
the thing the five-value enum could not express without a boolean bolted on.
apns: mutable-content: 1, alert.title fixed to the generic, and officer:{c,n,id,mv}
beside it. deliberately NOT the catalogue's title — sending the real text would
hand apple the category vocabulary in plaintext, which is what the code exists
to withhold.
fcm: data-only, no notification block. a notification block is rendered by the
system, which would put the code on the lock screen and give the app no chance
to resolve it. priority high is load-bearing — a normal-priority data message
can sit in doze indefinitely.
discord renders server-side from the catalogue, because it has no app to
resolve anything. safe: catalogue titles are templates and carry no user
content.
the catalogue is loaded ONCE per dispatch, not per channel or per device, so
every copy of one notification carries the same mv. two channels reading disk
either side of a plugin install would otherwise tell two devices different
things about the same event.
40 tests. verified live: a malformed code is refused, officer/core:test is
accepted and dispatches to zero configured channels.
the piece that makes a new notification kind a server change rather than an
app store release. a push carries a code and integers; this is what the code
means, synced to the device instead of compiled into it.
deliberately the same shape as affordances rather than a second mechanism: a
`notifications/` directory of yaml in the plugin repository, copied to
capabilities/notifications/<publisher>/<appName>/ on install, removed on
uninstall. publish.ts mirrors affordances/publish.ts closely enough to diff.
the namespace is DERIVED from where the file lands, never from what it
declares — same rule as mountPrefix. a plugin writing `officer/core:test` as a
key gets `<publisher>/<plugin>:officer/core:test` and the real core entry is
untouched. that is the security property of the whole scheme and it is pinned
by test.
version is a content hash, not a counter. a counter needs somewhere to live
and is then wrong after a restore, a rollback, or two servers built from the
same install; a hash needs no storage and is right in all three. so the client
compares mv !== version, and both docs now say so — i had written "higher".
core entries ship in code rather than on disk, because capabilities/ is
installed rather than committed and `test` has to exist on a machine that has
installed nothing — it is what first light is proved with.
read from disk per request, not memoised: installing a plugin has to change
the answer without a restart, or it presents as "the new plugin's
notifications don't work", which is the hardest kind of bug to place.
verified live: 401 through the platform, plugin catalogue appearing and
disappearing with no restart, version returning to its prior value when the
plugin is removed. 10 catalogue tests, 100% coverage of catalogue.ts.
three questions answered from monorepo-mobile, and two of my assumptions were
wrong.
bundle ids exist — dev.officer.mobile and dev.officer.mobile.dev. two of them
needs nothing special: push_devices is unique on (token, bundleId), so the
variants are separate rows on one phone, and the dev variant is exactly the
sandbox/production distinction the doc warned about. concrete now rather than
derived from build config by guesswork.
scheme is officer:// and officer-dev://, both from app.config.ts.
expo prebuild, not bare — and a config plugin that creates an ios app
extension target ALREADY EXISTS there, withVaultAutofillTarget.js for the
autofill extension. the nse follows it. that removes what i had called the
longest pole in phase 3.
corrected: expo-notifications is not in apps/mobile at all, only apps/chat.
the real blocker is narrower than the doc implied and is not code. today's
signed build has no aps-environment entitlement, and adding one fails while
xcode has no account signed in — same failure as the network extension on
2026-08-05. one manual sign-in, team RGHC4NJC77, then automatic again.
alpha: /api/notify was 404 all day because that server predated the work.
pulled, db:push, gen:ecosystem, officer-notify started, officer restarted.
verified 401 unauthenticated and push_devices with its 10 columns.
the 2026-07-31 design promised this document to `officer-suite/COMMS/`, a repo
path that has never existed. writing it where the work is instead, to be
handed to whoever builds the client.
exact contracts rather than prose: the three device routes with real request
and response shapes read off devices.ts, what is required versus defaulted,
and that the server takes the user from the session and ignores a userId in
the body.
most of it is the failure modes that cost a day each and are invisible from
the client — a send with no credentials configured returns success and
delivers nothing; a sandbox token registered as production fails at apple with
no user-visible symptom; the notification extension must not touch the network
or it will pass every test at a desk and fail on cellular with the vpn off.
leaves three questions for the owner: whether apps/mobile has a bundle id and
a provisioning profile at all, its url scheme, and expo managed versus bare —
that last one decides how the extension gets built and is probably the longest
pole in phase 3.
`personal` is matched against what remains after the permission's own prefix
is stripped, so the entries had to be the sidecar's real paths. they were
written '/devices' and '/subscriptions'; the sidecar serves '/_officer/devices'.
nothing matched, so read level permitted the GET (a safe method, allowed
anyway) and refused the POST and the DELETE — a member could see their
registered devices and neither add nor remove one.
that is the exact opposite of the comment sitting above it, which says device
registration is the caller's own. invisible so far because the owner
short-circuits every check and no member has ever been granted notify.
found while writing the app-side spec: the mobile client posts to
/api/notify/_officer/devices, which is what made the mismatch visible.
the regression test pins the real path and fails against the old value —
checked, not assumed.
second design, superseding 2026-07-31. the reversals are recorded rather than
overwritten, because the first one called its payload rule "not optional" and
this changes it.
one app on the device receives everything and renders it. the payload is a
namespaced code plus integers; the code's meaning lives in a server-owned
mapping synced to the device ahead of time, so a new notification kind is a
server change and never an app build. plugins declare their own codes on the
affordances pattern, which already does exactly this shape.
what moved: privacy relaxed but not abandoned — codes keep content off apple
and google while dropping the rigid category enum that made the doorbell
painful. appSlug inverts from "deliver to this app" to "deep-link to this
app". extensibility becomes the binding constraint.
the piece that makes it work is that the ios extension does a LOCAL lookup
against a synced mapping, not a fetch on arrival — so it does not depend on
the tailnet being up when the push lands, and it costs one build ever rather
than one per kind.
records two things it does not solve: the code vocabulary is still a
fingerprint to apple and google, and the grapheneos/fcm contradiction between
apps/mobile/PUSH_NOTIFICATIONS.md and the platform design is still unresolved.
built 2026-07-31, switched off 2026-08-13 when it was slated to become a
plugin alongside memos and photos. those two were extracted; this one never
was, so it spent six days mounted nowhere with its schema commented out and
no pm2 entry — complete code that nothing could reach.
core rather than a plugin because the producers are the platform's own: the
job queue, an agent turn ending, mail arriving. a notifier the owner can
uninstall is one those producers cannot rely on.
- hono.ts mounts /api/notify again; verified 401 unauthenticated, so the
permission gate covers it and assertPermissionTotality accepts the mount
- push_devices exported from the core schema and pushed: 10 columns,
uq_push_devices_token_bundle, idx_push_devices_user
- officer-notify added to CORE_PROCESSES, so gen:ecosystem writes it
- credentials read OFFICERDEV_X ?? X, the convention it predates
safe as core because it boots with nothing configured: every channel reports
isConfigured() false and dispatch resolves empty. verified by importing it
with the env stripped — "channels: none configured", no throw. an install
with no apns key runs it as a no-op rather than crash-looping.
APNS_ENV is dropped from the doc's credential table. it was never read: the
host comes from each device's `environment` column, so one server pushes to a
testflight build and a release build at once.
doc status corrected. the app side is not started — there is no officer-suite
repo, no PUSH_NOTIFICATIONS_APP.md, and apps/chat actively strips the ios push
entitlement. recorded there rather than here.
RULES was a hardcoded map from every route prefix to a title, which meant a
new route silently fell through to 'Officer' until somebody remembered to
add an entry — the gap that hit installed-plugin routes, which had no entry
at all. titleForPath now takes the URL's first path segment and title-cases
it, so every route gets a sane tab title for free, including ones a plugin
adds at runtime. Trade-off: a few routes lose their hand-tuned casing
(QR Transfer -> Qr Transfer, Command HQ -> Command Hq) and settings
sub-routes collapse to the one 'Settings' title instead of a distinct one
per section — both accepted as the point of removing the table.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The answer channel is a denial — the only PreToolUse decision that can carry a
result — and the harness stamps every denied tool `is_error`. So a perfectly
good answer arrived looking like a failure: red in the transcript, and read by
the agent as something that went wrong rather than as the reply to its own
question. Confirmed on the first live question through the new channel, which
came back as `<error>Show it in Officer</error>`.
The parser already sees the tool_use that opened the question, so it records the
id and clears the flag when the matching result lands. A timeout or a lost
session lands here too and is equally not an error: its output is a sentence
explaining itself, which the agent should read rather than retry.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The harness answered every question itself, instantly, with "The user did not
answer the questions." — before the card had painted, let alone been read. The
agent then reasoned about a refusal that never happened: on 2026-08-19 it asked
the same question three times in a row while the answers sat on the screen.
The web UI already worked around it by rendering the card ungated and sending
the click back as an ordinary chat message. That got an answer through, but the
agent read it as a new instruction arriving from nowhere rather than as the
reply to what it asked, and nothing could distinguish a live question from one
answered last week — every replayed transcript rendered its old questions as
clickable.
A PreToolUse hook is the fix, and it has to be a hook rather than canUseTool:
under bypassPermissions — which is every session here — the SDK shadows the
callback and never calls it. Measured against 0.2.59: a bypassing session's
AskUserQuestion reached the hook and never reached canUseTool. Hooks run
regardless of permission mode.
The hook parks on a promise keyed by the harness's own tool_use_id, and returns
`deny` with the human's answer as the reason — which the harness feeds back as
the tool result verbatim. "Deny" reads wrong and is right: what it denies is the
tool's ability to answer for the user, and what replaces its output is what the
user actually said. Held open for 150s in testing with the turn completing
normally, so a person has time to think.
Keying on tool_use_id rather than an invented id means no new durable event: the
questions are already in the session log as an ordinary tool:start, and the
answer arrives as its tool:result. One source of truth, replay included — which
is what re-enables gating the card on `output`, and with it the staleness fix.
The two tests that pinned the old ungated behaviour asserted the workaround as
the contract; they now pin the reversal, including a pre-fix transcript reading
as settled, which it is.
Unanswered questions settle like plans do: 20 minutes, every session-ending path
draining them first, and wording that tells the agent the question is still on
the user's screen and must not be asked again.
Mobile (Butler) has the same workaround and is not fixed here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The chip could not be cleared by any means, and the toast could not be silenced
from the call site: useClient raises a GLOBAL onError before it throws, so
handling the failure where Stop is pressed was always going to be too late.
DELETE is idempotent. Asking for a job to stop when it is already gone has
achieved what was asked, so "no such task" and "already stopped" now answer 200
with `gone: true` instead of 400. No error, no toast, and the client clears the
chip on the flag.
A genuine refusal — a malformed id, a subagent with no fd to trace — is still
400.
The previous client-side check stays as a fallback, for a browser talking to a
server that has not been updated yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A chip stuck on "running" could not be stopped, killed or dismissed. Stop and
Kill both answered {"stopped":false,"reason":"no such task"} — there is no
output file, so no pid, so nothing to signal — and dismiss is only offered for a
task the tray believes has finished. A chip with no way out.
The server saying it cannot find the job is authoritative rather than an error
worth reporting: the chip was the last thing claiming it existed. Pressing Stop
now clears it.
Running chips still have no dismiss button of their own, deliberately — the
tray is the only thing watching a live job and a hidden one is a job you have no
way back to. This is the escape hatch for a job that is not actually live, and
it is reached by pressing the control you would already have pressed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Your own messages were plain `whitespace-pre-wrap`, so pasting a fenced block
gave you back the backticks and none of the formatting — the one place in the
app where markdown was written and never read.
The usual reason to leave user text alone is that rendering changes what was
typed: `a_b_c` becomes italic, a leading `#` becomes a heading. That is real,
and the answer is the Copy button beside it, which copies the RAW text. The
original is one click away and nothing you wrote can be lost to a renderer.
Same remark plugins, components and sanitize schema as the assistant's,
deliberately — a code block should look identical whoever wrote it, and the
schema already strips script, iframe, object, embed and form, so pasted HTML is
inert either way.
The copy button appears on hover rather than always, unlike the assistant's: a
reply is something you copy out of, while your own message is something you
already have, so the control earns its place only when reached for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A background job that ignores SIGTERM could not be stopped from the UI at all.
Stop sends SIGTERM to every pid holding the job's output file, and the second
click sent the same signal again — task-restart.ts already said "that is what
the second click is for", and it was not. Reported after a job hung in another
chat.
The button now escalates instead of a second button appearing beside it. Press
Stop, and if the job is still running three seconds later the same control
becomes Kill in the destructive tone, and sends SIGKILL.
Escalating rather than always offering Kill, because a permanent Kill button is
a second destructive control competing with the first, and people reach for it
by default — losing the graceful shutdown that usually works. The delay is the
same argument: a clean exit takes well under a second, so offering Kill at once
teaches everyone to press it first.
`?force=1` on the existing DELETE rather than a second route: same verb on the
same thing, differing only in how hard it asks. The member path escalates too —
one `kill -KILL` run as them, since fuser and the kill must both be their own
identity.
Stated in the button's own title rather than hidden: SIGKILL gives the process
no chance to release a port or take its children with it. That is the right
trade for a hang and the reason it is not offered first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Update button failed with "couldn't find remote ref main" on every checkout
made before the plugin repositories were standardised on `master`. It pulled
`origin <local branch name>`, and the local branch and the remote's default had
stopped agreeing — so the button could never work again on exactly the installs
that most needed it.
Now `git fetch origin HEAD` and a fast-forward: HEAD resolves to whatever the
remote's default is, so the local name stops mattering, and the merge applies it
to whichever branch the checkout happens to be on.
Fourth time today that naming a branch was the bug — the marketplace icon URLs,
the capabilities sync, the setup script, and now this. The rule that keeps
holding: fetch HEAD, never a name.
Verified by reproducing it — renamed a real checkout to `main`, pulled against a
remote that has only `master`, and it succeeded.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Fable 5