core: split the agent and context builder into packages ...

Agent becomes one class assembled from mixins: runtime (turn lifecycle),
streaming (the turn loop), tools (tool execution), compression (context
gates) and context (tool lists, backend lookup, window). The module-level
helpers and sentinels move to helpers.py.

ContextBuilder splits into helpers (pure truncation/freshness/prompt
blocks) and builder (the class). Both old modules become packages with
the same import surface, so navi.core.agent.Agent and
navi.core.context_builder.ContextBuilder keep working.

Method bodies are unchanged; tests now patch settings/log/should_compress
on the mixin that actually reads them.

core: split the compressor into a package ...

`navi/core/compressor.py` was 1355 lines covering three different jobs:
deciding what a pass summarizes, building and calling the summarizer, and
the retry/truncate/persist wrapper around it. Move each to its own module:

* `compression/partition.py` — pure partitioning and the single
  `_plan_compression` decision shared with `would_compress`;
* `compression/summarize.py` — prompt formatting, the KEYS line, the
  meta-summary and `compress_context`;
* `compression/compressor.py` — `ContextCompressor` and its fallbacks.

`navi/core/compressor.py` stays as a compatibility shim that re-exports the
public surface, so imports elsewhere are untouched. Because each module now
binds its own `settings`, the tests that override settings patch all of them
(and `_meta_summarize`/`compress_context` are patched where they are read,
not on the shim). Adds a regression test for the hard-truncate trim inside a
single oversized turn, which the moved `_split_turn_tail` import silently
broke (ruff F821, no test hit that branch).

memory: fix review findings in unified search ...

- index each compression-dropped turn once: messages and context share
  objects, and earlier drops stay in the display history
- label raw excerpts against facts even when recall asks for scope=raw
- top up short vector results from the lexical index (NULL embeddings)
- count whole content words only and cap query terms at 12
- carry source_session_id on fact hits
- cap injected_chunk_ids at 100 entries
- keep a session delete successful when chunk cleanup fails
- stop logging query text in the memory paths
- stop fabricating similarity scores for recent chunks
- consult session_messages_archive in latest_summary_at

memory: one search across facts, raw history and sketches ...

Compression removes messages from the model's window, not from the
conversation: every compression path now writes the turns it demotes into
`memory_chunks` — verbatim, append-only, with the turn range, timestamps and
breadcrumb keys (the summarizer's `KEYS:` line plus a deterministic extractor,
which also covers the hard-truncate fallback that never sees a summarizer).

`memory_search` is the single read path over the three stores: curated facts
first, then raw excerpts by relevance, then the current session's sketches.
Every hit carries provenance (source, session, turn range, timestamp), and a
raw excerpt that a newer curated fact overrides is labelled outdated rather
than hidden — "we changed our mind, the old value was X" is often the
question. The agent also gets up to two relevant excerpts injected per turn
once the context holds a summary, deduped across turns.

Fixes found by running the pilot against a real database:
- `search_facts` returns ISO-string timestamps while chunks return datetimes;
  the freshness comparison raised TypeError and took the whole search down.
- an existing `memory_chunks` table created without pgvector never gained the
  `embedding` column (CREATE TABLE IF NOT EXISTS does not alter), and the
  INSERT failed on it; the DDL now adds the column, and a database without
  pgvector writes text-only rows found through FTS.

context: price images by area and detect backend-truncated prompts ...

Every window decision priced an inline image at a flat 500 tokens, while a
1024x1024 screenshot costs ~1026 on qwen3.6 and a 2048x2048 one ~4098. The
undercount kept sessions below the 90% trigger; Ollama then silently truncated
the prompt to about half the window (dropping the system prompt), and the
truncated prompt_eval_count was cached as the session baseline, pinning the
estimate at ~50% for good - the session never compressed while the model was
already told the context was full.

- image_tokens.py prices each image from its header (one token per 32x32 px,
  downscaled to <=2048^2, clamped to 256..4096); unreadable headers fall back
  to CONTEXT_IMAGE_TOKENS. Used by both estimators, the delta and
  check_context_size; the per-turn image budget fits images by their own cost.
- A prompt reported far below what was sent is a truncation: it is not cached
  as the baseline, and the post-turn worker compresses regardless of the
  threshold. The session keeps the honest token count.
- The pre-turn gate prices the incoming message and its images, which are not
  in session.context yet.
- The summarizer receives images under a window-scaled budget, and prompts
  carrying images stay out of the calibration fit (their bytes are not in
  chars and would skew it).
- Oversized user messages are capped for the LLM view (at least num_ctx/3),
  so a paste bigger than the window no longer dead-ends a session.
- The in-flight partition also trims by token budget: a gate that fires can
  now actually shrink a turn made of a few huge messages.

sessions: share a chat as a public read-only link ...

A session's owner can hand out one capability link that opens the display
history without an account: no input, no chat list, no artifacts panel.
The token lives in the URL hash, so it never reaches the server in a request
line or a Referer header.

The link is permanent by decision - no expiry, no revoke. Deleting the chat
removes the share row (FK cascade) and closes it, which is the only switch.

Backend: session_shares table (unique token, FK cascade), POST
/sessions/{id}/share issuing the session's one link (owner or admin; a
read-all permission may read another user's chat but not publish it), and
public GET /shared/{token}[/messages] serving display history only, with
session and owner ids left out of the payload.

Webclient: #share=<token> renders a standalone page with the owner's cards,
rating off, interactive UI components filtered out and scroll-up paging; a
share button in the chat header opens a dialog that creates the link.

Also fixes ChatHeader's rename, which called an undefined `api` and failed
silently.

profiles: teach the agent to scout profiles and tools before switching ...

Persona gains a reconnaissance order (list_profiles, then list_tools for the
real toolset, then tool_manual) and the switch-vs-delegate rule: switch when
the task itself is another profile's work, delegate a side piece with
spawn_agent. The profiles block is built in one place and shared with the
admin prompt debug view, and the stale 'next user message' claim is fixed.

list_tools applies the admin-only role gate to an explicitly named profile,
the same one list_profiles uses, so it cannot enumerate hidden profiles.

prompt: give the methodologies catalog its rules in the system prompt

subagents: a stopped run closes the tool it had opened ...

A tool card is drawn from tool_started and only its tool_call closes it.
When the user stopped a run while a sub-agent was mid-tool, the sub-agent
was cancelled, the parent dropped its sink, and the matching tool_call was
never sent — the card spun until the page was reloaded.

The sub-agent now reports its in-flight tool from the CancelledError
handler, and both batch paths (sequential and parallel) drain the sink
after cancelling instead of discarding it, so that event reaches the
client ahead of the parent's synthetic "stopped by the user" result.

The webclient settles anything still pending at stream_end,
stream_stopped and error as a safety net for a lost frame or a dying
server, with a visible "interrupted" note rather than a silent close.

The TUI needs nothing: it renders tool_call as a result panel and carries
no pending state, so it gets the fix through the backend alone.

subagents: a worker persona, a live prompt fallback, and guards that scale ...

- assistant and designer_3d get their own subagent_system_prompt.txt; without
  one a sub-agent ran on the orchestrator's prompt, or since ce55325 on nothing
  but the scope anchor, and rarely finished the step it was given
- build the sub-agent system prompt in one place; the documented fallback to
  profile.system_prompt had become dead code
- the thinking-stall guard killed healthy cloud reasoners at 12k chars after
  13-35s; raise the char bound to 48k, keep the 60s wall, and make both settings
- a 300s run cap cut long ops work in half; raise it to 600s, configurable

sessions: the info dialog shows a pending recall ...

GET /sessions/{id}/info now carries the session's pending recall, and
GET /sessions/{id}/recall answers in one shape ({"recall": {...} | null})
instead of a flat object when found and a wrapper when not. The lookup is a
single indexed row rather than the newest 50 recalls filtered in Python.

compression: keep the last four turns verbatim, not eight ...

Four turns still carry the current task word for word; everything older is
already summarised, so eight bought little and pushed the compression trigger
later than it needed to be.

The mid-turn window is unchanged: it counts messages, not turns, and
max(12, keep_recent*2) still floors at 12. navi_code keeps its own override of
12 turns.

Examples, docs and the two tests that assert the default follow.

compressor: count the context the model is sent, not the history it never sees ...

The session-info modal showed "817 288 / 131 072 (100%)" for a session whose
context held a 1.47 MB code_exec result. The estimate was honest about
session.context, but build() head/tail-truncates every oversized tool/assistant
message to context_message_token_budget before the call, so the model never
received that megabyte.

truncate_oversized() moves the per-build rule to module level (the method now
delegates, behaviour unchanged) so the compressor can price the same view it
will send: compress_and_save_session stores estimate_tokens(truncate_oversized(
new_context)) instead of estimate_tokens(new_context).

Full content stays in stored history — the user still sees it, reloads are
unaffected. Regression test keeps a 1 MB tool result in the context and asserts
the stored count equals the truncated-view estimate and is >10x smaller than
the raw one.

llm: routes that name a host, a backup and a window, and a profile that reads them ...

`llm.json` replaces `OLLAMA_BACKENDS_FILE`. It has targets (host and key
environment variable) and routes, where a route is an ordered chain of
`model @ target` entries, each with its own `context_window` and options. The
`default` route now starts on `glm-5.3-flash:cloud` and backs it with
`qwen3.6:35b-128k` on the home host, both at 131072 tokens, so a failover no
longer changes the budget the compressor and `num_ctx` are accounted against.
Embeddings get their own `embedding` route instead of a pinned host.

The engine classifies a failure (network, quota, auth, server, missing model),
cools that entry and moves the call down the chain; a background probe watches
only degraded targets and lets the next turn return to the primary once it is
healthy — it never interrupts a running turn. A profile joins a route with
`llm_route`, and the loader now actually reads it: `llm_route` and
`context_window` were declared on `AgentProfile` and written into every
`config.json` while the loader skipped both, the same silent no-op that
`is_admin_only` used to be, so every profile ran the legacy model list at the
global window. The writer emits them too, or an admin edit would erase the
route from disk.

The turn's resolved entry travels to the UI: the first chunk is stamped with
model and target, `model_info` carries `fallback` when a backup answered, and
the chat header shows a chip only then. `serving_primary` compares the target
as well as the model name, because a route may run one model on two hosts.
`/health` gains an `llm` block with the active entry, target states and missing
models.

`deploy/ollama/` keeps the local model's definition honest: MTP off (slower at
every context on this host), `presence_penalty 0` (the base model's 1.5 breaks
agentic tool calls), and `num_gpu 40` — Ollama's automatic fit claims a 128k
f16 slot fits and then dies mid-prefill with CUDA OOM; 40 of 42 layers leaves
~400 MiB and decodes at ~77 tok/s, 38 layers collapses to 48, and 39 OOMs.
q8_0 KV measured 37 tok/s against 70 on f16 here, so the cache stays f16.

profiles: the Personal Secretary retires, and every reference goes with it ...

`secretary` had become a second general-purpose assistant: same models, same
tools, one temperature step apart from `assistant`, and admin-only for no
reason the user could see. The directory is gone and the eight remaining
profiles load clean.

A profile that no longer exists is not a harmless orphan — `Agent` resolves
`session.profile_id` on every run and raises `ProfileNotFound`, so any session
left behind would open and then fail on its first turn. Prod sessions were
moved to `assistant` first (115 rows, verified after), and the local clone
along with them (101).

The reaction fallback loses its role table: it existed because the admin
fallback was itself admin-only, which `assistant` never is. `spawn_agent`
falls back to `assistant` too, and the two prompts that recommended
`secretary` now name only `server_admin` and `developer`.

navi: a token count that matches the model, a type for every file, and a socket that admits it is dead ...

Compression decided everything in chars // 3, and on this workload that sits
~1.8x below reality — 101k real prompt tokens against a ~56k estimate — so the
trigger, the target, the truncate budgets and the pre-call size check all ran
in a unit half the size of the real one. TokenCalibration now fits
overhead + chars / chars_per_token per model from the prompt_eval_count that
every call already reports, and a profile declares its own context_window
(sent to Ollama as num_ctx) instead of every model being held to OLLAMA_NUM_CTX.

Superseded summaries were never demoted in the database: save() only updates
flags for rows in session.messages, a summary is is_display=False, so it lived
in session.context alone and every reload resurrected it — prod sessions
carried up to 15 live summaries. PgSessionStore.set_context_flag() writes the
flip for those rows directly.

Five extension tables disagreed about what a file is. navi/content_types.py is
the one detector — signature, then extension, then a text probe — it decides
the MIME the download route serves, and the session file list now carries the
type the viewers branch on.

The idle receive loop answers client pings and sends its own heartbeat. A
half-open socket keeps readyState at OPEN and never fires close, so traffic
coming back is the only proof the connection still works.

mcp: a run says why a server's tools were withheld, instead of silently lacking them ...

A profile can declare a BYOK-gated server the user has no personal key for. The
manager refuses such a call and build_tool_list drops the server, so the tool
list stays honest — but the system prompt kept naming the server with no
explanation at all. The model knew it existed, held none of its tools, and had
nothing to tell the user, who concluded the assistant simply could not do the
task.

The reason was never stored: it is the complement of what visible_servers kept,
so _apply_mcp_scope derives it from that same value (byok_servers() - allowed)
rather than reading the key store a second time and risking a disagreement with
the first read. It rides in current_keyless_mcp_servers, next to the scope
variable, and _mcp_context_msg names each withheld server where it lists it,
followed by the reason and a pointer at Settings -> MCP keys.

Both ContextVar tokens are returned and reset together; without that the two
existing reset sites leak or raise. The variable defaults to empty, so a run
that never set it (a peer run out of a fresh task) claims nothing.

mcp_status said "without one this server runs on the shared default", which is
false for an ordinary account — the shared credential is admin-only.

memory: a fact written under a new spelling of its key merges into the one that survives ...

The extractor invents a key every time it meets the same fact — `language`,
`preferred_language`, `ui_language` — and the upsert keys on the exact string, so
the base grew several spellings of each durable fact. On prod, 24 facts across 11
clusters share a key once noise prefixes are dropped, 10 of them under the exact
same value.

upsert_fact(dedupe=True) now compares the *tokens* of the normalized key — set
equality, not overlap, and never the value: `ui_language` and `language` are one
key while `dark` and `dark_ui` are two. The row already holding the writer's exact
key wins; otherwise the incoming one does. Losers are marked, not deleted: each
keeps its key and its value and gains `merged_into`, so the merge is reversible
with one UPDATE. Off by default, so the memory tool still writes exactly the row
it asked for.

Every read path filters `merged_into IS NULL`, and the mark is reachable only
where it is meant to be — get_all_facts/fact_count gained include_merged, and
GET /admin/memory?include_merged=true exposes it. search_facts deliberately has
no such flag: the injection path must not be able to see a hidden row. Forgetting
a key drops its hidden aliases first, so none is left pointing at nothing.

Three fixes that fell out of the same read:

- expires_at was overwritten with EXCLUDED.expires_at on every upsert, and the
  extractor always passes None — so it silently cleared any expiry the agent had
  set. Both DO UPDATE clauses now COALESCE.
- The ILIKE fallback was the one read path that served expired facts.
- The `list` action promised "all stored facts" and returned categories. The code
  was right and the description was wrong; the description now says so.

The extraction prompt stopped allowing infrastructure — servers, hosts, addresses,
running services — while the agent and the planner already forbade it; that
loophole is where 423 technical facts came from. It also forbids secrets outright,
and asks for stable snake_case keys. Expiry is now documented as being for facts
with a known end, not for facts you merely doubt.

Facts reach the prompt with their age ("updated 34d ago") alongside confidence:
nothing expires on a clock, so the injection says how old a fact is and lets the
agent weigh it.

mcp: every wait on the MCP path gets a bound, and a failed reload keeps what it had ...

reload_tools kept dying on prod, and only a restart cured it. Nothing on the
MCP path was bounded: ClientSession was built without read_timeout_seconds, so
the SDK waited forever (anyio.fail_after(None)); _send awaited a future with no
timeout; disconnect() awaited the shielded runner with no timeout; and
disconnect_all() walks the pool one client at a time, so a single wedged client
blocked every reload that came after it. A cancelled caller only cancelled
itself — the runner stayed wedged, which is why it was every reload, not one.

Bounds, in two deliberate layers. The SDK read timeout ends a request nobody
answers *inside* the runner, so the client stays usable; the caller-side bound
is the backstop for an op queued behind a stuck one, and it aborts the runner
rather than leaving it for the next command to queue behind. connect 60s,
list_tools 45s, call_tool 300s (SDK 240s), session read 30s, disconnect 15s,
each overridable, each logging the culprit.

disconnect() and disconnect_all() no longer swallow CancelledError — that is
exactly how the reload budget stopped being enforceable.

The registry is now rebuilt in one step: collect every server's tools first,
then commit the whole set in a single synchronous swap. clear_external_tools()
ran *before* the rebuild, so a rebuild that failed halfway left the model
holding MCP tool names that resolved to nothing. A failed pass now leaves the
previous registrations untouched, and the reload phase carries its own budget
so the tool always returns a report.

Two more defects fell out of the audit. The streamable_http transport was
handed a bare httpx.AsyncClient, whose 5s default read killed the GET stream of
an idle server — six of the nine prod servers are streamable_http. And
register_mcp_tools called log.warning() in a module where log was never
defined, a NameError on precisely the failure path it was meant to report.

sessions: a pasted image lands in the session directory, and the notice says where ...

An image pasted into the chat lived only in the transcript. The system prompt of
every session names `session_files/<id>/` as the place its files live, so an agent
looking for "the attached images" went there, found nothing, and spent turns on
fruitless `find` calls before giving up.

Now the agent's non-hidden turn writes each pasted image into that directory as
`image_N.<ext>` — the extension sniffed from the bytes, the bytes stored as they
arrived, so a PNG keeps its alpha channel. Numbering runs across the session, and
a picture sent twice reuses the file already holding it.

The paths go into the hidden context copy of the message: images past the context
budget are not sent to the model at all, so the notice names them for `image_view`
instead. The line is written by the agent rather than the websocket handler, which
is the layer that knows the names the files actually took — including for a message
queued behind a running turn.

A save that fails is logged and skipped: it never costs the turn.

synapse: route an event by the role of the account it was delivered for ...

The dispatcher's choice of profile was checked against a hardcoded "user" role,
so an admin's own events could never reach the admin-only profiles their routing
instruction named. The event fell to whichever profile all() happened to yield
first — a profile without the tools the event needed — and the instruction looked
like it did not work. The role now comes from navi_users for the account the event
was delivered for (_user_role, failing closed to "user" and logging), and it is the
role the run carries as current_user_role.

Alongside, in the same path:

- the dispatcher is offered each profile as "id (name) — description", so a rule
  that names a profile in words has something to match it against;
- an unroutable event lands on a role-aware fallback (secretary for an admin,
  assistant otherwise) instead of the first of all(), and every substitution is
  logged as synapse.reaction_profile_downgraded with both ids;
- session_key is folded to one spelling — whitespace collapsed, lowercased — so a
  chat cannot fork on "TG:42" against "tg:42";
- the conversation rule is read from whichever instruction document states it,
  not from the dispatcher one alone.

A refused profile is still refused: hidden stays hidden for everyone, and an
admin-only profile stays out of reach for a regular user's event.

synapse: a reaction continues its conversation, and the request becomes a record ...

Every Synapse event used to open its own service session, so two messages of
one Telegram chat landed in two unrelated chats. The dispatcher now returns a
`session_key` — derived from the payload according to the user's routing
document — and a later event carrying the same key joins the session that
opened it, within `reaction_session_ttl_minutes` of idle time (0 restores the
old always-fresh behaviour). A session that is still running is never joined:
`create_run` overwrites `state.run`, so a second run would orphan the first
one's subscribers — a busy thread gets a fresh session instead. When the
dispatcher names a different profile for the event, the session's profile is
switched through `set_profile`, never through `save()`, which does not rewrite
`name` or `profile_id`: the thread keeps its name and its history.

What the user reads in the transcript is now only the request. The event
record is a system message (`metadata.source == "synapse_event"`) drawn by a
new SynapseEventNotice.vue in the visual language of the recall badge, and the
framing plus the JSON envelope become a hidden user turn written once, on the
first event of a thread — not on every one. The instructions from Settings
reach the model through a new `current_reaction_instructions` ContextVar and
the `[Reaction session]` block of the system prompt, so they appear in no
transcript at all. The stored system record still has to reach the model, so
ContextBuilder's allowlist becomes `_LLM_SYSTEM_SOURCES = {task_note,
synapse_event}`.

The dispatcher gets a document of its own — how to route, rather than what to
do — stored beside the reaction instructions, versioned separately, and edited
in its own field in the settings panel. `synapse_instruction_versions` gains a
`doc` discriminator, so existing rows keep `'reaction'` and their history
verbatim. The new columns are added by `_MIGRATE`, and the index over `doc`
lives there too: `_DDL` runs first, so an index over a column the migration has
not added yet kills the whole batch on an existing database — which is what
the prod database is. A guard test keeps it that way.

Tests: 1776 passed, 1 skipped (backend), 242 passed (webclient, 28 files).

profiles: restricted profiles for ordinary users, and a role gate that holds ...

`is_admin_only` was checked in one place out of nine and was not read from
config.json at all, so all seven profiles were reachable by every account with
role `user`. The flag now lives in config.json — the file is the baseline, a
`profile_overrides` row still wins on top of it — and one predicate,
`admin_only_blocked`, is the single place the rule is expressed. The nine
surfaces that list, switch to, spawn or resolve a profile all consult it:
`POST /sessions`, the WebSocket, switch_profile, list_profiles, the system
prompt's "Available profiles" block, spawn_agent and the Synapse reaction
runner. The prompt cache is now keyed by (profile, role), so a user's prompt
can never be served an admin's profile list.

The seven existing profiles (developer, discuss, dispatcher, modeler_3d,
navi_code, secretary, server_admin) are marked admin-only. Three new ones take
their place for ordinary users: assistant, designer_3d and coder. They share one
native tool set — ssh_exec, peer, reload_tools, create_mcp_server, test_mcp_tool,
image_view and gmail are withheld — and differ only in system prompt, model and
MCP groups. navi-web's raw `request` group, and the whole of gnexus-creds and
tgclient, are withheld too.

MCP per-user keys gain the missing half of the rule: a server that declares a
`user_key` slot is refused to anyone but an admin who has no personal key, and
is left out of their tool list entirely, instead of quietly falling back to the
owner's credential and appearing as a tool that cannot work. The refusal names
the server and points at Settings.

Also closes `GET /agents/prompts`, which served every profile's system prompt to
anyone, with no user dependency at all.

The accepted residual risk is written down in docs/profiles.md: the working
directory is a convention, not a sandbox.

subagents, secrets: an honest result contract, and two leaks closed ...

A pass over the sub-agent system, plus the two findings from the previous one.

Leaks:

- `redact_args` / `is_sensitive_key` (navi/tools/_internal/redact.py) mask
  credential-shaped keys at every log site that prints tool arguments — by key
  name, for all tools, so a future MCP tool is covered without declaring
  anything. ssh_exec passwords were sitting in the prod journal in plaintext.
- `mcp_servers.d/*.json` are tracked in git and carried the scaffolding
  machine's absolute paths, so navi-3d/navi-web silently vanished from the
  toolset off that machine. They now hold project-relative paths, resolved in
  `McpClient.open_transport` — not at load time, because create_mcp_server
  round-trips every config file through save_mcp_servers.

Sub-agent result contract:

- `run_ephemeral` returns a `SubAgentOutcome` (text + status: ok, timeout,
  max_iterations, thinking_stall, user_stop, context_overflow) instead of
  `(text, bool)`. Every exit routes through `SubAgentRunner._finish`, so token
  accounting is never dropped and a partial run always carries a progress
  report — the stop-after-stream path used to return a bare string.
- `spawn_agent` renders its header from the status. Before this, every short
  run reached the parent as "hit iteration limit", and the parent repeats that
  diagnosis to the user — a timeout was reported as an iteration limit.
- `ContextTooLargeError` no longer kills a sub-agent: the parent compresses its
  own context, a sub-agent has no session to compress into, so it stops with
  `context_overflow` and hands back what it did rather than surfacing as
  "Sub-agent failed: …" with the whole run discarded.
- The result is capped at 8000 chars (head and tail kept) so a long run cannot
  flood the parent's context, and tool arguments in the progress report go
  through `redact_args`.
- The navi-3d calling convention left the runner for the server's own tool
  schemas — a generic runner should not know one MCP server's path shapes.
- Validation moved inside spawn_agent's try: a bad argument is a clean
  ToolResult the model can read, not an exception in the parent's loop.

Tests: 1636 passed, 1 skipped. New: SubAgentOutcome paths and headers, result
truncation, context overflow, clean argument failures.

tools, mcp: a description is a hook, not a manual ...

With 24 tools in a profile the schemas are the largest fixed block of every
request, and they are paid for whether or not the tool is called. Eleven of
them carried a manual's worth of prose in their `description` — examples,
error tables, "common mistakes", the mechanics of the file areas. Reading
them against the manuals first, the manuals already held all of it, and
richer: this was duplication sitting in the one place the model cannot avoid
reading, not knowledge that had nowhere else to live. So the descriptions
became selection hooks — what the tool is for, when to pick it over its
neighbour, and the one rule that cannot wait — and the detail moved to
tool_manual("<tool>"), which costs nothing until the tool is actually in
play.

filesystem, spawn_agent, schedule_recall, manage_recall, scratchpad, plan,
share_file, content_publish, reflect, todo and peer. Descriptions drop from
18.4 KB to 11.5 KB, those tools' schemas from 25.5 KB to 16.8 KB, and a
profile's whole native toolset from 38.3 KB to 29.6 KB (server_admin,
developer; secretary 33.7 → 25.0, navi_code 32.9 → 25.9, tool_developer
37.9 → 29.2, modeler_3d 33.4 → 24.8). Stated as a budget rather than a byte
count: roughly 4k tokens of the model's window per request, back.

Two things were deliberately not shortened. The filesystem edit ladder
(`edit` → `edit_lines` → `smart_edit`, last resort, costs an LLM call) and
todo's mandatory `validation` on `done` both exist to prevent an extra
round trip; a shorter description there would trade tokens for turns. What
todo lost is the prose around the rule, not the rule. `enabled.json` was
left alone too: weather, gmail and get_current_datetime are opt-in and the
DB shows 12, 16 and 40 calls, so they are opt-in tools that are actually
used.

peer had no manual at all, which is how this surfaced: its description was
the only documentation the tool had. manuals/peer.md is now written from
the tool and its /peer route — the ask/status/list actions, the fact that
the hive is only a phone book and the question travels peer-to-peer, the
one-concurrent-answer semaphore, the two independent recursion guards, and
the six error codes.

The MCP server instructions leave the system prompt the same way. They were
8 KB of always-present prose per request, most of it workflow detail the
model only needs when it is about to use that server. Each server now
contributes one line — a new optional `summary` field in mcp_servers.d/*.json,
defaulting to the first sentence of its `instructions` — and
tool_manual("<server>") returns the full text plus the tool names the server
declares. server_admin's MCP block goes from 8.3 KB to 1.3 KB, secretary's
from 8.1 to 1.2. tool_manual learned to answer for a server (a tool name
still wins over a server of the same name, and dash/underscore spelling is
tolerated), and the index names the servers alongside the tools.

One judgement call worth recording: gnexus-book's and navi-web's
instructions end in an absolute "NEVER bypass these tools with filesystem,
terminal or code_exec" rule. Moving that on demand would have been a
behavioural regression dressed as a token saving, so those two `summary`
fields carry the prohibition verbatim alongside the hook, and it stays
always visible.

docs/tools.md gains a section on the split (a description is paid for every
request, a manual only when the tool is used), which is where the next
person will look before trimming a description back into a manual.

Full suite green (1577 passed, 1 skipped). No frontend change and no new
dependency, so the deploy is a pull and a restart.

agent: a profile switch now survives the turn that made it ...

switch_profile repoints the session with one narrow UPDATE, and the run's own
save() — which lands right after every tool batch, the switch's own batch
included — wrote its stale in-memory profile back over it. The post-turn
reload then read the row it had just clobbered, saw no change, and left the
turn bound to the old profile's tools: the agent called exactly the tools
switch_profile had just advertised ("Newly available: ssh_exec, terminal, …")
and got "tool not found" for every one of them. Prod shows both halves — the
session that reported two switches kept the profile it started with, and
agent.profile_reloaded appears zero times in the whole boot.

The reload now compares against the profile the run is bound to
(bound_profile_id), which set_profile cannot move, instead of against
session.profile_id, which the store either rewrites or mutates to the new
value — making the old guard false in both branches by construction. And
save() leaves the profile_id column alone on conflict: set_profile owns it
after creation, the same way name/created_at are owned elsewhere.

A tool the live tool_map does not hold is now logged (tool.not_found, with
profile and live tool count). It previously left no trace at all in the
journal, which is why this took a database dig to find.

Three tests, each verified to fail without its fix: the next LLM call is
offered the new profile's tools, save() does not rewrite profile_id, and a
missing tool is logged.

reload: pick up the new code, and drop MCP tools that are gone ...

reload_tools reported success while three separate things kept it from
doing what it says.

The bytecode cache is keyed on (mtime in whole seconds, file size), so a
tool edited to the same length inside the same second as its previous
load re-ran the OLD code — the reload was real, the new version was not
live. The loader now compiles the source itself instead of consulting
__pycache__ (importlib.invalidate_caches() does not help here).

MCP registrations only ever grew: register_mcp_tools called
register_external, and unregister_external was used in one place, so a
server removed from the config or a tool a server stopped exposing
stayed in the registry and failed only when the model called it. Reload
now clears external tools and rebuilds them.

enabled.json naming a tool that failed to load (the gmail/html2text case)
was visible only as a log line. It is now part of the report.

The reload itself moves to navi/core/reload.py, one implementation shared
by the tool and the admin route, so the two cannot leave different
toolsets behind. list_tools.py also read enabled.json through its own
cwd-relative path, which made it disagree with the real toolset, and the
class-based loader rejected execute(self, params, ctx=None) — the shape
every built-in uses.

switch_profile: run the switch alone, then the batch on the new tools ...

A tool called in the same batch as switch_profile was still dispatched against
the old tool_map and died with "tool 'X' not found" — reload_tools did, twice
in one session. The batch is now split: the switch runs first, its
ProfileSwitched event is watched for the target profile, the tools are
re-resolved from it, and the remaining calls run against the new set.

The turn's own profile binding is deliberately left alone — the
end-of-iteration reload in run_stream() is what rebinds profile/llm/schemas,
and pre-setting session.profile_id here would make it skip that step.

Allocate message sequence numbers in the DB, not in memory ...

save() numbered new messages from Session.db_next_sequence, a counter read
when the session was loaded. Any second writer of the same session handed
out the numbers it still believed were free, and the two inserts collided on
UNIQUE(session_id, sequence_number) — in production, when switch_profile
loaded the session mid-run and saved it back. The turn died with
"Internal error: duplicate key value violates unique constraint".

The range is now claimed inside save()'s transaction with a single
UPDATE ... RETURNING, so concurrent writers serialize on the session row,
and GREATEST() seeds the pre-counter sessions whose next_sequence is still 0
instead of relying on a racy max()+1 fallback in memory.

switch_profile itself no longer saves a session at all: it repoints the row
through a narrow set_profile() UPDATE, which keeps it out of the running
turn's way. It runs mid-turn on a session the turn still holds, so saving a
second copy from there was the collision in the first place.

Await the session pool in notify and three neighbours ...

PgSessionStore._get_pool() is async, and four call sites passed its coroutine
straight into a store constructor, so the first query inside died with
"'coroutine' object has no attribute 'fetchrow'": notify always failed, the
reaction runner never got past reading its settings, synapse_instructions was
unusable, and the BYOK resolver caught the AttributeError and silently fell
back to the default credential.

The tests missed it because each one mocked the store or the pool provider
away; the new ones run on a fake asyncpg pool with nothing faked below the tool.