elanous 0.2.23 → 0.2.25

package/src/steward/triage.ts

@@ -8,6 +8,10 @@ import { getUserConfig } from '../user-config.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { debug, redactSecretText } from '../debug/log.js';
 import { loopEvent } from '../loops/observe.js';
+import { checkLoops, daemonScheduleEntries, entriesFromRegistry, extendHealthyLauncher, launcherEvidence, notifyOwners, scheduleFindings, versionEvidence, type CheckEntry } from '../loops/checker.js';
+import { listSchedules, schedulesDbPath, type ScheduleRow } from '../domains/schedule-registry.js';
+import { Database } from 'bun:sqlite';
+import { defaultLoopRoot, listAllLoops, listLoops } from '../loops/registry.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { redactSecrets } from '../task-cards/card-store.js';
 import { directiveHash } from './directive.js';
@@ -17,7 +21,7 @@ import { planLaunches, launch, collectOutcomes, raiseHitl, readLaunchLedger, sav
 import { listFabricExecutionCandidates } from '../self-dev/fabric-plan-core.js';
 import { InvalidWorkingBackwardsDraft, recordWorkingBackwardsOnCards } from './working-backwards.js';
 import { CardStore } from '../task-cards/card-store.js';
-import { triageWithinBudget } from './triage-budget.js';
+import { draftWithinBudget, triageWithinBudget } from './triage-budget.js';
 import { askSteward, classifyIssue, installedCapabilities, planIssues, ruleJudgment, unsafeReason, type ClassifiedIssue, type StewardAsk } from './triage-plan.js';
 import { failureAlertText, markStageStart, markStageEnd, readFailureStreak, shouldAlert, writeFailureStreak, type FailureStreak, type StewardStage } from './failure-streak.js';
 
@@ -59,6 +63,8 @@ export interface StewardDeps {
   ask?: StewardAsk;
   /** Maximum time for each working-backwards wish draft in schedule (milliseconds). */
   draftItemMs?: number;
+  /** Maximum time for the whole wish-drafting phase in schedule (milliseconds); wishes still undrafted are carried. */
+  draftDeadlineMs?: number;
   launchSettings?: Pick<StewardSettings, 'mode' | 'launch' | 'maxParallel' | 'podPool'>;
   launchCommand?: LaunchDeps['command'];
   spawnLaunch?: LaunchDeps['spawn'];
@@ -68,6 +74,9 @@ export interface StewardDeps {
   outcomeNotify?: Pick<OutcomeNotifyDeps, 'document' | 'message' | 'worktreeCommand' | 'loadOrigin' | 'loadOrigins'>;
   /** Internal command boundary: the current sync has already claimed this pid. */
   stageOwnedByCommand?: boolean;
+  /** Isolated scheduler inventory for this tick; production reads the unified registry. */
+  scheduleInventory?: () => CheckEntry[];
+  daemonSchedules?: () => ScheduleRow[];
 }
 
 /** rescue launches/harvests like live (HQ-SEAT). */
@@ -314,6 +323,61 @@ function logStageFailure(root: string, stage: StewardStage, reason: string): voi
   if (runId) try { rmSync(tickDecisionPath(root, runId), { force: true }); } catch { /* Observation must not change the failure. */ }
   logTickDecision(root, 'failed', `${stage}: ${reason}`);
 }
+const SCHEDULE_CHECK_MS = 15 * 60_000;
+
+/** Called by runStewardStage(sync) under its stage slot, never from the checker CLI. */
+async function checkStewardSchedules(root: string, settings: StewardSettings, deps: StewardDeps): Promise<void> {
+  const now = (deps.now ?? (() => new Date()))();
+  const marker = join(root, 'steward', 'schedule-check.json');
+  let previous: { at?: string } = {};
+  try { previous = JSON.parse(readFileSync(marker, 'utf8')) as typeof previous; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  const elapsed = now.getTime() - Date.parse(previous.at ?? '');
+  if (Number.isFinite(elapsed) && elapsed >= 0 && elapsed < SCHEDULE_CHECK_MS) return;
+  const inventory = deps.scheduleInventory ?? (() => {
+    const repo = deps.root ? process.cwd() : defaultLoopRoot();
+    const registryOptions = { now, root: repo, stateRoot: root,
+      ...(deps.root ? { schedules: [] } : {}) };
+    const { entries } = entriesFromRegistry({ now, listAllLoops: () => listAllLoops(registryOptions) });
+    const graphs = listLoops(registryOptions);
+    const byId = new Map(graphs.map(graph => [graph.id, graph.file]));
+    return versionEvidence(launcherEvidence(entries.map(entry => byId.has(entry.id)
+      ? { ...entry, file: byId.get(entry.id) } : entry), root), repo, root);
+  });
+  const daemonRows = deps.daemonSchedules ?? (() => {
+    const path = deps.root ? join(root, 'schedules.db') : schedulesDbPath();
+    if (!existsSync(path)) return [];
+    try {
+      const db = new Database(path, { readonly: true });
+      try { return listSchedules(db); } finally { db.close(); }
+    } catch (error) {
+      debug.log('steward.schedule-check', 'daemon-inventory-unavailable', { reason: redactSecretText(String(error)) });
+      return [];
+    }
+  });
+  const entries = inventory();
+  const seen = new Set(entries.map(entry => entry.id));
+  const checked = checkLoops([...entries, ...daemonScheduleEntries(daemonRows(), now).filter(row => !seen.has(row.id))], now);
+  const findings = scheduleFindings(checked, now);
+  if (settings.mode === 'live') {
+    let recovered = 0;
+    const unresolved = findings.filter(finding => {
+      try {
+        if (extendHealthyLauncher(root, finding, now)) { recovered++; return false; }
+      } catch (error) {
+        debug.log('steward.schedule-check', 'recovery-failed', { id: finding.id, reason: redactSecretText(String(error)) });
+      }
+      return true;
+    });
+    const remainingChecks = checked.filter(row => unresolved.some(finding => finding.id === row.id && finding.kind === row.state));
+    const ownerRequests = notifyOwners(remainingChecks, { root, now }, unresolved);
+    const opEscalations = notifyOwners(remainingChecks, { root, now }, unresolved, true);
+    debug.log('steward.schedule-check', 'routing', { ownerRequests, opEscalations, recovered });
+  }
+  debug.log('steward.schedule-check', 'checked', { count: checked.length, findings: findings.length, mode: settings.mode });
+  writeFileSync(marker, JSON.stringify({ at: now.toISOString() }));
+}
+
 function readState(path: string): { issues: Record<string, string>; digestDay?: string } {
   try { return JSON.parse(readFileSync(path, 'utf8')) as ReturnType<typeof readState>; }
   catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { issues: {} }; throw error; }
@@ -343,6 +407,11 @@ export async function runStewardStage(stage: 'sync' | 'triage' | 'schedule' | 'r
   const runId = (graphRunId() ?? process.env.ELANOUS_RUN_ID?.trim()) || `steward-stage-${randomUUID()}`;
   let outcome: 'ok' | 'fail' = 'fail';
   try {
+  if (stage === 'sync') {
+    // The schedule check is an add-on to sync: its failure is observed, never allowed to stop the Linear sync.
+    try { await checkStewardSchedules(root, settings, deps); }
+    catch (error) { debug.log('steward.schedule-check', 'failed', { reason: redactSecretText(String(error)) }, { level: 'warn' }); }
+  }
   const key = await (deps.getSecret ?? getSecretAsync)('connector.linear.apiKey');
   if (!key) throw new Error('connector.linear.apiKey missing');
   if (stage === 'sync') {
@@ -420,27 +489,19 @@ export async function runStewardStage(stage: 'sync' | 'triage' | 'schedule' | 'r
       const carried = new Set<string>();
       if (store) try {
         recordTriageOnCards(wishes, issues, { root, store, now: deps.now });
-        for (const wish of wishes) {
-          const timedOut = Symbol('draft-timeout');
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          const timeout = new Promise<never>((_, reject) => {
-            timer = setTimeout(() => reject(timedOut), deps.draftItemMs ?? 120_000);
-          });
-          // The draft may finish without ever racing this promise (no ask needed) — never leave its rejection unhandled.
-          timeout.catch(() => undefined);
-          try {
-            // Bound the ask itself so a late answer cannot write to a store closed after this tick.
-            const ask: StewardAsk = (prompt, role) => Promise.race([(deps.ask ?? askSteward)(prompt, role), timeout]);
-            await recordWorkingBackwardsOnCards([wish], issues, store, ask);
-          } catch (error) {
-            if (error instanceof InvalidWorkingBackwardsDraft) {
-              invalid.add(wish.issue);
-              debug.log('steward.stage', 'draft-invalid', { issue: wish.issue });
-            } else {
-              carried.add(wish.issue);
-              debug.log('steward.schedule', 'draft-carried', { issue: wish.issue, reason: error === timedOut ? 'timeout' : 'error' });
-            }
-          } finally { if (timer) clearTimeout(timer); }
+        const outcome = await draftWithinBudget({
+          wishes, perItemMs: deps.draftItemMs ?? 120_000, deadlineMs: deps.draftDeadlineMs ?? 240_000,
+          // Bound the ask itself so a late answer cannot write to a store closed after this tick.
+          draft: (wish, expired) => recordWorkingBackwardsOnCards([wish], issues, store,
+            (prompt, role) => Promise.race([(deps.ask ?? askSteward)(prompt, role), expired])),
+        });
+        for (const wish of outcome.invalid) {
+          invalid.add(wish.issue);
+          debug.log('steward.stage', 'draft-invalid', { issue: wish.issue });
+        }
+        for (const { wish, reason } of outcome.carried) {
+          carried.add(wish.issue);
+          debug.log('steward.schedule', 'draft-carried', { issue: wish.issue, reason });
         }
       } finally { if (!deps.cardStore) store.close(); }
       if (invalid.size || carried.size) rows = rows.map(row => invalid.has(row.issue)

package/src/task-agent/actions.ts

@@ -1,7 +1,7 @@
 import { copyFileSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { debug } from '../debug/log.js';
-import { judgeNextMove } from './judge.js';
+import { judgeNextMove, retryMoveOf, SAME_MOVE_FAILURE_LIMIT } from './judge.js';
 import { checkCompletionEvidence } from './completion-evidence.js';
 
 export type DeliveryKind = 'research-report' | 'artifact' | 'content';
@@ -65,6 +65,48 @@ export interface ActionDeps {
   /** 실패 한 번을 잠금 안에서 디스크에 더한다(다른 프로세스의 실패를 덮지 않게) · 더한 뒤의 값을 돌려준다. */
   incrementFailure?(key: string): number;
   observe(event: 'task-agent.action', data: { taskId: string; kind: NextActionKind; result: string; reason: string }): void;
+  /** 사다리 R4 — 실제로 할 재발사 수의 허용 목록(`taskAgent.liveMoves` 어휘). 없으면 종전 그대로(재발사에 목록 검사 없음) · 목록에 없는 수는 shadow. */
+  liveMoves?: ReadonlySet<string>;
+  /** 한 판단 회차의 발사 칸 — 호출부가 회차마다 새로 준다. 없으면 회당 상한 없음(종전). 발사를 시도할 때마다 `count` 가 오른다. */
+  retryLaunches?: { count: number };
+  /** mbp 부하 관문(OP 신호 `loadMax`) — 지금 1분 부하가 `loadMax` 이상이거나 못 읽으면 발사하지 않고 shadow. 없으면 관문 없음(종전). */
+  loadGate?: { loadMax: number; load1(): number | null };
+}
+
+/** 재발사는 한 판단 회차에 한 건만 발사한다. */
+export const RETRY_LAUNCHES_PER_CYCLE = 1;
+
+/** live 인데도 shadow 로 내릴 사유 — 없으면 발사해도 된다(재발사 아닌 수는 늘 없다). 기다림(wait)은 발사가 아니라 부하·회당 상한을 보지 않는다. */
+function retryShadowReason(action: NextAction, deps: ActionDeps): string | undefined {
+  if (action.kind !== 'retry') return undefined;
+  const move = retryMoveOf(action.variant);
+  if (deps.liveMoves && !deps.liveMoves.has(move)) return `${move} not in live allow-list`;
+  if (action.variant === 'wait') return undefined;
+  if (deps.loadGate) {
+    const load = deps.loadGate.load1();
+    if (load === null || !Number.isFinite(load)) return `load gate: load unreadable (loadMax ${deps.loadGate.loadMax})`;
+    if (load >= deps.loadGate.loadMax) return `load gate: load ${load} >= loadMax ${deps.loadGate.loadMax}`;
+  }
+  if (deps.retryLaunches && deps.retryLaunches.count >= RETRY_LAUNCHES_PER_CYCLE) return `one relaunch per cycle already used (${move})`;
+  return undefined;
+}
+
+/** 결정 카드가 «근거»로 쓰는 세 칸 — 막힌 과제의 서명 · 막힌 화면 · 리뷰 must-fix. */
+export interface DecisionCardEvidence { signature?: string; screen?: string; mustFix?: readonly string[] }
+
+/** 비지 않은 근거 칸 이름들 — 비어 있으면 카드를 올리지 않는다(근거 없는 카드 0). */
+export function decisionCardGrounds(evidence: DecisionCardEvidence | undefined): Array<'signature' | 'screen' | 'must-fix'> {
+  const grounds: Array<'signature' | 'screen' | 'must-fix'> = [];
+  if (evidence?.signature?.trim()) grounds.push('signature');
+  if (evidence?.screen?.trim()) grounds.push('screen');
+  if (evidence?.mustFix?.some(fix => typeof fix === 'string' && fix.trim())) grounds.push('must-fix');
+  return grounds;
+}
+
+/** `decisions raise` 인자 — 종전 실행부(`executeNextAction`)와 live 수(`executeLiveDecisionCard`)가 같은 카드 모양을 쓴다. */
+export function decisionRaiseArgs(input: { taskId: string; reason: string; risk?: NextAction['risk']; evidence: string }): string[] {
+  const category = input.risk === 'money' ? 'money' : input.risk === 'security' ? 'security' : input.risk === 'irreversible-publication' ? 'publish' : 'other';
+  return ['decisions', 'raise', '--title', `${input.taskId}: ${input.reason}`, '--category', category, '--s', `Task ${input.taskId} needs a decision.`, '--c', input.reason, '--ref', input.evidence, '--q', 'Which action should be taken?', '--option', 'h=Keep on hold:no automatic execution', '--option', 'p=Approve action:execute after approval', '--skip-recommend', 'requires human decision', '--no-xcheck', 'automated escalation'];
 }
 
 /** 실패 셈 키. 갈래가 있으면 갈래별로 센다(G2 — «다른 수»의 실패가 같은 칸에 쌓이지 않게). 없으면 종전 키 그대로. */
@@ -72,6 +114,19 @@ export function failureKey(action: Pick<NextAction, 'taskId' | 'kind' | 'variant
   return JSON.stringify(action.variant ? [action.taskId, action.kind, action.variant] : [action.taskId, action.kind]);
 }
 
+/**
+ * 같은 «수»의 실패 수 — 상한 판정용. 셈 키(`failureKey`)는 종전 그대로 두되, 갈래 없는 재발사와 `narrow` 갈래는
+ * 같은 수(`narrow-relaunch` · `retryMoveOf`)라 두 키를 합쳐 본다(TA-LIVE-RETRY: 같은 과제·같은 수 3회 반복 0).
+ */
+export function sameMoveFailures(action: Pick<NextAction, 'taskId' | 'kind' | 'variant'>, deps: Pick<ActionDeps, 'failureCounts' | 'failures'>): number {
+  if (!deps.failureCounts) return deps.failures ?? 0;
+  if (action.kind !== 'retry' || retryMoveOf(action.variant) !== 'narrow-relaunch') return deps.failureCounts[failureKey(action)] ?? deps.failures ?? 0;
+  const bare = deps.failureCounts[failureKey({ taskId: action.taskId, kind: 'retry' })];
+  const narrow = deps.failureCounts[failureKey({ taskId: action.taskId, kind: 'retry', variant: 'narrow' })];
+  if (bare === undefined && narrow === undefined) return deps.failures ?? 0;
+  return (bare ?? 0) + (narrow ?? 0);
+}
+
 const RETRY_HINT: Record<Exclude<RetryVariant, 'wait'>, (action: NextAction) => string> = {
   narrow: action => `Narrow relaunch: previous run ${action.runId} made no progress. Halve the scope; keep the same acceptance line.`,
   salvage: action => `Salvage relaunch: continue from the salvage branch ${action.salvageBranch ?? `of run ${action.runId}`} — take its diff, do not restart from scratch.`,
@@ -89,18 +144,19 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
     deps.observe('task-agent.action', { taskId: action.taskId, kind: action.kind, result, reason });
     return result;
   };
-  if (deps.mode !== 'live') {
+  const shadowReason = deps.mode === 'live' ? retryShadowReason(action, deps) : undefined;
+  if (deps.mode !== 'live' || shadowReason) {
     const destination = action.delivery && action.kind === 'deliver'
       ? ` → ${join(action.delivery.projectTarget, 'elanous-out', action.taskId)}/${action.delivery.files.join(', ')}` : '';
-    return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}${destination}`);
+    return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}${destination}${shadowReason ? ` · shadow: ${shadowReason}` : ''}`);
   }
   const card = async (reason: string) => {
     const evidence = JSON.stringify({ runId: action.runId, pr: action.pr, mustFix: action.mustFix ?? [], history: action.history ?? [], selected: action.kind, reason });
-    const result = await deps.command(['decisions', 'raise', '--title', `${action.taskId}: ${reason}`, '--category', action.risk === 'money' ? 'money' : action.risk === 'security' ? 'security' : action.risk === 'irreversible-publication' ? 'publish' : 'other', '--s', `Task ${action.taskId} needs a decision.`, '--c', reason, '--ref', evidence, '--q', 'Which action should be taken?', '--option', 'h=Keep on hold:no automatic execution', '--option', 'p=Approve action:execute after approval', '--skip-recommend', 'requires human decision', '--no-xcheck', 'automated escalation']);
+    const result = await deps.command(decisionRaiseArgs({ taskId: action.taskId, reason, ...(action.risk ? { risk: action.risk } : {}), evidence }));
     return record(result.status === 0 ? 'decision' : 'failed', reason);
   };
   if (action.risk) return card(`risk: ${action.risk}`);
-  if ((deps.failureCounts?.[failureKey(action)] ?? deps.failures ?? 0) >= 2) return card('same task/action failed twice');
+  if (sameMoveFailures(action, deps) >= SAME_MOVE_FAILURE_LIMIT) return card('same task/action failed twice');
   if (action.kind === 'land') {
     if (!action.cwd) return card('landing worktree unknown');
     const view = await deps.command(['gh', 'pr', 'view', String(action.pr), '--json', 'labels']);
@@ -175,6 +231,7 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
   // 여기 닿는 종류는 land · retry 둘뿐이다(green·decision·review 는 위에서 끝난다).
   const args = action.kind === 'land' ? ['pr', 'land', '--cwd', action.cwd!] : ['harness', 'say', retryText(action)];
   const day = deps.landingDay ?? new Date().toLocaleDateString('en-CA', { timeZone: 'Asia/Seoul' });
+  if (action.kind === 'retry' && deps.retryLaunches) deps.retryLaunches.count++;
   const outcome = await deps.command(args);
   if (outcome.status !== 0) {
     if (action.kind === 'land') deps.releaseLanding?.(day);

package/src/task-agent/board.ts

@@ -7,13 +7,42 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { debug } from '../debug/log.js';
 import { releaseLedgerRoot } from '../instance/resolve.js';
 import { listChecklist, type ChecklistStatus } from '../release-loop/checklist.js';
-import { readTaskAgentState, type CompletionKind, type TaskCard } from './task-hand.js';
+import { buildRunProgressRows, queryRunningRuns, type RunningRunsResult, type RunProgressRow } from '../self-implement/running-runs.js';
+import {
+  cardPrNumber, CLOSED_BY_HAND_EVENT, HAND_MOVE_HISTORY_EVENT, LIVE_MOVE_HISTORY_EVENT, LIVE_MOVE_RESULT_EVENT, readTaskAgentState,
+  type CompletionKind, type TaskCard,
+} from './task-hand.js';
 
 export type BoardLevel = 'project' | 'goal' | 'milestone' | 'task';
 export type BoardStatus = 'open' | 'done' | 'blocked';
 
+/** 카드 원장(task-agent-actions.json)에 적힌 사실만 — 없는 칸은 null(지어내지 않는다). */
+export interface BoardTaskLedger {
+  runId: string | null;
+  pr: number | null;
+  /** 카드 상태(handed · launched · launch-failed · failed). */
+  lastStatus: TaskCard['status'];
+  /** 관측 기록(live-move · hand-move)을 뺀 history 의 마지막 줄. */
+  lastEvent: { at: string; event: string; detail: string | null } | null;
+  /** 카드가 failed · launch-failed 일 때 마지막 줄의 사유(예: `failed/needs-owner — exit 1 · pod-failure`). 그 밖에는 null. */
+  exitReason: string | null;
+}
+
+/** `GET /api/task-agent/board` 응답 — progress 는 진전 관측(`queryRunningRuns`)을 싣는다; 관측을 못 얻으면 null(0을 «없다»로 쓰지 않는다). */
+export interface TaskAgentBoardResponse { board: BoardNode[]; progress: TaskAgentBoardProgress | null }
+
+/** 진전 관측 칸 — 행은 기존 `RunProgressRow` 형식 그대로(새 행 형식을 만들지 않는다). 과제 노드와는 `ledger.runId` ↔ `rows[].runId` 로만 짝짓는다(ledger 에 새 칸은 없다). */
+export interface TaskAgentBoardProgress {
+  readonly rows: readonly RunProgressRow[];
+  /** 관측이 부분(running 수가 `{ count: null, lowerBound }` 꼴이거나 읽지 못한 원장 unreadable 이 있으면)이면 true · 아니면 false. */
+  readonly partial: boolean;
+  /** 부분 관측일 때의 최소 running 수 · 완전 관측이면 null. */
+  readonly lowerBound: number | null;
+}
+
 export interface BoardNode {
   level: BoardLevel;
   id: string;
@@ -21,6 +50,8 @@ export interface BoardNode {
   status: BoardStatus;
   /** 과제 노드만 — 카드의 종결 종류(비면 code-pr 로 읽는다 · 칸은 싣지 않는다). */
   completion?: CompletionKind;
+  /** 과제 노드만 · `cardsBoard(…, { ledger: true })` 일 때만 — 카드 원장에서 읽은 런·PR·마지막 상태·종료 이유. */
+  ledger?: BoardTaskLedger;
   /** 부모 노드 id(프로젝트는 없다). */
   parent?: string;
   /** 프로젝트 노드만 — 프로젝트 없는 카드의 자리(id 는 빈 문자열이라 실제 프로젝트 id 와 겹치지 않는다). */
@@ -60,8 +91,28 @@ function cardStatus(card: TaskCard): BoardStatus {
   return card.greenProposal ? 'done' : 'open';
 }
 
-/** 과제 카드 → 프로젝트 트리. 프로젝트 없는 카드는 «무소속»(`unassigned: true` · id '') 아래 — 어떤 프로젝트 id 로도 걸러지지 않는다. */
-export function cardsBoard(statePath: string): BoardNode[] {
+function cardLedger(card: TaskCard): BoardTaskLedger {
+  const last = (card.history ?? [])
+    .filter((item) => item.event !== LIVE_MOVE_HISTORY_EVENT && item.event !== LIVE_MOVE_RESULT_EVENT && item.event !== HAND_MOVE_HISTORY_EVENT)
+    .at(-1);
+  const ended = card.status === 'failed' || card.status === 'launch-failed';
+  // ⚠️ 종료 이유 = «관측 줄을 뺀 마지막 줄»의 detail 만 본다 — 그 줄이 detail 없는 run-bound·pr-bound 면 null(지어내지 않음 · 앞줄을 거슬러 찾지 않는다).
+  //   관측 줄 거르기는 task-hand.ts(wait 사유)와 같은 셋이다 — 공용 헬퍼로 묶는 것은 다음 조각(UX 수확 리뷰 should-fix).
+  const reason = last ? (last.event === CLOSED_BY_HAND_EVENT ? last.reason ?? last.detail : last.detail) : undefined;
+  return {
+    runId: card.runId ?? null,
+    pr: cardPrNumber(card) ?? null,
+    lastStatus: card.status,
+    lastEvent: last ? { at: last.at, event: last.event, detail: last.detail ?? null } : null,
+    exitReason: ended ? reason ?? null : null,
+  };
+}
+
+/**
+ * 과제 카드 → 프로젝트 트리. 프로젝트 없는 카드는 «무소속»(`unassigned: true` · id '') 아래 — 어떤 프로젝트 id 로도 걸러지지 않는다.
+ * `ledger: true` 면 과제 노드마다 카드 원장 사실(`ledger`)을 붙인다 — 기본(CLI)은 그대로다.
+ */
+export function cardsBoard(statePath: string, options: { ledger?: boolean } = {}): BoardNode[] {
   const projects: BoardNode[] = [];
   const cards = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(statePath).tasks ?? {};
   for (const card of Object.values(cards)) {
@@ -77,6 +128,7 @@ export function cardsBoard(statePath: string): BoardNode[] {
     milestone.children!.push({
       level: 'task', id: card.id, title: card.text, status: cardStatus(card),
       ...(card.completion ? { completion: card.completion } : {}),
+      ...(options.ledger ? { ledger: cardLedger(card) } : {}),
       parent: milestone.id,
     });
   }
@@ -84,6 +136,43 @@ export function cardsBoard(statePath: string): BoardNode[] {
   return projects;
 }
 
+/** `taskAgentBoard` 주입 자리 — 시험은 관측을 갈아끼워 결정성을 얻는다. */
+export interface TaskAgentBoardDeps {
+  /** 진전 관측. 기본 = `queryRunningRuns({ caller: 'task-agent.board' })`. 던지면 progress=null — 보드는 그대로 돌려준다. */
+  readonly runningRuns?: () => RunningRunsResult;
+  /** 경과 계산의 기준 시각(`buildRunProgressRows` 의 nowMs) · 기본 = Date.now(). */
+  readonly nowMs?: number;
+  /** 진전 관측을 돌릴지 — 기본 false(progress=null · «요청 안 함»). ⛔ 운영 원장에서 queryRunningRuns 는 동기 수 초(10-12 실측 4.3초)라
+   *  데몬 이벤트 루프를 멈춘다 → 라우트는 `?progress=1` 일 때만 켠다(UX 수확 리뷰 should-fix). runningRuns 를 주입하면 이 값과 무관하게 돈다. */
+  readonly withProgress?: boolean;
+}
+
+/** 관측 결과 → progress 칸. running 수가 `{ count: null, lowerBound }` 꼴이거나 읽지 못한 원장(unreadable)이 있으면 부분 관측으로 친다. */
+function runProgressFrom(result: RunningRunsResult, nowMs: number): TaskAgentBoardProgress {
+  const objectCount = result.count !== undefined && typeof result.count !== 'number' ? result.count : null;
+  // 판정 출처는 관측 결과의 completeness 가 1순위 — count 꼴·unreadable 은 그것이 없을 때의 보조다.
+  const partial = result.completeness === 'partial' || objectCount !== null || (result.unreadable?.length ?? 0) > 0;
+  return {
+    rows: buildRunProgressRows(result, nowMs),
+    partial,
+    lowerBound: partial ? (objectCount !== null ? objectCount.lowerBound : result.counts.running + result.counts['probable-running']) : null,
+  };
+}
+
+/** 읽기 전용 — 원장이 없으면 빈 보드. 원장이 손상됐으면 `TaskAgentStateError` 를 그대로 던진다(빈 보드로 속이지 않는다). progress 는 진전 관측을 싣는다 — 관측이 던지면 progress=null(0을 «없다»로 쓰지 않는다) · 보드는 그대로. */
+export function taskAgentBoard(statePath: string, deps: TaskAgentBoardDeps = {}): TaskAgentBoardResponse {
+  const board = cardsBoard(statePath, { ledger: true });
+  if (!deps.runningRuns && !deps.withProgress) return { board, progress: null };
+  const observe = deps.runningRuns ?? (() => queryRunningRuns({ caller: 'task-agent.board' }));
+  let progress: TaskAgentBoardProgress | null = null;
+  try {
+    progress = runProgressFrom(observe(), deps.nowMs ?? Date.now());
+  } catch (error) {
+    debug.log('task-agent', 'board-progress-unavailable', { error: error instanceof Error ? error.message : String(error) });
+  }
+  return { board, progress };
+}
+
 function releaseStatus(status: ChecklistStatus): BoardStatus {
   return status === 'green' || status === 'done' ? 'done' : status === 'red' ? 'blocked' : 'open';
 }

package/src/task-agent/card-evidence.ts

@@ -13,7 +13,7 @@ import { readRunExits, type RunExit } from '../harness/harness-incidents.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { debug } from '../debug/log.js';
 import { LogStore, logsDbPath } from '../mss/logging/log-store.js';
-import type { RunLedgerEntry } from '../self-implement/run-ledger.js';
+import { appendRunLedgerEntry, type RunLedgerEntry } from '../self-implement/run-ledger.js';
 import { cardPrNumber, taskAgentStatePath, updateTaskCard, readTaskCard, type TaskCard } from './task-hand.js';
 import { judgeNextMove, type TaskJudgeInput } from './judge.js';
 import { remoteParentAlive, type SshRunner } from './parent-host.js';
@@ -342,3 +342,90 @@ export async function refreshCardRunBinding(cardId: string, statePath = taskAgen
   }
   return { card: next, evidence };
 }
+
+/** TA-WIRING-CHECK — `live-verified` 원장 줄의 이벤트 이름 · 카드 런 원장에 적는다. */
+export const WIRING_LIVE_VERIFIED_EVENT = 'live-verified';
+
+export interface WiringLiveVerifiedInput { pr: number; ref: string; ok: boolean }
+export interface WiringLiveVerifiedDeps { ledgerDir?: string; now?: () => Date }
+export type WiringLiveVerifiedOutcome = { written: true; entry: RunLedgerEntry } | { written: false; reason: string };
+
+/**
+ * 실물 1회를 돌린 뒤 남기는 기록 — 카드 런 원장에 `live-verified {pr, ref, ok, card}` 한 줄.
+ * `ref`(실물로 돌린 명령·화면 근거)가 비거나 카드에 런이 없거나 PR 번호가 자연수가 아니면 거부하고 쓰지 않는다.
+ */
+export function recordWiringLiveVerified(card: Pick<TaskCard, 'id' | 'runId'>, input: WiringLiveVerifiedInput, deps: WiringLiveVerifiedDeps = {}): WiringLiveVerifiedOutcome {
+  const ref = typeof input.ref === 'string' ? input.ref.trim() : '';
+  if (!ref) return { written: false, reason: 'ref 가 비었다 — 실물로 돌린 명령·화면 근거 한 줄이 필요하다' };
+  if (!Number.isSafeInteger(input.pr) || input.pr <= 0) return { written: false, reason: `pr 은 자연수다: ${input.pr}` };
+  if (!card.runId) return { written: false, reason: `카드 ${card.id} 에 런(runId)이 없다 — 기록할 원장이 없다` };
+  const entry: RunLedgerEntry = {
+    timestamp: (deps.now ?? (() => new Date()))().toISOString(),
+    runId: card.runId,
+    event: WIRING_LIVE_VERIFIED_EVENT,
+    data: { pr: input.pr, ref, ok: input.ok, card: card.id },
+  };
+  try {
+    appendRunLedgerEntry(entry, deps.ledgerDir);
+  } catch (error) {
+    return { written: false, reason: `원장 쓰기 실패: ${(error instanceof Error ? error.message : String(error)).slice(0, 200)}` };
+  }
+  return { written: true, entry };
+}
+
+export interface WiringEvidence {
+  /** 이 PR 이 배선(진입점·명령 등록·호출자 대입)을 바꿨나 — 그렇다면 실물 1회가 필요하다. */
+  required: boolean;
+  /** 카드 런 원장에 이 PR 의 `live-verified` ok 기록이 있나. */
+  liveRunRecorded: boolean;
+  /** 근거를 못 읽었다(gh 실패 · 원장 읽기 실패) — 관측만 하고 green 을 막지 않는다. */
+  unknown: boolean;
+}
+
+export interface WiringEvidenceDeps {
+  /** 카드 — 없으면 liveRunRecorded 는 false. */
+  card?: Pick<TaskCard, 'id' | 'runId'>;
+  /** `gh pr diff <pr>` 의 통합 diff 원문 — 한 번만 부른다(시험 주입). */
+  prDiff?: (pr: number) => string | Promise<string>;
+  loadLedger?: (runId: string) => RunLedgerEntry[] | null;
+}
+
+const WIRING_PATH = /(^|\/)(bin|scripts|cli)\/|(^|\/)[^/]*(install|auth|entrypoint)[^/]*$/i;
+const NON_WIRING_PATH = /^docs\/|\.md$|\.test\.[cm]?[jt]sx?$/;
+const WIRING_LINE = /\bregisterCommand\b|\.command\(|\.set\(|\.on\(|\bhandlers(?:\.\w+|\[[^\]]+\])\s*=(?!=)/;
+
+async function defaultPrDiff(pr: number): Promise<string> {
+  const { execFile } = await import('node:child_process');
+  return new Promise((resolveDiff, reject) => {
+    execFile('gh', ['pr', 'diff', String(pr)], { encoding: 'utf8', timeout: 30_000, maxBuffer: 32 * 1024 * 1024 }, (error, stdout) => (error ? reject(error) : resolveDiff(stdout)));
+  });
+}
+
+/** 순수 — 통합 diff 가 배선을 바꾸나. 문서·시험 파일은 보지 않는다. */
+export function diffTouchesWiring(diff: string): boolean {
+  for (const chunk of diff.split(/^diff --git /m)) {
+    const path = /^\S+ b\/(\S+)/.exec(chunk)?.[1] ?? '';
+    if (path && NON_WIRING_PATH.test(path)) continue;
+    if (path && WIRING_PATH.test(path)) return true;
+    const added = chunk.split('\n').filter((line) => line.startsWith('+') && !line.startsWith('+++'));
+    if (added.some((line) => WIRING_LINE.test(line))) return true;
+  }
+  return false;
+}
+
+/**
+ * 수집기 — 판단부(judge.ts) 밖에서만 gh 를 부른다. PR diff 는 «한 번» 읽고, gh·원장 읽기 실패는 던지지 않고 `unknown: true` 로 돌려준다.
+ */
+export async function collectWiringEvidence(pr: number, deps: WiringEvidenceDeps = {}): Promise<WiringEvidence> {
+  let unknown = false;
+  let required = false;
+  try { required = diffTouchesWiring(await (deps.prDiff ?? defaultPrDiff)(pr)); } catch { unknown = true; }
+  let liveRunRecorded = false;
+  if (deps.card?.runId) {
+    try {
+      const entries = (deps.loadLedger ?? await defaultLoadLedger())(deps.card.runId) ?? [];
+      liveRunRecorded = entries.some((entry) => entry.event === WIRING_LIVE_VERIFIED_EVENT && entry.data?.ok === true && entry.data?.pr === pr);
+    } catch { unknown = true; }
+  }
+  return { required, liveRunRecorded, unknown };
+}

package/src/task-agent/completion-evidence.ts

@@ -5,6 +5,11 @@ import type { DecisionLedger } from '../decisions/decision-ledger.js';
 import { getLastStatus } from '../domains/schedule-registry.js';
 
 export type CompletionEvidenceKind = 'research-report' | 'artifact' | 'content' | 'ops-action' | 'watch-brief' | 'decision-support' | 'deliverable';
+/** Card evidence stays a string in the existing ledger; retain both the checked output reference and the confirmed receipt. */
+export function deliverableReceiptEvidence(ref: string): string {
+  return JSON.stringify({ ref, receipt: true });
+}
+
 export interface CompletionEvidenceDeps {
   ledger?: Pick<DecisionLedger, 'list'>;
   schedulesDb?: Database;