synabun 2.0.0-beta → 2.0.5

package/neural-interface/lib/assistant-api.js

@@ -30,6 +30,8 @@ export const BUDGET_ENFORCEMENT = Object.freeze({
 });
 
 const OWNER_ONLY = { error: 'The assistant is available to the owner only', code: 'GUEST_FORBIDDEN' };
+// What GET /catalog is made from when no catalog builder is wired: one object, so its answer is reused like any build's.
+const NO_CATALOG = Object.freeze({});
 
 function sendError(res, error, fallbackStatus = 500) {
   if (error instanceof DispatchError || (error && error.code && error.status)) {
@@ -119,6 +121,11 @@ export function createAssistantApi({
   // Remote sessions (lib/remote-policy.js): the session's policy, or null. Defaults
   // to the runtime's view, else the process-wide registry.
   sessionPolicy = null,
+  // The user-context engine (assistant-user-context.js) and the project a new conversation starts in.
+  userContext = null,
+  // Why the engine did not start on this server (a string or null), for the settings page.
+  userContextError = () => null,
+  defaultProject = () => 'global',
 } = {}) {
   if (!dispatcher) throw new Error('createAssistantApi requires a dispatcher');
   const router = Router();
@@ -268,22 +275,26 @@ export function createAssistantApi({
   // ── catalog ────────────────────────────────────────────────────────────────
   router.get('/catalog', async (req, res) => {
     try {
-      const force = req.query.refresh === '1';
+      // refresh=1 rebuilds from the providers' endpoints; deep=1 also makes them ask the CLI / app-server again.
+      const deep = req.query.deep === '1';
+      const force = req.query.refresh === '1' || deep;
       // Brain view / search: compact rows (OpenCode can list hundreds of models).
       const view = req.query.view === 'brain' ? 'brain' : req.query.view === 'manage' ? 'manage' : 'full';
       const provider = req.query.provider ? String(req.query.provider) : null;
       const q = req.query.q || req.query.search ? String(req.query.q || req.query.search) : null;
       // The Models manager: every row with hidden: true|false.
-      if (view === 'manage' && catalog?.get) return res.json({ ok: true, ...(await catalog.get({ force, view: 'manage', provider })) });
+      if (view === 'manage' && catalog?.get) return res.json({ ok: true, ...(await catalog.get({ force, deep, view: 'manage', provider })) });
       if (catalog?.get && (view === 'brain' || provider || q)) {
         let preferences = {};
         try { preferences = configStore?.routing?.().preferences || {}; } catch {}
-        const brief = await catalog.get({ force, view: 'brain', provider, q, preferences });
+        const brief = await catalog.get({ force, deep, view: 'brain', provider, q, preferences });
         return res.json({ ok: true, generatedAt: new Date(now()).toISOString(), ...brief, limits: dispatcher.limits, runs: dispatcher.list({ activeOnly: true }), totals: dispatcher.totals() });
       }
-      // Reuse only while the catalog underneath is the same build (invalidate() drops it).
-      if (!force && catalogCache && now() - catalogCache.at < 30_000 && (!catalog?.peek || catalog.peek() === catalogCache.base)) return res.json(catalogCache.value);
-      const base = typeof buildCatalog === 'function' ? await buildCatalog({ force }) : {};
+      // The catalog says how long one of its builds is good for (one without a verified list is redone
+      // within seconds), so it is asked every time: this answer is reused only while it hands back the
+      // build the answer was made from (a rebuild or invalidate() gives another one).
+      const base = typeof buildCatalog === 'function' ? await buildCatalog({ force, deep }) : NO_CATALOG;
+      if (!force && catalogCache && catalogCache.base === base && now() - catalogCache.at < 30_000) return res.json(catalogCache.value);
       // Hidden rows stay server-side (view=manage lists them); the lists themselves ship.
       const { hiddenRows: _hiddenRows, ...visible } = base || {};
       const value = {
@@ -470,6 +481,41 @@ export function createAssistantApi({
       bounds: { minUsd: BUDGET_MIN_USD, maxUsd: BUDGET_MAX_USD }, session, pricing: pricingStatus, enforcement: BUDGET_ENFORCEMENT,
     };
   }
+  // ── User context (Settings → Automation behavior): the three layers and what a new conversation is told ──
+  function userContextPayload(req) {
+    let fallback = 'global';
+    try { fallback = String(defaultProject() || 'global'); } catch { fallback = 'global'; }
+    const project = String(req.query?.project || '').trim().slice(0, 200) || fallback;
+    return { ok: true, settings: configStore.userContext(), capabilities: userContext.capabilities(), preview: userContext.preview({ project }) };
+  }
+  const userContextReady = (res) => {
+    if (userContext && configStore?.userContext) return true;
+    let reason = null;
+    try { reason = typeof userContextError === 'function' ? userContextError() : userContextError; } catch { reason = null; }
+    res.status(503).json({ ok: false, code: 'USER_CONTEXT_UNAVAILABLE', error: 'User context is not available on this server', reason: reason ? String(reason).slice(0, 300) : null });
+    return false;
+  };
+  router.get('/user-context', (req, res) => {
+    if (!userContextReady(res)) return;
+    try { res.json(userContextPayload(req)); } catch (error) { sendError(res, error); }
+  });
+  router.put('/user-context', (req, res) => {
+    if (!userContextReady(res)) return;
+    if (!configStore.patchUserContext) return res.status(503).json({ ok: false, code: 'CONFIG_UNAVAILABLE', error: 'User context settings are read-only' });
+    if (callerContext(req).kind !== 'ui') return res.status(403).json({ ok: false, code: 'UI_ONLY', error: 'User context settings are changed from Settings only.' });
+    try {
+      const body = req.body || {};
+      const { project: _project, ...patch } = body.settings && typeof body.settings === 'object' ? body.settings : body;
+      configStore.patchUserContext(patch);
+      // Read live by the engine: the next turn (and the next brain start) follows it.
+      broadcastSync({ type: 'assistant:user-context-changed', settings: configStore.userContext() });
+      res.json(userContextPayload(req));
+    } catch (error) {
+      if (error?.code === 'USER_CONTEXT_INVALID') return res.status(400).json({ ok: false, code: error.code, error: error.message, message: error.message, field: error.field || null });
+      sendError(res, error, 400);
+    }
+  });
+
   router.get('/budget', (req, res) => {
     if (!configStore?.budget) return res.status(503).json({ ok: false, code: 'CONFIG_UNAVAILABLE', error: 'Budget settings are not available' });
     try { res.json(budgetPayload(req.query.sessionId || null)); } catch (error) { sendError(res, error); }
@@ -779,6 +825,12 @@ export function createAssistantApi({
   router.post('/runs/:runId/complete', orchestrationGuard, (req, res) => {
     try { res.json(dispatcher.complete(req.params.runId)); } catch (error) { sendError(res, error); }
   });
+  // The user closed the sidepanel tab of a worker that finished its task: completed, never "stopped
+  // by the user" (409 RUN_NOT_FINISHED for any other run, which the tab then stops as before).
+  router.post('/runs/:runId/tab-closed', (req, res) => {
+    if (callerContext(req).kind !== 'ui') return res.status(403).json({ ok: false, code: 'UI_ONLY', error: 'Only the sidepanel that closed the tab reports it.' });
+    try { res.json(dispatcher.completeClosedTab(req.params.runId)); } catch (error) { sendError(res, error); }
+  });
   router.post('/runs/:runId/focus', (req, res) => {
     const run = dispatcher.get(req.params.runId);
     if (!run) return res.status(404).json({ ok: false, code: 'RUN_NOT_FOUND', error: `Unknown run ${req.params.runId}` });
@@ -835,6 +887,10 @@ export function createAssistantApi({
     if (req.body && 'computerUse' in req.body && (req.get('x-synabun-terminal') || req.get('x-synabun-desktop-grant'))) {
       return res.status(403).json({ ok: false, code: 'UI_ONLY', error: 'Only the user can switch computer use on or off.' });
     }
+    // Test density is the user's setting too: an agent cannot raise or lower it.
+    if (req.body && 'testDensity' in req.body && (req.get('x-synabun-terminal') || req.get('x-synabun-desktop-grant'))) {
+      return res.status(403).json({ ok: false, code: 'UI_ONLY', error: 'Only the user can change the Test density.' });
+    }
     try {
       const session = await runtime.updateSession(req.params.id, req.body || {});
       if (!session) return res.status(404).json({ ok: false, code: 'SESSION_NOT_FOUND', error: `Unknown assistant session ${req.params.id}` });

package/neural-interface/lib/assistant-brains/claude.js

@@ -125,9 +125,13 @@ export function createClaudeBrain({ session, sink, deps = {}, persona = '', hook
     // prompt-submit.mjs steps aside (it injected every memory twice and paid Jev
     // twice) and stop.mjs skips the claim check (a relayed worker "tests pass"
     // has its evidence in the worker's turn, not here). Hooks read it from env.
+    // SYNABUN_ASSISTANT_THREADS: the user-context engine keeps this conversation's
+    // thread record (its nudges layer is on), so pre-compact.mjs asks for no
+    // conversation memory of its own.
     env: {
       ...(typeof deps.claudeAccountEnv === 'function' ? deps.claudeAccountEnv(brain.accountId) : {}),
       SYNABUN_ASSISTANT_SESSION: String(session.id),
+      ...(deps.userContextThreads === true ? { SYNABUN_ASSISTANT_THREADS: '1' } : {}),
     },
     maxBudgetUsd: Number(deps.maxBudgetUsd) > 0 ? Number(deps.maxBudgetUsd) : undefined,
   });

package/neural-interface/lib/assistant-catalog.js

@@ -15,6 +15,13 @@
 // planner) and the router can pick cheap-first, send image work to a model that
 // can see, and image / video creation to a model that makes them. Everything
 // I/O is injected; parsers are pure.
+//
+// Which models exist is never decided here. Each provider's rows are the list
+// its own model selector reads (/api/claude/models, /api/codex/models,
+// /api/opencode/providers/full); the static tables (prices, tier hints, the 1M
+// rule) only describe a row. A model the provider lists and no table knows is
+// offered with what is unknown left unknown; a model only a table knows is
+// never offered. `sources` says how each provider's list was obtained.
 
 import { sortEfforts, variantNames } from './effort-levels.js';
 import { listPrice } from './assistant-pricing.js';
@@ -82,6 +89,43 @@ function resolvedKey(row) {
   return `${baseModelId(row.upstream)}${contextSuffix(row.id)}`.toLowerCase();
 }
 
+// ── moving aliases ───────────────────────────────────────────────────────────
+// "opus", "haiku", "default" name whatever model Claude Code points them at, and
+// that changes with a CLI update. A hidden alias is pinned to the model it named
+// when it was hidden (lib/assistant-hidden-models.js); these say what a row names.
+
+/** A model id without its snapshot date ("claude-haiku-4-5-20251001", "…@20251001"), lower-case: what makes two ids one model. */
+export function modelIdentity(id) {
+  return baseModelId(id).trim().toLowerCase().replace(/[-@]\d{8}$/, '');
+}
+
+/**
+ * What a moving alias row names right now: { model, variant } ("opus[1m]" →
+ * { model: 'claude-opus-5-5', variant: '1m' }), lower-case. null for a row that
+ * is its own model (a concrete id, every Codex row), for OpenCode (its
+ * `upstream` is the provider, not a model) and whenever the provider did not
+ * name a versioned model behind the alias (the static stand-in list, an alias
+ * resolving to another alias): nothing is guessed.
+ */
+export function aliasTargetOf(row) {
+  if (!row?.id || row.provider === 'opencode' || String(row.id).includes('/')) return null;
+  const model = baseModelId(row.upstream || '').trim().toLowerCase();
+  if (!model || !/\d/.test(model) || modelIdentity(model) === modelIdentity(row.id)) return null;
+  return { model, variant: contextVariantOf(row.id) };
+}
+
+/** The id of the model a pin or an alias target names, context included ("claude-opus-5-5[1m]"), lower-case. */
+export function pinnedModelId(pin) {
+  const model = baseModelId(pin?.model || '').trim().toLowerCase();
+  return model ? `${model}${pin.variant ? `[${String(pin.variant).toLowerCase()}]` : ''}` : '';
+}
+
+/** Do a pin and an alias target name the same model at the same context window? (A new snapshot date is the same model.) */
+export function sameModelPin(a, b) {
+  return !!a && !!b && !!modelIdentity(a.model) && modelIdentity(a.model) === modelIdentity(b.model)
+    && String(a.variant || '').toLowerCase() === String(b.variant || '').toLowerCase();
+}
+
 /**
  * Every Claude row that can run at 1M gets a "[1m]" sibling right after it,
  * unless the CLI already lists one: the CLI accepts "<id>[1m]" for those
@@ -305,6 +349,9 @@ export function rowIsHidden(catalog, row) {
  * "opus[1m]"). Context variants hide independently: hiding "opus" leaves
  * "opus[1m]" alone and the other way round; same for "gpt-x" / "gpt-x[extended]".
  * OpenCode: the full "provider/model" id, or a bare model id.
+ * An entry with a pin record (catalog.hiddenPins: an alias hidden as the model
+ * it named, or that model's own id once the alias moved on) hides its own row
+ * only: it never reaches another alias through the resolved model.
  */
 export function hiddenModelId(catalog, provider, id, { row = null } = {}) {
   if (!provider || !id) return null;
@@ -322,7 +369,8 @@ export function hiddenModelId(catalog, provider, id, { row = null } = {}) {
     .find((r) => String(r?.id || '').toLowerCase() === want);
   const resolved = resolvedKey(own);
   if (!resolved || resolved === want) return null;
-  return hidden.find((h) => String(h).toLowerCase() === resolved) || null;
+  const pins = catalog?.hiddenPins?.[provider] || null;
+  return hidden.find((h) => String(h).toLowerCase() === resolved && !pins?.[resolved]) || null;
 }
 
 /**
@@ -442,7 +490,9 @@ function ctxText(ctx) {
 
 /** One routing-sheet line: `id · tier · $in/$out · vision · image-out · video-out · ctx · efforts`. */
 export function formatModelLine(row) {
-  const parts = [row.id, row.tier || '?', priceText(row.price, row.listPrice)];
+  // Only Codex bills a plan; any other row without a price is a model no table prices yet.
+  const planBilled = row.provider === 'codex' || !!row.listPrice;
+  const parts = [row.id, row.tier || '?', row.price || planBilled ? priceText(row.price, row.listPrice) : 'price unknown'];
   if (row.vision) parts.push('vision');
   if (rowMakes(row, 'image')) parts.push('image-out');
   if (rowMakes(row, 'video')) parts.push('video-out');
@@ -549,6 +599,12 @@ export function compactRow(row) {
  * @param {()=>object} [deps.readFilter]   → { opencode:[globs] } (routing.catalogFilter)
  * @param {()=>object} [deps.readHidden] → { 'claude-code': [], codex: [], opencode: [] } ids the user
  *   hid (Assistant → Models; OpenCode's list is Settings → OpenCode's). A bare array = OpenCode ids.
+ * @param {(args:{provider:string, rows:object[], source:string})=>{ids:string[], pins:object}|null} [deps.reconcileHidden]
+ *   settles a provider's hidden list against the rows just listed (hidden aliases are pinned to a model:
+ *   lib/assistant-hidden-models.js `reconcile`); its ids and pins replace readHidden's for that build
+ * @param {(change:{providers:string[], generatedAt:string})=>void} [deps.onChange] a build listed other
+ *   models than the build before it (hiding has its own event and does not count)
+ * @param {number} [deps.retryMs] how soon a build is redone while Claude Code or Codex gave no verified list
  */
 export function createAssistantCatalog({
   fetchJson,
@@ -557,24 +613,53 @@ export function createAssistantCatalog({
   listAccounts = () => ({}),
   readFilter = () => ({}),
   readHidden = () => [],
+  reconcileHidden = null,
+  onChange = null,
   ttlMs = 30_000,
+  retryMs = 5_000,
   now = Date.now,
   log = () => {},
 } = {}) {
   if (typeof fetchJson !== 'function') throw new Error('createAssistantCatalog requires fetchJson');
   let cache = null;
   let inflight = null;
+  // The last verified list Claude Code and Codex gave: what their rows are built
+  // from while the provider does not answer, or answers with its static stand-in.
+  const lastLive = {};
+  let degradedBuilds = 0;
+  let epoch = 0; // bumped by invalidate(): a build that began before it is not kept
+  let lastListed = null; // provider → signature of the rows the last build listed
+
+  const pickArray = (value, keys = []) => {
+    if (Array.isArray(value)) return value;
+    for (const key of keys) if (Array.isArray(value?.[key])) return value[key];
+    return [];
+  };
 
-  async function build() {
+  /**
+   * One provider's answer → the list to build rows from and how it was obtained:
+   * 'live' (the provider answered), 'stale' (it did not: its last verified list),
+   * 'fallback' (never verified: the endpoint's static stand-in), 'unavailable'.
+   */
+  function settle(provider, payload) {
+    const list = pickArray(payload, ['models']);
+    const verified = !!payload && payload.ok !== false && payload.source !== 'fallback' && list.length > 0;
+    if (verified) { lastLive[provider] = list; return { list, state: 'live' }; }
+    if (lastLive[provider]) return { list: lastLive[provider], state: 'stale' };
+    return list.length ? { list, state: 'fallback' } : { list: [], state: 'unavailable' };
+  }
+
+  function listedSignature(rows) {
+    return JSON.stringify(arr(rows).map((row) => [row.id, row.label, row.upstream || '', row.status || '', row.contextWindow || 0, arr(row.efforts).join(',')]));
+  }
+
+  async function build({ deep = false } = {}) {
+    // `deep` also drops the providers' own discovery caches (a CLI or app-server round trip).
+    const fresh = deep ? '?refresh=1' : '';
     const [claudeModels, codexModels, opencodeProviders, projects, mcpProfile] = await Promise.all([
-      fetchJson('/api/claude/models'), fetchJson('/api/codex/models'), fetchJson('/api/opencode/providers/full'),
+      fetchJson(`/api/claude/models${fresh}`), fetchJson(`/api/codex/models${fresh}`), fetchJson('/api/opencode/providers/full'),
       fetchJson('/api/projects'), fetchJson('/api/mcp/profile'),
     ]);
-    const pickArray = (value, keys = []) => {
-      if (Array.isArray(value)) return value;
-      for (const key of keys) if (Array.isArray(value?.[key])) return value[key];
-      return [];
-    };
     const filter = (() => { try { return readFilter() || {}; } catch { return {}; } })();
     const presets = mcpProfile?.presets && typeof mcpProfile.presets === 'object'
       ? Object.entries(mcpProfile.presets).map(([name, preset]) => ({ name, label: preset?.label || name, groups: preset?.groups || [], tools: preset?.tools || null }))
@@ -590,12 +675,34 @@ export function createAssistantCatalog({
       if (Array.isArray(raw)) raw = { opencode: raw };
       return Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, arr(raw[p]).map(String)]));
     })();
+    const claude = settle('claude-code', claudeModels);
+    const codex = settle('codex', codexModels);
+    // OpenCode is read from its serve on every build; while it is down its models are unknown, not remembered.
+    const sources = {
+      'claude-code': claude.state,
+      codex: codex.state,
+      opencode: opencodeProviders && opencodeProviders.ok !== false ? 'live' : 'unavailable',
+    };
+    for (const p of ['claude-code', 'codex']) if (sources[p] !== 'live') log('catalog:source', `${p}: ${sources[p]}`);
     const all = {
-      'claude-code': withClaudeContextVariants(normalizeClaudeRows(pickArray(claudeModels, ['models']), { pricing: claudePricing })),
-      codex: normalizeCodexRows(pickArray(codexModels, ['models']), { priceOf: codexPrice }),
+      'claude-code': withClaudeContextVariants(normalizeClaudeRows(claude.list, { pricing: claudePricing })),
+      codex: normalizeCodexRows(codex.list, { priceOf: codexPrice }),
       opencode: parseOpenCodeProviders(opencodeProviders, { filter: filter.opencode || null }),
     };
-    const lookup = { hidden };
+    // A hidden alias hides the model it named when it was hidden. With the rows at hand the
+    // store settles that: an alias that moved on is shown again and its old model stays hidden.
+    const hiddenPins = Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, {}]));
+    if (typeof reconcileHidden === 'function') {
+      for (const p of CATALOG_PROVIDERS) {
+        try {
+          const settled = reconcileHidden({ provider: p, rows: all[p], source: sources[p] });
+          if (!settled || !Array.isArray(settled.ids)) continue;
+          hidden[p] = settled.ids.map(String);
+          hiddenPins[p] = settled.pins && typeof settled.pins === 'object' ? settled.pins : {};
+        } catch (error) { log('catalog:hidden-pins-error', `${p}: ${error?.message || String(error)}`); }
+      }
+    }
+    const lookup = { hidden, hiddenPins };
     const models = {};
     const hiddenRows = {};
     const listedCounts = {};
@@ -606,11 +713,20 @@ export function createAssistantCatalog({
       for (const row of all[p]) (hidden[p].length && hiddenModelId(lookup, p, row.id, { row }) ? hiddenRows[p] : models[p]).push(row);
     }
     const opencode = models.opencode;
+    const listedNow = Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, listedSignature(all[p])]));
+    const changed = lastListed ? CATALOG_PROVIDERS.filter((p) => listedNow[p] !== lastListed[p]) : [];
+    lastListed = listedNow;
     return {
       generatedAt: new Date(now()).toISOString(),
+      // Providers whose listed models differ from the build before (not part of the value's meaning: full() reports it).
+      changedProviders: changed,
       models,
       hidden,
+      // provider → { hidden id (lower-case) → { model, variant, label, at, … } }: the entries that hide one row only.
+      hiddenPins,
       hiddenRows,
+      // How each provider's list was obtained: live | stale | fallback | unavailable.
+      sources,
       listed: listedCounts,
       // The provider answered with an authoritative list, even an empty one (OpenCode's `connected`).
       known: { opencode: openCodeConnectedKnown(opencodeProviders) },
@@ -630,28 +746,57 @@ export function createAssistantCatalog({
     };
   }
 
-  async function full({ force = false } = {}) {
-    if (!force && cache && now() - cache.at < ttlMs) return cache.value;
+  /**
+   * `force` rebuilds now from the providers' endpoints (each answers from its own
+   * discovery cache, exactly as it does for its panel's selector); `deep` makes
+   * those endpoints ask the CLI / app-server again as well.
+   */
+  async function full({ force = false, deep = false } = {}) {
+    if (!force && !deep && cache && now() - cache.at < cache.ttl) return cache.value;
     if (inflight) return inflight;
-    inflight = build().then((value) => { cache = { at: now(), value }; return value; }).finally(() => { inflight = null; });
+    const started = epoch;
+    inflight = build({ deep }).then((built) => {
+      const { changedProviders, ...value } = built;
+      // No verified list from Claude Code or Codex: ask again soon, backing off to the
+      // normal lifetime (a provider that is not installed must not be spawned every few seconds).
+      const degraded = ['claude-code', 'codex'].some((p) => value.sources[p] !== 'live');
+      degradedBuilds = degraded ? degradedBuilds + 1 : 0;
+      const ttl = degraded ? Math.min(ttlMs, retryMs * 2 ** (degradedBuilds - 1)) : ttlMs;
+      cache = { at: now(), value, ttl: started === epoch ? ttl : 0 };
+      if (changedProviders.length && typeof onChange === 'function') {
+        try { onChange({ providers: changedProviders, generatedAt: value.generatedAt }); } catch (error) { log('catalog:onchange-error', error?.message || String(error)); }
+      }
+      return value;
+    }).finally(() => { inflight = null; });
     return inflight;
   }
 
-  /** Every row, hidden ones included, per provider (the Models manager, id resolution). */
-  async function manageRows({ force = false } = {}) {
-    const value = await full({ force });
-    return Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, [...arr(value.models?.[p]), ...arr(value.hiddenRows?.[p])]]));
+  /**
+   * Every row, hidden ones included, per provider, and how each provider's list was obtained:
+   * { rows, sources, generatedAt } of one build, so what a row says is never read against another build's source.
+   */
+  async function manageSnapshot({ force = false, deep = false } = {}) {
+    const value = await full({ force, deep });
+    return {
+      rows: Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, [...arr(value.models?.[p]), ...arr(value.hiddenRows?.[p])]])),
+      sources: { ...value.sources },
+      generatedAt: value.generatedAt,
+    };
   }
 
+  /** Every row, hidden ones included, per provider (the Models manager, id resolution). */
+  async function manageRows(options = {}) { return (await manageSnapshot(options)).rows; }
+
   /**
    * view 'full' (default): every visible row. view 'brain': compact rows,
    * OpenCode capped; `provider` + `q` narrow the list (agent_catalog search).
    * view 'manage': every row with hidden: true|false and hiddenBy (the list
    * entry that hides it), plus `archived`: every hidden id per provider with
-   * the rows it covers; listed:false = no current row (still restorable).
+   * the rows it covers; listed:false = no current row (still restorable); `pin`
+   * = the model an alias entry was hidden as (see hiddenPins).
    */
-  async function get({ force = false, view = 'full', provider = null, q = null, brain = null, preferences = {} } = {}) {
-    const value = await full({ force });
+  async function get({ force = false, deep = false, view = 'full', provider = null, q = null, brain = null, preferences = {} } = {}) {
+    const value = await full({ force, deep });
     if (view === 'manage') {
       const models = {};
       const archived = {};
@@ -672,10 +817,11 @@ export function createAssistantCatalog({
         });
         archived[p] = arr(value.hidden?.[p]).map((id) => {
           const covered = covers.get(String(id).toLowerCase()) || [];
-          return { id, listed: covered.length > 0, group: p === 'opencode' ? String(id).split('/')[0] : null, rows: covered };
+          const pin = value.hiddenPins?.[p]?.[String(id).toLowerCase()] || null;
+          return { id, listed: covered.length > 0, group: p === 'opencode' ? String(id).split('/')[0] : null, rows: covered, ...(pin ? { pin } : {}) };
         });
       }
-      return { view: 'manage', generatedAt: value.generatedAt, models, archived, hidden: value.hidden, listed: value.listed };
+      return { view: 'manage', generatedAt: value.generatedAt, models, archived, hidden: value.hidden, hiddenPins: value.hiddenPins, listed: value.listed, sources: value.sources };
     }
     if (view !== 'brain' && !provider && !q) return value;
     const needle = q ? String(q).toLowerCase() : null;
@@ -690,7 +836,7 @@ export function createAssistantCatalog({
       const sheet = selectSheetModels(value, { brain, preferences, max: 40 });
       for (const p of CATALOG_PROVIDERS) models[p] = (p === 'opencode' ? sheet[p] : value.models[p]).map(compactRow);
     }
-    const { opencodeHidden, hidden, hiddenRows, ...rest } = value;
+    const { opencodeHidden, hidden, hiddenPins, hiddenRows, ...rest } = value;
     const hiddenCount = Object.fromEntries(CATALOG_PROVIDERS.map((p) => [p, arr(hiddenRows?.[p]).length]));
     return { ...rest, view: 'brain', models, opencodeTotal: value.opencodeTotal, hiddenCount, opencodeHiddenCount: arr(opencodeHidden).length };
   }
@@ -725,7 +871,13 @@ export function createAssistantCatalog({
     return { vision: row.vision ?? null, tier: row.tier || null, price: row.price || null, label: row.label || row.id, contextWindow: row.contextWindow || null, source: hit?.match || 'default', id: row.id };
   }
 
-  function invalidate() { cache = null; }
+  function invalidate() { cache = null; epoch += 1; }
+  /** A provider's own list changed: drop the copy and build the next one now (onChange reports the difference). */
+  function refresh() {
+    invalidate();
+    const pending = inflight; // began before the change: let it end, then build again
+    return pending ? pending.catch(() => null).then(() => full()) : full();
+  }
 
-  return { get, full, peek, find, hiddenId, manageRows, brainInfo, invalidate };
+  return { get, full, peek, find, hiddenId, manageRows, manageSnapshot, brainInfo, invalidate, refresh };
 }

package/neural-interface/lib/assistant-config.js

@@ -4,7 +4,8 @@
 //
 // The assistant's user-editable knobs live in one JSON file: `defaultBrain`,
 // `persona`, `limits`, `memory` (read by the other assistant modules),
-// `routing` and the budget caps (owned here; see assistant-budget.js). Knobs
+// `routing`, the budget caps (owned here; see assistant-budget.js) and
+// `userContext` (the three layers of assistant-user-context.js). Knobs
 // are data: the file is re-read when its mtime changes, so a PUT from the
 // routes or budget editor, or a hand edit, applies without a restart. Writes
 // are atomic (tmp + rename) and keep every unknown key.
@@ -12,6 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { effectiveBudget, validateBudgetPatch, writeBudgetInto } from './assistant-budget.js';
+import { normalizeUserContext, USER_CONTEXT_DEFAULTS } from './assistant-user-context-budgets.js';
 
 export const ROUTE_MODES = ['always-ask', 'ask-unsure', 'never'];
 export const PREFERENCE_KINDS = ['direct', 'dispatch'];
@@ -145,6 +147,22 @@ export function effectiveRouting(raw = {}) {
   };
 }
 
+export const USER_CONTEXT_KEYS = Object.freeze(Object.keys(USER_CONTEXT_DEFAULTS));
+
+/** A partial `userContext` patch: booleans only, known layers only. */
+export function validateUserContextPatch(patch = {}) {
+  const fail = (field, message) => { const error = new Error(message); error.code = 'USER_CONTEXT_INVALID'; error.field = field; error.status = 400; return error; };
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw fail('userContext', 'userContext must be an object');
+  const out = {};
+  for (const [key, value] of Object.entries(patch)) {
+    if (!USER_CONTEXT_KEYS.includes(key)) throw fail(key, `Unknown userContext setting "${key}"`);
+    if (typeof value !== 'boolean') throw fail(key, `userContext.${key} must be true or false`);
+    out[key] = value;
+  }
+  if (!Object.keys(out).length) throw fail('userContext', `Nothing to change: send one of ${USER_CONTEXT_KEYS.join(', ')}`);
+  return out;
+}
+
 export function createAssistantConfigStore({ path, log = () => {}, now = Date.now } = {}) {
   if (!path) throw new Error('createAssistantConfigStore requires path');
   let cached = null; // { mtimeMs, value }
@@ -224,9 +242,20 @@ export function createAssistantConfigStore({ path, log = () => {}, now = Date.no
     return patchRouting({ preferences: { [key]: value } });
   }
 
+  /** The user-context layers (assistant-user-context.js): knowledge, nudges, trace. All on by default; read live. */
+  function userContext() { return normalizeUserContext(read().userContext); }
+  /** Switch layers (a validated partial patch). Every unknown key of the file is kept. */
+  function patchUserContext(patch = {}) {
+    const clean = validateUserContextPatch(patch);
+    const current = read();
+    const stored = current.userContext && typeof current.userContext === 'object' && !Array.isArray(current.userContext) ? current.userContext : {};
+    write({ ...current, userContext: { ...stored, ...clean, updatedAt: new Date(now()).toISOString() } });
+    return userContext();
+  }
+
   function onChange(fn) { listeners.add(fn); return () => listeners.delete(fn); }
 
-  return { read, routing, version, patchRouting, setPreference, budget, budgetVersion, patchBudget, onChange, path };
+  return { read, routing, version, patchRouting, setPreference, budget, budgetVersion, patchBudget, userContext, patchUserContext, onChange, path };
 }
 
 export function fileExists(path) { try { return existsSync(path); } catch { return false; } }