elanous 0.2.29 → 0.2.32

package/src/skills/tools/shell.ts

@@ -34,6 +34,8 @@ import {
 import type { ShellHandle, ShellResult as RunnerResult } from '../../shell-runner/types.js';
 import { debug } from '../../debug/log.js';
 import { getSessionCwd } from '../../session/working-dir.js';
+import { getUserConfig } from '../../user-config.js';
+import { SCHEDULE_WAKEUP_TOOL_NAME } from './schedule-wakeup.js';
 import {
   globalTaskNotificationQueue,
   type TaskNotificationQueue,
@@ -193,7 +195,7 @@ function rejectedCdResult(): RunShellDispatchResult {
 // always serve THIS process's instance.
 const LEDGER_CLI_BIN = /(?:^|[/\\])(?:elanous|elanous\.mjs|elanous\.cjs|eln)$/;
 const LEDGER_ENV_BIN = /(?:^|[/\\])env$/;
-const LEDGER_CLI_NATIVE_TOOL: Readonly<Record<string, string>> = {
+export const LEDGER_CLI_NATIVE_TOOL: Readonly<Record<string, string>> = {
   'msg list': 'MsgList',
   'msg post': 'MsgPost',
   'msg ack': 'MsgAck',
@@ -288,6 +290,231 @@ export function rejectedLedgerCliResult(
   };
 }
 
+// ── long sleep inside a turn (TUI-RUNSHELL-LONG-SLEEP · #38) ──────────────
+// A seat agent told "check again at 22:45" held its turn inside RunShell with
+// a long sleep, so the TUI stayed busy for 8+ minutes and the human could not
+// type. The command still runs unchanged (blocking it would break legitimate
+// waits); the result gains one warning line and `shell.run long-sleep` is
+// logged BEFORE the wait starts, so the hold is visible while it happens.
+// Static argv/script inspection only — no shell is spawned to analyse.
+
+export const DEFAULT_LONG_SLEEP_WARN_SECONDS = 60;
+
+export type LongSleepPattern = 'sleep' | 'shell-sleep' | 'poll-loop' | 'python-sleep' | 'computed-sleep';
+
+export interface LongSleepFinding {
+  pattern: LongSleepPattern;
+  /** Estimated total wait in seconds; null when unbounded or not literal. */
+  seconds: number | null;
+  /** Per-iteration sleep of a poll loop (poll-loop only; null when not literal). */
+  perIterationSeconds?: number | null;
+  limitSeconds: number;
+}
+
+/** `tools.runShell.longSleepWarnSeconds` from a raw config root (positive number) or the default. */
+export function longSleepWarnSecondsFrom(raw: Record<string, unknown> | undefined): number {
+  const tools = raw?.tools as { runShell?: { longSleepWarnSeconds?: unknown } } | undefined;
+  const v = tools?.runShell?.longSleepWarnSeconds;
+  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : DEFAULT_LONG_SLEEP_WARN_SECONDS;
+}
+
+function longSleepWarnSeconds(): number {
+  try {
+    return longSleepWarnSecondsFrom(getUserConfig().raw);
+  } catch { /* config unreadable → default */ }
+  return DEFAULT_LONG_SLEEP_WARN_SECONDS;
+}
+
+const SLEEP_UNIT_SECONDS: Readonly<Record<string, number>> = { '': 1, s: 1, m: 60, h: 3600, d: 86400 };
+
+/** coreutils `sleep` operand → seconds (`480`, `5m`, `1.5h`, `infinity`), null when not literal. */
+function parseSleepOperand(token: string): number | null {
+  if (/^inf(?:inity)?$/i.test(token)) return Infinity;
+  const m = /^(\d+(?:\.\d+)?|\.\d+)([smhd]?)$/.exec(token);
+  return m ? Number(m[1]) * SLEEP_UNIT_SECONDS[m[2]!]! : null;
+}
+
+function binName(arg: string | undefined): string {
+  return (arg ?? '').split(/[/\\]/).pop() ?? '';
+}
+
+/** Strip argv-preserving wrappers (env/timeout/nice/nohup/command/exec/time).
+ *  `timeout D …` caps the wait, so its duration is returned as `capSeconds`. */
+function unwrapArgv(command: readonly string[]): { argv: readonly string[]; capSeconds: number } {
+  let argv = command;
+  let capSeconds = Infinity;
+  for (let guard = 0; guard < 8 && argv.length > 0; guard += 1) {
+    const bin = binName(argv[0]);
+    let i = 1;
+    if (bin === 'env') {
+      while (i < argv.length && (argv[i]!.startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[i]!))) {
+        if (['-u', '--unset', '-C', '--chdir', '-S', '--split-string'].includes(argv[i]!)) i += 1;
+        i += 1;
+      }
+    } else if (bin === 'timeout' || bin === 'gtimeout') {
+      while (i < argv.length && argv[i]!.startsWith('-')) {
+        if (['-s', '--signal', '-k', '--kill-after'].includes(argv[i]!)) i += 1;
+        i += 1;
+      }
+      const cap = parseSleepOperand(argv[i] ?? '');
+      if (cap !== null) capSeconds = Math.min(capSeconds, cap);
+      i += 1;
+    } else if (bin === 'nice') {
+      if (argv[1] === '-n') i = 3;
+      else if ((argv[1] ?? '').startsWith('-')) i = 2;
+    } else if (!['nohup', 'command', 'exec', 'time'].includes(bin)) {
+      break;
+    }
+    argv = argv.slice(i);
+  }
+  return { argv, capSeconds };
+}
+
+interface ScriptSleep { index: number; seconds: number | null }
+interface ScriptScan { sleeps: ScriptSleep[]; loopBodyStart: number; loopIterations: number | null }
+
+function scanShellScript(script: string): ScriptScan {
+  const sleeps: ScriptSleep[] = [];
+  // Command position only — `echo sleep 480` is an argument, not a wait.
+  const sleepRe = /(?:^|[;&|(`{\n]|\b(?:do|then|else)\b)[ \t]*sleep[ \t]+([^;&|)\n`}]+)/g;
+  for (let m = sleepRe.exec(script); m; m = sleepRe.exec(script)) {
+    const operands = m[1]!.trim().split(/\s+/).filter((t) => !t.startsWith('-'));
+    let total = 0;
+    for (const op of operands) {
+      const s = parseSleepOperand(op.replace(/^['"]|['"]$/g, ''));
+      if (s === null) { total = NaN; break; }
+      total += s;
+    }
+    sleeps.push({ index: m.index + m[0].indexOf('sleep'), seconds: operands.length > 0 && !Number.isNaN(total) ? total : null });
+  }
+  const loopRe = /(?:^|[;&|\n({]|\b(?:then|do|else)\b)\s*(while|until|for)\b([\s\S]*?)(?:;|\n)\s*do\b/;
+  const loop = loopRe.exec(script);
+  if (!loop) return { sleeps, loopBodyStart: -1, loopIterations: null };
+  let loopIterations: number | null = null;
+  if (loop[1] === 'for') {
+    const header = loop[2]!;
+    const brace = /\{(\d+)\.\.(\d+)\}/.exec(header);
+    const seq = /\$\(\s*seq\s+(\d+)(?:\s+(\d+))?\s*\)/.exec(header);
+    const words = /\bin\s+([^`$(){}]*)$/.exec(header.trim());
+    if (brace) loopIterations = Math.abs(Number(brace[2]) - Number(brace[1])) + 1;
+    else if (seq) loopIterations = seq[2] === undefined ? Number(seq[1]) : Math.max(0, Number(seq[2]) - Number(seq[1]) + 1);
+    else if (words) loopIterations = words[1]!.trim().split(/\s+/).filter(Boolean).length;
+  }
+  return { sleeps, loopBodyStart: loop.index + loop[0].length, loopIterations };
+}
+
+function scanPythonCode(code: string): ScriptScan {
+  const sleeps: ScriptSleep[] = [];
+  const sleepRe = /\b(?:time\.)?sleep\s*\(\s*([^)]*)\)/g;
+  for (let m = sleepRe.exec(code); m; m = sleepRe.exec(code)) {
+    const arg = m[1]!.trim();
+    sleeps.push({ index: m.index, seconds: /^(\d+(?:\.\d+)?|\.\d+)$/.test(arg) ? Number(arg) : null });
+  }
+  const loop = /(?:^|[;\n])\s*(while|for)\b([^:\n]*):/.exec(code);
+  if (!loop) return { sleeps, loopBodyStart: -1, loopIterations: null };
+  let loopIterations: number | null = null;
+  if (loop[1] === 'for') {
+    const range = /\brange\(\s*(\d+)(?:\s*,\s*(\d+))?\s*\)/.exec(loop[2]!);
+    if (range) loopIterations = range[2] === undefined ? Number(range[1]) : Math.max(0, Number(range[2]) - Number(range[1]));
+  }
+  return { sleeps, loopBodyStart: loop.index + loop[0].length, loopIterations };
+}
+
+function evaluateScan(
+  scan: ScriptScan, sleepPattern: LongSleepPattern, capSeconds: number, limitSeconds: number,
+): LongSleepFinding | null {
+  if (scan.sleeps.length === 0) return null;
+  const inLoop = scan.loopBodyStart >= 0 ? scan.sleeps.filter((s) => s.index >= scan.loopBodyStart) : [];
+  const outside = scan.sleeps.filter((s) => !inLoop.includes(s));
+  let total = outside.reduce((acc, s) => acc + (s.seconds ?? 0), 0);
+  if (inLoop.length > 0) {
+    const perIteration = inLoop.some((s) => s.seconds === null)
+      ? null : inLoop.reduce((acc, s) => acc + s.seconds!, 0);
+    const loopTotal = scan.loopIterations === null || perIteration === null
+      ? Infinity : perIteration * scan.loopIterations;
+    total = Math.min(total + loopTotal, capSeconds);
+    if (total > limitSeconds) {
+      return { pattern: 'poll-loop', seconds: Number.isFinite(total) ? total : null, perIterationSeconds: perIteration, limitSeconds };
+    }
+    return null;
+  }
+  total = Math.min(total, capSeconds);
+  if (total > limitSeconds) return { pattern: sleepPattern, seconds: Number.isFinite(total) ? total : null, limitSeconds };
+  if (outside.some((s) => s.seconds === null) && capSeconds > limitSeconds) {
+    return { pattern: 'computed-sleep', seconds: null, limitSeconds };
+  }
+  return null;
+}
+
+/** Long in-turn wait in a RunShell argv, or null. Exported for tests. */
+export function detectLongSleep(
+  command: readonly string[], limitSeconds: number = DEFAULT_LONG_SLEEP_WARN_SECONDS,
+): LongSleepFinding | null {
+  const { argv, capSeconds } = unwrapArgv(command);
+  const bin = binName(argv[0]);
+  if (bin === 'sleep') {
+    const operands = argv.slice(1).filter((t) => !t.startsWith('-'));
+    let total = 0;
+    for (const op of operands) {
+      const s = parseSleepOperand(op);
+      if (s === null) return null; // sleep itself rejects it — no wait happens
+      total += s;
+    }
+    total = Math.min(total, capSeconds);
+    return total > limitSeconds
+      ? { pattern: 'sleep', seconds: Number.isFinite(total) ? total : null, limitSeconds }
+      : null;
+  }
+  const scriptFlag = argv.findIndex((a, i) => i > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(a));
+  const script = scriptFlag > 0 ? argv[scriptFlag + 1] : undefined;
+  if (script === undefined) return null;
+  if (/^(?:ba|z|da|k)?sh$/.test(bin)) {
+    return evaluateScan(scanShellScript(script), 'shell-sleep', capSeconds, limitSeconds);
+  }
+  if (/^python(?:\d+(?:\.\d+)?)?$/.test(bin) && argv[scriptFlag] === '-c') {
+    return evaluateScan(scanPythonCode(script), 'python-sleep', capSeconds, limitSeconds);
+  }
+  return null;
+}
+
+/**
+ * Which resume path the warning names (TUI-RUNSHELL-LONG-SLEEP follow-up):
+ * `schedule-wakeup` when the turn was offered the ScheduleWakeup host tool
+ * (seat TUI · dashboard host tool), `generic` elsewhere (harness children,
+ * MCP, CLI agents) where that tool does not exist.
+ */
+export type LongSleepResumeHint = 'schedule-wakeup' | 'generic';
+
+/** `ScheduleWakeup` in this turn's tool list → name it; otherwise the generic resume advice. */
+export function longSleepResumeHint(availableToolNames: readonly string[] | undefined): LongSleepResumeHint {
+  return availableToolNames?.includes(SCHEDULE_WAKEUP_TOOL_NAME) ? 'schedule-wakeup' : 'generic';
+}
+
+/** The one warning line prefixed to a RunShell result. Exported for tests. */
+export function formatLongSleepWarning(
+  finding: LongSleepFinding, bgAvailable: boolean, resumeHint: LongSleepResumeHint = 'generic',
+): string {
+  const wait = finding.pattern === 'poll-loop'
+    ? `a poll loop sleeping ${finding.perIterationSeconds ?? '?'}s per iteration (total ${finding.seconds === null ? 'unbounded' : `~${finding.seconds}s`})`
+    : finding.pattern === 'computed-sleep'
+      ? 'a sleep of computed length'
+      : `a sleep of ${finding.seconds === null ? 'unbounded length' : `~${finding.seconds}s`}`;
+  const resume = resumeHint === 'schedule-wakeup'
+    ? `end the turn and call ${SCHEDULE_WAKEUP_TOOL_NAME} (delaySeconds ≥60, at "HH:MM", or repeatMinutes) so a wakeup turn resumes the work`
+    : 'end the turn and let the next turn or a mail wake resume the work';
+  return `⚠ RunShell long-sleep: this command waited inside the turn with ${wait} (limit ${finding.limitSeconds}s) — `
+    + `the turn stays busy and the human cannot type meanwhile. Do not hold the turn to wait: ${resume}`
+    + (bgAvailable ? ", or start long-running work with mode:'bg' (its completion arrives as a notification)." : '.');
+}
+
+function withLongSleepWarning(
+  result: RunShellDispatchResult, finding: LongSleepFinding | null, bgAvailable: boolean,
+  resumeHint: LongSleepResumeHint,
+): RunShellDispatchResult {
+  if (!finding) return result;
+  return { ...result, output: `${formatLongSleepWarning(finding, bgAvailable, resumeHint)}\n${result.output}` };
+}
+
 function logShellDispatch(event: string, data: Record<string, unknown>): void {
   debug.log('shell.dispatch', event, data);
 }
@@ -379,6 +606,21 @@ export async function dispatchRunShell(
   // Explicit inline/bg uses the file-backed runner when its deps are installed;
   // omitted mode and uninitialized hosts keep the legacy argv path.
   const deps = mode ? getShellRunnerDeps() : null;
+  // A bg handle returns immediately, so only blocking paths can hold the turn.
+  // Note `mode:'bg'` without runner deps falls through to the blocking legacy path.
+  const longSleep = mode === 'bg' && deps ? null : detectLongSleep(command, longSleepWarnSeconds());
+  const resumeHint = longSleepResumeHint(opts.availableToolNames);
+  if (longSleep) {
+    debug.log('shell.run', 'long-sleep', {
+      seconds: longSleep.seconds,
+      pattern: longSleep.pattern,
+      ...(longSleep.perIterationSeconds !== undefined ? { perIterationSeconds: longSleep.perIterationSeconds } : {}),
+      limitSeconds: longSleep.limitSeconds,
+      path: mode && deps ? 'runner' : 'legacy',
+      resumeHint,
+    });
+  }
+  const bgAvailable = getShellRunnerDeps() !== null;
   if (mode && deps) {
     const result = await dispatchViaRunner({
       command, cwd, timeoutMs, mode, description,
@@ -386,7 +628,7 @@ export async function dispatchRunShell(
       deps,
     });
     logShellDispatch(`runner.${result.outcome}`, { cwd: effectiveCwd, cwdSource });
-    return result;
+    return withLongSleepWarning(result, longSleep, bgAvailable, resumeHint);
   }
 
   const result = await runShell({
@@ -401,7 +643,7 @@ export async function dispatchRunShell(
 
   logShellDispatch(`legacy.${result.outcome}`, { cwd: effectiveCwd, cwdSource });
   const summary = formatSummary(result);
-  return {
+  return withLongSleepWarning({
     output: summary,
     exitCode: result.exitCode,
     outcome: result.outcome,
@@ -412,7 +654,7 @@ export async function dispatchRunShell(
     approvalKey: result.approvalKey,
     sandboxed: result.sandboxed,
     sandboxTool: result.sandboxTool,
-  };
+  }, longSleep, bgAvailable, resumeHint);
 }
 
 /** Route a request through the file-backed shell-runner and project its

package/src/status/bar.ts

@@ -659,6 +659,32 @@ export function shellRollupSegment(
   return text(`🐚 ${parts.join(' ')}`, tone, opts);
 }
 
+/** TUI-BG-JOB-VISIBILITY (#71) — 턴이 끝난 뒤에도 남는 백그라운드 일을 상태줄에서 보이게 한다.
+ *
+ *  🚨 10-16 07:3x OPT 가 «남은 리뷰 4건 실행 중 · 다음 점검 = …» 로 턴을 «✔ 완료» 로 끝내자
+ *     바깥에선 «12분 유휴» 로 보였다.
+ *
+ *      ⧗ 백그라운드 2   — 등록된(ShellRegistry) 백그라운드 일 2개가 돈다
+ *      (빈 문자열)       — 0 · 끝나면 사라진다
+ *
+ *  `background` = 살아 있는 bg 모드 핸들 ⊕ backgrounded(인라인 전경 실행은 안 셈 — 그건 🐚 몫).
+ *  명령 안 `&`·`nohup` 으로 떼어 낸 프로세스는 등록되지 않아 여기 안 잡힌다.
+ *  깨우기(끝나면 턴을 여는 것)는 이 세그먼트 몫이 아니다 — TUI-AGENT-IDLE-WAKE 칸.
+ *  `runningAgentsSegment` 와 같은 꼴 · 같은 색 계열(peach). */
+export interface BackgroundJobsSummary {
+  background: number;
+}
+
+export function backgroundJobsSegment(
+  summary: BackgroundJobsSummary | null | undefined,
+  opts: StatusBarRenderOptions = {},
+): string {
+  if (!summary) return '';
+  const live = Number.isFinite(summary.background) ? Math.max(0, Math.floor(summary.background)) : 0;
+  if (live <= 0) return '';
+  return text(`⧗ 백그라운드 ${live}`, 'peach', opts);
+}
+
 export type DockStripDensity = 'full' | 'compact' | 'count-only';
 
 export interface DockStripSegmentOptions extends StatusBarRenderOptions {

package/src/steward/digest-delivery.ts

@@ -0,0 +1,118 @@
+/**
+ * 스튜어드 발송 모듈 — 흐름 판정 변화 브리핑(OVW-BRIEF · RFC §A4·§A7).
+ *
+ * §A4 — 브리핑은 판정이 «마지막으로 브리핑한 값»과 달라질 때만 한 줄.
+ * §A7 — 경계값 플래핑 방지: «2연속» 같은 판정으로 관측될 때만 발송.
+ * 발송 킨드 = `ops-report`(운영 봇) — 스튜어드 digest 와 같은 통로, 트레이딩 봇으로는 내려가지 않는다.
+ */
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { collectOverview, parseSince } from '../ops/overview-collect.js';
+import { VERDICT_LABEL, VERDICTS, computeVerdict, type OverviewSnapshot, type Verdict, type VerdictResult } from '../ops/overview.js';
+
+/** 브리핑 상태 파일 — 인스턴스 루트 기준 상대 경로. */
+export const VERDICT_BRIEF_STATE = 'steward/verdict-brief.json';
+
+export interface VerdictBriefState {
+  /** 마지막 관측 판정 — streak 를 센다. */
+  lastObserved: Verdict | null;
+  /** 마지막으로 «브리핑을 보낸» 판정 — 이 값과 같으면 다시 보내지 않는다(§A4). */
+  lastBriefed: Verdict | null;
+  /** lastObserved 가 «연속»으로 관측된 횟수 — 2 이상이어야 발송한다(§A7). */
+  streak: number;
+}
+
+export function emptyVerdictBriefState(): VerdictBriefState {
+  return { lastObserved: null, lastBriefed: null, streak: 0 };
+}
+
+/** 판정 한 번 관측 — 같은 판정이면 streak 를 쌓고, 다른 판정이면 1로 되돌린다. */
+export function observeVerdict(state: VerdictBriefState, observed: Verdict): VerdictBriefState {
+  if (state.lastObserved === observed) return { ...state, streak: state.streak + 1 };
+  return { lastBriefed: state.lastBriefed, lastObserved: observed, streak: 1 };
+}
+
+/** 발송 조건 — §A7(2연속 관측) ⊕ §A4(마지막 브리핑과 다른 판정). */
+export function briefDue(state: VerdictBriefState): boolean {
+  return state.streak >= 2 && state.lastObserved !== state.lastBriefed;
+}
+
+/** 브리핑 한 줄 — 새 판정 ⊕ 이전 판정(있으면) ⊕ 첫 사유 ⊕ 첫 다음 행동. */
+export function formatVerdictBrief(current: VerdictResult, previous: Verdict | null): string {
+  const one = (text: string | undefined) => (text ?? '').replace(/\s+/g, ' ').trim();
+  const reason = one(current.reasons[0]);
+  const next = one(current.nextActions[0]);
+  const from = previous ? ` (이전 ${VERDICT_LABEL[previous]})` : '';
+  return `스튜어드 흐름 · 판정 변화 ${VERDICT_LABEL[current.verdict]}${from}${reason ? ` · ${reason}` : ''}${next ? ` · 다음: ${next}` : ''}`;
+}
+
+export interface VerdictBriefDeps {
+  /** 판정 계산용 스냅샷 — 기본: `elanous ops overview` CLI 와 같은 창(최근 1h)으로 수집. */
+  collect?: () => Promise<OverviewSnapshot>;
+  /** 브리핑 발송 — 기본: 킨드 `ops-report`(운영 봇)으로 직접 발송. */
+  send?: (text: string) => Promise<void>;
+  /** 상태 파일 경로 — 기본: <root>/steward/verdict-brief.json. */
+  statePath?: string;
+}
+
+export function verdictBriefStatePath(root: string): string {
+  return join(root, VERDICT_BRIEF_STATE);
+}
+
+function isVerdict(value: unknown): value is Verdict {
+  return typeof value === 'string' && (VERDICTS as readonly string[]).includes(value);
+}
+
+function readBriefState(path: string): VerdictBriefState {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<VerdictBriefState>;
+    if (isVerdict(raw.lastObserved) && (raw.lastBriefed == null || isVerdict(raw.lastBriefed)) && typeof raw.streak === 'number') {
+      return { lastObserved: raw.lastObserved, lastBriefed: raw.lastBriefed ?? null, streak: raw.streak };
+    }
+  } catch {
+    /* 상태가 없거나 깨졌으면 새로 시작한다 — 다음 관측이 streak 를 다시 쌓는다. */
+  }
+  return emptyVerdictBriefState();
+}
+
+function writeBriefState(path: string, state: VerdictBriefState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/** 스튜어드 운영 발송 — 킨드 `ops-report`(운영 봇). digest 와 같은 통로, 다른 줄. */
+export async function sendStewardReport(text: string): Promise<void> {
+  const { deliver } = await import('../domains/outbound-alert.js');
+  if (!deliver(text, 'ops-report')) throw new Error('steward report delivery failed');
+}
+
+/**
+ * 흐름 판정을 관측해, «2연속 같은 판정»이 «마지막 브리핑과 다를 때»만 한 줄을 보낸다(§A4·§A7).
+ * 관측(streak)은 항상 상태로 남고, 마지막 브리핑 값은 발송 성공 뒤에만 진행한다 —
+ * 실패한 브리핑은 다음 틱의 같은 판정 관측이 재시도한다.
+ * @returns 보낸 브리핑 원문 — 이번 관측에서 보내지 않았으면 null.
+ */
+export async function briefVerdictChange(root: string, deps: VerdictBriefDeps = {}): Promise<string | null> {
+  const collect = deps.collect ?? defaultCollect;
+  const snapshot = await collect();
+  const result = computeVerdict(snapshot);
+  const statePath = deps.statePath ?? verdictBriefStatePath(root);
+  const state = readBriefState(statePath);
+  const observed = observeVerdict(state, result.verdict);
+  if (!briefDue(observed)) {
+    writeBriefState(statePath, observed);
+    debug.log('steward.verdict-brief', 'held', { verdict: result.verdict, streak: observed.streak });
+    return null;
+  }
+  const text = formatVerdictBrief(result, state.lastBriefed);
+  await (deps.send ?? sendStewardReport)(text);
+  writeBriefState(statePath, { ...observed, lastBriefed: result.verdict });
+  debug.log('steward.verdict-brief', 'sent', { verdict: result.verdict, previous: state.lastBriefed });
+  return text;
+}
+
+async function defaultCollect(): Promise<OverviewSnapshot> {
+  const { ms, label } = parseSince(undefined);
+  return collectOverview({ sinceMs: ms, sinceLabel: label });
+}

package/src/steward/hold-hygiene.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { openMsgStore } from '../msg/msg-store.js';
+import { opSeatStatePath, readTrafficSignal } from '../seat-loop/traffic-signal.js';
+
+const SEATS = ['OP', 'MK', 'TC', 'UX'] as const;
+type Seat = typeof SEATS[number];
+export type HygieneCell = { id: string; owner?: string | null; status: string };
+export type HygieneNotice = { to: Seat; key: string; body: string };
+export type HygieneDeps = {
+  root: string;
+  now: Date;
+  cells: readonly HygieneCell[];
+  trafficPath?: string;
+  metaPath?: string;
+  dispatcherDir?: string;
+};
+
+function readOptional(path: string): string | null {
+  try { return readFileSync(path, 'utf8'); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
+}
+
+/** A following budget line closes the preceding cycle; a trailing cycle may still launch. */
+export function starvingCycles(log: string): { reasons: Record<string, number> } | null {
+  const cycles: Array<{ budget: number; launches: number; noCapacity: number; reasons: Record<string, number> }> = [];
+  for (const line of log.split(/\r?\n/)) {
+    const budget = /역압 예산\s*(\d+)/.exec(line);
+    if (budget) cycles.push({ budget: Number(budget[1]), launches: 0, noCapacity: 0, reasons: {} });
+    else if (cycles.length) {
+      const current = cycles[cycles.length - 1]!;
+      if (/발사\s+\S/.test(line)) current.launches++;
+      if (line.includes('여유 없음')) current.noCapacity++;
+      const skip = /건너뜀\s*(.*)/.exec(line);
+      if (skip) {
+        const reason = skip[1]?.trim() || '사유 미기록';
+        current.reasons[reason] = (current.reasons[reason] ?? 0) + 1;
+      }
+    }
+  }
+  const last = cycles.slice(0, -1).slice(-3);
+  if (last.length !== 3 || last.some(cycle => cycle.budget <= 0 || cycle.launches !== 0 || cycle.noCapacity !== 0)) return null;
+  const reasons: Record<string, number> = {};
+  for (const cycle of last) for (const [reason, count] of Object.entries(cycle.reasons)) reasons[reason] = (reasons[reason] ?? 0) + count;
+  return { reasons };
+}
+
+type HoldMeta = { id?: unknown; op?: unknown; reason?: unknown; until?: unknown };
+function holdMetadata(path: string): Map<string, HoldMeta> {
+  const latest = new Map<string, HoldMeta>();
+  for (const line of (readOptional(path) ?? '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line) as HoldMeta;
+      if (typeof row.id === 'string') latest.set(row.id, row);
+    } catch { /* An invalid row cannot supply a reason for any hold. */ }
+  }
+  return latest;
+}
+
+function untilTime(value: unknown): number | null {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const compact = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
+  const time = compact ? Date.parse(`${compact[1]}-${compact[2]}-${compact[3]}T${compact[4]}:${compact[5]}:00+09:00`) : Date.parse(value);
+  return Number.isFinite(time) ? time : null;
+}
+
+export function inspectHoldHygiene(deps: HygieneDeps): HygieneNotice[] {
+  const notices: HygieneNotice[] = [];
+  const dir = deps.dispatcherDir ?? opSeatStatePath('feeder');
+  for (const seat of SEATS) {
+    const log = readOptional(join(dir, `dispatcher-${seat}.out`));
+    const finding = log === null ? null : starvingCycles(log);
+    if (!finding) continue;
+    const detail = Object.entries(finding.reasons).map(([reason, count]) => `${reason} ×${count}`).join(' · ') || '건너뜀 사유 미기록';
+    const body = `${seat} 디스패처 굶주림: 최근 3주기 예산>0 · 발사 0 · 여유 없음 0. 건너뜀: ${detail}. 후보 칸·잠금·경로를 확인해 주세요.`;
+    for (const to of new Set<Seat>(['OP', seat])) notices.push({ to, key: `starve:${seat}:${to}`, body });
+  }
+  const signal = readTrafficSignal(deps.trafficPath);
+  if (!signal || 'unreadable' in signal) return notices;
+  const held = new Set(signal.hold ?? []);
+  const metadata = holdMetadata(deps.metaPath ?? opSeatStatePath(join('tools', 'hold-meta.jsonl')));
+  const seen = new Set<string>();
+  for (const cell of deps.cells) {
+    if (!held.has(cell.id) || cell.status !== 'yellow' || seen.has(cell.id)) continue;
+    seen.add(cell.id);
+    const owner = cell.owner;
+    if (!SEATS.some(seat => seat === owner)) continue;
+    const meta = metadata.get(cell.id);
+    const reason = meta?.op === 'add' && typeof meta.reason === 'string' ? meta.reason.trim() : '';
+    const expiry = untilTime(meta?.until);
+    const expired = typeof meta?.until === 'string' && meta.until.trim() !== '' && (expiry === null || expiry <= deps.now.getTime());
+    if (reason && !expired) continue;
+    notices.push({ to: owner as Seat, key: `hold:${cell.id}:${owner}`,
+      body: `노랑 칸 ${cell.id} traffic hold: ${!reason ? '사유 없음' : `사유 ${reason}`} ${expired ? `· until ${String(meta?.until)} 지남` : ''}. 풀기/유지(사유·until)를 판단해 OP에 알려 주세요. 자동 해제하지 않습니다.` });
+  }
+  return notices;
+}
+
+/** One durable msg per recipient/key per 30 minutes, even when two tick processes race. */
+export function runHoldHygiene(deps: HygieneDeps): HygieneNotice[] {
+  const notices = inspectHoldHygiene(deps);
+  if (!notices.length) return [];
+  const store = openMsgStore(join(deps.root, 'msg', 'messages.db'));
+  const sent: HygieneNotice[] = [];
+  try {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS hold_hygiene_notices (key TEXT PRIMARY KEY, sent_at INTEGER NOT NULL)`);
+    for (const notice of notices) {
+      store.db.transaction(() => {
+        const prior = store.db.query('SELECT sent_at FROM hold_hygiene_notices WHERE key = ?').get(notice.key) as { sent_at: number } | null;
+        if (prior && deps.now.getTime() - prior.sent_at < 30 * 60_000) return;
+        store.append({ from: 'ORCHESTRATOR', to: notice.to, body: notice.body, kind: 'hold-hygiene' });
+        store.db.query('INSERT INTO hold_hygiene_notices(key, sent_at) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET sent_at = excluded.sent_at')
+          .run(notice.key, deps.now.getTime());
+        sent.push(notice);
+      }).immediate();
+    }
+  } finally { store.close(); }
+  return sent;
+}