@hicaru/pi-rlm 0.3.19 → 0.3.21

package/src/core/session-archive.ts

@@ -0,0 +1,174 @@
+/**
+ * Session archive (recall W1) — the model-reachable copy of elided root history.
+ *
+ * The root context transform (core/root-context.ts) stubs every turn older than the keep
+ * window; before this module those bytes were unrecoverable — the session log is host-side
+ * only and the repl sandbox never saw native read/bash payloads. The archive closes the
+ * loop: every message the elision destroys is recorded here, rendered into markdown
+ * segments, and materialized into the sandbox under `ctx/session-log/` through the SAME
+ * upsert seam native edit/write uses (context/refresh.ts) — so the existing free
+ * search() / grep_context() BM25 recall them (RLM paper §2: context stays an environment;
+ * LLM-memory survey §5: query, not storage, is the recall bottleneck).
+ *
+ * The elision re-runs on EVERY provider call over a fresh clone, so records dedup by
+ * content hash (the transcript is append-only; the same stale turn re-elides each call).
+ * Segment materialization is idempotent per segment path and fail-soft end to end.
+ */
+
+import { truncateOutput } from "../text/parsing.ts";
+
+/** Sandbox namespace the segments materialize under — one wording source for the stubs
+ *  that teach recall (prompts/glossary.ts) and for the materialized paths. */
+export const ARCHIVE_NAMESPACE = "ctx/session-log/";
+
+/** Per-record cap: a 2MB tool payload is archived mid-truncated (head+tail) — recall needs
+ *  the shape and the needles, not every byte (paper A.4 compact-serialization doctrine). */
+const ARCHIVE_RECORD_MAX_CHARS = 100_000;
+/** Host-memory ring cap (chars). Already-materialized segments live in the worker; this
+ *  caps only the host copy. Configurable as `rootArchiveMaxChars` (0 = archive off). */
+export const ARCHIVE_DEFAULT_MAX_CHARS = 2_000_000;
+/** Dedup-set cap: FIFO eviction of the oldest hashes; a re-elided evicted message is
+ *  re-recorded harmlessly (a duplicate segment entry, not a correctness issue). */
+const HASH_SET_MAX = 8_192;
+
+const ARCHIVE_TRUNCATE_MARK = "chars archived out — the middle never enters the archive";
+
+export interface ArchivedEntry {
+  readonly role: "assistant" | "toolResult";
+  readonly toolName: string | undefined;
+  readonly text: string;
+}
+
+/** FNV-1a 32-bit over role+name+text — the dedup key (same double-hash idiom as skillstate). */
+function entryHash(entry: ArchivedEntry): string {
+  const basis = `${entry.role}\u0000${entry.toolName ?? ""}\u0000${entry.text}`;
+  let h1 = 0x811c9dc5;
+  let h2 = 0x811c9dc5;
+  for (let i = 0; i < basis.length; i++) {
+    const c = basis.charCodeAt(i);
+    h1 = (h1 ^ c) * 0x01000193;
+    h2 = (h2 ^ (c + i)) * 0x01000193;
+    h1 >>>= 0;
+    h2 >>>= 0;
+  }
+  return `${h1.toString(36)}${h2.toString(36)}`;
+}
+
+interface RingEntry {
+  readonly seq: number;
+  readonly hash: string;
+  readonly entry: ArchivedEntry;
+}
+
+export interface ArchiveSegment {
+  /** Unique context path for this segment (`ctx/session-log/turn-<a>-<b>.md`). */
+  readonly path: string;
+  readonly text: string;
+}
+
+export class SessionArchive {
+  private ring: RingEntry[] = [];
+  private readonly seen = new Map<string, true>();
+  private totalChars = 0;
+  private nextSeq = 1;
+  private materializedThrough = 0;
+  private lostWhilePending = 0;
+  private pendingChars = 0;
+  private pendingCount = 0;
+
+  constructor(private readonly maxChars: number) {}
+
+  /**
+   * Record one elided message. Returns the assigned seq, or undefined for
+   * empty/duplicate records. Per-record truncation applies BEFORE the ring cap.
+   */
+  record(entry: ArchivedEntry): number | undefined {
+    const text = entry.text.trim();
+    if (text === "") return undefined;
+    const capped: ArchivedEntry = {
+      ...entry,
+      text: text.length > ARCHIVE_RECORD_MAX_CHARS
+        ? truncateOutput(text, ARCHIVE_RECORD_MAX_CHARS, ARCHIVE_TRUNCATE_MARK)
+        : text,
+    };
+    const hash = entryHash(capped);
+    if (this.seen.has(hash)) return undefined;
+    this.seen.set(hash, true);
+    if (this.seen.size > HASH_SET_MAX) {
+      // FIFO: Map preserves insertion order; drop the oldest hash only.
+      const oldest = this.seen.keys().next();
+      if (oldest.done !== true) this.seen.delete(oldest.value);
+    }
+    const seq = this.nextSeq++;
+    this.ring.push({ seq, hash, entry: capped });
+    this.totalChars += capped.text.length;
+    if (seq > this.materializedThrough) {
+      this.pendingChars += capped.text.length;
+      this.pendingCount += 1;
+    }
+    this.evictOverCap();
+    return seq;
+  }
+
+  /** True when unmaterialized records exist (flush when the sandbox is next alive). */
+  get hasPending(): boolean {
+    return this.pendingCount > 0;
+  }
+
+  get pendingCharsValue(): number {
+    return this.pendingChars;
+  }
+
+  /** Telemetry: entries + chars currently held (host copy). */
+  get stats(): { readonly entries: number; readonly chars: number; readonly recorded: number } {
+    return { entries: this.ring.length, chars: this.totalChars, recorded: this.nextSeq - 1 };
+  }
+
+  /**
+   * Render every unmaterialized record into ONE segment and mark it materialized.
+   * Returns undefined when nothing is pending. The path embeds the covered seq range so
+   * segments never collide and the `ctx/session-log/*` glob covers them all.
+   */
+  renderPending(): ArchiveSegment | undefined {
+    const pending = this.ring.filter((r) => r.seq > this.materializedThrough);
+    if (pending.length === 0) return undefined;
+    const parts: string[] = [];
+    if (this.lostWhilePending > 0) {
+      parts.push(
+        `(archive cap dropped ${this.lostWhilePending} older elided turn(s) before materialization)`,
+      );
+      this.lostWhilePending = 0;
+    }
+    for (const r of pending) {
+      const label = r.entry.role === "toolResult" && r.entry.toolName !== undefined
+        ? `${r.entry.role} (${r.entry.toolName})`
+        : r.entry.role;
+      parts.push(`### turn ${r.seq} — ${label}\n${r.entry.text}`);
+    }
+    const first = pending[0]?.seq ?? 0;
+    const last = pending[pending.length - 1]?.seq ?? first;
+    this.materializedThrough = last;
+    this.pendingChars = 0;
+    this.pendingCount = 0;
+    return {
+      path: `${ARCHIVE_NAMESPACE}turn-${first}-${last}.md`,
+      text: parts.join("\n\n"),
+    };
+  }
+
+  /** Ring eviction: drop OLDEST entries until under cap. Evicting an unmaterialized
+   *  record loses it from recall — counted so the next segment says so honestly. */
+  private evictOverCap(): void {
+    while (this.totalChars > this.maxChars && this.ring.length > 1) {
+      const oldest = this.ring[0];
+      if (oldest === undefined) return;
+      this.ring = this.ring.slice(1);
+      this.totalChars -= oldest.entry.text.length;
+      if (oldest.seq > this.materializedThrough) {
+        this.pendingChars -= oldest.entry.text.length;
+        this.pendingCount -= 1;
+        this.lostWhilePending += 1;
+      }
+    }
+  }
+}

package/src/core/types.ts

@@ -13,7 +13,8 @@ export interface RlmConfig {
   readonly enabled: boolean;
   /** Max recursion depth. depth >= maxDepth ⇒ rlm_query falls back to a plain llm_query. */
   readonly maxDepth: number;
-  /** Max turns before the engine must finalize. */
+  /** Max turns before the engine must finalize. Deliberately large — runs end on FINAL
+   *  answer, errors, or wall-clock long before this bites. */
   readonly maxIterations: number;
   /** Per-`repl`-block wall-clock timeout inside the worker (seconds).
    *  v5 doctrine: content limits are the token budget's job — this is a HANG backstop only. */
@@ -120,6 +121,9 @@ export interface RlmConfig {
   readonly skillStateLeafTokens: number;
   /** BM25 score a note must clear before a leaf prompt gets grounded (below ⇒ byte-identical). */
   readonly skillStateMinScore: number;
+  /** BM25 score a note must clear before it enters the Ξ root block (below ⇒ not injected).
+   *  Was effectively 0 (`Number.MIN_VALUE`) — stale cross-session notes rode every prompt. */
+  readonly skillStateXiMinScore: number;
   /** Per-project note cap; LRU by ts with the top-hits quartile pinned (Workstream B). */
   readonly skillStateNotesPerProject: number;
 
@@ -140,6 +144,9 @@ export interface RlmConfig {
   readonly rootContextKeepTurns: number;
   /** Tool-result payloads older than the keep window are preview-capped at this many chars. */
   readonly rootContextElideChars: number;
+  /** Recall W1: host-memory ring cap (chars) for the session archive that makes elision
+   *  dereferenceable (`ctx/session-log/*` in the sandbox). 0 = archive off (plain stubs). */
+  readonly rootArchiveMaxChars: number;
   /** Splice the RootStateTracker Σ snapshot before the last user message each call. */
   readonly rootContextSnapshot: boolean;
   /** WS-4.2 (default OFF, paper §5.7 fence tax): the root may commit ΔΣ_t via a ```state
@@ -181,10 +188,14 @@ export interface RlmInput {
 export interface RlmResult {
   readonly answer: string;
   readonly iterations: number;
-  readonly costUsd: number;
   readonly inputTokens: number;
   readonly outputTokens: number;
   readonly durationMs: number;
+  /** Last non-empty repl stdout of the run (capped, P2 §3.4). The engine itself never reads
+   *  it: a run that ends without `answer[...]` (no final frame) would otherwise score as an
+   *  empty submission even though the winning value was printed. The bench/grader recovers
+   *  that value from here instead of re-running the whole task. */
+  readonly lastStdout: string;
 }
 
 /** A function that runs an RLM to completion — used to wire recursion (rlm_query). */

package/src/index.ts

@@ -29,11 +29,18 @@ import type { AddContextHandlerBundle } from "./bridge/add-context.ts";
 import { buildNativeSystemPrompt } from "./prompts/native.ts";
 import { SkillStore, notesFromRunState, xiQuery } from "./config/skillstate.ts";
 import { buildRootDigestCompaction } from "./core/root-digest.ts";
-import { RootStateTracker } from "./core/root-state.ts";
+import { ROOT_IDLE_DEGRADE_TURNS, RootStateTracker } from "./core/root-state.ts";
 import { elideStalePayloads, spliceSigmaSnapshot } from "./core/root-context.ts";
+import { SessionArchive } from "./core/session-archive.ts";
 import { agentMessageText, firstLine, textContentOf } from "./text/agent-text.ts";
 import { findStatePatches } from "./text/parsing.ts";
 import { capToolResultText } from "./mode/native-guards.ts";
+import {
+  STAGE_CUSTOM_TYPE,
+  renderStageCard,
+  stageCardMarkdown,
+  type StageCardDetails,
+} from "./ui/stage-cards.ts";
 import {
   isSubagentChildBypass,
   commitSubagentForceActivation,
@@ -108,17 +115,36 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     hideWhenEmpty: true,
   });
   let treePanelInstalled = false;
+  /**
+   * Native-mode abort: repl cells' child engines, detached spawn() tasks and add_context
+   * loads read this signal lazily (createReplTool getSignal), so /rlm-stop aborts AND
+   * rotates the controller mid-session — work started after a stop sees a fresh signal.
+   */
+  let nativeAbort = new AbortController();
+  const stopNativeWork = (): boolean => {
+    const hadWork = runRegistry.hasActive() || background.pending > 0;
+    nativeAbort.abort();
+    nativeAbort = new AbortController();
+    return hadWork;
+  };
   /** SKILL.state (Workstream B): session store — hydrated at session_start, flushed at shutdown. */
   let skillStore: SkillStore | undefined;
   /** Root Σ (WS-3/4): the native session's digest-level Σ_t — runtime-derived (tool outcomes,
    *  engine mirrors, prompts); lazily born on the first prompt, harvested + dropped at shutdown. */
   let rootTracker: RootStateTracker | undefined;
+  /** Recall W1: elided turns archive here and materialize into the sandbox
+   *  (ctx/session-log/*) so search()/grep_context() recall them. Per-session, closure-only. */
+  const sessionArchive = new SessionArchive(config.rootArchiveMaxChars);
+  /** Archive gate: enabled (chars > 0) AND the context transform actually running. */
+  const archiveActive = (): boolean =>
+    controller.config.rootArchiveMaxChars > 0 && rootContextActive();
   // Root Σ WS-5.1 telemetry — journal counters (trace lines + status widget when tracing).
   let xiCompositions = 0;
   let rootDigests = 0;
   let elidedMessages = 0;
   let sigmaSplices = 0;
   let idleDegrades = 0;
+  let archivedTurns = 0;
   /** R6: Σ counter snapshot for the status line — a fresh readonly object per render. */
   const sigmaTelemetry = (): RootSigmaTelemetry => ({
     xiCompositions,
@@ -127,6 +153,21 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     sigmaSplices,
     idleDegrades,
   });
+  /** [rlm.stage]: post one stage-transition card into the transcript (persisted, ctrl+o-expandable). */
+  const postStageCard = (details: StageCardDetails): void => {
+    try {
+      pi.sendMessage({ customType: STAGE_CUSTOM_TYPE, content: stageCardMarkdown(details), display: true, details });
+    } catch (err) {
+      // Stage cards are decoration — never fail the hook that produced the transition.
+      if (traceEnabled) trace("stage-card.fail", { error: errorMessage(err) });
+    }
+  };
+  /**
+   * Compaction-hook re-entrancy guard: session_before_compact builds the digest card but does
+   * NOT post it from inside the hook (a message appended mid-compaction would fold into the
+   * very span being digested) — the pending card flushes at the next turn_start instead.
+   */
+  let pendingDigestCard: StageCardDetails | undefined;
   // A detached child works in its OWN sandbox, so this one sees no frames and its request
   // watchdog would fire mid-await and SIGKILL a healthy worker, taking the REPL namespace
   // with it. Keep it alive while detached work is genuinely in flight.
@@ -173,7 +214,9 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const cfg = controller.config;
     // R0: enableSkillState is enforced (validateEnforcedOn) — no config check remains.
     if (skillStore === undefined) return undefined;
-    const block = skillStore.blockFor(query, cfg.skillStateMaxTokens);
+    // Recall W3: the Ξ block honors the configured score floor (was MIN_VALUE — any
+    // positively-scored stale note rode every prompt).
+    const block = skillStore.blockFor(query, cfg.skillStateMaxTokens, cfg.skillStateXiMinScore);
     return block === "" ? undefined : block;
   };
 
@@ -189,6 +232,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   pi.registerMessageRenderer("rlm-intro", (message, _options, theme) =>
     new Markdown(textContentOf(message.content), 1, 0, markdownTheme(theme)),
   );
+  // [rlm.stage] cards — orchestrator stage transitions, collapsed until the user's ctrl+o.
+  pi.registerMessageRenderer(STAGE_CUSTOM_TYPE, renderStageCard);
 
   // ── CLI flag: `pi --rlm` / `pi --rlm=false` overrides the persisted mode for this run ──
   pi.registerFlag("rlm", {
@@ -197,7 +242,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   });
 
   // ── Commands ──
-  registerRlmCommand(pi, controller);
+  registerRlmCommand(pi, controller, stopNativeWork);
   registerRlmConfigCommand(pi, controller);
   registerRlmLlmCommand(pi, controller);
   registerRlmRlmCommand(pi, controller);
@@ -322,6 +367,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           background,
           runRegistry,
           skillStore,
+          getSignal: () => nativeAbort.signal,
           onRunState: (state) => { rootTracker?.absorbEngineState(state); },
           getSkillBlock: composeSkillBlock,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
@@ -362,6 +408,14 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     setRlmModeStatus(ctx, controller, ctx.getContextUsage(), sigmaTelemetry());
   });
 
+  // Deferred [rlm.stage] digest card — built inside session_before_compact, posted here.
+  pi.on("turn_start", async () => {
+    const card = pendingDigestCard;
+    if (card === undefined) return;
+    pendingDigestCard = undefined;
+    postStageCard(card);
+  });
+
   /** True when the native-mode trade holds: enabled AND repl is in the active tool set. */
   const nativeTradeHolds = (): boolean =>
     shouldEnforceNativeReaderBlock({
@@ -423,8 +477,13 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const tracker = rootTracker;
     if (tracker === undefined || !controller.config.enableRootStateFences) return;
     if (event.message.role !== "assistant") return;
+    // Recall W2: a turn that ran TOOLS did work — it is never fence-idle (file-editing
+    // sessions were degrading before their first fence landed). Productive turns neither
+    // grow nor reset the idle streak; prose-only turns keep the R4 ladder.
+    const productiveTurn = Array.isArray(event.message.content) &&
+      (event.message.content as Array<{ type?: string }>).some((b) => b?.type === "toolCall");
     const wasActive = tracker.isActive;
-    const outcome = tracker.applyFences(findStatePatches(agentMessageText(event.message)));
+    const outcome = tracker.applyFences(findStatePatches(agentMessageText(event.message)), { productiveTurn });
     // R3 soak observability: per-turn fence outcomes — the soak-B bars (≥50% of turns commit
     // ≥1 accepted delta, rejection storms <10%) are computed from these journal lines.
     if (traceEnabled) {
@@ -439,6 +498,12 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     }
     if (wasActive && !tracker.isActive) {
       idleDegrades += 1;
+      postStageCard({
+        kind: "degrade",
+        reason: tracker.degradeReason ?? "unknown",
+        idleTurns: tracker.idleTurns,
+        idleMax: ROOT_IDLE_DEGRADE_TURNS,
+      });
       if (traceEnabled) {
         const reason = tracker.degradeReason ?? "unknown";
         trace(reason.startsWith("idle") ? "root-state.idle-degrade" : "root-state.degrade", {
@@ -446,6 +511,9 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           reason,
         });
       }
+    } else if (!wasActive && tracker.isActive) {
+      // R7-fix recovery observability, user-visible: a degraded tracker accepted a clean batch.
+      postStageCard({ kind: "recover", fencesAccepted: outcome.accepted, fencesTotal: outcome.fences });
     }
   });
 
@@ -462,6 +530,14 @@ export default function rlmExtension(pi: ExtensionAPI): void {
       });
       if (result !== undefined) {
         rootDigests += 1;
+        pendingDigestCard = {
+          kind: "digest",
+          index: rootDigests,
+          turnsFolded: event.preparation.messagesToSummarize.length,
+          tokensBefore: result.compaction.tokensBefore,
+          tokensBeforeRecomputed: result.tokensBeforeRecomputed,
+          summary: result.compaction.summary,
+        };
         if (traceEnabled) {
           // V1 soak probe: host-consumed tokensBefore vs our recomputation over the same span.
           trace("root-digest.built", {
@@ -486,7 +562,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // ── Context injection: listing of whatever is currently loaded ──
   // Re-inject only when the payload identity changes (seed / add_context), not every turn —
   // the listing can be up to 200 file lines and the plugin exists to shrink the root window.
-  pi.on("context", async (event) => {
+  pi.on("context", async (event, ctx) => {
     const filtered = event.messages.filter(
       (message) =>
         !(message.role === "custom" && message.customType === "rlm-intro")
@@ -499,10 +575,23 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     // then splice exactly one fresh Σ snapshot. Fail-soft: a throw here must never break a turn.
     if (rootContextActive()) {
       try {
-        const elided = elideStalePayloads(filtered, {
-          keepTurns: controller.config.rootContextKeepTurns,
-          elideChars: controller.config.rootContextElideChars,
-        });
+        // Recall W1: every destroyed message's full text rides the sink into the session
+        // archive BEFORE the stub replaces it — elision stays dereferenceable.
+        const sink = archiveActive()
+          ? (entry: { role: "assistant" | "toolResult"; toolName: string | undefined; text: string }) => {
+              const seq = sessionArchive.record(entry);
+              if (seq !== undefined) archivedTurns += 1;
+            }
+          : undefined;
+        const elided = elideStalePayloads(
+          filtered,
+          {
+            keepTurns: controller.config.rootContextKeepTurns,
+            elideChars: controller.config.rootContextElideChars,
+            archiveActive: sink !== undefined,
+          },
+          sink,
+        );
         elidedMessages += elided;
         const tracker = rootTracker;
         // R4 REV (amnesia fix): degrade suspends fence WRITES (applyFences gate) — never Σ
@@ -523,8 +612,31 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           });
           sigmaSplices += 1;
         }
+        // Recall W1 flush: materialize new archive segments into the sandbox — ONLY when a
+        // worker already exists (never spawn Python from a context event) and fail-soft.
+        const pendingSegment = archiveActive() && sandboxManager.isAlive
+          ? sessionArchive.renderPending()
+          : undefined;
+        if (pendingSegment !== undefined) {
+          const cwd = resolve(ctx?.cwd ?? process.cwd());
+          const written = await sandboxManager.upsertArchiveSegment(pendingSegment.path, pendingSegment.text, cwd);
+          if (traceEnabled) {
+            trace("root-archive.flush", {
+              path: pendingSegment.path,
+              chars: pendingSegment.text.length,
+              written,
+              stats: sessionArchive.stats,
+            });
+          }
+        }
         if (traceEnabled && (elided > 0 || sigmaSplices > 0)) {
-          trace("root-context.transform", { elided, total: elidedMessages, splices: sigmaSplices });
+          trace("root-context.transform", {
+            elided,
+            total: elidedMessages,
+            splices: sigmaSplices,
+            archived: archivedTurns,
+            archiveChars: sessionArchive.stats.chars,
+          });
         }
       } catch (err) {
         if (traceEnabled) trace("root-context.fail", { error: errorMessage(err) });
@@ -571,6 +683,13 @@ export default function rlmExtension(pi: ExtensionAPI): void {
         event.isError,
         event.isError ? firstLine(textContentOf(event.content)) : "",
       );
+      // Recall W2 deterministic harvest (commit-at-first-sight, paper §7): successful reads
+      // are Σ facts the moment they happen — previously the only runtime feeds were tool
+      // ERRORS and edits, so the early turns (the ones elided first) never reached Σ.
+      if (!event.isError && event.toolName === "read") {
+        const path = extractEditPaths(event.input)[0];
+        if (path !== undefined) tracker.noteFact(`read ${path}`);
+      }
     }
 
     // ── Keep RLM context fresh after native file mutations ──
@@ -617,14 +736,25 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const tracker = rootTracker;
     if (skillStore !== undefined && tracker !== undefined && tracker.dirty) {
       try {
-        skillStore.merge(notesFromRunState(tracker.snapshot()));
-        if (traceEnabled) trace("root-harvest.merged", { notes: tracker.snapshot().verifiedFacts.length });
+        const merged = notesFromRunState(tracker.snapshot());
+        skillStore.merge(merged);
+        if (merged.length > 0) {
+          // One-line stage card: what this session taught the store (tag histogram via stats()).
+          postStageCard({
+            kind: "distill",
+            merged,
+            total: skillStore.noteCount,
+            byTag: skillStore.stats().byTag,
+          });
+        }
+        if (traceEnabled) trace("root-harvest.merged", { notes: merged.length });
       } catch (err) {
         if (traceEnabled) trace("root-harvest.fail", { error: errorMessage(err) });
       }
     }
     await skillStore?.flush(); // SKILL.state (Workstream B): persist distilled notes
     controller.abort();
+    nativeAbort.abort(); // detach engines/spawns still holding the session signal
     clearInterval(watchdogHeartbeat);
     background.dispose();
     await sandboxManager.dispose();

package/src/mode/rlm-mode.ts

@@ -120,10 +120,10 @@ export class RlmController {
   }
 
   /** Ξ (Workstream C): BM25 slice of the session SkillState for a root prompt; undefined when
-   *  the store is absent/disabled or nothing is relevant. */
+   *  the store is absent/disabled or nothing is relevant. Recall W3: honors the Ξ score floor. */
   private skillBlockFor(query: string): string | undefined {
     if (this.skillStore === undefined || !this.config.enableSkillState) return undefined;
-    const block = this.skillStore.blockFor(query, this.config.skillStateMaxTokens);
+    const block = this.skillStore.blockFor(query, this.config.skillStateMaxTokens, this.config.skillStateXiMinScore);
     return block === "" ? undefined : block;
   }
 

package/src/prompts/glossary.ts

@@ -7,6 +7,8 @@
  * about functions that do not exist, or not told about ones that do.
  */
 
+import { ARCHIVE_NAMESPACE } from "../core/session-archive.ts";
+
 export type ContextKind = "files" | "text";
 
 /** "str" (raw string context, e.g. rlm_query children) → text; everything else → files. */
@@ -28,9 +30,11 @@ export function promptCapTokensK(maxPromptChars: number): number {
  * the outcome (§5, Fig. 4a). These cost no tokens and no sub-calls.
  */
 const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
-  "- `search(query: str, k=10, path_glob=None)`: BM25 ranking over `context`. Returns",
-  "  [{path, line, score, snippet, text}] — POINTERS, not bodies (`text` aliases `snippet`).",
-  "  **Start here.** Free: no sub-LLM call. Use before guessing filenames.",
+  "- `search(query: str, k=10, path_glob=None)`: BM25 ranking over `context` (stemmed, with",
+  "  query expansion — try plain words, not just exact identifiers). Returns",
+  "  [{path, line, end, score, snippet, text}] — POINTERS, not bodies (`text` aliases",
+  "  `snippet`; line..end is the match span; `index_truncated: true` means the context tail",
+  "  is NOT indexed — narrow with path_glob). **Start here.** Free: no sub-LLM call.",
   "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> dict`: regex over",
   "  `context`. Returns {hits: [{path, line, text, snippet}], counts, total, truncated} —",
   "  `counts` is complete even when `hits` is capped, so a wide pattern reports its shape",
@@ -56,6 +60,15 @@ const SKILL_SEARCH_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "  smells like something already learned — do not re-discover it.",
 ]);
 
+/** W3 recall discoverability: the condensed NATIVE twins. glossary doctrine — divergence
+ *  between the headless and native surfaces is a bug; `skill_search` had no native twin, so
+ *  native models could not discover cross-session recall at all (and the archive line
+ *  teaches the ctx/session-log recall that honest elision stubs point at). */
+export const SKILL_SEARCH_LINE_NATIVE =
+  "- `skill_search(query, k=8) -> [{id, text, tags, score}]` — BM25 over distilled project facts from PRIOR sessions. Free; use before re-discovering a learned config/gotcha/symbol.";
+export const ARCHIVE_RECALL_LINE_NATIVE =
+  `- Elided chat turns are archived in the sandbox: \`search("<keywords>", path_glob="${ARCHIVE_NAMESPACE}*")\` / \`grep_context()\` recall text that scrolled out of your context — free, no sub-LLM call.`;
+
 /** Single source of wording for the injected SkillState block (headless + native, Workstream C).
  *  Takes the dynamic body as an argument — the glossary itself stays static-only. */
 /** One wording source for the skill_search recall hint (Ξ block + root Σ snapshot). */
@@ -63,9 +76,22 @@ export const SKILL_RECALL_LINE =
   "Recall more anytime inside repl: `skill_search(query, k=8)` → [{id, text, tags, score}].";
 
 /** R5 (G4, /tmp/ROOT_FULL_SKILLSTATE_PLAN.md): the one-line replacement for assistant prose
- *  older than the keep window — durable facts live in Σ, the full text in the session log. */
+ *  older than the keep window — durable facts live in Σ; the repl sandbox (answers/vars) is
+ *  the model-reachable recovery channel for repl-owned payloads. Stubs must promise only a
+ *  channel that actually holds the bytes (recall W1): repl-owned payloads → the repl line,
+ *  native payloads → the archive line (searchable `ctx/session-log/`), else the plain line. */
 export const ROOT_TURN_ELIDED_LINE =
-  "… turn elided — durable facts live in Σ; full text in session log";
+  "… turn elided — durable facts live in Σ; your repl sandbox persists: print(answers) / SHOW_VARS() to re-derive";
+export const ROOT_TURN_ELIDED_ARCHIVE_LINE =
+  `… turn elided — durable facts live in Σ; the full text is archived in the sandbox: ` +
+  `search('<keywords>', path_glob='${ARCHIVE_NAMESPACE}*') or grep_context() recalls it`;
+export const ROOT_TURN_ELIDED_PLAIN_LINE =
+  "… turn elided — durable facts live in Σ";
+/** Preview mark twin: payloads kept as head+tail previews point at the same archive. */
+export const ROOT_ELIDE_PREVIEW_MARK =
+  `chars elided — full text archived under ${ARCHIVE_NAMESPACE} (search/grep_context it)`;
+export const ROOT_ELIDE_PREVIEW_MARK_REPL =
+  "chars elided — repl sandbox persists: print(answers[k]) or re-run repl to re-derive";
 
 export function skillStateLines(noteCount: number, body: string): string {
   return [
@@ -341,6 +367,9 @@ export function replGlossary(
   lines.push(
     "- `llm_query(prompt: str) -> Task`: spawn one sub-LLM (await_task for str). The prompt must",
     "  **contain the text** to analyze — this call has no filesystem and no `context`.",
+    "  Leaf convention: a sub-LLM answers exactly `NOT_FOUND` when its slice lacks the answer —",
+    "  treat that as \"not in this slice\": slice differently, search elsewhere, or narrow the ask.",
+    "  Never re-send an identical prompt hoping for a different verdict.",
     "- `llm_batch(prompts: list[str]) -> Task`: many parallel one-shots (same rule: embed text).",
     "  await_task → ordered list[str]. NEVER pass bare file paths as if the worker can open them.",
     ...CHUNKED_GLOSSARY_LINES,
@@ -393,6 +422,8 @@ export function replGlossary(
     '- `answer`: a dict initialized to {"content": "", "ready": False}. To submit your final answer,',
     '  set `answer["content"]` to the answer text and `answer["ready"] = True`.',
     '  **You MUST flip `answer["ready"] = True` — runs that never finalize are discarded.**',
+    '  Never write FINAL(...) / FINAL_VAR(...) prose and never emit a ```state fence in the',
+    '  reply that finalizes — `answer` is the only finalize channel; Σ bookkeeping waits.',
   );
   return lines.join("\n");
 }

package/src/prompts/native.ts

@@ -6,11 +6,13 @@
  */
 
 import {
+  ARCHIVE_RECALL_LINE_NATIVE,
   CHUNKED_GLOSSARY_LINE_NATIVE,
   ENV_TIPS_CONDENSED,
   LARGE_FILE_RULE_NATIVE,
   DEFAULT_PROMPT_CAP,
   promptCapTokensK,
+  SKILL_SEARCH_LINE_NATIVE,
 } from "./glossary.ts";
 import { STATE_FENCE_INSTRUCTION } from "../core/run-state.ts";
 
@@ -25,6 +27,7 @@ function nativeReplGlossary(): string {
     "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet, text}]` — BM25 pointers, not bodies",
     "- `grep_context(pattern, k=50, …) -> {hits, counts, total, truncated}` — regex / lexical needles",
     "- `outline(path) -> str` — definition skeleton (~200 chars)",
+    ARCHIVE_RECALL_LINE_NATIVE,
     "",
     "### Always-spawn fan-out (return Task + run ↯bg — NEVER the answer)",
     "| Call | await_task → | When | NOT for |",
@@ -47,6 +50,7 @@ function nativeReplGlossary(): string {
     "- `answers` / `plan` — persistent dicts for **collected** results. Task handles are REPL vars (`t`), not `answers` keys.",
     "- `add_context(source) -> dict` — append external dir/file/doc/git under `ctx/<id>/…` (metadata only).",
     "- `list_claims()` — the live `[ledger]` table of agent work.",
+    SKILL_SEARCH_LINE_NATIVE,
     "- `SHOW_VARS()` — list REPL vars (Tasks as `<Task …>`). `list_tasks()` finds Task handles. `answer[\"ready\"]=True` only for headless finalize (native: write a normal message).",
     "",
     ENV_TIPS_CONDENSED,
@@ -189,8 +193,10 @@ export function buildNativeSystemPrompt(opts?: { readonly stateFences?: boolean
   ].join("\n");
 }
 
-/** Soft cap on the static native prompt. Raised for v5-style contract/routing/examples. */
-export const NATIVE_PROMPT_BUDGET = 9_500;
+/** Soft cap on the static native prompt. Raised for v5-style contract/routing/examples;
+ *  recall W3 raised it again (+200) for the archive-recall + skill_search twin lines —
+ *  the model cannot recall elided turns or prior-session facts it is never told about. */
+export const NATIVE_PROMPT_BUDGET = 9_700;
 
 /** Exported for tests — prompt length without context metadata (which is injected separately). */
 export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();