@animalabs/agent-framework 0.22.0 → 0.22.2

package/src/mcpl/push-coalescer.ts

@@ -18,6 +18,7 @@
  * bookkeeping and is unit-tested without a framework.
  */
 import type { McplContentBlock, PushEventResult } from './types.js';
+import { classifyBlock, isInlineContradiction } from './references.js';
 import { isVisiblyEmptyContent } from './visible-content.js';
 
 export const PUSH_COALESCING_SUPPORT = {
@@ -37,6 +38,18 @@ export class CoalesceError extends Error {
   }
 }
 
+/**
+ * How the host names a coalesce rejection, from the code the wire answered
+ * with. `coalesce-failed` is the host's own failure: -32000 (coalescing
+ * unavailable, the host stopping, or an acceptance it couldn't make durable)
+ * and -32603 (an internal error). `coalesce-invalid` is every other answer,
+ * the sender's: -32602 for a malformed item, -32017 or -32023 for a channel
+ * that isn't permitted or isn't registered.
+ */
+export function coalesceRejectionReason(answered: number): 'coalesce-failed' | 'coalesce-invalid' {
+  return answered === -32000 || answered === -32603 ? 'coalesce-failed' : 'coalesce-invalid';
+}
+
 /** Content with nothing model-visible (see visible-content.ts): -32602. */
 export class EmptyContentError extends CoalesceError {
   readonly reason = 'empty-content';
@@ -212,7 +225,6 @@ export interface CoalescerOptions {
   recoveryBackoffMs?: number;
   maxSubjects?: number;
   maxNotices?: number;
-  maxContentBytes?: number;
   maxDataBytes?: number;
 }
 
@@ -232,6 +244,32 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
 /**
  * Validate wire content before it is stored, rendered or converted.
  *
+ * Its shape and its visible emptiness, nothing else. An incoming coalesced
+ * occurrence reaches context through the converters an uncoalesced message
+ * goes through: a plain occurrence the moment it is admitted (the coalescer
+ * only remembers where it landed), a deferred one when its render settles or
+ * falls back to it. Its content must be an array of objects. A block the
+ * converters can't render (a video, an unknown type, an image with neither
+ * uri nor data) becomes a placeholder, as it does uncoalesced, and so does a
+ * malformed one, since the converters take any object without throwing: a
+ * type, text, data, mimeType or uri that isn't a string counts as absent, a
+ * text block's as no text. The uncoalesced lane doesn't check the array:
+ * there a member that isn't an object becomes the untyped placeholder, and a
+ * null member or content that isn't an array throws in conversion
+ * (agent-framework#297 brings that lane to this rule).
+ * Nor does the uncoalesced path set a byte budget on content:
+ * an inline image is admitted here as it is there (agent-framework#266: a
+ * 1 MiB serialized-content budget here dropped every coalesced message
+ * carrying a screenshot). A deferred occurrence's content is held, until then,
+ * in the coalescer's state and its persisted snapshot and receipts.
+ *
+ * A render result, which the host delivers in the occurrence's place, gets
+ * these checks, as RFC-006 §5.2 gives it every check a pushed payload gets,
+ * and one more (`checkBlockShapes`): each block must be one the converters
+ * show as itself or as a reference stub, not as a placeholder. A malformed
+ * render falls back to the occurrence's own content; a pushed payload has
+ * nothing to fall back to, and gets its placeholders.
+ *
  * Visibly-empty content is refused unless `allowEmpty`: an admitted
  * occurrence with nothing to show would wake the model with no visible cause.
  * Empty is legitimate only where the RFC gives it a meaning — a retraction
@@ -240,22 +278,38 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
  */
 export function validateCoalescedContent(
   content: unknown,
-  maxBytes = 1024 * 1024,
-  options: { allowEmpty?: boolean } = {},
+  options: { allowEmpty?: boolean; checkBlockShapes?: boolean } = {},
 ): asserts content is McplContentBlock[] {
   if (!Array.isArray(content)) throw new CoalesceError('payload.content', 'content must be an array');
   for (const b of content as Array<Record<string, unknown>>) {
     if (!b || typeof b !== 'object' || Array.isArray(b)) throw new CoalesceError('payload.content', 'invalid content block');
-    if (b.type === 'text' && typeof b.text === 'string') continue;
-    if (b.type === 'resource' && typeof b.uri === 'string') continue;
-    if ((b.type === 'image' || b.type === 'audio')
-      && (typeof b.uri === 'string' || (typeof b.data === 'string' && typeof b.mimeType === 'string'))) continue;
-    throw new CoalesceError('payload.content', 'invalid content block');
+    if (options.checkBlockShapes && !showsAsItself(b)) throw new CoalesceError('payload.content', 'invalid content block');
   }
-  if (Buffer.byteLength(JSON.stringify(content)) > maxBytes) throw new CoalesceError('payload.content', 'content exceeds host byte limit');
   if (!options.allowEmpty && isVisiblyEmptyContent(content)) throw new EmptyContentError();
 }
 
+/**
+ * Whether the converters (`convertBlock` in push-handler.ts and
+ * channel-registry.ts) show a block as itself, its text or its image or
+ * audio source, or as a reference stub, and not as a placeholder: an
+ * unrecognized block, a no-data or no-media-type one, or withheld inline
+ * data. A text block whose text isn't a string, which they show as no text,
+ * is refused too. This follows their branches in their order.
+ */
+function showsAsItself(b: Record<string, unknown>): boolean {
+  if (b.type === 'text') return typeof b.text === 'string';
+  if (b.type === 'resource') return classifyBlock(b).kind === 'reference';
+  if (b.type !== 'image' && b.type !== 'audio') return false;
+  if (isInlineContradiction(b)) return false;
+  if (isFilledString(b.uri) && b.disposition) return classifyBlock(b).kind === 'reference';
+  if (isFilledString(b.data) && isFilledString(b.mimeType)) return true;
+  return b.type === 'image' && isFilledString(b.uri);
+}
+
+function isFilledString(value: unknown): value is string {
+  return typeof value === 'string' && value !== '';
+}
+
 /** Validate the `coalesce` member of either lane (§13). */
 export function validateCoalesceMember(
   c: unknown,
@@ -700,14 +754,24 @@ export class PushCoalescer<E = unknown> {
       try {
         const result = await this.host.render(occurrence, params);
         if (rendering.cancelled) { this.host.audit({ kind: 'late-render', subject, eventId: occurrence.eventId, discarded: true }); }
-        // §5.2: an empty result is legitimate ("nothing happened").
-        else validateCoalescedContent(result?.content, this.options.maxContentBytes, { allowEmpty: true });
+        // §5.2: an empty result is legitimate ("nothing happened"); each
+        // block must be well formed.
+        else validateCoalescedContent(result?.content, { allowEmpty: true, checkBlockShapes: true });
         if (rendering.cancelled) throw new CancelledRender();
         content = result.content;
         timestamp = typeof result.timestamp === 'string' ? result.timestamp : new Date().toISOString();
         source = 'render';
       } catch (error) {
-        if (!(error instanceof CancelledRender)) this.host.audit({ kind: 'render-failed', subject, eventId: occurrence.eventId, error: String(error) });
+        if (!(error instanceof CancelledRender)) {
+          // The occurrence's own content is delivered instead; the host names
+          // the failure where operators look (a console line, not only this
+          // audit record).
+          this.host.audit({
+            kind: 'render-failed', subject, serverId: occurrence.serverId, eventId: occurrence.eventId,
+            ...(error instanceof CoalesceError ? { field: error.field } : {}),
+            error: String(error),
+          });
+        }
       } finally {
         const left = (this.rendersInFlight.get(occurrence.serverId) ?? 1) - 1;
         if (left > 0) this.rendersInFlight.set(occurrence.serverId, left); else this.rendersInFlight.delete(occurrence.serverId);

package/src/mcpl/push-handler.ts

@@ -18,8 +18,10 @@ import type {
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
 import { expandCoreTags } from './tags.js';
-import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
 import { isSilentHeartbeatMarker, isVisiblyEmptyContent } from './visible-content.js';
+import { logDetail, logValue } from './log-value.js';
+import { RefusalLines } from './refusal-lines.js';
 
 // ============================================================================
 // McplPushEvent (the ProcessEvent shape pushed to the queue)
@@ -55,13 +57,17 @@ export interface McplPushEvent {
 // ============================================================================
 
 /**
- * Convert a single MCPL wire-format content block to a membrane ContentBlock.
- * Same logic as hook-orchestrator.ts.
+ * Convert a single MCPL wire-format content block to a membrane ContentBlock,
+ * as the channel lane's convertBlock (channel-registry.ts) does, apart from
+ * the provenance its reference stubs name. Hook context injections convert
+ * through hook-orchestrator.ts's own.
  */
 export function convertBlock(block: McplContentBlock): ContentBlock {
   switch (block.type) {
     case 'text':
-      return { type: 'text', text: block.text };
+      // Text that isn't a string is no text, as the request sanitizer and
+      // the visible-content check already read it.
+      return { type: 'text', text: typeof block.text === 'string' ? block.text : '' };
 
     case 'image':
       if (isInlineContradiction(block)) {
@@ -69,24 +75,24 @@ export function convertBlock(block: McplContentBlock): ContentBlock {
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (block.uri && block.disposition) {
+      if (isFilledString(block.uri) && block.disposition) {
         // RFC-005 uri-form media with a disposition claim: stub, do not
         // hand the URI to the provider or inline it.
         return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
       }
-      if (block.data && block.mimeType) {
+      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
         return {
           type: 'image',
           source: { type: 'base64', data: block.data, mediaType: block.mimeType },
         } as ContentBlock;
       }
-      if (block.uri) {
+      if (isFilledString(block.uri)) {
         return {
           type: 'image',
           source: { type: 'url', url: block.uri },
         } as ContentBlock;
       }
-      return { type: 'text', text: '[Image: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? '[Image: no media type]' : '[Image: no data]' };
 
     case 'audio':
       if (isInlineContradiction(block)) {
@@ -94,31 +100,43 @@ export function convertBlock(block: McplContentBlock): ContentBlock {
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (block.uri && block.disposition) {
+      if (isFilledString(block.uri) && block.disposition) {
         // RFC-005 uri-form media with a disposition claim: stub, do not
         // hand the URI to the provider or inline it.
         return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
       }
-      if (block.data && block.mimeType) {
+      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
         return {
           type: 'audio',
           source: { type: 'base64', data: block.data, mediaType: block.mimeType },
         } as ContentBlock;
       }
-      return { type: 'text', text: '[Audio: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? '[Audio: no media type]' : '[Audio: no data]' };
 
     case 'resource':
       // RFC-005: reference blocks become bounded stubs — never raw URIs
       // (a signed URL is a bearer credential that looks like a location).
       return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
 
-    default:
+    default: {
       // Unknown wire block types previously fell off the exhaustive switch
-      // and propagated `undefined` into ContentBlock[]. Fail visibly.
-      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
+      // and propagated `undefined` into ContentBlock[]. Fail visibly. A type
+      // that isn't a string is no type, and is never converted to one: an
+      // object can throw when it is.
+      const type: unknown = (block as { type?: unknown }).type;
+      return { type: 'text', text: `[unrecognized content block: ${typeof type === 'string' ? type : 'untyped'}]` };
+    }
   }
 }
 
+/** A string with something in it: the only data, mimeType or uri a block's
+ *  source is built from, and the only uri that makes it a reference. Anything
+ *  else a sender puts there leaves the block without it, so conversion never
+ *  throws and never copies a non-string. */
+function isFilledString(value: unknown): value is string {
+  return typeof value === 'string' && value !== '';
+}
+
 // ============================================================================
 // LRU Dedup Set
 // ============================================================================
@@ -171,6 +189,9 @@ export class PushHandler {
   private emitTraceFn: (event: { type: string; [key: string]: unknown }) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
   private dedup = new DedupSet(1000);
+  /** Holds back repeats of the line for a channel-scoped push refused because
+   *  its channel isn't declared (-32023) or may not be used (-32017). */
+  private channelRefusalLines = new RefusalLines();
 
   constructor(
     featureSetManager: FeatureSetManager,
@@ -221,7 +242,7 @@ export class PushHandler {
         : 'Feature set validation failed';
       // Loud rejection — a rejected push event is an agent that silently
       // never hears the message. (2026-07-09 diagnosability pass.)
-      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${reason}`);
+      console.error(`[push-event-rejected] server=${serverId} eventId=${logValue(params.eventId ?? '')} reason=${logValue(reason)}`);
       if (err instanceof McplFeatureSetError && responder?.respondError) {
         responder.respondError(err.code, reason, { featureSet: err.featureSet });
       } else {
@@ -240,11 +261,13 @@ export class PushHandler {
     if (coalesced) {
       // RFC-006 §13: malformed content is a -32602, checked before conversion.
       try {
-        validateCoalescedContent(params.payload?.content, undefined, { allowEmpty: emptyAllowed });
+        validateCoalescedContent(params.payload?.content, { allowEmpty: emptyAllowed });
       } catch (error) {
         const err = error as Error & { code?: number; field?: string };
+        const code = err.code ?? -32602;
         if (err instanceof EmptyContentError) this.traceEmptyRejection(serverId, params);
-        if (responder?.respondError) responder.respondError(err.code ?? -32602, err.message, { field: err.field });
+        else this.traceCoalesceRejection(serverId, params, err, code);
+        if (responder?.respondError) responder.respondError(code, err.message, { field: err.field });
         else responder?.respond({ accepted: false, reason: err instanceof EmptyContentError ? err.reason : err.message });
         return;
       }
@@ -265,7 +288,7 @@ export class PushHandler {
     // coalescer's receipts instead (RFC-006 §3.1: a retry within the window
     // gets its original result, which this set could not return).
     if (!coalesced && this.dedup.checkAndAdd(params.eventId)) {
-      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=duplicate`);
+      console.error(`[push-event-rejected] server=${serverId} eventId=${logValue(params.eventId ?? '')} reason=duplicate`);
       responder?.respond({ accepted: false, reason: 'duplicate' });
       return;
     }
@@ -314,8 +337,9 @@ export class PushHandler {
         responder?.respond(result);
       } catch (error) {
         const err = error as Error & { code?: number; field?: string };
-        console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${err.message}`);
-        if (responder?.respondError) responder.respondError(typeof err.code === 'number' ? err.code : -32603, err.message, { field: err.field });
+        const code = typeof err.code === 'number' ? err.code : -32603;
+        this.traceCoalesceRejection(serverId, params, err, code);
+        if (responder?.respondError) responder.respondError(code, err.message, { field: err.field });
         else responder?.respond({ accepted: false, reason: err.message });
       }
       return;
@@ -334,13 +358,61 @@ export class PushHandler {
     responder?.respond({ accepted: true, inferenceId });
   }
 
-  /** Loud, like every other push rejection: the producer's wake went nowhere. */
+  /**
+   * A coalesced occurrence the host refused, as loud as every other push
+   * rejection: its producer is told on the wire, and until now the host said
+   * nothing, so a dropped message left no trace where operators look
+   * (agent-framework#266). The producer gets the wire answer this lane gives
+   * (`answered`): the thrown error's code and message, or -32602 for a
+   * malformed occurrence without one. The reason follows that answer
+   * (coalesceRejectionReason): `coalesce-failed` when the host itself failed,
+   * `coalesce-invalid` when the producer's occurrence was refused, with the
+   * failing `field` and the error's message as `detail`. A missing eventId
+   * prints as `""` and traces as `''`, as the channel lane's missing id does.
+   * A channel-scoped push refused because its channel isn't declared or may
+   * not be used names the channel on its line and its trace, and is refused
+   * for as long as that lasts, so its line prints at most once a minute per
+   * channel (RefusalLines); every refusal is traced.
+   */
+  private traceCoalesceRejection(
+    serverId: string,
+    params: PushEventParams,
+    error: { field?: unknown; message: string },
+    answered: number,
+  ): void {
+    const reason = coalesceRejectionReason(answered);
+    const field = typeof error.field === 'string' && error.field ? error.field : undefined;
+    const scoped = params.coalesce?.channelId;
+    const channelId = (answered === -32023 || answered === -32017) && typeof scoped === 'string' ? scoped : undefined;
+    const held = channelId === undefined ? 0 : this.channelRefusalLines.admit(serverId, channelId);
+    if (held !== null) {
+      console.error(
+        `[push-event-rejected] server=${serverId} featureSet=${logValue(params.featureSet ?? '')} eventId=${logValue(params.eventId ?? '')} ` +
+        (channelId === undefined ? '' : `channel=${logValue(channelId)} `) +
+        `reason=${reason}${field ? ` field=${logValue(field)}` : ''}: ${logDetail(error.message)}` +
+        (held ? ` (${held} more since the last line)` : ''),
+      );
+    }
+    this.emitTraceFn({
+      type: 'mcpl:push-event-rejected',
+      serverId,
+      eventId: typeof params.eventId === 'string' ? params.eventId : '',
+      featureSet: params.featureSet,
+      reason,
+      ...(field ? { field } : {}),
+      ...(channelId === undefined ? {} : { channelId }),
+      detail: error.message,
+    });
+  }
+
+  /** Loud, like every other push rejection: the producer's wake went nowhere.
+   *  A missing eventId prints as `""` and traces as `''`, as on every push line. */
   private traceEmptyRejection(serverId: string, params: PushEventParams): void {
-    console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=empty-content`);
+    console.error(`[push-event-rejected] server=${serverId} eventId=${logValue(params.eventId ?? '')} reason=empty-content`);
     this.emitTraceFn({
       type: 'mcpl:push-event-rejected',
       serverId,
-      eventId: params.eventId,
+      eventId: typeof params.eventId === 'string' ? params.eventId : '',
       featureSet: params.featureSet,
       reason: 'empty-content',
     });

package/src/mcpl/reference-fetcher.ts

@@ -29,7 +29,7 @@
  */
 import { createHash } from 'node:crypto';
 import type { ReferenceRecord } from './references.js';
-import { isReferenceExpired } from './references.js';
+import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel } from './references.js';
 
 /** Per-fetch hard ceiling on actual bytes (overridable per server / call). */
 export const DEFAULT_FETCH_MAX_BYTES = 256 * 1024 * 1024;
@@ -79,13 +79,14 @@ export function sniffMime(data: Buffer): string | null {
   return null;
 }
 
-const EXT_BY_MIME: Record<string, string> = {
+/** A Map, so a server's type such as `constructor` finds no inherited key. */
+const EXT_BY_MIME = new Map<string, string>(Object.entries({
   'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/mpeg': 'mp3', 'audio/mp4': 'm4a',
   'audio/flac': 'flac', 'audio/midi': 'mid', 'audio/ogg': 'ogg',
   'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp',
   'video/mp4': 'mp4', 'application/json': 'json', 'text/plain': 'txt',
   'application/pdf': 'pdf', 'application/zip': 'zip',
-};
+}));
 
 /** ws→http / wss→https with default ports elided, for origin comparison. */
 export function normalizedOrigin(url: string): string | null {
@@ -111,9 +112,11 @@ export class ReferenceFetcher {
     private readonly saveFile: (fileName: string, data: Buffer, mimeType: string) => Promise<string | null>,
   ) {}
 
-  /** Would the eager (autofetch) default fetch this record? */
+  /** Would the eager (autofetch) default fetch this record? Not one the
+   *  fetcher refuses as expired, which would only take an eager slot. */
   isEagerEligible(record: ReferenceRecord): boolean {
     if (record.fetchedPath) return false;
+    if (isReferenceExpired(record.testimony)) return false;
     if (record.serverId === undefined) return false;
     const binding = this.resolveServer(record.serverId);
     if (!binding) return false;
@@ -161,7 +164,8 @@ export class ReferenceFetcher {
 
     const refusal = this.originCheck(record, binding);
     if (refusal) return { ok: false, error: refusal };
-    if (isReferenceExpired(t)) return { ok: false, error: 'reference expired (or unparseable expiry — fail closed)' };
+    const expiry = referenceExpiry(t);
+    if (expiry) return { ok: false, error: `reference ${EXPIRY_REASON[expiry]}` };
 
     const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
     // Vector 4: a claim already over the ceiling refuses without dialing.
@@ -215,9 +219,15 @@ export class ReferenceFetcher {
         digestVerified = true;
       }
 
-      const headerMime = resp.headers.get('content-type')?.split(';')[0].trim() || null;
-      const observedMime = sniffMime(data) ?? headerMime ?? t.mimeType ?? 'application/octet-stream';
-      const ext = EXT_BY_MIME[observedMime] ?? EXT_BY_MIME[headerMime ?? ''] ?? EXT_BY_MIME[t.mimeType ?? ''] ?? 'bin';
+      // The response's header and the server's claimed type are both the
+      // server's words, and either can become fetch_reference's mime_type,
+      // the saved type and the record's verified type, so each is shown as a
+      // label is. One left empty once sanitized counts as absent.
+      const header = resp.headers.get('content-type');
+      const headerMime = header !== null ? sanitizeLabel(header.split(';')[0], REFERENCE_LIMITS.mimeType) || null : null;
+      const claimedMime = t.mimeType !== undefined ? sanitizeLabel(t.mimeType, REFERENCE_LIMITS.mimeType) || undefined : undefined;
+      const observedMime = sniffMime(data) ?? headerMime ?? claimedMime ?? 'application/octet-stream';
+      const ext = EXT_BY_MIME.get(observedMime) ?? EXT_BY_MIME.get(headerMime ?? '') ?? EXT_BY_MIME.get(claimedMime ?? '') ?? 'bin';
       // §7.3: host-generated storage name; the server's `name` is display-only.
       const path = await this.saveFile(`${record.refId}.${ext}`, data, observedMime);
       if (path === null) return { ok: false, error: 'no writable workspace mount to store the payload' };

package/src/mcpl/references.ts

@@ -13,7 +13,8 @@
  *  - `disposition:"never"` withholds payload AND uri from model context
  *    unconditionally — enforced in code here, not by caller discipline (§5);
  *  - stub size is independent of every server-supplied field length (§5);
- *  - unparseable `expiresAt` fails closed (§7.4);
+ *  - unparseable `expiresAt` fails closed (§7.4), and so does one rejected
+ *    as a field: it's absent as testimony, never read as immortal;
  *  - unknown block types never propagate `undefined` (the pre-existing
  *    convertBlock switches had no default — a latent corruption this module
  *    retires).
@@ -141,16 +142,42 @@ export function isInlineContradiction(block: unknown): boolean {
 export const INLINE_WITHHELD_TEXT =
   '[inline content withheld: nonconformant bulk disposition on inline data]';
 
-export function isReferenceExpired(t: Pick<ReferenceTestimony, 'expiresAt'>, nowMs = Date.now()): boolean {
-  if (t.expiresAt === undefined) return false;
+/**
+ * Why a reference counts as expired, or null when it doesn't: its expiresAt
+ * has passed, doesn't parse, or was rejected as a field (§7.4, §8). A
+ * rejected expiry (past its schema maximum, or not a string, null included)
+ * is absent as testimony under the one invalid-field rule, but reading that
+ * absence as "never expires" would let field invalidity widen exposure:
+ * like an unparseable one, it fails closed. A reference that claims no
+ * expiry has none.
+ */
+export function referenceExpiry(
+  t: Pick<ReferenceTestimony, 'expiresAt' | 'rejectedFields'>, nowMs = Date.now(),
+): 'rejected' | 'unparseable' | 'passed' | null {
+  if (t.rejectedFields.includes('expiresAt')) return 'rejected';
+  if (t.expiresAt === undefined) return null;
   const exp = Date.parse(t.expiresAt);
-  return Number.isNaN(exp) ? true : exp <= nowMs;
+  if (Number.isNaN(exp)) return 'unparseable';
+  return exp <= nowMs ? 'passed' : null;
+}
+
+export function isReferenceExpired(t: Pick<ReferenceTestimony, 'expiresAt' | 'rejectedFields'>, nowMs = Date.now()): boolean {
+  return referenceExpiry(t, nowMs) !== null;
 }
 
-/** Strip C0/C1 controls plus bidi marks/overrides/isolates; bound length.
+/** Each expiry case as the stub and the fetcher's refusal both say it. */
+export const EXPIRY_REASON = {
+  passed: 'expired: its expiresAt has passed',
+  unparseable: 'treated as expired: its expiresAt does not parse (fail closed)',
+  rejected: `treated as expired: its expiresAt was rejected as a field, over ${REFERENCE_LIMITS.expiresAt} characters or not a string (fail closed)`,
+} as const;
+
+/** Strip control characters (C0, DEL, C1) and every bidi control (marks,
+ *  embeddings, overrides, isolates, and the Arabic letter mark), trim the
+ *  whitespace (a BOM included) left at either end, and bound the length.
  *  Labels are labels — storage naming is host-generated elsewhere (§7.3). */
 export function sanitizeLabel(s: string, maxChars: number): string {
-  const cleaned = s.replace(/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, '');
+  const cleaned = s.replace(/[\p{Cc}\p{Bidi_Control}]/gu, '').trim();
   if (cleaned.length <= maxChars) return cleaned;
   let cut = cleaned.slice(0, Math.max(0, maxChars - 1));
   // never split a surrogate pair at the truncation boundary
@@ -187,9 +214,10 @@ const MAX_RECORDS = 2000;
 /**
  * Host-private store of received references. Raw URIs live here and in stubs
  * never (under `never`) or by policy only (`ref`/absent). Ids are stable and
- * never reused within the process (vector 20); eviction is FIFO past
- * MAX_RECORDS and a stale lookup returns undefined — a defined miss, never a
- * different record.
+ * never reused within the process (vector 20). Past MAX_RECORDS the record
+ * registered least recently is evicted (registering a uri the registry holds
+ * makes its record the newest), and a stale lookup returns undefined — a
+ * defined miss, never a different record.
  *
  * Process-wide singleton by design: ids are host-local *names*, not
  * capabilities, and the record itself carries serverId for any future
@@ -222,6 +250,9 @@ export class ReferenceRegistry {
         // describes verified bytes on disk and keeps the testimony they were
         // verified against.
         if (!existing.fetchedPath) existing.testimony = testimony;
+        // Newest again, so a uri just mentioned is the last to be evicted.
+        this.records.delete(existingId);
+        this.records.set(existingId, existing);
         return existing;
       }
     }
@@ -257,6 +288,12 @@ export const referenceRegistry = new ReferenceRegistry();
 // Stub building (§5)
 // ============================================================================
 
+/** A reference's type as its stub shows one, or '' when nothing is left of
+ *  it once sanitized (the stub then leaves it out). */
+export function referenceTypeLabel(mimeType: string | undefined): string {
+  return mimeType ? sanitizeLabel(mimeType, STUB_FIELD_CHARS) : '';
+}
+
 /**
  * Build the model-visible stub for a reference. Output length is bounded by
  * host constants and independent of every server-supplied field length.
@@ -267,18 +304,25 @@ export const referenceRegistry = new ReferenceRegistry();
 export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, serverId?: string): string {
   const record = referenceRegistry.register(t, serverId);
   const parts: string[] = [];
-  if (t.name) parts.push(sanitizeLabel(t.name, STUB_FIELD_CHARS));
+  // A label is shown only when something is left of it once sanitized.
+  const name = t.name ? sanitizeLabel(t.name, STUB_FIELD_CHARS) : '';
+  if (name) parts.push(name);
   const meta: string[] = [];
-  if (t.mimeType) meta.push(sanitizeLabel(t.mimeType, STUB_FIELD_CHARS));
+  const mimeType = referenceTypeLabel(t.mimeType);
+  if (mimeType) meta.push(mimeType);
   if (t.sizeBytes !== undefined) meta.push(`${formatSizeBytes(t.sizeBytes)} claimed`);
   if (meta.length) parts.push(meta.join(', '));
-  if (provenance) parts.push(sanitizeLabel(provenance, STUB_FIELD_CHARS));
+  const origin = provenance ? sanitizeLabel(provenance, STUB_FIELD_CHARS) : '';
+  if (origin) parts.push(origin);
   if (record.fetchedPath) {
     // Already materialized by the host-mediated fetcher: hand the model the
     // workspace path (host-generated, §7.3) so existing tools just work.
     parts.push(`saved: ${sanitizeLabel(record.fetchedPath, 256)}`);
   } else {
-    parts.push('fetch with fetch_reference');
+    // An expired reference says so rather than inviting a fetch_reference
+    // call the fetcher can only refuse.
+    const expiry = referenceExpiry(record.testimony);
+    parts.push(expiry ? EXPIRY_REASON[expiry] : 'fetch with fetch_reference');
   }
   return `[${record.refId}] ${parts.join(' — ') || 'referenced content'}`;
 }

package/src/mcpl/refusal-lines.ts

@@ -0,0 +1,59 @@
+import { logValue } from './log-value.js';
+
+/**
+ * At most one host line a minute for a refusal a server keeps repeating for
+ * as long as a standing condition lasts: messages for a channel it never
+ * registered, or channel-scoped pushes to a channel it hasn't declared or may
+ * not use. A server that never registered a busy channel would otherwise
+ * print a line for every message in it. Only the line is held back: every
+ * refusal is still answered and traced. Each lane keeps its own records, as
+ * its lines are its own.
+ *
+ * Per server and channel, the first refusal prints. After that a refusal
+ * prints only once a minute has passed since that channel's last line, and
+ * its line names how many were held back since. The minute is timed with a
+ * monotonic clock, so a step of the wall clock can't silence a channel. A
+ * refusal within a minute of the channel's last line is counted into its
+ * next line, whatever happens to the channel in between (it may be
+ * registered, unregistered or reconnected).
+ *
+ * A record is keyed by the channel as its line prints it (logValue), so two
+ * ids share one exactly when their lines name them alike, which only ids
+ * over 256 units can. The records cover the 1,000 most recently refused
+ * channels: a new channel evicts the least recently refused one, with its
+ * minute and any count it held, and that channel's next refusal prints as a
+ * first.
+ */
+export class RefusalLines {
+  /** By key, from the least recently refused channel to the most. */
+  private readonly records = new Map<string, { at: number; since: number }>();
+
+  constructor(private readonly now: () => number = () => performance.now()) {}
+
+  /**
+   * Record one refusal for a server's channel. Returns null when its line is
+   * held back, or else how many of the channel's refusals were held back
+   * since its last line (0 for its first).
+   */
+  admit(serverId: string, channelId: string): number | null {
+    // logValue never prints a NUL, so the key's last NUL keeps the two apart
+    // whatever a server id holds.
+    const key = `${serverId}\u0000${logValue(channelId)}`;
+    const now = this.now();
+    const record = this.records.get(key);
+    if (record) this.records.delete(key);
+    else if (this.records.size >= MAX_CHANNELS) this.records.delete(this.records.keys().next().value!);
+    if (!record || now - record.at >= EVERY_MS) {
+      this.records.set(key, { at: now, since: 0 });
+      return record?.since ?? 0;
+    }
+    record.since++;
+    this.records.set(key, record);
+    return null;
+  }
+}
+
+/** A channel's line prints at most this often. */
+const EVERY_MS = 60_000;
+/** The channels the records cover at once. */
+const MAX_CHANNELS = 1_000;