@chatpanel/events 0.95.0 → 0.97.0

package/citations.js

@@ -77,3 +77,52 @@ export function linkifyCitations(answer, sources, { heading = 'Sources' } = {})
     .join('\n');
   return `${linked.trimEnd()}\n\n**${heading}**\n${list}\n`;
 }
+
+// ---------------------------------------------------------------------------------------
+// The collector — what a turn was GIVEN, gathered as its tools return it, and put back
+// under the answer as links. Was the extension's `citationCollector`; the desktop had none,
+// so its answers cited `[1]` with nothing to click.
+// ---------------------------------------------------------------------------------------
+
+/** Tools whose job is to RETURN material rather than to act on something. */
+export const RETRIEVAL_TOOLS = Object.freeze(new Set(['find', 'source', 'history_search', 'web_search', 'search', 'fetch', 'read_page']));
+
+const retrievalName = (name) => String(name || '').replace(/^mcp[_-]/, '').split('__')[0];
+
+/**
+ * Wrap a toolset so every result is read for numbered sources.
+ *
+ * @param tools        `{ execute, … }`; returned as `.tools`, wrapped
+ * @param onRetrieved  `({ tool, count, chars, sources }) => void` — RETRIEVAL IS INPUT. Called
+ *                     per call that returned material, so the turn shows what it was given and
+ *                     by which tool. A retrieval tool that returned no LINKS still returned
+ *                     material (notes, past chats), and is reported with `count: 0` — silence
+ *                     there would under-report exactly the private sources this makes visible.
+ * @returns `{ tools, list(), apply(answer) }`
+ */
+export function createCitationCollector(tools, { onRetrieved = null } = {}) {
+  const sources = new Map();
+  const collect = (name, out) => {
+    const body = typeof out === 'string' ? out : (out?.text || '');
+    if (!body) return;
+    const found = sourcesFromToolText(body);
+    for (const s of found) if (!sources.has(s.rank)) sources.set(s.rank, s);
+    if (!onRetrieved) return;
+    try {
+      if (found.length) onRetrieved({ tool: name, count: found.length, chars: body.length, sources: found.slice(0, 20).map((x) => ({ rank: x.rank, title: x.title || '', url: x.url || '' })) });
+      else if (RETRIEVAL_TOOLS.has(retrievalName(name))) onRetrieved({ tool: name, count: 0, chars: body.length, sources: [] });
+    } catch { /* reporting never breaks a turn */ }
+  };
+  const wrapped = tools && typeof tools.execute === 'function'
+    ? { ...tools, execute: async (name, input, meta) => { const out = await tools.execute(name, input, meta); collect(name, out); return out; } }
+    : tools;
+  return {
+    tools: wrapped,
+    list: () => [...sources.values()],
+    /** The answer with its `[n]` citations linked and a Sources section — or the answer untouched when nothing was retrieved. */
+    apply(answer) {
+      if (!sources.size || !answer || typeof answer !== 'string') return answer;
+      try { return linkifyCitations(answer, [...sources.values()]); } catch { return answer; }
+    },
+  };
+}

package/client-prefs.js

@@ -40,6 +40,10 @@ export const PREF_SECTIONS = Object.freeze([
   { id: 'watch', label: 'Watch', path: ['ui', 'watch'], kind: 'object' },
   { id: 'meetings', label: 'Meetings', path: null, kind: 'object', keys: ['meetingWindowMin', 'liveNotesIntervalMin', 'alertSound'] },
   { id: 'redaction', label: 'Redaction (client-side)', path: ['ui', 'piiRedaction'], kind: 'object' },
+  // Internal sites (source-gate.js): which hosts are internal and how far their content may
+  // travel. A rule the desktop enforces too, or a page internal in the panel is sent
+  // anywhere from the desk.
+  { id: 'internalSites', label: 'Internal sites', path: ['privacy'], kind: 'object' },
 ]);
 
 export const PREF_SECTION_IDS = Object.freeze(PREF_SECTIONS.map((s) => s.id));

package/failover.js

@@ -0,0 +1,93 @@
+// Run the call, and try the next model when this one cannot answer.
+//
+// A provider that returns "you have depleted your monthly credits" has not failed the
+// request — it has declined it, and there is very likely another model that would say yes.
+// Showing that error to the user when an alternative was available is the router not doing
+// the one job it exists for.
+//
+// ONLY WHEN THE ROUTER CHOSE. If the user picked a specific model, silently answering from a
+// different one would be worse than the error: they asked for that model for a reason.
+//
+// This was the extension's `withFailover`; the desktop had none, so the same decline ended
+// the turn there. What is shared is the attempt loop and its rules — keep trying (bounded),
+// classify before retrying, never announce a model that will not be called, say "N models
+// tried" rather than the last provider's error as if it were the whole story. What is
+// injected is how the host picks the next model (its router, its roster) and how it tells
+// the user.
+//
+// Class R with an async seam: no I/O of its own.
+
+/** Enough to work through a realistic set of models rather than sampling it — but bounded, because sitting through every failure is its own kind of broken. */
+export const FAILOVER_MAX_ATTEMPTS = 6;
+
+/** The terminal message: what was tried, and the last thing that went wrong. */
+export function failoverExhausted(tried, err) {
+  const n = Array.isArray(tried) ? tried.length : Number(tried) || 0;
+  const e = new Error(`${n} model${n === 1 ? '' : 's'} tried, none could answer. Last error — ${err?.message || err}`);
+  e.cause = err;
+  e.tried = Array.isArray(tried) ? [...tried] : [];
+  return e;
+}
+
+/**
+ * @param first     the target to call first — `{ id, model, name?, routedVia? }` plus whatever the host's call needs
+ * @param call      `(target) => Promise<result>` — MUST throw on a failure (an Error with
+ *                  `status` when the host has one); a host whose call returns `{ ok: false }`
+ *                  converts before handing it here
+ * @param chose     did the router choose `first`? When false, a failure is the answer.
+ * @param health    a model-health ledger (`createModelHealth`)
+ * @param next      `async ({ current, tried, reason, marked }) => target | null` — the host's
+ *                  router: the same class of thing, excluding what already failed
+ * @param onHop     `({ from, to, reason, reasons, next }) => void` — tell the user, record it
+ * @param labelOf   `(target) => string` for messages
+ * @param signal    an aborted signal ends the chain with the current error
+ */
+export async function runWithFailover({
+  first, call, chose = false, health = null, next = null, onHop = null, labelOf = defaultLabel, signal = null,
+  maxAttempts = FAILOVER_MAX_ATTEMPTS,
+} = {}) {
+  if (typeof call !== 'function') throw new Error('runWithFailover: call required');
+  const tried = [];
+  let current = first;
+  let lastErr = null;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      const out = await call(current);
+      if (current?.id && health) health.markHealthy(current.id);
+      return out;
+    } catch (err) {
+      lastErr = err;
+      if (!chose || signal?.aborted || !health || typeof next !== 'function') throw err;
+      // The model name goes with the report, so "this model fails everywhere" is learnable
+      // rather than rediscovered at each provider in turn.
+      const marked = health.markUnhealthy(current?.id, err, current?.model);
+      if (!marked) throw err;
+      tried.push(current?.id);
+
+      // Do not ANNOUNCE a model we are not going to call. The loop used to pick and announce
+      // the next one and only then discover it was out of attempts, so the chain named a
+      // model that never ran and the error shown came from the hop before it.
+      if (attempt === maxAttempts - 1) throw failoverExhausted(tried, err);
+
+      const to = await next({ current, tried: [...tried], reason: marked.reason, marked, error: err });
+      // Genuinely out of options. Say that, rather than showing the last provider's error as
+      // though it were the whole story — "Groq says no" and "every model you have said no"
+      // are different problems with different fixes.
+      if (!to) throw failoverExhausted(tried, err);
+
+      const hop = {
+        from: labelOf(current), to: labelOf(to), reason: marked.reason,
+        reasons: [`${labelOf(current)} declined (${marked.reason})`, ...(to.routedVia?.reasons || [])],
+        next: to,
+      };
+      try { onHop?.(hop); } catch { /* telling is best effort */ }
+      current = to;
+    }
+  }
+  throw lastErr;
+}
+
+function defaultLabel(t) {
+  return t?.routedVia?.model || t?.name || t?.label || t?.model || t?.id || 'model';
+}

package/index.js

@@ -119,12 +119,12 @@ export {
 } from './observability.js';
 export { routeGraph, projectChain } from './route-graph.js';
 export { defineAdapter, createAdapterRegistry, AdapterError } from './adapters.js';
-export { linkifyCitations, sourcesFromToolText } from './citations.js';
+export { linkifyCitations, sourcesFromToolText, createCitationCollector, RETRIEVAL_TOOLS } from './citations.js';
 export { buildTrajectory, phasesOf, lanesOf, filterEntries, displayName, ENTRY_KINDS, threadsOf, threadTitle, promptEntries, turnsOf, threadTree } from './trajectory.js';
 export { createTurnRunner, defineLoop, LOOP_KINDS, LoopError } from './loop.js';
 export { defineModel, defineMiddleware, defineRouteStrategy, createModelRouter, signalsFrom, requirementsFor, requirementsForStep, preferenceFor, failoverOrder, pinnedOrderOf, FAILOVER_CLASS_GAP, FAILOVER_CAPABILITY_GAP, sameModelKey, RouterError } from './router.js';
 export { makeSourceStore, manifestText, shortUrl, readSource, sourceId } from './sources-retrieval.js';
-export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
+export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, sourceUrlsOf, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
 export { defineRule, createRuleEngine, SUPPRESSED, RuleError } from './rules.js';
 export {
   VAULT_VERSION, KDF_ITERATIONS, KDF_HASH, DEFAULT_LOCK_MS, VaultError,
@@ -178,6 +178,13 @@ export {
   createToolLoopGuard, roundSignature, stableToolCallKey, toolMadeProgress, isLoopableTool, blockedToolResult,
   OBSERVATION_TOOLS, INPUT_PROGRESS_TOOLS,
 } from './tool-loop-guard.js';
+// Failover — the attempt loop and the health ledger behind it; the host's router picks the
+// next model.
+export { classifyFailure, createModelHealth, COOLDOWN_MS, UNAVAILABLE_REASONS, normModelName } from './model-health.js';
+export { runWithFailover, failoverExhausted, FAILOVER_MAX_ATTEMPTS } from './failover.js';
+// The source ceiling as a gate, and the citation collector — the last two pieces of the turn
+// wrapper that were the extension's alone.
+export { sourcePolicySettings, sourceGuardFor, sourceGate, isSourceGateError, withinReach } from './source-gate.js';
 export {
   runTurnLoop, createCallRunner, roundCap, withToolSystem, describeCall as describeToolCall, stepResultText, addUsage, normalizeUsage,
   openAiTranscript, anthropicTranscript,

package/model-health.js

@@ -0,0 +1,182 @@
+// What a provider failure MEANS, and how long to stand the model down for it.
+//
+// Lived in the extension as `js/model-health.js`, wrapped around chrome.storage.session.
+// The desktop could not read it and so could not fail over at all: a model that returned
+// "you have depleted your monthly credits" ended the turn there, while the extension would
+// have moved to the next one. The classifier and the ledger are pure; only the persistence
+// was the extension's, and that is injected now.
+//
+// Only the categories that change what to DO are distinguished. A 402 and a 429 are both
+// "not now", but one is "not for a while" and the other is "in a moment", and routing that
+// treats them the same either hammers a dead endpoint or abandons a live one.
+//
+// Class R: strings in, a category and a deadline out. The clock is injected.
+
+const MODEL_STANDDOWN_MS = 30 * 60_000;
+
+/** How long to stand a model down, by what went wrong. */
+export const COOLDOWN_MS = Object.freeze({
+  quota: 30 * 60_000,
+  rate: 60_000,
+  server: 2 * 60_000,
+  // The model is gone — retired, removed, renamed. It is not coming back, so standing it
+  // down for the rest of the session is the honest answer; anything shorter just repeats the
+  // same failure on a timer.
+  gone: 24 * 60 * 60_000,
+  // The account needs reconnecting — a human action, on no timetable. Retrying on a short
+  // timer just walks the chain back into the same wall every turn.
+  auth: 6 * 60 * 60_000,
+  // A request this provider would not take. Another may; this one probably still will not,
+  // but it is worth re-checking well before an auth problem.
+  request: 10 * 60_000,
+  // Nobody is listening. A local model that is not running, a hostname that does not
+  // resolve, a server that refuses the connection. It is not coming back on a 30-second
+  // timer — someone has to start the thing — and re-dialling it every turn was the exact
+  // failure a user watched as ERR_CONNECTION_REFUSED, twice, on two different pages.
+  unreachable: 5 * 60_000,
+  // Anything else — treat as transient and barely stand it down at all.
+  unknown: 30_000,
+});
+
+/** The reasons that mean "not available" rather than "not right now". */
+export const UNAVAILABLE_REASONS = Object.freeze(['quota', 'server', 'gone', 'auth', 'request', 'unreachable']);
+
+export const normModelName = (m) => String(m || '').toLowerCase().replace(/^[^/]+\//, '').replace(/[:@].*$/, '').replace(/[^a-z0-9.]+/g, '');
+
+/**
+ * Classify a provider failure — an Error, or a `{ status, message }` the host built from a
+ * response it did not throw on.
+ */
+export function classifyFailure(err) {
+  const text = String(err?.message || err?.error || err || '');
+  const status = Number(err?.status) || Number(/\b(4\d\d|5\d\d)\b/.exec(text)?.[1]) || 0;
+  if (status === 402 || /credit|quota|billing|payment required|depleted/i.test(text)) return 'quota';
+  if (status === 429 || /rate.?limit|too many requests/i.test(text)) return 'rate';
+  // THE MODEL IS GONE, not our request. A 410 saying "reached its end of life", a 404 on the
+  // model name, a deprecation notice — every other model would handle this request fine, so
+  // failing the turn is the one response that helps nobody. Checked BEFORE the generic 4xx
+  // rule, which would otherwise read this as our mistake and refuse to fail over.
+  if (status === 410
+    || /end of life|no longer available|has been (retired|deprecated|removed)|decommissioned/i.test(text)
+    // "The model X does not exist or you do not have access to it" — a 404 naming a model is
+    // the provider saying THIS model is unusable, not that our request was malformed.
+    || /model.*(does not exist|not found|no access|do not have access)|unknown model|no such model/i.test(text)
+    // An agent configured for a model it does not have. Nothing about that changes in thirty
+    // seconds, and retrying it costs a process spawn to be told the same thing.
+    || /invalid model selection|not recognized as a (known|custom) model|unsupported model/i.test(text)) return 'gone';
+  if (status >= 500 || /overloaded|unavailable|timeout|ECONNRESET/i.test(text)) return 'server';
+  // NOBODY IS LISTENING. A browser fetch to a dead endpoint throws TypeError: Failed to fetch
+  // (Safari: "Load failed"); Node says ECONNREFUSED. None carry a status.
+  if (/failed to fetch|load failed|networkerror|network error|connection refused|ECONNREFUSED|ERR_CONNECTION|ENOTFOUND|EHOSTUNREACH|ECONNABORTED|couldn't reach the gateway|gateway is not answering/i.test(text)) return 'unreachable';
+  // A BROKEN CONNECTION IS THIS PROVIDER'S, NOT THE REQUEST'S. An expired refresh token —
+  // "OAuth token exchange failed: HTTP 400 — invalid_grant" — says this provider's
+  // credentials went stale, and every other model would have answered the question fine.
+  if (status === 401 || status === 403
+    || /oauth|invalid[_ ]?grant|refresh[_ ]?token|token exchange|api[_ ]?key|unauthorized|not authenticated|authentication|credential|expired token|sign in|log ?in again/i.test(text)) {
+    return 'auth';
+  }
+  // A plain 400 usually IS a malformed request — but providers reject each other's
+  // parameters, tool schemas and sampling settings all the time. Failing over costs one
+  // extra attempt; dead-ending costs the user their turn.
+  if (status === 400) return 'request';
+  // Everything else gets tried elsewhere. A router that gives up on an unrecognised failure
+  // is a router that gives up.
+  return 'unknown';
+}
+
+/**
+ * The health ledger: which models are standing down, and why.
+ *
+ * @param now       clock
+ * @param onChange  `(snapshot) => void` — the host persists it (the extension: the session
+ *                  area; the desktop: memory). Called after every change.
+ */
+export function createModelHealth({ now = () => Date.now(), onChange = null } = {}) {
+  const health = new Map();   // id -> { until, reason, failures }
+  const byModel = new Map();  // normalised model name -> { providers:Set, until, reason }
+
+  const snapshot = () => ({
+    health: [...health].map(([id, h]) => [id, h]),
+    byModel: [...byModel].map(([k, m]) => [k, { providers: [...m.providers], until: m.until, reason: m.reason }]),
+  });
+  const changed = () => { try { onChange?.(snapshot()); } catch { /* persistence is best effort */ } };
+
+  return {
+    snapshot,
+
+    /** Load what another context already learned. Never overwrites what this one knows. */
+    hydrate(snap) {
+      if (!snap) return false;
+      const t = now();
+      for (const [id, h] of snap.health || []) if (h?.until > t && !health.has(id)) health.set(id, h);
+      for (const [k, m] of snap.byModel || []) {
+        if (!m || byModel.has(k)) continue;
+        byModel.set(k, { providers: new Set(m.providers || []), until: m.until || 0, reason: m.reason || null });
+      }
+      return true;
+    },
+
+    /** Record that a model failed, and stand it down for as long as that failure warrants. */
+    markUnhealthy(id, err, modelName = '') {
+      const reason = classifyFailure(err);
+      if (!id || !reason) return null;
+      // Learn about the MODEL, not only the endpoint. A model that is gone is gone everywhere,
+      // so one report is enough; anything else needs two providers to agree before we believe
+      // it is the model rather than the provider.
+      const key = normModelName(modelName);
+      if (key) {
+        const seen = byModel.get(key) || { providers: new Set(), until: 0, reason: null };
+        seen.providers.add(id);
+        if (reason === 'gone' || seen.providers.size >= 2) {
+          seen.until = now() + MODEL_STANDDOWN_MS;
+          seen.reason = reason;
+        }
+        byModel.set(key, seen);
+      }
+      const prev = health.get(id);
+      const failures = (prev?.failures || 0) + 1;
+      // Repeated failures extend the wait, capped — a model failing every time should be
+      // tried rarely, not never. The cap never shortens the base: capping a 24-hour
+      // stand-down at an hour would retry a model that no longer exists, 23 times a day.
+      const base = COOLDOWN_MS[reason] || COOLDOWN_MS.unknown;
+      const ceiling = Math.max(base, 60 * 60_000);
+      const until = now() + Math.min(base * failures, ceiling);
+      health.set(id, { until, reason, failures });
+      changed();
+      return { reason, until };
+    },
+
+    /** A model answered, so whatever was wrong is over. */
+    markHealthy(id) {
+      if (id && health.has(id)) { health.delete(id); changed(); }
+    },
+
+    /** `{ available, rateLimited, reason, until? }` for the router. Unknown models are healthy. */
+    healthOf(id, modelName = '') {
+      const key = normModelName(modelName);
+      if (key) {
+        const m = byModel.get(key);
+        if (m && m.until && now() < m.until) return { available: false, rateLimited: false, reason: m.reason, until: m.until, model: true };
+      }
+      const h = health.get(id);
+      if (!h || now() >= h.until) {
+        if (h) health.delete(id);   // expired; forget it rather than carrying dead state
+        return { available: true, rateLimited: false, reason: null };
+      }
+      // A rate limit is "not right now"; everything else on the list is "not available". The
+      // router rejects both; the reason it shows the user differs.
+      return { available: !UNAVAILABLE_REASONS.includes(h.reason), rateLimited: h.reason === 'rate', reason: h.reason, until: h.until };
+    },
+
+    /** What is currently stood down, for a settings page. */
+    unhealthyModels() {
+      const out = [];
+      const t = now();
+      for (const [id, h] of health) if (t < h.until) out.push({ id, ...h });
+      return out;
+    },
+
+    /** Forget everything. */
+    reset() { health.clear(); byModel.clear(); changed(); },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.95.0",
+  "version": "0.97.0",
   "description": "The canonical ChatPanel event-log and capability contracts — typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -26,6 +26,7 @@
     "./entity.js": "./entity.js",
     "./event.js": "./event.js",
     "./extraction.js": "./extraction.js",
+    "./failover.js": "./failover.js",
     "./find-tool.js": "./find-tool.js",
     "./flowchart.js": "./flowchart.js",
     "./harness.js": "./harness.js",
@@ -49,6 +50,7 @@
     "./meeting-text.js": "./meeting-text.js",
     "./memory.js": "./memory.js",
     "./model-candidates.js": "./model-candidates.js",
+    "./model-health.js": "./model-health.js",
     "./model-ledger.js": "./model-ledger.js",
     "./model-picker.js": "./model-picker.js",
     "./note-actions.js": "./note-actions.js",
@@ -86,6 +88,7 @@
     "./skill-vars.js": "./skill-vars.js",
     "./slash-commands.js": "./slash-commands.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
+    "./source-gate.js": "./source-gate.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
     "./structured.js": "./structured.js",
@@ -161,6 +164,7 @@
     "entity.js",
     "event.js",
     "extraction.js",
+    "failover.js",
     "find-tool.js",
     "flowchart.js",
     "harness.js",
@@ -185,6 +189,7 @@
     "meeting-text.js",
     "memory.js",
     "model-candidates.js",
+    "model-health.js",
     "model-ledger.js",
     "model-picker.js",
     "note-actions.js",
@@ -222,6 +227,7 @@
     "skill-vars.js",
     "slash-commands.js",
     "sources-retrieval.js",
+    "source-gate.js",
     "sources.js",
     "store.js",
     "structured.js",

package/source-gate.js

@@ -0,0 +1,92 @@
+// The source ceiling — would this turn send internal material to a model that is too far
+// away? — as a GATE, not a ranking.
+//
+// Routing is not enough. A router returns null in every uncertain case and null means
+// "leave the choice alone", which is right for a preference and catastrophic for a privacy
+// rule: an internal page with no local model available would have gone to the third party
+// the user had selected. And routing only runs under Auto, so a manually chosen cloud model
+// bypassed it entirely. So this runs on every turn, after routing has had its chance to
+// pick something local, and it REFUSES rather than substituting: silently answering from a
+// different model is the substitution this codebase keeps removing, and silently sending
+// anyway is the leak it exists to stop.
+//
+// Was the extension's `sourceGate` + `sourcePolicySettings` + `sourceUrlsOf`; the desktop
+// had none of it and sent internal pages wherever the picker pointed. The policy (which
+// hosts are internal, how far their content may travel) is the user's and travels in the
+// shared `internalSites` preference section, so both clients enforce the same rule.
+//
+// Class R: no I/O. The target's reach comes from `reachOf` (a bridge agent is 'trusted', a
+// localhost endpoint 'device', the rest 'any') unless the caller already knows it.
+
+import { sourcePolicyFor, sourceUrlsOf, DEFAULT_INTERNAL_PATTERNS } from './sources.js';
+import { reachOf } from './model-candidates.js';
+import { REACH, reachRank } from './reach.js';
+
+// `sourceUrlsOf` lives in sources.js (no router on its graph) so a client's first paint can
+// list a turn's addresses without pulling the router in; it is re-exported here for callers
+// that have the gate anyway.
+export { sourceUrlsOf };
+
+/**
+ * The internal-source policy, read from the `privacy` settings object in ONE place.
+ *
+ * NEVER CONFIGURED and CONFIGURED TO NOTHING are different answers. Undefined means the
+ * user has not been here yet, so the built-ins apply; an array — even an empty one — is a
+ * list they edited, and prepending our own to it would make a default impossible to
+ * remove. Someone testing against localhost has a real reason to delete that line.
+ */
+export function sourcePolicySettings(privacy = {}) {
+  const cfg = privacy || {};
+  const saved = cfg.internalPatterns;
+  const list = Array.isArray(saved)
+    ? saved
+    : (saved == null ? DEFAULT_INTERNAL_PATTERNS : String(saved).split(/[\s,]+/));
+  return {
+    enabled: cfg.internalGuard !== false,
+    patterns: list.map((x) => String(x || '').trim().toLowerCase()).filter(Boolean),
+    ceiling: cfg.internalCeiling === 'trusted' ? 'trusted' : 'device',
+  };
+}
+
+/** What the sources of a turn allow. Null when the guard is off or nothing matched. */
+export function sourceGuardFor(policy, sources = []) {
+  if (!policy || !policy.enabled || !sources?.length) return null;
+  const p = sourcePolicyFor(sources, { patterns: policy.patterns, ceiling: policy.ceiling });
+  return p.internal ? p : null;
+}
+
+/**
+ * The gate. `{ blocked, why, reach, message }` when the target is out of reach for these
+ * sources; null when the turn may go.
+ *
+ * @param policy    `sourcePolicySettings(privacy)`
+ * @param messages  the conversation as it will be sent
+ * @param sources   anything else the caller knows was attached
+ * @param target    `{ kind, baseUrl }` (reach computed) or `{ reach }` (reach known)
+ * @param label     how to name the target in the message
+ */
+export function sourceGate({ policy, messages = [], sources = [], target = {}, label = '' } = {}) {
+  const guard = sourceGuardFor(policy, sourceUrlsOf(messages, sources));
+  if (!guard) return null;
+  const actual = REACH.includes(target?.reach) ? target.reach : reachOf(target || {});
+  if (reachRank(actual) <= reachRank(guard.reach)) return null;
+  const where = guard.reach === 'device' ? 'stay on this device' : 'stay inside your workspace';
+  return {
+    blocked: true,
+    why: guard.why,
+    reach: guard.reach,
+    // Name the source, the model and the way out. A refusal a person cannot act on gets
+    // switched off wholesale, which would leave them worse protected than before.
+    message: `Not sent: ${guard.why}. "${label || 'this model'}" is outside that, and content from an internal source must ${where}. `
+      + 'Pick a local model (or run one), or remove this site under Settings → Privacy → Internal sites.',
+  };
+}
+
+/** Is this error the gate's refusal? A runner reads it as "this model, not this task". */
+export const isSourceGateError = (err) => /^Not sent: /.test(String(err?.message || err || ''));
+
+/** The candidates a turn under `guard` may be handed at all — for a roster, before appointment. */
+export function withinReach(candidates = [], guard = null) {
+  if (!guard) return candidates;
+  return (candidates || []).filter((c) => reachRank(REACH.includes(c?.reach) ? c.reach : reachOf(c || {})) <= reachRank(guard.reach));
+}

package/sources.js

@@ -254,3 +254,20 @@ export function sourcePolicyFor(sources = [], { patterns, ceiling = 'device', ba
     why: `${hits[0].host || 'the source'} matches '${hits[0].matched}' — kept ${safeCeiling === 'device' ? 'on this device' : 'inside your workspace'}`,
   };
 }
+
+/**
+ * Every address a conversation carries: each attachment's `url`, every URL in a message
+ * body (an internal link pasted into a message — or arriving in a tool result written back
+ * into the conversation — is internal material just as much as an attachment is), plus
+ * anything the caller states outright. The WHOLE conversation, because an internal page
+ * attached three turns ago is still in the text being sent now.
+ */
+export function sourceUrlsOf(messages, extraSources = []) {
+  const urls = [];
+  for (const m of messages || []) {
+    for (const a of m?.attachments || []) if (a?.url) urls.push(a.url);
+    for (const u of extractUrls(typeof m?.content === 'string' ? m.content : '')) urls.push(u);
+  }
+  for (const s of extraSources || []) if (s) urls.push(typeof s === 'string' ? s : (s.url || s.href || ''));
+  return urls.filter(Boolean);
+}

package/team-record.js

@@ -70,7 +70,10 @@ export function foldRun(run, ev) {
       if (t) { t.status = 'running'; t.startedAt = at; t.error = null; }
       run.status = 'running'; break;
     }
-    case 'task.model': { const t = taskOf(run, p.taskId); if (t) { t.model = p.model; t.attempts = [...(t.attempts || []), { model: p.model, at, attempt: p.attempt }]; } break; }
+    case 'task.model': { const t = taskOf(run, p.taskId); if (t) { t.model = p.model; t.attempts = [...(t.attempts || []), { model: p.model, ...(p.label ? { label: p.label } : {}), at, attempt: p.attempt }]; } break; }
+    // Which engine the attempt runs on (pillars §13): kept on the attempt, so a record folded
+    // from events names the model the way the runner's own `attempts` do.
+    case 'task.routed': { const t = taskOf(run, p.taskId); const a = t?.attempts?.at?.(-1); if (a && p.engine && (a.attempt == null || a.attempt === p.attempt)) a.engine = p.engine; break; }
     case 'task.step': { const t = taskOf(run, p.taskId); if (t && Array.isArray(p.steps)) t.transcript = [...(t.transcript || []), ...p.steps]; break; }
     case 'task.handoff': { const t = taskOf(run, p.taskId); if (t) { t.model = p.to; t.handoffs = [...(t.handoffs || []), { from: p.from, to: p.to, by: p.by, reason: p.reason, at }]; } break; }
     case 'task.tool': { const t = taskOf(run, p.taskId); if (t) t.tools = (t.tools || 0) + 1; break; }

package/team-run.js

@@ -69,6 +69,9 @@ export function isModelUnavailable(error) {
   // fetch" (the extension reports it as "network error") — a local model killed mid-run
   // arrived as the latter and ended the task on its first attempt with Claude Code sitting
   // idle on the roster.
+  // The source gate's refusal (source-gate.js) is about THIS model's reach, not the task:
+  // the next appointment, within reach, can do it.
+  if (/^Not sent: /.test(m)) return true;
   return /model[_ ]not[_ ]found|not found|not deployed|inaccessible|does not exist|no such model|unknown model|unsupported model|not available|unavailable|no api key|not configured|"status":\s*(404|401|403|500|502|503)\b|\b(404|401|403|502|503)\b|exited \d+|returned no answer|did not answer|closed the connection|couldn't reach|could not reach|ECONNREFUSED|ECONNRESET|ENOTFOUND|EHOSTUNREACH|socket hang up|fetch failed|failed to fetch|load failed|network ?error|overloaded|capacity/i.test(m);
 }
 
@@ -414,7 +417,9 @@ export async function runTeam({
           // A model that is not there — not deployed, no key, gone — is not the task failing:
           // the next model on the roster is appointed and the task tried again, up to three
           // models. Anything else (a refusal, a timeout, a bad request) fails the task.
-          const exclude = new Set();
+          // A resumed task does not walk back into the models that were unavailable the last
+          // time it ran — that is how one task read `A → B → A → B → A → B` on the board.
+          const exclude = new Set((was?.attempts || []).filter((a) => a && a.model && a.status === 'error' && isModelUnavailable(a.error)).map((a) => a.model));
           let lastErr = '';
           // What the next attempt is told, when it continues rather than starts.
           let note = was ? continuationNote(was.status === 'waiting' ? { kind: 'answer', answer: 'see the board' } : { kind: 'resume', reason: was.error || was.status }) : null;
@@ -440,10 +445,12 @@ export async function runTeam({
             if (!m?.model) throw new Error(exclude.size ? `no model left for role "${role.id}" after ${[...exclude].join(', ')}` : `no model for role "${role.id}"`);
             if (attempt > 1 && lastErr) say('task.reappointed', { taskId: task.id, role: role.id, model: m.model, after: [...exclude], error: lastErr });
             // Who is doing this task, for a ledger that shows the lanes — said per attempt.
-            say('task.model', { taskId: task.id, role: role.id, model: m.model, attempt });
+            say('task.model', { taskId: task.id, role: role.id, model: m.model, label: m.label || null, attempt });
             routed = routeOf(m, role, { attempt, exclude, handoff: handoffNow });
             say('task.routed', { taskId: task.id, role: role.id, attempt, ...routed });
-            attempts.push({ model: m.model, engine: routed.engine, at: now(), continued: !!note });
+            // The label beside the id: a work log that reads `mqk41ucyhmz1au → mqqzh4970js34c` names
+            // nothing to the person reading it.
+            attempts.push({ model: m.model, label: m.label || routed.engine?.label || routed.engine?.model || null, engine: routed.engine, at: now(), continued: !!note });
             attemptNo = attempts.length;
             const sent = messagesFor({ transcript }, { prompt, note });
             // The record grows AS THE ATTEMPT GOES: a host that reports each wire message the
@@ -525,7 +532,7 @@ export async function runTeam({
       // the board sees "researcher failed: network error" where it happened, and what was tried.
       if (thread && status === 'ok') board.setThreadStatus(thread.id, 'resolved');
       else if (thread && status !== 'waiting') {
-        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role?.id || task.role} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.model).join(', ')})` : ''}.` });
+        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role?.id || task.role} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.label || a.model).join(', ')})` : ''}.` });
         board.setThreadStatus(thread.id, 'failed');
       }
       const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(task.parent ? { parent: task.parent } : {}), ...(routed ? { routed } : {}), ...(scm ? { scm } : {}), ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };

package/team-worklog.js

@@ -49,7 +49,7 @@ export function workLogFor(run, taskId) {
   const out = [];
   const attempts = Array.isArray(task.attempts) ? task.attempts : [];
   const baseAt = num(task.startedAt, num(attempts[0]?.at, num(run?.startedAt, 0)));
-  attempts.forEach((a, i) => out.push({ id: `attempt:${i + 1}`, kind: 'attempt', at: num(a.at, baseAt + i), by: 'runner', attempt: i + 1, model: a.model || '', engine: a.engine || null, continued: !!a.continued, status: a.status || null, error: a.error || null }));
+  attempts.forEach((a, i) => out.push({ id: `attempt:${i + 1}`, kind: 'attempt', at: num(a.at, baseAt + i), by: 'runner', attempt: i + 1, model: a.label || a.engine?.label || a.engine?.model || a.model || '', modelId: a.model || '', engine: a.engine || null, continued: !!a.continued, status: a.status || null, error: a.error || null }));
 
   // Steps: stamped ones sort by their time; unstamped ones follow their attempt in order.
   const steps = Array.isArray(task.transcript) ? task.transcript : [];
@@ -101,7 +101,7 @@ export function workLogFor(run, taskId) {
 }
 
 function endText(task, attempts) {
-  const tried = attempts.length > 1 ? ` after ${attempts.length} models (${attempts.map((a) => a.model).join(' → ')})` : '';
+  const tried = attempts.length > 1 ? ` after ${attempts.length} models (${attempts.map((a) => a.label || a.engine?.label || a.engine?.model || a.model).join(' → ')})` : '';
   const s = task.status;
   if (s === 'ok') return `done${tried} · ${task.findings || 0} finding${task.findings === 1 ? '' : 's'} · ${task.tools || 0} tool call${task.tools === 1 ? '' : 's'}`;
   if (s === 'waiting') return 'waiting on a person';

package/turn-loop.js

@@ -412,7 +412,8 @@ export async function runTurnLoop({
     // Reconcile: an adapter that returned text without streaming it still gets it into `said`.
     const text = String(res?.text || '');
     if (text && !roundText) { if (said) said += ROUND_SEPARATOR; said += text; roundText = text; }
-    if (!res?.ok) { finish('error'); return result({ ok: false, error: res?.error || 'the model did not answer', aborted: !!res?.aborted, transcript: text.trim() ? [...convo, transcript.said(said)] : convo }); }
+    // `status` rides along when the adapter had one — a failover classifier reads it.
+    if (!res?.ok) { finish('error'); return result({ ok: false, error: res?.error || 'the model did not answer', ...(res?.status ? { status: res.status } : {}), aborted: !!res?.aborted, transcript: text.trim() ? [...convo, transcript.said(said)] : convo }); }
     if (res.aborted || signal?.aborted) { finish('aborted'); return closeWith(said, { aborted: true }); }
 
     const wanted = (Array.isArray(res.toolCalls) ? res.toolCalls : []).filter((c) => c && c.name).map((c) => ({ id: c.id, name: c.name, input: c.input ?? safeJson(c.arguments), arguments: c.arguments }));