elanous 0.2.27 → 0.2.28

package/src/loops/orchestrator/resync-shadow.ts

@@ -5,6 +5,9 @@ import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { debug } from '../../debug/log.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { PR_LABEL_NAMES } from '../../github/pr-labels.js';
+import { listRunLedgers } from '../../self-implement/run-ledger.js';
+import { queryRunningRuns } from '../../self-implement/running-runs.js';
 import {
   defaultGitMergeSeam, defaultLlmResolve, mergeMainWithLlmResolve,
   type LlmMergeOutcome, type MergeGitSeam,
@@ -16,6 +19,8 @@ interface ResyncShadowEntry {
   at: string;
   pr: number;
   head: string;
+  beforeHead?: string;
+  afterHead?: string;
   mode: ResyncShadowMode;
   pushed: boolean;
   labelRemoved: boolean;
@@ -27,7 +32,7 @@ interface ResyncShadowEntry {
 }
 export interface ResyncShadowSummary { candidates: number; tried: number; saved: number; savedRatio: number | null }
 
-type OpenPr = { number: number; headRefName: string; mergeable: string; isDraft: boolean; labels: { name: string }[] };
+type OpenPr = { number: number; headRefName: string; headRefOid?: string; mergeable: string; isDraft: boolean; labels: { name: string }[] };
 export interface ResyncShadowDeps {
   repoRoot?: string;
   instanceRoot?: string;
@@ -37,6 +42,63 @@ export interface ResyncShadowDeps {
   gitSeam?: MergeGitSeam;
   runTests?: (cwd: string, files: string[]) => { ok: boolean; failedTests?: string[]; noTests?: boolean };
   now?: () => Date;
+  /** Run ownership is checked before touching a branch; null means the observation failed. */
+  activePrNumbers?: (candidatePrs: readonly number[]) => ReadonlySet<number> | null;
+}
+
+function activePrNumbers(candidatePrs: readonly OpenPr[], repoRoot: string, instanceRoot: string): ReadonlySet<number> | null {
+  const owners = new Map<number, { runId: string; branch: string; headCommit: string; terminal: boolean }[]>();
+  const branchRuns = new Map<string, Set<string>>();
+  const incompleteOwnerPrs = new Set<number>();
+  const candidateSet = new Set(candidatePrs.map(pr => pr.number));
+  try {
+    for (const match of listRunLedgers().matches) {
+      const latestStatus = match.entries.filter(entry => entry.event === 'run-status').at(-1)?.data.runStatus;
+      const terminal = latestStatus === 'completed' || latestStatus === 'failed' || latestStatus === 'cancelled';
+      for (const entry of match.entries) {
+        // A competing run can own the branch even when its PR number or worktree event is missing.
+        if ((entry.event === 'worktree' || entry.event === 'pr-opened') && typeof entry.data.branch === 'string') {
+          const ids = branchRuns.get(entry.data.branch) ?? new Set<string>();
+          ids.add(match.runId);
+          branchRuns.set(entry.data.branch, ids);
+        }
+        const number = entry.event === 'pr-opened' ? entry.data.number : undefined;
+        if (typeof number !== 'number' || !candidateSet.has(number)) continue;
+        const matches = owners.get(number) ?? [];
+        if (typeof entry.data.branch !== 'string' || typeof entry.data.headCommit !== 'string')
+          incompleteOwnerPrs.add(number);
+        else matches.push({ runId: match.runId, branch: entry.data.branch, headCommit: entry.data.headCommit, terminal });
+        owners.set(number, matches);
+      }
+    }
+    const runIds = [...new Set([...owners.values()].flatMap(rows => rows.map(row => row.runId)))];
+    if (runIds.length === 0) return new Set(candidatePrs.map(pr => pr.number));
+    const observed = queryRunningRuns({ runIds, caller: 'smart-merge.resync' });
+    if (observed.completeness !== 'complete') return null;
+    const active = new Set(observed.entries.filter(row => row.status === 'running' || row.status === 'probable-running'
+      || row.status === 'unknown' || row.status === 'ended-unclosed').map(row => row.runId));
+    const priorPath = join(instanceRoot, 'orchestrator', 'resync-shadow.jsonl');
+    const prior = existsSync(priorPath) ? readFileSync(priorPath, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line) as ResyncShadowEntry) : [];
+    const excluded = new Set<number>();
+    for (const pr of candidatePrs) {
+      const matches = owners.get(pr.number) ?? [];
+      if (incompleteOwnerPrs.has(pr.number) || matches.length !== 1 || !/^[a-f0-9]{40}$/i.test(pr.headRefOid ?? '')) { excluded.add(pr.number); continue; }
+      const owner = matches[0]!;
+      if (owner.branch !== pr.headRefName || !owner.terminal || !/^[a-f0-9]{40}$/i.test(owner.headCommit)
+        || active.has(owner.runId) || [...(branchRuns.get(pr.headRefName) ?? [])].some(id => id !== owner.runId)) {
+        excluded.add(pr.number); continue;
+      }
+      const remote = command('git', ['ls-remote', 'origin', `refs/heads/${pr.headRefName}`], repoRoot).trim().split(/\s/)[0];
+      if (remote !== pr.headRefOid) { excluded.add(pr.number); continue; }
+      let proven = owner.headCommit;
+      for (const row of prior.filter(row => row.pr === pr.number && row.head === pr.headRefName && row.pushed)) {
+        if (row.beforeHead !== proven || !/^[a-f0-9]{40}$/i.test(row.afterHead ?? '')) { proven = ''; break; }
+        proven = row.afterHead!;
+      }
+      if (proven !== remote) excluded.add(pr.number);
+    }
+    return excluded;
+  } catch { return null; }
 }
 
 function command(file: string, args: string[], cwd: string, timeout = 60_000): string {
@@ -51,6 +113,15 @@ function changedTests(gh: (args: string[]) => string, number: number): string[]
     path.endsWith('.test.ts') && !isAbsolute(path) && path !== '' && !path.split('/').some(part => part === '..' || part === '.' || part === '')))];
 }
 
+function listOpenPrs(gh: (args: string[]) => string): OpenPr[] {
+  const observed: unknown = JSON.parse(gh(['pr', 'list', '--state', 'open', '--json', 'number,headRefName,headRefOid,mergeable,isDraft,labels', '--limit', '1000']));
+  if (!Array.isArray(observed) || observed.length >= 1000 || observed.some(pr => !pr || !Number.isSafeInteger(pr.number)
+    || typeof pr.headRefName !== 'string' || typeof pr.mergeable !== 'string' || typeof pr.isDraft !== 'boolean'
+    || !Array.isArray(pr.labels) || pr.labels.some((label: unknown) => !label || typeof label !== 'object' || typeof (label as { name?: unknown }).name !== 'string')))
+    throw new Error('incomplete or invalid PR observation');
+  return observed as OpenPr[];
+}
+
 // A PR test must not inherit credentials, reach the network or write outside its own worktree.
 // If the kernel does not provide the required isolation, fail closed before starting bun.
 const TEST_SANDBOX = `import ctypes, os, sys
@@ -145,16 +216,16 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
   if (mode !== 'shadow' && mode !== 'live') throw new Error('mode must be shadow or live');
   const repoRoot = deps.repoRoot ?? resolve(import.meta.dir, '../../..');
   const gh = deps.runGh ?? ((args: string[]) => command('gh', args, repoRoot));
-  const observed: unknown = JSON.parse(gh(['pr', 'list', '--state', 'open', '--json', 'number,headRefName,mergeable,isDraft,labels', '--limit', '1000']));
-  if (!Array.isArray(observed) || observed.length >= 1000 || observed.some(pr => !pr || !Number.isSafeInteger(pr.number)
-    || typeof pr.headRefName !== 'string' || typeof pr.mergeable !== 'string' || typeof pr.isDraft !== 'boolean'
-    || !Array.isArray(pr.labels) || pr.labels.some((label: unknown) => !label || typeof label !== 'object' || typeof (label as { name?: unknown }).name !== 'string')))
-    throw new Error('incomplete or invalid PR observation');
-  const candidates = (observed as OpenPr[]).filter(pr => pr.headRefName.startsWith('self-impl/')
-    && pr.mergeable === 'CONFLICTING'
-    && (mode === 'shadow' || pr.labels.some(label => label.name === 'elanous:needs-rebase'))
-    && !pr.labels.some(label => label.name === 'elanous:stalled' || label.name === 'elanous:superseded'))
-    .sort((a, b) => a.number - b.number).slice(0, max);
+  const eligible = listOpenPrs(gh).filter(pr => pr.headRefName.startsWith('self-impl/')
+    && (mode === 'shadow' ? pr.mergeable === 'CONFLICTING' : pr.mergeable === 'MERGEABLE')
+    && (mode === 'shadow' || pr.labels.some(label => label.name === PR_LABEL_NAMES.needsRebase))
+    && !pr.labels.some(label => label.name === PR_LABEL_NAMES.running)
+    && !pr.labels.some(label => label.name === PR_LABEL_NAMES.stalled || label.name === PR_LABEL_NAMES.superseded));
+  const observeActive = deps.activePrNumbers ?? ((numbers: readonly number[]) => activePrNumbers(
+    eligible.filter(pr => numbers.includes(pr.number)), repoRoot, deps.instanceRoot ?? effectiveInstanceRoot()));
+  const active = mode === 'live' && eligible.length ? observeActive(eligible.map(pr => pr.number)) : new Set<number>();
+  if (active === null) throw new Error('active run observation unavailable — resync stays read-only');
+  const candidates = eligible.filter(pr => !active.has(pr.number)).sort((a, b) => a.number - b.number).slice(0, max);
   const ledger = join(deps.instanceRoot ?? effectiveInstanceRoot(), 'orchestrator', 'resync-shadow.jsonl');
   let saved = 0;
   let tried = 0;
@@ -169,6 +240,9 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
       // Explicit destination refspecs make origin/<head> and origin/main fresh even without remote.origin.fetch.
       command('git', ['fetch', 'origin', `+refs/heads/${pr.headRefName}:refs/remotes/origin/${pr.headRefName}`,
         '+refs/heads/main:refs/remotes/origin/main'], repoRoot);
+      entry.beforeHead = command('git', ['rev-parse', `origin/${pr.headRefName}`], repoRoot).trim();
+      if (mode === 'live' && !deps.activePrNumbers && entry.beforeHead !== pr.headRefOid)
+        throw new Error('PR head changed after owner proof — resync stays read-only');
       entry.testFiles = changedTests(gh, pr.number);
       tmp = realpathSync(mkdtempSync(join(tmpdir(), 'resync-shadow-')));
       command('git', ['worktree', 'add', '--detach', tmp, `origin/${pr.headRefName}`], repoRoot);
@@ -189,10 +263,24 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
       } else entry.verdict = outcome.status === 'conflict-unresolved' || outcome.status === 'up-to-date' ? 'unresolved' : 'error';
       if (mode === 'live' && entry.verdict === 'saved') {
         try {
+          const lateActive = observeActive([pr.number]);
+          if (lateActive === null || lateActive.has(pr.number))
+            throw new Error('PR ownership changed before push — resync stays read-only');
+          const current = listOpenPrs(gh).filter(row => row.number === pr.number);
+          if (current.length !== 1 || current[0]!.headRefName !== pr.headRefName
+            || current[0]!.headRefOid !== pr.headRefOid || current[0]!.mergeable !== 'MERGEABLE'
+            || !current[0]!.labels.some(label => label.name === PR_LABEL_NAMES.needsRebase)
+            || current[0]!.labels.some(label => label.name === PR_LABEL_NAMES.running
+              || label.name === PR_LABEL_NAMES.stalled || label.name === PR_LABEL_NAMES.superseded))
+            throw new Error('PR state changed before push — resync stays read-only');
+          const immediateHead = command('git', ['ls-remote', 'origin', `refs/heads/${pr.headRefName}`], repoRoot).trim().split(/\s/)[0];
+          if (immediateHead !== entry.beforeHead)
+            throw new Error('remote head changed before push — resync stays read-only');
           (deps.runGit ?? (args => { command('git', args, tmp!); }))(
             ['push', 'origin', `HEAD:refs/heads/${pr.headRefName}`]);
           entry.pushed = true;
-          gh(['pr', 'edit', String(pr.number), '--remove-label', 'elanous:needs-rebase']);
+          entry.afterHead = command('git', ['rev-parse', 'HEAD'], tmp).trim();
+          gh(['pr', 'edit', String(pr.number), '--remove-label', PR_LABEL_NAMES.needsRebase]);
           entry.labelRemoved = true;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);

package/src/loops/orchestrator/tick.ts

@@ -1,5 +1,5 @@
 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';
@@ -16,6 +16,7 @@ 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 { readTaskAgentState, TASK_SEATS, type HandTaskOptions, type TaskCard as TaskAgentCard, type HandTaskResult, type TaskLauncher, type TaskSeat } from '../../task-agent/task-hand.js';
+import { runCoordinatorInbox } from './inbox.js';
 
 export type Window = '08' | '12' | '18';
 export type Node = 'intake' | 'split' | 'place' | 'delegate' | 'launch' | 'reconcile' | 'report';
@@ -31,6 +32,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 +72,8 @@ 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?: () => { replied: number; acknowledged: number };
 }
 
 /** ORCH-TA-HAND ledger — one row per handed `orch:<card>:<cell>` key so a cell is handed once across ticks and processes. */
@@ -329,6 +336,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 +472,15 @@ 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 inbox = (deps.coordinatorInbox ?? (() => runCoordinatorInbox(undefined, 100, join(root, 'msg', 'messages.db'))))();
+    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 +546,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 +821,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/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/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);
+  } };
+}

package/src/msg/msg-store.ts

@@ -8,6 +8,7 @@ export interface MessageEnvelope {
   to: string;
   body: string;
   kind?: string;
+  replyTo?: number;
 }
 
 export interface Message extends MessageEnvelope {
@@ -46,8 +47,16 @@ export function validateMessageEnvelope(input: unknown): MessageEnvelope {
   if (record.kind !== undefined && (typeof record.kind !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(record.kind))) {
     throw new Error('invalid message kind');
   }
-  if (Object.keys(record).some(key => !['from', 'to', 'body', 'kind'].includes(key))) throw new Error('unknown message field');
-  return record.kind === undefined ? { from, to, body: record.body } : { from, to, body: record.body, kind: record.kind as string };
+  const replyTo = record.replyTo;
+  if (replyTo !== undefined && (typeof replyTo !== 'number' || !Number.isSafeInteger(replyTo) || replyTo < 1)) {
+    throw new Error('replyTo must be a positive integer message ID');
+  }
+  if (Object.keys(record).some(key => !['from', 'to', 'body', 'kind', 'replyTo'].includes(key))) throw new Error('unknown message field');
+  return {
+    from, to, body: record.body,
+    ...(record.kind === undefined ? {} : { kind: record.kind as string }),
+    ...(replyTo === undefined ? {} : { replyTo }),
+  };
 }
 
 function validCursor(cursor: number): number {
@@ -68,28 +77,45 @@ interface MessageRow {
   recipient: string;
   body: string;
   kind: string | null;
+  reply_to: number | null;
   created_at: string;
 }
 
 function fromRow(row: MessageRow): Message {
   return { id: row.id, from: row.sender, to: row.recipient, body: row.body,
-    ...(row.kind === null ? {} : { kind: row.kind }), createdAt: row.created_at };
+    ...(row.kind === null ? {} : { kind: row.kind }),
+    ...(row.reply_to == null ? {} : { replyTo: row.reply_to }),
+    createdAt: row.created_at };
 }
 
 /** SQLite owns both append order and per-recipient acknowledgement progress. */
 export class MsgStore {
   readonly db: Database;
 
-  constructor(path: string = defaultMsgStorePath()) {
-    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    this.db = new Database(path);
+  // A read-only SSE connection may outlive another process's in-place migration.
+  private get hasReplyTo(): boolean {
+    return (this.db.query(`SELECT COUNT(*) AS count FROM pragma_table_info('msg_messages') WHERE name = 'reply_to'`)
+      .get() as { count: number }).count > 0;
+  }
+
+  private readWithSchema<T>(read: (hasReplyTo: boolean) => T): T {
+    // The schema projection and rows must share one SQLite snapshot. Otherwise a writer can
+    // migrate between them and a reader could advance past a reply with its link erased.
+    return this.db.transaction(() => read(this.hasReplyTo)).deferred();
+  }
+
+  constructor(path: string = defaultMsgStorePath(), options: { readOnly?: boolean } = {}) {
+    if (options.readOnly && (path === ':memory:' || !existsSync(path))) throw new Error('message ledger unavailable for read-only SSE service');
+    if (!options.readOnly && path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    this.db = options.readOnly ? new Database(path, { readonly: true }) : new Database(path);
     this.db.exec('PRAGMA busy_timeout = 5000');
-    this.db.exec(`CREATE TABLE IF NOT EXISTS msg_messages (
+    if (!options.readOnly) this.db.exec(`CREATE TABLE IF NOT EXISTS msg_messages (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       sender TEXT NOT NULL,
       recipient TEXT NOT NULL,
       body TEXT NOT NULL,
       kind TEXT,
+      reply_to INTEGER,
       created_at TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_msg_messages_recipient_id ON msg_messages(recipient, id);
@@ -101,21 +127,28 @@ export class MsgStore {
       provenance_key TEXT PRIMARY KEY,
       message_id INTEGER NOT NULL REFERENCES msg_messages(id)
     );`);
+    // Serialize the schema check and ALTER across processes opening an old ledger at once.
+    if (!options.readOnly) this.db.transaction(() => {
+      const replyToColumn = (this.db.query(`SELECT COUNT(*) AS count FROM pragma_table_info('msg_messages') WHERE name = 'reply_to'`)
+        .get() as { count: number }).count;
+      if (replyToColumn === 0) this.db.exec('ALTER TABLE msg_messages ADD COLUMN reply_to INTEGER');
+      this.db.exec('CREATE INDEX IF NOT EXISTS idx_msg_messages_reply_to ON msg_messages(reply_to, id)');
+    }).immediate();
   }
 
   append(input: MessageEnvelope): Message {
     return this.insertMessage(input);
   }
 
-  /** Append once for a provenance key such as coord:<commentId>:<recipient>. */
+  /** Append once for a coordination comment or a task failure incident. */
   appendWithProvenance(input: MessageEnvelope, provenanceKey: string): Message {
-    if (typeof provenanceKey !== 'string' || !/^coord:[^:]+:[^:]+$/.test(provenanceKey)) {
+    if (typeof provenanceKey !== 'string' || !/^(?:coord|ta-failure):[^:]+:[^:]+$/.test(provenanceKey)) {
       throw new Error('invalid message provenance key');
     }
     const msg = validateMessageEnvelope(input);
     if (provenanceKey.split(':')[2] !== msg.to) throw new Error('provenance recipient does not match message recipient');
     return this.db.transaction(() => {
-      const existing = this.db.query(`SELECT m.id, m.sender, m.recipient, m.body, m.kind, m.created_at
+      const existing = this.db.query(`SELECT m.id, m.sender, m.recipient, m.body, m.kind, m.reply_to, m.created_at
         FROM msg_provenance p JOIN msg_messages m ON m.id = p.message_id WHERE p.provenance_key = ?`)
         .get(provenanceKey) as MessageRow | null;
       if (existing) return fromRow(existing);
@@ -128,9 +161,12 @@ export class MsgStore {
 
   private insertMessage(input: MessageEnvelope): Message {
     const msg = validateMessageEnvelope(input);
+    if (msg.replyTo !== undefined && this.db.query('SELECT 1 FROM msg_messages WHERE id = ?').get(msg.replyTo) === null) {
+      throw new Error(`reply target not found: #${msg.replyTo}`);
+    }
     const createdAt = new Date().toISOString();
-    const result = this.db.query(`INSERT INTO msg_messages(sender, recipient, body, kind, created_at)
-      VALUES (?, ?, ?, ?, ?)`).run(msg.from, msg.to, msg.body, msg.kind ?? null, createdAt);
+    const result = this.db.query(`INSERT INTO msg_messages(sender, recipient, body, kind, reply_to, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)`).run(msg.from, msg.to, msg.body, msg.kind ?? null, msg.replyTo ?? null, createdAt);
     return { id: Number(result.lastInsertRowid), ...msg, createdAt };
   }
 
@@ -142,15 +178,48 @@ export class MsgStore {
     if (to === 'ALL') throw new Error('ALL is a topic, not a recipient');
     validCursor(after);
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error('limit must be between 1 and 1000');
-    return (this.db.query(`SELECT id, sender, recipient, body, kind, created_at FROM msg_messages
+    return this.readWithSchema(hasReplyTo => (this.db.query(`SELECT id, sender, recipient, body, kind, ${hasReplyTo ? 'reply_to' : 'NULL AS reply_to'}, created_at FROM msg_messages
       WHERE id > ? AND (recipient = ? OR (recipient = 'ALL' AND sender <> ?))
-      ORDER BY id ASC LIMIT ?`).all(after, to, to, limit) as MessageRow[]).map(fromRow);
+      ORDER BY id ASC LIMIT ?`).all(after, to, to, limit) as MessageRow[]).map(fromRow));
+  }
+
+  /** One message by durable ID, or null when absent. */
+  getMessage(messageId: number): Message | null {
+    if (!Number.isSafeInteger(messageId) || messageId < 1) throw new Error('message ID must be a positive integer');
+    return this.readWithSchema(hasReplyTo => {
+      const row = this.db.query(`SELECT id, sender, recipient, body, kind, ${hasReplyTo ? 'reply_to' : 'NULL AS reply_to'}, created_at FROM msg_messages
+        WHERE id = ?`).get(messageId) as MessageRow | null;
+      return row === null ? null : fromRow(row);
+    });
+  }
+
+  /** Replies pointing at the supplied message, ordered by durable insertion ID. */
+  listReplies(messageId: number, limit: number = 100, afterId: number = 0): Message[] {
+    if (!Number.isSafeInteger(messageId) || messageId < 1) throw new Error('message ID must be a positive integer');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error('limit must be between 1 and 1000');
+    validCursor(afterId);
+    return this.readWithSchema(hasReplyTo => hasReplyTo
+      ? (this.db.query(`SELECT id, sender, recipient, body, kind, reply_to, created_at FROM msg_messages
+        WHERE reply_to = ? AND id > ? ORDER BY id ASC LIMIT ?`).all(messageId, afterId, limit) as MessageRow[]).map(fromRow)
+      : []);
   }
 
   list(recipient: string, after: number = 0, limit: number = 100): Message[] {
     return this.listByRecipient(recipient, after, limit);
   }
 
+  /** One ordered scan for every SSE subscriber; recipient filtering happens in the server. */
+  listAfter(after: number, limit: number = 1000): Message[] {
+    validCursor(after);
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error('limit must be between 1 and 1000');
+    return this.readWithSchema(hasReplyTo => (this.db.query(`SELECT id, sender, recipient, body, kind, ${hasReplyTo ? 'reply_to' : 'NULL AS reply_to'}, created_at FROM msg_messages
+      WHERE id > ? ORDER BY id ASC LIMIT ?`).all(after, limit) as MessageRow[]).map(fromRow));
+  }
+
+  latestId(): number {
+    return (this.db.query('SELECT COALESCE(MAX(id), 0) AS id FROM msg_messages').get() as { id: number }).id;
+  }
+
   getCursor(recipient: string): number {
     const to = canonicalSeatId(recipient);
     if (to === 'ALL') throw new Error('ALL is a topic, not a recipient');
@@ -199,6 +268,7 @@ export class MsgStore {
 
 export function defaultMsgStorePath(): string { return join(elanousStateRoot(), 'msg', 'messages.db'); }
 export function openMsgStore(path?: string): MsgStore { return new MsgStore(path); }
+export function openMsgStoreReadOnly(path?: string): MsgStore { return new MsgStore(path, { readOnly: true }); }
 
 /** Observe one recipient without creating a store or advancing its acknowledgement. */
 export function readUnreadCount(recipient: string, path: string = defaultMsgStorePath()): number | null {