@animalabs/agent-framework 0.21.1 → 0.22.1

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 { isVisiblyEmptyContent } from './visible-content.js';
 
 export const PUSH_COALESCING_SUPPORT = {
   pushEvents: true, channelsIncoming: true, deferred: true, channelScopedPush: true,
@@ -36,6 +37,15 @@ export class CoalesceError extends Error {
   }
 }
 
+/** Content with nothing model-visible (see visible-content.ts): -32602. */
+export class EmptyContentError extends CoalesceError {
+  readonly reason = 'empty-content';
+  constructor(field = 'payload.content') {
+    super(field, 'content has no visible content: send at least one non-text block or non-whitespace text');
+    this.name = 'EmptyContentError';
+  }
+}
+
 /** Where an unread occurrence currently lives. */
 export interface CoalescingPlacement {
   agent: string;
@@ -100,6 +110,18 @@ interface Rendering<E> {
   batch: DeferredBatch<E>;
   cancelled: boolean;
   done: Promise<void>;
+  /** Set once the render (or its fallback) was delivered as content. */
+  materialized?: boolean;
+}
+
+/** What an assembly did, per subject, for the turn being assembled. */
+export interface AssemblyResult {
+  /** Subjects whose render this assembly waited on to completion. */
+  settled: Set<string>;
+  /** Of those, the subjects whose render or fallback was delivered as content.
+   *  A settled subject that is not here gave the turn nothing to read: empty
+   *  or blank render (§5.2), cancelled, or revoked at response. */
+  materialized: Set<string>;
 }
 
 interface SubjectState<E> {
@@ -207,8 +229,20 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
   return out;
 }
 
-/** Validate wire content before it is stored, rendered or converted. */
-export function validateCoalescedContent(content: unknown, maxBytes = 1024 * 1024): asserts content is McplContentBlock[] {
+/**
+ * Validate wire content before it is stored, rendered or converted.
+ *
+ * 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
+ * with nothing to announce (§6) and a render result that says nothing
+ * happened (§5.2) — and for the silent-heartbeat marker.
+ */
+export function validateCoalescedContent(
+  content: unknown,
+  maxBytes = 1024 * 1024,
+  options: { allowEmpty?: 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');
@@ -219,6 +253,7 @@ export function validateCoalescedContent(content: unknown, maxBytes = 1024 * 102
     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();
 }
 
 /** Validate the `coalesce` member of either lane (§13). */
@@ -486,7 +521,9 @@ export class PushCoalescer<E = unknown> {
     this.host.cancelWake(subject);
     state.consumedEventId = undefined;
     if (state.history === 'none') return 'retracted';
-    if (!occurrence.content.length) return 'consumed';
+    // An empty notice — or one with only blank text, which would reach the
+    // model as an empty message — is pure withdrawal: append nothing.
+    if (isVisiblyEmptyContent(occurrence.content)) return 'consumed';
     // The notice is an ordinary occurrence: it rides the normal delivery path
     // (tags → gate policy → wake) and is consumed like any message — in the
     // context that read a version, never a new one (§3.2).
@@ -563,20 +600,29 @@ export class PushCoalescer<E = unknown> {
    * Render and materialize every pending batch whose audience includes
    * `agentName`. Called by the host at a turn's assembly boundary, before the
    * compile. Bounded by the host's render timeout; a failed or late render
-   * materializes the admitted fallback (§5.3).
+   * materializes the admitted fallback (§5.3). Reports which subjects
+   * settled and which of them produced content, so the host can tell a turn
+   * whose only cause rendered nothing.
    */
-  async assemble(agentName: string): Promise<void> {
-    if (this.suspended) return;
+  async assemble(agentName: string): Promise<AssemblyResult> {
+    const result: AssemblyResult = { settled: new Set(), materialized: new Set() };
+    if (this.suspended) return result;
     const work: Promise<void>[] = [];
     for (const subject of [...this.subjects.keys()]) {
       // The handle is wrapped: a bare promise returned through `locked` would
       // be flattened by `then`, holding the lock until the render settled —
       // and the settlement itself needs the lock.
       const started = await this.locked(() => this.freeze(subject, agentName));
-      if (started) work.push(started.done);
+      if (started) {
+        work.push(started.done.then(() => {
+          result.settled.add(subject);
+          if (started.rendering.materialized) result.materialized.add(subject);
+        }));
+      }
     }
     await Promise.all(work);
     this.persist();
+    return result;
   }
 
   /**
@@ -585,13 +631,13 @@ export class PushCoalescer<E = unknown> {
    * the RPC. Returns the render's completion (shared by every assembly that
    * waits on this batch, vector 25) or undefined when nothing was started.
    */
-  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void> } | undefined> {
+  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void>; rendering: Rendering<E> } | undefined> {
     const state = this.subjects.get(subject);
     if (!state || this.suspended) return undefined;
     if (state.rendering) {
       // Another assembly froze this batch; share its outcome (vector 25).
       const rendering = state.rendering;
-      return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done } : undefined;
+      return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done, rendering } : undefined;
     }
     const batch = state.batch;
     if (!batch) return undefined;
@@ -634,7 +680,7 @@ export class PushCoalescer<E = unknown> {
       return undefined;
     }
     rendering.done = this.render(subject, state, rendering, agentName);
-    return { done: rendering.done };
+    return { done: rendering.done, rendering };
   }
 
   private async render(subject: string, state: SubjectState<E>, rendering: Rendering<E>, assemblingFor: string): Promise<void> {
@@ -654,7 +700,8 @@ 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 }); }
-        else validateCoalescedContent(result?.content, this.options.maxContentBytes);
+        // §5.2: an empty result is legitimate ("nothing happened").
+        else validateCoalescedContent(result?.content, this.options.maxContentBytes, { allowEmpty: true });
         if (rendering.cancelled) throw new CancelledRender();
         content = result.content;
         timestamp = typeof result.timestamp === 'string' ? result.timestamp : new Date().toISOString();
@@ -673,9 +720,11 @@ export class PushCoalescer<E = unknown> {
         if (rendering.cancelled || state.rendering !== rendering || this.suspended) return;
         // Rule 4: authority is re-checked at response.
         if (!this.host.authorized(occurrence)) { this.host.audit({ kind: 'revoked', subject, eventId: occurrence.eventId }); return; }
-        this.host.audit({ kind: 'rendered', subject, eventId: occurrence.eventId, source, empty: content.length === 0 });
-        if (!content.length) return; // §5.2: nothing happened
+        const empty = isVisiblyEmptyContent(content);
+        this.host.audit({ kind: 'rendered', subject, eventId: occurrence.eventId, source, empty });
+        if (empty) return; // §5.2: nothing happened (blank text included)
         const placement = await this.host.deliver({ ...occurrence, timestamp, content }, content, assemblingFor);
+        rendering.materialized = true;
         if (placement?.deferredId) {
           // Landed in another agent's deferred queue (its turn is alive): still
           // unread there, so it stays replaceable and withdrawable.

package/src/mcpl/push-handler.ts

@@ -18,7 +18,8 @@ import type {
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
 import { expandCoreTags } from './tags.js';
-import { validateCoalescedContent } from './push-coalescer.js';
+import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { isSilentHeartbeatMarker, isVisiblyEmptyContent } from './visible-content.js';
 
 // ============================================================================
 // McplPushEvent (the ProcessEvent shape pushed to the queue)
@@ -188,9 +189,9 @@ export class PushHandler {
    * Handle a push/event message from an MCPL server.
    *
    * 1. Validate feature set
-   * 2. Deduplicate by eventId
-   * 3. Optionally check shouldTriggerInference callback
-   * 4. Convert content blocks
+   * 2. Convert content blocks; reject visibly-empty content
+   * 3. Deduplicate by eventId
+   * 4. Optionally check shouldTriggerInference callback
    * 5. Push event to queue
    * 6. Emit trace
    * 7. Respond with accepted + inferenceId
@@ -229,30 +230,46 @@ export class PushHandler {
       return;
     }
 
-    // 2. Deduplicate by eventId. A coalesced occurrence is deduplicated by the
-    // coalescer's receipts instead (RFC-006 §3.1: a retry within the window
-    // gets its original result, which this set could not return).
     const coalesced = params.coalesce !== undefined && !!this.handleCoalesced;
+    // Empty content is meaningful only for a coalescing retraction (pure
+    // withdrawal, RFC-006 §6 — the coalescer appends nothing for it) and for
+    // the silent-heartbeat marker. Anything else that shows the model nothing
+    // would wake it with no visible cause.
+    const emptyAllowed = (coalesced && params.coalesce?.retract === true)
+      || isSilentHeartbeatMarker({ serverId, featureSet: params.featureSet, origin: params.origin, content: params.payload?.content });
     if (coalesced) {
       // RFC-006 §13: malformed content is a -32602, checked before conversion.
       try {
-        validateCoalescedContent(params.payload?.content);
+        validateCoalescedContent(params.payload?.content, undefined, { allowEmpty: emptyAllowed });
       } catch (error) {
         const err = error as Error & { code?: number; field?: string };
+        if (err instanceof EmptyContentError) this.traceEmptyRejection(serverId, params);
         if (responder?.respondError) responder.respondError(err.code ?? -32602, err.message, { field: err.field });
-        else responder?.respond({ accepted: false, reason: err.message });
+        else responder?.respond({ accepted: false, reason: err instanceof EmptyContentError ? err.reason : err.message });
         return;
       }
     }
+
+    // 2. Convert content blocks, and refuse content with nothing visible in
+    // it — before dedup, so a refused eventId is not burned for a retry.
+    const content: ContentBlock[] = params.payload.content.map(convertBlock);
+    if (!emptyAllowed && isVisiblyEmptyContent(content)) {
+      const err = new EmptyContentError();
+      this.traceEmptyRejection(serverId, params);
+      if (responder?.respondError) responder.respondError(err.code, err.message, { field: err.field });
+      else responder?.respond({ accepted: false, reason: err.reason });
+      return;
+    }
+
+    // 3. Deduplicate by eventId. A coalesced occurrence is deduplicated by the
+    // 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`);
       responder?.respond({ accepted: false, reason: 'duplicate' });
       return;
     }
 
-    // 3. Convert content blocks
-    const content: ContentBlock[] = params.payload.content.map(convertBlock);
-
     // 4. Check shouldTriggerInference callback
     let triggerInference = true;
     if (this.shouldTriggerInference) {
@@ -316,4 +333,16 @@ export class PushHandler {
     // 8. Respond
     responder?.respond({ accepted: true, inferenceId });
   }
+
+  /** Loud, like every other push rejection: the producer's wake went nowhere. */
+  private traceEmptyRejection(serverId: string, params: PushEventParams): void {
+    console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=empty-content`);
+    this.emitTraceFn({
+      type: 'mcpl:push-event-rejected',
+      serverId,
+      eventId: 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/server-connection.ts

@@ -48,6 +48,28 @@ import type {
 import { McplMethod } from './types.js';
 import type { ToolLifecycleParams, ToolObserveRule } from './tool-lifecycle.js';
 
+/**
+ * Payload of the connection `'close'` event (third argument; the first two
+ * stay `(code, signal)` for existing listeners). Lets a host see WHY the
+ * link went down — in particular a WebSocket close code such as 4001 from
+ * a server that refused or expired the credential — so it can refresh what
+ * `accessProvider` will hand the next dial instead of replaying it.
+ */
+export interface McplConnectionCloseInfo {
+  /** Transport kind that closed; null when the connection never had one
+   *  (a disconnected stub torn down before its first reconnect). */
+  transport: McplTransport['kind'] | null;
+  /** WebSocket close code (e.g. 4001) or stdio child exit code; null when unknown. */
+  code: number | null;
+  /** Signal that ended a stdio child; null otherwise. */
+  signal: NodeJS.Signals | null;
+  /** WebSocket close reason, or a short description of the cause. */
+  reason?: string;
+  /** True when the host closed the link (`close()` / `reconnectAfterFailure()`),
+   *  false when the transport dropped unexpectedly. */
+  byHost: boolean;
+}
+
 /** Timeout for the initialize handshake in milliseconds.
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
@@ -93,7 +115,7 @@ interface RequestOptions {
  * - `'channels-changed'`   — Server sent `channels/changed`
  * - `'channels-incoming'`  — Server sent `channels/incoming`
  * - `'error'`              — Connection-level error
- * - `'close'`              — Connection closed
+ * - `'close'`              — Connection closed: `(code, signal, info: McplConnectionCloseInfo)`
  * - `'connect-failed'`     — Initial connect failed; background retry scheduled
  * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled
  * - `'reconnect'`          — Background reconnect succeeded
@@ -209,6 +231,12 @@ export class McplServerConnection extends EventEmitter {
    * observable even though its original promise has already been rejected. */
   private orphanedRequests = new Map<string | number, { method: string; renderParams?: Record<string, unknown> }>();
   private closed = false;
+  /** Set by `reconnectAfterFailure()` before it closes a live transport, so
+   *  the transport close handler reports that teardown as `byHost: true`. */
+  private hostCloseRequested = false;
+  private closePromise: Promise<void> | null = null;
+  private closeIncomplete = false;
+  private reconnectPromise: Promise<void> | null = null;
 
   /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
   private requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
@@ -837,10 +865,10 @@ export class McplServerConnection extends EventEmitter {
       this.reconnectTimer = null;
     }
 
-    if (this.closed) {
-      return;
-    }
+    if (this.closePromise) return this.closePromise;
+    if (this.closed && !this.closeIncomplete && !this.reconnectPromise) return;
     this.closed = true;
+    this.closeIncomplete = true;
     this.resetPolicyForTransportBoundary();
 
     // Reject all pending requests
@@ -854,11 +882,20 @@ export class McplServerConnection extends EventEmitter {
     // Tear down the transport (kills the child / closes the socket). The
     // transport's own 'close' event is short-circuited by `this.closed` in
     // setupLifecycle, so this is the single source of the connection 'close'.
-    if (this.transport) {
-      await this.transport.close();
-    }
-
-    this.emit('close');
+    const attempt = Promise.resolve().then(async () => {
+      // An already opened handshake owns a transport too. It hands that
+      // transport back without admission once reconnect has been disabled.
+      // The registry bounds this wait; retry reuses this real close attempt.
+      if (this.reconnectPromise) await this.reconnectPromise;
+      if (this.transport) await this.transport.close();
+      this.closeIncomplete = false;
+      this.emit('close', null, null, this.closeInfoByHost());
+    });
+    this.closePromise = attempt;
+    void attempt.catch(() => {
+      if (this.closePromise === attempt) this.closePromise = null;
+    });
+    return attempt;
   }
 
   /**
@@ -874,14 +911,26 @@ export class McplServerConnection extends EventEmitter {
       return;
     }
     if (this.transport) {
+      this.hostCloseRequested = true;
       await this.transport.close();
       return;
     }
     this.closed = true;
-    this.emit('close');
+    this.emit('close', null, null, this.closeInfoByHost());
     this.scheduleReconnect();
   }
 
+  /** 'close' payload for a host-initiated teardown (no transport close code). */
+  private closeInfoByHost(): McplConnectionCloseInfo {
+    return {
+      transport: this.transport?.kind ?? null,
+      code: null,
+      signal: null,
+      reason: 'closed by host',
+      byHost: true,
+    };
+  }
+
   /**
    * Schedule a background reconnection attempt.
    *
@@ -912,8 +961,19 @@ export class McplServerConnection extends EventEmitter {
    * approach this builds no throwaway connection instance, so there are no
    * leaked listeners on a dead object.
    */
-  private async attemptReconnect(): Promise<void> {
-    if (!this.reconnectEnabled || !this.config || !this.hostCapabilities) return;
+  private attemptReconnect(): Promise<void> {
+    if (this.reconnectPromise) return this.reconnectPromise;
+    const attempt = this.reconnectOnce();
+    this.reconnectPromise = attempt;
+    const clear = () => { if (this.reconnectPromise === attempt) this.reconnectPromise = null; };
+    void attempt.then(clear, clear);
+    return attempt;
+  }
+
+  private async reconnectOnce(): Promise<void> {
+    // A queued recovery timer may outlive an earlier successful handshake.
+    // Recheck disconnection before opening or replacing any owned transport.
+    if (!this.closed || !this.reconnectEnabled || !this.config || !this.hostCapabilities) return;
 
     // Ordinal of this attempt: 0 was the initial connect, so the Nth retry
     // reports attempt N (reconnectAttempts counts failures so far).
@@ -925,6 +985,14 @@ export class McplServerConnection extends EventEmitter {
         this.hostCapabilities,
       );
 
+      if (!this.reconnectEnabled) {
+        // The prior transport was disconnected before this retry began. Keep
+        // the fresh, unadmitted transport owned by close(), including on a
+        // failed transport cleanup, instead of reviving a stopped connection.
+        this.transport = transport;
+        return;
+      }
+
       // Close the data plane before the new transport can emit. The reconnect
       // lifecycle event bypasses buffering; its framework listener installs the
       // awareness barrier synchronously, then releases control traffic needed
@@ -1254,6 +1322,7 @@ export class McplServerConnection extends EventEmitter {
    * and — when enabled — schedules a background reconnect.
    */
   private setupLifecycle(transport: McplTransport): void {
+    this.hostCloseRequested = false;
     transport.on('error', (err: Error) => {
       this.emit('error', new Error(`MCPL server "${this.id}" transport error: ${err.message}`));
     });
@@ -1275,7 +1344,20 @@ export class McplServerConnection extends EventEmitter {
         this.pendingRequests.clear();
         this.orphanedRequests.clear();
 
-        this.emit('close', info.code ?? null, info.signal ?? null);
+        // Forward the transport's close info so listeners can tell a server
+        // that refused the credential (WebSocket 4001) from a crash, and act
+        // before the reconnect below redials. A teardown the host asked for
+        // via reconnectAfterFailure() arrives here too; report it as such.
+        const byHost = this.hostCloseRequested;
+        this.hostCloseRequested = false;
+        const closeInfo: McplConnectionCloseInfo = {
+          transport: transport.kind,
+          code: info.code ?? null,
+          signal: info.signal ?? null,
+          reason: info.reason ?? (byHost ? 'closed by host' : undefined),
+          byHost,
+        };
+        this.emit('close', closeInfo.code, closeInfo.signal, closeInfo);
 
         // Schedule reconnect if enabled (unexpected disconnect triggers auto-reconnect)
         if (this.reconnectEnabled) {