sentinelayer-cli 0.39.2 → 0.41.0

package/src/session/recall/retrieve.js

@@ -0,0 +1,374 @@
+/**
+ * ENGRAM §1 — the Recall Engine (ENGRAM §7).
+ *
+ * Query path, faithful to §7 (no LLM in the hot path):
+ *   1. query embed (256-d int8) + entity-mention match
+ *   2a. dense candidates: EXACT int8 scan (no ANN — small-data, Thesis 1)
+ *   2b. lexical candidates: BM25 (FTS5-equivalent, ruling #1), in parallel
+ *   3.  RRF-pool 2a + 2b + entity matches -> candidate set (rank-based fusion)
+ *   4.  bounded spreading activation: BFS over the entity graph from the
+ *       pooled seeds (the first diffusion hops of §7's forward-push PPR;
+ *       full ACL push-PPR is the P1 upgrade)
+ *   5.  fusion score = cos + log(1+PPR-mass) + ACT-R B(m); order the pool
+ *   6.  assemble results + provenance path evidence
+ *
+ * POOLING (RRF + expansion, builds the candidate set) and ORDERING (the
+ * fusion score) are separate jobs, per §7. `candidatePoolIds` is the
+ * pre-rerank pool the Needle-Scatter benchmark measures.
+ *
+ * Determinism: every sort has an explicit tie-breaker; B(m) `now` is
+ * injectable. Same inputs -> byte-identical ranking.
+ */
+
+import { normInt8, cosineInt8 } from "./embedder.js";
+import { matchQueryEntities } from "./entities.js";
+import { buildProvenance, observationNeighbors } from "./provenance.js";
+import { BM25_K1, BM25_B } from "./index-core.js";
+import { queryTokens } from "./text.js";
+
+export const RECALL_DEFAULTS = Object.freeze({
+  k: 12,
+  rrfK: 60,
+  denseChannelDepth: 100, // top-N dense hits that feed RRF
+  denseCosThreshold: 0.12, // dense hits below this are collision noise (esp. for the stub embedder)
+  expansionHops: 8, // bounded BFS depth (>= needle chain length so 8-chains complete)
+  expansionDecay: 0.85, // per-hop mass decay
+  expansionSeedCount: 24, // top-RRF observations used as diffusion seeds
+  hubDegreeCap: 40, // entities bound to more obs than this don't carry activation
+  poolCap: 512, // hard cap on candidate-pool size
+  expansionWeight: 0.1, // scales diffusion mass into the PPR-stand-in term
+});
+
+// Fusion weights. Fixed, interpretable constants for P0; learned weights
+// trained on the rehearsal loop are the §7 P1 upgrade. `ppr` (the rank-based
+// RRF+diffusion pool, which carries the precise BM25 signal) leads; raw cos
+// from the deterministic stub is a minor tie-shaper only.
+export const RECALL_WEIGHTS = Object.freeze({ cos: 0.2, ppr: 1.0, actr: 0.25 });
+
+function sortedByScoreDesc(scoreById, order) {
+  // order: canonical obs order for deterministic tie-breaking.
+  const rankIndex = new Map();
+  order.forEach((id, i) => rankIndex.set(id, i));
+  return Array.from(scoreById.entries())
+    .sort((a, b) => {
+      if (b[1] !== a[1]) return b[1] - a[1];
+      return (rankIndex.get(a[0]) ?? 0) - (rankIndex.get(b[0]) ?? 0);
+    })
+    .map(([id]) => id);
+}
+
+/** Dense exact int8 scan. Returns cosById (all) + top-depth ranked list. */
+function denseChannel(index, queryVec, depth, threshold) {
+  const queryNorm = normInt8(queryVec);
+  const cosById = new Map();
+  for (const obsId of index.order) {
+    const vec = index.dense.vectors.get(obsId);
+    const cos = cosineInt8(queryVec, vec, queryNorm, index.dense.norms.get(obsId));
+    cosById.set(obsId, cos);
+  }
+  const ranked = sortedByScoreDesc(
+    new Map(Array.from(cosById.entries()).filter(([, cos]) => cos >= threshold)),
+    index.order,
+  ).slice(0, depth);
+  return { cosById, ranked };
+}
+
+/** BM25 lexical channel (FTS5-equivalent). Returns scoreById + ranked list. */
+function bm25Channel(index, queryTokens) {
+  const { postings, df, docLen, avgdl, N } = index.bm25;
+  const scoreById = new Map();
+  if (N === 0 || avgdl === 0) return { scoreById, ranked: [] };
+  const seen = new Set();
+  for (const term of queryTokens) {
+    if (seen.has(term)) continue;
+    seen.add(term);
+    const bucket = postings.get(term);
+    if (!bucket) continue;
+    const termDf = df.get(term) || bucket.size;
+    const idf = Math.log(1 + (N - termDf + 0.5) / (termDf + 0.5));
+    for (const [obsId, tf] of bucket.entries()) {
+      const dl = docLen.get(obsId) || 0;
+      const denom = tf + BM25_K1 * (1 - BM25_B + (BM25_B * dl) / avgdl);
+      const contribution = idf * ((tf * (BM25_K1 + 1)) / (denom || 1));
+      scoreById.set(obsId, (scoreById.get(obsId) || 0) + contribution);
+    }
+  }
+  return { scoreById, ranked: sortedByScoreDesc(scoreById, index.order) };
+}
+
+/** Entity-match channel with inverse-degree (IDF-like) weighting of hits. */
+function entityChannel(index, matchedEntityIds) {
+  const scoreById = new Map();
+  const seedObs = new Set();
+  for (const entityId of matchedEntityIds) {
+    const peers = index.graph.entityToObs.get(entityId);
+    if (!peers) continue;
+    const degree = peers.size;
+    const weight = 1 / Math.log2(2 + degree); // hubs contribute little
+    const isHub = degree > RECALL_DEFAULTS.hubDegreeCap;
+    for (const obsId of peers) {
+      scoreById.set(obsId, (scoreById.get(obsId) || 0) + weight);
+      if (!isHub) seedObs.add(obsId); // only specific entities seed expansion
+    }
+  }
+  return { scoreById, ranked: sortedByScoreDesc(scoreById, index.order), seedObs };
+}
+
+/** Reciprocal-rank fusion over the channel ranked lists. */
+function reciprocalRankFusion(rankedLists, rrfK) {
+  const rrfById = new Map();
+  for (const ranked of rankedLists) {
+    ranked.forEach((obsId, i) => {
+      const rank = i + 1;
+      rrfById.set(obsId, (rrfById.get(obsId) || 0) + 1 / (rrfK + rank));
+    });
+  }
+  return rrfById;
+}
+
+/**
+ * Bounded spreading activation: BFS over the entity graph from seed
+ * observations, decaying mass each hop. Returns expansionMassById (max mass
+ * reached per observation). The first diffusion hops of §7's PPR.
+ */
+function spreadActivation(index, seedObsIds, { hops, decay, hubDegreeCap, poolCap }) {
+  const massById = new Map();
+  let frontier = [];
+  for (const seed of seedObsIds) {
+    massById.set(seed, 1);
+    frontier.push(seed);
+  }
+  const visitedCap = poolCap * 4;
+  for (let hop = 1; hop <= hops; hop += 1) {
+    if (massById.size >= visitedCap) break;
+    const hopMass = decay ** hop;
+    const next = [];
+    for (const obsId of frontier) {
+      const neighbors = observationNeighbors(index, obsId, { hubDegreeCap });
+      for (const neighbor of Array.from(neighbors.keys()).sort()) {
+        if (!massById.has(neighbor)) {
+          massById.set(neighbor, hopMass);
+          next.push(neighbor);
+          if (massById.size >= visitedCap) break;
+        }
+      }
+      if (massById.size >= visitedCap) break;
+    }
+    if (next.length === 0) break;
+    frontier = next;
+  }
+  return massById;
+}
+
+/** ACT-R base-level activation: B(m) = ln Σ_j (t_now - t_j)^(-0.5). */
+function actrActivation(occurrences, nowMs) {
+  if (!occurrences || occurrences.length === 0) return 0;
+  let sum = 0;
+  for (const occ of occurrences) {
+    const dtSeconds = Math.max((nowMs - (occ.atMs || 0)) / 1000, 1); // floor at 1s
+    sum += dtSeconds ** -0.5;
+  }
+  return sum > 0 ? Math.log(sum) : 0;
+}
+
+function normalizeMap(valueById, ids) {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const id of ids) {
+    const v = valueById.get(id) ?? 0;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  const range = max - min;
+  const out = new Map();
+  for (const id of ids) {
+    const v = valueById.get(id) ?? 0;
+    out.set(id, range > 0 ? (v - min) / range : 0);
+  }
+  return out;
+}
+
+/**
+ * Run recall over a built index.
+ *
+ * @param {object} index  From buildRecallIndex().
+ * @param {object} params
+ * @param {string} params.query   The need / question.
+ * @param {number} [params.k=12]
+ * @param {string} [params.role]  Optional role lens folded into the query.
+ * @param {number} [params.now]   Epoch ms for ACT-R (default Date.now()).
+ * @param {object} [params.weights]  Override RECALL_WEIGHTS.
+ * @param {object} [params.tuning]   Override RECALL_DEFAULTS knobs.
+ * @returns {{results: object[], candidatePoolIds: string[], poolSize: number,
+ *            matchedEntityIds: string[], query: string, k: number, weights: object}}
+ */
+export function recall(index, {
+  query = "",
+  k = RECALL_DEFAULTS.k,
+  role = "",
+  now = Date.now(),
+  weights = RECALL_WEIGHTS,
+  tuning = {},
+} = {}) {
+  const cfg = { ...RECALL_DEFAULTS, ...tuning };
+  const w = { ...RECALL_WEIGHTS, ...weights };
+  const rawQueryText = [String(query || ""), String(role || "")].filter((s) => s.trim()).join(" ").trim();
+  // Strip query stopwords so the weak deterministic stub and BM25 both focus
+  // on the query's meaningful anchors (see text.js QUERY_STOPWORDS).
+  const qTokens = queryTokens(rawQueryText);
+  const queryText = qTokens.join(" ") || rawQueryText;
+  const normalizedK = Math.max(1, Math.floor(Number(k) || RECALL_DEFAULTS.k));
+
+  // --- Channels (2a dense / 2b lexical / entity) ---
+  const queryVec = index.embedder.embed(queryText);
+  const dense = denseChannel(index, queryVec, cfg.denseChannelDepth, cfg.denseCosThreshold);
+  const lexical = bm25Channel(index, qTokens);
+  const matchedEntityIds = matchQueryEntities(index.graph.entities, queryText);
+  const entity = entityChannel(index, matchedEntityIds);
+
+  // --- 3. RRF pool ---
+  const rrfById = reciprocalRankFusion([dense.ranked, lexical.ranked, entity.ranked], cfg.rrfK);
+
+  // Direct-match set = observations any channel ranked (rrf > 0): the query's
+  // own hits, and the seed set for provenance.
+  const directSeeds = new Set(rrfById.keys());
+
+  // --- 4. Bounded spreading activation ---
+  // Expansion seeds are PRECISION-GATED: only high-confidence direct matches
+  // may diffuse. A BM25 hit is an exact lexical match; a strong-dense hit
+  // clears a higher cos bar than the pool threshold; matched non-hub entities
+  // seed too. This stops a low-confidence dense COLLISION from seeding a
+  // whole unrelated cluster into the pool.
+  const expansionSeeds = new Set([...lexical.ranked, ...entity.seedObs]);
+  for (const id of dense.ranked) {
+    if ((dense.cosById.get(id) || 0) >= cfg.seedCosThreshold) expansionSeeds.add(id);
+  }
+  const expansionMassById = spreadActivation(index, expansionSeeds, {
+    hops: cfg.expansionHops,
+    decay: cfg.expansionDecay,
+    hubDegreeCap: cfg.hubDegreeCap,
+    poolCap: cfg.poolCap,
+  });
+
+  // --- Candidate pool (pre-rerank): rrf>0 OR reached by expansion ---
+  // Unified pool scale (the §7 "PPR mass" stand-in): a seed / direct match
+  // carries base mass 1 PLUS its rank-based RRF; an item reached ONLY by
+  // diffusion carries its decayed mass (< 1). So a direct query hit ALWAYS
+  // outranks pure diffusion, while a deep-chain tail (pure diffusion) still
+  // sits above collision noise. `expansionWeight` scales diffusion influence.
+  const poolScoreById = new Map();
+  const poolIdSet = new Set();
+  for (const id of directSeeds) poolIdSet.add(id);
+  for (const id of expansionMassById.keys()) poolIdSet.add(id);
+  for (const id of poolIdSet) {
+    const rrf = rrfById.get(id) || 0;
+    const mass = expansionMassById.get(id) || 0;
+    const isSeed = expansionSeeds.has(id);
+    const graphMass = isSeed ? 1 : cfg.expansionWeight * mass;
+    poolScoreById.set(id, graphMass + rrf);
+  }
+  // Cap the pool deterministically by pool score.
+  let poolIds = sortedByScoreDesc(poolScoreById, index.order);
+  if (poolIds.length > cfg.poolCap) poolIds = poolIds.slice(0, cfg.poolCap);
+
+  // --- 5. Fusion score over the pool ---
+  // Evidence TIER dominates the ordering, then the fusion blend orders within
+  // a tier (§7 intent: seeds/direct matches > graph-diffused > weak signal).
+  // This is what stops the stub's cos noise on a weak-direct collision from
+  // outranking a legitimate graph-diffused chain member (whose cos is 0).
+  //   tier 3: direct strong match (an expansion seed: BM25 hit / strong dense / entity)
+  //   tier 2: reached by graph diffusion (not a seed)
+  //   tier 1: weak direct only (dense hit below the seed bar, no diffusion)
+  const TIER_WEIGHT = 10;
+  const tierById = new Map();
+  for (const id of poolIds) {
+    if (expansionSeeds.has(id)) tierById.set(id, 3);
+    else if ((expansionMassById.get(id) || 0) > 0) tierById.set(id, 2);
+    else tierById.set(id, 1);
+  }
+
+  const cosPosById = new Map();
+  const pprById = new Map();
+  const actrById = new Map();
+  for (const id of poolIds) {
+    cosPosById.set(id, Math.max(0, dense.cosById.get(id) || 0));
+    pprById.set(id, Math.log(1 + (poolScoreById.get(id) || 0)));
+    actrById.set(id, actrActivation(index.occurrences.get(id), now));
+  }
+  const cosN = normalizeMap(cosPosById, poolIds);
+  const pprN = normalizeMap(pprById, poolIds);
+  const actrN = normalizeMap(actrById, poolIds);
+
+  const finalScoreById = new Map();
+  for (const id of poolIds) {
+    const within =
+      w.cos * (cosN.get(id) || 0) + w.ppr * (pprN.get(id) || 0) + w.actr * (actrN.get(id) || 0);
+    finalScoreById.set(id, TIER_WEIGHT * (tierById.get(id) || 1) + within);
+  }
+
+  const ordered = Array.from(poolIds).sort((a, b) => {
+    const sa = finalScoreById.get(a) || 0;
+    const sb = finalScoreById.get(b) || 0;
+    if (sb !== sa) return sb - sa;
+    // tie-break: higher pool score, then more recent (sequenceId desc), then id.
+    const pa = poolScoreById.get(a) || 0;
+    const pb = poolScoreById.get(b) || 0;
+    if (pb !== pa) return pb - pa;
+    const obsA = index.byId.get(a);
+    const obsB = index.byId.get(b);
+    const seqA = obsA?.sequenceId || 0;
+    const seqB = obsB?.sequenceId || 0;
+    if (seqB !== seqA) return seqB - seqA;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+
+  const topIds = ordered.slice(0, normalizedK);
+
+  // --- 6. Assemble results + provenance ---
+  const denseTopSet = new Set(dense.ranked);
+  const bm25Set = new Set(lexical.ranked);
+  const entitySet = new Set(entity.ranked);
+  const results = topIds.map((id) => {
+    const obs = index.byId.get(id);
+    const channels = [];
+    if (denseTopSet.has(id)) channels.push("dense");
+    if (bm25Set.has(id)) channels.push("bm25");
+    if (entitySet.has(id)) channels.push("entity");
+    const provenance = buildProvenance(
+      index,
+      id,
+      { obsIds: directSeeds, entityIds: matchedEntityIds, channels },
+      { maxHops: 4, hubDegreeCap: cfg.hubDegreeCap },
+    );
+    return {
+      observationId: id,
+      sequenceId: obs?.sequenceId || 0,
+      ts: obs?.ts || "",
+      agentId: obs?.agentId || "",
+      kind: obs?.kind || "",
+      snippet: obs?.snippet || "",
+      text: obs?.text || "",
+      score: Number((finalScoreById.get(id) || 0).toFixed(6)),
+      breakdown: {
+        cos: Number((dense.cosById.get(id) || 0).toFixed(6)),
+        rrf: Number((rrfById.get(id) || 0).toFixed(6)),
+        expansion: Number((expansionMassById.get(id) || 0).toFixed(6)),
+        actr: Number((actrById.get(id) || 0).toFixed(6)),
+        channels,
+        viaExpansionOnly: !directSeeds.has(id),
+      },
+      provenance,
+    };
+  });
+
+  return {
+    query: queryText,
+    k: normalizedK,
+    results,
+    candidatePoolIds: poolIds,
+    poolSize: poolIds.length,
+    matchedEntityIds,
+    weights: w,
+    tuning: cfg,
+  };
+}

package/src/session/recall/token-stats.js

@@ -0,0 +1,81 @@
+/**
+ * ENGRAM §1 — token accounting for the "hydration cost decouples from
+ * session length" claim (stack doc §1).
+ *
+ * Compares the cost of the STATUS QUO (replay the full material transcript)
+ * against the ENGRAM path (retrieve top-K memories + provenance). Uses the
+ * Anthropic tokenizer when available (agents here are Claude/codex), with a
+ * deterministic chars/4 fallback so tests never depend on the native module.
+ */
+
+let cachedCounter;
+
+async function getCounter() {
+  if (cachedCounter !== undefined) return cachedCounter;
+  try {
+    const mod = await import("@anthropic-ai/tokenizer");
+    cachedCounter = typeof mod.countTokens === "function" ? mod.countTokens : null;
+  } catch {
+    cachedCounter = null;
+  }
+  return cachedCounter;
+}
+
+/**
+ * Count tokens in a string. Falls back to a chars/4 estimate.
+ * @param {string} text
+ * @returns {Promise<{tokens: number, method: string}>}
+ */
+export async function countTextTokens(text) {
+  const value = String(text ?? "");
+  const counter = await getCounter();
+  if (counter) {
+    try {
+      return { tokens: counter(value), method: "anthropic-tokenizer" };
+    } catch {
+      // fall through to estimate
+    }
+  }
+  return { tokens: Math.ceil(value.length / 4), method: "chars/4-estimate" };
+}
+
+/** Render a full-replay transcript line for an observation. */
+function transcriptLine(obs) {
+  const ts = obs.ts || "";
+  const agent = obs.agentId || "unknown";
+  const kind = obs.kind || "event";
+  return `${ts} ${agent} ${kind}: ${obs.text}`.trim();
+}
+
+/** Render a compact recall-pack line (snippet + provenance) for a result. */
+function packLine(result) {
+  const seq = result.sequenceId ? `#${result.sequenceId} ` : "";
+  return `${seq}${result.agentId} ${result.kind}: ${result.snippet} [why: ${result.provenance}]`.trim();
+}
+
+/**
+ * Compute the token cut of recall-vs-replay for a session.
+ *
+ * @param {object} params
+ * @param {object[]} params.observations  All material observations (full replay).
+ * @param {object[]} params.results       The recall results (the pack).
+ * @returns {Promise<{fullReplayTokens:number, recallPackTokens:number,
+ *   reductionRatio:number, reductionPct:number, method:string,
+ *   replayEvents:number, packEvents:number}>}
+ */
+export async function computeTokenCut({ observations = [], results = [] }) {
+  const fullText = observations.map(transcriptLine).join("\n");
+  const packText = results.map(packLine).join("\n");
+  const full = await countTextTokens(fullText);
+  const pack = await countTextTokens(packText);
+  const ratio = pack.tokens > 0 ? full.tokens / pack.tokens : 0;
+  return {
+    fullReplayTokens: full.tokens,
+    recallPackTokens: pack.tokens,
+    reductionRatio: Number(ratio.toFixed(2)),
+    reductionPct: full.tokens > 0 ? Number((100 * (1 - pack.tokens / full.tokens)).toFixed(1)) : 0,
+    method: full.method,
+    replayEvents: observations.length,
+    packEvents: results.length,
+  };
+}

package/src/session/recap.js

@@ -5,9 +5,8 @@ import process from "node:process";
 
 import { createAgentEvent } from "../events/schema.js";
 import { dedupeSessionEvents } from "./event-identity.js";
-import { summarizeListeners } from "./listeners.js";
 import { resolveSessionPaths } from "./paths.js";
-import { appendToStream, readStream } from "./stream.js";
+import { readStream } from "./stream.js";
 import { getSession } from "./store.js";
 import { aggregateSessionUsage } from "./usage.js";
 
@@ -1107,13 +1106,13 @@ const AGENT_JOIN_RULES = [
   "",
   "**Reading the room** — When you join, the recap above summarizes activity since the last quiet stretch. To read further back, run `sl session read --remote --tail 50 --json` (bump `--tail` if you need more). Do this BEFORE responding so you don't repeat questions or miss a lock-and-claim someone else already opened.",
   "",
-  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen` or `sl session read --remote --tail N`). `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. More frequent than that wastes budget and can hit per-user rate limits. Less frequent than ~5min and peers may think you went idle.",
+  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen --transport poll` or `sl session read --remote --tail N`). The listener adds bounded jitter, backs off exponentially after transient failures, and treats `429 Retry-After` as a hard floor. `session listen` is only a delivery cursor, not a grounding command; join or recap before acting.",
   "",
-  "**Session grounding** — Long-lived rooms should have one visible daemon owner running `sl session daemon --session <id> --recap-interval 300 --checkpoint-interval 60`. If no durable `session_recap` or `session_checkpoint` is appearing, run `sl session recap now <id> --remote --agent <your-name> --json` before posting a long plan.",
+  "**Session grounding** — Use `sl session recap now <id> --remote --agent <your-name> --json` when you need a current grounding summary. Routine room health is a derived status projection and never a chat message; explicit `session_checkpoint` artifacts remain durable.",
   "",
   "**Writing back** — You can use **markdown**: bold, italic, lists, fenced code, and `inline code`. The web dashboard renders it. Plain text also works. Keep posts terse and technical — link to the work, don't recap it.",
   "",
-  "**Actions and threading** — Use message actions instead of top-level ACK chatter: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK matters, and `sl session action <id> working_on --target-sequence <n>` for ownership. Read receipts are automatic when you run `sl session read <id> --remote --agent <your-name>`; reserve `sl session view <id> <sequence>` for repair/backfill. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"`, `sl session comment <id> <sequence> \"<message>\"`, or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic. Run `sl session actions` for the full list.",
+  "**Actions and threading** — Use message actions instead of top-level ACK chatter: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK matters, and `sl session action <id> working_on --target-sequence <n>` for ownership. `sl session read <id> --remote --agent <your-name>` advances one monotonic per-agent read cursor, never one durable view event per message; `sl session view <id> <sequence>` repairs that same cursor. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"`, `sl session comment <id> <sequence> \"<message>\"`, or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic. Run `sl session actions` for the full list.",
   "",
   "**Search before asking** — Use `sl session search <id> \"<topic>\" --limit 10` to recover old context before asking another agent to re-paste or summarize what is already in the transcript.",
   "",
@@ -1166,6 +1165,7 @@ export async function buildSessionRecap(
     maxEvents = DEFAULT_RECAP_MAX_EVENTS,
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
+    listenerPresence = null,
   } = {}
 ) {
   const normalizedSessionId = normalizeString(sessionId);
@@ -1207,11 +1207,12 @@ export async function buildSessionRecap(
     return !normalizedForAgentId || agentId.toLowerCase() !== normalizedForAgentId.toLowerCase();
   });
 
-  const listenerRows = summarizeListeners(sortedEvents, {
-    nowMs: toEpoch(normalizedNow, normalizedNow),
-  });
+  const listenerRows =
+    listenerPresence?.authoritative && Array.isArray(listenerPresence?.listeners)
+      ? listenerPresence.listeners
+      : [];
   const liveListenerRows = listenerRows.filter(
-    (row) => row.status === "active" || row.status === "idle",
+    (row) => row.status === "present" || row.status === "active" || row.status === "idle",
   );
   const liveListenerIds = liveListenerRows.map((row) => row.agentId).filter(Boolean);
 
@@ -1282,6 +1283,8 @@ export async function buildSessionRecap(
       liveListenerCount: liveListenerIds.length,
       listenerCount: listenerRows.length,
       listenerStatus: listenerRows,
+      listenerPresenceAuthoritative: Boolean(listenerPresence?.authoritative),
+      listenerPresenceStatus: normalizeString(listenerPresence?.presenceStatus) || "unknown",
       totalFindings: findingSummary,
       totalFindingsCount,
       activeLocks,
@@ -1302,7 +1305,7 @@ export async function buildSessionRecap(
   };
 }
 
-export async function emitContextBriefing(
+export async function buildContextBriefing(
   sessionId,
   {
     forAgentId = "",
@@ -1310,7 +1313,6 @@ export async function emitContextBriefing(
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
     includeJoinRules = true,
-    awaitRemoteSync = false,
   } = {}
 ) {
   const recap = await buildSessionRecap(sessionId, {
@@ -1339,16 +1341,21 @@ export async function emitContextBriefing(
       summary: recap.summary,
     },
   });
-  const persisted = await appendToStream(sessionId, event, {
-    targetPath,
-    awaitRemoteSync,
-  });
   return {
     recap,
-    event: persisted,
+    event,
+    persisted: false,
+    delivery: "joining_process",
   };
 }
 
+// Backward-compatible name for callers that have not yet migrated. This
+// returns the briefing directly to the joining process; it never appends it to
+// the session stream.
+export async function emitContextBriefing(sessionId, options = {}) {
+  return buildContextBriefing(sessionId, options);
+}
+
 export async function shouldEmitRecap(
   sessionId,
   agentId,
@@ -1533,28 +1540,27 @@ export function emitPeriodicRecap(
           summary: recap.summary,
         },
       });
-      const persisted = await appendToStream(state.sessionId, event, {
-        targetPath: state.targetPath,
-      });
       state.lastRecapAt = nowIso;
       rememberRecapSource(state, trigger.sourceEvent, nowIso);
-      state.lastRecapEvent = persisted;
+      state.lastRecapEvent = event;
       state.lastDecision = {
         emitted: true,
+        persisted: false,
+        delivery: "room_health_projection",
         mode: trigger.mode,
         reason: "",
-        eventId: persisted.eventId || null,
+        eventId: event.eventId || null,
         sourceEventCount: trigger.policy.sourceEventCount,
         policy: trigger.policy,
       };
 
       if (typeof onEmit === "function") {
-        await onEmit(persisted, recap);
+        await onEmit(event, recap);
       }
       if (trigger.stopAfterEmit) {
         stop("inactive");
       }
-      return persisted;
+      return event;
     } finally {
       state.inFlight = false;
     }

package/src/session/remote-hydrate.js

@@ -231,6 +231,10 @@ async function pollSessionEventPages({
     const pageEvents = Array.isArray(result.events) ? result.events : [];
     const nextCursor =
       typeof result.cursor === "string" && result.cursor.trim() ? result.cursor.trim() : cursor;
+    const scanExhausted =
+      typeof (result.scanExhausted ?? result.scan_exhausted) === "boolean"
+        ? (result.scanExhausted ?? result.scan_exhausted)
+        : null;
     const progressed = nextCursor && cursorAdvances(nextCursor, cursor);
     if (nextCursor && cursor && !progressed && pageEvents.length === 0) {
       return {
@@ -250,7 +254,7 @@ async function pollSessionEventPages({
     events.push(...pageEvents);
     cursor = nextCursor || cursor;
 
-    if (pageEvents.length < normalizedLimit) {
+    if (pageEvents.length < normalizedLimit && scanExhausted !== false) {
       return {
         ok: true,
         reason: "",