@ai-matrx/agents 0.59.269 → 0.59.271

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
-## 0.59.269
+## 0.59.271
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.270
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 4c08cba6c4 8a4ed656ea -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.269
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 5b7c48a99c 4c08cba6c4 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.268
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 06a190b44e 5b7c48a99c -- apps/shared/matrx-agents/src`

package/dist/context/index.cjs

@@ -43,6 +43,7 @@ __export(context_exports, {
   contextValueChars: () => contextValueChars,
   deliveredFields: () => deliveredFields,
   formatChars: () => formatChars,
+  hasNothingToSend: () => hasNothingToSend,
   isRichEnvelope: () => isRichEnvelope,
   isServerAuthoritativeKey: () => isServerAuthoritativeKey,
   isServerResolved: () => isServerResolved,
@@ -281,6 +282,16 @@ function isRichEnvelope(value) {
 function isLazyPointer(value) {
   return isPlainObject(value) && !hasOwn(value, "content") && onlyRichKeys(value) && hasLazySource(value);
 }
+function hasNothingToSend(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string") return value.trim() === "";
+  if (Array.isArray(value)) return value.length === 0;
+  if (!isPlainObject(value)) return false;
+  if (value.__kind !== void 0) return false;
+  if (isRichEnvelope(value)) return !hasLazySource(value) && hasNothingToSend(value.content);
+  if (isLazyPointer(value)) return false;
+  return Object.keys(value).length === 0;
+}
 function splitContextValue(value) {
   if (isRichEnvelope(value) || isLazyPointer(value)) {
     const { content = null, ...overrides } = value;

package/dist/context/index.d.cts

@@ -424,6 +424,14 @@ declare const RICH_ENVELOPE_KEYS: ReadonlySet<string>;
  * (a note `{ id, title, content }`) is raw content, not an envelope.
  */
 declare function isRichEnvelope(value: unknown): value is Record<string, unknown>;
+/**
+ * True for a value with NOTHING to send: absent, `null`, a blank string, an empty list or an
+ * empty object — or a rich envelope whose `content` is one of those and that names no `source`
+ * for the server to read. Such a value is not a row (live walk 2026-10-23: Side Chat listed five
+ * included 0-character rows — Current selection, Text before/after selection, Primary content,
+ * Custom fields — and counted them). A directive the server acts on by shape is never "nothing".
+ */
+declare function hasNothingToSend(value: unknown): boolean;
 /**
  * Split one wire value into `{ content, overrides }` exactly as aidream
  * `_split_rich_context_value`: a rich envelope or lazy pointer → its `content`
@@ -604,5 +612,5 @@ declare function attachmentContextKey(provider: string, resourceRef: string): st
 /** Compact size for a tabular column: `950`, `18.4k`, `184k`, `1.2M`, `—` for unknown. */
 declare function formatChars(n: number | null | undefined): string;
 
-export { CONTEXT_FETCHABLE_ROWS, CONTEXT_ROW_BLOCKS, CONTEXT_RULES_FEATURE, CONVERSATION_DOCUMENT_CONTEXT_KEYS, CONVERSATION_SCRATCHPAD_PREFIX, DEFAULT_INLINE_CAP, DEFAULT_INLINE_MAX_CHARS, DEFAULT_SURFACE_KEY, LAZY_SOURCE_DEFAULT_MAX, OWN_CONVERSATION_WITHHELD, PAGE_OFF_WITHHELD, PERSON_CONTEXT_VALUES, RESERVED_CONSUMED_KEYS, RICH_ENVELOPE_KEYS, SERVER_AUTHORITATIVE_KEYS, applyReceiptToRows, attachmentContextKey, blocksForRow, buildContextWire, compareReceipt, contextValueChars, deliveredFields, formatChars, isRichEnvelope, isServerAuthoritativeKey, isServerResolved, isWireDirective, lookupSavedRule, lookupSavedRuleFor, neverThePage, pageContextWithheldKeys, pageContextWithholds, receiptRowToResolved, resolveContextRow, resolveContextRule, serverDefaultMax, splitContextValue, systemRowsToResolved, unclaimedBlocks, withheldKeys };
+export { CONTEXT_FETCHABLE_ROWS, CONTEXT_ROW_BLOCKS, CONTEXT_RULES_FEATURE, CONVERSATION_DOCUMENT_CONTEXT_KEYS, CONVERSATION_SCRATCHPAD_PREFIX, DEFAULT_INLINE_CAP, DEFAULT_INLINE_MAX_CHARS, DEFAULT_SURFACE_KEY, LAZY_SOURCE_DEFAULT_MAX, OWN_CONVERSATION_WITHHELD, PAGE_OFF_WITHHELD, PERSON_CONTEXT_VALUES, RESERVED_CONSUMED_KEYS, RICH_ENVELOPE_KEYS, SERVER_AUTHORITATIVE_KEYS, applyReceiptToRows, attachmentContextKey, blocksForRow, buildContextWire, compareReceipt, contextValueChars, deliveredFields, formatChars, hasNothingToSend, isRichEnvelope, isServerAuthoritativeKey, isServerResolved, isWireDirective, lookupSavedRule, lookupSavedRuleFor, neverThePage, pageContextWithheldKeys, pageContextWithholds, receiptRowToResolved, resolveContextRow, resolveContextRule, serverDefaultMax, splitContextValue, systemRowsToResolved, unclaimedBlocks, withheldKeys };
 export type { ContextAgentLayer, ContextBlockedBy, ContextConsumedAs, ContextDeliveredRef, ContextDelivery, ContextLayer, ContextReceipt, ContextReceiptBlock, ContextReceiptMismatch, ContextReceiptRow, ContextRowDelivery, ContextRowOrigin, ContextRowSource, ContextRuleInput, ContextRuleLayers, ContextRuleResult, ContextSurfaceLayer, ContextViewKind, ContextViewLoader, ContextViewTarget, ContextViewedText, PageContextDirective, PageContextMode, PageContextValueFacts, ResolvedContextRow, SavedContextRule, SavedContextRuleRows };

package/dist/context/index.d.ts

@@ -424,6 +424,14 @@ declare const RICH_ENVELOPE_KEYS: ReadonlySet<string>;
  * (a note `{ id, title, content }`) is raw content, not an envelope.
  */
 declare function isRichEnvelope(value: unknown): value is Record<string, unknown>;
+/**
+ * True for a value with NOTHING to send: absent, `null`, a blank string, an empty list or an
+ * empty object — or a rich envelope whose `content` is one of those and that names no `source`
+ * for the server to read. Such a value is not a row (live walk 2026-10-23: Side Chat listed five
+ * included 0-character rows — Current selection, Text before/after selection, Primary content,
+ * Custom fields — and counted them). A directive the server acts on by shape is never "nothing".
+ */
+declare function hasNothingToSend(value: unknown): boolean;
 /**
  * Split one wire value into `{ content, overrides }` exactly as aidream
  * `_split_rich_context_value`: a rich envelope or lazy pointer → its `content`
@@ -604,5 +612,5 @@ declare function attachmentContextKey(provider: string, resourceRef: string): st
 /** Compact size for a tabular column: `950`, `18.4k`, `184k`, `1.2M`, `—` for unknown. */
 declare function formatChars(n: number | null | undefined): string;
 
-export { CONTEXT_FETCHABLE_ROWS, CONTEXT_ROW_BLOCKS, CONTEXT_RULES_FEATURE, CONVERSATION_DOCUMENT_CONTEXT_KEYS, CONVERSATION_SCRATCHPAD_PREFIX, DEFAULT_INLINE_CAP, DEFAULT_INLINE_MAX_CHARS, DEFAULT_SURFACE_KEY, LAZY_SOURCE_DEFAULT_MAX, OWN_CONVERSATION_WITHHELD, PAGE_OFF_WITHHELD, PERSON_CONTEXT_VALUES, RESERVED_CONSUMED_KEYS, RICH_ENVELOPE_KEYS, SERVER_AUTHORITATIVE_KEYS, applyReceiptToRows, attachmentContextKey, blocksForRow, buildContextWire, compareReceipt, contextValueChars, deliveredFields, formatChars, isRichEnvelope, isServerAuthoritativeKey, isServerResolved, isWireDirective, lookupSavedRule, lookupSavedRuleFor, neverThePage, pageContextWithheldKeys, pageContextWithholds, receiptRowToResolved, resolveContextRow, resolveContextRule, serverDefaultMax, splitContextValue, systemRowsToResolved, unclaimedBlocks, withheldKeys };
+export { CONTEXT_FETCHABLE_ROWS, CONTEXT_ROW_BLOCKS, CONTEXT_RULES_FEATURE, CONVERSATION_DOCUMENT_CONTEXT_KEYS, CONVERSATION_SCRATCHPAD_PREFIX, DEFAULT_INLINE_CAP, DEFAULT_INLINE_MAX_CHARS, DEFAULT_SURFACE_KEY, LAZY_SOURCE_DEFAULT_MAX, OWN_CONVERSATION_WITHHELD, PAGE_OFF_WITHHELD, PERSON_CONTEXT_VALUES, RESERVED_CONSUMED_KEYS, RICH_ENVELOPE_KEYS, SERVER_AUTHORITATIVE_KEYS, applyReceiptToRows, attachmentContextKey, blocksForRow, buildContextWire, compareReceipt, contextValueChars, deliveredFields, formatChars, hasNothingToSend, isRichEnvelope, isServerAuthoritativeKey, isServerResolved, isWireDirective, lookupSavedRule, lookupSavedRuleFor, neverThePage, pageContextWithheldKeys, pageContextWithholds, receiptRowToResolved, resolveContextRow, resolveContextRule, serverDefaultMax, splitContextValue, systemRowsToResolved, unclaimedBlocks, withheldKeys };
 export type { ContextAgentLayer, ContextBlockedBy, ContextConsumedAs, ContextDeliveredRef, ContextDelivery, ContextLayer, ContextReceipt, ContextReceiptBlock, ContextReceiptMismatch, ContextReceiptRow, ContextRowDelivery, ContextRowOrigin, ContextRowSource, ContextRuleInput, ContextRuleLayers, ContextRuleResult, ContextSurfaceLayer, ContextViewKind, ContextViewLoader, ContextViewTarget, ContextViewedText, PageContextDirective, PageContextMode, PageContextValueFacts, ResolvedContextRow, SavedContextRule, SavedContextRuleRows };

package/dist/context/index.js

@@ -218,6 +218,16 @@ function isRichEnvelope(value) {
 function isLazyPointer(value) {
   return isPlainObject(value) && !hasOwn(value, "content") && onlyRichKeys(value) && hasLazySource(value);
 }
+function hasNothingToSend(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string") return value.trim() === "";
+  if (Array.isArray(value)) return value.length === 0;
+  if (!isPlainObject(value)) return false;
+  if (value.__kind !== void 0) return false;
+  if (isRichEnvelope(value)) return !hasLazySource(value) && hasNothingToSend(value.content);
+  if (isLazyPointer(value)) return false;
+  return Object.keys(value).length === 0;
+}
 function splitContextValue(value) {
   if (isRichEnvelope(value) || isLazyPointer(value)) {
     const { content = null, ...overrides } = value;
@@ -506,6 +516,7 @@ export {
   contextValueChars,
   deliveredFields,
   formatChars,
+  hasNothingToSend,
   isRichEnvelope,
   isServerAuthoritativeKey,
   isServerResolved,

package/dist/context/react/index.cjs

@@ -376,6 +376,9 @@ function offByDefaultReason(row) {
   if (row.include || row.decided_by.include !== "page") return null;
   return row.layers?.surface?.auto_context === false ? "Off by default on this page" : null;
 }
+function deliveredTextForPerson(text) {
+  return text.replace(/<object\b[^>]*>/g, (tag) => tag.replace(/\s+key="[^"]*"/g, ""));
+}
 
 // context/react/InlineMaxInput.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
@@ -893,6 +896,7 @@ var import_icons7 = require("@ai-matrx/design-system/icons");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var BLIND_TOOLTIP = "Not sent to this model";
 var BLIND_LABEL = "Not read";
+var PENDING_LABEL = "Included values";
 function IconButton({
   label,
   onClick,
@@ -934,6 +938,7 @@ function ContextRulesChip({
   open: openProp,
   onOpenChange,
   pressed,
+  countPending = false,
   className,
   variant = "outline"
 }) {
@@ -945,7 +950,7 @@ function ContextRulesChip({
   };
   const { count, charsLabel } = summarizeContextRows(rows);
   const name = label?.trim() ?? "";
-  const faceName = name ? `${name} \xB7 ${count} included` : `${count} included`;
+  const faceName = countPending ? name || PENDING_LABEL : name ? `${name} \xB7 ${count} included` : `${count} included`;
   const anyOverride = rows.some(hasOverride);
   const blind = !modelReadsContext;
   const comfortable = !!isMobile;
@@ -964,7 +969,7 @@ function ContextRulesChip({
       icon: eyeOpen ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(EyeIcon, {}) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_icons7.EyeOffIcon, {}),
       ...isMobile ? { onClick: () => setOpen(true) } : {},
       className: (0, import_design_system4.cn)("min-w-0", className),
-      children: `${name ? `${name} \xB7 ` : ""}${count}`
+      children: countPending ? name || null : `${name ? `${name} \xB7 ` : ""}${count}`
     }
   );
   const faceTip = blind ? BLIND_TOOLTIP : name ? null : faceName;
@@ -990,7 +995,7 @@ function ContextRulesChip({
             children: [
               eyeOpen ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(EyeIcon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_icons7.EyeOffIcon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }),
               headerName ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "min-w-0 truncate text-sm font-medium", children: headerName }) : null,
-              /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "shrink-0 text-xs tabular-nums text-muted-foreground", children: `${count} \xB7 ${charsLabel} chars` }),
+              countPending ? null : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "shrink-0 text-xs tabular-nums text-muted-foreground", children: `${count} \xB7 ${charsLabel} chars` }),
               /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "ml-auto flex shrink-0 items-center gap-0.5", children: [
                 blind ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "mr-1 text-xs text-muted-foreground", children: BLIND_LABEL }) : null,
                 canMaster ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
@@ -1020,7 +1025,7 @@ function ContextRulesChip({
             ]
           }
         ),
-        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { className: (0, import_design_system4.cn)("min-h-0 overflow-y-auto", comfortable ? "max-h-[70dvh]" : "max-h-[min(24rem,60vh)]"), children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { className: (0, import_design_system4.cn)("min-h-0 overflow-y-auto", comfortable ? "max-h-[70dvh]" : "max-h-[min(24rem,60vh)]"), children: countPending ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { "data-testid": "context-rules-pending", role: "status", "aria-busy": "true", className: "p-3", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_design_system4.Skeleton, { className: "h-16 w-full" }) }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
           ContextRulesTable,
           {
             rows,
@@ -1193,7 +1198,7 @@ function DeliveredSection({
           "whitespace-pre-wrap break-words rounded border border-border",
           "bg-muted/40 p-2 font-mono text-[11px] text-foreground"
         ),
-        children: loaded.text
+        children: deliveredTextForPerson(loaded.text)
       }
     )
   ] });

package/dist/context/react/index.d.cts

@@ -364,6 +364,13 @@ interface ContextRulesChipProps {
      * Omitted: the chip is a plain popover trigger, no pressed state.
      */
     pressed?: boolean | undefined;
+    /**
+     * True while what decides INCLUSION (the person's saved rules, a kill switch) has not answered:
+     * the face shows its eye and no number, and the opened surface shows no count and no switches
+     * yet — never a number that changes when it is opened (live walk 2026-10-23: 5 on the face, 3
+     * in the popover). Omitted: the rows are final.
+     */
+    countPending?: boolean | undefined;
     /** The face's skin: `outline` (default) or `quiet` (a composer row). */
     variant?: "outline" | "quiet";
     /** Placement only. */
@@ -374,7 +381,7 @@ interface ContextRulesChipProps {
  * "N · chars" summary, page master switch, reset-all, full view) over the
  * compact rules table. Popover on desktop, bottom sheet on mobile.
  */
-declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, modelReadsContext, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, pressed, className, variant, }: ContextRulesChipProps): React.JSX.Element;
+declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, modelReadsContext, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, pressed, countPending, className, variant, }: ContextRulesChipProps): React.JSX.Element;
 
 interface ContextRulesPanelBodyProps {
     rows: readonly ResolvedContextRow[];

package/dist/context/react/index.d.ts

@@ -364,6 +364,13 @@ interface ContextRulesChipProps {
      * Omitted: the chip is a plain popover trigger, no pressed state.
      */
     pressed?: boolean | undefined;
+    /**
+     * True while what decides INCLUSION (the person's saved rules, a kill switch) has not answered:
+     * the face shows its eye and no number, and the opened surface shows no count and no switches
+     * yet — never a number that changes when it is opened (live walk 2026-10-23: 5 on the face, 3
+     * in the popover). Omitted: the rows are final.
+     */
+    countPending?: boolean | undefined;
     /** The face's skin: `outline` (default) or `quiet` (a composer row). */
     variant?: "outline" | "quiet";
     /** Placement only. */
@@ -374,7 +381,7 @@ interface ContextRulesChipProps {
  * "N · chars" summary, page master switch, reset-all, full view) over the
  * compact rules table. Popover on desktop, bottom sheet on mobile.
  */
-declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, modelReadsContext, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, pressed, className, variant, }: ContextRulesChipProps): React.JSX.Element;
+declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, modelReadsContext, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, pressed, countPending, className, variant, }: ContextRulesChipProps): React.JSX.Element;
 
 interface ContextRulesPanelBodyProps {
     rows: readonly ResolvedContextRow[];

package/dist/context/react/index.js

@@ -344,6 +344,9 @@ function offByDefaultReason(row) {
   if (row.include || row.decided_by.include !== "page") return null;
   return row.layers?.surface?.auto_context === false ? "Off by default on this page" : null;
 }
+function deliveredTextForPerson(text) {
+  return text.replace(/<object\b[^>]*>/g, (tag) => tag.replace(/\s+key="[^"]*"/g, ""));
+}
 
 // context/react/InlineMaxInput.tsx
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
@@ -859,6 +862,7 @@ import { Button } from "@ai-matrx/design-system/controls";
 import {
   BottomSheet,
   Popover as Popover2,
+  Skeleton,
   PopoverContent as PopoverContent2,
   PopoverTrigger as PopoverTrigger2,
   Switch as Switch2,
@@ -872,6 +876,7 @@ import { EyeOffIcon, PanelRightIcon } from "@ai-matrx/design-system/icons";
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 var BLIND_TOOLTIP = "Not sent to this model";
 var BLIND_LABEL = "Not read";
+var PENDING_LABEL = "Included values";
 function IconButton({
   label,
   onClick,
@@ -913,6 +918,7 @@ function ContextRulesChip({
   open: openProp,
   onOpenChange,
   pressed,
+  countPending = false,
   className,
   variant = "outline"
 }) {
@@ -924,7 +930,7 @@ function ContextRulesChip({
   };
   const { count, charsLabel } = summarizeContextRows(rows);
   const name = label?.trim() ?? "";
-  const faceName = name ? `${name} \xB7 ${count} included` : `${count} included`;
+  const faceName = countPending ? name || PENDING_LABEL : name ? `${name} \xB7 ${count} included` : `${count} included`;
   const anyOverride = rows.some(hasOverride);
   const blind = !modelReadsContext;
   const comfortable = !!isMobile;
@@ -943,7 +949,7 @@ function ContextRulesChip({
       icon: eyeOpen ? /* @__PURE__ */ jsx4(EyeIcon, {}) : /* @__PURE__ */ jsx4(EyeOffIcon, {}),
       ...isMobile ? { onClick: () => setOpen(true) } : {},
       className: cn4("min-w-0", className),
-      children: `${name ? `${name} \xB7 ` : ""}${count}`
+      children: countPending ? name || null : `${name ? `${name} \xB7 ` : ""}${count}`
     }
   );
   const faceTip = blind ? BLIND_TOOLTIP : name ? null : faceName;
@@ -969,7 +975,7 @@ function ContextRulesChip({
             children: [
               eyeOpen ? /* @__PURE__ */ jsx4(EyeIcon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }) : /* @__PURE__ */ jsx4(EyeOffIcon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }),
               headerName ? /* @__PURE__ */ jsx4("span", { className: "min-w-0 truncate text-sm font-medium", children: headerName }) : null,
-              /* @__PURE__ */ jsx4("span", { className: "shrink-0 text-xs tabular-nums text-muted-foreground", children: `${count} \xB7 ${charsLabel} chars` }),
+              countPending ? null : /* @__PURE__ */ jsx4("span", { className: "shrink-0 text-xs tabular-nums text-muted-foreground", children: `${count} \xB7 ${charsLabel} chars` }),
               /* @__PURE__ */ jsxs4("div", { className: "ml-auto flex shrink-0 items-center gap-0.5", children: [
                 blind ? /* @__PURE__ */ jsx4("span", { className: "mr-1 text-xs text-muted-foreground", children: BLIND_LABEL }) : null,
                 canMaster ? /* @__PURE__ */ jsx4(
@@ -999,7 +1005,7 @@ function ContextRulesChip({
             ]
           }
         ),
-        /* @__PURE__ */ jsx4("div", { className: cn4("min-h-0 overflow-y-auto", comfortable ? "max-h-[70dvh]" : "max-h-[min(24rem,60vh)]"), children: /* @__PURE__ */ jsx4(
+        /* @__PURE__ */ jsx4("div", { className: cn4("min-h-0 overflow-y-auto", comfortable ? "max-h-[70dvh]" : "max-h-[min(24rem,60vh)]"), children: countPending ? /* @__PURE__ */ jsx4("div", { "data-testid": "context-rules-pending", role: "status", "aria-busy": "true", className: "p-3", children: /* @__PURE__ */ jsx4(Skeleton, { className: "h-16 w-full" }) }) : /* @__PURE__ */ jsx4(
           ContextRulesTable,
           {
             rows,
@@ -1046,7 +1052,7 @@ import { ChevronLeftIcon, SearchIcon } from "@ai-matrx/design-system/icons";
 
 // context/react/ContextDeliveredValue.tsx
 import * as React4 from "react";
-import { Skeleton, cn as cn5 } from "@ai-matrx/design-system";
+import { Skeleton as Skeleton2, cn as cn5 } from "@ai-matrx/design-system";
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 function ContextDeliveredValue({
   row,
@@ -1154,7 +1160,7 @@ function DeliveredSection({
         }
       ) : null
     ] }),
-    unavailable ? null : !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? (
+    unavailable ? null : !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton2, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? (
       // Calm and one line: the server's words never reach the person (the host's loader files the error).
       /* @__PURE__ */ jsxs5("span", { "data-testid": "context-delivered-unavailable", className: "flex items-center gap-2 text-xs text-muted-foreground", children: [
         /* @__PURE__ */ jsx5("span", { className: "min-w-0 truncate", children: "Text not kept for this message" }),
@@ -1177,7 +1183,7 @@ function DeliveredSection({
           "whitespace-pre-wrap break-words rounded border border-border",
           "bg-muted/40 p-2 font-mono text-[11px] text-foreground"
         ),
-        children: loaded.text
+        children: deliveredTextForPerson(loaded.text)
       }
     )
   ] });

package/dist/models/index.cjs

@@ -25,6 +25,8 @@ __export(models_exports, {
   DEFAULT_CAPABILITIES: () => DEFAULT_CAPABILITIES,
   DEVICE_FILE_USABLE_STATES: () => DEVICE_FILE_USABLE_STATES,
   DEVICE_OWN_FILE_USABLE_STATES: () => DEVICE_OWN_FILE_USABLE_STATES,
+  DEVICE_RULE_TWIN_FIXTURE: () => DEVICE_RULE_TWIN_FIXTURE,
+  DEVICE_SERVED_SETTINGS_KEY: () => DEVICE_SERVED_SETTINGS_KEY,
   DEVICE_SERVED_VIA: () => DEVICE_SERVED_VIA,
   DeviceModelUnavailableError: () => DeviceModelUnavailableError,
   EMPTY_MODEL_RECORDS: () => EMPTY_MODEL_RECORDS,
@@ -72,6 +74,7 @@ __export(models_exports, {
   fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
   followModelCatalogChanges: () => followModelCatalogChanges,
+  followModelCatalogVisibility: () => followModelCatalogVisibility,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
   ggufEngine: () => ggufEngine,
@@ -120,6 +123,7 @@ __export(models_exports, {
   readDeviceModelFiles: () => readDeviceModelFiles,
   readGgufHeader: () => readGgufHeader,
   readModelCatalog: () => readModelCatalog,
+  readModelCatalogStamp: () => readModelCatalogStamp,
   readModelIdentities: () => readModelIdentities,
   readPublicModel: () => readPublicModel,
   reconcileModelFavoriteIds: () => reconcileModelFavoriteIds,
@@ -935,42 +939,6 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
-// models/catalog/changes.ts
-var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
-function hub() {
-  const g = globalThis;
-  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
-}
-function isModelCatalogChange(payload) {
-  const catalog = payload?.["catalog"];
-  return catalog === void 0 || catalog === null || catalog === "models";
-}
-function onModelCatalogChanged(listener) {
-  const h = hub();
-  h.listeners.add(listener);
-  return () => {
-    h.listeners.delete(listener);
-  };
-}
-function modelCatalogRevision() {
-  return hub().revision;
-}
-function announceModelCatalogChanged(payload = {}) {
-  if (!isModelCatalogChange(payload)) return;
-  const h = hub();
-  h.revision += 1;
-  for (const l of [...h.listeners]) {
-    try {
-      l(payload);
-    } catch (err) {
-      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
-    }
-  }
-}
-function followModelCatalogChanges(subscribe) {
-  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
-}
-
 // models/label.ts
 function modelDisplayLabel(row) {
   if (!row) return void 0;
@@ -1562,6 +1530,102 @@ async function readPublicModel(client, key) {
   if (error) return { row: null, error: error.message };
   return { row: data ?? null, error: null };
 }
+async function readModelCatalogStamp(client) {
+  const q = client.schema("ai").from("model_definition").select("updated_at").order("updated_at", { ascending: false, nullsFirst: false });
+  if (!q.limit) throw new Error("readModelCatalogStamp: the client has no .limit() (a supabase-js client does)");
+  const { data, error } = await q.limit(1).maybeSingle();
+  if (error) throw new Error(error.message);
+  const stamp = data?.updated_at;
+  return typeof stamp === "string" ? stamp : null;
+}
+
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+function followModelCatalogVisibility(options) {
+  const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
+  if (!page) return () => {
+  };
+  const minIntervalMs = options.minIntervalMs ?? 2e4;
+  const now = options.now ?? (() => Date.now());
+  const sink = options.errorSink ?? ((e) => {
+    console.error(`[@ai-matrx/agents/models] ${e.code}: ${e.message}`);
+  });
+  let baseline;
+  let inFlight = null;
+  let lastShownRead = -Infinity;
+  const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
+    inFlight = null;
+  });
+  const fail = (err) => sink({ code: "model-catalog-stamp-failed", message: err instanceof Error ? err.message : String(err) });
+  const learnBaseline = () => {
+    if (baseline !== void 0) return;
+    void stamp().then((s4) => {
+      if (baseline === void 0) baseline = s4;
+    }, fail);
+  };
+  const onHidden = () => {
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  };
+  const onShown = () => {
+    if (page.document.visibilityState === "hidden") return;
+    const t = now();
+    if (t - lastShownRead < minIntervalMs) return;
+    lastShownRead = t;
+    const known = baseline;
+    if (known === void 0) return learnBaseline();
+    void stamp().then((s4) => {
+      if (s4 === known) return;
+      baseline = s4;
+      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+    }, fail);
+  };
+  const offChanges = onModelCatalogChanged(() => {
+    baseline = void 0;
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  });
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  page.document.addEventListener("visibilitychange", onVisibility);
+  page.window.addEventListener("focus", onShown);
+  if (page.document.visibilityState === "hidden") learnBaseline();
+  return () => {
+    offChanges();
+    page.document.removeEventListener("visibilitychange", onVisibility);
+    page.window.removeEventListener("focus", onShown);
+  };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -2747,6 +2811,8 @@ var import_sha256 = require("@ai-matrx/kit/sha256");
 
 // models/device-models.ts
 var DEVICE_SERVED_VIA = "device";
+var DEVICE_SERVED_SETTINGS_KEY = "served_via";
+var DEVICE_RULE_TWIN_FIXTURE = "apps/shared/matrx-agents/models/__tests__/device-models.test.ts";
 var DEVICE_FILE_USABLE_STATES = Object.freeze(["present"]);
 var DEVICE_OWN_FILE_USABLE_STATES = Object.freeze(["present", "unmatched"]);
 var s2 = (v) => typeof v === "string" ? v : "";

package/dist/models/index.d.cts

@@ -641,6 +641,8 @@ interface RecordsQuery extends PromiseLike<PgResult> {
         nullsFirst?: boolean;
     }): RecordsQuery;
     maybeSingle(): PromiseLike<PgResult>;
+    /** Only the catalog stamp (`readModelCatalogStamp`) uses it. */
+    limit?(count: number): RecordsQuery;
 }
 interface ModelRecordsClient {
     schema(name: string): {
@@ -791,6 +793,12 @@ declare function readPublicModel(client: PublicModelClient, key: string): Promis
     } | null;
     error: string | null;
 }>;
+/**
+ * THE catalog stamp: the newest `ai.model_definition.updated_at` (one row, one column) — the cheap read a
+ * tab makes to learn whether the catalog changed while it was not listening (catalog/changes.ts
+ * `followModelCatalogVisibility`). Null when the catalog is empty. Throws the database's error.
+ */
+declare function readModelCatalogStamp(client: ModelRecordsClient): Promise<string | null>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -1706,8 +1714,15 @@ declare function curatedList<T extends CuratedModel>(models: readonly T[], { off
  *     listed in `device_model_file_ids` when present.
  */
 type Row$1 = Record<string, unknown>;
-/** How a device-served run says it is served: run settings `{ served_via: "device", … }`. */
+/** The `provider` value of a device-served run: `config_overrides.served_via = { provider: "device", … }`. */
 declare const DEVICE_SERVED_VIA: "device";
+/** Where a device-served run carries its DeviceServedSettings on the agent-run request: `config_overrides.served_via`. */
+declare const DEVICE_SERVED_SETTINGS_KEY: "served_via";
+/**
+ * The server's Python twin (the device provider) MUST mirror the usable states, the required-artifact rule
+ * and the resolveDeviceModel refusals above; this test file is the fixture both sides prove against.
+ */
+declare const DEVICE_RULE_TWIN_FIXTURE: "apps/shared/matrx-agents/models/__tests__/device-models.test.ts";
 /**
  * The ai.device_model_file states whose catalog file can be loaded (the column holds present, missing,
  * corrupt, unmatched, hashing, unverified_match). Only `present` is a verified copy of the catalog artifact;
@@ -1727,8 +1742,9 @@ interface DeviceAvailability {
     device_model_file_ids: string[];
 }
 /** The run settings of a device-served model. There is no ai.provider row and no pricing row: the ledger counts 0 points. */
+/** Carried at `config_overrides.served_via` (DEVICE_SERVED_SETTINGS_KEY) on the agent-run request. */
 interface DeviceServedSettings {
-    served_via: typeof DEVICE_SERVED_VIA;
+    provider: typeof DEVICE_SERVED_VIA;
     /** The computer (public.app_instances.id). */
     app_instance_id: string;
     /** ai.model_definition.id, or an ai.device_model_file.id (artifact_id null) for a person's own model. */
@@ -2024,7 +2040,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
  * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
  *
  * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ *
+ * A tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 /** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
@@ -2039,6 +2060,32 @@ declare function modelCatalogRevision(): number;
 declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
 /** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
 declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+interface ModelCatalogVisibilityOptions {
+    /** The client the stamp is read with (supabase-js fits as is). */
+    client: ModelRecordsClient;
+    /** At most one stamp read per this many ms when the tab shows / takes focus. Default 20 s. */
+    minIntervalMs?: number;
+    /** The page (tests pass a double); defaults to the global `document` / `window`. */
+    page?: {
+        document: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener">;
+        window: Pick<Window, "addEventListener" | "removeEventListener">;
+    };
+    /** Where a failed stamp read is said. Default: console.error, tagged. */
+    errorSink?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    now?: () => number;
+}
+/**
+ * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
+ * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
+ * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
+ * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
+ * where there is no document (a server render, a worker).
+ */
+declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.d.ts

@@ -641,6 +641,8 @@ interface RecordsQuery extends PromiseLike<PgResult> {
         nullsFirst?: boolean;
     }): RecordsQuery;
     maybeSingle(): PromiseLike<PgResult>;
+    /** Only the catalog stamp (`readModelCatalogStamp`) uses it. */
+    limit?(count: number): RecordsQuery;
 }
 interface ModelRecordsClient {
     schema(name: string): {
@@ -791,6 +793,12 @@ declare function readPublicModel(client: PublicModelClient, key: string): Promis
     } | null;
     error: string | null;
 }>;
+/**
+ * THE catalog stamp: the newest `ai.model_definition.updated_at` (one row, one column) — the cheap read a
+ * tab makes to learn whether the catalog changed while it was not listening (catalog/changes.ts
+ * `followModelCatalogVisibility`). Null when the catalog is empty. Throws the database's error.
+ */
+declare function readModelCatalogStamp(client: ModelRecordsClient): Promise<string | null>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -1706,8 +1714,15 @@ declare function curatedList<T extends CuratedModel>(models: readonly T[], { off
  *     listed in `device_model_file_ids` when present.
  */
 type Row$1 = Record<string, unknown>;
-/** How a device-served run says it is served: run settings `{ served_via: "device", … }`. */
+/** The `provider` value of a device-served run: `config_overrides.served_via = { provider: "device", … }`. */
 declare const DEVICE_SERVED_VIA: "device";
+/** Where a device-served run carries its DeviceServedSettings on the agent-run request: `config_overrides.served_via`. */
+declare const DEVICE_SERVED_SETTINGS_KEY: "served_via";
+/**
+ * The server's Python twin (the device provider) MUST mirror the usable states, the required-artifact rule
+ * and the resolveDeviceModel refusals above; this test file is the fixture both sides prove against.
+ */
+declare const DEVICE_RULE_TWIN_FIXTURE: "apps/shared/matrx-agents/models/__tests__/device-models.test.ts";
 /**
  * The ai.device_model_file states whose catalog file can be loaded (the column holds present, missing,
  * corrupt, unmatched, hashing, unverified_match). Only `present` is a verified copy of the catalog artifact;
@@ -1727,8 +1742,9 @@ interface DeviceAvailability {
     device_model_file_ids: string[];
 }
 /** The run settings of a device-served model. There is no ai.provider row and no pricing row: the ledger counts 0 points. */
+/** Carried at `config_overrides.served_via` (DEVICE_SERVED_SETTINGS_KEY) on the agent-run request. */
 interface DeviceServedSettings {
-    served_via: typeof DEVICE_SERVED_VIA;
+    provider: typeof DEVICE_SERVED_VIA;
     /** The computer (public.app_instances.id). */
     app_instance_id: string;
     /** ai.model_definition.id, or an ai.device_model_file.id (artifact_id null) for a person's own model. */
@@ -2024,7 +2040,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
  * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
  *
  * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ *
+ * A tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 /** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
@@ -2039,6 +2060,32 @@ declare function modelCatalogRevision(): number;
 declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
 /** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
 declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+interface ModelCatalogVisibilityOptions {
+    /** The client the stamp is read with (supabase-js fits as is). */
+    client: ModelRecordsClient;
+    /** At most one stamp read per this many ms when the tab shows / takes focus. Default 20 s. */
+    minIntervalMs?: number;
+    /** The page (tests pass a double); defaults to the global `document` / `window`. */
+    page?: {
+        document: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener">;
+        window: Pick<Window, "addEventListener" | "removeEventListener">;
+    };
+    /** Where a failed stamp read is said. Default: console.error, tagged. */
+    errorSink?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    now?: () => number;
+}
+/**
+ * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
+ * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
+ * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
+ * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
+ * where there is no document (a server render, a worker).
+ */
+declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.js

@@ -759,42 +759,6 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
-// models/catalog/changes.ts
-var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
-function hub() {
-  const g = globalThis;
-  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
-}
-function isModelCatalogChange(payload) {
-  const catalog = payload?.["catalog"];
-  return catalog === void 0 || catalog === null || catalog === "models";
-}
-function onModelCatalogChanged(listener) {
-  const h = hub();
-  h.listeners.add(listener);
-  return () => {
-    h.listeners.delete(listener);
-  };
-}
-function modelCatalogRevision() {
-  return hub().revision;
-}
-function announceModelCatalogChanged(payload = {}) {
-  if (!isModelCatalogChange(payload)) return;
-  const h = hub();
-  h.revision += 1;
-  for (const l of [...h.listeners]) {
-    try {
-      l(payload);
-    } catch (err) {
-      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
-    }
-  }
-}
-function followModelCatalogChanges(subscribe) {
-  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
-}
-
 // models/label.ts
 function modelDisplayLabel(row) {
   if (!row) return void 0;
@@ -1386,6 +1350,102 @@ async function readPublicModel(client, key) {
   if (error) return { row: null, error: error.message };
   return { row: data ?? null, error: null };
 }
+async function readModelCatalogStamp(client) {
+  const q = client.schema("ai").from("model_definition").select("updated_at").order("updated_at", { ascending: false, nullsFirst: false });
+  if (!q.limit) throw new Error("readModelCatalogStamp: the client has no .limit() (a supabase-js client does)");
+  const { data, error } = await q.limit(1).maybeSingle();
+  if (error) throw new Error(error.message);
+  const stamp = data?.updated_at;
+  return typeof stamp === "string" ? stamp : null;
+}
+
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+function followModelCatalogVisibility(options) {
+  const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
+  if (!page) return () => {
+  };
+  const minIntervalMs = options.minIntervalMs ?? 2e4;
+  const now = options.now ?? (() => Date.now());
+  const sink = options.errorSink ?? ((e) => {
+    console.error(`[@ai-matrx/agents/models] ${e.code}: ${e.message}`);
+  });
+  let baseline;
+  let inFlight = null;
+  let lastShownRead = -Infinity;
+  const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
+    inFlight = null;
+  });
+  const fail = (err) => sink({ code: "model-catalog-stamp-failed", message: err instanceof Error ? err.message : String(err) });
+  const learnBaseline = () => {
+    if (baseline !== void 0) return;
+    void stamp().then((s4) => {
+      if (baseline === void 0) baseline = s4;
+    }, fail);
+  };
+  const onHidden = () => {
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  };
+  const onShown = () => {
+    if (page.document.visibilityState === "hidden") return;
+    const t = now();
+    if (t - lastShownRead < minIntervalMs) return;
+    lastShownRead = t;
+    const known = baseline;
+    if (known === void 0) return learnBaseline();
+    void stamp().then((s4) => {
+      if (s4 === known) return;
+      baseline = s4;
+      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+    }, fail);
+  };
+  const offChanges = onModelCatalogChanged(() => {
+    baseline = void 0;
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  });
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  page.document.addEventListener("visibilitychange", onVisibility);
+  page.window.addEventListener("focus", onShown);
+  if (page.document.visibilityState === "hidden") learnBaseline();
+  return () => {
+    offChanges();
+    page.document.removeEventListener("visibilitychange", onVisibility);
+    page.window.removeEventListener("focus", onShown);
+  };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -2571,6 +2631,8 @@ import { sha256Hex } from "@ai-matrx/kit/sha256";
 
 // models/device-models.ts
 var DEVICE_SERVED_VIA = "device";
+var DEVICE_SERVED_SETTINGS_KEY = "served_via";
+var DEVICE_RULE_TWIN_FIXTURE = "apps/shared/matrx-agents/models/__tests__/device-models.test.ts";
 var DEVICE_FILE_USABLE_STATES = Object.freeze(["present"]);
 var DEVICE_OWN_FILE_USABLE_STATES = Object.freeze(["present", "unmatched"]);
 var s2 = (v) => typeof v === "string" ? v : "";
@@ -2980,6 +3042,8 @@ export {
   DEFAULT_CAPABILITIES,
   DEVICE_FILE_USABLE_STATES,
   DEVICE_OWN_FILE_USABLE_STATES,
+  DEVICE_RULE_TWIN_FIXTURE,
+  DEVICE_SERVED_SETTINGS_KEY,
   DEVICE_SERVED_VIA,
   DeviceModelUnavailableError,
   EMPTY_MODEL_RECORDS,
@@ -3027,6 +3091,7 @@ export {
   fitsNeed,
   fitsThisComputer,
   followModelCatalogChanges,
+  followModelCatalogVisibility,
   formatMemoryBytes,
   fromDiscovery,
   ggufEngine,
@@ -3075,6 +3140,7 @@ export {
   readDeviceModelFiles,
   readGgufHeader,
   readModelCatalog,
+  readModelCatalogStamp,
   readModelIdentities,
   readPublicModel,
   reconcileModelFavoriteIds,

package/dist/models/react/index.d.cts

@@ -675,7 +675,12 @@ declare function ModelListDropdown({ value: savedValue, localModels: localModels
  * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
  *
  * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ *
+ * A tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 

package/dist/models/react/index.d.ts

@@ -675,7 +675,12 @@ declare function ModelListDropdown({ value: savedValue, localModels: localModels
  * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
  *
  * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ *
+ * A tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.269",
+  "version": "0.59.271",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -518,23 +518,5 @@
       "optional": true
     }
   },
-  "matrx": {
-    "charter": "The headless agent core and the server API contract.",
-    "owns": [
-      "transport",
-      "stream protocol",
-      "mandates",
-      "agent catalog and picker",
-      "models",
-      "skills",
-      "generated server types"
-    ],
-    "mustNotOwn": [
-      "chat UI",
-      "Redux",
-      "the agent builder"
-    ],
-    "layer": 5
-  },
-  "gitHead": "4c08cba6c4ebffa2299d1307c43d2229e29a8afb"
+  "gitHead": "2c48e6413332bdf7ea9f92366e3ad0e4129ddd52"
 }