@animalabs/agent-framework 0.31.0 → 0.33.0

package/src/tune-out/tools.ts

@@ -29,10 +29,9 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'deliver_summary',
     description:
-      'Deliver a summary into the resident\'s context, in your own voice, ' +
-      'addressed to them (second person). Use at cadence when the diverted ' +
-      'traffic merits it; staying silent is always allowed — an empty ' +
-      'period needs no report.',
+      'Deliver a summary into the resident\'s context: `text` arrives there ' +
+      'verbatim (leading and trailing whitespace trimmed), under your own ' +
+      'name.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -51,11 +50,15 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'cancel_tuneout',
     description:
-      'End the tune-out on a channel now — use when something needs the ' +
-      'resident\'s full attention. The diverted backlog is delivered to ' +
-      'them (capped), and normal attention resumes. Add your own note in ' +
-      '`text`; it arrives alongside the backlog, in your voice. If you were ' +
-      'started to read one hold, you can end only that hold.',
+      'End the tune-out on a channel. The diverted backlog is delivered ' +
+      'to the resident (capped), and the channel\'s traffic reaches them as ' +
+      'it did before the tune-out, unless the all-except hold holds it too. ' +
+      'A note in `text` arrives alongside the ' +
+      'backlog, verbatim (leading and trailing whitespace trimmed), under ' +
+      'your own name. Where the cancel has to wait (an operator\'s change to ' +
+      'the store, say), its answer says so, and whether your note waits with ' +
+      'it. If you were started to read ' +
+      'one hold, you can end only that hold.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -72,10 +75,10 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'note_disposition',
     description:
-      'Record a standing disposition for yourself — a durable note that ' +
-      'shapes how you treat future traffic ("antra\'s pings always ' +
-      'escalate", "ignore release-bot"). Replaces any previous note under ' +
-      'the same key.',
+      'Record a standing disposition: a durable note, kept under `key` ' +
+      'across invocations and shown to the reader each time it runs (e.g. ' +
+      'key "<sender>", text "<a note on their messages>"). Replaces any ' +
+      'previous note under the same key.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -91,14 +94,14 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'speak_in_channel',
     description:
-      'Post a message into a tuned-out channel, in your own words and ' +
-      'clearly as yourself (not as the resident); it goes out through the ' +
-      'resident\'s publish path, so the channel sees it under their account. ' +
-      'Use sparingly — e.g. to tell someone the resident is tuned out and ' +
-      'when to expect them. If you were started to read one hold, you can ' +
-      'post only into a channel that hold still holds, and a post made once ' +
-      'it has ended is refused; your report can say it instead. Disabled unless ' +
-      'the resident\'s configuration allows it.',
+      'Post `text` into a tuned-out channel, as written (leading and trailing ' +
+      'whitespace trimmed). It goes out through ' +
+      'the resident\'s publish path, so the channel sees it under the ' +
+      'resident\'s account; nothing in the post names you. If you were ' +
+      'started to read one hold, you can post only into a channel that hold ' +
+      'still holds, and a post made once it has ended is refused; your report ' +
+      'can say it instead. Disabled unless the resident\'s configuration ' +
+      'allows it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -110,6 +113,77 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   },
 ];
 
+/**
+ * Who reads a tuned-out channel's traffic, as the text a resident reads
+ * says it: the persistent subconscious by the name it runs under, or reader
+ * forks. There is no hold without a reader (0.33.0) but one whose release
+ * failed after the persistent reader ended, or at a start with none
+ * configured: none runs then (`running: false`), the reader named as
+ * configured, or by its default name, for tune_out's own text, and what a
+ * held channel's messages are says that none reads them (tuneOutHeldWords,
+ * tunedOutTrafficWords). A persistent reader's name is a value the host
+ * supplied, marked as such (suppliedValue).
+ */
+export type TuneOutReader =
+  | { readonly kind: 'persistent'; readonly name: string; readonly running?: false }
+  | { readonly kind: 'forks' };
+
+/**
+ * What a tuned-out channel's messages are, as the words after "its
+ * messages" in a refusal a resident reads (a channel tool's on a tuned-out
+ * channel): held from it and read by `reader`, by the name it runs under or
+ * as forks of the resident's context.
+ */
+export function tuneOutHeldWords(reader: TuneOutReader): string {
+  if (reader.kind === 'persistent' && reader.running === false) {
+    return "are held from you, with no reader running here to read them, until the tune-out's release, which failed, is tried again";
+  }
+  return reader.kind === 'persistent' ? `are held from you and read by ${reader.name}`
+    : 'are held from you and read by forks of your context';
+}
+
+/**
+ * What a tuned-out channel's traffic is, as the words after "its traffic"
+ * in the [tuned out] note to a send there: held from the resident and read
+ * by `reader` until the tune-out ends, or, where none runs, held until its
+ * release is tried again (TuneOutReader).
+ */
+export function tunedOutTrafficWords(reader: TuneOutReader): string {
+  if (reader.kind === 'persistent' && reader.running === false) {
+    return "is still held from you, with no reader running here to read it, until the tune-out's release, which failed, is tried again.";
+  }
+  return reader.kind === 'persistent'
+    ? `is still held from you, and read by ${reader.name}, until the tune-out ends.`
+    : 'is still held from you, and read by forks of your context, until the tune-out ends.';
+}
+
+/**
+ * Whether a tuned-out channel's messages get to its reader, as the words
+ * after "its messages" in tune_out's answers about the channel's transport,
+ * in the sentence's `form`: they reach `reader`, by the name it runs under
+ * or as "the reader" (forks, as tuneOutTool says it). Where no reader runs,
+ * those answers aren't given: tuneOutNoReaderAnswer is, in their place.
+ */
+export function tuneOutReachWords(reader: TuneOutReader, form: 'reach' | 'may not reach' | "don't reach"): string {
+  return `${form} ${reader.kind === 'persistent' ? reader.name : 'the reader'}`;
+}
+
+/**
+ * tune_out's answer about a tuned-out channel's transport where no reader
+ * runs (`running: false`, a hold left on record by a failed release): a
+ * sentence of its own, given alone in place of each answer that says
+ * whether the messages reach the reader and when (tuneOutReachWords), since
+ * opening the channel doesn't change that none reads them. Undefined where
+ * a reader runs. tune_out is refused with no reader, repeated for a channel
+ * already tuned out too, so this answers a tune_out whose reader ended
+ * while its channel's open was out.
+ */
+export function tuneOutNoReaderAnswer(reader: TuneOutReader): string | undefined {
+  if (reader.kind !== 'persistent' || reader.running !== false) return undefined;
+  return 'The tune-out is recorded, but its messages are held, with no reader running here to read them, until the '
+    + "tune-out's release, which failed, is tried again; opening its channel doesn't change that.";
+}
+
 /**
  * Configuration for the subconscious (FrameworkConfig.subconscious). Two
  * shapes, by `reader`:
@@ -156,12 +230,22 @@ interface SubconsciousConfigBase {
   thinkingBinding?: AgentConfig['thinkingBinding'];
 }
 
+/**
+ * The name a persistent reader runs under: its configuration's `name`, or,
+ * where the host gave none, `'Subconscious'` (PersistentReaderConfig.name).
+ * The one place the framework names a reader the host didn't: everything
+ * that needs the name of an unnamed reader asks this.
+ */
+export function persistentReaderName(config: { name?: string }): string {
+  return config.name ?? 'Subconscious';
+}
+
 export interface PersistentReaderConfig extends SubconsciousConfigBase {
   reader?: 'persistent';
   /**
    * Registry + participant name. Default 'Subconscious' — following the
    * Context Manager precedent: a title-case functional voice, not an
-   * agent-prefixed identifier.
+   * agent-prefixed identifier. persistentReaderName applies the default.
    */
   name?: string;
   /** Model id; defaults to the primary agent's (same-model side-process).
@@ -171,29 +255,53 @@ export interface PersistentReaderConfig extends SubconsciousConfigBase {
    *  `thinkingBinding` set its own. */
   model?: string;
   /**
-   * The voice/criteria mode block — recipe-side and co-authored with the
-   * resident (it is an aspect of their attention). Report-shaped, second
-   * person toward the resident. Canary before fleet use (issue #77).
+   * The persistent reader's system prompt (its AgentConfig.systemPrompt).
+   * Who writes it and what it says, a policy for the reader tools
+   * included, are the host's choice. Canary before fleet use (issue #77).
    */
   systemPrompt: string;
   /** WindowedPassthroughStrategy re-anchor fraction (default 0.5). */
   reAnchorFraction?: number;
+  /**
+   * How a resident's rounds go out in the subconscious's requests once its
+   * window follows the presentation index (#291, answer 13). Its own rounds go
+   * as stored either way.
+   *
+   * - `'transcript'` (the default): a line per tool call (the tool's name and
+   *   its input in brief) and per result (its outcome in brief), the text as
+   *   stored, and none of the resident's thinking (foreign-rounds.ts).
+   * - `'raw'`: as stored, as 0.30.0 sent them: the resident's thinking
+   *   blocks, its tool calls and their results, in the subconscious's
+   *   requests under the resident's name. A provider pairs tool blocks only
+   *   in the turns of the agent that made the call, so it may refuse them, or
+   *   the formatter may move them into the subconscious's own turns, where
+   *   they read as calls it made.
+   *
+   * A thinking block's signature binds the block to the prefix the resident
+   * was sent, so the block can't be sent as part of another agent's prefix;
+   * its text could be. Leaving the text out is the transcript's choice, not
+   * the provider's.
+   */
+  foreignRounds?: 'transcript' | 'raw';
 }
 
 export interface ForkReaderConfig extends SubconsciousConfigBase {
   reader: 'forks';
   /**
    * Whose weights run the fork. Required, never defaulted: a fork holds the
-   * resident's whole prefix, and which model reads it is the one fact the
-   * resident's consent names. The resident's own model is the copy; another
-   * model is allowed when stated here. `create` refuses the omission.
+   * resident's whole prefix, and which model reads it is recorded on each
+   * fork's `dendrite:agent-created` trace and is what a host's
+   * `dendrite.beforeDerive` can decide on. The resident's own model, or
+   * another model stated here. `create` refuses the omission.
    */
   model: string;
   /**
-   * The reader's voice block — report-shaped, second person toward the
-   * resident, co-authored with them. Delivered as the first message after
-   * the fork point, with the notice, the standing dispositions and the held
-   * traffic; never a system prompt.
+   * The reader's voice block: text the host supplies, handed to `framing`.
+   * The default framing (defaultReaderFraming) puts it in the one message a
+   * fork receives after the fork point, with the notice, the standing
+   * dispositions and the held traffic; it is never a system prompt. Who
+   * writes it and what it says, a policy for the reader tools included,
+   * are the host's choice.
    */
   voice: string;
   /**
@@ -211,7 +319,13 @@ export interface ForkReaderConfig extends SubconsciousConfigBase {
    * framework stores whatever this returns as a user message with
    * `metadata.kind = 'tune-out-reader-framing'`; the notice, voice,
    * dispositions and held traffic are in the context, and nothing else
-   * about the fork's prompt is fixed by the path.
+   * about the fork's prompt is fixed by the path. note_disposition tells a
+   * reader that a disposition it records is shown to the reader each time
+   * it runs, and a fork is shown them only as its framing puts them
+   * (`dispositions`), so a framing that leaves them out makes that untrue.
+   * Likewise the held traffic reaches the fork only as its framing puts it
+   * (`backlog`): the fork's view, the residents', leaves the raw rows out,
+   * as it leaves out all held traffic (the default framing shows them).
    */
   framing?: (context: ReaderFramingContext) => ContentBlock[];
 }
@@ -232,13 +346,20 @@ export interface ReaderFramingContext {
   /** Standing dispositions recorded on the epoch, or null. */
   dispositions: string | null;
   /**
-   * The traffic held since the last look, oldest first; empty when nothing
-   * arrived. It includes the messages still queued behind the resident's
-   * turn (admitted, not yet stored), last: their ids are held handles and
-   * their sequences provisional, as a module's held rows are.
+   * The traffic held since the last look, oldest first, as stored; empty
+   * when nothing arrived. A held message is stored as it arrives, the
+   * resident's turn alive or not (#291), so the stored rows are all of it,
+   * but for one a surgery's hold or a manager awaiting recovery keeps in
+   * memory: it isn't stored yet, and is in the first backlog after it is.
    */
   backlog: StoredMessage[];
-  /** How many of `backlog`'s last entries are still queued behind the resident's turn. Absent is none. */
+  /**
+   * Was how many of `backlog`'s last entries were still queued behind the
+   * resident's turn. Since #291 nothing is queued, so the framework never
+   * sets it.
+   *
+   * @deprecated Never set since #291; removed in a later release.
+   */
   queuedCount?: number;
 }
 
@@ -259,15 +380,11 @@ export function defaultReaderFraming(ctx: ReaderFramingContext): ContentBlock[]
     return content;
   }
   const n = ctx.backlog.length;
-  const q = Math.min(Math.max(0, Math.floor(ctx.queuedCount ?? 0)), n);
   const lines: string[] = [`\n[Held in ${ctx.channelId} since your last look: ${n} message${n === 1 ? '' : 's'}]`];
   const flush = () => {
     if (lines.length > 0) content.push({ type: 'text', text: lines.splice(0).join('\n') });
   };
-  const which = q === n ? (q === 1 ? 'It' : 'They') : (q === 1 ? 'The last one' : `The last ${q}`);
-  const queuedNote = `[${which} arrived while ${ctx.resident}'s turn was running, so ${q === 1 ? 'it is' : 'they are'} still queued, not yet stored.]`;
-  for (const [i, message] of ctx.backlog.entries()) {
-    if (q > 0 && i === n - q) lines.push(queuedNote);
+  for (const message of ctx.backlog) {
     const author = (message.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? message.participant;
     const text = message.content
       .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')

package/src/tune-out/window-anchor.ts

@@ -0,0 +1,277 @@
+/**
+ * Where the persistent subconscious's window starts (#291, AF-5).
+ *
+ * The subconscious reads a tune-out's held traffic through a windowed
+ * passthrough strategy: everything from the anchor on, the anchor at the
+ * oldest active tune-out's start (the coordinator's anchorSubconscious), or
+ * at an earlier start kept in force: a cancelled tune-out's, kept while
+ * another stays active and across a restart, until the next enter sets the
+ * oldest active one's (below).
+ * While its window is the record, a start is a sequence, and the window is
+ * every row stored at it or after. Once its window follows the presentation
+ * index, the window is the rows in the order it was shown them, and a start
+ * is an index ordinal: the row at it and every row presented after it.
+ *
+ * A tune-out's start can't be turned into an ordinal once and for all at its
+ * enter. The subconscious's window grows only at its own points, so a row
+ * stored before the start can still be out of its window then (its turn
+ * alive, the host quiesced), and would be presented after the start, inside
+ * the window. Converting the sequence again later (a restart, another
+ * tune-out's enter) can give another ordinal, and so another window, once
+ * rows have been presented out of record order. So each tune-out's start is
+ * fixed once, at the first moment no row the subconscious is owed stored
+ * before the start is out of its window: the ordinal just past the last row
+ * in its window stored before the start, which leaves every such row out
+ * (0 when there is none). Others' rows enter a window in record order, so
+ * that is where the first row stored at the start or after entered, unless
+ * one of the subconscious's own rows was presented ahead of them, at its
+ * write, in the turn the tune-out began in; that row stays out too, the turn
+ * having been before the tune-out. The coordinator keeps the ordinal
+ * (subconsciousWindowFixed), and from then on the start is set by it,
+ * clamped to the window's length on a branch whose window is shorter (a
+ * rollback), the clamped ordinal then kept as the start, never converted
+ * again. A kept ordinal is kept as the start in force once it is set, not
+ * before, and one whose setting or keeping fails is tried again at the next
+ * presentation, as a fix is. One set while the window is the record (a
+ * branch move whose re-initialization of the subconscious failed) waits
+ * longer: it is set by sequence and fixed at the next enter or restart once
+ * the window presents. One whose setting or keeping failed before a branch
+ * move is fixed again on the branch moved to, from its window there, as one
+ * never fixed is: an ordinal is a place on the branch it was fixed on; one
+ * for tune-outs none of which is active then, and a cancelled tune-out's
+ * start set in force by its kept ordinal, are dropped at the move. A
+ * restart that finds a start in force kept sets that one, and fixes the
+ * oldest active tune-out's start, if it isn't kept, without moving the
+ * window to it; one that finds none in force kept sets the anchor the
+ * strategy persisted, as the start in force: where the oldest's start is
+ * kept, if it is earlier (a cancelled tune-out's start that was set but
+ * never kept), and where it isn't (its fix set, its keeping failed),
+ * wherever it is, rather than converting the oldest's sequence again, that
+ * start fixed without moving the window to it; where that anchor can't be
+ * read, it sets nothing, the window left where it was until the next enter
+ * or restart.
+ */
+import type { ContextManager, StoredMessage } from '@animalabs/context-manager';
+import type { SubconsciousWindowStart } from './coordinator.js';
+import type { TraceEventInput } from '../types/trace.js';
+
+/** The windowed strategy's anchor setters and read, as the anchor uses them. */
+export interface AnchoredStrategy {
+  setAnchor(sequence: number): void;
+  setAnchorOrdinal(ordinal: number): void;
+  getAnchorOrdinal(): number | undefined;
+}
+
+/** What the anchor reads of the framework. */
+export interface SubconsciousWindowAnchorHost {
+  /** The subconscious's name, for its traces. */
+  readonly agentName: string;
+  /** Its context manager while it is registered. */
+  cm(): Pick<ContextManager, 'indexLength' | 'getPresentedMessages' | 'ordinalOf'> | undefined;
+  /** Its windowed strategy. */
+  strategy(): AnchoredStrategy | null;
+  /** Whether its window follows the presentation index, so its places are ordinals. */
+  presents(): boolean;
+  /** The rows it is owed that its window doesn't hold yet, one per body (AgentPresentation.owedOf). */
+  owed(): readonly Pick<StoredMessage, 'sequence'>[];
+  /**
+   * Keep a start fixed for `epochIds` (TuneOutCoordinator.subconsciousWindowFixed), as the start in force when
+   * `inForce`; false when it couldn't be kept.
+   */
+  fixed(epochIds: readonly string[], ordinal: number, inForce: boolean): boolean;
+  emitTrace(event: Extract<TraceEventInput, { type: 'tune-out:subconscious-window' }>): void;
+}
+
+/** The subconscious's window start, set by sequence in legacy mode and by a fixed ordinal once its window is presented. */
+export class SubconsciousWindowAnchor {
+  /**
+   * The starts whose ordinal isn't set and kept yet, the one in force
+   * (`inForce`) first if it is among them: some row older than a start is
+   * still out of the window, or setting or keeping the ordinal it was fixed
+   * at (`ordinal`) failed, which the next presentation tries again. A start
+   * set by an ordinal already known (`known`) waits only for its setting and
+   * keeping: kept for `keep` (none for a start in force only) and as the
+   * start in force, traced when clamped (`clampedFrom`, the ordinal kept
+   * before).
+   */
+  private pending: Array<{
+    start: SubconsciousWindowStart;
+    ordinal?: number;
+    inForce: boolean;
+    known?: { keep: readonly string[]; clampedFrom?: number };
+  }> = [];
+
+  constructor(private readonly host: SubconsciousWindowAnchorHost) {}
+
+  /**
+   * Set the window start (the coordinator's setSubconsciousAnchor). In
+   * legacy mode by its sequence, as before the index. In presented mode by
+   * its ordinal when one was fixed, clamped to the window's index length
+   * and traced when past it, the clamped ordinal kept as the start; the
+   * strategy's persisted anchor where it is earlier, or, with no ordinal
+   * known, where it has one, at a resume that asks for it
+   * (keepEarlierAnchor); else by its sequence for now, converted as
+   * the strategy converts one, and the ordinal is fixed (see the module
+   * doc) as soon as no row the subconscious is owed stored before the start
+   * is out of its window, now or at a later presentation (presented). An
+   * ordinal set is kept as the start in force once it is set, and tried
+   * again at the next presentation until both succeed. The starts of
+   * `others`, the other active tune-outs' whose ordinal isn't kept yet, are
+   * fixed the same way, without moving the window to them. Never throws: a
+   * set that fails is logged, and the anchor stays where it was.
+   */
+  set(start: SubconsciousWindowStart, others: readonly SubconsciousWindowStart[] = []): void {
+    try {
+      const strategy = this.host.strategy();
+      if (!strategy) return;
+      if (!this.host.presents()) {
+        this.pending = [];
+        strategy.setAnchor(start.sequence);
+        return;
+      }
+      const was = this.pending;
+      const carried = (wanted: SubconsciousWindowStart, inForce: boolean) => ({
+        ...(was.find((p) => !p.known && sameStart(p.start, wanted)) ?? { start: wanted }),
+        inForce,
+      });
+      this.pending = others.map((other) => carried(other, false));
+      let known = start.ordinal;
+      let inForceOnly = start.inForceOnly === true;
+      if (start.keepEarlierAnchor) {
+        const persisted = persistedOrdinal(strategy);
+        if (persisted === null) {
+          // Whether the strategy holds an earlier start (a cancelled
+          // tune-out's, set and never kept) can't be told: the kept one set
+          // over it would drop the rows it held from the window, and be kept
+          // in force. The window stays where it was, nothing set or kept in
+          // force; the next enter or restart sets it. The others are fixed,
+          // and so is the start itself where no ordinal is kept for it,
+          // without moving the window to it.
+          if (known === undefined) this.pending.push(carried(start, false));
+          this.tryFix();
+          return;
+        }
+        // With no ordinal kept (one fixed and set whose keeping failed), the
+        // persisted anchor is the start this window had, wherever it is: the
+        // sequence converted again could give a later one, leaving out a
+        // row presented out of record order (AF #844 review 5, #47). The
+        // start's own ordinal is fixed beside it, unmoved to.
+        if (persisted !== undefined && (known === undefined || persisted < known)) {
+          if (known === undefined) this.pending.push(carried(start, false));
+          known = persisted;
+          inForceOnly = true;
+        }
+      }
+      if (known !== undefined) {
+        const length = this.host.cm()?.indexLength() ?? 0;
+        const ordinal = Math.min(known, length);
+        this.pending.unshift({
+          start,
+          ordinal,
+          inForce: true,
+          known: { keep: inForceOnly ? [] : start.epochIds, ...(ordinal !== known ? { clampedFrom: known } : {}) },
+        });
+      } else {
+        this.pending.unshift(carried(start, true));
+        strategy.setAnchor(start.sequence);
+      }
+      this.tryFix();
+    } catch (error) {
+      console.error(`[tune-out] the subconscious's window start couldn't be set, so it stays where it was:`, error);
+    }
+  }
+
+  /**
+   * The store's branch moved (the framework's followBranchMove, before the
+   * agents follow it): an ordinal is a place on the branch it was fixed on,
+   * so a start pending at one (its setting or keeping failed), or set by one
+   * kept there (`known`), waits again to be fixed, from the window it
+   * presents on now, as a start never fixed does (tryFix): one for a
+   * tune-out still active (`active`, the coordinator's, where the framework
+   * says). One fixed for tune-outs none of which is active any more, and
+   * the start in force only (a cancelled tune-out's, set by its kept
+   * ordinal: fixed again, it would be the active one's start), are dropped,
+   * as every start fixed at an ordinal was before (AF #844 review 3, #30
+   * and #44): the anchor the destination's strategy keeps stands until the
+   * next enter or restart sets one.
+   */
+  branchMoved(active?: readonly string[]): void {
+    const holds = active === undefined ? undefined : new Set(active);
+    this.pending = this.pending
+      .filter((p) => {
+        if (p.known && p.known.keep.length === 0) return false;
+        const fixedThere = p.ordinal !== undefined || p.known !== undefined;
+        return !fixedThere || holds === undefined || p.start.epochIds.some((id) => holds.has(id));
+      })
+      .map((p) => ({ start: p.start, inForce: p.inForce }));
+  }
+
+  /** Rows entered the subconscious's window (the presentation index's onPresented): a start waiting to be fixed may be fixable now. */
+  presented(): void {
+    if (this.pending.length === 0) return;
+    try {
+      this.tryFix();
+    } catch (error) {
+      console.error(`[tune-out] the subconscious's window start couldn't be fixed at this presentation; the next one tries again:`, error);
+    }
+  }
+
+  /**
+   * Fix each pending start's ordinal, once no row owed and stored before it
+   * is out of the window, then set it (the start in force) and keep it;
+   * until both succeed a start stays pending at that ordinal. A start set by
+   * an ordinal known is set and kept the same way, and traced only when
+   * clamped.
+   */
+  private tryFix(): void {
+    if (this.pending.length === 0 || !this.host.presents()) return;
+    const cm = this.host.cm();
+    const strategy = this.host.strategy();
+    if (!cm || !strategy) return;
+    // Read once, and only for a start still to be fixed.
+    let owed: readonly Pick<StoredMessage, 'sequence'>[] | undefined;
+    for (const entry of [...this.pending]) {
+      if (entry.ordinal === undefined) {
+        owed ??= this.host.owed();
+        if (owed.some((row) => row.sequence < entry.start.sequence)) continue;
+        // Just past the last row in the window stored before the start.
+        let ordinal = 0;
+        for (const row of cm.getPresentedMessages()) {
+          if (row.sequence >= entry.start.sequence) continue;
+          const at = cm.ordinalOf(row.id);
+          if (at !== undefined && at + 1 > ordinal) ordinal = at + 1;
+        }
+        entry.ordinal = ordinal;
+      }
+      const ordinal = entry.ordinal;
+      if (entry.inForce) strategy.setAnchorOrdinal(ordinal);
+      if (!this.host.fixed(entry.known ? entry.known.keep : entry.start.epochIds, ordinal, entry.inForce)) continue;
+      this.pending = this.pending.filter((p) => p !== entry);
+      if (!entry.known) {
+        this.host.emitTrace({
+          type: 'tune-out:subconscious-window', agentName: this.host.agentName,
+          epochIds: [...entry.start.epochIds], how: 'fixed', ordinal,
+        });
+      } else if (entry.known.clampedFrom !== undefined) {
+        this.host.emitTrace({
+          type: 'tune-out:subconscious-window', agentName: this.host.agentName,
+          epochIds: [...entry.start.epochIds], how: 'clamped', ordinal, kept: entry.known.clampedFrom,
+        });
+      }
+    }
+  }
+}
+
+/** The anchor the strategy persisted, as an ordinal: undefined where it persisted none, null where it can't be read. */
+function persistedOrdinal(strategy: AnchoredStrategy): number | undefined | null {
+  try {
+    return strategy.getAnchorOrdinal();
+  } catch (error) {
+    console.error(`[tune-out] the subconscious's persisted window start couldn't be read, so the window start stays where it was; the next enter or restart sets it:`, error);
+    return null;
+  }
+}
+
+function sameStart(a: SubconsciousWindowStart, b: SubconsciousWindowStart): boolean {
+  return a.sequence === b.sequence && a.epochIds.length === b.epochIds.length && a.epochIds.every((id) => b.epochIds.includes(id));
+}