elanous 0.2.29 → 0.2.31

package/src/loops/consensus.ts

@@ -0,0 +1,348 @@
+// 두 대표 합의 체제 — 조율자(일의 흐름)·수호자(몸)가 루프 세계의 공동 대표다.
+// 다섯 범주(①스폰·은퇴 ②shadow→live 승격 ③상대 가지 영향 변경 ④주기·예산 ⑤운영 그래프 구조 변경)는 «둘의 합의» 뒤에 실행된다.
+// 제안 카드(사실 id·비용·되돌리기) → 상대 검토 최대 2왕복 → 합의: 실행·합의 원장 / 불합의·임계 범주: 양쪽 주장 나란히 대표 결정 카드.
+// 메아리 방지 — 대표별 렌즈(입력 원장) 분리 ⊕ 가능하면 다른 LLM 제공자 표식.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { DecisionLedger, type DecisionCategory } from '../decisions/decision-ledger.js';
+import type { Versions } from '../directives/version-at.js';
+
+export type ConsensusRepresentative = 'coordinator' | 'guardian';
+export const CONSENSUS_REPRESENTATIVES: readonly ConsensusRepresentative[] = ['coordinator', 'guardian'];
+/** 조율자는 일의 흐름, 수호자는 몸을 가진 공동 대표다. */
+export const representativeLabel = (who: ConsensusRepresentative): string =>
+  who === 'coordinator' ? '조율자(일의 흐름)' : '수호자(몸)';
+
+export type ConsensusCategory =
+  | 'spawn-retire'
+  | 'shadow-live-promotion'
+  | 'cross-branch-change'
+  | 'period-budget'
+  | 'graph-structure-change';
+export const CONSENSUS_CATEGORIES: readonly ConsensusCategory[] = [
+  'spawn-retire', 'shadow-live-promotion', 'cross-branch-change', 'period-budget', 'graph-structure-change',
+];
+const CATEGORY_LABELS: Record<ConsensusCategory, string> = {
+  'spawn-retire': '①스폰·은퇴',
+  'shadow-live-promotion': '②shadow→live 승격',
+  'cross-branch-change': '③상대 가지 영향 변경',
+  'period-budget': '④주기·예산',
+  'graph-structure-change': '⑤운영 그래프 구조 변경',
+};
+export const categoryLabel = (category: ConsensusCategory): string => CATEGORY_LABELS[category];
+
+/** 상대 검토는 최대 2왕복이다. */
+export const MAX_REVIEW_ROUND_TRIPS = 2;
+
+/** 대표 몫 = 불합의 ⊕ 돈·보안·되돌릴 수 없는 것 — 결정 원장의 DecisionCategory 어휘를 그대로 쓴다 (import 만). */
+export const CROWN_THRESHOLD_CATEGORIES: readonly DecisionCategory[] = ['money', 'security', 'irreversible'];
+
+/** 대표 카드 표식 — 소스에 글자를 직접 쓰면 공개본 유출 검사(ceo-mark)가 문자열 안까지 문다 — 코드 포인트로 만든다. */
+export const CROWN_MARK = String.fromCodePoint(0x1F451);
+
+export interface ProposalCard {
+  id: string;
+  category: ConsensusCategory;
+  title: string;
+  /** 사실 id — 제안의 근거 관측. */
+  factId: string;
+  /** 비용 */
+  cost: string;
+  /** 되돌리기 */
+  undo: string;
+  thresholds: DecisionCategory[];
+  proposedBy: ConsensusRepresentative;
+  proposedAt: string;
+  status: 'open' | 'agreed' | 'disagreed';
+  roundTrips: number;
+  reviews: ReviewRecord[];
+  provider?: string;
+}
+
+export interface ReviewRecord {
+  by: ConsensusRepresentative;
+  at: string;
+  roundTrip: number;
+  verdict: 'revise' | 'agree' | 'disagree';
+  claim: string;
+  provider?: string;
+}
+
+/** 대표 결정 카드 — 양쪽 주장이 나란히 실린다. */
+export interface CrownCard {
+  id: string;
+  proposalId: string;
+  reason: 'disagreement' | 'threshold';
+  thresholds: DecisionCategory[];
+  coordinatorClaim: string;
+  guardianClaim: string;
+  raisedAt: string;
+  /** 결정 원장 미러 카드 — refs 로 멱등이라 같은 제안의 재발급은 같은 카드를 돌려준다. */
+  decisionId?: string;
+}
+
+export type ConsensusEvent =
+  | { type: 'proposed'; proposal: ProposalCard }
+  | { type: 'reviewed'; proposalId: string; review: ReviewRecord }
+  | { type: 'agreed'; proposalId: string; at: string; agreedBy: ConsensusRepresentative }
+  | { type: 'disagreed'; proposalId: string; at: string; disagreedBy: ConsensusRepresentative }
+  | { type: 'crown-card'; card: CrownCard };
+
+/** 렌즈(입력 원장) 이벤트 — 행위한 대표의 원장에만 남는다 (메아리 방지). */
+export interface LensEvent {
+  action: 'proposed' | 'reviewed';
+  proposalId: string;
+  at: string;
+  verdict?: ReviewRecord['verdict'];
+  provider?: string;
+}
+
+export interface ConsensusOptions {
+  stateDir?: string;
+  now?: () => Date;
+  resolveVersion?: (at: string) => Versions;
+  /** 가능하면 다른 LLM 제공자 — 대표별 기본 표식. */
+  providers?: { coordinator?: string; guardian?: string };
+  /** 합의 원장의 agreed 이벤트가 실행 권한 기록이다 — 훅은 기록 뒤에 한 번 돈다. */
+  execute?: (proposal: ProposalCard) => void;
+  ledger?: DecisionLedger;
+}
+
+function oneLine(value: string, name: string): string {
+  const text = (value ?? '').trim().replace(/[\r\n]+/g, ' ');
+  if (!text) throw new Error(`${name} is required`);
+  return text;
+}
+
+/** ISO 8601 주 키 — 합의 원장 «한 주 N건» 집계 단위. */
+function isoWeek(at: string): string {
+  const date = new Date(at);
+  const day = date.getUTCDay() || 7;
+  date.setUTCDate(date.getUTCDate() + 4 - day);
+  const yearStart = Date.UTC(date.getUTCFullYear(), 0, 1);
+  const week = Math.ceil(((date.getTime() - yearStart) / 86400000 + 1) / 7);
+  return `${date.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+export class ConsensusEngine {
+  readonly ledgerPath: string;
+  private readonly stateDir: string;
+  private readonly now: () => Date;
+  private readonly providers: { coordinator?: string; guardian?: string };
+  private readonly executeHook: (proposal: ProposalCard) => void;
+  private readonly ledger: DecisionLedger;
+
+  constructor(options: ConsensusOptions = {}) {
+    this.stateDir = options.stateDir ?? elanousStateRoot();
+    this.ledgerPath = join(this.stateDir, 'consensus', 'consensus.jsonl');
+    this.now = options.now ?? (() => new Date());
+    this.providers = options.providers ?? {};
+    this.executeHook = options.execute ?? (() => {});
+    this.ledger = options.ledger ?? new DecisionLedger({
+      stateDir: options.stateDir, now: options.now, resolveVersion: options.resolveVersion,
+    });
+  }
+
+  /** 대표별 렌즈(입력 원장) 경로 — 두 대표의 렌즈는 서로 분리되어 메아리를 막는다. */
+  lensPath(who: ConsensusRepresentative): string {
+    return join(this.stateDir, 'consensus', 'lens', `${who}.jsonl`);
+  }
+
+  propose(input: {
+    by: ConsensusRepresentative; category: ConsensusCategory; title: string; factId: string; cost: string; undo: string;
+    thresholds?: DecisionCategory[]; provider?: string;
+  }): ProposalCard {
+    if (!CONSENSUS_REPRESENTATIVES.includes(input.by)) throw new Error(`invalid representative: ${input.by} (coordinator|guardian)`);
+    if (!CONSENSUS_CATEGORIES.includes(input.category)) throw new Error(`invalid consensus category: ${input.category} (${CONSENSUS_CATEGORIES.join('|')})`);
+    const thresholds = [...new Set(input.thresholds ?? [])];
+    if (thresholds.some(threshold => !CROWN_THRESHOLD_CATEGORIES.includes(threshold)))
+      throw new Error(`invalid threshold category — ${CROWN_MARK} 몫은 ${CROWN_THRESHOLD_CATEGORIES.join('|')}만`);
+    const at = this.now().toISOString();
+    const provider = input.provider ?? this.providers[input.by];
+    const proposal: ProposalCard = {
+      id: this.nextId('C', at),
+      category: input.category,
+      title: oneLine(input.title, 'title'),
+      factId: oneLine(input.factId, 'fact id'),
+      cost: oneLine(input.cost, 'cost'),
+      undo: oneLine(input.undo, 'undo'),
+      thresholds,
+      proposedBy: input.by,
+      proposedAt: at,
+      status: 'open',
+      roundTrips: 0,
+      reviews: [],
+      ...(provider ? { provider } : {}),
+    };
+    this.append([{ type: 'proposed', proposal }]);
+    this.appendLens(input.by, { action: 'proposed', proposalId: proposal.id, at, ...(provider ? { provider } : {}) });
+    debug.log('loops.consensus', 'proposed', { id: proposal.id, category: proposal.category, by: input.by });
+    return proposal;
+  }
+
+  /** 결론 없이 왕복 하나를 소비하는 검토 — 두 번째 왕복은 결론으로 끝내야 한다. */
+  review(id: string, input: { by: ConsensusRepresentative; claim: string; provider?: string }): ProposalCard {
+    return this.conclude(id, 'revise', input).proposal;
+  }
+
+  /** 합의 — 실행 훅이 돌고 합의 원장에 기록된다. 임계 범주면 대표 카드도 함께 만든다. */
+  agree(id: string, input: { by: ConsensusRepresentative; claim?: string; provider?: string }): { proposal: ProposalCard; crownCard?: CrownCard } {
+    return this.conclude(id, 'agree', input);
+  }
+
+  /** 불합의 — 양쪽 주장 나란히 대표 결정 카드로 간다. */
+  disagree(id: string, input: { by: ConsensusRepresentative; claim: string; provider?: string }): { proposal: ProposalCard; crownCard: CrownCard } {
+    const { proposal, crownCard } = this.conclude(id, 'disagree', input);
+    if (!crownCard) throw new Error(`${CROWN_MARK} 카드 없는 불합의는 없다: ${id}`);
+    return { proposal, crownCard };
+  }
+
+  list(): ProposalCard[] {
+    return [...this.state().proposals.values()]
+      .sort((a, b) => b.proposedAt.localeCompare(a.proposedAt) || a.id.localeCompare(b.id));
+  }
+
+  show(id: string): ProposalCard {
+    const proposal = this.list().find(entry => entry.id === id);
+    if (!proposal) throw new Error(`consensus proposal not found: ${id}`);
+    return proposal;
+  }
+
+  crownCards(): CrownCard[] {
+    return [...this.state().cards]
+      .sort((a, b) => b.raisedAt.localeCompare(a.raisedAt) || a.id.localeCompare(b.id));
+  }
+
+  /** 판정선 — 합의 원장의 agreed 이벤트를 ISO 주 단위로 센다 (한 주 N건의 기전). */
+  weeklyAgreementCounts(): Array<{ week: string; count: number }> {
+    const counts = new Map<string, number>();
+    for (const event of this.events()) {
+      if (event.type !== 'agreed') continue;
+      const week = isoWeek(event.at);
+      counts.set(week, (counts.get(week) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([week, count]) => ({ week, count }));
+  }
+
+  /** 상대 검토 — 검토자는 제안자의 상대여야 하고 왕복은 최대 2다. */
+  private conclude(id: string, verdict: ReviewRecord['verdict'], input: { by: ConsensusRepresentative; claim?: string; provider?: string }): { proposal: ProposalCard; crownCard?: CrownCard } {
+    const proposal = this.show(id);
+    if (proposal.status !== 'open') throw new Error(`합의가 이미 결론났다: ${id} (${proposal.status === 'agreed' ? '합의' : '불합의'})`);
+    if (input.by === proposal.proposedBy) throw new Error('메아리 방지 — 제안한 대표는 자기 제안을 검토하지 않는다');
+    if (verdict === 'revise' && proposal.roundTrips + 1 >= MAX_REVIEW_ROUND_TRIPS)
+      throw new Error(`상대 검토는 최대 ${MAX_REVIEW_ROUND_TRIPS}왕복이다 — 마지막 왕복에는 합의 또는 불합의로 끝낸다`);
+    const claim = oneLine(input.claim ?? (verdict === 'agree' ? '동의 — 제안대로 실행한다' : ''), 'claim');
+    const at = this.now().toISOString();
+    const provider = input.provider ?? this.providers[input.by];
+    const review: ReviewRecord = { by: input.by, at, roundTrip: proposal.roundTrips + 1, verdict, claim, ...(provider ? { provider } : {}) };
+    const events: ConsensusEvent[] = [{ type: 'reviewed', proposalId: proposal.id, review }];
+    if (verdict === 'agree') events.push({ type: 'agreed', proposalId: proposal.id, at, agreedBy: input.by });
+    if (verdict === 'disagree') events.push({ type: 'disagreed', proposalId: proposal.id, at, disagreedBy: input.by });
+    let crownCard: CrownCard | undefined;
+    if (verdict === 'disagree' || (verdict === 'agree' && proposal.thresholds.length > 0)) {
+      crownCard = this.mintCrown(proposal, review, verdict === 'disagree' ? 'disagreement' : 'threshold', at);
+      events.push({ type: 'crown-card', card: crownCard });
+    }
+    this.append(events);
+    this.appendLens(input.by, { action: 'reviewed', proposalId: proposal.id, at, verdict, ...(provider ? { provider } : {}) });
+    debug.log('loops.consensus', 'reviewed', { proposalId: proposal.id, verdict, roundTrip: review.roundTrip, by: input.by });
+    const updated = this.show(proposal.id);
+    if (verdict === 'agree') this.executeHook(updated);
+    return { proposal: updated, ...(crownCard ? { crownCard } : {}) };
+  }
+
+  /** 대표 결정 카드 — 결정 원장에 refs 멱등으로 미러하고 양쪽 주장을 나란히 담는다. */
+  private mintCrown(proposal: ProposalCard, review: ReviewRecord, reason: 'disagreement' | 'threshold', at: string): CrownCard {
+    const proposerClaim = `제안 ${proposal.title} — 사실 ${proposal.factId} · 비용 ${proposal.cost} · 되돌리기 ${proposal.undo}`;
+    const coordinatorClaim = proposal.proposedBy === 'coordinator' ? proposerClaim : review.claim;
+    const guardianClaim = proposal.proposedBy === 'guardian' ? proposerClaim : review.claim;
+    const category = CROWN_THRESHOLD_CATEGORIES.find(threshold => proposal.thresholds.includes(threshold)) ?? 'other';
+    const ref = `consensus:${proposal.id}:crown`;
+    const decision = this.ledger.raiseOnce({
+      title: `${CROWN_MARK} ${reason === 'disagreement' ? '합의 불합의' : '임계 합의 승인'} — ${proposal.title}`,
+      category,
+      scqa: {
+        s: `두 대표 합의 ${categoryLabel(proposal.category)} 제안 ${proposal.id}이 ${reason === 'disagreement' ? '불합의로 끝났다' : '임계 범주 합의에 도달했다'}`,
+        c: reason === 'disagreement' ? '두 대표 주장이 갈린다 — 양쪽 주장이 선택지로 나란히 실렸다' : `두 대표가 합의했으나 ${category} 범주다 — ${CROWN_MARK} 승인이 필요하다`,
+        q: reason === 'disagreement' ? '어느 대표 주장을 따를까?' : `합의된 ${category} 변경을 승인할까?`,
+      },
+      options: [
+        { key: 'a', label: '조율자', consequence: coordinatorClaim },
+        { key: 'b', label: '수호자', consequence: guardianClaim },
+      ],
+      recommendation: { skipped: true, reason: reason === 'disagreement' ? `두 대표 주장이 갈린다 — ${CROWN_MARK} 판단` : `임계 범주 합의 — ${CROWN_MARK} 승인` },
+      raisedBy: { agent: 'consensus' },
+      refs: [ref],
+    }, ref);
+    const card: CrownCard = {
+      id: this.nextId('K', at),
+      proposalId: proposal.id,
+      reason,
+      thresholds: [...proposal.thresholds],
+      coordinatorClaim,
+      guardianClaim,
+      raisedAt: at,
+      decisionId: decision.id,
+    };
+    debug.log('loops.consensus', 'crown-card', { id: card.id, proposalId: proposal.id, reason, decisionId: decision.id });
+    return card;
+  }
+
+  private state(): { proposals: Map<string, ProposalCard>; cards: CrownCard[] } {
+    const proposals = new Map<string, ProposalCard>();
+    const cards: CrownCard[] = [];
+    for (const event of this.events()) {
+      if (event.type === 'proposed') {
+        if (proposals.has(event.proposal.id)) throw new Error(`duplicate consensus proposal: ${event.proposal.id}`);
+        proposals.set(event.proposal.id, { ...event.proposal, reviews: [...event.proposal.reviews] });
+      } else if (event.type === 'crown-card') {
+        cards.push(event.card);
+      } else {
+        const proposal = proposals.get(event.proposalId);
+        if (!proposal) throw new Error(`unknown consensus proposal: ${event.proposalId}`);
+        if (event.type === 'reviewed') {
+          proposal.reviews.push(event.review);
+          proposal.roundTrips = event.review.roundTrip;
+        } else {
+          if (proposal.status !== 'open') throw new Error(`invalid consensus transition: ${event.proposalId}`);
+          proposal.status = event.type === 'agreed' ? 'agreed' : 'disagreed';
+        }
+      }
+    }
+    return { proposals, cards };
+  }
+
+  private events(): ConsensusEvent[] {
+    if (!existsSync(this.ledgerPath)) return [];
+    const text = readFileSync(this.ledgerPath, 'utf8');
+    if (text && !text.endsWith('\n')) throw new Error('incomplete consensus ledger line');
+    return text.split('\n').filter(Boolean).map((line, index) => {
+      try { return JSON.parse(line) as ConsensusEvent; }
+      catch { throw new Error(`invalid consensus ledger event on line ${index + 1}`); }
+    });
+  }
+
+  private nextId(prefix: 'C' | 'K', at: string): string {
+    const day = at.slice(0, 10).replaceAll('-', '');
+    const head = `${prefix}-${day}-`;
+    let next = 1;
+    for (const event of this.events()) {
+      const id = event.type === 'proposed' ? event.proposal.id : event.type === 'crown-card' ? event.card.id : null;
+      if (id?.startsWith(head)) next = Math.max(next, Number(id.slice(head.length)) + 1);
+    }
+    return `${head}${String(next).padStart(2, '0')}`;
+  }
+
+  private append(events: ConsensusEvent[]): void {
+    mkdirSync(dirname(this.ledgerPath), { recursive: true });
+    appendFileSync(this.ledgerPath, `${events.map(event => JSON.stringify(event)).join('\n')}\n`);
+  }
+
+  private appendLens(who: ConsensusRepresentative, event: LensEvent): void {
+    const path = this.lensPath(who);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(event)}\n`);
+  }
+}

package/src/loops/msg-wake.ts

@@ -14,6 +14,11 @@
 //    ⚠️ wake-inject 는 «사람이 치지 않는 pane»(무인 에이전트 전용)에만 둔다 — 사람이 치는 pane 에는 켜지 말 것.
 // ⛔ 깨움은 post 의 성패를 바꾸지 않는다 — 실패·시간 초과는 결과 값으로만 돌아온다.
 // ⛔ 시험 우주에서는 실제 pty/herdr 호출 0 — `ELANOUS_MSG_WAKE_LIVE=1` 로만 연다(격리 실물 시험용).
+// ⭐ 버리지 않고 미룬다(TUI-H4 · 10-16 OPT 우편 36 중 18 깨움 0): pty-inject 대상이 턴 중(busy)이거나 5분 창(debounced)이라
+//    못 두드린 글은 `pending_wakes` 에 «주소당 한 줄»로 접어 두고, 그 TUI 안의 폴러(`startPendingWakePoller`)가
+//    턴이 idle 로 «기록»된 뒤 한 번 다시 두드린다. 5분 창은 다시 두드림에도 걸린다 — 창 안이면 버림이 아니라 다음 틱으로 미룸.
+//    상한(시도 3 · 2시간) → `gave-up`. 관측 = `loops.msg-wake` deferred | redelivered | gave-up.
+//    재두드림 «전»에 그 주소 미읽음을 잰다 — 0 이면 두드리지 않고 줄을 지운다(`dropped-read` · H4-FOLLOW ③).
 
 import { spawn } from 'node:child_process';
 import { Database } from 'bun:sqlite';
@@ -24,11 +29,17 @@ import { dirname, join } from 'node:path';
 
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
+import { readUnreadCount } from '../msg/msg-store.js';
 import { listPtyManifestRows } from '../pty-shell/pty-manifest.js';
 import { messageRouteFor, type MessageWake } from './msg-address.js';
 
 export const WAKE_DEBOUNCE_MS = 5 * 60_000;
 export const WAKE_TIMEOUT_MS = 3_000;
+/** A deferred wake is retried at most this many times (an attempt = idle ∧ window free ∧ injection tried). */
+export const MAX_REDELIVER_ATTEMPTS = 3;
+/** A deferred wake older than this is given up even if the TUI never went idle. */
+export const PENDING_WAKE_TTL_MS = 2 * 60 * 60_000;
+export const PENDING_WAKE_POLL_MS = 15_000;
 /** Seat-folder file that opts a human pane in to wake injection (presence is the switch). */
 const WAKE_OPT_IN_FILE = 'wake-inject';
 
@@ -67,6 +78,8 @@ export interface WakeDeps {
   herdrStatus?: (paneId: string, signal: AbortSignal) => Promise<string>;
   herdrInject?: (paneId: string, line: string, signal: AbortSignal) => Promise<void>;
   warn?: (line: string) => void;
+  /** Unread count for an address before a deferred re-knock (H4-FOLLOW ③). null = «모름» (never drops). Default: the msg ledger. */
+  readUnread?: (address: string) => number | null;
 }
 
 function isLive(deps: WakeDeps): boolean {
@@ -127,18 +140,28 @@ function claimDbPath(deps: WakeDeps): string {
 
 interface WakeClaim { db: string; address: string; token: string }
 
+function openWakeDb(db: string): Database {
+  mkdirSync(dirname(db), { recursive: true });
+  const conn = new Database(db);
+  try {
+    conn.exec('PRAGMA busy_timeout = 2000');
+    conn.exec('CREATE TABLE IF NOT EXISTS wake_claims (address TEXT PRIMARY KEY, at INTEGER NOT NULL, token TEXT NOT NULL)');
+    conn.exec(`CREATE TABLE IF NOT EXISTS pending_wakes (address TEXT PRIMARY KEY, first_msg_id INTEGER NOT NULL,
+      last_msg_id INTEGER NOT NULL, last_from TEXT NOT NULL, count INTEGER NOT NULL, since INTEGER NOT NULL,
+      attempts INTEGER NOT NULL DEFAULT 0, reason TEXT NOT NULL)`);
+    return conn;
+  } catch (error) { conn.close(); throw error; }
+}
+
 /**
  * Atomically claim the 5-minute wake window for one address. One SQLite upsert decides it under the
  * write lock — the row is replaced only when the held claim is older than the window — so two
  * concurrent `msg post` processes cannot both win, including when both saw an expired claim.
  */
 export function claimWake(db: string, address: string, now: number): WakeClaim | null {
-  mkdirSync(dirname(db), { recursive: true });
   const token = `${now} ${process.pid} ${randomUUID()}`;
-  const conn = new Database(db);
+  const conn = openWakeDb(db);
   try {
-    conn.exec('PRAGMA busy_timeout = 2000');
-    conn.exec('CREATE TABLE IF NOT EXISTS wake_claims (address TEXT PRIMARY KEY, at INTEGER NOT NULL, token TEXT NOT NULL)');
     const changed = conn.query(`INSERT INTO wake_claims (address, at, token) VALUES (?1, ?2, ?3)
       ON CONFLICT(address) DO UPDATE SET at = excluded.at, token = excluded.token WHERE wake_claims.at <= ?2 - ?4`)
       .run(address, now, token, WAKE_DEBOUNCE_MS).changes;
@@ -278,5 +301,184 @@ export async function wakeRecipient(address: string, msgId: number, message: { f
     debug.log('msg.wake', outcome.result === 'skipped' ? 'skipped' : outcome.wake, { address, msgId, wake: outcome.wake, result: outcome.result, reason: outcome.reason ?? outcome.source,
       ...(outcome.target ? { target: outcome.target } : {}) });
   } catch { /* reporting never turns a wake outcome into a throw */ }
+  try { settlePending(outcome, message.from, deps); } catch { /* the deferral ledger never turns a post into a throw */ }
   return outcome;
 }
+
+// ── 미룬 깨움(pending) ─────────────────────────────────────────────────────────
+
+interface PendingWakeRow { address: string; first_msg_id: number; last_msg_id: number; last_from: string; count: number; since: number; attempts: number; reason: string }
+
+export type PendingWakeEvent = 'deferred' | 'redelivered' | 'gave-up' | 'dropped-read';
+
+function logPending(event: PendingWakeEvent, data: Record<string, unknown>): void {
+  try { debug.log('loops.msg-wake', event, data); } catch { /* observability is fail-open */ }
+}
+
+/**
+ * After a fresh wake: a pty-inject TUI that was busy or inside the 5-minute window is remembered (not dropped);
+ * an injected wake absorbs whatever was pending for that address (the line tells the reader to list everything).
+ */
+function settlePending(outcome: WakeOutcome, from: string, deps: WakeDeps): void {
+  if (!isLive(deps)) return;
+  // TTL 은 폴러 «밖»에서도 닫는다 — TUI 가 죽은 채 안 돌아오면 그 폴러는 없다. 어느 주소든 post 가 오면 낡은 줄을 거둔다.
+  try { prunePendingWakes(deps); } catch { /* fail-soft */ }
+  if (outcome.wake !== 'pty-inject') return;
+  const address = outcome.address.trim().toUpperCase();
+  if (outcome.result === 'injected') {
+    // 이 줄은 «그때까지 저장된 글 전부를 읽어라»라 msgId 이하만 덮는다 — 주입 «뒤»에 저장·미뤄진 글(더 큰 id)이 섞인 줄은 남긴다.
+    const conn = openWakeDb(claimDbPath(deps));
+    try { conn.query('DELETE FROM pending_wakes WHERE address = ?1 AND last_msg_id <= ?2').run(address, outcome.msgId); } finally { conn.close(); }
+    return;
+  }
+  if (outcome.result !== 'busy' && outcome.result !== 'debounced') return;
+  const reason = outcome.result === 'debounced' ? 'debounced' : outcome.reason ?? 'busy';
+  const conn = openWakeDb(claimDbPath(deps));
+  let count = 1;
+  try {
+    // 주소당 한 줄 — 묶음이 늘어도 다시 두드림은 한 번. 범위는 id 순서로(동시 post 가 역순으로 와도 min·max),
+    // 보낸 이는 끝 id 의 것. 끝 id 가 바뀌면(새 글) 시도 수는 0 — 새 글은 자기 몫의 시도를 받는다. 시작 시각(TTL)은 첫 미룸 기준.
+    conn.query(`INSERT INTO pending_wakes (address, first_msg_id, last_msg_id, last_from, count, since, attempts, reason)
+      VALUES (?1, ?2, ?2, ?3, 1, ?4, 0, ?5)
+      ON CONFLICT(address) DO UPDATE SET first_msg_id = min(first_msg_id, excluded.first_msg_id),
+        last_msg_id = max(last_msg_id, excluded.last_msg_id),
+        last_from = CASE WHEN excluded.last_msg_id > last_msg_id THEN excluded.last_from ELSE last_from END,
+        attempts = CASE WHEN excluded.last_msg_id > last_msg_id THEN 0 ELSE attempts END,
+        count = count + 1, reason = excluded.reason`)
+      .run(address, outcome.msgId, from, (deps.now ?? Date.now)(), reason);
+    count = (conn.query('SELECT count FROM pending_wakes WHERE address = ?1').get(address) as { count: number } | null)?.count ?? 1;
+  } finally { conn.close(); }
+  logPending('deferred', { seat: address, count, reason, msgId: outcome.msgId });
+}
+
+function logGaveUp(row: PendingWakeRow, reason: string, attempts = row.attempts): void {
+  logPending('gave-up', { seat: row.address, count: row.count, reason, attempts, firstMsgId: row.first_msg_id, lastMsgId: row.last_msg_id });
+}
+
+/** Give up deferrals older than the TTL (a TUI that died and never came back has no poller to do it). */
+export function prunePendingWakes(deps: WakeDeps = {}): number {
+  const db = claimDbPath(deps);
+  if (!existsSync(db)) return 0;
+  const cutoff = (deps.now ?? Date.now)() - PENDING_WAKE_TTL_MS;
+  const conn = openWakeDb(db);
+  try {
+    const stale = conn.query('SELECT * FROM pending_wakes WHERE since < ?1').all(cutoff) as PendingWakeRow[];
+    for (const row of stale) {
+      if (conn.query('DELETE FROM pending_wakes WHERE address = ?1 AND last_msg_id = ?2').run(row.address, row.last_msg_id).changes === 1) logGaveUp(row, 'ttl');
+    }
+    return stale.length;
+  } finally { conn.close(); }
+}
+
+export interface RedeliverOutcome { seat: string; result: 'redelivered' | 'gave-up' | 'dropped-read' | 'waiting' | 'failed'; count: number; reason?: string }
+
+/** Unread count for a deferred address — injected reader first, else the msg ledger beside the claims db. Never throws. */
+function readUnreadFor(address: string, deps: WakeDeps): number | null {
+  try {
+    if (deps.readUnread) return deps.readUnread(address);
+    return readUnreadCount(address, join(deps.stateRoot ?? effectiveInstanceRoot(), 'msg', 'messages.db'));
+  } catch { return null; }
+}
+
+export function redeliverLine(row: Pick<PendingWakeRow, 'address' | 'last_from' | 'first_msg_id' | 'last_msg_id' | 'count'>): string {
+  const ids = row.first_msg_id === row.last_msg_id ? `#${row.last_msg_id}` : `#${row.first_msg_id}..#${row.last_msg_id}`;
+  return `[우편 깨움 · 미룬 ${row.count}통] ${row.last_from} → ${row.address} ${ids} — eln msg list --to ${row.address} 로 읽고 처리`;
+}
+
+/**
+ * Re-knock deferred wakes whose TUI is now recorded idle. `target` limits the sweep to one pty (the TUI's own poller).
+ * Never throws per row; a row stays pending while the TUI is busy or the 5-minute window is held.
+ */
+export async function redeliverPendingWakes(deps: WakeDeps = {}, opts: { target?: string } = {}): Promise<RedeliverOutcome[]> {
+  if (!isLive(deps)) return [];
+  const db = claimDbPath(deps);
+  if (!existsSync(db)) return [];
+  const conn = openWakeDb(db);
+  let rows: PendingWakeRow[];
+  try { rows = conn.query('SELECT * FROM pending_wakes ORDER BY since').all() as PendingWakeRow[]; } finally { conn.close(); }
+  const results: RedeliverOutcome[] = [];
+  const now = () => (deps.now ?? Date.now)();
+  // 지울 때는 «읽은 그 묶음»만 — 그 사이 새로 미룬 글이 오면 줄이 남아 한 번 더 두드린다.
+  const drop = (row: PendingWakeRow): boolean => {
+    const c = openWakeDb(db);
+    try { return c.query('DELETE FROM pending_wakes WHERE address = ?1 AND last_msg_id = ?2').run(row.address, row.last_msg_id).changes === 1; }
+    finally { c.close(); }
+  };
+  // 포기는 «실제로 지운» 묶음만 — 그 사이 새 글이 합쳐졌으면(끝 id 바뀜) 줄은 새 묶음으로 남고 시도 수는 0 으로 돌아가 있다.
+  const giveUp = (row: PendingWakeRow, reason: string) => {
+    if (drop(row)) {
+      logGaveUp(row, reason);
+      results.push({ seat: row.address, result: 'gave-up', count: row.count, reason });
+    } else results.push({ seat: row.address, result: 'waiting', count: row.count, reason: 'batch-changed' });
+  };
+  for (const row of rows) {
+    try {
+      if (row.attempts >= MAX_REDELIVER_ATTEMPTS) { giveUp(row, `attempts>=${MAX_REDELIVER_ATTEMPTS}`); continue; }
+      if (now() - row.since > PENDING_WAKE_TTL_MS) { giveUp(row, 'ttl'); continue; }
+      // H4-FOLLOW ③ — 그 사이 이미 읽었으면(미읽음 0) 재두드림하지 않고 줄을 지운다(10-16 OPT 가 ack 한 #9250 재두드림).
+      //   «모름»(원장 없음·못 읽음)은 지우지 않는다 — 0 으로 읽지 않는다.
+      const unread = readUnreadFor(row.address, deps);
+      if (unread === 0) {
+        if (drop(row)) {
+          logPending('dropped-read', { seat: row.address, count: row.count, attempts: row.attempts, firstMsgId: row.first_msg_id, lastMsgId: row.last_msg_id });
+          results.push({ seat: row.address, result: 'dropped-read', count: row.count });
+        } else results.push({ seat: row.address, result: 'waiting', count: row.count, reason: 'batch-changed' });
+        continue;
+      }
+      const resolution = resolveWake(row.address, deps);
+      if (resolution.optIn === false) { giveUp(row, 'human-pane-no-opt-in'); continue; }
+      // TUI 가 없거나(재기동 중) 다른 pty 의 몫이면 이번 틱은 건너뛴다 — 수명은 TTL 이 닫는다.
+      if (resolution.wake !== 'pty-inject' || !resolution.target) continue;
+      if (opts.target !== undefined && resolution.target !== opts.target) continue;
+      const tui = (deps.listPtys ?? listPtyManifestRows)().find(item => item.id === resolution.target);
+      if (!tui?.alive || tui.turnState !== 'idle') { results.push({ seat: row.address, result: 'waiting', count: row.count, reason: `turn=${tui?.turnState ?? 'unknown'}` }); continue; }
+      const claim = claimWake(db, row.address, now());
+      // 5분 창 안 — 버림이 아니라 미룸: 줄은 그대로, 다음 틱.
+      if (!claim) { results.push({ seat: row.address, result: 'waiting', count: row.count, reason: 'debounced' }); continue; }
+      const c = openWakeDb(db);
+      try { c.query('UPDATE pending_wakes SET attempts = attempts + 1 WHERE address = ?1 AND last_msg_id = ?2').run(row.address, row.last_msg_id); } finally { c.close(); }
+      let injected = false;
+      try {
+        const inject = await (deps.ptyInjector ?? defaultPtyInjector)();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        await Promise.race([inject(resolution.target, redeliverLine(row)), new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error('timeout')), deps.timeoutMs ?? WAKE_TIMEOUT_MS);
+        })]).finally(() => clearTimeout(timer));
+        injected = true;
+      } catch (error) {
+        releaseClaim(claim);
+        const reason = error instanceof Error ? error.message : String(error);
+        // 상한에 닿은 실패는 그 자리에서 닫는다 — 다음 틱을 기다리지 않는다.
+        if (row.attempts + 1 >= MAX_REDELIVER_ATTEMPTS) giveUp({ ...row, attempts: row.attempts + 1 }, `attempts>=${MAX_REDELIVER_ATTEMPTS}:${reason}`);
+        else {
+          logPending('deferred', { seat: row.address, count: row.count, reason: `inject-failed:${reason}`, attempts: row.attempts + 1 });
+          results.push({ seat: row.address, result: 'failed', count: row.count, reason });
+        }
+      }
+      if (injected) {
+        drop(row);
+        logPending('redelivered', { seat: row.address, count: row.count, reason: row.reason, attempts: row.attempts + 1, target: resolution.target, firstMsgId: row.first_msg_id, lastMsgId: row.last_msg_id });
+        results.push({ seat: row.address, result: 'redelivered', count: row.count });
+      }
+    } catch (error) {
+      results.push({ seat: row.address, result: 'failed', count: row.count, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return results;
+}
+
+/**
+ * The TUI's own poller: every tick, re-knock wakes deferred for this pty once its turn is recorded idle.
+ * Reuses the manifest `turn_state` the TUI already writes (#27485) — no new IPC. Unref'd; never throws.
+ */
+export function startPendingWakePoller(surfaceId: string, deps: WakeDeps = {}, intervalMs = PENDING_WAKE_POLL_MS): () => void {
+  let inFlight = false;
+  const tick = () => {
+    if (inFlight) return;
+    inFlight = true;
+    void redeliverPendingWakes(deps, { target: surfaceId }).catch(() => []).finally(() => { inFlight = false; });
+  };
+  const timer = setInterval(tick, intervalMs);
+  (timer as { unref?: () => void }).unref?.();
+  return () => clearInterval(timer);
+}

package/src/loops/observe.ts

@@ -28,7 +28,18 @@ export function loopCategory(id: string): string {
   return `loop.${id}`;
 }
 
-/** Emit an RFC loop event, retaining absent context as a measurable list. */
+/** Collapse whitespace runs so a value stays on a single line. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Emit an RFC loop event, retaining absent context as a measurable list. The approval
+ * observation ('hitl') settles the «왜 한 줄 ⊕ 근거 포인터» convention at this boundary:
+ * reason and sourceRef are collapsed onto a copy as single-line strings, so every approval
+ * emission carries a one-line why and evidence pointer without mutating caller data or
+ * fabricating fields REQUIRED_CONTEXT reports as missing.
+ */
 export function loopEvent(loopId: string, event: string, data: Record<string, unknown>): void {
   if (!validId(loopId)) {
     reject('invalid-loop-id');
@@ -44,9 +55,14 @@ export function loopEvent(loopId: string, event: string, data: Record<string, un
     reject('invalid-data');
     return;
   }
+  const payload: Record<string, unknown> = { ...data };
+  if (event === 'hitl') {
+    if (typeof payload.reason === 'string') payload.reason = oneLine(payload.reason);
+    if (typeof payload.sourceRef === 'string') payload.sourceRef = oneLine(payload.sourceRef);
+  }
   const missingRequired = REQUIRED_CONTEXT.filter(field =>
-    typeof data[field] !== 'string' || !(data[field] as string).trim());
-  debug.log(`loop.${loopId}`, event, { ...data, loopId, missingRequired });
+    typeof payload[field] !== 'string' || !(payload[field] as string).trim());
+  debug.log(`loop.${loopId}`, event, { ...payload, loopId, missingRequired });
   if (event === 'tick' && (data.outcome === 'failed' || data.status === 'failed')) {
     try {
       recordFailureEvent({ source: 'loop-tick', kind: event, ref: loopId,