mixdog 1.3.4 → 1.4.0

package/src/runtime/session-search/session-search-ingest.mjs

@@ -2,19 +2,32 @@
  * Keeps the PG session-search copy (session-search-db.mjs) in step with the
  * session store: per-turn ingest, a once-per-run backfill of stored sessions,
  * and deletion. Everything is best-effort and never touches the memory runtime.
+ *
+ * A session's writes run one at a time, in the order they were issued
+ * (serialized). That order is what keeps a value marked sensitive out of the
+ * index: the replacement that redacts the stored rows
+ * (replaceSessionSearchMessages) locks only rows that already exist, so an
+ * earlier plaintext append still in flight would otherwise land after it and
+ * bring the value back. A write also redacts with the values known when it
+ * runs, not when it was issued.
  */
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { isAgentOnlySession } from '../agent/orchestrator/session/store-summary-visibility.mjs';
+import { redactSensitiveText, sensitiveValuesVersion } from '../agent/orchestrator/session/sensitive-values.mjs';
+import { redactSensitiveMessages } from '../agent/orchestrator/session/sensitive-projection.mjs';
 import {
   appendSessionSearchMessages,
   deleteSessionSearchMessages,
   readSessionSearchBackfillStamps,
   readSessionSearchSessionIds,
   recordSessionSearchBackfillStamp,
+  replaceSessionSearchMessages,
 } from './session-search-db.mjs';
 
-const lastIngestedLength = new Map();
+/** sessionId → { length, version }: the transcript length and the
+ *  sensitive-values version (sensitive-values.mjs) of the last stored ingest. */
+const lastIngested = new Map();
 const LAST_INGESTED_LIMIT = 500;
 
 function logFailure(what, error) {
@@ -23,6 +36,87 @@ function logFailure(what, error) {
   } catch {}
 }
 
+/** sessionId → { tail, controller }: the tail of the session's write queue
+ *  (see serialized) and the lifetime its writes run under (closeSessionSearch
+ *  aborts it). Present only while a write of the session is queued or running. */
+const writeQueues = new Map();
+
+/** The reason a closed session's writes stop with; never reported as a failure. */
+class SessionSearchClosedError extends Error {
+  constructor(sessionId) {
+    super(`session search writes of ${sessionId} closed`);
+    this.name = 'AbortError';
+  }
+}
+
+const reportUnlessClosed = (what) => (error) => {
+  if (!(error instanceof SessionSearchClosedError)) logFailure(what, error);
+};
+
+/** Runs `task(signal)` once every earlier task of `sessionId` has settled; the
+ *  task's own promise is returned, so its failure reaches the caller to report.
+ *  The queue moves on past a failed task: that failure is the caller's, not the
+ *  next write's. `signal` is the session's write lifetime. */
+function serialized(sessionId, task) {
+  const queue = writeQueues.get(sessionId);
+  const controller = queue && !queue.controller.signal.aborted ? queue.controller : new AbortController();
+  // A write cancelled while queued never starts (rejects with the close reason).
+  const run = (queue?.tail ?? Promise.resolve()).then(() => {
+    controller.signal.throwIfAborted();
+    return task(controller.signal);
+  });
+  const tail = run.then(
+    () => {},
+    () => {}
+  );
+  const entry = { tail, controller };
+  writeQueues.set(sessionId, entry);
+  tail.then(() => {
+    if (writeQueues.get(sessionId) === entry) writeQueues.delete(sessionId);
+  });
+  return run;
+}
+
+/**
+ * Stops the session's search writes for a runtime close: the queued ones never
+ * start and the running one is cancelled — a PostgreSQL runtime install or
+ * start it is waiting on included, once no other writer still waits on it
+ * (createSharedAbortable). Resolves when the queue has settled, so nothing this
+ * session issued writes into the data dir afterwards. The rows are derived:
+ * the stored-session backfill restores what a cancelled write left out.
+ */
+export async function closeSessionSearch(sessionId) {
+  const queue = writeQueues.get(sessionId);
+  if (!queue) return;
+  queue.controller.abort(new SessionSearchClosedError(sessionId));
+  await queue.tail;
+}
+
+/** Stores `messages`, the transcript as it was when the turn was ingested, as
+ *  the session's search rows; runs in the session's write queue. */
+async function storeTranscript(sessionId, messages, signal) {
+  // A turn always grows the transcript; an unchanged length means nothing
+  // new. This is only a shortcut: the insert itself is idempotent.
+  const length = messages.length;
+  const version = sensitiveValuesVersion(sessionId);
+  const last = lastIngested.get(sessionId);
+  if (last?.length === length && last.version === version) return;
+  // A value a sensitive fill marked is stored as a marker here too. While
+  // the session has values not yet applied to its stored rows (rows made
+  // before the mark, compacted ones included), the rows that hold one are
+  // replaced in one transaction instead of only appending.
+  const redacted = redactSensitiveMessages(sessionId, messages);
+  if (version && last?.version !== version) {
+    await replaceSessionSearchMessages(sessionId, messages, redacted, (text) => redactSensitiveText(sessionId, text), {
+      signal,
+    });
+  } else {
+    await appendSessionSearchMessages(sessionId, redacted, { signal });
+  }
+  if (lastIngested.size >= LAST_INGESTED_LIMIT) lastIngested.clear();
+  lastIngested.set(sessionId, { length, version });
+}
+
 /** Fire-and-forget: store a completed turn's transcript. Never throws. */
 export function ingestSessionTurn(session) {
   try {
@@ -30,30 +124,24 @@ export function ingestSessionTurn(session) {
     const messages = session?.messages;
     if (!sessionId || !Array.isArray(messages) || messages.length === 0) return;
     if (isAgentOnlySession(session)) return;
-    // A turn always grows the transcript; an unchanged length means nothing
-    // new. This is only a shortcut: the insert itself is idempotent.
-    const length = messages.length;
-    if (lastIngestedLength.get(sessionId) === length) return;
-    appendSessionSearchMessages(sessionId, messages).then(
-      () => {
-        if (lastIngestedLength.size >= LAST_INGESTED_LIMIT) lastIngestedLength.clear();
-        lastIngestedLength.set(sessionId, length);
-      },
-      (error) => logFailure(`ingest ${sessionId}`, error)
+    // The write runs after the session's earlier ones, so it keeps the
+    // transcript of this call: compaction may rewrite the live array before then.
+    const transcript = messages.slice();
+    serialized(sessionId, (signal) => storeTranscript(sessionId, transcript, signal)).catch(
+      reportUnlessClosed(`ingest ${sessionId}`)
     );
   } catch (error) {
     logFailure('ingest', error);
   }
 }
 
-/** Best-effort removal of a deleted session's search rows. Never throws. */
+/** Best-effort removal of a deleted session's search rows, after the
+ *  session's pending writes. Never throws. */
 export async function forgetSessionSearch(sessionId) {
-  lastIngestedLength.delete(sessionId);
-  try {
-    await deleteSessionSearchMessages(sessionId);
-  } catch (error) {
-    logFailure(`delete ${sessionId}`, error);
-  }
+  await serialized(sessionId, async (signal) => {
+    lastIngested.delete(sessionId);
+    await deleteSessionSearchMessages(sessionId, { signal });
+  }).catch(reportUnlessClosed(`delete ${sessionId}`));
 }
 
 async function loadStoreDeps() {
@@ -89,8 +177,10 @@ export async function backfillSessionSearch({ deps } = {}) {
       if (stamps.get(sessionId) === stamp) continue;
       const session = readSession(dir, file);
       if (session?.id && !isAgentOnlySession(session)) {
-        await appendSessionSearchMessages(session.id, session.messages);
-        await recordSessionSearchBackfillStamp(session.id, stamp);
+        await serialized(session.id, async () => {
+          await appendSessionSearchMessages(session.id, redactSensitiveMessages(session.id, session.messages));
+          await recordSessionSearchBackfillStamp(session.id, stamp);
+        });
         ingested += 1;
       }
     } catch (error) {

package/src/runtime/shared/abort-race.mjs

@@ -50,6 +50,95 @@ export async function runAbortable(signal, task, fallback) {
   });
 }
 
+/** Resolves after `ms`, or rejects with the abort reason once `signal` aborts. */
+export function sleepUnlessAborted(ms, signal) {
+  if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) return reject(abortReason(signal));
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * One operation that several callers await. `start(signal)` runs once, when
+ * the first caller that still wants it joins — a live signal, or none — so a
+ * caller that is already aborted starts nothing. Its signal aborts only when
+ * every caller that joined with a signal has aborted and no caller joined
+ * without one (such a caller keeps it running). The caller whose abort cancels
+ * the work waits for the work to settle, its cleanup included, so nothing it
+ * started outlives it; any other aborted caller stops waiting at once and
+ * leaves the work to the callers still on it. `onSettled(failed)` runs once
+ * the started work settles; `promise` is that work, null until started.
+ */
+export function createSharedAbortable(start, { onSettled = null } = {}) {
+  const controller = new AbortController();
+  let waiting = 0;
+  let pinned = false;
+  let promise = null;
+  const begin = () => {
+    if (!promise) {
+      promise = Promise.resolve().then(() => start(controller.signal));
+      promise.then(
+        () => onSettled?.(false),
+        () => onSettled?.(true)
+      );
+    }
+    return promise;
+  };
+  return {
+    get promise() {
+      return promise;
+    },
+    join(signal) {
+      if (!signal) {
+        pinned = true;
+        return begin();
+      }
+      if (signal.aborted) return Promise.reject(abortReason(signal));
+      waiting += 1;
+      const work = begin();
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          waiting -= 1;
+          const reason = abortReason(signal);
+          if (waiting > 0 || pinned) {
+            reject(reason);
+            return;
+          }
+          controller.abort(reason);
+          work.then(
+            () => reject(reason),
+            () => reject(reason)
+          );
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then(
+          (value) => {
+            if (signal.aborted) return;
+            signal.removeEventListener('abort', onAbort);
+            waiting -= 1;
+            resolve(value);
+          },
+          (error) => {
+            if (signal.aborted) return;
+            signal.removeEventListener('abort', onAbort);
+            waiting -= 1;
+            reject(error);
+          }
+        );
+      });
+    },
+  };
+}
+
 /**
  * Bound best-effort cleanup without cancelling the underlying work. The
  * detached promise remains observed and may still finish in the background.

package/src/runtime/shared/agent-avatar.d.mts

@@ -42,7 +42,6 @@ export const MASCOT_EXPRESSIONS: readonly string[];
 export const MASCOT_INKS: Readonly<Record<string, string>>;
 export const MIXY_AVATAR: Readonly<MascotAvatar>;
 export const AGENT_AVATAR_STATES: readonly AgentAvatarState[];
-export const AGENT_AVATAR_LATER_STATES: readonly string[];
 export const AGENT_AVATAR_IMAGE_FILE: RegExp;
 export const AGENT_AVATAR_STATE_FILE: RegExp;
 export const AGENT_AVATAR_DIR: string;

package/src/runtime/shared/agent-kind.mjs

@@ -45,8 +45,10 @@ const homeEvidenceCache = new Map();
 
 /** What `agentId`'s home thread (sessions/sess_home_<id>.json) holds:
  *  whether it exists, whether it has the creation greeting, and whether the
- *  user and the agent talked (any user message that is not a runtime turn,
- *  or any assistant message). A missing or unreadable file holds nothing. */
+ *  user talked in it: a message the user wrote (a user message that is not a
+ *  runtime turn or the greeting). The agent's own messages never count: Mixy's
+ *  heartbeat posts its reports there unasked. A missing or unreadable file
+ *  holds nothing. */
 export function homeThreadEvidence(dataDir, agentId) {
   const sessionId = agentHomeSessionId(agentId);
   if (!dataDir || !sessionId) return NO_HOME;
@@ -69,7 +71,6 @@ export function homeThreadEvidence(dataDir, agentId) {
   let greeted = false;
   let chatted = false;
   for (const message of messages) {
-    if (message?.role === 'assistant') chatted = true;
     if (message?.role !== 'user') continue;
     const text = messageText(message.content);
     if (CREATION_GREETING.test(text)) greeted = true;

package/src/runtime/shared/bot-hops.mjs

@@ -20,16 +20,76 @@ export const hopOf = (value) => (Number.isInteger(value) && value > 0 ? value :
  *  depth: bot-descended work resumes where it was, independent work at 0. */
 export const sendDepth = ({ hop, target } = {}) => Math.max(0, hopOf(hop) - (target === 'session' ? 1 : 0));
 
-/** Stamp the hop of the submission that starts the turn (else 0) on `session`. */
+// The bots of a chain (`botChain`): the agent ids that handed the work on,
+// oldest first, the sender last. A bot's send carries the chain of its turn
+// plus itself in the transcript meta of the message it delivers (like `hop`);
+// the turn that message starts or joins is in that chain (`turnBotChain`), and
+// a send or spawn from it may never reach a bot already in it, nor itself
+// (assertBotChainTarget). A turn the user, a routine or a notification
+// started begins a chain of its own.
+export const botChainOf = (value) =>
+  Array.isArray(value) ? [...new Set(value.filter((id) => typeof id === 'string' && id))] : [];
+
+// The chain of a submission the runtime takes without transcript meta of its
+// own (a group-room member's turn, submitted by the desktop room host under
+// the send's submission id), recorded by the sender before it is submitted.
+const chainsBySubmission = new Map();
+const MAX_SUBMISSION_CHAINS = 1000;
+
+/** Record that submission `submissionId` starts or joins a turn of `chain`. */
+export function rememberSubmissionBotChain(submissionId, chain) {
+  const id = String(submissionId || '').trim();
+  const bots = botChainOf(chain);
+  if (!id || !bots.length) return;
+  chainsBySubmission.set(id, bots);
+  while (chainsBySubmission.size > MAX_SUBMISSION_CHAINS) {
+    chainsBySubmission.delete(chainsBySubmission.keys().next().value);
+  }
+}
+
+/** The chain a submission's transcript meta carries, else the one recorded for its ids. */
+function submissionBotChain(transcriptMeta) {
+  const carried = botChainOf(transcriptMeta?.botChain);
+  if (carried.length) return carried;
+  const merged = Array.isArray(transcriptMeta?.submissionIds) ? transcriptMeta.submissionIds : [];
+  const ids = [transcriptMeta?.checkpointId, ...merged];
+  return botChainOf(ids.flatMap((id) => chainsBySubmission.get(String(id || '')) || []));
+}
+
+/** Stamp the hop and bot chain of the submission that starts the turn (else 0 and none) on `session`. */
 export function stampTurnHop(session, transcriptMeta) {
   session.turnHop = hopOf(transcriptMeta?.hop);
+  session.turnBotChain = submissionBotChain(transcriptMeta);
 }
 
-/** A bot's message steered into the running turn raises the turn's hop. */
+/** A bot's message steered into the running turn raises the turn's hop and joins its chain. */
 export function raiseTurnHop(session, transcriptMeta) {
   const hop = hopOf(transcriptMeta?.hop);
   if (session && hop > hopOf(session.turnHop)) session.turnHop = hop;
+  const chain = submissionBotChain(transcriptMeta);
+  if (session && chain.length) session.turnBotChain = botChainOf([...turnBotChainOf(session), ...chain]);
 }
 
 /** The hop of the turn `session` is in. */
 export const turnHopOf = (session) => hopOf(session?.turnHop);
+
+/** The bot chain of the turn `session` is in. */
+export const turnBotChainOf = (session) => botChainOf(session?.turnBotChain);
+
+/** The one check of every bot-to-bot hand-off (session send, a room seat,
+ *  a contact agent spawn): `target`, the bot the work would reach, is
+ *  neither `self` (the bot handing it on) nor already in `chain`. */
+export function assertBotChainTarget(target, { chain = [], self = '' } = {}, prefix = 'session') {
+  if (!target) return;
+  if (target === self) {
+    throw new Error(
+      `${prefix}: the contact agent "${target}" cannot hand work to itself; do it yourself or delegate to a sub-agent`
+    );
+  }
+  if (chain.includes(target)) {
+    const path = [...chain, ...(self && chain.at(-1) !== self ? [self] : []), target];
+    throw new Error(
+      `${prefix}: the contact agent "${target}" is already in this delegation chain (${path.join(' → ')}); do not hand the work back, answer or delegate to a sub-agent instead`
+    );
+  }
+}

package/src/runtime/shared/bounded-download.mjs

@@ -1,7 +1,7 @@
 import { createWriteStream, rmSync } from 'node:fs';
 import { Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { sleep } from './sleep.mjs';
+import { sleepUnlessAborted } from './abort-race.mjs';
 
 export const MAX_NATIVE_BINARY_DOWNLOAD_BYTES = 256 * 1024 * 1024;
 const DEFAULT_RETRY_DELAYS_MS = [1000, 3000, 9000];
@@ -118,13 +118,17 @@ export async function downloadToFileWithRetry(
     timeoutMs = 180_000,
     retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
     onRetry = null,
+    // Cancels the request, its body and any retry wait; rejects with its reason.
+    signal = null,
   } = {}
 ) {
   const { maximum, expected } = downloadBounds(maxBytes, expectedBytes, label);
   let lastError;
   for (let attempt = 0; attempt <= retryDelaysMs.length; attempt += 1) {
+    signal?.throwIfAborted();
     try {
-      const response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+      const timeout = AbortSignal.timeout(timeoutMs);
+      const response = await fetchFn(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
       try {
         if (!response.ok) throw new DownloadHttpError(response.status, httpLabel, url);
         return await streamResponseToFile(response, destPath, {
@@ -142,12 +146,13 @@ export async function downloadToFileWithRetry(
         }
       }
     } catch (error) {
+      signal?.throwIfAborted();
       lastError = error;
       if (error instanceof DownloadHttpError && error.terminal) throw error;
       const delayMs = retryDelaysMs[attempt];
       if (delayMs === undefined) break;
       onRetry?.({ attempt: attempt + 1, delayMs, error });
-      await sleep(delayMs);
+      await sleepUnlessAborted(delayMs, signal);
     }
   }
   throw lastError;

package/src/runtime/shared/config.mjs

@@ -35,6 +35,7 @@ const {
   setSecret: _setSecret,
   deleteSecret: _deleteSecret,
   hasSecret: _hasSecret,
+  hasFallbackSecret: _hasFallbackSecret,
   setSecretAsync: _setSecretAsyncImpl,
   deleteSecretAsync: _deleteSecretAsyncImpl,
   keychainStatus: _keychainStatus,
@@ -149,23 +150,12 @@ function readConfigRawCached() {
   return raw;
 }
 
-// Canonical on-disk channel shape. Provider-specific ids are durable. Schedule
-// arrays moved to the scheduler DB and prompt injection moved to runtime hooks,
-// so neither belongs in config anymore.
+// Canonical on-disk channel shape. Schedules live in the scheduler DB and
+// prompt injection moved to runtime hooks, so neither belongs in config.
 export function canonicalizeStoredChannelsConfig(value = {}) {
   const next = isPlainObject(value) ? { ...value } : {};
   delete next.promptInjection;
   delete next.schedules;
-  delete next.nonInteractive;
-  delete next.interactive;
-
-  // Messaging (Discord/Telegram) is retired: scrub the provider selector and
-  // per-provider routing sections from stored config.
-  delete next.backend;
-  delete next.provider;
-  delete next.discord;
-  delete next.telegram;
-  delete next.channel;
   return next;
 }
 
@@ -523,6 +513,18 @@ export function readSection(section) {
   return stripGeneratedMarker(readAll()[section] ?? null) ?? {};
 }
 
+/**
+ * One section straight from the file, read-only: never served from the read
+ * cache, restored from a backup, quarantined or written. A missing, unreadable
+ * or malformed config throws. For checks that must fail closed, where a stale
+ * value restored from a backup must not count (developerOptionEnabledStrict).
+ */
+export function readSectionStrict(section) {
+  const parsed = parseJsonText(readFileSync(configPath(), 'utf8'));
+  if (!isPlainObject(parsed)) throw new SyntaxError('config root must be a JSON object');
+  return stripGeneratedMarker(parsed[section] ?? null) ?? {};
+}
+
 export function readConfig() {
   return stripGeneratedMarker(readAll()) ?? {};
 }
@@ -641,14 +643,17 @@ export function updateSectionAsync(section, updater) {
 }
 
 // ── Secret account names ─────────────────────────────────────────────────────
-// Canonical account strings stored in the OS keychain.
+// Canonical account strings stored in the OS keychain (or, on a Linux host with
+// no usable keychain provider, in the private secrets file behind the same
+// get/set/delete calls: keychain-cjs.cjs "Linux fallback file").
 export const SECRET_ACCOUNTS = Object.freeze({
   agentApiKey: (provider) => `agent.${provider}.apiKey`,
   openaiUsageSessionKey: 'agent.openai.usageSessionKey',
 });
 
 // ── Secret-aware getters ─────────────────────────────────────────────────────
-// Read order: ENV MIXDOG_<UPPER_SNAKE> → OS keychain → null.
+// Read order: ENV MIXDOG_<UPPER_SNAKE> → OS keychain → Linux fallback secrets
+// file (read by _getSecret when the keychain has nothing) → null.
 
 function _envKey(account) {
   // 'agent.openai.apiKey' → 'MIXDOG_AGENT_OPENAI_APIKEY'
@@ -676,7 +681,9 @@ export function getOpenAIUsageSessionKey() {
 }
 
 /**
- * Persist a secret to the OS keychain. Throws on failure.
+ * Persist a secret to the OS keychain; on a Linux host with no keychain provider
+ * (secret-tool/libsecret missing, no Secret Service) to the owner-only secrets
+ * file in the data dir instead. Throws on failure.
  * Never writes to mixdog-config.json.
  */
 export function saveSecret(account, value) {
@@ -697,25 +704,25 @@ export async function saveSecretAsync(account, value) {
 }
 
 function saveSecretError(account, err) {
-  {
-    // On WSL/headless Linux (and any host missing a usable keychain provider,
-    // e.g. secret-tool/libsecret not installed or no running Secret Service) the OS
-    // write throws a cryptic provider error. Surface an actionable message that
-    // points at the env-var read path the getters already honor, instead of
-    // silently writing the plaintext secret to mixdog-config.json.
-    const envKey = _envKey(account);
-    const agentMatch = String(account || '').match(/^agent\.([^.]+)\.apiKey$/);
-    const stdEnv = agentMatch ? AGENT_PROVIDER_ENV[agentMatch[1]] : null;
-    const envHint = stdEnv ? `${stdEnv} (or ${envKey})` : envKey;
-    const e = new Error(
-      `[config] could not save secret to the OS keychain: ${err?.message ? err.message : err}\n` +
-        `  Set the ${envHint} environment variable instead — the runtime reads it directly.`
-    );
-    e.cause = err;
-    return e;
-  }
+  // Reached for a locked keyring, a non-Linux keychain failure, or a Linux host
+  // with no keychain provider whose fallback secrets file could not be written
+  // (keychain-cjs.cjs). Surface an actionable message that points at the
+  // env-var read path the getters already honor, instead of silently writing
+  // the plaintext secret to mixdog-config.json. The fallback is a separate
+  // owner-only file, never the config.
+  const envKey = _envKey(account);
+  const agentMatch = String(account || '').match(/^agent\.([^.]+)\.apiKey$/);
+  const stdEnv = agentMatch ? AGENT_PROVIDER_ENV[agentMatch[1]] : null;
+  const envHint = stdEnv ? `${stdEnv} (or ${envKey})` : envKey;
+  const e = new Error(
+    `[config] could not save secret to the OS keychain: ${err?.message ? err.message : err}\n` +
+      `  Set the ${envHint} environment variable instead — the runtime reads it directly.`
+  );
+  e.cause = err;
+  return e;
 }
 
+/** Remove a secret from the OS keychain (if present) and the Linux fallback file. */
 export function deleteSecret(account) {
   _deleteSecret(account);
 }
@@ -741,13 +748,16 @@ export function onKeychainRecovered(listener) {
   return typeof _onKeychainRecovered === 'function' ? _onKeychainRecovered(listener) : () => {};
 }
 
-/** Keyring health for the UI: { state: ok|locked|missing|error|unknown, message }. */
+/** Keyring health for the UI: { state: ok|locked|missing|unreachable|error|unknown, message, fallback }.
+ *  `fallback` is true when no keychain provider exists on this Linux host and
+ *  secrets live in the private secrets file: working storage, not a failure. */
 export function getKeychainStatus() {
   return typeof _keychainStatus === 'function' ? _keychainStatus() : { state: 'unknown', message: '' };
 }
 
 /**
- * Whether a secret is stored in the OS keychain for `account` (ignores env).
+ * Whether a secret is stored in the OS keychain (or Linux fallback file) for
+ * `account` (ignores env).
  * Lets the setup UI show "Set" WITHOUT ever sending the secret value to the
  * browser.
  */
@@ -760,4 +770,10 @@ export function hasStoredSecret(account) {
   }
 }
 
+/** Whether `account`'s stored secret currently lives in the Linux fallback file
+ *  (never true on Windows/macOS). Lets the UI label where a key is kept. */
+export function isFallbackSecret(account) {
+  return typeof _hasFallbackSecret === 'function' ? !!_hasFallbackSecret(account) : false;
+}
+
 export { configPath };

package/src/runtime/shared/connector-accounts.mjs

@@ -1,15 +1,25 @@
 // What a multi-account connector server tells the model about itself (MCP
-// `instructions`): the account it acts for, and to ask which one when the
-// user did not say and several are connected. The deferred-tool manifest
-// (context/deferred-tools.mjs) reads the leading "Account: <address>" back.
+// `instructions`), in one line: the connected accounts, and that each tool
+// takes `account` (asked of the user when several are connected and none was
+// named). An account that cannot be used right now is listed with why.
 
-/** The MCP instructions of a `service` server acting for `account` ('' when unknown). */
-export function accountInstructions(service, account) {
-  if (!account) return undefined;
-  return `Account: ${account}. This server acts only for this ${service} account; other ${service} accounts are separate servers. If several are connected and the user did not name one, ask which account before acting.`;
+/** The MCP instructions naming `accounts` (`{ email, note? }`, `note` a short
+ *  reason it is unusable such as "needs sign-in"; one without an address is
+ *  left out), or undefined when none has one. */
+export function connectorAccountsInstructions(accounts) {
+  const named = (Array.isArray(accounts) ? accounts : []).filter((account) => account?.email);
+  if (!named.length) return undefined;
+  const list = named.map(({ email, note }) => (note ? `${email} (${note})` : email)).join(', ');
+  return named.length === 1
+    ? `Accounts: ${list}. \`account\` may be left out.`
+    : `Accounts: ${list}. Pass \`account\`; if the user named none and there are several, ask which.`;
 }
 
-/** The account a server's instructions name, or ''. */
-export function accountOfInstructions(instructions) {
-  return /^Account: (\S+?)\. /.exec(String(instructions || ''))?.[1] || '';
+/** The account addresses instructions from connectorAccountsInstructions name. */
+export function accountsOfInstructions(instructions) {
+  const list = /^Accounts: (.+?)\. (?:`account`|Pass `account`)/.exec(String(instructions || ''))?.[1] || '';
+  return list
+    .split(', ')
+    .map((part) => part.replace(/ \(.*\)$/, '').trim())
+    .filter(Boolean);
 }