@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/gate/event-gate.ts

@@ -11,6 +11,8 @@
  * inference tokens, not whether the agent should know about the event.
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
+import { cutToFit, suppliedValue } from '../supplied-text.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
@@ -343,7 +345,7 @@ function referenceLine(count: number, channel: string, oldest: number, now: numb
 /** A handed batched-wake line's text (WakeLine), as it reads when written at
  *  `now`: the gate's words, its message's age counted to then. */
 export function wakeLineText(line: WakeLine, now: number): string {
-  return `[Gate: 1 event matched]\n\n${referenceLine(1, line.shown, line.at, now)}`;
+  return `[${NOTICE_TAG.gate}: 1 event matched]\n\n${referenceLine(1, line.shown, line.at, now)}`;
 }
 
 /** The event's own stored entry, as the framework is asked about it. */
@@ -1825,30 +1827,72 @@ function globAtLeastAsBroad(earlier: string | undefined, later: string | undefin
   return earlier === later;
 }
 
+/** The event types the gate can see from an MCPL server: its pushes and its
+ *  channels' messages. */
+export const MCPL_GATE_EVENT_TYPES: readonly string[] = ['mcpl:push-event', 'mcpl:channel-incoming'];
+
+/** The event types a host knows a source sends (EventGate's
+ *  `eventTypesFrom`), or undefined when it could send any. */
+export type EventTypesFrom = (source: string) => readonly string[] | undefined;
+
+/** The event types `rule` can match: its scope's, narrowed to those its
+ *  source is known to send; 'all' when neither says. */
+function typesSeenBy(rule: GatePolicy, eventTypesFrom?: EventTypesFrom): { types: string[] | 'all'; known: boolean } {
+  const scope = rule.match.scope && rule.match.scope.length > 0 ? rule.match.scope : undefined;
+  const source = rule.match.source;
+  let sent: readonly string[] | undefined;
+  if (eventTypesFrom && source !== undefined && !source.includes('*')) {
+    try {
+      sent = eventTypesFrom(source);
+    } catch {
+      sent = undefined;
+    }
+  }
+  if (scope && sent) return { types: scope.filter((t) => sent!.includes(t)), known: true };
+  if (scope) return { types: scope, known: true };
+  if (sent) return { types: [...sent], known: true };
+  return { types: 'all', known: false };
+}
+
 /**
- * Event types for which `earlier` provably matches EVERY event that `later`
- * would match — i.e. the types for which `later` is unreachable when
- * `earlier` sits before it and consumes its matches. Returns null when
- * subsumption can't be proven (which is not proof of safety — the lint is
- * deliberately one-sided so every warning it emits is true).
+ * Whether `earlier` provably matches events `later` would match, so that
+ * `later` doesn't see them when `earlier` sits before it and consumes its
+ * matches: the event types concerned, whether that's every event `later`
+ * would match, and whether `later` is known to see those types. Returns null
+ * when it can't be proven (which is not proof of safety — the lint is
+ * deliberately one-sided so every note it emits is true).
  */
-function subsumedEventTypes(earlier: GatePolicy, later: GatePolicy): string[] | 'all' | null {
+function subsumedEventTypes(
+  earlier: GatePolicy,
+  later: GatePolicy,
+  eventTypesFrom?: EventTypesFrom,
+): Omit<ShadowWarning, 'earlier' | 'later'> | null {
   const e = earlier.match;
   const l = later.match;
 
-  // Scope: which of `later`'s event types does `earlier` cover?
-  let covered: string[] | 'all';
-  if (!e.scope || e.scope.length === 0) {
-    covered = l.scope && l.scope.length > 0 ? l.scope : 'all';
-  } else if (!l.scope || l.scope.length === 0) {
-    // `later` matches all types; `earlier` only consumes its own scope, so
-    // the shadow is partial — exactly those types.
-    covered = e.scope;
+  // Event types: which of those `later` can match does `earlier` cover?
+  const seen = typesSeenBy(later, eventTypesFrom);
+  const earlierTypes = e.scope && e.scope.length > 0 ? e.scope : 'all';
+  let eventTypes: string[] | 'all';
+  let whole: boolean;
+  let known = seen.known;
+  if (earlierTypes === 'all') {
+    eventTypes = seen.types;
+    whole = true;
+  } else if (seen.types === 'all') {
+    // `later` matches every type; `earlier` only consumes its own scope, so
+    // the overlap is partial — exactly those types, which may never reach
+    // `later`.
+    eventTypes = earlierTypes;
+    whole = false;
   } else {
-    const overlap = l.scope.filter((t) => e.scope!.includes(t));
+    const overlap = seen.types.filter((t) => earlierTypes.includes(t));
     if (overlap.length === 0) return null;
-    covered = overlap;
+    eventTypes = overlap;
+    whole = overlap.length === seen.types.length;
+    known = true;
   }
+  if (Array.isArray(eventTypes) && eventTypes.length === 0) return null;
 
   // Every remaining discriminator on `earlier` must be at least as broad as
   // `later`'s, otherwise some `later` events slip past `earlier`.
@@ -1876,38 +1920,55 @@ function subsumedEventTypes(earlier: GatePolicy, later: GatePolicy): string[] |
   if (e.tagsAll && !subsetOf(e.tagsAll, l.tagsAll ?? [])) return null;
   if (e.tagsNone && !subsetOf(e.tagsNone, l.tagsNone ?? [])) return null;
 
-  return covered;
+  return { eventTypes, whole, known };
 }
 
 /**
- * Find rules made unreachable by earlier, broader rules (first match wins).
+ * Find rules an earlier, broader rule keeps from applying (first match wins),
+ * in whole or for some event types.
  * The 2026-08-08 Mythos incident is the canonical catch: a prepended
  * `{scope:[mcpl:channel-incoming]}` sampler silently made the
  * direct-address and mention rules dead for the whole incoming lane.
  * `passthrough` observers shadow nothing — non-firing matches fall through.
+ * `eventTypesFrom` leaves out types a rule's source is known never to send:
+ * a rule for an MCPL server's events isn't told about another rule that
+ * takes every `external-message`.
  */
-export function findShadowedPolicies(policies: GatePolicy[]): ShadowWarning[] {
+export function findShadowedPolicies(policies: GatePolicy[], eventTypesFrom?: EventTypesFrom): ShadowWarning[] {
   const out: ShadowWarning[] = [];
   for (let i = 0; i < policies.length; i++) {
     const earlier = policies[i];
     if (earlier.passthrough) continue;
     for (let j = i + 1; j < policies.length; j++) {
-      const covered = subsumedEventTypes(earlier, policies[j]);
-      if (covered) {
-        out.push({ earlier: earlier.name, later: policies[j].name, eventTypes: covered });
+      const found = subsumedEventTypes(earlier, policies[j], eventTypesFrom);
+      if (found) {
+        out.push({ earlier: earlier.name, later: policies[j].name, ...found });
       }
     }
   }
   return out;
 }
 
-/** Human-readable one-liner for a ShadowWarning, used in tool results,
- *  traces, and gate_status alike so the same hazard reads the same way
- *  everywhere. */
+/** A ShadowWarning in words, used in tool results, traces, and gate_status
+ *  alike so the same note reads the same way everywhere. It says which of
+ *  three it is (the rule never applies; it misses some of its events; it
+ *  may not be meant for those events at all) and what to do. */
 export function formatShadowWarning(w: ShadowWarning): string {
-  const types = w.eventTypes === 'all' ? 'ALL event types' : w.eventTypes.join(', ');
-  return `rule "${w.earlier}" makes "${w.later}" unreachable for ${types} `
-    + `(first match wins — every event "${w.later}" would match is consumed by "${w.earlier}" first)`;
+  const later = `"${w.later}"`;
+  const earlier = `"${w.earlier}"`;
+  const move = `move ${later} above ${earlier} (wake_add_rule with the whole rule and insertBefore: "${w.earlier}")`;
+  if (w.whole) {
+    return `${later} never applies: ${earlier} comes first and matches every event ${later} would. `
+      + `If ${later} should apply, ${move}, or narrow ${earlier}.`;
+  }
+  const types = w.eventTypes === 'all' ? 'all' : w.eventTypes.join(', ');
+  if (w.known) {
+    return `${earlier} comes first and takes ${later}'s ${types} events, so ${later} applies only to its others. `
+      + `If it should apply to those too, ${move}.`;
+  }
+  return `${earlier} comes first and takes every ${types} event, so ${later} sees none. `
+    + `Nothing to do unless ${later} is meant for ${types} events; then ${move}. `
+    + `A scope on ${later} naming the event types it's for clears this note.`;
 }
 
 /** The text of a thrown value, for a log line. It never throws itself, whatever was thrown. */
@@ -2035,10 +2096,12 @@ export class EventGate {
   // Per-policy stats
   private stats = new Map<string, PolicyStats>();
 
-  // Shadow-lint cache (see refreshShadowWarnings) — recomputed on every
-  // config change, fingerprinted so an unchanged hazard set doesn't re-trace.
-  private shadowWarningsCache: ShadowWarning[] = [];
+  // The shadow lint's last findings (see refreshShadowWarnings), recomputed
+  // on every config change and fingerprinted so an unchanged set doesn't
+  // re-trace.
   private shadowWarningsFingerprint = '[]';
+  /** See the constructor's `eventTypesFrom`. */
+  private eventTypesFromFn: EventTypesFrom | undefined;
 
   // Observability counters for events that didn't match any policy
   private totalEvaluations = 0;
@@ -2093,6 +2156,8 @@ export class EventGate {
   ) => unknown;
   private requestInferenceFn: (agentName: string, reason: string, source: string, provenance?: WakeProvenance, after?: WritePlacement) => void;
   private getAgentNamesFn: () => string[];
+  /** Delivery-time re-check: is this channel held from the recipients now? */
+  private isHeldFn: (serverId: string | undefined, channelId: string | undefined) => boolean;
   private resolveRouteChannelFn: (info: GateEventInfo) => string | undefined;
   private channelShownFn?: (channel: { serverId: string; channelId: string }) => string;
   private isNewestEntryFn?: (entry: GateEntryRef) => boolean;
@@ -2117,6 +2182,13 @@ export class EventGate {
      *  message is answered. */
     requestInference: (agentName: string, reason: string, source: string, provenance?: WakeProvenance, after?: WritePlacement) => void;
     getAgentNames: () => string[];
+    /**
+     * Whether a channel is held from the recipients (a tune-out epoch in
+     * force). A held event never enters a batch — admission runs before the
+     * gate — but a hold can begin after an event was batched; at delivery
+     * the batch is re-checked and held events are dropped (#232 H3).
+     */
+    isHeld?: (serverId: string | undefined, channelId: string | undefined) => boolean;
     /** Optional clock — defaults to Date.now. Tests inject for deterministic time. */
     now?: () => number;
     /** Per-event timeout (ms) for the optional gate.js script. Default 50. */
@@ -2153,6 +2225,11 @@ export class EventGate {
      *  (WakeProvenance.line), for a fresh start of the wake's turn to decide
      *  (WakeLine). Absent: every batched wake writes its line, as before. */
     isNewestEntry?: (entry: GateEntryRef) => boolean;
+    /** The event types the gate can see from a source, when the host knows
+     *  them (an MCPL server's id: MCPL_GATE_EVENT_TYPES), else undefined.
+     *  The rule-order notes (findShadowedPolicies) leave out types a rule's
+     *  source never sends. Absent: any source can send any type. */
+    eventTypesFrom?: EventTypesFrom;
   }) {
     this.configPath = opts.configPath;
     this.privilegedUsersPath = opts.privilegedUsersPath;
@@ -2160,9 +2237,11 @@ export class EventGate {
     this.addMessageFn = opts.addMessage;
     this.requestInferenceFn = opts.requestInference;
     this.getAgentNamesFn = opts.getAgentNames;
+    this.isHeldFn = opts.isHeld ?? (() => false);
     this.resolveRouteChannelFn = opts.resolveRouteChannel ?? defaultRouteChannel;
     this.channelShownFn = opts.channelShown;
     this.isNewestEntryFn = opts.isNewestEntry;
+    this.eventTypesFromFn = opts.eventTypesFrom;
     this.now = opts.now ?? (() => Date.now());
     this.judgeFn = opts.judge;
     this.changesJudgedContextFn = opts.changesJudgedContext;
@@ -3448,22 +3527,32 @@ export class EventGate {
   /** Current shadow-lint findings for the live policy order. Fresh compute —
    *  cheap (policy lists are tens of entries at most). */
   lintShadows(): ShadowWarning[] {
-    return findShadowedPolicies(this.config.policies);
+    return findShadowedPolicies(this.config.policies, this.eventTypesFromFn);
   }
 
   /**
-   * Recompute shadow warnings and, when the set changed and is non-empty,
-   * emit a `gate:shadow-warnings` trace so the hazard lands in ops
-   * observability at the moment the order changed — not at the next missed
-   * DM. Called from writeConfig and reloadIfChanged.
+   * The sources the host knows changed (eventTypesFrom answers differently),
+   * as when an MCPL server connects or is removed: the rule-order notes are
+   * made again, and traced if they changed, as a change to the rules would.
+   */
+  sourcesChanged(): void {
+    this.refreshShadowWarnings('sources-changed');
+  }
+
+  /**
+   * Recompute shadow warnings and, when the set changed, emit a
+   * `gate:shadow-warnings` trace so the hazard lands in ops observability at
+   * the moment the order changed — not at the next missed DM — and, with an
+   * empty list, the moment the last of them went. Called from writeConfig,
+   * reloadIfChanged and sourcesChanged.
    */
   private refreshShadowWarnings(reason: string): void {
     const warnings = this.lintShadows();
     const fingerprint = JSON.stringify(warnings);
     if (fingerprint === this.shadowWarningsFingerprint) return;
+    const hadSome = this.shadowWarningsFingerprint !== '[]';
     this.shadowWarningsFingerprint = fingerprint;
-    this.shadowWarningsCache = warnings;
-    if (warnings.length > 0) {
+    if (warnings.length > 0 || hadSome) {
       this.emitTrace({
         type: 'gate:shadow-warnings',
         reason,
@@ -3608,7 +3697,23 @@ export class EventGate {
   // Event delivery
   // =========================================================================
 
-  private deliverEvents(events: PendingEvent[]): void {
+  private deliverEvents(batched: PendingEvent[]): void {
+    // Delivery-time re-check: a channel tuned out after its events were
+    // batched is held now, and "already shown above at arrival" would be
+    // untrue of them. They are dropped; the hold's own reader has them.
+    const heldAt = (e: PendingEvent): string | undefined => e.routeChannelId ?? e.channelId;
+    const events = batched.filter((e) => {
+      const channel = heldAt(e);
+      return !(channel && this.isHeldFn(e.serverId, channel));
+    });
+    if (events.length < batched.length) {
+      this.emitTrace({
+        type: 'gate:held-dropped',
+        dropped: batched.length - events.length,
+        channels: [...new Set(batched.filter((e) => !events.includes(e)).map(heldAt))],
+        timestamp: this.now(),
+      });
+    }
     if (events.length === 0) return;
 
     const policyNames = [...new Set(events.map(e => e.policyName))];
@@ -3621,7 +3726,7 @@ export class EventGate {
     const quoted = events.filter(e => !e.inContext);
     const referenced = events.filter(e => e.inContext);
 
-    const lines: string[] = quoted.map(e => `- [${e.policyName}] (${e.eventType}): ${e.content}`);
+    const lines: string[] = quoted.map(e => `- [${e.policyName}] (${e.eventType}): ${suppliedValue(e.content)}`);
     // How each referenced channel is named in the line, in order.
     const shown: string[] = [];
     if (referenced.length > 0) {
@@ -3640,7 +3745,7 @@ export class EventGate {
           ? '(unknown channel)'
           : e.routeChannelId !== undefined && e.serverId !== undefined && this.channelShownFn
             ? this.channelShownFn({ serverId: e.serverId, channelId: e.routeChannelId })
-            : id;
+            : suppliedValue(id);
         const key = JSON.stringify([e.serverId ?? null, id ?? null]);
         const entry = byChannel.get(key) ?? { name, count: 0, oldest: e.timestamp, label: e.channelLabel };
         entry.count += 1;
@@ -3653,7 +3758,7 @@ export class EventGate {
         // agent can still address tools that want the composite id. A name
         // may carry its own `#`, so one is added only where the name lacks
         // it, as at the other places that add a `#`.
-        const channel = label ? `${label.startsWith('#') ? label : `#${label}`} (${name})` : name;
+        const channel = label ? `${label.startsWith('#') ? '' : '#'}${suppliedValue(label)} (${name})` : name;
         shown.push(channel);
         lines.push(referenceLine(count, channel, oldest, Date.now()));
       }
@@ -3666,7 +3771,7 @@ export class EventGate {
     // gate hands the line to the wake (WakeProvenance.line) and a fresh start
     // of the wake's turn decides it (WakeLine). Several messages, one with
     // anything after it, or content the line quotes, keep the line now.
-    const text = `[Gate: ${events.length} event${events.length > 1 ? 's' : ''} matched]\n\n${lines.join('\n')}`;
+    const text = `[${NOTICE_TAG.gate}: ${events.length} event${events.length > 1 ? 's' : ''} matched]\n\n${lines.join('\n')}`;
     const only = events.length === 1 && events[0].inContext ? events[0] : undefined;
     let line: WakeLine | undefined;
     if (only && this.newestEntry(only)) {
@@ -3911,7 +4016,7 @@ export class EventGate {
     record.last = {
       at: Date.now(),
       verdict: outcome,
-      reason: safeSlice(reason, 0, 300),
+      reason: cutToFit(suppliedValue(reason), 300),
       eventCount: state.events.length,
       durationMs,
       ...(!failed && typeof verdict.inputTokens === 'number' ? { inputTokens: verdict.inputTokens } : {}),
@@ -3919,7 +4024,7 @@ export class EventGate {
     if (this.config.policies.some((p) => p.name === policyName)) this.judgeRecords.set(policyName, record);
     if (failed) {
       this.judgeFailStreak++;
-      this.judgeLastFailure = safeSlice(reason, 0, 200);
+      this.judgeLastFailure = cutToFit(suppliedValue(reason), 200);
     } else {
       this.judgeFailStreak = 0;
     }
@@ -4190,10 +4295,9 @@ export class EventGate {
   }
 
   /**
-   * `agentName` is gone, as a conversation fork's end or an ephemeral run's
-   * removes one: its pending self-wake is cancelled, rather than wake a name
-   * that no longer exists. It holds no sleep: neither can set one (the
-   * framework refuses their `sleep`).
+   * `agentName` is gone, as an agent's end removes one: its pending
+   * self-wake is cancelled, and a sleep it set ends, rather than go on
+   * quieting every agent and then wake a name that no longer exists.
    */
   agentGone(agentName: string): void {
     const selfWake = this.selfWakeTimers.get(agentName);
@@ -4201,6 +4305,7 @@ export class EventGate {
       clearTimeout(selfWake);
       this.selfWakeTimers.delete(agentName);
     }
+    if (this.sleepAgent === agentName) this.clearSleep();
   }
 
   // =========================================================================
@@ -4246,7 +4351,7 @@ export class EventGate {
       const placement: WritePlacement = {};
       this.addMessageFn('user', [{
         type: 'text',
-        text: `[self-wake] your ${source} timer (${Math.round(ms / 1000)}s) elapsed — now ${nowIso}`,
+        text: `[${NOTICE_TAG.selfWake}] your ${source} timer (${Math.round(ms / 1000)}s) elapsed — now ${nowIso}`,
       }], { source: 'gate:self-wake' }, agentName, placement);
       this.requestInferenceFn(
         agentName,
@@ -4497,7 +4602,9 @@ export class EventGate {
         this.judgeUnwiredNotice(), this.judgeFailingNotice(),
       ]
         .filter((e): e is string => e !== null),
-      shadowWarnings: this.shadowWarningsCache.map(formatShadowWarning),
+      // Fresh, not the cache: the sources the host knows (eventTypesFrom)
+      // change as servers connect, with no change to the rules.
+      shadowWarnings: this.lintShadows().map(formatShadowWarning),
       totalEvaluations: this.totalEvaluations,
       defaultDecisions: {
         triggered: this.defaultTriggered,

package/src/gate/index.ts

@@ -1,4 +1,4 @@
-export { EventGate, wakeProvenance, wakeLineText, type WakeProvenance, type WritePlacement } from './event-gate.js';
+export { EventGate, MCPL_GATE_EVENT_TYPES, wakeProvenance, wakeLineText, type EventTypesFrom, type WakeProvenance, type WritePlacement } from './event-gate.js';
 export type {
   GateConfig,
   GateOptions,

package/src/gate/types.ts

@@ -359,10 +359,20 @@ export interface GateDecision {
 export interface ShadowWarning {
   /** Name of the earlier (consuming) policy. */
   earlier: string;
-  /** Name of the later policy it makes unreachable. */
+  /** Name of the later policy whose events it takes. */
   later: string;
-  /** Event types affected — 'all' when both rules are unscoped. */
+  /** Event types affected: those of `later`'s (its scope's, narrowed to the
+   *  ones its source is known to send) that `earlier` covers. 'all' only when
+   *  neither rule has a scope and `later`'s source could send any type. */
   eventTypes: string[] | 'all';
+  /** Whether `earlier` takes every event `later` would match, so `later`
+   *  never applies. */
+  whole: boolean;
+  /** Whether `later` is known to see these types: its scope names them, or
+   *  its source is one whose event types the host knows (an MCPL server's).
+   *  False when `later` names no scope and its source could send anything,
+   *  so the types may never reach it. */
+  known: boolean;
 }
 
 /** One row of the dry-run probe table (see EventGate.probeTable). */

package/src/heartbeat/heartbeat.ts

@@ -28,6 +28,7 @@
  * missed.
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { checkToolInput, shownValue } from '../gate/event-gate.js';
@@ -81,7 +82,7 @@ export const DEFAULT_HEARTBEAT: Readonly<HeartbeatSettings> = {
   intervalSeconds: 4 * 60 * 60,
   paused: false,
   deliveryMode: 'message',
-  message: '[heartbeat] Periodic self-check-in. Review anything pending — reminders, schedules, follow-ups — and act if needed; otherwise a brief note to yourself is fine.',
+  message: `[${NOTICE_TAG.heartbeat}] Periodic self-check-in. Review anything pending — reminders, schedules, follow-ups — and act if needed; otherwise a brief note to yourself is fine.`,
 };
 
 /** A scheduled reminder. `everySeconds` null: one-off, dropped once it fires. */
@@ -112,6 +113,17 @@ export interface HeartbeatOptions {
   importFrom?: { configPath?: string; remindersPath?: string };
 }
 
+/** One of the heartbeat's scheduled wakes: its next tick or a pending reminder. */
+export interface HeartbeatScheduledWake extends UpcomingWake {
+  kind: 'heartbeat' | 'reminder';
+  at: number;
+  /** Whether it's a silent tick, delivered as one (HeartbeatWake's `silent`). */
+  silent: boolean;
+  /** The text it brings, as of its due time: so the gate can be asked about
+   *  the event it will judge. */
+  text: string;
+}
+
 /** A wake the heartbeat asks the framework to deliver. */
 export type HeartbeatWake =
   | { kind: 'heartbeat'; reason: 'schedule' | 'manual'; silent: boolean; text: string; eventId: string }
@@ -223,11 +235,16 @@ function callAt(dueAt: number, now: () => number, onDue: () => void): () => void
   return () => clearTimeout(timer);
 }
 
+/** The text a tick brings: the time, then its message. */
+function tickText(now: number, message: string, timeZone: string): string {
+  return `[${NOTICE_TAG.currentTime}: ${formatHeartbeatTime(now, timeZone)}] ${message}`;
+}
+
 /** The text a reminder brings: a header naming it, then its message. */
 export function reminderText(rem: Reminder, now: number, timeZone: string): string {
   let schedule = rem.everySeconds !== null ? `, repeats every ${rem.everySeconds}s` : `, set ${formatHeartbeatTime(rem.createdAt, timeZone)}`;
   if (now - rem.fireAt >= LATE_MS) schedule += `, due ${formatHeartbeatTime(rem.fireAt, timeZone)}`;
-  return `[reminder ${rem.id}${schedule} · current time: ${formatHeartbeatTime(now, timeZone)}] ${rem.message}`;
+  return `[${NOTICE_TAG.reminder} ${rem.id}${schedule} · current time: ${formatHeartbeatTime(now, timeZone)}] ${rem.message}`;
 }
 
 /** A length of time as the agent is shown it. */
@@ -318,24 +335,46 @@ export class Heartbeat {
 
   /** What the heartbeat will wake the agent with, soonest first, for the reply judge (UpcomingWake). */
   upcomingWakes(): UpcomingWake[] {
-    const wakes: UpcomingWake[] = [];
+    return this.scheduledWakes().map(({ at, certain, what }) => ({ at, certain, what }));
+  }
+
+  /**
+   * The heartbeat's next tick and its pending reminders, soonest first, each
+   * with its kind and the event it will bring, so the gate can be asked about
+   * it. `whose` words each for the reply judge ("its heartbeat", as
+   * upcomingWakes) or for the agent ("your heartbeat", as skip_reply's
+   * confirmation names one due before its self-wake).
+   */
+  scheduledWakes(whose: 'its' | 'your' = 'its'): HeartbeatScheduledWake[] {
+    const wakes: HeartbeatScheduledWake[] = [];
     const s = this.state;
     if (!s.settings.paused && s.nextFireAt !== null) {
+      const at = Math.max(s.nextFireAt, this.notBefore);
+      const silent = s.settings.deliveryMode === 'silent';
       wakes.push({
-        at: Math.max(s.nextFireAt, this.notBefore),
+        kind: 'heartbeat',
+        at,
         certain: true,
-        what: `its heartbeat (${s.settings.deliveryMode === 'silent' ? 'a silent tick' : 'a check-in prompt'}, every ${shownLength(s.settings.intervalSeconds)})`,
+        what: `${whose} heartbeat (${silent ? 'a silent tick' : 'a check-in prompt'}, every ${shownLength(s.settings.intervalSeconds)})`,
+        silent,
+        // A host's interval can put the tick past the last time a date
+        // shows (readSettings has no ceiling), and a time can't be shown there.
+        text: canHoldTime(at) ? tickText(at, s.settings.message, this.timeZone) : s.settings.message,
       });
     }
     for (const r of s.reminders) {
       const message = r.message.length > 80 ? `${r.message.slice(0, 77)}...` : r.message;
+      const at = Math.max(dueAt(r), this.notBefore);
       wakes.push({
-        at: Math.max(dueAt(r), this.notBefore),
+        kind: 'reminder',
+        at,
         certain: true,
-        what: `its reminder ${JSON.stringify(message)}${r.everySeconds !== null ? ` (repeats every ${shownLength(r.everySeconds)})` : ''}`,
+        what: `${whose} reminder ${JSON.stringify(message)}${r.everySeconds !== null ? ` (repeats every ${shownLength(r.everySeconds)})` : ''}`,
+        silent: false,
+        text: reminderText(r, at, this.timeZone),
       });
     }
-    return wakes.sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    return wakes.sort((a, b) => a.at - b.at);
   }
 
   /**
@@ -549,7 +588,7 @@ export class Heartbeat {
         kind: 'heartbeat',
         reason,
         silent,
-        text: `[current time: ${formatHeartbeatTime(now, this.timeZone)}] ${s.message}`,
+        text: tickText(now, s.message, this.timeZone),
         eventId: `heartbeat_${now}_${Math.random().toString(36).slice(2, 8)}`,
       });
       log(`fired heartbeat (${reason}${silent ? ', silent' : ''})`);

package/src/held-writes.ts

@@ -62,9 +62,9 @@ function valueAt(value: unknown, path: string): unknown {
  * A row as a module's context answers it: marked `heldFromResidents` when it
  * carries the stamp a tune-out puts on a message it holds from the residents
  * (`metadata.tuneOut`). Every resident's viewFilter leaves a stamped row out
- * of its compiled view (framework.ts, createAgent), and a tool boundary
- * stores a stamped write without injecting it into the live turn, so a
- * marked row is one the store keeps and no resident is shown
+ * of its compiled view (framework.ts, createAgent), and a resident's tool
+ * boundary stores a stamped write without injecting it into the live turn, so
+ * a marked row is one the store keeps and no resident is shown
  * (ModuleMessage.heldFromResidents says where its text can still reach
  * one). Any other row comes back as it is.
  */