elanous 0.2.24 → 0.2.27

package/src/session-runtime/index.ts

@@ -4,6 +4,7 @@ import { getUserConfig } from '../user-config.js';
 import { resolve } from 'node:path';
 import type { ModelFamily } from '../models/prompts.js';
 import type { InputSourceKind, InputSourceRef } from '../input/input-source-kind.js';
+import type { ControlTurnIntent, SubmitTurnIntent } from '../input/input-intent.js';
 import { getSessionCwd } from '../session/working-dir.js';
 import {
   armQuickControlOnce,
@@ -22,6 +23,7 @@ import {
 import type { LLMMessage, LLMToolSpec } from '../llm.js';
 import type { LLMToolDef } from '../plugins/core/types.js';
 import type { ToolRunResult, ToolRuntime } from '../tool-runtime/types.js';
+import { blockWriteToolSearchHydration, type ToolSearchRunResult } from '../tool-runtime/tool-search-runtime.js';
 import { findNativeTool, isNativeToolModelExposed } from '../native-tool-catalog.js';
 import { hasAstGrep } from '../skills/tools/ast-grep.js';
 import { buildOmniSearchTool, omniSearchAvailable } from '../skills/tools/omni-search.js';
@@ -1731,6 +1733,8 @@ const ESSENTIAL_NATIVE_RULE_IDS = [
   'agent', 'agent-output', 'agent-reply', 'agent-stop', 'agent-list', 'self-implement', 'self-orchestrate', 'dev-harness',
 ] as const;
 const ESSENTIAL_HOST_FAMILY_IDS = ['self-ops', 'release-read'] as const;
+// Keep this TUI essential addition out of the shared control/agent self-ops family.
+const ESSENTIAL_HOST_EXTRA_NAMES = ['logs_query'] as const;
 const ESSENTIAL_RUNTIME_FAMILY_IDS = ['bash', 'run-shell', 'pty-shell', 'run-tests', 'elanous_skills_list', 'skill_exec', 'code-grounding'] as const;
 const ESSENTIAL_OPTIONAL_TOOL_NAMES = [
   'GetDashboardState',
@@ -1764,7 +1768,11 @@ function buildEssentialSessionRuntimeToolSpecs(opts: {
         .filter((tool): tool is LLMToolDef => !!tool)
         .map(toSpec)
       : [];
-  });
+  }).concat(ESSENTIAL_HOST_EXTRA_NAMES
+    .filter(name => isToolAvailable(name, opts.toolAvailability))
+    .map(name => hostByName.get(name))
+    .filter((tool): tool is LLMToolDef => !!tool)
+    .map(toSpec));
   const runtimeById = new Map(opts.runtimeTools.map(tool => [tool.id, tool] as const));
   const runtimeSpecs = ESSENTIAL_RUNTIME_FAMILY_IDS.flatMap(id => {
     const rule = RUNTIME_TOOL_FAMILY_RULE_MAP.get(id);
@@ -1833,12 +1841,23 @@ export function buildSessionRuntimeToolSpecs(opts: {
   // toolset (incident 2026-05-04 — Opus replied "no file tools in this
   // session" while Bash was actually exposed at position 7+).
   const finalSpecs: LLMToolSpec[] = opts.rich === false
-    ? buildEssentialSessionRuntimeToolSpecs({
-        hostTools: opts.hostTools,
-        runtimeTools: opts.runtimeTools ?? [],
-        optionalTools: opts.optionalTools ?? [],
-        toolAvailability: opts.toolAvailability,
-      })
+    ? (() => {
+        const essentialSpecs = buildEssentialSessionRuntimeToolSpecs({
+          hostTools: opts.hostTools,
+          runtimeTools: opts.runtimeTools ?? [],
+          optionalTools: opts.optionalTools ?? [],
+          toolAvailability: opts.toolAvailability,
+        });
+        if (!hasDevHarnessIntent(opts.userText)) return essentialSpecs;
+        const droppedNames = new Set(['Edit', 'Write']);
+        const filteredSpecs = essentialSpecs.filter(spec => !droppedNames.has(spec.name));
+        if (filteredSpecs.length !== essentialSpecs.length) {
+          debug.log('session-runtime.tools', 'harness-phrase-write-tools-dropped', {
+            dropped: ['Edit', 'Write'],
+          });
+        }
+        return filteredSpecs;
+      })()
     : [
         ...dynamicNativeTools,
         ...hostSpecs,
@@ -2084,6 +2103,10 @@ export async function dispatchSessionRuntimeTool(
   args: Record<string, unknown>,
   deps: SessionRuntimeDispatchDeps,
 ): Promise<unknown> {
+  const finishRuntimeResult = (result: unknown): unknown =>
+    name === 'ToolSearch' && isDevHarnessIntent(deps.userText ?? '')
+      ? blockWriteToolSearchHydration(result as ToolSearchRunResult)
+      : result;
   // Fix W-bis (2026-04-25): codex family always enables scoped-analysis
   // mode regardless of userText vocabulary. Rationale (see docs/RESEARCH-
   // codex-reread-pathology-2refs-2026-04-25.md): codex's search-heavy
@@ -2178,8 +2201,9 @@ export async function dispatchSessionRuntimeTool(
   const nativeRuntime = nativeRule?.preferRuntime ? deps.getToolRuntime(name) : undefined;
   if (nativeRuntime) {
     const result = await deps.dispatchToolRuntime(name, normalizedArgs, deps.toolCallId);
-    rememberCandidateListingResult(name, normalizedArgs, result, scopedAnalysis, deps.searchPlannerState);
-    return result;
+    const safeResult = finishRuntimeResult(result);
+    rememberCandidateListingResult(name, normalizedArgs, safeResult, scopedAnalysis, deps.searchPlannerState);
+    return safeResult;
   }
   if (nativeRule?.dispatch) {
     let result: unknown;
@@ -2213,8 +2237,9 @@ export async function dispatchSessionRuntimeTool(
     const isPtyTool = name.startsWith('PtyShell') || name.startsWith('pty_shell');
     if (!isPtyTool || deps.ptyDashboardOn) {
       const result = await deps.dispatchToolRuntime(name, normalizedArgs, deps.toolCallId);
-      rememberCandidateListingResult(name, normalizedArgs, result, scopedAnalysis, deps.searchPlannerState);
-      return result;
+      const safeResult = finishRuntimeResult(result);
+      rememberCandidateListingResult(name, normalizedArgs, safeResult, scopedAnalysis, deps.searchPlannerState);
+      return safeResult;
     }
   }
 
@@ -2699,6 +2724,25 @@ function hasDevHarnessIntent(text: string): boolean {
   return hasAny(text, DEV_HARNESS_INTENT_TERMS);
 }
 
+export function isDevHarnessIntent(text: string): boolean {
+  return hasDevHarnessIntent(text);
+}
+
+/** The dashboard calls this immediately after submitIntent resolution. A
+ * fixed plain turn becomes the same control turn used by `/harness ask`, so
+ * the model dispatch branch is never reached for that turn. */
+export function routeDevHarnessSubmitIntent(
+  intent: SubmitTurnIntent | ControlTurnIntent,
+): SubmitTurnIntent | ControlTurnIntent {
+  if (intent.kind !== 'submit-turn' || intent.route !== 'plain' || !isDevHarnessIntent(intent.text)) return intent;
+  return {
+    kind: 'control-turn',
+    source: intent.source,
+    command: 'slash-command',
+    commandText: `/harness ask ${intent.text}`,
+  };
+}
+
 export function shouldExposeDevHarnessSessionTool(text: string): boolean {
   return isDevHarnessModelSurfaceEnabled() && hasDevHarnessIntent(text);
 }

package/src/skills/tools/agent.ts

@@ -44,7 +44,7 @@ import { enhanceAgentResultWithSeed } from '../../agent/seed.js';
 import { resolveAgent } from '../../agent/loader.js';
 import { resolveAgentLayered } from '../../agent/definition-registry.js';
 import type { AgentDefinition } from '../../agent/types.js';
-import { getSessionCwd } from '../../session/working-dir.js';
+import { getSessionCwd, setSessionCwd } from '../../session/working-dir.js';
 import {
   agentCacheKey, dedupeStub, logDedupHit, type SessionCache,
   DEDUP_CASCADE_HALT_THRESHOLD, CONSECUTIVE_DEDUP_BLOCK_THRESHOLD,
@@ -485,6 +485,11 @@ export async function dispatchAgent(
   } else if (isolation === 'worktree') {
     const { enterWorktreeRuntime } = await import('../../tool-runtime/git-worktree-runtimes.js');
     const wtName = `${spawnName ?? definition.name}-${debugCorrelationId}`.replace(/[^a-zA-Z0-9._/-]/g, '-');
+    // enterWorktreeRuntime.run mutates the parent session cwd via
+    // setSessionCwd(path, 'tool'). Capture and restore so Agent(isolation:
+    // 'worktree') never leaks the child's worktree into the parent status
+    // line — enter_worktree (human-invoked) still moves cwd intentionally.
+    const parentCwd = getSessionCwd();
     try {
       const wt = await enterWorktreeRuntime.run({ name: wtName }, { surface: 'skill' as any });
       childCwd = wt.path;
@@ -506,6 +511,16 @@ export async function dispatchAgent(
         requestedIsolation: 'worktree',
         reason: message,
       }, { level: 'warn' });
+    } finally {
+      const afterCwd = getSessionCwd();
+      if (afterCwd !== parentCwd) {
+        setSessionCwd(parentCwd, 'tool');
+        debug.log('agent.spawn', 'worktree-parent-cwd-restored', {
+          agent: definition.name,
+          from: afterCwd,
+          to: parentCwd,
+        });
+      }
     }
   } else {
     childCwd = opts.cwd ?? getSessionCwd();

package/src/skills/tools/persistent-grounding.ts

@@ -153,6 +153,16 @@ function rejectionSample(value: string): string {
   return value.slice(0, EVIDENCE_REJECTION_SAMPLE_PREFIX_LENGTH);
 }
 
+function stripLeadingListMarkers(line: string): string {
+  let stripped = line;
+  let previous: string;
+  do {
+    previous = stripped;
+    stripped = stripped.replace(/^\s*(?:[-*+•]|\d+[.)])\s+/, '');
+  } while (stripped !== previous);
+  return stripped;
+}
+
 function verifiedEvidenceFromCompletion(evidence: string, readFiles: Set<string>): { files: string[]; evidence: string[]; rejection: EvidenceRejection } {
   const lines = evidence.split(/\r?\n/).filter((line) => line.trim());
   const rejection: {
@@ -185,7 +195,7 @@ function verifiedEvidenceFromCompletion(evidence: string, readFiles: Set<string>
     return hasPath && insideRoot && unreadPaths.length === 0 && hasMeaningfulText;
   });
   const files = Array.from(new Set(verifiedLines.flatMap(repositoryRelativeCodePaths)));
-  return { files, evidence: verifiedLines, rejection };
+  return { files, evidence: verifiedLines.map(stripLeadingListMarkers), rejection };
 }
 
 function groundingMessages(goal: string, terms: readonly string[]): LLMMessage[] {

package/src/skills/tools/shell.ts

@@ -113,7 +113,7 @@ export interface RunShellDispatchResult extends Record<string, unknown> {
    *  follow in the structured fields below. */
   output: string;
   exitCode: number | null;
-  outcome: ShellResult['outcome'];
+  outcome: ShellResult['outcome'] | 'started';
   elapsedMs: number;
   stdout: string;
   stderr: string;
@@ -260,6 +260,38 @@ async function dispatchViaRunner(args: {
     ...(args.signal !== undefined ? { signal: args.signal } : {}),
   };
   const handle = runnerDispatch(req, args.deps);
+  if (args.mode === 'bg') {
+    const bgStartedAt = Date.now();
+    void handle.result.then(
+      (result) => {
+        debug.log('skill-tool.shell', 'bg-finished', {
+          handle: handle.id,
+          exitCode: result.exitCode ?? null,
+          durationMs: result.durationMs,
+        });
+      },
+      (err: unknown) => {
+        debug.log('skill-tool.shell', 'bg-finished', {
+          handle: handle.id,
+          exitCode: null,
+          durationMs: Date.now() - bgStartedAt,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      },
+    );
+    return {
+      output: `RunShell outcome=started handle=${handle.id} bg=${handle.id}`,
+      exitCode: null,
+      outcome: 'started',
+      elapsedMs: 0,
+      stdout: '',
+      stderr: '',
+      truncated: false,
+      approvalKey: `runner:${handle.id}`,
+      sandboxed: false,
+      sandboxTool: 'none',
+    };
+  }
   const result = await handle.result;
   return runnerToLegacyResult(handle.id, result);
 }

package/src/steward/rejudge-tick.ts

@@ -0,0 +1,142 @@
+/**
+ * TA-REJUDGE-PERIODIC — the steward (coordinator) tick re-runs `tasks rejudge --all` on a cadence.
+ *
+ * `tasks rejudge` only ran when someone typed it (OP bridged the gap with a 30-minute shell loop). This node is the
+ * product form: the steward graph already ticks every 15 minutes, so the rejudge rides that tick — no new resident loop.
+ *
+ * - Off by default: `taskAgent.rejudgeEveryMinutes` absent/0 → one `disabled` line per tick and nothing else.
+ *   Rejudge can land PRs (per `taskAgent.liveMoves`), so it is switched on by an operator, not by an upgrade.
+ * - Cadence: due when the last started run is ≥ interval − 2 min ago (tick start jitter must not skip a whole tick).
+ * - Load guard: 1-minute load average above `taskAgent.rejudgeMaxLoad` (default 60) skips this tick without stamping,
+ *   so the next tick retries.
+ * - Fail-soft: every outcome exits 0 — a rejudge problem never stops the steward's own stages.
+ * - Observation: one `debug.log('loop.steward', 'rejudge-tick', …)` per tick.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { loadavg } from 'node:os';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { spawnElanous } from '../instance/spawn-elanous.js';
+import { getUserConfig } from '../user-config.js';
+
+export const REJUDGE_TICK_EVENT = 'rejudge-tick';
+export const REJUDGE_DEFAULT_MAX_LOAD = 60;
+export const REJUDGE_JITTER_MS = 2 * 60_000;
+export const REJUDGE_TIMEOUT_MS = 600_000;
+
+export type RejudgeTickDecision = 'disabled' | 'not-due' | 'load-skip' | 'ran' | 'failed';
+
+export interface RejudgeTickResult {
+  decision: RejudgeTickDecision;
+  everyMinutes: number | null;
+  load?: number;
+  maxLoad?: number;
+  lastStartedAt?: string | null;
+  rc?: number | null;
+  timedOut?: boolean;
+  cards?: number;
+  decisions?: Record<string, number>;
+  ms?: number;
+  reason?: string;
+}
+
+export interface RejudgeRun { code: number | null; stdout: string; stderr: string; timedOut: boolean }
+
+export interface RejudgeTickDeps {
+  now?: () => Date;
+  /** `taskAgent.rejudgeEveryMinutes` / `taskAgent.rejudgeMaxLoad` — default reads the user config. */
+  config?: () => { rejudgeEveryMinutes?: number; rejudgeMaxLoad?: number } | undefined;
+  load?: () => number;
+  stampPath?: string;
+  run?: () => Promise<RejudgeRun>;
+  log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+function defaultStampPath(): string {
+  // Resolved at call time, in the node process's own universe (prod cron vs --test graph run).
+  return join(effectiveInstanceRoot(), 'steward', 'rejudge-tick.json');
+}
+
+function readStamp(path: string): string | null {
+  try {
+    const value = (JSON.parse(readFileSync(path, 'utf8')) as { startedAt?: unknown }).startedAt;
+    return typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : null;
+  } catch { return null; }
+}
+
+/** Same universe as this process (env inherited) · same installed version (entry next to this module). */
+export function defaultRejudgeRun(timeoutMs = REJUDGE_TIMEOUT_MS): Promise<RejudgeRun> {
+  return new Promise(done => {
+    const child = spawnElanous(['tasks', 'rejudge', '--all', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs);
+    child.stdout?.on('data', chunk => { stdout += String(chunk); });
+    child.stderr?.on('data', chunk => { stderr += String(chunk); });
+    child.on('error', error => { clearTimeout(timer); done({ code: null, stdout, stderr: `${stderr}${error.message}`, timedOut }); });
+    child.on('close', code => { clearTimeout(timer); done({ code, stdout, stderr, timedOut }); });
+  });
+}
+
+/** The last `[...]` line of `tasks rejudge --all --json` → card count and a decision histogram. */
+function summarize(stdout: string): { cards: number; decisions: Record<string, number> } | null {
+  const line = stdout.split('\n').map(text => text.trim()).filter(text => text.startsWith('[')).at(-1);
+  if (!line) return null;
+  try {
+    const rows = JSON.parse(line) as Array<{ card?: unknown; decision?: unknown }>;
+    if (!Array.isArray(rows)) return null;
+    const decisions: Record<string, number> = {};
+    for (const row of rows) { const key = String(row?.decision ?? 'unknown'); decisions[key] = (decisions[key] ?? 0) + 1; }
+    return { cards: new Set(rows.map(row => String(row?.card))).size, decisions };
+  } catch { return null; }
+}
+
+function positive(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+
+export async function rejudgeTick(deps: RejudgeTickDeps = {}): Promise<RejudgeTickResult> {
+  const log = deps.log ?? ((event, data) => debug.log('loop.steward', event, data));
+  const emit = (result: RejudgeTickResult): RejudgeTickResult => {
+    try { log(REJUDGE_TICK_EVENT, { ...result }); } catch { /* fail-soft */ }
+    return result;
+  };
+  try {
+    const cfg = (deps.config ?? (() => getUserConfig().taskAgent))();
+    const everyMinutes = positive(cfg?.rejudgeEveryMinutes);
+    if (everyMinutes === null) return emit({ decision: 'disabled', everyMinutes: null, reason: 'taskAgent.rejudgeEveryMinutes unset' });
+    const now = (deps.now ?? (() => new Date()))();
+    const stampPath = deps.stampPath ?? defaultStampPath();
+    const lastStartedAt = readStamp(stampPath);
+    if (lastStartedAt && now.getTime() - Date.parse(lastStartedAt) < everyMinutes * 60_000 - REJUDGE_JITTER_MS) {
+      return emit({ decision: 'not-due', everyMinutes, lastStartedAt });
+    }
+    const maxLoad = positive(cfg?.rejudgeMaxLoad) ?? REJUDGE_DEFAULT_MAX_LOAD;
+    const load = (deps.load ?? (() => loadavg()[0] ?? 0))();
+    if (load > maxLoad) return emit({ decision: 'load-skip', everyMinutes, load, maxLoad, lastStartedAt });
+    // Claim before running so an overlapping steward tick does not start a second rejudge.
+    mkdirSync(dirname(stampPath), { recursive: true });
+    writeFileSync(stampPath, JSON.stringify({ startedAt: now.toISOString() }));
+    const started = Date.now();
+    const run = await (deps.run ?? (() => defaultRejudgeRun()))();
+    const summary = summarize(run.stdout);
+    const ok = run.code === 0 && !run.timedOut && summary !== null;
+    return emit({
+      decision: ok ? 'ran' : 'failed', everyMinutes, load, maxLoad, lastStartedAt, rc: run.code, timedOut: run.timedOut,
+      cards: summary?.cards ?? 0, decisions: summary?.decisions ?? {}, ms: Date.now() - started,
+      ...(ok ? {} : { reason: (run.stderr || run.stdout).trim().slice(-300) || (summary === null ? 'no JSON result line' : 'nonzero exit') }),
+    });
+  } catch (error) {
+    return emit({ decision: 'failed', everyMinutes: null, reason: (error instanceof Error ? error.message : String(error)).slice(-300) });
+  }
+}
+
+if (import.meta.main) {
+  try { await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('steward'); }
+  catch (error) { console.error(`steward rejudge: log sink registration failed — ${error instanceof Error ? error.message : String(error)}`); }
+  const result = await rejudgeTick();
+  console.log(`steward rejudge: ${result.decision}${result.reason ? ` — ${result.reason}` : ''}`);
+  process.exitCode = 0;
+}

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 };
+}