68f4fe61faca3ea9a46ec947da5ebabc30d335be
867
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
  pastilhasandClaude Opus 5
|
a51a969cd0 |
a file with no turns in it is not a conversation
Four "(untitled) · 0 msgs" rows accumulated in the sessions list from one evening of commander testing. They are transcripts containing only harness metadata — last-prompt, ai-title, atis-latch — written after a session was deleted or before it ever sent anything. Filtered at the list, not deleted on disk: the files belong to the harness, and a cleanup racing it would be the same class of bug that produced them. Which is also the cause of two of the four. The delete path resolves officer's session key from two in-memory maps, and both answer only for a session younger than the process. After a restart neither does, so no kill is sent, nothing is awaited, and the transcript is removed while the harness is still writing — which writes it back. Same failure as the events cleanup, same durable answer: the event rows carry both ids, so ask them when the maps cannot say. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
5c802b07b5 |
a command dropped for want of a sidecar has to say so
`sendFire` looked up a sidecar, and if none was registered it did nothing. No log, no error, no return value — the command simply stopped existing. That window is real and entirely predictable: every `pm2 restart officer` has one while the sidecars reconnect, and somebody clicking a button has no idea they are in it. The cost landed hardest on answering a question. `answerClaudeQuestion` in the agent documents this exact failure in a careful comment and cannot report it, because the command never arrives to be reported. So the question card kept spinning, which from the person's side is indistinguishable from a slow agent, and the only move left is to send another message — the worst possible thing to do to a waiting tool call. Observed tonight, on a restart I ran myself while a commander was mid-question. So `sendFire` returns whether anyone took the command and warns when nobody did, and the two paths where a person is actively waiting — a question answer and a plan decision — tell them instead of leaving the card to spin. The other five callers are unchanged and now leave a log line, which is the part that was missing when this was diagnosed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
2aef23c8ba |
a commander starts its own conversation, instead of being handed one
Starting a commander meant writing a good opening prompt, which is the hard part of the whole thing — so in practice somebody else wrote it and pasted it in. That is not a flow, it is a person acting as the intake form. Now the two decisions that cannot be guessed stay with the owner (a name and a working directory) and the rest is a button. It sends a brief the MODEL reads — "I have not told you what I want yet, orient yourself and ask me one question" — while the transcript shows "Set me up.", which is what a person would have typed. That split is `effectivePrompt` vs `displayText` and the chat path already had it. What to ask, in what order, and to read the directory BEFORE asking anything, all live in the Commanders skill under "When you started yourself". Deliberately not here: capabilities are re-read from disk every run, so rewording a question costs nothing, while the same words in commander-block.ts cost a restart each time. The block carries a pointer and no doctrine. Orienting first is what makes this work on a real request. Told "automate the platform deploys", a commander that has read the directory finds `deploy/`, the previous releases and the deploy skill, and asks whether that is still how you want it — instead of inventing a scheme next to the one already there. `sendPrompt` gained an options object rather than a tenth positional parameter. Nine is already past where a call site reads as a row of undefineds. The composer stays enabled beside the button: typing your own opener still works, it just is not the only way in any more. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
eefcb06e35 |
stop the harness before deleting its transcript, and wait for it to actually stop
Deleting a commander removed its transcript and the `claude` CLI wrote it straight back. Verified rather than inferred: the file returned with 22 lines, every one timestamped after the delete, and the deleted commander was sitting in /chat as "(untitled)" — no longer in `command_hq_sessions`, so nothing filtered it out. Delete a commander, get an untitled chat back. Two causes, and the first one hid the second. The kill never happened. `killClaudeSession` was imported straight from `claude-manager` into a route that runs in `officer`, while the session map lives in `officer-claude-code`. It read an empty map in the wrong process and returned false every time. `claude:kill` and `killClaude` already existed for this; the route just wasn't using them. And killing is not being dead. `abort()` returns while the CLI is still unwinding, and officer does not own that file — the CLI does. So a session now carries an `exited` promise resolved by the same exit hook that already reaps it, `claude:kill` replies only once that resolves, and both delete routes await the reply before touching the filesystem. Bounded at 5s and never fatal. A child that will not die delays a delete by seconds instead of hanging it, and a sidecar that is down leaves the caller with exactly the race it already had. `markExited` fires before `dropDeadSession`'s identity guard, deliberately: a waiter has to be released even when a newer session has taken its key, or it blocks for the full timeout on a process that died on schedule. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8ac3ca7fe5 |
forgetting a conversation needs both of its ids, not one twice
`chat_session_events` is keyed on officer's SESSION KEY. The other three tables are keyed on the harness's TRANSCRIPT ID. Both are uuids for the same conversation, and `forgetChatSessions` took one list and passed it to all four — so the events delete matched nothing. Not sometimes: by construction, every time. A deleted conversation left its entire durable output behind. It survived two verifications because counting events BY TRANSCRIPT ID also returns zero by construction, and zero read as "cleaned". What settled it was reading an orphaned event instead of counting it — the payload carries both ids side by side and says outright which key the row is filed under. So the parameter is now named for its id space. That is the whole defence and it is the only one available: nothing else distinguishes the two, since both are uuids of the same shape, and a positional `string[]` cannot be got wrong loudly. Empty `sessionKeys` is legitimate and common — a session spawned by `claude -p` outside officer's websocket never had a key and never wrote an event, which is exactly a commander's children. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Fable 5
|
03e7ca39c3 |
minesweeper: narrow send(), and tell the ws mirror about the provider
two failures another session found in a shared checkout, both mine. send() took a plain Uint8Array, whose default buffer type is ArrayBufferLike and may be a SharedArrayBuffer — WebSocket.send takes only BufferSource. narrowed to Uint8Array<ArrayBuffer>, which every caller already builds and which the terminal relay already does. registry.test.ts keeps REAL_WS as a hand-written mirror of server.tsx's handlers map, and its own comment says that drift is what it catches. it caught mine: the route and the registry entry landed, the mirror did not. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
3837af657d |
live sessions default to agents only, and you ask by name for a commander
`?kind=` was opt-in, so a client that said nothing got everything — which is the wrong default for the one caller that cannot cope. The phone swipes between live chats one at a time, has no room for tabs and no way to skip a row, so a commander in that list is a commander you are stuck on. Defaulting to `agent` means forgetting the parameter can only ever under-report. The two callers that want both now say `kind=all` explicitly, and that is a fair price: they are few, they are on screens built to show both kinds, and they are the ones positioned to notice when the answer is wrong. `counts` still describes every live session whatever the filter, so a filtered caller renders both tab numbers from one request rather than two. Also corrects useLiveSessions' comment, which said `isCommander` was derived from the cwd. It stopped being true when a commander gained the right to choose its own working directory — it comes from the `command_hq_sessions` row, and the directory answers nothing. Unrelated but caught by docs:check on the way past: the registry gained a nineteenth entry (minesweeper, execution) and CLAUDE.md still said eighteen, which also left the generated platform skill two lines stale. Both corrected; the check is green again. The minesweeper feature itself is half-landed and not mine — `rfb.ts` fails typecheck and its registry test fails on a websocket that is not served. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
749c80c877 |
the server says which live sessions are commanders, and can return just one kind
/chat/live already classified every row from `command_hq_sessions`; what it did not do was filter, so each client repeated that itself. Fine for the web list, which shows both tabs at once. Wrong for the iPhone app, which swipes between live chats, has no room for tabs, and must simply never be handed a commander. `?kind=agent|commander` does it server-side. Counts always describe the whole set regardless of the filter — the web tabs show both numbers side by side and both must be right whichever tab is open, so a filter that also hid the other count would force a second request to render one screen. An unrecognised kind is a 400 rather than "everything": a mistyped `?kind=agents` silently returning commanders is the precise swipe-order bug this exists to prevent, so the plural forms are accepted too, since the client's own type is already plural. And /chat/sessions no longer tags rows it is about to delete. It called listCommandHqSessionIds twice — once to mark commanders, once to remove exactly those rows four lines later — so isCommander was false on every row that survived. A field that could only ever lie, plus a second identical query per request to produce it. A list that excludes commanders has nothing to say about which of its rows is one; withCommanderFlag had no other caller and is gone. Not restarted: the shared checkout currently fails typecheck on another agent's untracked Minesweeper work, and a restart is when half-applied work ships. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Fable 5
|
af918251d3 |
/minesweeper — a wine session streamed to the browser over RFB
a websocket byte relay onto x11vnc's tcp socket, the same shape as the terminal's relay onto the pty sidecar. this is the piece plugins/desktop could not have: a plugin cannot claim a websocket provider. the rfb client is ours rather than vendored novnc — raw and copyrect, one pixel format we dictate so a rectangle memcpys into ImageData. we control the server, so the other eight encodings are surface we would carry and never run. execution, so owner-only: wine runs as the owner, which makes the game's menus file dialogs over the owner's home. two bugs worth keeping. the token key is BEARER_TOKEN, not token, so the upgrade 401'd before any rfb byte moved. and the /status health check opened a tcp connection to prove liveness — libvncserver blocks its accept loop peeking for a websocket handshake, so a polled health check filled the backlog and locked out the real viewer. a liveness check must not be indistinguishable from a client; it reads /proc/net/tcp now. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
ae27478a27 |
the platform keeps its own transcript-id mapping, because the sidecar's is invisible to it
The commander block still was not arriving. Not the delivery mechanism this time — the LOOKUP. Building the block needs the transcript id, the platform had only officer's session key, and it asked the sidecar's `state.ts` for the mapping. That map lives in the sidecar's memory; the platform process has its own empty copy of the module, and re-reading the state file from here does not find a live session either. Verified both ways before changing anything. So the platform keeps its own map, filled from the `session:claude` message it already handles — the one moment the mapping is announced. It is not derivable from anything: it is stated once, mid-turn, and whoever needs it either records it as it passes or does without. The delete route had the identical problem for the same reason and now asks the platform's map first, keeping the sidecar lookup as a fallback for a session that predates this process. Third distinct bug today from these two ids, and they are all the same shape: a lookup keyed on one id space against data held in the other, failing silently because both are UUIDs and neither side can tell. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
0bfad0e592 |
deleting a commander ends its session, not just its loop
Its own test caught this too. Delete removed the row and the transcript, and the transcript was BACK a minute later — because the commander's `claude` process was still alive and rewrote it. That happened twice tonight and both times it read as the delete having failed. Killing the loop was never enough: the loop is a grandchild of the session, so ending it leaves the session running, still holding the conversation open and still able to write. So the session is ended first, with `killClaudeSession` — which already existed and does the whole teardown (abort, close input, settle pending plans and questions). It takes officer's session key while this route holds a transcript id, so the map is read backwards through `findSessionKeyByClaudeSession`, which exists for the same reason a refreshed browser holds only the uuid. Ending the session takes its children with it; the pid-based stop still runs afterwards, catching anything that outlived its parent. The response reports `sessionKilled` beside `processesStopped` so the two are distinguishable in a report rather than one number standing for both. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
aad382f4be |
a commander is told where to record itself on a TURN, because the preamble never reaches it
Its own first test caught this: the commander armed a perfectly good watcher, established a baseline correctly, and wrote no loop-pid — so deleting it would have left the loop running. The block was composed into the system preamble, which `createSession` builds ONCE, on a conversation's first turn. For a commander that is exactly the turn where the block cannot exist: no command_hq_sessions row, no transcript id, so `commanderBlock` returns null. Every later turn reuses the session and never rebuilds the preamble. So a commander never received it at all — the "first turn gets no block" limitation I closed with a rule was really "no turn ever gets it". It rides `effectivePrompt` now: the string the model sees, as against `displayText` which the transcript shows. Same seam the background-job dialog already uses for its hidden preamble, so nothing new — the agent gets the paths without them appearing in the conversation. Once per session, on the first turn where the block resolves, and it stays in the conversation's history from then on. `briefedSessions` is in memory, so a restart re-briefs. That is the safe direction: a few hundred tokens on one turn against a commander that was never told and therefore cannot be stopped. The preamble path is removed rather than left dormant — a dead branch that reads as the mechanism is how this went unnoticed in the first place. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
fc8ce04f2b |
the commander's name shows the moment it is typed, not after a refresh
Naming works — confirmed on a live commander, which now carries `{"type":"summary","summary":"Inbox
Summarizer"}` in its transcript. The instrumentation showed exactly the predicted shape: two attempts 2.8
seconds apart, the first on `session:claude` before the transcript file existed and the second on `result`,
which is the one that landed. The retry was the fix; the guess about WHY was right and the evidence was worth
having rather than assuming.
What was left was cosmetic and looked like the same bug: the pane still read "Untitled commander" until a
refresh. It could not have read anything else — the rename lands at the end of the first turn, and this bar
has no fetched title because a brand-new commander has nothing to resume. So it showed the one thing on
screen nobody had chosen, while the chosen name sat in a field two inches above it.
It takes the name from state now, which is where it already was.
Instrumentation removed. It earned its place: three attempts at this bug were reasoned and two of them were
wrong, and the log settled it in one run.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
cb51f35cad |
deleting a conversation forgets what the platform stored about it
Found by a sanity check after two commanders were deleted through the UI: the Command HQ tables cascaded perfectly and four OTHER tables kept a row each, for ever. 24 orphaned rows in chat_session_models, 26 in chat_session_events, against 14 live transcripts. Nothing cascades because there is nothing to cascade FROM. All four are keyed on a transcript id, and a transcript is a file the harness writes — there is no row for a conversation, so the database cannot help and the delete path has to be explicit. It was not. Three of the four are inert: a model, a bell preference, a durable copy of turn output nothing will ask for again. `nudges` is not — it is a SCHEDULE, read by the tick in nudger.ts. A nudge belonging to a deleted conversation is a timer that keeps firing at something that no longer exists. That is what turned this from untidy into worth doing now. deleteClaudeSession returns the IDS it removed rather than a boolean, because a `/clear` chain is several transcripts presenting as one conversation and forgetting the head while orphaning its parts is the same bug at a smaller scale. THE TRAP THAT CHANGE INTRODUCED, caught before shipping: every call site said `if (deleteClaudeSession(...))` and an empty array is TRUTHY in JavaScript, so a delete that found nothing would have reported success. The typecheck was clean — `string[]` is a perfectly good truthy expression. All three sites test `.length` now. Fifth silently-wrong thing today that a typecheck could not see. Cleared the existing orphans with the same function the delete path now uses, after checking the one thing that would have made it wrong: whether any of them belonged to a member, whose transcripts live in a home this scan does not read. There is one account on this machine, so they were all the owner's. Two chat_session_events rows appeared again immediately after, and are not a leak: the durable log is written independently of the transcript — that is what makes turn output survive officer being down — so a session that has just begun legitimately has events before a transcript exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
2bd8701b15 |
a commander runs where the owner chose, and Command HQ stops scanning one folder
Two of the three things the identity change unblocked. THE WORKING DIRECTORY. `resolveChatCwd` forced `getCommandersDir(email)` and ignored `msg.cwd` entirely — every commander shared one empty directory whose only purpose was to BE a cwd, because the cwd was how a commander was recognised. It honours the choice now, resolved through the same `resolveCwd(home, …)` containment the ordinary chat branch uses, so "client-chosen" still cannot mean "anywhere outside the account's tree". No fallback to the old shared folder: the UI will require a directory, and an absent one falls back to the account's home, which is the honest last resort rather than a silent special case. THE LIST. Command HQ found its commanders by scanning that one directory, which would now find only the ones that happen to still live there and silently hide every other. It reads its rows and loads each transcript by id — `loadClaudeSessionSummaryById`, added here — a handful of lookups rather than a directory walk. A row whose transcript is nowhere is treated as absent exactly as a missing file was. `POST /purge` had the same scan and it was the dangerous one: unfiling every commander that chose a different directory, from a housekeeping route, when the rows are what identity now depends on. Three smaller corrections that came with it: - rename and delete passed the commanders directory as their cwd argument. It is documented as a HINT that falls back to locating the transcript anywhere, so they worked — but passing a path we know is usually wrong reads as intent later. They pass `who.home` now. - `POST /command-hq/commanders/new` returned `cwd: getCommandersDir(...)` regardless of where the commander actually ran, and now accepts `cwd` and `name` like the UI will, and reports what it was given. - the router's "Where commanders live" section said every commander shares one directory and that listing is therefore a scan. Both sentences were the design being replaced. `loadClaudeSessionSummaryById` takes its mtime from `listTranscriptsAs` rather than a bare stat: the file may belong to a member, and reading a member's tree needs the as-user path. That is one scoped directory listing per commander — the same call the old whole-folder scan made, once per row instead of once for all, which is the price of letting each choose where it lives. Verified on live data: the existing commander still resolves, with its title and its real updatedAt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
d08ae41f1f |
a commander can be named before it says anything
Claude Code will not accept a name for a new session — the harness names its own from the first prompt — so the platform renames the transcript the moment it exists. The owner names the commander up front, beside choosing its working directory, and never sees the rename happen. It works because of what rename actually writes. `renameClaudeSession` stores a `summary` record, which is what sets `hasExplicitTitle`, and an explicit title is never overwritten — not by the harness's `ai-title`, not by the first-message fallback. So the chosen name wins permanently rather than racing the titling. That property already existed and was documented; nothing needed adding to make it hold. Applied SERVER-side, in `fileAsCommander`, on the `session:claude` that first carries a transcript id. Not by the client, because it must not depend on a browser still being open: the name is chosen before the first message, and losing it to a closed tab would leave a commander called after whatever it happened to say first. `chatIdentity` is exported and reused rather than reconstructed. It decides the home and the OS user, and a rename writes a file as that user — a second copy of that resolution is the kind of thing that works until a member uses it. The wire field is carried on the turn rather than sent afterwards, for the same reason the plan-mode flag is: a brand-new conversation has no live session to configure and no stored row to update, so its first message is the first moment anything can be acted on. UI comes with the directory picker — both are chosen in the same place, and neither is optional. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
75affec091 |
a commander is identified by its row, not by where it lives
Groundwork for choosing a commander's working directory. Identity was the CWD — every commander shared one directory, so the directory was the answer and it needed no query. The moment a commander can choose its own, that test is wrong in BOTH directions: a commander in the platform checkout reads as an ordinary chat, and an ordinary chat in the old shared directory reads as a commander. So identity is now the `command_hq_sessions` row, which is the only thing that survives the cwd being free. The isolation the shared directory provided is no longer carrying anything — the surfaces that needed it now filter explicitly, which is what made this possible. Four surfaces moved, and the shape of the change is the same in each: the transcript scanner stops inferring it and the ROUTE decorates from the rows. - `listClaudeSessions` says nothing about commanders any more. It is synchronous over a directory scan and identity now needs a database read, so `withCommanderFlag` applies it at the caller. - the sessions list, `/chat/live` and `GET /chat/sessions/:id` each read `listCommandHqSessionIds` once per request. A set membership test per row rather than a lookup per row: commanders are few, and the alternative turns one list into fifty queries. - `commanderBlock` resolves the row instead of parsing the account out of the path. It needs the email for the record paths, so that is a second read — once per session spawn, beside the affordances and the skills index, which are read there for the same reason. `commanderBlock` had to be hoisted out of `createSession`, which is synchronous, into `spawnClaudeStreaming`, which is async and already holds the account. Passing it in as a parameter rather than making the whole session constructor async. `isCommandersDir` survives but is documented as no longer being the identity test — it remains only for the places that legitimately care about that specific path: creating it for a new OS account, and as the historical home of commanders created before this. A commander mid-first-turn has no row and so reports false for one turn. That is the same turn it must not arm anything on, and it corrects itself the moment it is filed. Verified against real data: a filed commander renders the block, an unknown id and a null id both return null, and the live gate still answers 401. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
cabc4825ef |
a commander never arms on its first turn, and the missing paths are how it knows
The first-turn gap is closed by a rule rather than a mechanism, and the two halves interlock instead of conflicting. A commander cannot be told its record paths on the very first turn: the transcript id is minted as that turn begins, so there is no id to key a path on. That was written up as a limitation. It is not one, because arming on the first turn is not permissible anyway — the first exchange is for agreeing what to watch and what to do about it, and a watcher armed before that agreement is armed on a guess. A wrong condition fails silently in both directions: never fires, or fires constantly, discovered days later. So the absence became the signal, and the block says so: "If you were given no paths above, you ARE on your first turn: that is what their absence means." An agent with no paths is on the turn it must not arm on, and an agent that armed anyway would be unstoppable and undeletable — the same rule reached from the other side. The rule is in both places on purpose. The block, always loaded, carries the instruction and the interlock in four lines. The Commanders skill carries why, at length, for the agent that is about to arm one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
87ff6ed326 |
a commander is told where to record itself, however its loop gets started
The record instruction lived in one place: the preamble the background-job dialog composes. Fine while the dialog was the only way to arm a commander, and wrong for the flow being built — the commander arming itself from the conversation, with the owner never touching the launcher. An agent starting its own background job never sees that preamble, so it would record nothing, and delete would quietly go back to leaving orphaned loops. So the paths are compiled into a commander's session preamble, beside the affordances and the skills index. THE SPLIT, which is the part worth keeping: the METHOD lives in the Commanders skill — read on demand, as long as it needs to be — and the PATHS are compiled in always, because they are a fact about this session that the agent cannot derive. That is exactly the line between a skill and an always-loaded block, and it falls in the same place here as everywhere else. The account is derived from the CWD rather than passed in, because the caller does not have it: the sidecar knows a member's osUser and home, and an owner's turn carries no email at all. A commander's cwd is DATA_PATH/<email>/commanders, so the email is in the path — and it is verified by reconstructing the directory from it, so a coincidentally-shaped path cannot pass. Keyed on the cwd rather than a database lookup, for the same reason every other surface uses isCommandersDir: a session must not be a commander in one place and not another. It also works before the row exists, which a lookup would not — and the first turn is when the row does not exist yet. Stated in the file rather than left to be found: a brand-new commander's FIRST turn gets no block, because the transcript id does not exist until that turn begins. In practice the first turn is the conversation about what to watch and the loop starts on a later one, but a commander that armed itself on its opening message would not have been told where to record. Verified on the three cases: a real commanders cwd renders the block with both paths, an ordinary chat gets null, and a session with no id yet gets null. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
6d6e8a841e |
spawned children are database rows, linked to their commander
The file was doing a job it is not good at. A newline-delimited list appended by a shell cannot express a link, cannot be queried, cannot be updated in place, and cannot hold a fact that arrives later — and a child's cost arrives later, from the child, long after the loop wrote its id. So the file becomes an INBOX and command_hq_spawned becomes the record. The constraint that shapes it: the loop is bash and cannot reach Postgres. Giving it a credential so it could would put an authenticated writer inside a background job, which is worse than the problem. So the loop appends with a shell redirect and the platform ingests — idempotently, on the unique index, which is what makes ingest-on-READ safe. A cron for this would be a moving part that can stop without anybody noticing; the read is the only moment the answer is wanted. What the rows buy that the file cannot: - the link, ENFORCED. onDelete cascade means deleting a commander cannot leave an orphaned child row, which is the reason this became important. - queries. Cost per commander, how many agents a trigger spawned, which are still running. - somewhere for finishedAt, totalUsd and outcome, which the loop cannot know when it appends. totalUsd is NULLABLE and null means unknown, never zero. The children endpoint returns `unknownCost` as a count beside the total, because a commander whose children's costs are unknown must not display a confident total that happens to be too low — that understatement is the whole reason this exists. Delete ingests before reading, so a child appended since the last read is still deleted: the file is allowed to be lossy, the rows are not, but a row never ingested does not exist yet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
b7112f6e5d |
a commander records what it is and what it spawned, so deleting one means it
Without this record a commander cannot be stopped or fully deleted, and the delete route's comment claimed otherwise: "the running background process (if any) dies on its own". It does not. Nothing in that route touched a process, so a deleted commander left its loop running — still polling, still able to fire, still able to spawn a deploying agent, with no chip to stop it from and no row left to disarm. THE RECORD, and why the loop has to write it. Three ways to recover the link were tried and none works: the PROCESS holds nothing (no open transcript descriptor, nothing identifying in its environment — tested); the TRANSCRIPT is indistinguishable, because queue-operation/ai-title/last-prompt look like platform markers and are the harness's own, appearing in every session equally; CONTENT matching finds ordinary chats that quote a procedure as readily as the agent following it. So the loop records, because it is the only party that knows. Two files under DATA_PATH/<email>/commander-state/<session>/: `loop-pid` and `spawned`. The reader is deliberately tolerant — a truncated write or a stray line is dropped, not fatal, because a record that failed closed would make a commander undeletable over one bad line. STOPPING needs no new mechanism, only the pid: descendantPids + SIGTERM from the loop takes the loop and any agent under it, which is exactly what that helper was written for. A commander with no recorded pid stops nothing and SAYS so — the honest answer for one armed before this existed. DELETE now cascades in a deliberate order: stop the processes, then the children's transcripts, then the commander. Stopping first because a live agent writing to a transcript being deleted is a race, and because the loop could otherwise spawn a replacement between the last two steps. It returns counts rather than a bare ok — this is the one irreversible action here. The children's transcripts are deleted with the EXISTING deleteClaudeSession: its cwd argument is documented as "a hint, not an authority", so it locates a child that ran in the platform checkout rather than the commanders directory. No new function. THE CHAIN'S WEAK LINK was that the loop cannot know which commander it belongs to. The paths are now handed to it in the background-job prompt, fetched from a new endpoint because they are rooted in DATA_PATH — a server fact. Paths rather than an upload endpoint on purpose: a shell redirect needs no credential, and a background job has no business holding one. The prompt rule is numbered properly rather than landing on 7.5, and the output rule shifts down one when it is present. Verified both shapes produce consecutive numbers. The manager now exposes claudeSessionId, because a commander is keyed on the TRANSCRIPT id everywhere and officer's own session handle is not interchangeable — that mismatch is what once rendered a working commander as an empty pane. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
bd15a186b5 |
themes: rotate to the one you are wearing, star the ones you like
Four changes for 200+ themes, and one mistake worth recording. ORDERING IS A ROTATION, not a sort. The registry order is the list's only structure — families sit together in it — so lifting the selected theme to the top answers "which am I on" by destroying "what is next to it". Rotating keeps every neighbour and moves the starting point. Both lists use the same `ordered` array, which is the point: "the one below the one I have on" has to mean the same thing in the dropdown and in the ctrl+shift+space browser, or one teaches an order the other contradicts. FAVOURITES are a table, not a JSON column. theme_favorites is a row per star, so a toggle is an INSERT or a DELETE and cannot race with itself; an array in user_settings would be read-modify-written and two tabs would lose one. No foreign key to a theme, because themes are not rows — most are compiled in, the rest are directories discovered at request time — so a star can outlive its theme and the reader intersects with the live registry rather than trusting the table. Favourites-first is a second rotation-preserving pass rather than a filter, so the list can still answer "what else is there". Filtering to favourites only is a separate, explicit toggle. THE INSTRUCTIONS NO LONGER SCROLL AWAY. DropdownMenuContent carried overflow-y-auto itself, so the one line telling you the shortcuts exist was visible for half a second and then gone under two hundred entries — which is the same as not having written it. Header and footer are now siblings of a scroll box instead of passengers in it, and the header names alt+space too. THE MISTAKE: the routes went on /themes first, and that prefix is deliberately UNAUTHENTICATED — the sign-in screen paints in the chosen theme, before any account exists to ask. An anonymous GET answered 500, which was the consequence arriving politely. They now live on /theme-favorites, claimed by the `account` permission, which is core and already owns /user, /dock and /api-keys: a starred theme is the same shape as a dock preference. I then mounted it one line off, in the unprotected block beside the thing I was moving it away from, and caught that by reading rather than by testing. Verified after: /api/theme-favorites is 401 unauthenticated on both verbs, and /api/themes still answers 200 so the login screen keeps its colours. 10 tests on the pure ordering — including the property that makes a rotation a rotation: every adjacency in the original survives it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
a15fadbddc |
27 tests on the file standing between a member and a shell
authorize.ts had none, and its own header is what says why that mattered: every deny path in the platform ends there, and the failure mode of a permissive default is not a bug report, it is someone else's session. It had none for a structural reason rather than an oversight. Every path needed two database calls, and the only file here that mocks officerdb leaks its stub into whatever runs after it — so the obvious approach would have traded one untested file for a flaky suite. So the decisions are split from the fetching. resolveEffectivePermissions, decideApiRequest and decideWsProvider are pure functions of their arguments; the async wrappers keep the role cache, the fail-closed catches and the shape callers use. No behaviour change, and the live gate still answers 401 on file-browser, users and tasks. REAL registry keys throughout, deliberately: a suite built on invented permissions keeps passing after a rename, which is the failure an authorization table can least afford. If a key here disappears this file goes red. Pinned beyond the happy paths — the owner carries no grants to consult; core is write unconditionally; a confined grant is dropped without a Linux user and all three drop together; execution and admin grants in the table are ignored even though no CHECK stops the row existing; an unknown key is ignored without disturbing what is legitimately held; self-service is exact in method AND path; a socket needs no level; an unauthenticated caller is refused every door. Two gaps are stated in the file rather than left to be found: ownerOnly has no declaring permission yet, so testing it would test the fixtures; and the grant cache's contract is a claim about call sites, not logic. Found while writing them: readOnlyWrites paths are relative to the permission's api prefix, and getting that wrong fails as "no permission covers this path" rather than as a level error — a misleading message for a misleading path, now commented at the test that hit it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
0c2ff88c88 |
a commander is a commander wherever it is opened
Fixing a regression I introduced last night. Commander rows in the Live list were changed to open in /chat rather than navigating to Command HQ — right, and it cost the composer its commander controls, because `isCommander` was computed from the ROUTE: `manager.context === 'command-hq'`. So the same commander, rendered on a different screen, silently lost "exit and hand back, then re-arm" — the only fire behaviour a watcher wants, and the one the dialog makes default inside a commander. GET /chat/sessions/:id now reports isCommander, derived from the session's own cwd by the same isCommandersDir already used by the sessions list and /chat/live. The answer travels with the conversation. The composer reads one value, manager.isCommander, true when EITHER source says so — and both are needed. The screen knows when Command HQ starts a commander, before a session or a transcript exists for any route to report on. The session knows once it does, wherever it is opened. Screen-only was this bug; session-only would have broken the brand-new composer, which is where the whole thing starts. Verified on a real commander rather than by reading: 172cdd8c resolves cwd=…/commanders and isCommander=true. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
7d7a80782e |
switch Anthropic accounts from the usage pills
The owner keeps a personal account and a company one and moves between them during a day — by what the work
is, and sometimes because one has hit a limit and the work has to carry on. /login handles ARRIVING at an
account. It could not go back to one, because the credential it overwrote was gone.
ai_provider_usage already answered "which of my accounts has room". This answers what immediately follows:
"then use that one". The chips under the numbers stop selecting whose stats you read and start selecting who
you ARE — which turned out to be the useful half of the same gesture, since reading the other account's
percentages was only ever a prelude to using it.
anthropic_accounts holds each login's OAuth object encrypted, keyed (user_id, account_uuid).
One key per ACCOUNT, not one for the table: encryptSecret('anthropic-account:<uuid>', …), so the secret
store mints a separate key each and one leak is one account. Same reasoning that split VAULT_STORE_KEY into
purposes. The uuid comes from Anthropic and survives a re-login; the email is stable too but is editable at
the provider.
What is stored includes a REFRESH token, deliberately — the access token lives hours and the refresh token
is what makes a switch work a week later. So a row plus its key is thirty days of acting as that account.
That was accepted knowingly; the per-account key narrows it, and refreshExpiresAt is a column so a dead
credential gets purged on read rather than sitting here for ever. An expired one cannot be switched to at
all: reveal returns null, because writing an expired credential would sign the owner out with no message.
Capture happens on login AND on every read of the account list. Without that second one this would know
only about logins that went through this dialog, and an account signed into from a terminal would be
invisible to the switcher — half your accounts missing, silently. The switch also captures the OUTGOING
credential first, or switching away from a terminal login loses it.
.credentials.json is replaced wholesale; .claude.json is PATCHED. The second holds the CLI's entire config
and overwriting it would take out every project entry and preference in it.
Owner only, and the isolation is unchanged: getOwnerHomeDir ignores the email it is passed, so every path
here is the owner's. A member's claude reads their own home and none of this touches it. The earlier claim
in this work that the credential was "machine-wide" was wrong — the owner corrected it. What a switch
actually changes is every claude running AS THE OWNER: terminals, task runners, pipelines, the commander.
The spinner is not decoration. A switch rewrites a file and changes nothing visible, so without it the
honest reading of a click is "nothing happened" and the second click is somebody checking. A running turn
keeps the credential it was spawned with, and the response says so rather than leaving the UI to imply
otherwise.
Verified before shipping: capture records the live account with org, plan and expiry; reveal decrypts
byte-identical to what is on disk; /api/claude-auth/accounts is 401 unauthenticated and 403 for a non-owner.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
8917f36be5 |
/login works in the chat window
Officer authenticates claude with a Claude SUBSCRIPTION over OAuth, and that is a browser round trip: open a URL, authorise, paste a code back. It was the one part of running an agent a browser-only user could not do from the browser — the answer was "open a terminal panel and drive the CLI by hand", which works, and is a strange thing to ask of somebody whose entire session is a web page. It needs no pty. `claude auth login` behaves identically through plain pipes, verified by capturing its raw bytes, so this is an ordinary subprocess with two reads and one write: spawn, read until the URL, wait for the person, write the code to stdin. The parsing is the only non-obvious part. The CLI wraps the URL in an OSC-8 hyperlink escape AND prints it again as visible text, so `https://\S+` returns two URLs concatenated with no separator between them. Stripping the escape wrappers first leaves exactly one. Written against captured bytes rather than against what the terminal appeared to show. Three decisions worth keeping: NOT under /auth. totality.ts exempts that prefix from the permission gate entirely, and correctly — it is where a caller goes to BECOME authenticated. Mounted there, an unauthenticated POST could have started a login as the owner. Verified after moving it: unauthenticated POST /api/claude-auth is 401. On the `chat` grant rather than its own. The pairing is exact: an account that may use the agent must be able to authenticate the agent, and an account that may not has nothing to authenticate. `confined` then carries the rest for free — authorize.ts drops a confined grant for an account with no osUser, which is precisely the account that cannot hold credentials of its own. Nothing Anthropic-shaped is inherited by the child. For the owner those variables point at the local proxy, whose whole job is swapping a shared secret for the owner's bearer token — handing them to a login is how you get a success that authenticates nothing. A member's login runs through setpriv --reset-env as their own Linux user, into their own home, because their turns bill their own subscription and that only holds if the credential is theirs. Pending logins are in memory on purpose: one is worthless once the process holding its PKCE verifier dies, so persisting it would store a row that can only ever be stale. Ten-minute reaper, one per account, and the dialog abandons its own on close so a dismissed dialog does not leave claude parked on a read of stdin. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
ebfa09e067 |
live splits into Agents and Commanders, and the payload says which is which
A commander is a chat by every mechanism it uses, so it turned up in Live beside the conversations somebody is actually having. With one deploy commander that is untidy. With a watcher armed per repo it is a list where the thing you are looking for is outnumbered. Two tabs inside Live, counts always shown. That last part differs from the badge on the Live tab above it, which hides at zero because a standing `0` there says nothing. These two say a lot at zero: `Commanders (0)` is how you find out the watcher is not running, which is usually why you looked. The flag is derived server-side from the cwd, not from a `command_hq_sessions` lookup — every commander shares one directory, so the directory IS the answer, it costs no query, and it is already right during a commander's first turn, before any row exists. It has to be in the payload rather than computed in the panel, and that is the point of the change: the iPhone app swipes between LIVE chats and has no room for tabs. Filtering there needs the server to name them. A deploy commander appearing in that swipe order is precisely what must not happen. A commander row also now opens Command HQ instead of /chat. Same transcript either way, but /chat renders it with nothing that makes it a commander legible — no category, no cost, no watcher state, and no way to disarm it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
af78f0ed51 |
sessions carry isCommander, so the phone can filter what tabs would hide
A commander IS a Claude session and this list reads transcripts from disk, so nothing distinguished the two: commanders appeared in the chat list looking like conversations somebody started and forgot. The flag is in the PAYLOAD rather than in the web UI, and that is the owner's constraint rather than an implementation preference. The iPhone chat app swipes left and right between live chats and has no tabs to hide behind, so it has to filter commanders out of that gesture itself. A flag only the web knew about would fix one surface and leave the other wrong — which is the shape of half the bugs found tonight. Derived from the CWD, not from a join against command_hq_sessions. Every commander a user has shares one directory — getCommandersDir(email), never per-commander and never client-chosen — and this list already reads each session's cwd. So it costs one string comparison, adds no query, and still works for a commander whose database row was lost. Compared after resolve(), because the cwd comes from a transcript rather than from code and records whatever directory the process was actually in. Verified against this host: 8 sessions, 0 flagged, and that is right — the commanders directory exists, no transcript has that cwd, and Command HQ shows 0 commanders. Still to do: the two live tabs in the web list, Agents (n) and Commanders (n), with live counts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8d476129ea |
an answer that goes nowhere now says so, and one that lands says that too
Second half of the AskUserQuestion report: "when I answer, the agent does not react — I see the bubble for a long time and end up sending a message anyway", intermittently and not reproducible. Two different causes, both invisible from the outside. A DROPPED answer was silent at every step. user-instance discarded the boolean, sendFire does nothing when no sidecar is connected, and the lookup returns undefined for both "no such session" and "not yours". So a lost answer and a slow agent looked identical: a card that does not change. It now warns with the reason, and where a session exists it emits an error into the durable log — the same channel a successful answer uses, so a second pane sees it too, rather than confirming to the browser that clicked. A LANDED answer had the opposite problem. The card goes read-only the moment you pick, but `sent` is local and optimistic while `message.output` only arrives once the harness has produced something. In between there is a real gap, and nothing filled it — so an answered card looked exactly like one that had timed out. It now says "Answer sent — waiting for the agent", which makes the two states different without pretending to know when the agent will speak. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
1a215dcfee |
a turn waiting on a person is not a stalled turn
Reported as: leave an AskUserQuestion unanswered for a while and the chat becomes unusable — refresh, send another message, the agent is stuck. armStall knew about compaction and about background tasks but not about a pending gate. Parking on a question or a plan means emitting nothing until somebody answers; that is what parking IS. So the watchdog could not tell it from a wedged turn, and at 10 minutes against gates that wait 20, it always won: 10m the turn is declared dead, isGenerating goes false, an error is emitted, the session is torn down 20m the gate's own timeout would have resolved it truthfully — never reached That left a ten-minute window to answer. Miss it and the card is still on screen with nothing behind it, and clicking an answer does nothing at all: an answer's only receipt is the tool:result the gate emits when it unblocks, and the gate is gone. From the outside that is precisely "unusable, refresh, send another message". A session with an outstanding question or plan is now left alone by the watchdog. Not unbounded — each gate holds its own 20-minute timer and resolves with a sentence written for the agent — and the timer is re-armed on both resolve paths, the answer and the timeout, so a turn that genuinely wedges AFTER a question is still caught. armStall skips itself while any gate remains, so answering one of two questions keeps the reprieve. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
ff7358188d |
sub-agents: a spawn cannot take the last of a window
The failure this prevents is specific — a sub-agent burns the end of a limit window and the session the owner is actually sitting in dies mid-turn, because the credits went somewhere nobody was watching. So it is a condition on spawning rather than a refinement: an endpoint that can start unattended work without checking is wrong from its first call, and the symptom lands on someone else's conversation. Wired into POST /command-hq/commanders/new, which — this is the finding — already IS the spawn mechanism the sub-agents item was asking for. It starts a turn with ws: null, waits only for session:claude, and returns the transcript id, with command_hq_sessions naming, listing and costing it. So "commander or something lighter" answers itself: a commander costs nothing extra and a lighter thing would need its own registry to be visible at all. What is still missing is only the agent-callable surface. Refuses rather than queues or downgrades. Queueing means holding work against a window Officer does not control, and the reset it would wait for is a claim about a shared pool — every claude on the machine spends these, including terminals and pipelines. A refusal naming the window, the percentage and the reset is something a caller can act on now. The floor is 15% and the reasoning is in the file: the interactive failure is not "cannot start a chat", it is "a turn already in flight is cut off", and a turn costs a fraction of a window. Fails OPEN, deliberately. The numbers come from an external endpoint with a credential Officer does not own, so a blip or a signed-out CLI must not stop every spawn on the machine with an error about usage that has nothing to do with usage. The problem is reported so a caller can say "started, but unchecked". Seven tests on the pure rule — tightest window decides rather than the average, no limits allowed rather than blocked, exactly-at-the-ceiling refuses. Verified against the live account, where it correctly refuses right now at Session 90%. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
03abdeb246 |
an Update button, so a server is not a terminal away from current
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> |
||
|
pastilhasandClaude Opus 5
|
d043e6650a |
name a published extension for itself, not "extension.zip"
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> |
||
|
pastilhasandClaude Opus 5
|
cfb2f98ccb |
plugins can ship a browser extension, published unauthenticated
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> |
||
|
pastilhasandClaude Opus 5
|
e44c0c7665 |
the browser relay leaves, and /scrape stops pretending to be it
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> |
||
|
pastilhasandClaude Opus 5
|
0a1f1ce6df |
publish desktop, and stop counting node_modules as a plugin
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> |
||
|
pastilhasandClaude Opus 5
|
fcdbf02649 |
the platform stops knowing what VNC is
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> |
||
|
pastilhasandClaude Opus 5
|
b1a2d67b76 |
plugins: node_modules is not a broken plugin
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> |
||
|
pastilhasandClaude Opus 5
|
4efc2552d0 |
os-deps: a dependency declares who has to be able to run it
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> |
||
|
pastilhasandClaude Opus 5
|
87603b800b |
os-deps: ask the owner's shell where a binary is, instead of guessing directories
`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> |
||
|
pastilhasandClaude Opus 5
|
43aeffd9d3 |
api keys: revoked ones stop filling the screen, and can be forgotten
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> |
||
|
pastilhasandClaude Opus 5
|
10feb76880 |
permissions: a plugin can mark part of its surface owner-only
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> |
||
|
pastilhasandClaude Opus 5
|
da30d1a69e |
plugins: a reinstalled plugin was still being read from the deleted one
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>
|
||
|
pastilhasandClaude Opus 5
|
16dd67a3ca |
plugins: enabling pulls first, so a plugin off for a week comes back current
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> |
||
|
pastilhasandClaude Opus 5
|
287cec39d0 |
plugins: enable, disable, delete — and uninstall is gone
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> |
||
|
pastilhas
|
a6e61d0c26 |
user provisioning: the platform pushes the account list to plugins that declare it
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. |
||
|
pastilhas
|
c336042b12 |
remove a dangling export, and write down the lockfile question
`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. |
||
|
pastilhas
|
21bedf1418 |
npmDependencies in the manifest, installed once for every plugin
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. |
||
|
pastilhas
|
3450f5eb57 |
warn when a plugin's packages would block its own updates
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. |
||
|
pastilhas
|
7e654d75bc |
plugins can declare their own npm packages
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. |