elanous 0.2.27 → 0.2.29

package/src/loops/orchestrator/tick.ts

@@ -1,11 +1,11 @@
 import { withFileLockSync } from '../../storage/file-lock.js';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { CardStore, taskCardsDir, type TaskCard } from '../../task-cards/card-store.js';
 import { Database } from 'bun:sqlite';
 import { type ChecklistItem } from '../../release-loop/checklist.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
-import { getUserConfig, type OrchestratorLoopConfig } from '../../user-config.js';
+import { getUserConfig, resolveConfiguredAgentRoleLlm, type OrchestratorLoopConfig } from '../../user-config.js';
 import { rubricPriority } from '../../release-loop/rubric.js';
 import { debug } from '../../debug/log.js';
 import { emitLoopHeartbeat } from '../neighbor-runtime.js';
@@ -15,13 +15,23 @@ import { addHarnessQueue, harnessQueueOutcome, setQueuedPoolHint } from '../../h
 import { placeOnGrid, type GridHost } from './grid-place.js';
 import { checkPodPool, parsePodPool, resolvePodPoolSpec } from '../../task-orchestrator/surfaces/pod-pool.js';
 import { leaseKubectl } from '../../task-orchestrator/surfaces/pod-lease.js';
+import type { TrafficSeatRow } from './traffic.js';
 import { readTaskAgentState, TASK_SEATS, type HandTaskOptions, type TaskCard as TaskAgentCard, type HandTaskResult, type TaskLauncher, type TaskSeat } from '../../task-agent/task-hand.js';
+import { runCoordinatorAgentInbox, runCoordinatorInbox, type CoordinatorInboxResult } from './inbox.js';
+import { loadAgentRolePack, type AgentReplyInput } from '../agent-reply.js';
+import type { LLMProvider } from '../../llm.js';
 
 export type Window = '08' | '12' | '18';
 export type Node = 'intake' | 'split' | 'place' | 'delegate' | 'launch' | 'reconcile' | 'report';
 export type Mode = 'off' | 'shadow' | 'live';
 const SEAT_LOOP_IDS: Readonly<Record<string, string>> = { OP: 'op-seat', MK: 'cmo-seat', TC: 'tc-seat', UX: 'ux-seat' };
 export interface Cell { id: string; title: string; kind?: string; seat?: string; host?: string; gridHost?: boolean; version?: string; cardId: string; origin: 'candidate' | 'flow1a'; priority?: 'P0' | 'P1' | 'P2' | 'P3' | 'P4'; predecessors?: string[] }
+/** Pure launch decision over observed traffic; dispatch-c will wire it into the periodic launch path. */
+export function isLaunchEligible(row: Pick<TrafficSeatRow, 'nextCell' | 'running' | 'launchCap'>,
+  skipReason?: string): boolean {
+  return row.nextCell !== null && row.running < row.launchCap &&
+    skipReason !== 'degraded-skip' && skipReason !== 'cap-deferred';
+}
 export interface TickState {
   runId: string; window: Window; mode: Mode; day: string;
   cards: TaskCard[]; skippedCards: Array<{ id: string; reason: string }>; cells: Cell[]; placed: number; unplaced?: number; delegated: number; wouldDelegate: number; rebalanced?: number; rebalanceBlocked?: Array<{ id: string; reason: string }>;
@@ -31,6 +41,10 @@ export interface TickState {
   /** The highest degradation actually applied in this run — the report keeps it even if the signal recovers before report. */
   degradationPeak?: { level: 1 | 2; reason: string };
   deferredCells?: Cell[];
+  /** A placement adapter rejected at least one cell; this run cannot claim full completion. */
+  placementFailed?: boolean;
+  /** Last confirmed live placement write in this run, carried across node processes. */
+  boardWrittenAt?: string;
   /** place ran at L2 (skipped) in this run — its unplaced cells are carried even if the board is back by delegate. */
   placeDegraded?: boolean;
   delegatedKeys?: string[];
@@ -67,6 +81,11 @@ export interface TickDeps {
   handToTaskAgentCell?: string;
   handTask?: (opts: HandTaskOptions) => Promise<HandTaskResult>;
   taskLauncher?: TaskLauncher;
+  /** Coordinator inbox seam; the real intake reads and replies on the durable message bus. */
+  coordinatorInbox?: () => CoordinatorInboxResult | Promise<CoordinatorInboxResult>;
+  /** Production still uses the restricted turn; tests can supply a deterministic turn. */
+  coordinatorAgentRun?: AgentReplyInput['runAgent'];
+  coordinatorAgentProvider?: LLMProvider;
 }
 
 /** ORCH-TA-HAND ledger — one row per handed `orch:<card>:<cell>` key so a cell is handed once across ticks and processes. */
@@ -329,6 +348,41 @@ function stateFile(root: string, runId: string): string {
   if (!/^[a-zA-Z0-9._-]+$/.test(runId) || runId === '.' || runId === '..') throw new Error('Invalid orchestrator runId');
   return join(root, 'loop', 'orchestrator', `${runId}.json`);
 }
+/** COORD-HA ③ 진행 하트비트 — the last tick that finished its work and the last confirmed placement write. The guardian watches this
+ * (RFC-loop-agent-map §A8b: «마지막 틱 완료 ⊕ 보드 마지막 쓰기 시각»), not process liveness — a held node keeps pulsing
+ * healthy while this record goes stale, which is exactly the stall it exists to expose. */
+export interface CompletionHeartbeat {
+  runId: string;
+  node: Node;
+  window: Window;
+  mode: Mode;
+  /** last confirmed live placement write; null before the first such write */
+  boardWrittenAt: string | null;
+  /** last fully completed run, or null while only board writes have succeeded */
+  tickCompletedAt: string | null;
+}
+/** Its own subdirectory, so the run-state scanners (`restorePrevious` · `previousDelegations` · `syncQueuedPoolHints`) never parse it as a TickState. */
+function completionHeartbeatPath(root: string): string { return join(root, 'loop', 'orchestrator', 'heartbeat', 'completion.json'); }
+/** COORD-HA ③ — last completed run and board write, independently. Undefined means neither has been recorded. */
+export function readCompletionHeartbeat(root: string): CompletionHeartbeat | undefined {
+  const path = completionHeartbeatPath(root);
+  if (!existsSync(path)) return undefined;
+  try {
+    const { runId, node, window, mode, boardWrittenAt, tickCompletedAt } = JSON.parse(readFileSync(path, 'utf8')) as Partial<CompletionHeartbeat>;
+    if (typeof runId !== 'string' || typeof node !== 'string' || typeof window !== 'string' || typeof mode !== 'string'
+      || (boardWrittenAt !== null && (typeof boardWrittenAt !== 'string' || !Number.isFinite(Date.parse(boardWrittenAt))))
+      || (tickCompletedAt !== null && (typeof tickCompletedAt !== 'string' || !Number.isFinite(Date.parse(tickCompletedAt))))) return undefined;
+    return { runId, node: node as Node, window: window as Window, mode: mode as Mode, boardWrittenAt, tickCompletedAt };
+  } catch { return undefined; }
+}
+/** Temp + rename, so a guardian in another process never reads a torn record. */
+function recordCompletionHeartbeat(root: string, completion: CompletionHeartbeat): void {
+  const path = completionHeartbeatPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(completion));
+  renameSync(temp, path);
+}
 function restorePrevious(root: string, day: string, mode: Mode): Pick<TickState, 'cards' | 'cells' | 'launched'> | null {
   const dir = join(root, 'loop', 'orchestrator');
   if (!existsSync(dir)) return null;
@@ -430,6 +484,23 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
     try { (deps.observe ?? ((name, payload) => debug.log('loop.orchestrator', name, payload)))(event, data); }
     catch { /* observation must not change the run */ }
   };
+  // A graph node may be replayed with the same runId, and 12/18 skip intake.
+  // Drain the bus on every tick command; the message transaction prevents duplicate answers.
+  if (mode !== 'off') {
+    const inboxPath = join(root, 'msg', 'messages.db');
+    const inbox = await (deps.coordinatorInbox ?? (() => {
+      const role = resolveConfiguredAgentRoleLlm('coordinator');
+      return role
+        ? runCoordinatorAgentInbox({ role, pack: loadAgentRolePack('coordinator'), path: inboxPath, root,
+            ...(deps.coordinatorAgentRun ? { runAgent: deps.coordinatorAgentRun } : {}),
+            ...(deps.coordinatorAgentProvider ? { provider: deps.coordinatorAgentProvider } : {}) })
+        : runCoordinatorInbox(undefined, 100, inboxPath);
+    }))();
+    if (inbox.replied || inbox.acknowledged) {
+      observe('exchange', 'coordinator-inbox-replied', inbox.replied);
+      observe('exchange', 'coordinator-inbox-acknowledged', inbox.acknowledged);
+    }
+  }
   if (mode !== 'off' && activeNode(node, window) && state.nodes[node] !== 'ok') {
     if (node === 'intake') {
       if (mode === 'live' && deps.cards) { state.cards = wishCards(deps.cards()); state.skippedCards = []; }
@@ -495,11 +566,19 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
             if (validVersion(placed?.version)) {
               cell.version = placed.version;
               state.placed++;
+              // The live placer has returned from its board write. A shadow dry run or null result is not a write.
+              if (mode === 'live') state.boardWrittenAt = currentTime().toISOString();
               observe('exchange', mode === 'shadow' ? `would-place:${cell.id}:${cell.version}` : `placed:${cell.id}:${cell.version}`, 1);
-            } else { state.unplaced = (state.unplaced ?? 0) + 1; observe('exchange', 'unplaced-no-release', 1); }
+            } else {
+              state.unplaced = (state.unplaced ?? 0) + 1;
+              if (mode === 'live') state.placementFailed = true;
+              observe('exchange', 'unplaced-no-release', 1);
+            }
           } catch (error) {
             state.unplaced = (state.unplaced ?? 0) + 1;
+            state.placementFailed = true;
             observe('exchange', `unplaced:${cell.id}:${String(error).slice(0, 160)}`, 1);
+            // Preserve the cell-by-cell recovery contract; the run completion record is withheld at report.
           }
         }
       }
@@ -762,8 +841,20 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
     state.nodes[node] = 'skipped';
   }
   observe('tick', state.nodes[node], state.cells.length);
+  if (mode === 'live' && node === 'place' && state.boardWrittenAt) {
+    // A board write can succeed even when a later cell fails. Advance its clock without claiming run completion.
+    const previous = readCompletionHeartbeat(root);
+    recordCompletionHeartbeat(root, previous
+      ? { ...previous, boardWrittenAt: state.boardWrittenAt }
+      : { runId, node, window, mode, boardWrittenAt: state.boardWrittenAt, tickCompletedAt: null });
+  }
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, JSON.stringify(state));
+  if (mode !== 'off' && node === 'report' && !state.placementFailed && !state.placeDegraded) {
+    // Only the last node can attest that the whole run completed. Carry the most recent confirmed board write.
+    const boardWrittenAt = state.boardWrittenAt ?? readCompletionHeartbeat(root)?.boardWrittenAt ?? null;
+    recordCompletionHeartbeat(root, { runId, node, window, mode, boardWrittenAt, tickCompletedAt: currentTime().toISOString() });
+  }
   return state;
   } catch (error) {
     nodeError = error;

package/src/loops/registry.ts

@@ -14,6 +14,9 @@ import { getUserConfig, type UserConfig } from '../user-config.js';
 import { runGraph, type GraphRunState } from '../graph-runner/runner.js';
 import { FENCE_ROLES } from '../hq/hq.js';
 import { dueBefore, type CheckEntry } from './checker.js';
+import { readUnreadCount } from '../msg/msg-store.js';
+import { loopMessageRoute, SEAT_MESSAGE_ROUTES, type LoopReplyBody, type MessageWake } from './msg-address.js';
+import { resolveWake, type WakeDeps, type WakeResolution } from './msg-wake.js';
 
 export interface LoopRun {
   at: string;
@@ -25,6 +28,12 @@ export interface LoopRun {
 }
 export interface LoopEntry {
   id: string;
+  msgAddress?: string | null;
+  replyBody?: LoopReplyBody;
+  wake?: MessageWake;
+  /** Where `wake` came from — `unresolved` is «모름», not a measured absence. */
+  wakeSource?: WakeResolution['source'];
+  unreadCount?: number | null;
   title: string;
   description: string | null;
   owner?: string | null;
@@ -48,6 +57,20 @@ export interface LoopRegistryOptions {
   scheduleAction?: (action: 'create' | 'enable' | 'disable', args: Record<string, unknown>) => Promise<unknown>;
   /** Home used to expand `~`/`$HOME` in cron redirects; tests inject a temp dir instead of writing the real HOME. */
   home?: string;
+  /** Seat wake resolution (pty manifest ⊕ seat folders); tests inject fixed rows. */
+  wakeDeps?: WakeDeps;
+}
+
+function messageFields(id: string, stateRoot: string): { msgAddress: string | null; replyBody: LoopReplyBody; wake: MessageWake; wakeSource?: WakeResolution['source']; unreadCount: number | null } {
+  const route = loopMessageRoute(id);
+  return { ...route, ...(route.msgAddress ? { wakeSource: 'loop-table' as const } : {}), unreadCount: route.msgAddress ? readUnreadCount(route.msgAddress, join(stateRoot, 'msg', 'messages.db')) : null };
+}
+
+/** A seat row is addressed by its seat; its wake path is resolved on this host (pty name → herdr pane → 모름). */
+function seatMessageFields(seat: string, stateRoot: string, wakeDeps?: WakeDeps): { msgAddress: string; replyBody: LoopReplyBody; wake: MessageWake; wakeSource: WakeResolution['source']; unreadCount: number | null } {
+  const wake = resolveWake(seat, wakeDeps);
+  return { msgAddress: seat, replyBody: 'agent', wake: wake.wake, wakeSource: wake.source,
+    unreadCount: readUnreadCount(seat, join(stateRoot, 'msg', 'messages.db')) };
 }
 
 function graphFiles(dir: string): string[] {
@@ -216,7 +239,7 @@ export function listLoops(opts: LoopRegistryOptions = {}): LoopEntry[] {
     const active = matched.filter(row => !!row.enabled && !!row.cron);
     const next = active.map(row => nextLoopFire(row.cron!, opts.now ?? new Date())).filter((v): v is string => v !== null).sort()[0] ?? null;
     const title = typeof header?.title === 'string' ? header.title : doc.graph_id;
-    const entry: LoopEntry = { id: doc.graph_id, title,
+    const entry: LoopEntry = { id: doc.graph_id, title, ...messageFields(doc.graph_id, stateRoot),
       description: typeof header?.description === 'string' ? header.description : null,
       ...resolveOwner(doc.graph_id, title, config, header?.owner),
       mode: typeof header?.mode === 'string' ? header.mode : null, file: relative(root, file),
@@ -229,6 +252,12 @@ export function listLoops(opts: LoopRegistryOptions = {}): LoopEntry[] {
 }
 
 export interface AllLoopEntry extends CheckEntry {
+  msgAddress?: string | null;
+  replyBody?: LoopReplyBody;
+  wake?: MessageWake;
+  /** Where `wake` came from — `unresolved` is «모름», not a measured absence. */
+  wakeSource?: WakeResolution['source'];
+  unreadCount?: number | null;
   kind: 'graph' | 'seat' | 'cron-shell' | 'orchestrator' | 'unregistered';
   title: string;
   cron?: string;
@@ -589,6 +618,7 @@ export function listAllLoops(opts: LoopRegistryOptions = {}): AllLoopEntry[] {
     const declaredHost = typeof header.host === 'string' && header.host ? header.host : undefined;
     const declaredCategory = typeof header.observationCategory === 'string' && header.observationCategory ? header.observationCategory : undefined;
     return { kind: 'graph', id: loop.id, title: loop.title, owner: loop.owner ?? undefined, ownerSource: loop.ownerSource,
+      msgAddress: loop.msgAddress, replyBody: loop.replyBody, wake: loop.wake, ...(loop.wakeSource ? { wakeSource: loop.wakeSource } : {}), unreadCount: loop.unreadCount,
       ...(declaredHost || installed.length ? { host: declaredHost ?? hostname() } : {}),
       observationCategory: declaredCategory ?? 'graph.runner',
       ...(fenceRole ? { fenceRole } : {}),
@@ -599,6 +629,7 @@ export function listAllLoops(opts: LoopRegistryOptions = {}): AllLoopEntry[] {
       recentStatuses: runs.map(run => run.status) };
   });
   const namedIds = namedCronIds(rows, claimed);
+  const seatOf = new Map<AllLoopEntry, string>();
   for (const row of rows) {
     if (claimed.has(row.id)) continue;
     const command = row.command ?? '';
@@ -622,7 +653,7 @@ export function listAllLoops(opts: LoopRegistryOptions = {}): AllLoopEntry[] {
     const picked = logMtime && (!recorded || Date.parse(logMtime) >= Date.parse(recorded)) ? 'log-mtime'
       : recorded ? 'registry' : 'none';
     debug.log('loops.registry', 'cron-last-run', { id, targets, picked });
-    all.push({ kind, id, title,
+    const pushed: AllLoopEntry = { kind, id, title,
       ...resolveOwner(id, title, config, undefined, seatArg ?? seat, seatArg ? 'seat-arg' : 'seat'), ...(fenceRole ? { fenceRole } : {}),
       host: hostname(), observationCategory: row.category,
       enabled: !!row.enabled, registered: true,
@@ -632,7 +663,11 @@ export function listAllLoops(opts: LoopRegistryOptions = {}): AllLoopEntry[] {
       ...(picked === 'log-mtime' ? { lastRunAt: logMtime, evidence: picked }
         : picked === 'registry' ? { lastRunAt: recorded, evidence: picked } : {}),
       ...(row.last_status ? { lastStatus: row.last_status } : {}),
-      recentStatuses: row.last_status ? [row.last_status] : [] });
+      recentStatuses: row.last_status ? [row.last_status] : [] };
+    all.push(pushed);
+    const seatName = (seatArg ?? seat)?.toUpperCase();
+    // 선언된 자리 줄만 자리 주소로 공개한다 — 모르는 `--seat FOO` 는 종전처럼 주소 없음.
+    if (kind === 'seat' && seatName && Object.hasOwn(SEAT_MESSAGE_ROUTES, seatName)) seatOf.set(pushed, seatName);
   }
   const warnings = unregisteredCronLoops(all, graphOpts);
   for (const row of warnings) {
@@ -647,7 +682,10 @@ export function listAllLoops(opts: LoopRegistryOptions = {}): AllLoopEntry[] {
   for (const loop of all) bySource[loop.ownerSource!]++;
   debug.log('loop.check', 'ownership', { total: all.length, bySource });
   debug.log('loops.registry', 'list-all', { count: all.length });
-  return all;
+  const stateRoot = opts.stateRoot ?? effectiveInstanceRoot();
+  return all.map(entry => entry.kind === 'graph' ? entry
+    : seatOf.has(entry) ? { ...entry, ...seatMessageFields(seatOf.get(entry)!, stateRoot, opts.wakeDeps) }
+      : { ...entry, ...messageFields(entry.id, stateRoot) });
 }
 
 /** An unclaimed cron line with any elanous marker must surface as an unregistered warning. */

package/src/maturity/feature-maturity.ts

@@ -62,7 +62,7 @@ export const FEATURE_MATURITY = {
     preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta',
     where: 'stable', bench: 'beta', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', know: 'beta', freeze: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', resource: 'beta', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',

package/src/memory.ts

@@ -444,7 +444,12 @@ const INDEX_MAX_LINES = 200;
  */
 export function rebuildIndex(root: string = memoryRoot()): void {
   ensureRoot(root);
-  const entries = listMemories({}, root);
+  writeFileDurable(memoryIndexPath(root), renderMemoryIndex(listMemories({}, root)));
+}
+
+/** The MEMORY.md text for a set of entries — rebuildIndex writes it for the whole store,
+ *  a scoped injection renders it for the entries its filter keeps. */
+export function renderMemoryIndex(entries: readonly MemoryEntry[]): string {
   const byType: Record<MemoryType, MemoryEntry[]> = {
     user: [], feedback: [], project: [], reference: [],
   };
@@ -468,7 +473,7 @@ export function rebuildIndex(root: string = memoryRoot()): void {
     }
     lines.push('');
   }
-  writeFileDurable(memoryIndexPath(root), lines.join('\n'));
+  return lines.join('\n');
 }
 
 /** Read the MEMORY.md index verbatim. Returns '' when missing (e.g.
@@ -512,6 +517,11 @@ export interface InjectOpts {
   minScore?: number;
   /** Always include the MEMORY.md index even if no keyword hits. */
   alwaysIncludeIndex?: boolean;
+  /** Scope filter. When set, only kept entries are injected and the index is rendered from
+   *  them instead of read from MEMORY.md (which lists every entry, other seats' cards included). */
+  filter?: (entry: MemoryEntry) => boolean;
+  /** Inject these bodies like pinned ones (e.g. the current seat's context cards). */
+  alwaysInject?: (entry: MemoryEntry) => boolean;
 }
 
 /** Build the memory-injection block for a user turn. Always prepends
@@ -531,7 +541,9 @@ export function buildMemoryInjection(
   const minScore = opts.minScore ?? 2;
   const alwaysIdx = opts.alwaysIncludeIndex !== false;
 
-  const index = readIndex(root);
+  const filter = opts.filter;
+  const scoped = filter ? listMemories({}, root).filter(m => m.contextCard?.status !== 'retired' && filter(m)) : null;
+  const index = scoped ? (scoped.length > 0 ? renderMemoryIndex(scoped) : '') : readIndex(root);
   if (!index) return { block: '', tokens: 0, injectedIds: [] };
 
   const parts: string[] = [];
@@ -548,7 +560,10 @@ export function buildMemoryInjection(
 
   // 📌 pinned 기억 — 키워드 무관 항상 주입(relevance gate bypass · Letta pinned block /
   //    claude-code MEMORY.md tier 동형). priority 높은 순. core/safety/ref-location 사실용.
-  const pinnedMems = listMemories({}, root).filter(m => m.pinned && m.contextCard?.status !== 'retired').sort((a, b) => b.priority - a.priority);
+  const alwaysInject = opts.alwaysInject;
+  const pinnedMems = (scoped ?? listMemories({}, root))
+    .filter(m => (m.pinned || alwaysInject?.(m) === true) && m.contextCard?.status !== 'retired')
+    .sort((a, b) => b.priority - a.priority);
   const pinnedParts: string[] = [];
   for (const e of pinnedMems) {
     const chunk = pinnedChunk(e);
@@ -566,7 +581,7 @@ export function buildMemoryInjection(
   const hits = lowContext
     ? []
     : searchMemories(userText, { limit: maxHits + pinnedParts.length }, root)
-        .filter(h => h.score >= minScore && !injected.includes(h.entry.id))
+        .filter(h => h.score >= minScore && !injected.includes(h.entry.id) && (!filter || filter(h.entry)))
         .slice(0, maxHits);
   const bodyParts: string[] = [];
   for (const hit of hits) {

package/src/msg/msg-sse-server.ts

@@ -0,0 +1,141 @@
+import { timingSafeEqual } from 'node:crypto';
+import { canonicalSeatId, type Message, type MsgStore } from './msg-store.js';
+
+type Subscriber = { to: string; lastId: number; heartbeatAt: number; replaying: boolean; controller: ReadableStreamDefaultController<Uint8Array> };
+const encoder = new TextEncoder();
+
+function cursor(raw: string | null): number {
+  if (raw === null) return 0;
+  if (!/^(0|[1-9]\d*)$/.test(raw)) throw new Error('invalid message cursor');
+  const id = Number(raw);
+  if (!Number.isSafeInteger(id)) throw new Error('invalid message cursor');
+  return id;
+}
+
+function authorized(request: Request, token: string): boolean {
+  const value = request.headers.get('authorization');
+  if (!value?.startsWith('Bearer ')) return false;
+  const received = Buffer.from(value.slice(7));
+  const expected = Buffer.from(token);
+  return expected.length > 0 && received.length === expected.length && timingSafeEqual(received, expected);
+}
+
+function addressed(message: Message, to: string): boolean {
+  return message.to === to || (message.to === 'ALL' && message.from !== to);
+}
+
+/** The SQLite ledger remains authoritative; this independent process only accelerates delivery. */
+export function startMsgSseServer(input: {
+  store: MsgStore;
+  token: string;
+  port: number;
+  hostname?: string;
+  pollMs?: number;
+}): { port: number; stats: () => { subscribers: number; maxQueuedEvents: number }; stop: () => void } {
+  if (!input.token) throw new Error('message SSE token is required');
+  if (!Number.isSafeInteger(input.port) || input.port < 0 || input.port > 65535) throw new Error('invalid SSE port');
+  const hostname = input.hostname ?? '127.0.0.1';
+  if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(hostname)) throw new Error('message SSE must bind to loopback');
+  const pollMs = input.pollMs ?? 250;
+  if (!Number.isSafeInteger(pollMs) || pollMs < 1 || pollMs > 500) throw new Error('SSE ledger poll must be 1–500ms');
+  const subscribers = new Set<Subscriber>();
+  let maxQueuedEvents = 0;
+  let scanned = input.store.latestId();
+  const send = (subscriber: Subscriber, message: Message) => {
+    if (message.id <= subscriber.lastId || !addressed(message, subscriber.to)) return;
+    if ((subscriber.controller.desiredSize ?? 0) < -256) throw new Error('slow SSE subscriber; reconnect for ledger replay');
+    subscriber.controller.enqueue(encoder.encode(`id: ${message.id}\ndata: ${JSON.stringify(message)}\n\n`));
+    maxQueuedEvents = Math.max(maxQueuedEvents, Math.max(0, 1 - (subscriber.controller.desiredSize ?? 0)));
+    subscriber.lastId = message.id;
+  };
+  const replay = (subscriber: Subscriber) => {
+    if (!subscriber.replaying) return;
+    try {
+      while ((subscriber.controller.desiredSize ?? 0) > 0) {
+        const batch = input.store.listByRecipient(subscriber.to, subscriber.lastId, 1000);
+        if (!batch.length) { subscriber.replaying = false; break; }
+        for (const message of batch) {
+          if ((subscriber.controller.desiredSize ?? 0) <= 0) break;
+          send(subscriber, message);
+        }
+      }
+    } catch (error) {
+      subscribers.delete(subscriber);
+      subscriber.controller.error(error);
+    }
+  };
+  const tick = () => {
+    try {
+      let batch: Message[];
+      let scans = 0;
+      do {
+        batch = input.store.listAfter(scanned);
+        for (const message of batch) {
+          scanned = message.id;
+          for (const subscriber of subscribers) {
+            if (subscriber.replaying) continue;
+            try { send(subscriber, message); } catch (error) {
+              subscribers.delete(subscriber);
+              try { subscriber.controller.error(error); } catch { /* already disconnected */ }
+            }
+          }
+        }
+        scans++;
+      } while (batch.length === 1000 && scans < 4);
+      const now = Date.now();
+      for (const subscriber of subscribers) {
+        if (subscriber.replaying || (subscriber.controller.desiredSize ?? 0) <= 0) continue;
+        if (now - subscriber.heartbeatAt < 1000) continue;
+        try {
+          subscriber.controller.enqueue(encoder.encode(': keepalive\n\n'));
+          subscriber.heartbeatAt = now;
+        } catch { subscribers.delete(subscriber); }
+      }
+    } catch (error) {
+      // The next tick retries from the last scanned ID; the durable ledger is unchanged.
+      console.error(`msg SSE scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const server = Bun.serve({
+    port: input.port,
+    hostname,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname !== '/stream' || request.method !== 'GET') return new Response('Not Found', { status: 404 });
+      if (!authorized(request, input.token)) return new Response('Unauthorized', { status: 401 });
+      let to: string;
+      let after: number;
+      try {
+        to = canonicalSeatId(url.searchParams.get('to') ?? '');
+        if (to === 'ALL') throw new Error('ALL is not a recipient');
+        after = Math.max(cursor(url.searchParams.get('since')), cursor(request.headers.get('last-event-id')));
+      } catch (error) { return new Response(error instanceof Error ? error.message : String(error), { status: 400 }); }
+      let subscriber: Subscriber;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          subscriber = { to, lastId: after, heartbeatAt: Date.now(), replaying: true, controller };
+          subscribers.add(subscriber);
+          controller.enqueue(encoder.encode(': connected\n\n'));
+        },
+        pull() { replay(subscriber); },
+        cancel() { subscribers.delete(subscriber); },
+      });
+      request.signal.addEventListener('abort', () => subscribers.delete(subscriber), { once: true });
+      return new Response(stream, { headers: {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+      } });
+    },
+  });
+  const timer = setInterval(tick, pollMs);
+  timer.unref();
+  return { port: server.port ?? input.port,
+    stats: () => ({ subscribers: subscribers.size, maxQueuedEvents }),
+    stop: () => {
+    clearInterval(timer);
+    for (const subscriber of subscribers) { try { subscriber.controller.close(); } catch { /* disconnected */ } }
+    subscribers.clear();
+    server.stop(true);
+  } };
+}