elanous 0.2.27 → 0.2.28

package/src/budget/llm-cost.ts

@@ -303,7 +303,19 @@ export function estimateLlmCost(
 
 /** Discriminated cost fields to spread onto an `llm.usage` observation. */
 /** 과금 경로(BACKLOG C6 · hermes `resolve_billing_route`). 구독(OAuth)·local 은 «토큰당 청구가 없다». */
-export type BillingRoute = 'subscription' | 'local' | 'api' | 'unknown';
+export type BillingRoute = 'subscription' | 'local' | 'credit' | 'api' | 'unknown';
+
+/** Credit is known only when the quota window is exhausted and credits are present. */
+export function creditRouteFromQuotaSignal(signal: {
+  usedPercent?: number | null;
+  rateLimitReached?: boolean | null;
+  hasCredits?: boolean | null;
+} | null): 'credit' | null {
+  if (!signal || signal.hasCredits !== true) return null;
+  const exhausted = signal.rateLimitReached === true
+    || (typeof signal.usedPercent === 'number' && Number.isFinite(signal.usedPercent) && signal.usedPercent >= 100);
+  return exhausted ? 'credit' : null;
+}
 
 /** 구독·local 호출의 비용 — 청구 0 이지만 «API 로 샀다면」 값은 따로 남긴다(환산가 · 모르면 칸이 없다). */
 /** provider 가 보고한 실제 청구액(OpenRouter `usage.cost`) — 카탈로그 추정과 다르면 이것이 맞다. */
@@ -323,14 +335,25 @@ export interface IncludedLlmCost {
   apiEquivalentUsd?: number;
 }
 
+export interface CreditLlmCost {
+  kind: 'credit';
+  model: string;
+  usd: null;
+  apiEquivalentUsd?: number;
+}
+
 export function llmUsageCostFields(
   model: string,
   usage: Omit<LlmCostUsage, 'model'>,
   opts?: EstimateLlmCostOptions,
   billing?: BillingRoute,
-): { cost: LlmCostEstimate | IncludedLlmCost | ActualLlmCost | ByokActualCost | ByokPartialCost } {
+): { cost: LlmCostEstimate | IncludedLlmCost | CreditLlmCost | ActualLlmCost | ByokActualCost | ByokPartialCost } {
   const resolved = opts ?? { configPricing: readLlmConfigPricing() };
   const estimate = estimateLlmCost({ model, ...usage }, resolved);
+  // An explicit credit route owns this cost row; API/BYOK amounts belong to other routes.
+  if (billing === 'credit') {
+    return { cost: { kind: 'credit', model, usd: null, ...(estimate.kind === 'known' || estimate.kind === 'partial' ? { apiEquivalentUsd: estimate.usd } : {}) } };
+  }
   // ⛔⭐ 구독을 API 단가로 «known» 이라 적지 않는다 — 09-25 벤치에서 codex 구독 팔이 `$7.81 known` 으로 보였다.
   // ⭐ BACKLOG C7 — provider 가 실어 보낸 «실제 청구액»이 있으면 그것이 비용이다(추정은 곁에 남긴다).
   // OR-BYOK-COST — BYOK 면 «OR 청구 + 상류 청구»가 비용이다(상류를 모르면 partial · 0 으로 가정하지 않는다).

package/src/budget/usage-outcomes.ts

@@ -33,6 +33,14 @@ export interface UsageOutcomesReport {
   readonly unreadableLedgers: number;
 }
 
+export interface AutoLandRatioRow {
+  readonly selfLanded: number;
+  readonly handMerges: number | null;
+  readonly totalMerges: number | null;
+  readonly autoLandRatio: number | null;
+  readonly blockReasons: Readonly<Record<string, number>>;
+}
+
 export interface UsageOutcomesDeps {
   readonly dir?: string;
   readonly nowMs?: number;
@@ -139,6 +147,30 @@ export function aggregateUsageOutcomes(
   return { sinceDays, sinceMs, rows, unreadableLedgers };
 }
 
+/** Join the existing run-ledger aggregate with an externally measured hand-merge count. */
+export function measureAutoLandRatio(report: UsageOutcomesReport, handMerges: number | null): AutoLandRatioRow {
+  const selfLanded = report.rows.reduce((sum, row) => sum + row.landed, 0);
+  const hand = handMerges !== null && Number.isSafeInteger(handMerges) && handMerges >= 0 ? handMerges : null;
+  const sum = hand === null ? null : selfLanded + hand;
+  // An empty report also represents a missing ledger directory; do not turn that into 0%.
+  const totalMerges = report.rows.length === 0 || report.unreadableLedgers > 0 || sum === null || !Number.isSafeInteger(sum) ? null : sum;
+  const autoLandRatio = totalMerges === null || totalMerges === 0 ? null : selfLanded / totalMerges;
+  const reasons = new Map<string, number>();
+  for (const row of report.rows) {
+    for (const [reason, count] of Object.entries(row.blockReasons)) {
+      reasons.set(reason, (reasons.get(reason) ?? 0) + count);
+    }
+  }
+  const blockReasons = Object.fromEntries([...reasons].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))) as Record<string, number>;
+  return { selfLanded, handMerges: hand, totalMerges, autoLandRatio, blockReasons };
+}
+
+export function formatAutoLandRatio(row: AutoLandRatioRow): string {
+  const ratio = row.autoLandRatio === null ? '-' : `${Math.round(row.autoLandRatio * 1000) / 10}%`;
+  const reasons = Object.entries(row.blockReasons).map(([reason, count]) => `${reason}=${count}`).join(',') || '-';
+  return `자율 착지 ${row.selfLanded} / 전체 ${row.totalMerges ?? '-'} (${ratio}) · 손 착지 ${row.handMerges ?? '-'} · 멈춤 사유 ${reasons}`;
+}
+
 export function queryUsageOutcomes(sinceDays: number, deps: UsageOutcomesDeps = {}): UsageOutcomesReport {
   const days = Number.isFinite(sinceDays) && sinceDays > 0 ? sinceDays : 2;
   const nowMs = deps.nowMs ?? Date.now();

package/src/claims/claims-ledger.ts

@@ -3,6 +3,7 @@ import { chmodSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { debug } from '../debug/log.js';
+import type { PatentCandidate, PatentLedger } from '../patents/ledger.js';
 
 export type ClaimStatus = 'draft' | 'verified' | 'public' | 'stale' | 'retracted';
 
@@ -41,6 +42,19 @@ function iso(value: string, field: string): string {
   return date.toISOString();
 }
 
+function patentClaimRow(candidate: PatentCandidate, owner: string, audience: string): ClaimRow {
+  return {
+    id: candidate.id,
+    claim: candidate.title,
+    audience,
+    status: 'public',
+    owner,
+    contrast: null,
+    created_at: candidate.created_at,
+    updated_at: candidate.updated_at,
+  };
+}
+
 export class ClaimsLedger {
   readonly path: string;
   private readonly now: () => Date;
@@ -229,4 +243,13 @@ export class ClaimsLedger {
       };
     }));
   }
+
+  /** 특허 원장의 공개 허용 상태 후보만 읽어 공개 주장 행으로 내온다 — 조사·명세·출원 상태 후보는 공개 주장으로 나오지 않는다. */
+  patentClaims(patents: PatentLedger, options: { owner: string; audience: string }): ClaimRow[] {
+    const owner = required(options.owner, 'owner');
+    const audience = required(options.audience, 'audience');
+    const rows = patents.listPublicCandidates().map(candidate => patentClaimRow(candidate, owner, audience));
+    debug.log('claims.ledger', 'patent-claims', { count: rows.length });
+    return rows;
+  }
 }

package/src/claims/claims-render.ts

@@ -6,6 +6,7 @@ import { BRAND_RULES_UNMEASURED, checkBrand } from '../../scripts/brand/check.js
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import type { ClaimsLedger, ClaimEvidence } from './claims-ledger.js';
+import type { PatentLedger } from '../patents/ledger.js';
 
 export type ClaimSurface = 'deck' | 'site' | 'notice';
 export interface RenderedClaims {
@@ -49,12 +50,14 @@ export function representativeNumber(value: string): string | undefined {
   return matches[0];
 }
 
-export function renderClaims(ledger: ClaimsLedger, options: { surface: ClaimSurface; audience?: string; rulesPath?: string }): RenderedClaims {
+export function renderClaims(ledger: ClaimsLedger, options: { surface: ClaimSurface; audience?: string; rulesPath?: string; patents?: { ledger: PatentLedger; owner: string; audience: string } }): RenderedClaims {
   const { surface, audience } = options;
   if (!(surface in headings)) throw new Error(`invalid claims surface: ${surface}`);
   const excluded: RenderedClaims['excluded'] = [];
   const candidates: Array<{ id: string; line: string }> = [];
-  for (const row of ledger.list()) {
+  const rows = ledger.list();
+  const known = new Set(rows.map(row => row.id));
+  for (const row of rows) {
     if (audience && !row.audience.split(',').includes(audience)) continue;
     if (row.status !== 'public') {
       excluded.push({ id: row.id, reason: row.status === 'stale' ? 'stale' : row.status === 'retracted' ? 'retracted' : 'not-public' });
@@ -83,6 +86,23 @@ export function renderClaims(ledger: ClaimsLedger, options: { surface: ClaimSurf
     candidates.push({ id: row.id, line: `- ${claim} — ${number} <!-- claim:${row.id} measured:${evidence.measured_at} cmd:${commentValue(evidence.command)}${evidence.source ? ` source:${commentValue(evidence.source)}` : ''} --> <!-- src:${commentValue(evidence.source ?? evidence.command)} -->` });
   }
 
+  // 공개 허용 상태는 렌더 시점에 특허 원장에서 읽는다. 임의의 ClaimRow 배열은 받지 않는다.
+  // 저장된 주장과 같은 식별자를 가진 유도 행은 원장 행이 이긴다.
+  for (const row of options.patents ? ledger.patentClaims(options.patents.ledger, options.patents) : []) {
+    if (known.has(row.id)) continue;
+    if (audience && !row.audience.split(',').includes(audience)) continue;
+    if (row.status !== 'public') {
+      excluded.push({ id: row.id, reason: 'not-public' });
+      continue;
+    }
+    const patentClaim = firstSentence(row.claim);
+    if (!patentClaim) {
+      excluded.push({ id: row.id, reason: 'brand' });
+      continue;
+    }
+    candidates.push({ id: row.id, line: `- ${patentClaim} <!-- claim:${row.id} patent --> <!-- src:patents -->` });
+  }
+
   const rulesMissing = checkBrand(scopes[surface], [], options.rulesPath).missing;
   if (rulesMissing) {
     excluded.push(...candidates.map(({ id }) => ({ id, reason: 'rules-missing' as const })));

package/src/cli/brief-cli.ts

@@ -1,9 +1,97 @@
 import type { Command } from 'commander';
 import { BRIEF_DOMAINS, BRIEF_PRIORITIES, BRIEF_REACTIONS, BRIEF_SLOTS, BriefItemsInputError, BriefItemsLedger, type BriefDomain, type BriefPriority, type BriefReaction, type BriefSendSlot } from '../briefing/brief-items.js';
 import { kindRouteTarget } from '../domains/telegram-kind-route.js';
-import { sendTelegramReturningId } from '../autopilot/mission-notify.js';
+import { sendTelegramButtonsTo, type TgButton } from '../autopilot/mission-notify.js';
 import { getUserConfig } from '../user-config.js';
 
+export function briefFeedbackButtons(ids: readonly number[]): TgButton[][] {
+  return ids.map(id => [
+    { text: `👀 ${id} 읽음`, data: `brief-item:${id}:read` },
+    { text: `✅ ${id} 움직임`, data: `brief-item:${id}:button` },
+    { text: `➖ ${id} 넘김`, data: `brief-item:${id}:ignore` },
+  ]);
+}
+
+export interface BriefTelegramUpdate {
+  botId: string;
+  chatId: number;
+  messageId: number;
+  updateId: string;
+  text?: string;
+  callbackData?: string;
+}
+
+export function recordBriefTelegramUpdate(ledger: BriefItemsLedger, update: BriefTelegramUpdate): boolean {
+  if (update.callbackData !== undefined) {
+    const match = /^brief-item:([1-9]\d*):(read|button|ignore)$/.exec(update.callbackData);
+    if (!match) return false;
+    return ledger.recordTelegramFeedback({ botId: update.botId, chatId: update.chatId,
+      messageId: update.messageId, updateId: update.updateId, itemId: Number(match[1]),
+      reaction: match[2] === 'read' ? '열람' : match[2] === 'ignore' ? '무시' : '버튼' });
+  }
+  if (!update.text?.trim()) return false;
+  const text = update.text.trim();
+  const itemId = /^(?:#|항목\s*)([1-9]\d*)(?=\s|[:：]|$)/.exec(text)?.[1];
+  return ledger.recordTelegramFeedback({ botId: update.botId, chatId: update.chatId,
+    messageId: update.messageId, updateId: update.updateId,
+    ...(itemId ? { itemId: Number(itemId) } : {}),
+    reaction: /그게 아니라|(?:^|\s)정정\s*[:：]/.test(text) ? '정정' : '답장' });
+}
+
+/** Prefix each item line with `#<id>` so the 대표 can name the reply target ("#12 답장", "#12 그게 아니라 …"). */
+function withItemNumbers(text: string, itemLines: ReadonlyMap<string, readonly number[]>): string {
+  const linePositions = new Map<string, number>();
+  return text.split('\n').map(line => {
+    const ids = itemLines.get(line);
+    if (!ids) return line;
+    const position = linePositions.get(line) ?? 0;
+    linePositions.set(line, position + 1);
+    const itemId = ids[position];
+    return itemId === undefined ? line : `#${itemId} ${line}`;
+  }).join('\n');
+}
+
+/** Split only feedback-enabled pages; each Telegram message gets its own real item coordinate.
+ * Item lines carry their `#<id>` so a plain text reply can name its target item.
+ */
+function briefDeliveryParts(markdown: string, itemLines: ReadonlyMap<string, readonly number[]>): Array<{ text: string; itemId: number }> {
+  const parts: Array<{ text: string; itemId: number }> = [];
+  const linePositions = new Map<string, number>();
+  let pending = '';
+  for (const line of markdown.trimEnd().split('\n')) {
+    const ids = itemLines.get(line);
+    const position = linePositions.get(line) ?? 0;
+    const itemId = ids?.[position];
+    if (itemId === undefined) {
+      pending += `${line}\n`;
+      continue;
+    }
+    linePositions.set(line, position + 1);
+    const numbered = `#${itemId} ${line}`;
+    // Leave room for the Telegram sender's newline and keep a button on every fragment.
+    while (pending.length >= 3800) {
+      parts.push({ text: pending.slice(0, 3800), itemId });
+      pending = pending.slice(3800);
+    }
+    let remainder = pending + numbered;
+    do {
+      parts.push({ text: remainder.slice(0, 3800), itemId });
+      remainder = remainder.slice(3800);
+    } while (remainder.length);
+    pending = '';
+  }
+  if (pending && parts.length) {
+    const last = parts[parts.length - 1]!;
+    if (last.text.length + pending.length <= 3800) last.text += pending;
+    else {
+      const room = 3800 - last.text.length;
+      last.text += pending.slice(0, room);
+      for (let i = room; i < pending.length; i += 3800) parts.push({ text: pending.slice(i, i + 3800), itemId: last.itemId });
+    }
+  }
+  return parts;
+}
+
 export interface BriefCliDeps {
   ledger?: BriefItemsLedger;
   stateDir?: string;
@@ -11,6 +99,10 @@ export interface BriefCliDeps {
   output?: (line: string) => void;
   error?: (line: string) => void;
   send?: (markdown: string) => number | null;
+  /** Test seam for the Telegram button sender (one actual message per invocation). */
+  sendWithButtons?: (text: string, buttons: TgButton[][]) => number | null;
+  /** Allows an injected sender to exercise the same Telegram attribution as the real sender. */
+  telegramTarget?: { botToken: string; chatId: number };
 }
 
 export function registerBriefCommands(program: Command, deps: BriefCliDeps = {}): void {
@@ -31,18 +123,47 @@ export function registerBriefCommands(program: Command, deps: BriefCliDeps = {})
         output(`이번 주 브리핑 중 대표가 움직인 것 ${acted}/${total}`);
       } catch (cause) { fail('', cause); }
     });
-  const deliver = (slot: BriefSendSlot): string => ledger().withSendLock(slot, ({ markdown, ids }, markSent) => {
+  const deliver = (slot: BriefSendSlot): string => ledger().withSendLock(slot, ({ markdown, ids, itemLines }, markSent) => {
     if (ids.length === 0) return '(보낼 항목 없음)';
-    const send = deps.send ?? ((text: string) => {
-      const target = kindRouteTarget(getUserConfig(), 'ops-report');
-      if (!target) return null;
-      return sendTelegramReturningId(target.botToken, target.chatId, text);
-    });
-    const messageId = send(markdown);
-    if (typeof messageId !== 'number' || !Number.isFinite(messageId) || messageId <= 0) {
+    const target = deps.telegramTarget ?? (deps.send ? null : kindRouteTarget(getUserConfig(), 'ops-report'));
+    const numberedMarkdown = withItemNumbers(markdown, itemLines);
+    const oneMessage = numberedMarkdown.length + numberedMarkdown.split('\n').length <= 3900 && ids.length <= 30;
+    const send = (text: string, itemIds: readonly number[]) => deps.sendWithButtons
+      ? deps.sendWithButtons(text, briefFeedbackButtons(itemIds))
+      : deps.send ? deps.send(text)
+      : target ? sendTelegramButtonsTo(target.botToken, target.chatId, text, briefFeedbackButtons(itemIds)) : null;
+    const botId = target ? target.botToken.split(':')[0]! : '';
+    if (target && !oneMessage) {
+      // A sent fragment is not a completed item. Persist only items whose every fragment
+      // succeeded; an incomplete item must remain available to the next send.
+      const parts = briefDeliveryParts(markdown, itemLines);
+      const remainingParts = new Map<number, number>();
+      for (const part of parts) remainingParts.set(part.itemId, (remainingParts.get(part.itemId) ?? 0) + 1);
+      const coordinates: Array<{ botId: string; chatId: number; messageId: number; itemId: number }> = [];
+      let sendThrew = false;
+      let sendCause: unknown;
+      for (const part of parts) {
+        let partMessageId: number | null;
+        try { partMessageId = send(part.text, [part.itemId]); }
+        catch (cause) { sendThrew = true; sendCause = cause; break; }
+        if (typeof partMessageId !== 'number' || !Number.isSafeInteger(partMessageId) || partMessageId <= 0) break;
+        coordinates.push({ botId, chatId: target.chatId, messageId: partMessageId, itemId: part.itemId });
+        remainingParts.set(part.itemId, remainingParts.get(part.itemId)! - 1);
+      }
+      const deliveredIds = [...new Set(coordinates.map(row => row.itemId))].filter(id => remainingParts.get(id) === 0);
+      if (deliveredIds.length > 0) markSent(deliveredIds, slot, coordinates.filter(row => deliveredIds.includes(row.itemId)));
+      if (coordinates.length < parts.length) {
+        if (sendThrew) throw sendCause;
+        throw new Error(`발송 실패: ${deliveredIds.length}/${ids.length} 항목 전송 후 중단 — 나머지는 다음 발송에서 이어진다`);
+      }
+      const lastMessageId = coordinates[coordinates.length - 1]!.messageId;
+      return `sent ${lastMessageId} (${ids.length} items)`;
+    }
+    const messageId = target ? send(numberedMarkdown, ids) : send(markdown, ids);
+    if (typeof messageId !== 'number' || !Number.isSafeInteger(messageId) || messageId <= 0) {
       throw new Error('발송 실패: 양수 메시지 id 없음');
     }
-    markSent(ids, slot);
+    markSent(ids, slot, target ? { botId, chatId: target.chatId, messageId } : undefined);
     return `sent ${messageId} (${ids.length} items)`;
   });
 

package/src/cli/claims-cli.ts

@@ -1,6 +1,7 @@
 import type { Command } from 'commander';
 import { ClaimsInputError, ClaimsLedger, type ClaimsLedgerOptions, type ClaimRow, type ClaimDetail } from '../claims/claims-ledger.js';
 import { renderClaims, queueStaleRechecks, type ClaimSurface } from '../claims/claims-render.js';
+import { PatentLedger, PatentsInputError, type PatentStatus, type PatentTrack } from '../patents/ledger.js';
 
 function actor(explicit?: string): string {
   const by = explicit?.trim() || process.env.AI_AGENT?.trim();
@@ -19,7 +20,7 @@ function handle<Args extends unknown[]>(command: string, action: (...args: Args)
   return (...args) => {
     try { action(...args); }
     catch (error) {
-      if (!(error instanceof ClaimsInputError)) throw error;
+      if (!(error instanceof ClaimsInputError) && !(error instanceof PatentsInputError)) throw error;
       const message = error.message.replace(/\r/g, '\\r').replace(/\n/g, '\\n')
         .replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
       process.stderr.write(`claims ${command}: ${message}\n`);
@@ -41,7 +42,19 @@ function detail(row: ClaimDetail): string {
 export function registerClaimsCommands(program: Command, options: ClaimsLedgerOptions & { instanceRoot?: string } = {}, out: Pick<Console, 'log'> = console): void {
   const root = program.command('claims').description('소구점 · 실측 근거 원장');
   const ledger = () => new ClaimsLedger(options);
+  const patentLedger = () => new PatentLedger(options);
   const emit = (value: unknown, json: boolean | undefined, text: string) => out.log(json ? JSON.stringify(value) : text);
+  const patents = root.command('patents').description('비공개 특허 후보 원장');
+  patents.command('add <id>').requiredOption('--title <title>').requiredOption('--track <track>')
+    .option('--deadline <YYYY-MM-DD>').action(handle('patents add', (id: string, o: { title: string; track: PatentTrack; deadline?: string }) => {
+      const row = patentLedger().add({ id, title: o.title, track: o.track, ...(o.deadline ? { deadline: o.deadline } : {}) });
+      emit(row, false, `${row.id} · ${row.status}`);
+    }));
+  patents.command('status <id>').requiredOption('--status <status>')
+    .action(handle('patents status', (id: string, o: { status: PatentStatus }) => {
+      const row = patentLedger().setStatus(id, o.status);
+      emit(row, false, `${row.id} · ${row.status}`);
+    }));
   root.command('add <id>').requiredOption('--claim <text>').requiredOption('--audience <list>').requiredOption('--owner <seat>')
     .option('--contrast <text>').action(handle('add', (id: string, o: { claim: string; audience: string; owner: string; contrast?: string }) => {
       const row = ledger().add({ id, claim: o.claim, audience: o.audience, owner: o.owner, ...(o.contrast ? { contrast: o.contrast } : {}) });
@@ -79,9 +92,16 @@ export function registerClaimsCommands(program: Command, options: ClaimsLedgerOp
     emit(row, o.json, detail(row));
   }));
   root.command('render').requiredOption('--surface <surface>', 'deck | site | notice')
-    .option('--audience <audience>').option('--json')
-    .action(handle('render', (o: { surface: ClaimSurface; audience?: string; json?: boolean }) => {
-      const result = renderClaims(ledger(), { surface: o.surface, ...(o.audience ? { audience: o.audience } : {}) });
+    .option('--audience <audience>').option('--include-patents', '명시적으로 공개 허용 특허 후보를 포함')
+    .option('--patent-owner <owner>', '특허 후보의 확인된 담당').option('--json')
+    .action(handle('render', (o: { surface: ClaimSurface; audience?: string; includePatents?: boolean; patentOwner?: string; json?: boolean }) => {
+      if (o.includePatents && (!o.patentOwner?.trim() || !o.audience?.trim())) {
+        throw new ClaimsInputError('--include-patents requires --patent-owner and --audience');
+      }
+      if (!o.includePatents && o.patentOwner) throw new ClaimsInputError('--patent-owner requires --include-patents');
+      const patents = o.includePatents
+        ? { ledger: patentLedger(), owner: o.patentOwner!, audience: o.audience! } : undefined;
+      const result = renderClaims(ledger(), { surface: o.surface, ...(o.audience ? { audience: o.audience } : {}), ...(patents ? { patents } : {}) });
       // Review follow-up: rendering is where stale claims surface — queue their re-measurement in the same act.
       const rechecks = result.excluded.some(item => item.reason === 'stale')
         ? queueStaleRechecks(ledger(), { root: options.instanceRoot, now: options.now?.() }) : 0;

package/src/cli/msg-cli.ts

@@ -1,13 +1,18 @@
 import type { Command } from 'commander';
-import { canonicalSeatId, openMsgStore, type Message, type MsgStore } from '../msg/msg-store.js';
+import { ensureAuthToken } from '../auth/acp-token.js';
+import { canonicalSeatId, openMsgStore, openMsgStoreReadOnly, type Message, type MsgStore } from '../msg/msg-store.js';
+import { startMsgSseServer } from '../msg/msg-sse-server.js';
 
 export interface MsgCliDeps {
   openStore?: () => MsgStore;
+  openReadStore?: () => MsgStore;
   out?: Pick<Console, 'log' | 'error'>;
   readStdin?: () => Promise<string>;
   sleep?: (ms: number) => Promise<void>;
   setExitCode?: (code: number) => void;
   signal?: AbortSignal;
+  fetch?: typeof fetch;
+  authToken?: () => string;
 }
 
 type CommonOptions = { json?: boolean };
@@ -33,6 +38,7 @@ function formatMessage(message: Message): string {
 /** Register the durable, recipient-addressed CLI. Reading never advances the acknowledgement cursor. */
 export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): void {
   const open = deps.openStore ?? (() => openMsgStore());
+  const openRead = deps.openReadStore ?? (() => openMsgStoreReadOnly());
   const out = deps.out ?? console;
   const readStdin = deps.readStdin ?? (() => Bun.stdin.text());
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
@@ -58,13 +64,16 @@ export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): vo
 
   msg.command('post [body]').description('Post a message; use - or omit body to read stdin')
     .option('--from <seat>').option('--to <seat>').option('--kind <kind>').option('--body <text>')
+    .option('--reply-to <id>', 'point this reply at a question message ID')
     .option('--origin-key <key>', 'deduplicate a channel mirror by coord:<commentId>:<recipient>').option('--json')
-    .action((body: string | undefined, opts: CommonOptions & { from?: string; to?: string; kind?: string; body?: string; originKey?: string }) => run(async () => {
+    .action((body: string | undefined, opts: CommonOptions & { from?: string; to?: string; kind?: string; body?: string; replyTo?: string; originKey?: string }) => run(async () => {
       const from = seat(opts.from, '--from');
       const to = seat(opts.to, '--to');
       if (body !== undefined && body !== '-' && opts.body !== undefined) throw new Error('provide body once (argument or --body)');
       const text = opts.body ?? (body !== undefined && body !== '-' ? body : await readStdin());
-      const envelope = { from, to, body: text, ...(opts.kind === undefined ? {} : { kind: opts.kind }) };
+      const envelope = { from, to, body: text,
+        ...(opts.kind === undefined ? {} : { kind: opts.kind }),
+        ...(opts.replyTo === undefined ? {} : { replyTo: integer(opts.replyTo, '--reply-to', 0, 1, Number.MAX_SAFE_INTEGER) }) };
       const posted = withStore(store => opts.originKey === undefined
         ? store.post(envelope)
         : store.appendWithProvenance(envelope, opts.originKey));
@@ -110,12 +119,13 @@ export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): vo
       });
     })());
 
-  msg.command('watch').description('Poll for new messages without acknowledging them (Ctrl-C to stop)')
+  msg.command('watch').description('Watch durable messages; SSE accelerates delivery and polling covers outages')
     .option('--to <seat>').option('--after <id>', 'exclusive message ID (default: acknowledged cursor)')
     .option('--since-ack', 'start from the recipient seat’s acknowledged cursor')
     .option('--interval <ms>', 'poll interval in milliseconds', '1000')
+    .option('--sse <url>', 'post office base URL (fall back to ledger polling on disconnect)')
     .option('--once', 'poll once and exit').option('--json')
-    .action((opts: RecipientOptions & { interval?: string; once?: boolean; sinceAck?: boolean }) => run(async () => {
+    .action((opts: RecipientOptions & { interval?: string; once?: boolean; sinceAck?: boolean; sse?: string }) => run(async () => {
       if (opts.sinceAck && opts.after !== undefined) throw new Error('--since-ack cannot be used with --after');
       const to = seat(opts.to, '--to');
       const interval = integer(opts.interval, '--interval', 1000, 1, 60000);
@@ -123,7 +133,7 @@ export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): vo
       const store = open();
       try {
         let cursor = after ?? store.getCursor(to);
-        do {
+        const poll = () => {
           let messages: Message[];
           do {
             messages = store.list(to, cursor, 1000);
@@ -132,12 +142,158 @@ export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): vo
               cursor = message.id;
             }
           } while (messages.length === 1000 && !deps.signal?.aborted);
-          if (opts.once || deps.signal?.aborted) break;
-          await sleep(interval);
-        } while (!deps.signal?.aborted);
+        };
+        if (!opts.sse || opts.once) {
+          do {
+            poll();
+            if (opts.once || deps.signal?.aborted) break;
+            await sleep(interval);
+          } while (!deps.signal?.aborted);
+        } else {
+          const url = new URL('/stream', opts.sse);
+          if (!['http:', 'https:'].includes(url.protocol)) throw new Error('--sse requires an HTTP URL');
+          if (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+            throw new Error('--sse requires HTTPS outside localhost');
+          url.searchParams.set('to', to);
+          const token = (deps.authToken ?? (() => ensureAuthToken().token))();
+          let outage = false;
+          while (!deps.signal?.aborted) {
+            poll();
+            url.searchParams.set('since', String(cursor));
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            deps.signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+              let connectTimer: ReturnType<typeof setTimeout> | undefined;
+              const response = await Promise.race([
+                (deps.fetch ?? fetch)(url, { headers: {
+                  Authorization: `Bearer ${token}`, 'Last-Event-ID': String(cursor),
+                }, signal: controller.signal }),
+                new Promise<never>((_, reject) => { connectTimer = setTimeout(() => {
+                  controller.abort();
+                  reject(new Error('SSE connect timeout'));
+                }, Math.max(1000, Math.min(5000, interval * 2))); }),
+              ]).finally(() => clearTimeout(connectTimer));
+              if (response.status === 401) throw new Error('SSE unauthorized (401)');
+              if (!response.ok || !response.body) throw new Error(`SSE unavailable (${response.status})`);
+              outage = false;
+              const reader = response.body.getReader();
+              const decoder = new TextDecoder();
+              let pending = '';
+              while (!deps.signal?.aborted) {
+                let idleTimer: ReturnType<typeof setTimeout> | undefined;
+                const chunk = await Promise.race([
+                  reader.read(),
+                  new Promise<never>((_, reject) => { idleTimer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error('SSE idle timeout'));
+                  }, Math.max(1000, Math.min(5000, interval * 2))); }),
+                ]).finally(() => clearTimeout(idleTimer));
+                if (chunk.done) break;
+                pending += decoder.decode(chunk.value, { stream: true });
+                pending = pending.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 event = pending.slice(0, boundary);
+                  pending = pending.slice(boundary + 2);
+                  if (event.split('\n').some((line) => line.startsWith('id: '))) poll();
+                }
+              }
+            } catch (error) {
+              if (error instanceof Error && error.message === 'SSE unauthorized (401)') throw error;
+              if (!outage && !deps.signal?.aborted) out.error(`msg: SSE disconnected; polling ledger (${error instanceof Error ? error.message : String(error)})`);
+              outage = true;
+            } finally { deps.signal?.removeEventListener('abort', onAbort); controller.abort(); }
+            if (deps.signal?.aborted) break;
+            poll();
+            await sleep(interval);
+          }
+        }
       } finally { store.close(); }
     })());
 
+  msg.command('ask <recipient> <question>').description('Post a question and wait for its first reply')
+    .option('--from <seat>', 'asking seat (required)').option('--wait <seconds>', 'seconds to wait for a reply (default 60)', '60')
+    .option('--json')
+    .action((recipient: string, question: string, opts: CommonOptions & { from?: string; wait?: string }) => run(async () => {
+      const from = seat(opts.from, '--from');
+      const to = canonicalSeatId(recipient);
+      const waitSeconds = integer(opts.wait, '--wait', 60, 0, 86400);
+      const interrupt = deps.signal === undefined ? new AbortController() : undefined;
+      const signal = deps.signal ?? interrupt!.signal;
+      const onInterrupt = () => interrupt?.abort();
+      if (interrupt) {
+        process.once('SIGINT', onInterrupt);
+        process.once('SIGTERM', onInterrupt);
+      }
+      let store: MsgStore | undefined;
+      try {
+        const asked = withStore(ledger => ledger.post({ from, to, body: question }));
+        const deadline = Date.now() + waitSeconds * 1000;
+        let reply: Message | undefined;
+        store = open();
+        do {
+          reply = store.listReplies(asked.id, 1)[0];
+          if (reply !== undefined || signal.aborted || Date.now() >= deadline) break;
+          await sleep(1000);
+        } while (true);
+        if (reply === undefined && signal.aborted) throw new Error(`ask interrupted after posting #${asked.id}`);
+        if (reply === undefined) throw new Error(`no reply to #${asked.id} within ${waitSeconds}s`);
+        emit(reply, opts.json, () => out.log(formatMessage(reply)));
+      } finally {
+        store?.close();
+        if (interrupt) {
+          process.removeListener('SIGINT', onInterrupt);
+          process.removeListener('SIGTERM', onInterrupt);
+        }
+      }
+    })());
+
+  msg.command('thread <id>').description('Show one question and its replies in time order')
+    .option('--json')
+    .action((id: string, opts: CommonOptions) => run(() => {
+      const target = integer(id, 'message ID', 0, 1, Number.MAX_SAFE_INTEGER);
+      const thread = withStore(store => {
+        const question = store.getMessage(target);
+        if (question === null) throw new Error(`message not found: #${target}`);
+        // Keep paging until a short page so a thread longer than one store page is never truncated.
+        const replies: Message[] = [];
+        let after = 0;
+        let page: Message[];
+        do {
+          page = store.listReplies(target, 100, after);
+          replies.push(...page);
+          after = page.at(-1)?.id ?? after;
+        } while (page.length === 100);
+        return { question, replies };
+      });
+      emit(thread, opts.json, () => {
+        out.log(formatMessage(thread.question));
+        for (const reply of thread.replies) out.log(formatMessage(reply));
+      });
+    })());
+
+  msg.command('serve').description('Run the independent, read-only post office SSE service')
+    .option('--sse', 'serve GET /stream')
+    .option('--port <port>', 'port (or ELANOUS_MSG_SSE_PORT)')
+    .option('--host <host>', 'bind address', '127.0.0.1')
+    .action((opts: { sse?: boolean; port?: string; host?: string }) => run(() => {
+      if (!opts.sse) throw new Error('serve requires --sse');
+      const rawPort = opts.port ?? process.env.ELANOUS_MSG_SSE_PORT;
+      if (rawPort === undefined) throw new Error('--port or ELANOUS_MSG_SSE_PORT is required');
+      const port = integer(rawPort, '--port', 0, 0, 65535);
+      const store = openRead();
+      try {
+        const service = startMsgSseServer({ store, token: (deps.authToken ?? (() => ensureAuthToken().token))(),
+          port, hostname: opts.host });
+        out.log(`msg SSE listening on ${opts.host}:${service.port}`);
+        const stop = () => { service.stop(); store.close(); };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+      } catch (error) { store.close(); throw error; }
+    })());
+
   // Commander reports option/argument errors before action handlers run. Scope their exit code
   // to msg so unrelated commands keep their own error and help behavior.
   for (const command of [msg, ...msg.commands]) {