elanous 0.2.38 → 0.2.40

package/src/skills/tools/shell.ts

@@ -586,6 +586,8 @@ export interface ShellCompletionNoticeInput {
   ok: boolean;
   exitCode: number | null;
   durationMs: number;
+  /** Full bounded runner result, when the runner resolved normally. */
+  result?: RunnerResult;
   /** Set when ok === false — the runner's failure reason. */
   errorMessage?: string;
   /** Caller-supplied free-form label (RunShell's `description` arg). */
@@ -598,6 +600,29 @@ export interface ShellCompletionNoticeInput {
  *  settle (an id-keyed record here would). */
 const notifiedHandles = new WeakSet<ShellHandle>();
 let nextShellCompletionNoticeId = 0;
+const SHELL_NOTICE_STREAM_TAIL_CHARS = 64;
+
+function shellNoticeTail(output: RunnerResult['stdout'] | undefined): { text: string; truncated: boolean } {
+  if (!output) return { text: '', truncated: false };
+  const source = output.tail ?? output.text;
+  const safe = redactSecretText(source);
+  const chars = Array.from(safe);
+  return {
+    text: shellNoticeJsonField(chars.slice(-SHELL_NOTICE_STREAM_TAIL_CHARS).join('')),
+    truncated: chars.length > SHELL_NOTICE_STREAM_TAIL_CHARS,
+  };
+}
+
+function shellNoticeReason(value: string): string {
+  return redactSecretText(value);
+}
+
+function shellNoticeJsonField(value: string): string {
+  return JSON.stringify(redactSecretText(value)).replace(/\p{White_Space}/gu, (char) => {
+    const hex = char.codePointAt(0)!.toString(16).padStart(4, '0');
+    return `\\u${hex}`;
+  });
+}
 
 /** Enqueue one bg shell-handle completion notice. Returns true when this
  *  handle had not notified before (the notice was handed to `queue`),
@@ -614,15 +639,35 @@ export function enqueueShellCompletionNotice(
   if (notifiedHandles.has(input.handle)) return false;
   notifiedHandles.add(input.handle);
   const header = `RunShell bg handle=${input.handle.id} ${input.ok ? 'completed' : 'failed'}`;
-  const output = `${header}${input.ok || input.exitCode !== null ? ` exitCode=${input.exitCode ?? 'null'}` : ''} elapsed=${input.durationMs}ms${input.errorMessage ? ` error=${input.errorMessage}` : ''}`;
+  const taskId = `shell:${input.handle.id}:${++nextShellCompletionNoticeId}`;
+  const result = input.result;
+  const reason = input.errorMessage ?? result?.failureReason;
+  const reportedExitCode = result?.exitCode ?? input.exitCode;
+  const stdoutTail = shellNoticeTail(result?.stdout);
+  const stderrTail = shellNoticeTail(result?.stderr);
+  const truncated = (result?.truncated ?? false) || stdoutTail.truncated || stderrTail.truncated;
+  const output = [
+    header,
+    `taskId=${taskId}`,
+    `outcome=${result?.outcome ?? 'unknown'}`,
+    ...(result ? [`exitCode=${reportedExitCode ?? 'null'}`]
+      : reportedExitCode !== null ? [`exitCode=${reportedExitCode}`] : []),
+    `elapsed=${input.durationMs}ms`,
+    ...(result ? [`stdoutTail=${stdoutTail.text}`, `stderrTail=${stderrTail.text}`] : []),
+    ...(stdoutTail.truncated ? ['stdoutTailTruncated=true'] : []),
+    ...(stderrTail.truncated ? ['stderrTailTruncated=true'] : []),
+    ...(truncated ? ['truncated=true'] : []),
+    ...(result?.outputFilePath ? [`outputFile=${shellNoticeJsonField(result.outputFilePath)}`] : []),
+    ...(reason ? [`failureReason=${shellNoticeJsonField(reason)}`] : []),
+  ].join(' ');
   queue.enqueue({
-    taskId: `shell:${input.handle.id}:${++nextShellCompletionNoticeId}`,
+    taskId,
     agentName: 'RunShell',
     ...(input.label ? { label: input.label } : {}),
     state: input.ok ? 'done' : 'error',
     output,
-    truncated: false,
-    ...(input.errorMessage ? { errorMessage: input.errorMessage } : {}),
+    truncated,
+    ...(reason ? { errorMessage: shellNoticeReason(reason) } : {}),
     durationMs: input.durationMs,
     finishedAt: Date.now(),
   });
@@ -748,8 +793,9 @@ async function dispatchViaRunner(args: {
           ok,
           exitCode: result.exitCode ?? null,
           durationMs: result.durationMs,
+          result,
           ...(!ok ? { errorMessage: result.exitCode !== undefined
-            ? `exitCode=${result.exitCode}` : `outcome=${result.outcome}` } : {}),
+            ? `exitCode=${result.exitCode}` : result.failureReason ?? `outcome=${result.outcome}` } : {}),
           ...(args.description !== undefined ? { label: args.description } : {}),
         });
       },

package/src/steward/directive-audit.ts

@@ -0,0 +1,354 @@
+// COORD-DIRECTIVE-AUDIT — 지시 원장 행마다 «로직 점검» 을 실제로 실행하는 감사기.
+//
+// 입력: seat-state/OP/directives/CEO-VERBATIM-*.jsonl (ts·kind·원문·상황)
+//       ⊕ seat-state/OP/directives/DIRECTIVES-LEDGER-*.md (지시마다 «로직 점검» 열)
+// 로직: 행마다 점검(원장 · 로그 · config · 원문 hash 조회) 실행 → 거짓이면 «지시 미이행» 경보 ⊕ 수리 칸 제안.
+// 기록: debug.log('coordinator.directive-audit') · 경보·제안 JSONL.
+// 지침 문서 확인으로 갈음하지 않는다 — 판정은 이 코드가 돌려 만든 값이다.
+
+import { appendFileSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { directiveHash } from './directive.js';
+
+export const AUDIT_LOG_CATEGORY = 'coordinator.directive-audit';
+export const VERBATIM_PREFIX = 'CEO-VERBATIM-';
+export const LEDGER_PREFIX = 'DIRECTIVES-LEDGER-';
+export const ALERTS_FILE = 'DIRECTIVE-AUDIT-ALERTS.jsonl';
+export const PROPOSALS_FILE = 'DIRECTIVE-REPAIR-PROPOSALS.jsonl';
+
+const HASH_MARKER = /\[directive-hash:([0-9a-f]{64})\]/;
+
+export interface VerbatimDirective {
+  ts: string;
+  kind: string;
+  text: string;
+  situation?: string;
+  hash: string;
+}
+
+export interface LedgerRow {
+  id: string;
+  text: string;
+  /** «로직 점검» 열 원문 — 예: `log:coordinator.tick`, `config:a.b`, `file:path`. */
+  check: string;
+  hash: string | null;
+}
+
+export interface CheckResult {
+  check: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface DirectiveFinding {
+  directive: string;
+  hash: string | null;
+  status: 'ok' | 'mismatch';
+  reasons: string[];
+  checks: CheckResult[];
+}
+
+export interface DirectiveAlert {
+  kind: 'directive-unfulfilled';
+  directive: string;
+  hash: string | null;
+  reasons: string[];
+  at: string;
+}
+
+export interface RepairProposal {
+  id: string;
+  title: string;
+  body: string;
+  source: 'directive-audit';
+  at: string;
+}
+
+export interface DirectiveAuditReport {
+  at: string;
+  directives: number;
+  checked: number;
+  passed: number;
+  findings: DirectiveFinding[];
+  alerts: DirectiveAlert[];
+  proposals: RepairProposal[];
+  logged: boolean;
+}
+
+export interface DirectiveAuditDeps {
+  /** 격리 root — `file:` 점검의 기준점 겸 기본 원장 위치의 부모. */
+  root?: string;
+  /** 원장·원문 로그가 있는 디렉터리(생략 시 `<root>/seat-state/OP/directives`). */
+  dir?: string;
+  now?: () => Date;
+  readFile?: (path: string) => string | null;
+  listFiles?: (path: string) => string[];
+  /** config 조회(점 표기 키). 기본은 환경 변수 조회. */
+  config?: (key: string) => string | undefined;
+  /** 로그 조회. 기본은 debug 링 버퍼 꼬리. */
+  logLines?: () => string[];
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  recordAlert?: (alert: DirectiveAlert) => void;
+  proposeRepair?: (proposal: RepairProposal) => void;
+}
+
+const readFileOrNull = (path: string): string | null => {
+  try { return readFileSync(path, 'utf8'); } catch { return null; }
+};
+
+const listFilesIn = (path: string): string[] => {
+  try { return readdirSync(path).sort(); } catch { return []; }
+};
+
+/** 원문 jsonl → 지시 행. 행 식별자는 기존 `directiveHash` 규약(NFKC·공백압축·소문자)을 그대로 쓴다. */
+export function parseVerbatimJsonl(body: string): VerbatimDirective[] {
+  const out: VerbatimDirective[] = [];
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (line === '') continue;
+    let row: Record<string, unknown>;
+    try { row = JSON.parse(line) as Record<string, unknown>; } catch { continue; }
+    const text = typeof row.text === 'string' ? row.text : typeof row['원문'] === 'string' ? (row['원문'] as string) : '';
+    const ts = typeof row.ts === 'string' ? row.ts : '';
+    if (text.trim() === '') continue;
+    out.push({
+      ts,
+      kind: typeof row.kind === 'string' ? row.kind : 'directive',
+      text,
+      ...(typeof row.situation === 'string' ? { situation: row.situation } : {}),
+      hash: directiveHash(text),
+    });
+  }
+  return out;
+}
+
+const cells = (line: string): string[] =>
+  line.replace(/^\|/, '').replace(/\|$/, '').split('|').map(cell => cell.trim());
+
+const isSeparator = (line: string): boolean => {
+  const parts = cells(line);
+  return parts.length > 0 && parts.every(part => /^:?-{2,}:?$/.test(part));
+};
+
+/** 원장 마크다운 → 행. «로직 점검» 열과 `[directive-hash:<hash>]` 표기를 그대로 읽는다. */
+export function parseDirectivesLedger(body: string): LedgerRow[] {
+  const lines = body.split('\n');
+  const headerAt = lines.findIndex(line => line.trim().startsWith('|') && line.includes('로직 점검'));
+  if (headerAt < 0) return [];
+  const header = cells(lines[headerAt]!);
+  const checkIdx = header.findIndex(cell => cell.includes('로직 점검'));
+  const textIdx = header.findIndex(cell => cell.includes('원문'));
+  const hashIdx = header.findIndex(cell => /해시|hash/i.test(cell));
+  const idIdx = header.findIndex(cell => cell !== '' && !cell.includes('로직 점검') && !cell.includes('원문') && !/해시|hash/i.test(cell));
+
+  const rows: LedgerRow[] = [];
+  for (const line of lines.slice(headerAt + 1)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) {
+      if (rows.length > 0) break;
+      continue;
+    }
+    if (isSeparator(trimmed)) continue;
+    const parts = cells(trimmed);
+    if (parts.every(part => part === '')) continue;
+    const marker = HASH_MARKER.exec(trimmed);
+    const hashCell = hashIdx >= 0 ? parts[hashIdx] ?? '' : '';
+    const cellMarker = HASH_MARKER.exec(hashCell);
+    const hash = cellMarker ? cellMarker[1]! : marker ? marker[1]! : null;
+    const id = (idIdx >= 0 ? parts[idIdx] ?? '' : '').replace(HASH_MARKER, '').trim();
+    const textCell = (textIdx >= 0 ? parts[textIdx] ?? '' : '').replace(/<!--[\s\S]*?-->/g, '').trim();
+    rows.push({
+      id: id !== '' ? id : textCell,
+      text: textCell !== '' ? textCell : id,
+      check: (parts[checkIdx] ?? '').replace(/<!--[\s\S]*?-->/g, '').trim(),
+      hash,
+    });
+  }
+  return rows;
+}
+
+const envConfig = (key: string): string | undefined => {
+  const direct = process.env[key];
+  if (direct !== undefined && direct !== '') return direct;
+  const mangled = `ELANOUS_${key.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}`;
+  const viaEnv = process.env[mangled];
+  return viaEnv !== undefined && viaEnv !== '' ? viaEnv : undefined;
+};
+
+interface CheckContext {
+  baseDir: string;
+  dir: string;
+  read: (path: string) => string | null;
+  config: (key: string) => string | undefined;
+  logLines: () => string[];
+  verbatimHashes: Set<string>;
+}
+
+/** 점검 한 줄 실행 — 원장·로그·config·원문 hash 조회. */
+export function runCheck(check: string, ctx: CheckContext): CheckResult {
+  const spec = check.trim();
+  if (spec === '') return { check, ok: false, detail: '점검 없음 — 로직 점검 열이 비어 있다' };
+
+  const [kind, ...rest] = spec.split(':');
+  const arg = rest.join(':').trim();
+
+  if (kind === 'log') {
+    if (arg === '') return { check, ok: false, detail: 'log 점검에 카테고리가 없다' };
+    const hit = ctx.logLines().some(line => line.includes(arg));
+    return { check, ok: hit, detail: hit ? `로그에 ${arg} 발견` : `로그에 ${arg} 없음` };
+  }
+
+  if (kind === 'config') {
+    const [key, expected] = arg.split('=');
+    const value = ctx.config((key ?? '').trim());
+    const absent = value === undefined || value === '';
+    const ok = !absent && (expected === undefined || value === expected.trim());
+    return { check, ok, detail: absent ? `config ${key} 없음` : `config ${key}=${value}` };
+  }
+
+  if (kind === 'file') {
+    const body = ctx.read(arg.startsWith('/') ? arg : join(ctx.baseDir, arg));
+    const ok = body !== null && body.trim() !== '';
+    return { check, ok, detail: ok ? `파일 ${arg} 존재` : `파일 ${arg} 없음` };
+  }
+
+  if (kind === 'hash') {
+    const ok = ctx.verbatimHashes.has(arg);
+    return { check, ok, detail: ok ? `원문 hash ${arg.slice(0, 12)} 확인` : `원문 hash ${arg.slice(0, 12)} 없음` };
+  }
+
+  return { check, ok: false, detail: `알 수 없는 점검 형식: ${spec}` };
+}
+
+const defaultDir = (root: string | undefined): string =>
+  join(root ?? process.cwd(), 'seat-state', 'OP', 'directives');
+
+function buildContext(deps: DirectiveAuditDeps, dir: string, verbatimHashes: Set<string>): CheckContext {
+  return {
+    baseDir: deps.root ?? dir,
+    dir,
+    read: deps.readFile ?? readFileOrNull,
+    config: deps.config ?? envConfig,
+    logLines: deps.logLines ?? (() => debug.tail(400)),
+    verbatimHashes,
+  };
+}
+
+const proposalId = (hash: string | null, directive: string): string =>
+  `DIRREPAIR-${(hash ?? directiveHash(directive)).slice(0, 8)}`;
+
+/** 부작용 없는 점검 — 보고서만 만든다. */
+export function inspectDirectives(deps: DirectiveAuditDeps = {}): DirectiveAuditReport {
+  const at = (deps.now?.() ?? new Date()).toISOString();
+  const dir = deps.dir ?? defaultDir(deps.root);
+  const list = deps.listFiles ?? listFilesIn;
+  const read = deps.readFile ?? readFileOrNull;
+
+  const names = list(dir);
+  const verbatim = names
+    .filter(name => name.startsWith(VERBATIM_PREFIX) && name.endsWith('.jsonl'))
+    .flatMap(name => parseVerbatimJsonl(read(join(dir, name)) ?? ''));
+  const rows = names
+    .filter(name => name.startsWith(LEDGER_PREFIX) && name.endsWith('.md'))
+    .flatMap(name => parseDirectivesLedger(read(join(dir, name)) ?? ''));
+
+  const verbatimHashes = new Set(verbatim.map(row => row.hash));
+  const ctx = buildContext(deps, dir, verbatimHashes);
+  const findings: DirectiveFinding[] = [];
+  const alerts: DirectiveAlert[] = [];
+  const proposals: RepairProposal[] = [];
+
+  const alert = (directive: string, hash: string | null, reasons: string[], checks: CheckResult[]) => {
+    findings.push({ directive, hash, status: 'mismatch', reasons, checks });
+    alerts.push({ kind: 'directive-unfulfilled', directive, hash, reasons, at });
+    proposals.push({
+      id: proposalId(hash, directive),
+      title: `[수리 칸 제안] 지시 미이행 — ${directive}`,
+      body: [
+        `지시: ${directive}`,
+        hash === null ? 'directive-hash: (없음)' : `directive-hash: ${hash}`,
+        `불일치: ${reasons.join(' / ')}`,
+        '조치: 원장 «로직 점검» 열을 실제 근거(로그·config·산출물)로 고치거나, 지시를 이행한 뒤 근거를 남긴다.',
+      ].join('\n'),
+      source: 'directive-audit',
+      at,
+    });
+  };
+
+  for (const row of rows) {
+    const checks: CheckResult[] = [];
+    const reasons: string[] = [];
+    if (row.check === '') {
+      reasons.push('로직 점검 열이 비어 있다');
+    } else {
+      const result = runCheck(row.check, ctx);
+      checks.push(result);
+      if (!result.ok) reasons.push(`로직 점검 실패: ${row.check}`);
+    }
+    if (row.hash !== null && !verbatimHashes.has(row.hash)) {
+      reasons.push(`원문 로그에 없는 directive-hash: ${row.hash}`);
+    }
+    if (reasons.length > 0) {
+      alert(row.id, row.hash, reasons, checks);
+    } else {
+      findings.push({ directive: row.id, hash: row.hash, status: 'ok', reasons, checks });
+    }
+  }
+
+  for (const verbatimRow of verbatim) {
+    const covered = rows.some(row => row.hash === verbatimRow.hash);
+    if (covered) continue;
+    alert(verbatimRow.text, verbatimRow.hash, ['원장 행 없음 — 로직 점검 열이 없다'], []);
+  }
+
+  const checked = findings.filter(finding => finding.checks.length > 0).length;
+  const passed = findings.filter(finding => finding.status === 'ok').length;
+
+  return {
+    at,
+    directives: findings.length,
+    checked,
+    passed,
+    findings,
+    alerts,
+    proposals,
+    logged: false,
+  };
+}
+
+const appendJsonl = (path: string, row: unknown): void => {
+  mkdirSync(join(path, '..'), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(row)}\n`);
+};
+
+/**
+ * 조율자 틱마다 부르는 감사 진입점 — 점검 실행 → 경보·수리 제안 기록 →
+ * debug.log('coordinator.directive-audit').
+ */
+export function runDirectiveAudit(deps: DirectiveAuditDeps = {}): DirectiveAuditReport {
+  const report = inspectDirectives(deps);
+  if (report.directives === 0) return report;
+
+  const dir = deps.dir ?? defaultDir(deps.root);
+  const recordAlert = deps.recordAlert ?? ((alert: DirectiveAlert) => appendJsonl(join(dir, ALERTS_FILE), alert));
+  const proposeRepair = deps.proposeRepair ?? ((proposal: RepairProposal) => appendJsonl(join(dir, PROPOSALS_FILE), proposal));
+
+  for (const alert of report.alerts) recordAlert(alert);
+  for (const proposal of report.proposals) proposeRepair(proposal);
+
+  const data = {
+    directives: report.directives,
+    checked: report.checked,
+    passed: report.passed,
+    alerts: report.alerts.length,
+  };
+  const message = report.alerts.length === 0
+    ? `지시 원장 점검 ${report.directives}행 · 불일치 0`
+    : `지시 원장 점검 ${report.directives}행 · 불일치 ${report.alerts.length}`;
+
+  const log = deps.log ?? ((category: string, event: string, payload: Record<string, unknown>) => debug.log(category, event, payload));
+  log(AUDIT_LOG_CATEGORY, message, data);
+
+  return { ...report, logged: true };
+}

package/src/surface/child-process.ts

@@ -0,0 +1,31 @@
+/** Forward a piped child stderr stream through the current surface's stderr
+ *  owner. TUI boot captures this stream into logs and one-line notices. */
+export function forwardChildStderr(stream: NodeJS.ReadableStream | null | undefined): void {
+  stream?.on('data', (chunk: Buffer | string) => process.stderr.write(chunk));
+}
+
+/** Shared child-process boundary for commands that need terminal progress.
+ *  stdin is closed, stdout/stderr are piped, and stderr is forwarded through
+ *  the owning surface's stderr stream, so TUI boot can turn it into a log
+ *  entry and a one-line notice. */
+export function spawnWithOwnedStderr(
+  command: string[],
+  options: Omit<Bun.SpawnOptions.OptionsObject<'ignore', 'pipe', 'pipe'>, 'cmd' | 'stdin' | 'stdout' | 'stderr'> = {},
+): ReturnType<typeof Bun.spawn> {
+  const child = Bun.spawn(command, { ...options, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+  if (child.stderr) {
+    const reader = child.stderr.getReader();
+    void (async () => {
+      try {
+        while (true) {
+          const next = await reader.read();
+          if (next.done) break;
+          process.stderr.write(next.value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+  }
+  return child;
+}

package/src/surface/tui-stderr-owner.ts

@@ -0,0 +1,48 @@
+import { debug } from '../debug/log.js';
+
+export type TuiStderrNotice = (line: string) => void;
+
+/** Take ownership of writes made through the TUI process' stderr stream.
+ *  Raw bytes go to the normal debug log; the presentation surface receives
+ *  bounded one-line notices. Child processes must still use piped stderr:
+ *  an OS-level fd 2 inherited by a child bypasses this JavaScript stream. */
+export function installTuiStderrOwner(notice: TuiStderrNotice): () => void {
+  const stderr = process.stderr;
+  const originalWrite = stderr.write;
+  let pending = '';
+  let active = true;
+
+  const emit = (raw: string): void => {
+    if (!raw) return;
+    try {
+      debug.log('tui.stderr', 'captured', { text: raw, byteLength: Buffer.byteLength(raw, 'utf8') });
+    } catch { /* capture must not re-open the physical stderr path */ }
+    const compact = raw.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/\s+/g, ' ').trim();
+    if (compact) {
+      try { notice(compact.length > 240 ? `${compact.slice(0, 239)}…` : compact); }
+      catch { /* renderer failure must not overwrite the prompt */ }
+    }
+  };
+
+  const write = ((chunk: string | Uint8Array, encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void), callback?: (error?: Error | null) => void): boolean => {
+    const text = typeof chunk === 'string'
+      ? chunk
+      : Buffer.from(chunk).toString(typeof encodingOrCallback === 'string' ? encodingOrCallback : 'utf8');
+    pending += text;
+    const lines = pending.split(/\r?\n/);
+    pending = lines.pop() ?? '';
+    for (const line of lines) emit(line);
+    if (typeof encodingOrCallback === 'function') encodingOrCallback();
+    else callback?.();
+    return true;
+  }) as typeof stderr.write;
+
+  stderr.write = write;
+  return () => {
+    if (!active) return;
+    active = false;
+    if (stderr.write === write) stderr.write = originalWrite;
+    emit(pending);
+    pending = '';
+  };
+}

package/src/task-agent/cover.ts

@@ -34,7 +34,11 @@ export interface TaskAgentCoverInput {
   /** null means the pending-landing age source could not be read; [] means no pending landings. */
   pendingLandingAgeSeconds?: readonly number[] | null;
   /** A source reached the query safety limit; its aggregate is not known to be complete. */
-  truncated?: { taskAgentActions: boolean; allLands: boolean; liveLandMoves?: boolean; goalAsks?: boolean; goalRuns?: boolean; implementCardRuns?: boolean; implementRunMerges?: boolean };
+  truncated?: { taskAgentActions: boolean; allLands: boolean; liveLandMoves?: boolean; goalAsks?: boolean; goalRuns?: boolean; implementCardRuns?: boolean; implementRunMerges?: boolean; cleanupCards?: boolean };
+  /** The physical read failed, as distinct from a reader explicitly returning null. */
+  implementReadFailure?: 'card-ledger-unreadable' | 'run-ledger-unreadable';
+  /** Confirmed post-land outcomes from the TA card ledger. undefined = not wired; null = unreadable. */
+  cleanupCards?: readonly { cardId: string; outcome: 'complete' | 'partial' }[] | null;
   /** Completed authoring provenance and terminal goal records. undefined = not wired; null = unreadable. */
   goalAsks?: readonly { authorRunId: string; goalId: string }[] | null;
   goalRuns?: readonly { goalId: string; outcome: string; stage?: string }[] | null;
@@ -205,10 +209,10 @@ export type SevenVerbState = 'live' | 'shadow-only' | 'none' | 'no-source' | 'un
 /** 7동사 출처 표의 한 칸 — source 는 그 동사를 관측하는 원천, null 이면 출처가 아직 없다. */
 export interface SevenVerbSource {
   verb: SevenVerbName;
-  source: Exclude<NextActionKind, 'decision' | 'deliver'> | 'goal-ask+goal-run' | 'card-run+merged' | null;
+  source: Exclude<NextActionKind, 'decision' | 'deliver'> | 'goal-ask+goal-run' | 'card-run+merged' | 'card:postland-card+postLand' | null;
 }
 
-/** TA-THEME-VERBS-LIVE — 저작은 완료 골 조인; 구현은 카드 런 결합 ⊕ 원장 merged 조인; 정리는 아직 출처가 없다. */
+/** TA-THEME-VERBS-LIVE — 저작은 완료 골 조인; 구현은 카드 런 ⊕ merged 원장; 정리는 카드 postland 이력. */
 export const SEVEN_VERB_SOURCES: readonly SevenVerbSource[] = [
   { verb: '리뷰', source: 'review' },
   { verb: '착지', source: 'land' },
@@ -216,7 +220,7 @@ export const SEVEN_VERB_SOURCES: readonly SevenVerbSource[] = [
   { verb: '검증', source: 'green' },
   { verb: '저작', source: 'goal-ask+goal-run' },
   { verb: '구현', source: 'card-run+merged' },
-  { verb: '정리', source: null },
+  { verb: '정리', source: 'card:postland-card+postLand' },
 ];
 
 /** 동사 하나의 관측 — 원장을 못 읽었으면 liveDone·shadow 는 null(0 이 아니다). */
@@ -226,6 +230,8 @@ export interface SevenVerbLiveRow {
   liveDone: number | null;
   shadow: number | null;
   state: SevenVerbState;
+  /** Present only for an unreadable implementation source. */
+  reason?: 'card-ledger-null' | 'run-ledger-null' | 'card-ledger-truncated' | 'run-ledger-truncated' | 'card-ledger-unreadable' | 'run-ledger-unreadable' | 'card-binding-invalid';
 }
 
 /** 합계 — liveVerbs 는 원장을 못 읽었으면 null(0 으로 쓰지 않는다) · measuredVerbs 는 출처 있는 동사 수. */
@@ -244,15 +250,17 @@ export function measureSevenVerbLive(input: TaskAgentCoverInput): SevenVerbLive
       if (input.implementCardRuns === undefined && input.implementRunMerges === undefined) {
         return { verb, source: null, liveDone: null, shadow: null, state: 'no-source' };
       }
-      if (input.implementCardRuns == null || input.implementRunMerges == null
-        || input.truncated?.implementCardRuns === true || input.truncated?.implementRunMerges === true) {
-        return { verb, source, liveDone: null, shadow: null, state: 'unreadable' };
-      }
-      const merges = input.implementRunMerges;
+      const reason = input.implementReadFailure
+        ?? (input.implementCardRuns == null ? 'card-ledger-null'
+          : input.implementRunMerges == null ? 'run-ledger-null'
+            : input.truncated?.implementCardRuns ? 'card-ledger-truncated'
+              : input.truncated?.implementRunMerges ? 'run-ledger-truncated' : null);
+      if (reason) return { verb, source, liveDone: null, shadow: null, state: 'unreadable', reason };
+      const merges = input.implementRunMerges ?? new Map();
       const cards = new Set<string>();
-      for (const binding of input.implementCardRuns) {
+      for (const binding of input.implementCardRuns ?? []) {
         // 카드 신원 없이는 중복 없는 분자를 낼 수 없다 — 그 원장은 못 읽은 것으로 한다.
-        if (!binding.cardId) return { verb, source, liveDone: null, shadow: null, state: 'unreadable' };
+        if (!binding.cardId) return { verb, source, liveDone: null, shadow: null, state: 'unreadable', reason: 'card-binding-invalid' };
         const bound = [binding.runId, binding.runChildId];
         if (bound.some((runId) => typeof runId === 'string' && runId && merges.get(runId)?.merged === true)) {
           cards.add(binding.cardId);
@@ -261,6 +269,12 @@ export function measureSevenVerbLive(input: TaskAgentCoverInput): SevenVerbLive
       const liveDone = cards.size;
       return { verb, source, liveDone, shadow: 0, state: liveDone >= 1 ? 'live' : 'none' };
     }
+    if (source === 'card:postland-card+postLand') {
+      if (input.cleanupCards === undefined) return { verb, source: null, liveDone: null, shadow: null, state: 'no-source' };
+      if (input.cleanupCards === null || input.truncated?.cleanupCards) return { verb, source, liveDone: null, shadow: null, state: 'unreadable' };
+      const liveDone = new Set(input.cleanupCards.filter((card) => card.outcome === 'complete').map((card) => card.cardId)).size;
+      return { verb, source, liveDone, shadow: 0, state: liveDone > 0 ? 'live' : 'none' };
+    }
     if (source === null) return { verb, source: null, liveDone: null, shadow: null, state: 'no-source' };
     if (source !== 'goal-ask+goal-run' && (unreadable || (source === 'land'
       && (input.liveLandMoves == null || input.truncated?.liveLandMoves)))) {
@@ -296,14 +310,18 @@ export function formatSevenVerbLive(measurement: SevenVerbLive): string {
     const landUnreadable = measurement.verbs.some((row) => row.source === 'land' && row.state === 'unreadable');
     const authorUnreadable = measurement.verbs.some((row) => row.source === 'goal-ask+goal-run' && row.state === 'unreadable');
     const implementUnreadable = measurement.verbs.some((row) => row.source === 'card-run+merged' && row.state === 'unreadable');
+    const cleanupUnreadable = measurement.verbs.some((row) => row.source === 'card:postland-card+postLand' && row.state === 'unreadable');
     const failures = [
       actionUnreadable ? '행동' : landUnreadable ? '착지' : null,
       authorUnreadable ? '저작·골' : null,
       implementUnreadable ? '구현 카드·런' : null,
+      cleanupUnreadable ? '정리 카드' : null,
     ].filter((part): part is string => part !== null);
     const reason = `${failures.join('·') || '저작·골'} 원장 null·절단`;
+    const physicalFailure = measurement.verbs.find((row) => row.verb === '구현')?.reason;
+    const detail = physicalFailure?.endsWith('-unreadable') ? ` · 구현 원인 ${physicalFailure}` : '';
     const noSource = measurement.verbs.filter((row) => row.state === 'no-source').map((row) => row.verb).join('·');
-    return `${total}동사 live -/${total} · 못 잼(${reason})${noSource ? ` · 출처 없음 ${noSource}` : ''}`;
+    return `${total}동사 live -/${total} · 못 잼(${reason})${detail}${noSource ? ` · 출처 없음 ${noSource}` : ''}`;
   }
   const noSource = measurement.verbs.filter((row) => row.state === 'no-source').map((row) => row.verb).join('·');
   return `${total}동사 live ${measurement.liveVerbs}/${total}${noSource ? ` · 출처 없음 ${noSource}` : ''}`;