elanous 0.2.21 → 0.2.22

package/src/cli/pr-cli.ts

@@ -62,6 +62,9 @@ import { enqueueL8ShadowQueue, runL8ShadowQueue, shadowPrNumber, statusL8ShadowQ
 export { branchLineageSlug, findSiblingPrs };
 
 export interface PrLandOpts {
+  /** Pin an existing PR and its reviewed head; both must be supplied together. */
+  pr?: string;
+  expectedHead?: string;
   base?: string;
   cwd?: string;
   dryRun?: boolean;
@@ -1180,10 +1183,33 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
 
   const cwd = opts.cwd ?? process.cwd();
   const run = deps.run ?? defaultCmdRunner;
+  const pinned = opts.pr !== undefined || opts.expectedHead !== undefined;
+  let pinnedBranch: string | undefined;
+  let pinnedUrl: string | undefined;
+  if (pinned) {
+    const pr = Number(opts.pr);
+    if (!/^[1-9]\d*$/.test(opts.pr ?? '') || !Number.isSafeInteger(pr) || !/^[a-f0-9]{40}$/i.test(opts.expectedHead ?? '') || opts.hold || opts.dryRun) {
+      out.error('✗ expected-head: --pr and --expected-head (full SHA) are required together without --hold/--dry-run');
+      return 1;
+    }
+    const viewed = run('gh', ['pr', 'view', String(pr), '--json', 'headRefOid,headRefName,state,isDraft,url'], { cwd });
+    let value: { headRefOid?: string; headRefName?: string; state?: string; isDraft?: boolean; url?: string } = {};
+    try { if (viewed.ok) value = JSON.parse(viewed.out) as typeof value; } catch { /* unreadable is not approval */ }
+    const local = run('git', ['rev-parse', 'HEAD'], { cwd });
+    const dirty = run('git', ['status', '--porcelain'], { cwd });
+    if (value.state !== 'OPEN' || value.isDraft !== false || value.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !value.url?.endsWith(`/pull/${pr}`) || !value.headRefName || !local.ok || local.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !dirty.ok || dirty.out.trim()) {
+      out.error('✗ expected-head: PR OPEN non-draft, matching local HEAD and clean worktree required');
+      return 1;
+    }
+    pinnedBranch = value.headRefName;
+    pinnedUrl = value.url;
+  }
   const resolveBase = deps.resolveBase ?? resolveDeliverableBase;
   const branch = (deps.currentBranch ?? liveCurrentBranch)(cwd);
-  if (!branch) {
-    const detail = '현재 브랜치를 해석하지 못했습니다.';
+  if (!branch || (pinned && branch !== pinnedBranch)) {
+    const detail = pinned ? 'PR head branch와 현재 브랜치가 다릅니다.' : '현재 브랜치를 해석하지 못했습니다.';
     record('branch', false);
     out.error(`✗ branch: ${detail}`);
     return 1;
@@ -1567,6 +1593,10 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     });
   }
   const hold = !!opts.hold || overlapDecision?.outcome === 'user-hold';
+  if (pinned && overlapDecision && overlapDecision.outcome !== 'user-merge') {
+    out.error('✗ expected-head: overlap merge approval unavailable for the reviewed head');
+    return 1;
+  }
 
   const manager = deps.manager ?? makePrManager(run);
   const existing = manager.findPrForBranchOutcome(branch, cwd);
@@ -1638,7 +1668,12 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     }
   }
 
-  const upsert = manager.upsertPr({
+  // A pinned, already-reviewed commit must not go through upsertPr (git add/commit/force-push/PR edit).
+  const upsert = pinned
+    ? existing.status === 'ok OUTPUT' && existing.url === pinnedUrl
+      ? { ok: true as const, url: pinnedUrl!, reused: true }
+      : { ok: false as const, reason: 'gh' as const, detail: 'pinned PR is not the branch open PR' }
+    : manager.upsertPr({
     branch,
     worktreePath: cwd,
     base,
@@ -1654,7 +1689,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     ...(excludingActiveRunFiles ? { excludePaths } : {}),
   });
   if (!upsert.ok) {
-    if (upsert.reason === 'noop' && excludingActiveRunFiles) {
+    if (upsert.reason === 'noop' && excludingActiveRunFiles && !pinned) {
       record('upsert-ready-noop', true, { excludePaths, detail: upsert.detail });
       out.log(`✓ upsert-ready: 제외 후 올릴 것이 없습니다 — ${upsert.detail}`);
       return 0;
@@ -1664,6 +1699,13 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     return 1;
   }
   record('upsert-ready', true);
+  if (pinned) {
+    const upsertHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (!upsert.reused || upsert.url !== pinnedUrl || !upsertHead.ok || upsertHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      out.error('✗ expected-head: pinned PR identity or reviewed HEAD changed');
+      return 1;
+    }
+  }
   out.log(`✓ upsert-ready: ${upsert.url}${upsert.reused ? ' (기존 PR)' : ' (새 PR)'}`);
 
   if (hold) {
@@ -1688,21 +1730,34 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     debug.log('harness.merge', 'frozen', { prUrl: upsert.url, reason: frozen.reason, until: frozen.until });
     record('freeze', true, { url: upsert.url, reason: frozen.reason, until: frozen.until });
     out.log(`✓ ready: ${upsert.url} — ${landingFreezeMessage(frozen)} · 병합 연기`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   if (admission.kind === 'taken') {
     record('freeze', true, { url: upsert.url, resumedElsewhere: true });
     out.log(`✓ ready: ${upsert.url} — 동결이 막 풀려 보류 병합 재개가 이 PR 을 맡았습니다`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   const landing = admission;
+  if (pinned) {
+    const view = run('gh', ['pr', 'view', String(opts.pr), '--json', 'headRefOid,state,isDraft'], { cwd });
+    let current: { headRefOid?: string; state?: string; isDraft?: boolean } = {};
+    try { if (view.ok) current = JSON.parse(view.out) as typeof current; } catch { /* fail closed */ }
+    const finalHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (current.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase() || current.state !== 'OPEN' || current.isDraft !== false
+      || !finalHead.ok || finalHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      landing.end(false);
+      out.error('✗ expected-head: PR head/state changed before merge');
+      return 1;
+    }
+  }
   let merged: ReturnType<typeof manager.mergePrOutcome>;
   try {
-  merged = manager.mergePrOutcome(upsert.url);
+  merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   // `GIT-S14` — 병합이 «미완료(OPEN)»로 끝났고 GitHub 가 아직 `mergeable=UNKNOWN`(병합 가능 여부 계산 중)이면
   //   짧게 기다렸다 다시 병합한다. 표본 셋(08-25 · 09-24 🅢 #20233 등)이 모두 «같은 명령 재시도에 병합»이었다.
   //   ⛔ UNKNOWN 일 때만 재시도한다 — CONFLICTING 등 다른 값은 기다려도 안 풀린다(그대로 실패를 낸다).
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  // pinned 도 재시도한다 — mergePrOutcome 이 머리를 다시 확인하고 --match-head-commit 으로 병합하므로 바뀐 머리로는 안 들어간다.
   for (let attempt = 1; !merged.ok && merged.kind === 'not-merged' && merged.state === 'OPEN' && attempt <= PR_LAND_MERGEABLE_UNKNOWN_RETRIES; attempt += 1) {
     const mergeable = run('gh', ['pr', 'view', upsert.url, '--json', 'mergeable', '--jq', '.mergeable'], { cwd });
     const value = mergeable.ok ? mergeable.out.trim() : '';
@@ -1710,7 +1765,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     record('merge-retry', true, { attempt, mergeable: value, waitMs: PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS });
     out.log(`⏳ merge: mergeable=UNKNOWN — GitHub 가 병합 가능 여부를 아직 계산 중입니다 · ${PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS / 1000}초 뒤 다시 병합 (${attempt}/${PR_LAND_MERGEABLE_UNKNOWN_RETRIES})`);
     await sleep(PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS);
-    merged = manager.mergePrOutcome(upsert.url);
+    merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   }
   } finally { landing.end(merged!?.ok === true); }
   if (!merged.ok) {
@@ -1781,6 +1836,8 @@ export function registerPrCommands(program: Command, deps: PrLandDeps = {}, queu
     .description('현재 브랜치 PR을 생성 또는 갱신해 ready 상태로 만들고 squash merge')
     .option('--base <branch>', 'PR base branch')
     .option('--cwd <path>', '작업 트리 경로')
+    .option('--pr <number>', '기존 PR 번호 고정 (--expected-head 와 함께)')
+    .option('--expected-head <sha>', '리뷰된 PR 머리 SHA 고정 (--pr 와 함께)')
     .option('--dry-run', '변경 없이 landing 계획만 출력')
     .option('--hold', 'PR을 생성 또는 갱신한 뒤 병합하지 않고 쌓아 둔다')
     .option('--title <title>', 'PR title')

package/src/cli/release-cli.ts

@@ -18,7 +18,7 @@
 // ⛔ 공개본은 «원본 매니페스트»(`release/public-export.yaml`)대로만 만든다 — 매매 실행 코드는 그 매니페스트가 이미 뺀다(🅢 #20529).
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import type { Command } from 'commander';
@@ -27,7 +27,7 @@ import { effectiveInstanceRoot, releaseLedgerRoot } from '../instance/resolve.js
 import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
 import { envLiteral } from '../platform/env-literal.js';
 import { getUserConfig, userConfigPath } from '../user-config.js';
-import { addItem, cellsReferencingDoc, claimItem, decodeClaimHistoryEntry, devVersion, listChecklist, ownerMatches, parseOwner, parityGap, removeItem, renderRefsStatus, seedFromRoadmap, setItem, summarizeChecklist, type ChecklistStatus, type ChecklistDisposition, type ChecklistKind } from '../release-loop/checklist.js';
+import { addItem, cellsReferencingDoc, claimItem, decodeClaimHistoryEntry, devVersion, lintDocRefs, listChecklist, normalizeRefs, ownerMatches, parseOwner, parityGap, refRoots, removeItem, renderRefsStatus, seedFromRoadmap, setItem, summarizeChecklist, type ChecklistStatus, type ChecklistDisposition, type ChecklistKind } from '../release-loop/checklist.js';
 import * as features from '../release-loop/feature-store.js';
 import { evidencePlan, landedButYellow, type MergedChecklistPr } from '../release-loop/landed-but-yellow.js';
 import { formatSchedule, getSchedule, listSchedules, setSchedule } from '../release-loop/release-schedule.js';
@@ -705,11 +705,28 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
       console.log(`루브릭 없는 칸 ${missing}`);
     });
   withContext(checklist.command('refs <doc>').description('문서를 인용하는 칸 — 모든 판의 구현 현황(읽기 전용)'))
-    .action(async (doc: string, _opts: unknown, cmd: Command) => {
+    .option('--lint', '문서 절과 칸 인용을 양방향 대조(읽기 전용)')
+    .action(async (doc: string, opts: { lint?: boolean }, cmd: Command) => {
       if (!doc.trim() || doc.trim().startsWith('#')) throw new CliUserError(`잘못된 문서: ${doc}`, '저장소 상대 경로[#절] — 예: docs/RFC-x.md#§3');
       const { json } = context(cmd);
       const ledgerRoot = releaseLedgerRoot();
-      const rows = cellsReferencingDoc(doc, features.assignedVersions(ledgerRoot).map((version) => listChecklist(version, ledgerRoot)));
+      const checklists = features.assignedVersions(ledgerRoot).map((version) => listChecklist(version, ledgerRoot));
+      if (opts.lint) {
+        const path = doc.trim().split('#')[0]!.replace(/^\.\//, '');
+        const roots = refRoots();
+        normalizeRefs([path], roots);
+        const file = roots.map((root) => join(root, path)).find((candidate) => {
+          try { return statSync(candidate).isFile(); } catch { return false; }
+        })!;
+        const result = lintDocRefs(path, readFileSync(file, 'utf8'), checklists);
+        debug.log('release.checklist', 'refs-lint', { doc, sections: result.sections.length, uncovered: result.uncoveredSections.length, dangling: result.danglingRefs.length });
+        if (json) { await writeStdoutJson(`${JSON.stringify({ doc, ...result })}\n`); return; }
+        console.log(`칸 없는 절: ${result.uncoveredSections.join(', ') || '없음'}`);
+        console.log(`없는 절을 가리키는 칸: ${result.danglingRefs.map(({ version, id, ref }) => `${version} ${id} ${ref}`).join(' · ') || '없음'}`);
+        console.log(`절 ${result.sections.length} · 칸 없는 절 ${result.uncoveredSections.length} · 없는 절을 가리키는 칸 ${result.danglingRefs.length}`);
+        return;
+      }
+      const rows = cellsReferencingDoc(doc, checklists);
       const byStatus = { green: 0, yellow: 0, red: 0, done: 0 } as Record<ChecklistStatus, number>;
       for (const row of rows) byStatus[row.status] += 1;
       debug.log('release.checklist', 'refs-read', { doc, rows: rows.length });

package/src/cli/tasks-cli.ts

@@ -1,4 +1,4 @@
-import { closeSync, mkdirSync, openSync, readFileSync, readSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { loadRunLedger as loadRunLedgerSync } from '../self-implement/run-ledger.js';
 import { join, resolve } from 'node:path';
@@ -12,6 +12,9 @@ import type { Task } from '../task-orchestrator/types.js';
 import { cardPrNumber, COMPLETION_KINDS, handTask, nextMoveFor, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TASK_CARD_PREFIX, TASK_SEATS, type CompletionKind, type TaskCard, type TaskLaunchContext, type TaskLaunchReceipt, type TaskLauncher, type TaskSeat } from '../task-agent/task-hand.js';
 import { readCardSalvageBranch, refreshCardRunBinding, type CardRunEvidenceDeps } from '../task-agent/card-evidence.js';
 import { advanceMission, handMission, MissionAdvanceError, openMissionIds, recordPieceRef, type AdvanceMissionResult, type MissionDecompose, type PieceEvidenceReader } from '../task-agent/mission.js';
+import { formatTaskAgentCover, measureTaskAgentCover, type CoverRow, type TaskAgentCoverInput } from '../task-agent/cover.js';
+import { LogStore, STORE_SAFETY_MAX, type LogQuery, type LogStoreRow } from '../mss/logging/log-store.js';
+import { resolveLogTargets } from './logs-cli.js';
 
 type TaskRow = Pick<Task, 'id' | 'title' | 'priority' | 'status' | 'createdAt' | 'approval' | 'generatedBy'>;
 
@@ -38,6 +41,9 @@ export interface TasksCliDeps {
   remoteLedgerMirror?: (card: TaskCard) => void;
   /** `tasks parents` 의 낡은 부모 보고 의존(시험 주입). */
   staleParents?: import('../task-agent/parent-host.js').StaleParentDeps;
+  /** `tasks cover` logs 조회 seam. 기본은 등록된 모든 우주(운영 ⊕ test)의 logs.db 를 read-only 로 연다 —
+   *  pr land 는 작업 트리마다 파생 test 우주에 기록되므로 현재 우주만 읽으면 분모가 늘 0 이다. */
+  coverLogs?: (query: LogQuery) => LogStoreRow[] | CoverLogRead;
 }
 
 /** `<조각id>=<값>` 반복 인자. */
@@ -390,6 +396,74 @@ function handleError(error: unknown, out: (line: string) => void): void {
   }
 }
 
+const COVER_QUERY_LIMIT = STORE_SAFETY_MAX;
+
+/** Federated read: rows from every store, whether any single store hit the bound, and how many stores could not be read. */
+export interface CoverLogRead { rows: LogStoreRow[]; limitReached: boolean; unreadableStores: number; storesRead: number }
+
+function queryCoverLogs(query: LogQuery): CoverLogRead {
+  const { targets, error } = resolveLogTargets({ all: true, includeTest: true });
+  if (error) throw new Error(error);
+  const read: CoverLogRead = { rows: [], limitReached: false, unreadableStores: 0, storesRead: 0 };
+  for (const target of targets) {
+    if (!existsSync(target.dbPath)) continue;
+    let store: LogStore | undefined;
+    try {
+      store = LogStore.openReadOnly(target.dbPath);
+      const rows = store.query(query);
+      if (query.limit !== undefined && rows.length >= query.limit) read.limitReached = true;
+      read.rows.push(...rows);
+      read.storesRead++;
+    } catch { read.unreadableStores++; }
+    finally { try { store?.close(); } catch { /* already closed */ } }
+  }
+  if (read.storesRead === 0) throw new Error('읽을 수 있는 logs.db 없음');
+  return read;
+}
+
+function coverEvents<T>(rows: readonly LogStoreRow[], category: string, event: string, parse: (data: Record<string, unknown>) => T | null): T[] {
+  const events: T[] = [];
+  for (const row of rows) {
+    if (row.category !== category || row.event !== event || !row.data) continue;
+    try {
+      const data: unknown = JSON.parse(row.data);
+      if (data === null || typeof data !== 'object' || Array.isArray(data)) continue;
+      const parsed = parse(data as Record<string, unknown>);
+      if (parsed !== null) events.push(parsed);
+    } catch { /* malformed log data is not evidence of an action */ }
+  }
+  return events;
+}
+
+export function readTaskAgentCover(
+  window: { sinceMs?: number; untilMs?: number } = {},
+  query: NonNullable<TasksCliDeps['coverLogs']> = queryCoverLogs,
+): { rows: CoverRow[]; limitReached: boolean; unreadableStores: number } {
+  let unreadableStores = 0;
+  const read = (category: 'task-agent' | 'pr.land', event: 'action' | 'step'): { rows: LogStoreRow[]; limitReached: boolean } | null => {
+    try {
+      const result = query({ ...window, limit: COVER_QUERY_LIMIT, exactCategories: [category], events: [event] });
+      if (Array.isArray(result)) return { rows: result, limitReached: result.length >= COVER_QUERY_LIMIT };
+      unreadableStores = Math.max(unreadableStores, result.unreadableStores);
+      return { rows: result.rows, limitReached: result.limitReached };
+    } catch { return null; }
+  };
+  const actionRead = read('task-agent', 'action');
+  const landRead = read('pr.land', 'step');
+  const actions = actionRead?.rows ?? null;
+  const lands = landRead?.rows ?? null;
+  const truncated = { taskAgentActions: actionRead?.limitReached === true, allLands: landRead?.limitReached === true };
+  const input: TaskAgentCoverInput = {
+    taskAgentActions: actions === null ? null : coverEvents(actions, 'task-agent', 'action', (data) =>
+      typeof data.kind === 'string' && typeof data.result === 'string'
+        ? { kind: data.kind as NonNullable<TaskAgentCoverInput['taskAgentActions']>[number]['kind'], result: data.result } : null),
+    allLands: lands === null ? null : coverEvents(lands, 'pr.land', 'step', (data) =>
+      typeof data.step === 'string' && typeof data.ok === 'boolean' ? { step: data.step, ok: data.ok } : null),
+    truncated,
+  };
+  return { rows: measureTaskAgentCover(input), limitReached: truncated.taskAgentActions || truncated.allLands, unreadableStores };
+}
+
 export function registerTasksCommands(program: Command, deps: TasksCliDeps = {}): void {
   let activeToken: string | undefined;
   const output = deps.output ?? console.log;
@@ -402,6 +476,39 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
   };
   const tasks = program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인 · TASK-AGENT 과제 넘기기(hand)');
 
+  tasks.command('cover')
+    .description('TASK-AGENT 가 대신한 착지 비율과 리뷰·재발사·green 의 아직 없는 분모를 조회(읽기 전용)')
+    .option('--since <iso>', '시작 시각 (ISO)')
+    .option('--until <iso>', '끝 시각 (ISO)')
+    .option('--json', 'JSON 출력')
+    .option('--lines', '동사별 한 줄 요약 출력 (읽기 전용)')
+    .action((opts: { since?: string; until?: string; json?: boolean; lines?: boolean }) => {
+      const parseIso = (value: string | undefined, flag: string): number | undefined => {
+        if (value === undefined) return undefined;
+        const time = Date.parse(value);
+        if (!/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d\d:\d\d)$/.test(value) || !Number.isFinite(time)) throw new Error(`${flag} 는 ISO 시각이어야 한다`);
+        return time;
+      };
+      try {
+        const sinceMs = parseIso(opts.since, '--since');
+        const untilMs = parseIso(opts.until, '--until');
+        if (sinceMs !== undefined && untilMs !== undefined && sinceMs > untilMs) throw new Error('--since 가 --until 보다 늦다');
+        const { rows, limitReached, unreadableStores } = readTaskAgentCover({ sinceMs, untilMs }, deps.coverLogs);
+        const limitWarning = limitReached ? `조회 상한 ${COVER_QUERY_LIMIT} 도달 — 더 오래된 사건이 있을 수 있다(절단된 수를 전체로 읽지 말 것)` : null;
+        const storeWarning = unreadableStores > 0 ? `logs.db ${unreadableStores}개를 못 읽었다 — 그 우주의 사건은 수에 없다(«없다»로 읽지 말 것)` : null;
+        if (opts.json) out(JSON.stringify({ rows, limitReached, unreadableStores, ...(limitWarning ? { warning: limitWarning } : {}), ...(storeWarning ? { storeWarning } : {}) }));
+        else {
+          if (opts.lines) for (const row of rows) out(formatTaskAgentCover(row));
+          else {
+            out('동사\t대신\t전체\t비율\t상태\t관측 사건');
+            for (const row of rows) out(`${row.verb}\t${row.byTaskAgent ?? '-'}\t${row.total ?? '-'}\t${row.ratio ?? '-'}\t${row.state}\t${row.observedActions ?? '-'}`);
+          }
+          if (limitWarning) out(`⚠ ${limitWarning}`);
+          if (storeWarning) out(`⚠ ${storeWarning}`);
+        }
+      } catch (error) { out(error instanceof Error ? error.message : '커버 조회 실패'); process.exitCode = 1; }
+    });
+
   tasks.command('list')
     .description('우선순위와 생성 시각 순으로 태스크 보기')
     .option('--status <s>', '상태로 필터')

package/src/connectors/types.ts

@@ -1,5 +1,5 @@
-export interface ExternalTaskEvent {
-  provider: 'linear' | 'asana';
+export interface ExternalTaskEvent<Provider extends string = 'linear' | 'asana'> {
+  provider: Provider;
   eventId: string;
   kind: 'created' | 'updated';
   ref: string;
@@ -11,9 +11,9 @@ export interface ExternalTaskEvent {
   occurredAt: string;
 }
 
-export interface TaskConnector {
-  provider: ExternalTaskEvent['provider'];
+export interface TaskConnector<Provider extends string = ExternalTaskEvent['provider']> {
+  provider: Provider;
   verify(req: { rawBody: string | Uint8Array; signature: string; secret: string; now?: number }): { ok: true } | { ok: false; reason: string };
-  parse(body: unknown, deliveryId: string): ExternalTaskEvent | null;
-  idempotencyKey(event: ExternalTaskEvent): string;
+  parse(body: unknown, deliveryId: string): ExternalTaskEvent<Provider> | null;
+  idempotencyKey(event: ExternalTaskEvent<Provider>): string;
 }

package/src/context-bus/context-now-surfaces.ts

@@ -53,6 +53,24 @@ export function renderTelegramNow(input: ContextNowAnswer, audience: ContextNowA
   return lines.map(line => line.replace(/\s+/g, ' ').trim()).join('\n');
 }
 
+/** Context-first opening for chat connectors: up to three operational rows (live runs, an unfinished
+ *  release run, late schedules) ahead of the same `/now` body. `/now` itself stays unchanged. */
+export function renderContextFirstNow(input: ContextNowAnswer, audience: ContextNowAudience = 'operator'): string {
+  const answer = forAudience(input, audience);
+  const labels = { run: '도는 런', release: '발행 런', 'schedule-late': '지연 스케줄' } as const;
+  const operational = answer.facts.filter(fact => fact.kind === 'run' ||
+    (fact.kind === 'release' && (fact.unreadable || fact.status !== 'done')) ||
+    (fact.kind === 'schedule-late' && (fact.unreadable || !!fact.count)));
+  // Run goals are whole asks (often thousands of characters); one line each keeps the opening to one screen.
+  const short = (text: string) => { const chars = Array.from(text); return chars.length > 60 ? `${chars.slice(0, 60).join('')}…` : text; };
+  const lines = operational.slice(0, 3).map(fact => {
+    const text = fact.kind === 'run' && !fact.unreadable ? `${short(fact.goal.replace(/\s+/g, ' ').trim())} · ${fact.phase} · ${fact.elapsed}` : factText(fact);
+    return `${labels[fact.kind as keyof typeof labels]}: ${text} — ${fact.source}`.replace(/\s+/g, ' ').trim();
+  });
+  if (operational.length > lines.length) lines.push(`… 운영 항목 ${operational.length - lines.length}개 더 (/now)`);
+  return [...lines, renderTelegramNow(answer, 'operator')].join('\n');
+}
+
 export function renderTuiNow(input: ContextNowAnswer, audience: ContextNowAudience = 'operator'): string[] {
   const answer = forAudience(input, audience);
   const shortText = (text: string) => {

package/src/context-bus/coord-events.ts

@@ -2,7 +2,9 @@ import { Database } from 'bun:sqlite';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { debug, redactSecretText } from '../debug/log.js';
+import { DecisionLedger, type Seat } from '../decisions/decision-ledger.js';
 import { openSurfaceEventsDb, recordEvent, surfaceEventsDbPath } from '../domains/surface-events.js';
+import { registeredSeats } from '../seat-address/seat-address.js';
 
 export interface CoordEventInput {
   seat: string;
@@ -31,6 +33,13 @@ function seatIds(): Set<string> {
 }
 const kinds = new Set(['요청', '결정', '사고', '보고', '정정']);
 
+function cleanCoordHeadline(value: string): string {
+  const first = value.split(/\r?\n/, 1)[0] ?? '';
+  const withoutPrefix = first.replace(/^\*\*\[[A-Z]+\]\*\*\s*/, '')
+    .replace(/^(?:📌안내\s*)?\d{4}-\d\d-\d\d\s+\d\d:\d\d\s+KST\s*/, '');
+  return redactSecretText(withoutPrefix).trim().slice(0, 120);
+}
+
 /** Mirror the sender's ordered envelope fields; only the first line enters this parser. */
 export function parseCoordHeader(seat: string, header: string): Omit<CoordEventInput, 'url' | 'at'> {
   const first = header.split(/\r?\n/, 1)[0] ?? '';
@@ -69,10 +78,7 @@ export function recordCoordEvent(input: CoordEventInput, deps: { db?: Database }
   try {
     db = deps.db ?? openSurfaceEventsDb();
     const at = input.at ?? new Date().toISOString();
-    const first = input.headline.split(/\r?\n/, 1)[0] ?? '';
-    const withoutPrefix = first.replace(/^\*\*\[[A-Z]+\]\*\*\s*/, '')
-      .replace(/^(?:📌안내\s*)?\d{4}-\d\d-\d\d\s+\d\d:\d\d\s+KST\s*/, '');
-    const headline = redactSecretText(withoutPrefix).trim().slice(0, 120);
+    const headline = cleanCoordHeadline(input.headline);
     const safe = (value: string) => redactSecretText(value.split(/\r?\n/, 1)[0] ?? '');
     const refs = { seat: safe(input.seat), recipients: input.recipients.map(safe), all: input.all,
       kind: input.kind === null ? null : safe(input.kind), slot: input.slot === null ? null : safe(input.slot),
@@ -98,6 +104,28 @@ export function recordCoordEvent(input: CoordEventInput, deps: { db?: Database }
   } finally { if (!deps.db) db?.close(); }
 }
 
+/** A failed decision mirror must never turn a successful channel/context record into a failure. */
+export function mirrorCoordDecision(input: CoordEventInput, deps: { ledger?: Pick<DecisionLedger, 'recordSeatDecision'> } = {}): void {
+  if (input.kind !== '결정') return;
+  try {
+    if (!registeredSeats().some(({ id }) => id === input.seat)) return;
+    const entry = (deps.ledger ?? new DecisionLedger()).recordSeatDecision({
+      seat: input.seat as Seat,
+      title: input.slot ? redactSecretText(input.slot.split(/\r?\n/, 1)[0] ?? '').trim() : cleanCoordHeadline(input.headline),
+      decision: cleanCoordHeadline(input.headline),
+      delegation: '조율 채널 — 자리 위임 범위',
+      ...(input.url ? { refs: [input.url] } : {}),
+      decidedAt: input.at ?? new Date().toISOString(),
+    });
+    try { debug.log('context.coord', 'decision-mirrored', { seat: entry.seat, id: entry.id }); }
+    catch { /* observation cannot turn a successful write into a failed send */ }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'seat decision source already recorded') return;
+    try { debug.log('context.coord', 'decision-mirror-failed', { seat: redactSecretText(input.seat) }); }
+    catch { /* observation cannot turn a successful send into a failure */ }
+  }
+}
+
 /** Read-only chronological list; a missing store is an empty ledger, not a newly created one. */
 export function listCoordEvents(opts: { since: string; seat?: string; channelOnly?: boolean }, deps: { db?: Database } = {}): CoordEvent[] {
   if (!deps.db && !existsSync(surfaceEventsDbPath())) return [];

package/src/context-bus/long-term-memory.ts

@@ -18,6 +18,14 @@ export interface MemoryItem {
   conflict?: { owner: 'OP'; sources: [string, string] };
 }
 
+/** Guardian retention boundary: lifecycle hygiene, independent of librarian promotion. */
+export function guardianRetireAged(items: readonly MemoryItem[], now: Date): MemoryItem[] {
+  const cutoff = now.getTime() - 30 * DAY_MS;
+  return items.map(item => ({ ...item,
+    status: Date.parse(item.updatedAt) < cutoff ? 'retired' as const : item.status,
+  }));
+}
+
 export type MemorySource =
   | { kind: 'event'; at: string; seat: string; text: string; source: string }
   | { kind: 'decision'; at: string; seat: string; text: string; source: string };
@@ -28,6 +36,8 @@ export interface MemorySummary {
   summary: string;
   /** Only supply this when the two strings identify the same fact and mutually exclusive values. */
   claim?: { key: string; value: string };
+  /** Sleep-review task agent's promotion decision; not stored in a MemoryItem. */
+  promote?: boolean;
 }
 
 type CondenseEvent = CoordEvent & { surface?: string };
@@ -38,7 +48,7 @@ export interface MemoryDeps {
   decisions?: () => DecisionEntry[];
 }
 
-export type CondenseSkipReason = 'no-seat' | 'no-project' | 'no-topic' | 'no-summary' | 'bad-link' | 'bad-claim' | 'no-claim' | 'summarize-failed';
+export type CondenseSkipReason = 'not-promoted' | 'no-seat' | 'no-project' | 'no-topic' | 'no-summary' | 'bad-link' | 'bad-claim' | 'no-claim' | 'summarize-failed';
 export type CondenseSkipped = Partial<Record<CondenseSkipReason, number>>;
 export interface FunnelCount { total: number; bySeat: Record<string, number> }
 export interface CondenseFunnel {
@@ -77,22 +87,25 @@ export function readCondenseEvents(since: string): CondenseEvent[] {
 /** Condense one UTC day; callers persist the returned snapshot, not raw transcripts. Read-only ledger access. */
 export async function condenseContextDay(
   day: string, previous: readonly MemoryItem[], deps: MemoryDeps, now: Date = new Date(),
+  policy: { promotion?: 'sleep-review'; retention?: 'guardian' } = {},
 ): Promise<MemoryItem[]> {
   if (!/^\d{4}-\d\d-\d\d$/.test(day) || new Date(`${day}T00:00:00.000Z`).toISOString().slice(0, 10) !== day) {
     throw new Error('day must be a valid UTC YYYY-MM-DD');
   }
-  return condenseContextWindow(`${day}T00:00:00.000Z`, new Date(Date.parse(`${day}T00:00:00.000Z`) + DAY_MS).toISOString(), previous, deps, now);
+  return condenseContextWindow(`${day}T00:00:00.000Z`, new Date(Date.parse(`${day}T00:00:00.000Z`) + DAY_MS).toISOString(), previous, deps, now, policy);
 }
 
 /** Read-only condensation over an exact rolling UTC window; the caller owns any persistence. */
 export async function condenseContextWindow(
   since: string, until: string, previous: readonly MemoryItem[], deps: MemoryDeps, now: Date = new Date(),
+  policy: { promotion?: 'sleep-review'; retention?: 'guardian' } = {},
 ): Promise<MemoryItem[]> {
-  return (await condenseContextWindowWithReport(since, until, previous, deps, now)).cards;
+  return (await condenseContextWindowWithReport(since, until, previous, deps, now, policy)).cards;
 }
 
 export async function condenseContextWindowWithReport(
   since: string, until: string, previous: readonly MemoryItem[], deps: MemoryDeps, now: Date = new Date(),
+  policy: { promotion?: 'sleep-review'; retention?: 'guardian' } = {},
 ): Promise<CondenseWindowReport> {
   const start = Date.parse(since);
   const end = Date.parse(until);
@@ -228,6 +241,7 @@ export async function condenseContextWindowWithReport(
     try { summary = await deps.summarize(source); }
     catch { skip('summarize-failed', source); continue; }
     bump(funnel.summarized, source.seat);
+    if (policy.promotion === 'sleep-review' && summary.promote !== true) { skip('not-promoted', source); continue; }
     const project = safeLine(summary?.project);
     const topic = safeLine(summary?.topic);
     const text = safeLine(summary?.summary);
@@ -253,17 +267,20 @@ export async function condenseContextWindowWithReport(
     updatedKeys.add(key);
   }
   const cutoff = now.getTime() - 30 * DAY_MS;
-  // Compare only the winning, non-retired assertions; a superseded claim cannot keep a decision candidate alive.
+  // The nightly librarian makes promotion judgments; guardian retention runs at the record boundary.
+  // The ordinary condense command keeps its existing retention behavior.
   const finalItems: MemoryItem[] = [...items.values()].map(({ conflict: _conflict, ...item }) => ({ ...item,
-    status: Date.parse(item.updatedAt) < cutoff ? 'retired' as const : 'active' as const,
+    status: policy.retention === 'guardian' ? item.status
+      : Date.parse(item.updatedAt) < cutoff ? 'retired' as const : 'active' as const,
   }));
   finalItems.sort((a, b) => Date.parse(a.updatedAt) - Date.parse(b.updatedAt) || a.source.localeCompare(b.source)
     || a.seat.localeCompare(b.seat));
   for (let index = 0; index < finalItems.length; index++) {
     const item = finalItems[index]!;
-    if (item.status !== 'active' || !item.claim) continue;
+    if (item.status !== 'active' || !item.claim || (policy.retention === 'guardian' && Date.parse(item.updatedAt) < cutoff)) continue;
     const { key, value } = item.claim;
     const conflicting = finalItems.slice(0, index).find(other => other.status === 'active'
+      && (policy.retention !== 'guardian' || Date.parse(other.updatedAt) >= cutoff)
       && other.project === item.project
       && other.claim?.key === key && other.claim.value !== value);
     if (conflicting) {