elanous 0.2.23 → 0.2.24

package/src/cli/tasks-cli.ts

@@ -9,9 +9,10 @@ import { readNexusRuntime } from '../nexus/runtime.js';
 import { checklistDevVersion } from '../release-loop/checklist.js';
 import { cardsBoard, countBoardTasks, INTERNAL_PACK_PROJECT, mergeBoards, releasePackBoard, type BoardNode } from '../task-agent/board.js';
 import type { Task } from '../task-orchestrator/types.js';
-import { cardPrNumber, COMPLETION_KINDS, handTask, LIVE_MOVE_HISTORY_EVENT, LIVE_MOVE_RESULT_EVENT, nextMoveFor, resolveHandText, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TA_LAND_ENV, TASK_CARD_PREFIX, TASK_SEATS, type CompletionKind, type TaskCard, type TaskLaunchContext, type TaskLaunchReceipt, type TaskLauncher, type TaskSeat } from '../task-agent/task-hand.js';
+import { cardPrNumber, CLOSED_BY_HAND_EVENT, closeTaskCard, COMPLETION_KINDS, handTask, updateTaskCard, LIVE_MOVE_HISTORY_EVENT, LIVE_MOVE_RESULT_EVENT, nextMoveFor, resolveHandText, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TA_LAND_ENV, 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 { captureReviewResults } from '../task-agent/review-result-capture.js';
+import { HAND_MOVE_KINDS, recordHandMove } from '../task-agent/live-move-history.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';
@@ -44,9 +45,13 @@ export interface TasksCliDeps {
   remoteLedgerMirror?: (card: TaskCard) => void;
   /** `tasks parents` 의 낡은 부모 보고 의존(시험 주입). */
   staleParents?: import('../task-agent/parent-host.js').StaleParentDeps;
+  /** `tasks adopt-runs` 의 백필 의존(시험 주입 · 등록부·상태 파일). */
+  adoptRuns?: import('../task-agent/run-adopt.js').RunAdoptDeps;
   /** `tasks cover` logs 조회 seam. 기본은 등록된 모든 우주(운영 ⊕ test)의 logs.db 를 read-only 로 연다 —
    *  pr land 는 작업 트리마다 파생 test 우주에 기록되므로 현재 우주만 읽으면 분모가 늘 0 이다. */
   coverLogs?: (query: LogQuery) => LogStoreRow[] | CoverLogRead;
+  /** `tasks cover --by-card` 카드 원장 읽기 seam(읽기 전용). 플래그가 있을 때만 부른다. 기본 = TA 카드 원장(task-agent-actions.json). null = 못 읽음. */
+  coverCards?: () => CoverCardRow[] | null | Promise<CoverCardRow[] | null>;
   /** TA-REJUDGE-ON-HEAD — `tasks rejudge` 의 판단 의존(시험 주입 · 기본 = 설정 liveMoves ⊕ 실물 gh·리뷰·재게이트·land). */
   rejudge?: Partial<import('../task-agent/rejudge-on-head.js').RejudgeDeps>;
   /** TA-REJUDGE-ON-HEAD — `tasks regate-run` 의 재게이트(시험 주입 · 기본 `runHostRegate`). */
@@ -469,9 +474,31 @@ function coverEvents<T>(rows: readonly LogStoreRow[], category: string, event: s
   return events;
 }
 
+export interface CoverCardRow { id: string; createdAt: string }
+
+/**
+ * 분모 = TA 카드 원장(`task-agent-actions.json` · `ta-…` id) — 분자 `task-agent`/`action` 로그의 taskId 가 이 id 다.
+ * (task-cards CardStore 의 UUID 카드는 taskId 와 겹치지 않아 언제나 0/N 을 «잰 값처럼» 그린다 — 리뷰 must-fix.)
+ */
+function readCoverCards(statePath: string): CoverCardRow[] {
+  const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(statePath).tasks ?? {};
+  return Object.values(tasks).filter((card) => typeof card?.id === 'string' && typeof card.createdAt === 'string')
+    .map(({ id, createdAt }) => ({ id, createdAt }));
+}
+
+/** Cards whose createdAt falls in the window; an unparsable createdAt is not placed in any window. */
+export function coverCardsInWindow(cards: readonly CoverCardRow[] | null, window: { sinceMs?: number; untilMs?: number }): { id: string }[] | null {
+  if (cards === null) return null;
+  return cards.filter(({ createdAt }) => {
+    const time = Date.parse(createdAt);
+    return Number.isFinite(time) && (window.sinceMs === undefined || time >= window.sinceMs) && (window.untilMs === undefined || time <= window.untilMs);
+  }).map(({ id }) => ({ id }));
+}
+
 export function readTaskAgentCover(
   window: { sinceMs?: number; untilMs?: number } = {},
   query: NonNullable<TasksCliDeps['coverLogs']> = queryCoverLogs,
+  taskCards?: readonly { id: string }[] | null,
 ): { rows: CoverRow[]; limitReached: boolean; unreadableStores: number } {
   let unreadableStores = 0;
   const read = (category: 'task-agent' | 'pr.land', event: 'action' | 'step'): { rows: LogStoreRow[]; limitReached: boolean } | null => {
@@ -490,10 +517,11 @@ export function readTaskAgentCover(
   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),
+        ? { kind: data.kind as NonNullable<TaskAgentCoverInput['taskAgentActions']>[number]['kind'], result: data.result, ...(typeof data.taskId === 'string' ? { taskId: data.taskId } : {}) } : 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,
+    ...(taskCards === undefined ? {} : { taskCards }),
   };
   return { rows: measureTaskAgentCover(input), limitReached: truncated.taskAgentActions || truncated.allLands, unreadableStores };
 }
@@ -516,7 +544,8 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
     .option('--until <iso>', '끝 시각 (ISO)')
     .option('--json', 'JSON 출력')
     .option('--lines', '동사별 한 줄 요약 출력 (읽기 전용)')
-    .action((opts: { since?: string; until?: string; json?: boolean; lines?: boolean }) => {
+    .option('--by-card', 'review·retry·green 분모를 카드 원장(창 안 createdAt 카드 수)으로 센다 (읽기 전용)')
+    .action(async (opts: { since?: string; until?: string; json?: boolean; lines?: boolean; byCard?: boolean }) => {
       const parseIso = (value: string | undefined, flag: string): number | undefined => {
         if (value === undefined) return undefined;
         const time = Date.parse(value);
@@ -527,7 +556,16 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
         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);
+        let taskCards: { id: string }[] | null | undefined;
+        if (opts.byCard) {
+          let cards: CoverCardRow[] | null;
+          try { cards = await (deps.coverCards ?? (() => readCoverCards(deps.taskStatePath ?? taskStatePathDefault())))(); } catch (error) {
+            cards = null;
+            try { debug.log('task-agent.cover', 'by-card-unreadable', { error: String(error).slice(-200) }, { level: 'warn' }); } catch { /* fail-soft */ }
+          }
+          taskCards = coverCardsInWindow(cards, { sinceMs, untilMs });
+        }
+        const { rows, limitReached, unreadableStores } = readTaskAgentCover({ sinceMs, untilMs }, deps.coverLogs, taskCards);
         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 } : {}) }));
@@ -677,6 +715,61 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
       }
     });
 
+  tasks.command('hand-move <id>')
+    .description('HAND-MOVE-LEDGER — 자리가 손으로 마무리한 수(기존 실패 면제 · diff 재적용 · 범위 자르기 · 쪼개기 · 다른 모델 의견)를 그 카드 history 에 한 줄로 남긴다 — live-move 와 같은 원장 칸 · 기존 줄은 건드리지 않는다')
+    .requiredOption('--kind <kind>', `손으로 쓴 수 (${HAND_MOVE_KINDS.join('|')})`)
+    .requiredOption('--by <seat>', '남긴 자리(예: OP·MK·TC·UX)')
+    .requiredOption('--detail <text>', '무엇을 했나 — 한 줄')
+    .option('--pr <number>', '관련 PR 번호')
+    .action(async (id: string, opts: { kind: string; by: string; detail: string; pr?: string }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      const pr = opts.pr === undefined ? undefined : Number(opts.pr);
+      if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { out(`--pr 은 자연수다: ${opts.pr}`); process.exitCode = 1; return; }
+      const outcome = recordHandMove(deps.taskStatePath ?? taskStatePathDefault(), id,
+        { kind: opts.kind, by: opts.by, detail: opts.detail, ...(pr !== undefined ? { pr } : {}) });
+      try {
+        debug.log('task-agent', 'hand-move', outcome.written
+          ? { card: id, kind: outcome.entry.kind, by: outcome.entry.by, ...(outcome.entry.pr !== undefined ? { pr: outcome.entry.pr } : {}) }
+          : { card: id, kind: opts.kind, by: opts.by, reason: outcome.reason });
+      } catch { /* fail-soft */ }
+      if (!outcome.written) { out(`hand-move 한 줄을 못 남겼다 — ${outcome.reason}`); process.exitCode = 1; return; }
+      out([id, 'hand-move', outcome.entry.kind, outcome.entry.by, outcome.entry.detail, ...(outcome.entry.pr !== undefined ? [`pr ${outcome.entry.pr}`] : [])].join('\t'));
+    });
+
+  tasks.command('close <cardId>')
+    .description('과제 카드를 손으로 닫는다 — 상태를 failed 로 두고 사유를 history(closed-by-hand)에 한 줄 남긴다 · 없는 카드 id 는 거부(exit 1)')
+    .requiredOption('--reason <사유>', '닫는 사유(비면 거부)')
+    .option('--by <seat>', '닫은 자리(예: OP·MK·TC·UX)', 'operator')
+    .option('--json', 'JSON 출력')
+    .action(async (cardId: string, opts: { reason: string; by: string; json?: boolean }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      const statePath = deps.taskStatePath ?? taskStatePathDefault();
+      try {
+        let found: TaskCard | undefined;
+        let changed = false;
+        const updated = updateTaskCard(statePath, cardId, (current) => {
+          if (!current) return undefined;
+          found = current;
+          const next = closeTaskCard(current, { reason: opts.reason, by: opts.by, at: new Date().toISOString() });
+          if (next === current) return undefined; // 이미 손으로 닫힘 — 다시 쓰지 않는다(멱등)
+          changed = true;
+          return next;
+        });
+        if (!found) { out(`과제 카드 없음: ${cardId}`); process.exitCode = 1; return; }
+        const card: TaskCard = updated ?? found;
+        const from = (found as TaskCard).status;
+        // 이미 닫힌 카드면 «저장된» 사유를 낸다 — 새로 준 사유는 원장에 없다.
+        const stored = [...card.history].reverse().find((item) => item.event === CLOSED_BY_HAND_EVENT);
+        const reason = changed ? opts.reason.trim() : (stored?.reason ?? stored?.detail ?? opts.reason.trim());
+        if (changed) { try { debug.log('task-agent', 'card-closed-by-hand', { id: cardId, from, by: opts.by, reason }); } catch { /* fail-soft */ } }
+        if (opts.json) out(JSON.stringify({ id: card.id, from, to: card.status, reason, ...(changed ? {} : { already: true }) }));
+        else out([card.id, card.status, changed ? 'closed-by-hand' : 'already-closed-by-hand', changed ? opts.by : (stored?.by ?? '-'), reason].join('\t'));
+      } catch (error) {
+        out(error instanceof Error ? error.message : '과제 카드 닫기 실패');
+        process.exitCode = 1;
+      }
+    });
+
   tasks.command('parents')
     .description('낡은 하니스 부모 보고(읽기 전용 · 죽이지 않는다) — 나이 ≥ N 시간이고 런 원장이 끝났거나(run-status) Pod 이 없는 `harness say|ask` 부모')
     .option('--older-than <hours>', '나이 하한(시간)', '6')
@@ -703,6 +796,18 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
       for (const row of report.rows) out([row.pid, row.ageHours, row.seat ?? '-', row.version ?? '-', row.runId ?? '-', row.reasons.join(',')].join('\t'));
     });
 
+  tasks.command('adopt-runs')
+    .description('TA-OWN-ALL-RUNS 백필 — 발사 등록부의 이 우주 런 중 카드 없는 것에 `ta-<runId>` 카드를 만든다(발사 훅 이전 런 몫 · 있으면 건드리지 않는다)')
+    .option('--json', 'JSON 출력')
+    .action(async (opts: { json?: boolean }) => {
+      const { adoptUncardedRuns } = await import('../task-agent/run-adopt.js');
+      const report = adoptUncardedRuns({ ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}), ...deps.adoptRuns });
+      try { debug.log('task-agent', 'run-adopt-backfill', report); } catch { /* fail-soft */ }
+      if (opts.json) { out(JSON.stringify(report)); return; }
+      const skipped = Object.entries(report.skipped).sort(([a], [b]) => a.localeCompare(b)).map(([reason, n]) => `${reason} ${n}`).join(' · ') || '없음';
+      out(`등록부 런 ${report.scanned} · 카드 만듦 ${report.adopted} · 건너뜀 ${skipped}`);
+    });
+
   tasks.command('board')
     .description('보드 — 프로젝트 › 목표 › 이정표 › 과제. 과제 카드(project·goal·milestone)와 내부 팩(릴리스 체크리스트 = elanous › 판 › 칸)을 합쳐 읽는다(쓰지 않는다)')
     .option('--project <id>', '이 프로젝트만')

package/src/cli/usage-cli.ts

@@ -60,15 +60,87 @@ function readRunLogs(query: LogQuery): LogStoreRow[] {
   }
 }
 
-function usageData(row: LogStoreRow): RunUsageInput | null {
+type UsageAxis = 'stage' | 'model' | 'account';
+type ExtendedRunUsageInput = RunUsageInput & { stage?: string | null; account?: string | null };
+type AxisUsageRow = {
+  stage?: string;
+  model?: string;
+  account?: string;
+  hostIds: string[];
+  calls: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadInputTokens: number;
+  cacheCreationInputTokens: number;
+  reasoningOutputTokens: number;
+  usdKnown: number;
+  unknownCostCalls: number;
+  includedCalls: number;
+  apiEquivalentUsd: number;
+};
+
+function usageData(row: LogStoreRow, unwrapPod = false): ExtendedRunUsageInput | null {
   if (row.category !== 'llm.usage' || row.event !== 'llm-usage' || !row.data) return null;
   try {
-    const value: unknown = JSON.parse(row.data);
+    let value: unknown = JSON.parse(row.data);
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    return value as RunUsageInput;
+    const wrapper = value as { origin?: unknown; originalData?: unknown };
+    if (unwrapPod && wrapper.origin === 'pod') {
+      value = typeof wrapper.originalData === 'string' ? JSON.parse(wrapper.originalData) : wrapper.originalData;
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    }
+    return value as ExtendedRunUsageInput;
   } catch { return null; }
 }
 
+function stageForUsage(data: ExtendedRunUsageInput): string {
+  const stages = ['authoring', 'implement', 'review', 'gate'];
+  if (typeof data.stage === 'string' && data.stage.length > 0) return stages.includes(data.stage) ? data.stage : '기타';
+  // 역할 대체: 저작 호출은 role 'planning' 으로 실린다(ModelRole 에 authoring 이 없다) → authoring 단계로 센다.
+  const role = data.role === 'planning' ? 'authoring' : data.role;
+  if (typeof role === 'string' && role.length > 0) return stages.includes(role) ? role : '기타';
+  return '(none)';
+}
+
+function rollupByAxis(inputs: readonly ExtendedRunUsageInput[], axis: UsageAxis): AxisUsageRow[] {
+  const groups = new Map<string, ExtendedRunUsageInput[]>();
+  for (const data of inputs) {
+    const value = axis === 'stage' ? stageForUsage(data)
+      : axis === 'model' ? (data.model || '(none)')
+        : (data.account || '(none)');
+    const group = groups.get(value) ?? [];
+    group.push(data);
+    groups.set(value, group);
+  }
+  return [...groups].map(([value, group]) => {
+    const rows = rollupRunUsage(group);
+    const result: AxisUsageRow = {
+      [axis]: value,
+      hostIds: [...new Set(rows.flatMap((row) => row.hostIds))],
+      calls: rows.reduce((sum, row) => sum + row.calls, 0),
+      inputTokens: rows.reduce((sum, row) => sum + row.inputTokens, 0),
+      outputTokens: rows.reduce((sum, row) => sum + row.outputTokens, 0),
+      cacheReadInputTokens: rows.reduce((sum, row) => sum + row.cacheReadInputTokens, 0),
+      cacheCreationInputTokens: rows.reduce((sum, row) => sum + row.cacheCreationInputTokens, 0),
+      reasoningOutputTokens: rows.reduce((sum, row) => sum + row.reasoningOutputTokens, 0),
+      usdKnown: rows.reduce((sum, row) => sum + row.usdKnown, 0),
+      unknownCostCalls: rows.reduce((sum, row) => sum + row.unknownCostCalls, 0),
+      includedCalls: rows.reduce((sum, row) => sum + row.includedCalls, 0),
+      apiEquivalentUsd: rows.reduce((sum, row) => sum + row.apiEquivalentUsd, 0),
+    };
+    return result;
+  }).sort((a, b) => b.calls - a.calls);
+}
+
+function isUsageAxis(value: string): value is 'run' | 'role' | UsageAxis {
+  return value === 'run' || value === 'role' || value === 'stage' || value === 'model' || value === 'account';
+}
+
+function formatAxisUsage(row: AxisUsageRow, axis: UsageAxis): string {
+  const value = row[axis] ?? '(none)';
+  return `${axis}=${value}  hosts=${row.hostIds.join(',') || '(none)'}  calls=${row.calls}  input=${row.inputTokens}  output=${row.outputTokens}  cacheRead=${row.cacheReadInputTokens}  cacheCreation=${row.cacheCreationInputTokens}  reasoning=${row.reasoningOutputTokens}  usdKnown=${row.usdKnown}  unknownCostCalls=${row.unknownCostCalls}  includedCalls=${row.includedCalls}  apiEquivalentUsd=${row.apiEquivalentUsd}`;
+}
+
 function defaultCreditPlan(): CodexCreditPlan | null {
   try { return codexCreditPlanFromDisk(); } catch { return null; }
 }
@@ -94,15 +166,15 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
 
   usage
     .command('runs')
-    .description('저장된 llm-usage 로그를 런 또는 역할·호출 자리별로 집계한다')
+    .description('저장된 llm-usage 로그를 런·역할·단계·모델·계정별로 집계한다')
     .option('--run <runId>', '런 ID 정확 일치')
-    .option('--by <axis>', '집계 축 (run | role)', 'run')
+    .option('--by <axis>', '집계 축 (run | role | stage | model | account)', 'run')
     .option(...LOGS_SINCE_OPTION)
     .option('--json', '집계 행 JSON 출력')
     .action((opts: { run?: string; by: string; since?: string; json?: boolean }, command: Command) => {
       const json = opts.json || command.optsWithGlobals<{ json?: boolean }>().json;
-      if (opts.by !== 'run' && opts.by !== 'role') {
-        out.log('⛔ --by 는 run | role');
+      if (!isUsageAxis(opts.by)) {
+        out.log('⛔ --by 는 run | role | stage | model | account');
         exit(2);
         return;
       }
@@ -116,8 +188,19 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
         exactCategories: ['llm.usage'], events: ['llm-usage'],
         ...(sinceMs !== undefined ? { sinceMs } : {}),
       });
-      const inputs = rows.map(usageData).filter((data): data is RunUsageInput => data !== null)
+      const unwrapPod = opts.by === 'stage' || opts.by === 'model' || opts.by === 'account';
+      const inputs = rows.map((row) => usageData(row, unwrapPod)).filter((data): data is ExtendedRunUsageInput => data !== null)
         .filter((data) => opts.run === undefined || data.runId === opts.run);
+      if (opts.by === 'stage' || opts.by === 'model' || opts.by === 'account') {
+        const report = rollupByAxis(inputs, opts.by);
+        if (json) {
+          out.log(JSON.stringify(report, null, 2));
+          return;
+        }
+        if (report.length === 0) { out.log('(일치하는 런 사용량 없음)'); return; }
+        for (const row of report) out.log(formatAxisUsage(row, opts.by));
+        return;
+      }
       const report = rollupRunUsage(inputs, { by: opts.by });
       if (opts.by === 'role') report.sort((a, b) => b.calls - a.calls);
       if (json) {

package/src/core-turn/run-goal-loop.ts

@@ -212,9 +212,10 @@ export const GOAL_INTENT_STALL_PROMPT = [
 /** 재촉 상한 — 이 횟수를 쓰고도 텍스트만이면 종전 ④(텍스트 수용)로 그대로 떨어진다. */
 export const GOAL_INTENT_STALL_MAX_REPROMPTS = 2;
 
-/** 재촉 가드가 켜지는 provider — ⭐ 이번 조각은 OpenRouter(오픈웨이트 모델) 구현 자식 «한정»이다
- *  (OP 10-10 결정 · 실측 GLM Flash 첫 턴 40토큰 말만 하고 abandoned). 다른 provider 는 종전 그대로. */
-export const GOAL_INTENT_STALL_PROVIDERS: ReadonlySet<string> = new Set(['openrouter']);
+/** 재촉 가드가 켜지는 provider — 구현 자식을 내는 provider 전부(10-11 · 첫 조각 #25876 은 OpenRouter 한정이었다 ·
+ *  실측 GLM Flash 첫 턴 40토큰 말만 하고 abandoned). 재촉은 «도구 0회·텍스트만» 턴에만 걸리므로 도구를 부르는 자식에는 영향이 없다.
+ *  목록 밖 provider(local 등)는 종전 그대로 바로 수용한다. */
+export const GOAL_INTENT_STALL_PROVIDERS: ReadonlySet<string> = new Set(['openrouter', 'openai-codex', 'anthropic', 'grok', 'bedrock']);
 
 /** evidence 누락 complete 재주입 — update_goal(complete) 를 호출했으나 evidence 가 비었을 때. */
 export const GOAL_EVIDENCE_REQUIRED_PROMPT = [
@@ -280,7 +281,7 @@ export interface GoalLoopOptions {
   controlSpaceId?: string | null;
   /** Test seam — file-backed child liveness heartbeat. Default starts the workspace-file writer. */
   startLivenessHeartbeat?: typeof startChildLivenessHeartbeat;
-  /** GOAL-LOOP-INTENT-STALL — 구현 자식의 LLM provider. `openrouter` 일 때만 «도구 0회·텍스트만» 턴을
+  /** GOAL-LOOP-INTENT-STALL — 구현 자식의 LLM provider. GOAL_INTENT_STALL_PROVIDERS 에 있을 때만 «도구 0회·텍스트만» 턴을
    *  최대 2번 재촉한다. 생략하면 harness role 이 executor 인 프로세스에서만 활성 provider 로 푼다.
    *  null = 가드 꺼짐. 시험은 이 인자를 명시해 env 에 기대지 않는다. */
   intentStallProvider?: string | null;

package/src/dashboard/ad-run-setup-bindings.ts

@@ -0,0 +1,279 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildAdRunSetup } from '../ad-pipeline/ad-run-setup.js';
+import type { CommandRunner } from '../ad-pipeline/higgsfield-backend.js';
+import type { ShootRunOptions } from '../ad-pipeline/shoot-run.js';
+import type { QcThresholds } from '../ad-pipeline/qc.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import {
+  createDashboardAdSlashRuntime as createAdSlashRuntime,
+  type DashboardAdSlashRuntime,
+  type DashboardAdSlashRuntimeDeps,
+} from './ad-slash-runtime.js';
+
+const dashboardDefaultShootRunOptions: Required<Pick<ShootRunOptions, 'pollIntervalMs' | 'maxPollsPerJob' | 'submitStaggerMs'>> = {
+  pollIntervalMs: 3_000,
+  // 2026-09-12 seedance_2_0 measured 330–400s; 174 polls = 522s, leaving 402s after six 20s staggers.
+  maxPollsPerJob: 174,
+  submitStaggerMs: 20_000,
+};
+
+/**
+ * ⛔ `src/ad-pipeline/ad-run-setup.ts` 의 `optionalProductionInputs` «사본»이다 — 그 목록은 export 가 아니다.
+ * 여기서 다시 세는 이유: 이 파일이 `buildAdRunSetup` «뒤»에 `assemblyMaterials` 를 덧붙이므로,
+ * 그 함수가 «입력» 기준으로 낸 목록은 최종 `production` 과 어긋난다(`#17880`).
+ * ⚠️ 사본이라 «늙는다» — `src/dashboard/index.test.ts` 가 권위 목록과 같은지 단언한다.
+ */
+export const dashboardOptionalProductionInputs = [
+  'assembly',
+  'assemblyMaterials',
+  'captionFontPath',
+  'musicBedPath',
+  'qcThresholds',
+  'voiceover',
+  'soundtrack',
+  'referenceAssets',
+  'shootRunOptions',
+  'ground',
+  'invariants',
+] as const;
+
+export interface DashboardAdAssetPreset {
+  readonly captionFontPath?: string;
+  readonly musicBedPath?: string;
+  readonly referenceAssets?: Readonly<Record<string, string[]>>;
+  readonly shootRunOptions?: ShootRunOptions;
+  readonly qcThresholds?: QcThresholds;
+}
+
+/** Operator-owned, instance-scoped optional asset preset; never a repository asset path. */
+export function dashboardAdAssetPresetPath(stateRoot = elanousStateRoot()): string {
+  return join(stateRoot, 'ad-assets.json');
+}
+
+/** Reads optional operator-owned asset paths without inventing local defaults. */
+export function loadDashboardAdAssetPreset(path: string): DashboardAdAssetPreset {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw new Error(`dashboard ad asset preset unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: expected an object`);
+  }
+
+  const preset = parsed as Record<string, unknown>;
+  for (const key of ['captionFontPath', 'musicBedPath'] as const) {
+    if (preset[key] !== undefined && typeof preset[key] !== 'string') {
+      throw new Error(`dashboard ad asset preset malformed at ${path}: ${key} must be a string`);
+    }
+  }
+  if (preset.referenceAssets !== undefined && (
+    preset.referenceAssets === null
+    || typeof preset.referenceAssets !== 'object'
+    || Array.isArray(preset.referenceAssets)
+    || Object.values(preset.referenceAssets).some((value) => !Array.isArray(value) || value.some((entry) => typeof entry !== 'string'))
+  )) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: referenceAssets must be a record of string arrays`);
+  }
+  if (preset.shootRunOptions !== undefined && (
+    preset.shootRunOptions === null
+    || typeof preset.shootRunOptions !== 'object'
+    || Array.isArray(preset.shootRunOptions)
+  )) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: shootRunOptions must be an object`);
+  }
+  const shootRunOptions = preset.shootRunOptions as Record<string, unknown> | undefined;
+  for (const key of ['pollIntervalMs', 'maxPollsPerJob', 'maxPollElapsedMs', 'submitStaggerMs', 'submitRetries'] as const) {
+    if (shootRunOptions?.[key] !== undefined && (typeof shootRunOptions[key] !== 'number' || !Number.isFinite(shootRunOptions[key]))) {
+      throw new Error(`dashboard ad asset preset malformed at ${path}: shootRunOptions.${key} must be a finite number`);
+    }
+  }
+  if (preset.qcThresholds !== undefined && (
+    preset.qcThresholds === null
+    || typeof preset.qcThresholds !== 'object'
+    || Array.isArray(preset.qcThresholds)
+  )) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds must be an object`);
+  }
+  const qcThresholds = preset.qcThresholds as Record<string, unknown> | undefined;
+  for (const key of ['dialogueLufsTolerance', 'colorDistance', 'frameDiffVariance'] as const) {
+    if (qcThresholds?.[key] !== undefined && (typeof qcThresholds[key] !== 'number' || !Number.isFinite(qcThresholds[key]))) {
+      throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.${key} must be a finite number`);
+    }
+  }
+  if (qcThresholds?.durationRanges !== undefined && (
+    qcThresholds.durationRanges === null
+    || typeof qcThresholds.durationRanges !== 'object'
+    || Array.isArray(qcThresholds.durationRanges)
+  )) {
+    throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.durationRanges must be an object`);
+  }
+  const durationRanges = qcThresholds?.durationRanges as Record<string, unknown> | undefined;
+  for (const scope of ['cut', 'master'] as const) {
+    if (durationRanges?.[scope] !== undefined && (
+      durationRanges[scope] === null
+      || typeof durationRanges[scope] !== 'object'
+      || Array.isArray(durationRanges[scope])
+    )) {
+      throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.durationRanges.${scope} must be an object`);
+    }
+    const range = durationRanges?.[scope] as Record<string, unknown> | undefined;
+    if (range !== undefined) {
+      const minimumSeconds = range.minimumSeconds;
+      const maximumSeconds = range.maximumSeconds;
+      if (typeof minimumSeconds !== 'number' || !Number.isFinite(minimumSeconds)) {
+        throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.durationRanges.${scope}.minimumSeconds must be a finite number`);
+      }
+      if (typeof maximumSeconds !== 'number' || !Number.isFinite(maximumSeconds)) {
+        throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.durationRanges.${scope}.maximumSeconds must be a finite number`);
+      }
+      if (minimumSeconds > maximumSeconds) {
+        throw new Error(`dashboard ad asset preset malformed at ${path}: qcThresholds.durationRanges.${scope}.minimumSeconds must be less than or equal to maximumSeconds`);
+      }
+    }
+  }
+  return {
+    ...(typeof preset.captionFontPath === 'string' ? { captionFontPath: preset.captionFontPath } : {}),
+    ...(typeof preset.musicBedPath === 'string' ? { musicBedPath: preset.musicBedPath } : {}),
+    ...(preset.referenceAssets === undefined ? {} : { referenceAssets: preset.referenceAssets as Record<string, string[]> }),
+    ...(shootRunOptions === undefined ? {} : { shootRunOptions: shootRunOptions as ShootRunOptions }),
+    ...(qcThresholds === undefined ? {} : { qcThresholds: qcThresholds as QcThresholds }),
+  };
+}
+
+export const dashboardAdCommandRunner: CommandRunner = {
+  async run(argv, options) {
+    const process = Bun.spawn([...argv], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      ...(options?.timeoutMs ? { timeout: options.timeoutMs } : {}),
+    });
+    const [raw, stderr, exitCode] = await Promise.all([
+      new Response(process.stdout).bytes(),
+      new Response(process.stderr).text(),
+      process.exited,
+    ]);
+    return { stdout: new TextDecoder().decode(raw), stderr, exitCode, raw };
+  },
+};
+
+export function createDashboardAdRunSetupFactory(input: {
+  readonly home: string;
+  readonly date: string;
+  readonly contractsJson: string;
+  readonly runner: CommandRunner;
+  readonly assetPresetPath?: string;
+}): (allowSpend: boolean) => ReturnType<typeof buildAdRunSetup> {
+  let runSequence = 0;
+  let activeRunSlug: string | undefined;
+
+  return (allowSpend) => {
+    if (!allowSpend) {
+      const runStart = new Date();
+      const time = [runStart.getHours(), runStart.getMinutes(), runStart.getSeconds()]
+        .map((part) => String(part).padStart(2, '0'))
+        .join('');
+      activeRunSlug = `dashboard-ad-${time}-${++runSequence}`;
+    }
+    const slug = activeRunSlug ?? (() => {
+      const runStart = new Date();
+      const time = [runStart.getHours(), runStart.getMinutes(), runStart.getSeconds()]
+        .map((part) => String(part).padStart(2, '0'))
+        .join('');
+      return `dashboard-ad-${time}-${++runSequence}`;
+    })();
+    const assetPreset = input.assetPresetPath === undefined ? {} : loadDashboardAdAssetPreset(input.assetPresetPath);
+    let setup = buildAdRunSetup({
+      home: input.home,
+      slug,
+      date: input.date,
+      version: 1,
+      aspect: '9x16',
+      contractsJson: input.contractsJson,
+      runner: input.runner,
+      ...assetPreset,
+      referenceAssets: assetPreset.referenceAssets ?? {},
+      shootRunOptions: { ...dashboardDefaultShootRunOptions, ...assetPreset.shootRunOptions },
+      soundtrack: input.runner,
+      voiceover: { runner: input.runner, lines: [] },
+      allowSpend,
+    });
+    if (!('error' in setup) && setup.production) {
+      const production = {
+        ...setup.production,
+        assemblyMaterials: { options: { workDir: setup.workDir, outputName: setup.outputName } },
+      };
+      setup = {
+        ...setup,
+        production,
+        missingProductionInputs: dashboardOptionalProductionInputs.filter((key) => production[key] === undefined),
+      };
+    }
+    return setup;
+  };
+}
+
+/** Builds the /ad runtime bindings used by showDashboard for each invocation's spend intent. */
+export function createDashboardAdRunSetupBindings(
+  buildDashboardAdRunSetup: ReturnType<typeof createDashboardAdRunSetupFactory>,
+) {
+  let adRunSetup: ReturnType<typeof buildAdRunSetup> | undefined;
+  let outputSetupError: string | undefined;
+  try {
+    adRunSetup = buildDashboardAdRunSetup(false);
+    outputSetupError = 'error' in adRunSetup ? adRunSetup.error : undefined;
+  } catch (error) {
+    outputSetupError = error instanceof Error ? error.message : String(error);
+  }
+
+  return {
+    production: adRunSetup && !('error' in adRunSetup) ? adRunSetup.production : undefined,
+    productionForSpend: (allowSpend: boolean) => {
+      try {
+        const setup = buildDashboardAdRunSetup(allowSpend);
+        if ('error' in setup) {
+          outputSetupError = setup.error;
+          return undefined;
+        }
+        return setup.production;
+      } catch (error) {
+        outputSetupError = error instanceof Error ? error.message : String(error);
+        return undefined;
+      }
+    },
+    missingProductionInputs: adRunSetup && !('error' in adRunSetup) ? adRunSetup.missingProductionInputs : undefined,
+    get outputSetupError() {
+      return outputSetupError;
+    },
+  };
+}
+
+/** Connects the dashboard's setup state to the actual /ad runtime. */
+export function createDashboardAdSlashRuntime(
+  input: Omit<DashboardAdSlashRuntimeDeps, 'production' | 'productionForSpend' | 'missingProductionInputs' | 'outputSetupError'> & {
+    readonly adRunSetupBindings?: ReturnType<typeof createDashboardAdRunSetupBindings>;
+    readonly adRunSetupError?: string;
+  },
+): DashboardAdSlashRuntime {
+  const { adRunSetupBindings, adRunSetupError, ...deps } = input;
+  return createAdSlashRuntime({
+    ...deps,
+    production: adRunSetupBindings?.production,
+    productionForSpend: adRunSetupBindings?.productionForSpend,
+    missingProductionInputs: adRunSetupBindings?.missingProductionInputs,
+    get outputSetupError() {
+      return adRunSetupBindings?.outputSetupError ?? adRunSetupError;
+    },
+  });
+}
+