elanous 0.2.29 → 0.2.31

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

@@ -0,0 +1,223 @@
+// ── 우편 SSE 구독 클라이언트 — 받는 몸이 «듣는» 쪽 ──
+//
+// 서버(`msg-sse-server.ts` · `eln msg serve --sse`)는 원장을 빨리 밀어 줄 뿐이고 원장(SQLite)이 정본이다.
+// 이 클라이언트는 한 주소를 구독해 글마다 `onMessage` 를 부른다.
+//   · 커서(Last-Event-ID)는 주소별 state-dir 파일에 보존하고 «onMessage 가 성공한 뒤에만» 전진한다
+//     — 실패하면 같은 글이 다시 온다(at-least-once · 중복은 소비자가 provenance 키로 거른다).
+//   · SSE 가 끊기면 지수 백오프(상한)로 다시 붙고, 기다리는 동안은 원장을 직접 폴링해 빠짐을 막는다.
+//   · 우체국 주소는 인자(`url`)로만 받는다(env·config·하드코딩 0) — 없으면 원장 폴링이 운영 기본이다.
+//     서버가 없거나 토큰이 거절되어도 같은 길로 원장 폴링에 내려앉는다 — `fallback-poll` 로그.
+//   · stop() 뒤에는 콜백 0.
+// 관측: debug.log('msg.sse-client', connect|reconnect|replay|fallback-poll|deliver-failed|stop, …) — 원장을 직접 읽는 구간마다 fallback-poll
+
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { ensureAuthToken } from '../auth/acp-token.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { canonicalSeatId, openMsgStoreReadOnly, type Message, type MsgStore } from './msg-store.js';
+
+export interface MsgStreamOptions {
+  address: string;
+  /** Resolve to advance the cursor; reject to receive the same message again. */
+  onMessage: (message: Message) => void | Promise<void>;
+  signal?: AbortSignal;
+  /** Default `<state-dir>/msg/sse-cursor/<ADDRESS>.json`. */
+  cursorPath?: string;
+  /**
+   * Post office base URL — only by argument (OP #3237: no env, config key or hard-coded port on the
+   * operating path). Absent = poll the ledger, which alone still delivers (wakes) every message.
+   * Discovery through the control resource ledger is a follow-up goal (ASK-MSG-SSE-LEDGER-DISCOVERY).
+   */
+  url?: string;
+  token?: () => string;
+  /** Ledger reader for the polling fallback (default: read-only ledger in this state-dir). */
+  openStore?: () => MsgStore;
+  fetch?: typeof fetch;
+  /** Reconnect backoff: doubles from `initialMs` to `maxMs`, reset after a successful connect. */
+  backoff?: { initialMs?: number; maxMs?: number };
+  pollMs?: number;
+  /** Reconnect when the stream is silent this long (the server sends a keepalive every second). */
+  idleTimeoutMs?: number;
+}
+
+export interface MsgStreamHandle {
+  /** Stop delivering; resolves once the loop has exited. No callback starts after stop() is called. */
+  stop: () => Promise<void>;
+}
+
+const LOG = 'msg.sse-client';
+
+function defaultCursorPath(address: string): string {
+  return join(elanousStateRoot(), 'msg', 'sse-cursor', `${address}.json`);
+}
+
+/** The saved cursor for `address` — a file written for another address is ignored (start from 0), never borrowed. */
+function readCursor(path: string, address: string): number | undefined {
+  let saved: { address?: unknown; lastEventId?: unknown };
+  try { saved = JSON.parse(readFileSync(path, 'utf8')) as typeof saved; } catch { return undefined; }
+  if (saved.address !== address) {
+    debug.log(LOG, 'cursor-address-mismatch', { address, fileAddress: typeof saved.address === 'string' ? saved.address : null, path });
+    return undefined;
+  }
+  const value = saved.lastEventId;
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function writeCursor(path: string, address: string, lastEventId: number): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ address, lastEventId, at: new Date().toISOString() }));
+  renameSync(tmp, path);
+}
+
+class StopError extends Error {}
+
+export function subscribeMsgStream(options: MsgStreamOptions): MsgStreamHandle {
+  const address = canonicalSeatId(options.address);
+  if (address === 'ALL') throw new Error('ALL is a topic, not a recipient');
+  const cursorPath = options.cursorPath ?? defaultCursorPath(address);
+  const url = options.url;
+  const doFetch = options.fetch ?? fetch;
+  const initialBackoff = options.backoff?.initialMs ?? 500;
+  const maxBackoff = options.backoff?.maxMs ?? 30_000;
+  const pollMs = options.pollMs ?? 1000;
+  const idleTimeoutMs = options.idleTimeoutMs ?? 10_000;
+  const controller = new AbortController();
+  const onOuterAbort = () => controller.abort();
+  options.signal?.addEventListener('abort', onOuterAbort, { once: true });
+  if (options.signal?.aborted) controller.abort();
+  const stopped = () => controller.signal.aborted;
+  let cursor = readCursor(cursorPath, address) ?? 0;
+
+  const sleep = (ms: number) => new Promise<void>(resolve => {
+    if (stopped()) { resolve(); return; }
+    const timer = setTimeout(done, ms);
+    function done() { clearTimeout(timer); controller.signal.removeEventListener('abort', done); resolve(); }
+    controller.signal.addEventListener('abort', done, { once: true });
+  });
+
+  /** Deliver in order; the cursor moves only after onMessage resolves. Returns false when a delivery failed. */
+  const deliver = async (message: Message, via: 'sse' | 'poll'): Promise<boolean> => {
+    if (message.id <= cursor) return true;
+    if (stopped()) throw new StopError();
+    try { await options.onMessage(message); }
+    catch (error) {
+      debug.log(LOG, 'deliver-failed', { address, msgId: message.id, via, cursor, error: error instanceof Error ? error.message : String(error) });
+      return false;
+    }
+    cursor = message.id;
+    try { writeCursor(cursorPath, address, cursor); }
+    catch (error) { debug.log(LOG, 'cursor-write-failed', { address, cursor, error: error instanceof Error ? error.message : String(error) }); }
+    return true;
+  };
+
+  /** Drain the ledger directly — the outage path. Stops at the first failed delivery. */
+  const pollOnce = async (): Promise<void> => {
+    let store: MsgStore;
+    try { store = (options.openStore ?? (() => openMsgStoreReadOnly()))(); }
+    catch (error) { debug.log(LOG, 'poll-unavailable', { address, error: error instanceof Error ? error.message : String(error) }); return; }
+    try {
+      for (;;) {
+        const batch = store.listByRecipient(address, cursor, 100);
+        for (const message of batch) if (!await deliver(message, 'poll')) return;
+        if (batch.length < 100) return;
+      }
+    } finally { store.close(); }
+  };
+
+  /** One SSE session; resolves when it ends (server gone, idle, delivery failure). Throws for 401. */
+  const streamOnce = async (base: string, attempt: number): Promise<{ connected: boolean }> => {
+    const target = new URL('/stream', base);
+    target.searchParams.set('to', address);
+    target.searchParams.set('since', String(cursor));
+    const session = new AbortController();
+    const onStop = () => session.abort();
+    controller.signal.addEventListener('abort', onStop, { once: true });
+    try {
+      const token = (options.token ?? (() => ensureAuthToken().token))();
+      // 재접속은 «실제로 다시 요청하는 순간»에 남긴다 — 토큰을 못 얻어 요청이 없으면 기록도 없다(첫 연결은 connect 만).
+      if (attempt > 0) debug.log(LOG, 'reconnect', { address, attempts: attempt, cursor });
+      // 헤더 대기에도 같은 무음 제한 — 연결만 받고 응답을 안 주는 서버에 매달려 폴링이 멈추지 않게.
+      let connectTimer: ReturnType<typeof setTimeout> | undefined;
+      const response = await Promise.race([
+        doFetch(target, { headers: { Authorization: `Bearer ${token}`, 'Last-Event-ID': String(cursor) }, signal: session.signal }),
+        new Promise<never>((_, reject) => { connectTimer = setTimeout(() => { session.abort(); reject(new Error('SSE connect timeout')); }, idleTimeoutMs); }),
+      ]).finally(() => clearTimeout(connectTimer));
+      if (response.status === 401) throw Object.assign(new Error('SSE unauthorized (401)'), { unauthorized: true });
+      if (!response.ok || !response.body) throw new Error(`SSE unavailable (${response.status})`);
+      debug.log(LOG, 'connect', { address, url: target.origin, lastEventId: cursor });
+      if (cursor > 0) debug.log(LOG, 'replay', { address, from: cursor });
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let pending = '';
+      while (!stopped()) {
+        let idle: ReturnType<typeof setTimeout> | undefined;
+        const chunk = await Promise.race([
+          reader.read(),
+          new Promise<never>((_, reject) => { idle = setTimeout(() => reject(new Error('SSE idle timeout')), idleTimeoutMs); }),
+        ]).finally(() => clearTimeout(idle));
+        if (chunk.done) break;
+        pending = (pending + decoder.decode(chunk.value, { stream: true })).replace(/\r\n/g, '\n');
+        if (pending.length > 1_000_000) throw new Error('SSE event exceeds limit');
+        let boundary: number;
+        while ((boundary = pending.indexOf('\n\n')) >= 0) {
+          const frame = pending.slice(0, boundary);
+          pending = pending.slice(boundary + 2);
+          const data = frame.split('\n').filter(line => line.startsWith('data: ')).map(line => line.slice(6)).join('\n');
+          if (!data) continue;
+          // A failed delivery drops this session; the reconnect replays from the unchanged cursor.
+          if (!await deliver(JSON.parse(data) as Message, 'sse')) return { connected: true };
+        }
+      }
+      return { connected: true };
+    } finally {
+      controller.signal.removeEventListener('abort', onStop);
+      session.abort();
+    }
+  };
+
+  /** Poll the ledger until `until` — one `fallback-poll` per interval. */
+  const pollInterval = async (reason: string, until: number, attempts: number): Promise<void> => {
+    debug.log(LOG, 'fallback-poll', { address, reason, cursor, attempts, ...(Number.isFinite(until) ? { untilMs: until - Date.now() } : {}) });
+    do {
+      try { await pollOnce(); }
+      catch (error) { if (error instanceof StopError) return; debug.log(LOG, 'poll-failed', { address, error: error instanceof Error ? error.message : String(error) }); }
+      await sleep(Math.min(pollMs, Math.max(0, until - Date.now())));
+    } while (!stopped() && Date.now() < until);
+  };
+
+  const loop = (async () => {
+    // 주소가 없으면 처음부터 원장 폴링 한 구간(끝 없음) — 운영 기본.
+    if (!url) { await pollInterval('no-url', Number.POSITIVE_INFINITY, 0); return; }
+    let backoff = initialBackoff;
+    let attempts = 0;
+    while (!stopped()) {
+      let reason: string;
+      try {
+        const { connected } = await streamOnce(url, attempts);
+        if (connected) backoff = initialBackoff;
+        reason = 'stream-ended';
+      } catch (error) {
+        if (error instanceof StopError || stopped()) break;
+        reason = (error as { unauthorized?: boolean }).unauthorized ? 'unauthorized' : error instanceof Error ? error.message : String(error);
+      }
+      if (stopped()) break;
+      attempts++;
+      // 끊긴 동안(서버 없음·토큰 거절·무응답·재접속 대기)은 원장을 직접 폴링한다.
+      await pollInterval(reason, Date.now() + backoff, attempts);
+      backoff = Math.min(maxBackoff, backoff * 2);
+    }
+  })();
+
+  return {
+    stop: async () => {
+      if (!stopped()) debug.log(LOG, 'stop', { address, cursor });
+      controller.abort();
+      options.signal?.removeEventListener('abort', onOuterAbort);
+      await loop.catch(() => undefined);
+    },
+  };
+}

package/src/msg/msg-store.ts

@@ -1,4 +1,5 @@
 import { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
@@ -64,6 +65,15 @@ function validCursor(cursor: number): number {
   return cursor;
 }
 
+/** Unread count ⊕ newest unread ID for one recipient (same predicate as `unreadCountOn`). */
+function unreadSummaryOn(db: Database, to: string): { count: number; maxId: number | null } {
+  const row = db.query(`SELECT COUNT(*) AS count, MAX(m.id) AS max_id FROM msg_messages m
+    WHERE m.id > COALESCE((SELECT last_id FROM msg_cursors WHERE recipient = ?), 0)
+      AND (m.recipient = ? OR (m.recipient = 'ALL' AND m.sender <> ?))`)
+    .get(to, to, to) as { count: number; max_id: number | null };
+  return { count: row.count, maxId: row.max_id ?? null };
+}
+
 function unreadCountOn(db: Database, to: string): number {
   return (db.query(`SELECT COUNT(*) AS count FROM msg_messages m
     WHERE m.id > COALESCE((SELECT last_id FROM msg_cursors WHERE recipient = ?), 0)
@@ -126,6 +136,14 @@ export class MsgStore {
     CREATE TABLE IF NOT EXISTS msg_provenance (
       provenance_key TEXT PRIMARY KEY,
       message_id INTEGER NOT NULL REFERENCES msg_messages(id)
+    );
+    CREATE TABLE IF NOT EXISTS msg_ta_delivery (
+      request_id INTEGER PRIMARY KEY REFERENCES msg_messages(id),
+      status TEXT NOT NULL CHECK(status IN ('pending', 'delivered'))
+    );
+    CREATE TABLE IF NOT EXISTS msg_ta_claim (
+      request_id INTEGER PRIMARY KEY REFERENCES msg_messages(id),
+      token TEXT NOT NULL
     );`);
     // Serialize the schema check and ALTER across processes opening an old ledger at once.
     if (!options.readOnly) this.db.transaction(() => {
@@ -140,9 +158,9 @@ export class MsgStore {
     return this.insertMessage(input);
   }
 
-  /** Append once for a coordination comment or a task failure incident. */
+  /** Append once for a coordination comment, task failure, or decided notification. */
   appendWithProvenance(input: MessageEnvelope, provenanceKey: string): Message {
-    if (typeof provenanceKey !== 'string' || !/^(?:coord|ta-failure):[^:]+:[^:]+$/.test(provenanceKey)) {
+    if (typeof provenanceKey !== 'string' || !/^(?:coord|ta-failure|decision):[^:]+:[^:]+$/.test(provenanceKey)) {
       throw new Error('invalid message provenance key');
     }
     const msg = validateMessageEnvelope(input);
@@ -172,6 +190,62 @@ export class MsgStore {
 
   post(input: MessageEnvelope): Message { return this.append(input); }
 
+  /** Delivery state is separate from the single linked reply; an uncertain send keeps its claim. */
+  taDeliveryStatus(requestId: number): 'pending' | 'delivered' | null {
+    return (this.db.query('SELECT status FROM msg_ta_delivery WHERE request_id = ?').get(requestId) as { status: 'pending' | 'delivered' } | null)?.status ?? null;
+  }
+
+  setTaDeliveryStatus(requestId: number, status: 'pending' | 'delivered'): void {
+    this.db.query(`INSERT INTO msg_ta_delivery(request_id, status) VALUES (?, ?)
+      ON CONFLICT(request_id) DO UPDATE SET status = excluded.status`).run(requestId, status);
+  }
+
+  /** A short DB transaction grants one sender the external delivery. An abandoned claim stays ambiguous. */
+  claimTaDelivery(requestId: number): string | null {
+    return this.db.transaction(() => {
+      if (this.taDeliveryStatus(requestId) !== 'pending') return null;
+      const previous = this.db.query('SELECT 1 FROM msg_ta_claim WHERE request_id = ?').get(requestId);
+      if (previous) return null;
+      const token = randomUUID();
+      this.db.query('INSERT INTO msg_ta_claim(request_id, token) VALUES (?, ?)').run(requestId, token);
+      return token;
+    }).immediate();
+  }
+
+  taDeliveryClaimState(requestId: number): 'none' | 'held' {
+    return this.db.query('SELECT 1 FROM msg_ta_claim WHERE request_id = ?').get(requestId) ? 'held' : 'none';
+  }
+
+  /** Only the active sender may settle or report its own attempt; stale failures cannot overwrite success. */
+  settleTaDelivery(requestId: number, token: string, replyBody: string, delivered: boolean): boolean {
+    return this.db.transaction(() => {
+      const owner = this.db.query('SELECT token FROM msg_ta_claim WHERE request_id = ?').get(requestId) as { token: string } | null;
+      if (owner?.token !== token || this.taDeliveryStatus(requestId) === 'delivered') return false;
+      if (delivered) this.setTaDeliveryStatus(requestId, 'delivered');
+      this.updateTaReply(requestId, replyBody);
+      this.db.query('DELETE FROM msg_ta_claim WHERE request_id = ? AND token = ?').run(requestId, token);
+      return true;
+    }).immediate();
+  }
+
+  /** Keep the claim after any transport/settlement exception: publication may already have happened. */
+  markTaDeliveryUnknown(requestId: number, token: string, replyBody: string): boolean {
+    return this.db.transaction(() => {
+      const owner = this.db.query('SELECT token FROM msg_ta_claim WHERE request_id = ?').get(requestId) as { token: string } | null;
+      if (owner?.token !== token || this.taDeliveryStatus(requestId) === 'delivered') return false;
+      this.updateTaReply(requestId, replyBody);
+      return true;
+    }).immediate();
+  }
+
+  /** Settle only the TA reply reserved for this request; never create a second reply. */
+  updateTaReply(requestId: number, body: string): void {
+    const changed = this.db.query(`UPDATE msg_messages SET body = ? WHERE id = (
+      SELECT id FROM msg_messages WHERE reply_to = ? AND sender = 'TA' ORDER BY id ASC LIMIT 1
+    ) AND sender = 'TA'`).run(body, requestId);
+    if (changed.changes !== 1) throw new Error(`TA reply missing: #${requestId}`);
+  }
+
   /** Messages strictly after the supplied cursor, ordered by durable insertion ID. */
   listByRecipient(recipient: string, after: number = 0, limit: number = 100): Message[] {
     const to = canonicalSeatId(recipient);
@@ -279,3 +353,13 @@ export function readUnreadCount(recipient: string, path: string = defaultMsgStor
   try { return unreadCountOn(db, to); }
   finally { db.close(); }
 }
+
+/** Observe one recipient's unread count ⊕ newest unread ID (read-only · no cursor change). null = ledger absent («모름»). */
+export function readUnreadSummary(recipient: string, path: string = defaultMsgStorePath()): { count: number; maxId: number | null } | null {
+  const to = canonicalSeatId(recipient);
+  if (to === 'ALL') throw new Error('ALL is a topic, not a recipient');
+  if (!existsSync(path)) return null;
+  const db = new Database(path, { readonly: true });
+  try { return unreadSummaryOn(db, to); }
+  finally { db.close(); }
+}

package/src/mss/logging/log-store.ts

@@ -19,8 +19,11 @@
 import { Database } from 'bun:sqlite';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readlinkSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 import { LOG_LEVEL_ORDER, type LogLevel, type LogRecord } from './record.js';
 import type { LogSink } from './sink.js';
@@ -978,6 +981,224 @@ function ownerDead(owner: RetentionLockOwner): boolean {
   }
 }
 
+// ── ⓑ 수호자: «설치 sha 보다 옛 판으로 logs.db 를 연 프로세스» 경보 (LOGS-RETENTION-46MIN) ──
+//
+// 사고(10-12 · 운영 보존 46분): 하한 이전 판을 쥔 옛 크론 프로세스들이 6시간마다
+// «오래된 행 50%» 삭제를 겹쳐 돌려 보존 창을 무너뜨렸다. retention 주기마다 lsof
+// 상당(/proc/<pid>/fd 스캔)으로 logs.db(-wal/-shm 포함)를 연 프로세스를 찾고, lstart
+// 상당(이 파일의 processStart() = /proc/<pid>/stat starttime)으로 «현재 설치 sha 의
+// 설치 시점보다 먼저 기동»한 프로세스(=옛 판 코드를 쥔 채 살아 있는 것)를 경보한다.
+// 마커는 git ref/HEAD 파일의 mtime(=이 sha 가 체크아웃된 시점)이지 모듈 파일 mtime 이
+// 아니다(must-fix — 그 파일이 변경되지 않은 채 새 판을 설치하면 옛 판을 놓친다). 전부 fail-soft.
+
+export interface LogDbOpenerInfo {
+  pid: number;
+  /** /proc/<pid>/stat starttime(clock ticks) — lstart 상당(pid 재사용 판별용). */
+  start: string | null;
+  /** 기동 절대시각(ms) — /proc/stat btime + ticks/100(리눅스 CLK_TCK=100 환산). */
+  startedAtMs: number | null;
+  cmdline: string[] | null;
+  cwd: string | null;
+  /** 열린 프로세스의 checkout ref. 설치 후 다른 checkout에서 기동한 옛 판도 구별한다. */
+  revisionSha?: string | null;
+}
+
+/** procfs 부팅 시각(ms). 읽기 실패 시 null(=환산 불가 → 경보하지 않는다, fail-safe). */
+function procBootTimeMs(): number | null {
+  try {
+    for (const line of readFileSync('/proc/stat', 'utf8').split('\n')) {
+      if (line.startsWith('btime ')) return Number(line.slice(6).trim()) * 1000;
+    }
+  } catch { /* fail-soft */ }
+  return null;
+}
+
+/** lsof 상당 — logs.db(와 -wal/-shm)를 연 fd 를 든 프로세스 목록. 개별 pid 실패는 조용히 건너뛴다. */
+export function scanLogDbOpeners(dbPath: string, opts: { selfPid?: number } = {}): LogDbOpenerInfo[] {
+  const selfPid = opts.selfPid ?? process.pid;
+  const wanted = new Set([dbPath, `${dbPath}-wal`, `${dbPath}-shm`]);
+  const bootMs = procBootTimeMs();
+  const openers: LogDbOpenerInfo[] = [];
+  let pids: string[];
+  try { pids = readdirSync('/proc').filter((name) => /^[0-9]+$/.test(name)); } catch { return openers; }
+  for (const name of pids) {
+    const pid = Number(name);
+    if (pid === selfPid) continue;
+    let holds = false;
+    try {
+      for (const fdName of readdirSync(`/proc/${pid}/fd`)) {
+        let target: string;
+        try { target = readlinkSync(`/proc/${pid}/fd/${fdName}`); } catch { continue; }
+        if (wanted.has(target)) { holds = true; break; }
+      }
+    } catch { continue; }
+    if (!holds) continue;
+    const start = processStart(pid);
+    const ticks = start === null ? null : Number(start);
+    let cmdline: string[] | null = null;
+    try { cmdline = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean); } catch { /* fail-soft */ }
+    let cwd: string | null = null;
+    try { cwd = readlinkSync(`/proc/${pid}/cwd`); } catch { /* fail-soft */ }
+    // cwd는 새 checkout일 수 있다. 실행한 스크립트 경로가 가리키는 판을 먼저 읽는다.
+    // 절대 경로뿐 아니라 cwd 상대 스크립트도 처리한다. 찾지 못할 때만 cwd로 폴백.
+    const scriptSha = cmdline?.slice(1).filter((arg) => /\.(?:[cm]?[jt]s|sh)$/.test(arg))
+      .map((arg) => resolveCheckoutRevisionFromCwd(dirname(resolve(cwd ?? '/', arg))))
+      .find((sha) => sha !== null) ?? null;
+    const revisionSha = scriptSha ?? (cwd === null ? null : resolveCheckoutRevisionFromCwd(cwd));
+    openers.push({ pid, start, startedAtMs: ticks !== null && bootMs !== null ? bootMs + (ticks / 100) * 1000 : null, cmdline, cwd, revisionSha });
+  }
+  return openers;
+}
+
+export interface InstalledRevisionMarker {
+  /** 이 체크아웃의 HEAD sha. 실패 시 null. */
+  sha: string | null;
+  /** 현재 sha 가 이 체크아웃에 설치된 시점(ms) — git ref/HEAD 파일의 mtime. 실패 시 null. */
+  installedAtMs: number | null;
+  /** 마커로 읽은 파일 경로 — 경보 payload 에 싣는 용도. */
+  marker: string | null;
+}
+
+/** /proc/<pid>/cwd에서 위로 올라가 첫 Git checkout의 현재 ref를 읽는다. */
+function resolveCheckoutRevisionFromCwd(cwd: string): string | null {
+  let current = cwd;
+  while (true) {
+    if (existsSync(join(current, '.git'))) return resolveInstalledRevisionMarker(current).sha;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** 설치 판 마커 — HEAD sha 와 «그 sha 가 설치된 시점»을 함께 돌린다(worktree 의 .git 파일·
+ * commondir 도 해석). must-fix(리뷰): 옛 판 판정 기준은 모듈 파일 mtime 이 아니라 «설치
+ * 시점»이다 — 같은 파일이 변경되지 않은 채 새 판을 설치하면 모듈 mtime 은 옛 채로 있어
+ * 옛 판 오프너를 놓친다. 설치 시점의 파일시스템 근거: 브랜치 체크아웃은 ref 파일 mtime
+ * (=pull·merge·reset·commit 로 ref 가 움직인 시점), detached 전환은 HEAD 파일 mtime —
+ * 둘 중 늦은 쪽. 전부 실패 시 null(fail-safe — 경보하지 않는다). */
+export function resolveInstalledRevisionMarker(root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')): InstalledRevisionMarker {
+  const none: InstalledRevisionMarker = { sha: null, installedAtMs: null, marker: null };
+  try {
+    const dotGit = join(root, '.git');
+    let gitDir: string;
+    if (statSync(dotGit).isDirectory()) gitDir = dotGit;
+    else {
+      const firstLine = readFileSync(dotGit, 'utf8').trim();
+      if (!firstLine.startsWith('gitdir:')) return none;
+      gitDir = resolve(root, firstLine.slice(7).trim());
+    }
+    const headPath = join(gitDir, 'HEAD');
+    let head: string;
+    try { head = readFileSync(headPath, 'utf8').trim(); } catch { return none; }
+    if (!head.startsWith('ref: ')) {
+      // detached — HEAD 파일이 sha 를 직접 쥔다: 그 mtime = 체크아웃(=설치) 시점.
+      if (!/^[0-9a-f]{40}$/.test(head)) return none;
+      try { return { sha: head, installedAtMs: statSync(headPath).mtimeMs, marker: headPath }; } catch { return none; }
+    }
+    const ref = head.slice(5).trim();
+    const commonDir = existsSync(join(gitDir, 'commondir'))
+      ? resolve(gitDir, readFileSync(join(gitDir, 'commondir'), 'utf8').trim())
+      : gitDir;
+    const looseRef = [join(gitDir, ref), join(commonDir, ref)].find(existsSync);
+    const markerPath = looseRef ?? join(commonDir, 'packed-refs');
+    const sha = looseRef
+      ? readFileSync(looseRef, 'utf8').trim()
+      : readFileSync(markerPath, 'utf8').split('\n')
+          .find((line) => line.endsWith(` ${ref}`) && /^[0-9a-f]{40} /.test(line))?.slice(0, 40) ?? '';
+    if (!/^[0-9a-f]{40}$/.test(sha)) return none;
+    // packed-refs mtime은 재패킹만 해도 움직이므로 설치 시각으로 쓰면 오경보가 난다.
+    // packed ref의 체크아웃 시각은 HEAD mtime만 사용한다. loose ref는 ref 갱신과
+    // 체크아웃 중 늦은 시각을 사용한다.
+    let installedAtMs: number | null = null;
+    try { installedAtMs = looseRef
+      ? Math.max(statSync(markerPath).mtimeMs, statSync(headPath).mtimeMs)
+      : statSync(headPath).mtimeMs; } catch { /* fail-soft */ }
+    return { sha, installedAtMs, marker: markerPath };
+  } catch { return none; }
+}
+
+/** 설치 sha — 이 체크아웃의 HEAD. 실패 시 null. */
+export function resolveInstalledSha(): string | null {
+  return resolveInstalledRevisionMarker().sha;
+}
+
+export interface StaleOpenerCheck {
+  selfPid: number;
+  /** 현재 설치 sha 가 설치된 시점(ms) — 이보다 먼저 기동한 오프너는 옛 판이다(must-fix: 모듈 mtime 아님). */
+  installedAtMs: number | null;
+  /** 경보 문자열에 싣는 현재 설치 sha. */
+  installedSha?: string | null;
+  revisionRelation?: 'older' | 'newer' | 'different' | 'same';
+}
+
+/** 설치 checkout의 Git 객체 그래프에서 선후를 확인한다. 알 수 없으면 다른 판으로 남긴다. */
+function revisionRelation(openerSha: string | null | undefined, installedSha: string | null): StaleOpenerCheck['revisionRelation'] {
+  if (!openerSha || !installedSha) return 'different';
+  if (openerSha === installedSha) return 'same';
+  const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+  const ancestor = (from: string, to: string): boolean =>
+    spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', from, to], { timeout: 2_000, stdio: 'ignore' }).status === 0;
+  if (ancestor(openerSha, installedSha)) return 'older';
+  if (ancestor(installedSha, openerSha)) return 'newer';
+  return 'different';
+}
+
+/** 순수 — 오프너 하나가 «옛 판»인가? 이유 문자열, 정상이면 null. 측정 결측은 정상 취급(fail-safe). */
+export function staleOpenerReason(opener: LogDbOpenerInfo, check: StaleOpenerCheck): string | null {
+  if (opener.pid === check.selfPid) return null;
+  if (check.revisionRelation === 'newer' || check.revisionRelation === 'different') return null;
+  if (check.revisionRelation === 'older') {
+    return `checkout revision ${opener.revisionSha} precedes installed revision ${check.installedSha}`;
+  }
+  if (check.installedAtMs === null || opener.startedAtMs === null) return null;
+  if (opener.startedAtMs >= check.installedAtMs) return null;
+  return `started ${new Date(opener.startedAtMs).toISOString()} before installed revision ${check.installedSha ?? 'unknown'} (installed at ${new Date(check.installedAtMs).toISOString()})`;
+}
+
+export interface StaleOpenerAlert {
+  pid: number;
+  start: string | null;
+  startedAt: string | null;
+  reason: string;
+}
+
+/** 수호자 본체 — 옛 판 오프너를 찾아 `log-store.retention`/`stale-opener-alert` 경보 관측을
+ *  남긴다. caller: runStampedRetention(보존 주기마다 1회 · registerLogStoreSink 가 스케줄).
+ *  전 경로 fail-soft — 수호자가 retention 을 절대 깨지 않는다. */
+export function alertStaleLogDbOpeners(
+  dbPath: string,
+  deps: { openers?: () => LogDbOpenerInfo[]; installedAtMs?: number | null } = {},
+): StaleOpenerAlert[] {
+  const alerts: StaleOpenerAlert[] = [];
+  try {
+    // must-fix: 옛 판 판정 마커는 모듈 파일 mtime 이 아니라 «설치 sha 의 설치 시점»이다.
+    const marker = resolveInstalledRevisionMarker();
+    const installedAtMs = deps.installedAtMs ?? marker.installedAtMs;
+    const openers = (deps.openers ?? (() => scanLogDbOpeners(dbPath)))();
+    for (const opener of openers) {
+      const relation = opener.revisionSha && marker.sha
+        ? revisionRelation(opener.revisionSha, marker.sha) : undefined;
+      if (relation === 'different') {
+        debug.log('log-store.retention', 'different-opener-alert', {
+          pid: opener.pid, db: dbPath, openerSha: opener.revisionSha, installedSha: marker.sha,
+          reason: 'checkout revision ancestry unavailable or divergent',
+        }, { level: 'warn' });
+        continue;
+      }
+      const reason = staleOpenerReason(opener, { selfPid: process.pid, installedAtMs, installedSha: marker.sha, revisionRelation: relation });
+      if (!reason) continue;
+      const startedAt = opener.startedAtMs === null ? null : new Date(opener.startedAtMs).toISOString();
+      alerts.push({ pid: opener.pid, start: opener.start, startedAt, reason });
+      debug.log('log-store.retention', 'stale-opener-alert', {
+        pid: opener.pid, start: opener.start, startedAt, reason,
+        db: dbPath, installedSha: marker.sha, openerSha: opener.revisionSha ?? null, installedAtMs,
+        marker: marker.marker, via: 'procfs-fd+stat',
+      }, { level: 'warn' });
+    }
+  } catch { /* fail-soft — 수호자가 retention 을 깨지지 않게 한다 */ }
+  return alerts;
+}
+
 /** Only the guard row can authorize removal. A pre-publication temp file belongs to its row's token. */
 function removeRetentionLockDirectory(lockPath: string, token: string, interrupted: boolean): void {
   if (!existsSync(lockPath)) return;
@@ -1071,6 +1292,9 @@ function runStampedRetention(store: LogStore, retention: LogStoreRetention, owne
   if (!release) return;
   try {
     if (!owner && isFresh()) return;
+    // ⓑ 수호자 — 설치 판보다 먼저 기동한(=옛 판) logs.db 오프너 경보(lsof⊕lstart 상당,
+    // fail-soft). 보존 주기(6h · owner=nexus)마다 함께 돈다.
+    alertStaleLogDbOpeners(store.path);
     store.enforceRetention(retention);
     try { store.reclaimFreePages(); }
     catch (error) { debug.log('log-store.retention', 'reclaim-failed', { reason: error instanceof Error ? error.message : String(error) }); }