elanous 0.2.17 → 0.2.19

package/src/domains/guardian-tick.ts

@@ -0,0 +1,138 @@
+import type { Database } from 'bun:sqlite';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../debug/log.js';
+import { calendarFields, resolveTimeZone } from '../time/format.js';
+import { cronMatches } from './cron-match.js';
+import { listScheduleRuns } from './schedule-runs.js';
+import { listSchedules, openSchedulesDb, type ScheduleRow } from './schedule-registry.js';
+import type { SpawnOutcome } from './schedule-runner.js';
+
+export interface GuardianPlan {
+  jobs: readonly (Pick<ScheduleRow, 'id' | 'cron' | 'enabled' | 'source' | 'run_via'> & Partial<Pick<ScheduleRow, 'command'>>)[];
+  timeZone?: string;
+}
+
+export interface GuardianDeps {
+  config?: { guardian?: { mode?: 'shadow' | 'live' } };
+  /** Inject a cron-run-compatible executor in tests; shadow never calls it. */
+  execute?: (command: string) => Promise<SpawnOutcome>;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function matchedJobs(plan: GuardianPlan): GuardianPlan['jobs'] {
+  return plan.jobs.filter(job => job.source === 'crontab' && job.run_via === 'crontab' && !!job.enabled && !!job.cron);
+}
+
+/** The wrapper prefix a live run may reuse as-is: `<bun> <…/>cron-run.ts --schedule-id <id> …` as the command's own
+ * first program (cron-run honours --schedule-id only as argv[0]). Fail-closed: any other mention of cron-run.ts —
+ * e.g. inside a `sh -c` body, behind `cd … &&`, or with shell control operators — is ambiguous and refused, so a run
+ * can never be attributed to the wrong (or no) schedule id. Unwrapped commands are wrapped with this job's id. */
+function liveCommand(jobId: string, raw: string): string {
+  if (!/cron-run\.ts/.test(raw)) {
+    return `${shellQuote(process.execPath)} ${shellQuote(fileURLToPath(new URL('../../scripts/cron-run.ts', import.meta.url)))} --schedule-id ${shellQuote(jobId)} --shell /bin/sh -c ${shellQuote(raw)}`;
+  }
+  // First program must be bun itself (bare `bun`, a path ending in /bun, or this process's executable).
+  const prefix = /^\s*(?:'(?:[^']*\/)?bun'|(?:[^\s'"]*\/)?bun)\s+(?:'[^']*\/)?(?:[^\s'"]*\/)?cron-run\.ts'?\s+--schedule-id\s+(?:'([^']*)'|([^\s'"]+))(?:\s|$)/.exec(raw);
+  const declaredId = prefix ? (prefix[1] ?? prefix[2]) : undefined;
+  const controls = /[;&|`\n]|\$\(/.test(raw);
+  if (declaredId !== jobId || controls || (raw.match(/cron-run\.ts/g) ?? []).length !== 1) {
+    throw new Error(`guardian live job ${jobId}: cron-run --schedule-id is ${declaredId ?? 'missing'}${controls ? ' (shell control operators)' : ''} — refusing misattributed run`);
+  }
+  return raw;
+}
+
+/** One five-minute guardian observation. No schedule state or crontab is mutated in shadow mode. */
+export async function guardianTick(now: Date, plan: GuardianPlan, deps: GuardianDeps = {}): Promise<{ mode: 'shadow' | 'live'; wouldRun: string[]; executed: number }> {
+  if (!Number.isFinite(now.getTime())) throw new RangeError('invalid tick time');
+  const mode = deps.config?.guardian?.mode === 'live' ? 'live' : 'shadow';
+  const timeZone = plan.timeZone ?? resolveTimeZone().timeZone;
+  const wouldRun: string[] = [];
+  let executed = 0;
+  for (const job of matchedJobs(plan)) {
+    if (!cronMatches(job.cron!, now, { timeZone })) continue;
+    wouldRun.push(job.id);
+    debug.log('guardian.tick', 'would-run', { job: job.id, cron: job.cron });
+    if (mode === 'live') {
+      if (!job.command) throw new Error(`guardian live job has no command: ${job.id}`);
+      const command = liveCommand(job.id, job.command);
+      const execute = deps.execute ?? (await import('./schedule-runner.js')).defaultSpawnJob;
+      const outcome = await execute(command);
+      executed++;
+      if (outcome.code !== 0) throw new Error(`guardian job ${job.id} exited ${outcome.code}`);
+    }
+  }
+  return { mode, wouldRun, executed };
+}
+
+export interface GuardianDayDeps {
+  db: Database;
+  plan: GuardianPlan;
+  /** Optional measured alert counts, keyed by stable schedule id. Absent means unmeasured, not zero. */
+  alertsActual?: (jobId: string, day: string) => number | null;
+}
+
+export interface GuardianComparison {
+  day: string;
+  timeZone: string;
+  jobs: Array<{ job: string; would: number; actual: number; alertsActual: number | null }>;
+  diff: Array<{ job: string; would: number; actual: number; alertsActual: number | null }>;
+  same: boolean;
+  /** Jobs whose measured alert count differs from would. Empty when alerts are unmeasured. */
+  alertDiff: Array<{ job: string; would: number; actual: number; alertsActual: number | null }>;
+}
+
+/** Count the 5-minute shadow ticks for a calendar day in the scheduler's time zone — using the CURRENT plan
+ * (today's cron/enabled), so a past day is judged against the present schedule, not the one in force that day —
+ * then compare actual fire history by stable id and instant (never by job name). */
+export function guardianShadowDay(day: string, deps?: GuardianDayDeps): GuardianComparison {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !Number.isFinite(Date.parse(`${day}T00:00:00Z`))
+    || new Date(`${day}T00:00:00Z`).toISOString().slice(0, 10) !== day) {
+    throw new RangeError('day must be a valid YYYY-MM-DD');
+  }
+  if (!deps) {
+    const db = openSchedulesDb();
+    try { return guardianShadowDay(day, { db, plan: { jobs: listSchedules(db) } }); }
+    finally { db.close(); }
+  }
+  const timeZone = deps.plan.timeZone ?? resolveTimeZone().timeZone;
+  const jobs = matchedJobs(deps.plan);
+  const counts = new Map(jobs.map(job => [job.id, 0]));
+  const date = Date.parse(`${day}T00:00:00Z`);
+  // Bracket every possible IANA civil-day offset, including daylight-saving transitions.
+  for (let ms = date - 14 * 3600_000; ms < date + 38 * 3600_000; ms += 5 * 60_000) {
+    const at = new Date(ms);
+    const fields = calendarFields(at, { timeZone });
+    if (`${fields.year}-${String(fields.month).padStart(2, '0')}-${String(fields.day).padStart(2, '0')}` !== day) continue;
+    for (const job of jobs) {
+      if (cronMatches(job.cron!, at, { timeZone })) counts.set(job.id, counts.get(job.id)! + 1);
+    }
+  }
+  const rows = jobs.map(job => {
+    // schedule_runs retains only the latest 500 fires per id: older days can be incomplete.
+    const runs = listScheduleRuns(deps.db, job.id, { limit: 500 });
+    const actual = runs.filter(run => {
+      const fields = calendarFields(new Date(run.fired_at), { timeZone });
+      return `${fields.year}-${String(fields.month).padStart(2, '0')}-${String(fields.day).padStart(2, '0')}` === day;
+    }).length;
+    if (runs.length === 500 && runs.length > 0) {
+      const oldest = calendarFields(new Date(runs[runs.length - 1]!.fired_at), { timeZone });
+      const oldestDay = `${oldest.year}-${String(oldest.month).padStart(2, '0')}-${String(oldest.day).padStart(2, '0')}`;
+      if (oldestDay >= day) throw new Error(`guardian comparison incomplete: schedule_runs history truncated for ${job.id} on ${day}`);
+    }
+    const alertsActual = deps.alertsActual?.(job.id, day) ?? null;
+    if (alertsActual !== null && (!Number.isSafeInteger(alertsActual) || alertsActual < 0)) {
+      throw new RangeError('alertsActual must be a non-negative integer or null');
+    }
+    return { job: job.id, would: counts.get(job.id)!, actual, alertsActual };
+  });
+  // `same` judges scheduled vs recorded fires only. Alert counts are a separate axis: unmeasured (null) by default,
+  // and a measured mismatch is reported in alertDiff without changing the fire verdict.
+  const diff = rows.filter(row => row.would !== row.actual);
+  const same = diff.length === 0;
+  const alertDiff = rows.filter(row => row.alertsActual !== null && row.would !== row.alertsActual);
+  debug.log('guardian.compare', 'day', { same, diff, alertDiff });
+  return { day, timeZone, jobs: rows, diff, same, alertDiff };
+}

package/src/domains/outbound-alert.ts

@@ -5,8 +5,8 @@
 // send.py 와 동일 동작을 TS 로 포팅(완전 elanous 소유). sync(curl) 계약.
 
 import * as childProcess from 'node:child_process';
-import { existsSync, readFileSync, appendFileSync, mkdirSync, unlinkSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { existsSync, readFileSync, appendFileSync, mkdirSync, unlinkSync, readdirSync, renameSync, openSync, closeSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { conatusEnv } from './conatus-env.js';
@@ -15,7 +15,7 @@ import { openSurfaceEventsDb, recordEvent } from './surface-events.js';
 import { latestUserIntentTs } from '../user-intent/index.js';
 import { getUserConfig, type UserConfig } from '../user-config.js';
 import { resolveChannelBotToken } from '../channel-bot-token.js';
-import { isOperationalKind, kindRouteTarget, logKindRouteFallback, mainHomeTarget } from './telegram-kind-route.js';
+import { explainReportRoute, isOperationalKind, kindRouteTarget, logKindRouteFallback, mainHomeTarget } from './telegram-kind-route.js';
 import { debug } from '../debug/log.js';
 import { registerLogStoreSink, setLogInstanceName } from '../mss/logging/log-store.js';
 import type { LogSink } from '../mss/logging/sink.js';
@@ -24,7 +24,8 @@ import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js'
 // ★ origin 되돌림(대표 2026-07-12) — 미션 알림을 발신 채널(메인 Q&A 봇)로 되돌린다. type-only
 //   import 라 런타임 순환 없음(발송 로직은 이 파일에 self-contained). origin 없으면 report 폴백.
 import type { MissionOrigin } from '../autopilot/mission-origin.js';
-import { conatusPath } from './conatus-data-dir.js';
+import { conatusDataDir, conatusPath } from './conatus-data-dir.js';
+import { assertNoRealSendFromTest, assertNotTestWritingOps, isTestDouble } from '../instance/test-write-guard.js';
 
 /** Explicit `ELANOUS_NEXUS_URL` wins. Otherwise ask the daemon endpoint resolver.
  *  A missing daemon is not a guessed port — the caller falls through to direct send. */
@@ -37,6 +38,8 @@ function nexusUrl(): string | null {
 // /v1/outbound 로 POST — getElanousConfigDir() 치환은 prod 동치(~/.elanous) + --config-dir 정합.
 const ACP_TOKEN_PATH = join(getElanousConfigDir(), 'acp-token');
 const DEFERRED_PATH = conatusPath('outbound_deferred.jsonl');
+// The real transport, captured before any test can spy on it — a pass-through spy is not a fake.
+const REAL_EXEC_FILE_SYNC = childProcess.execFileSync;
 
 // CLI/cron do not inherit the daemon's StoreSink. Register once before the first
 // send, but never attach a second sink to a daemon which already owns one.
@@ -138,11 +141,12 @@ export function userRecentlyActive(now: Date = new Date()): boolean {
 
 /** 야간 보류 적재 (jsonl append — 크론 동시 실행에 안전). origin 있으면 함께 적재 —
  *  아침 flush 가 그 origin(발신 채널)으로 되돌려 발송(없으면 report 묶음). */
-function deferOutbound(text: string, kind: string, origin?: MissionOrigin | null, path = DEFERRED_PATH): boolean {
+export function deferOutbound(text: string, kind: string, origin?: MissionOrigin | null, path = DEFERRED_PATH): boolean {
+  assertNotTestWritingOps(path, 'append the deferred-alert queue');
   try {
     mkdirSync(dirname(path), { recursive: true });
     const rec = { ts: new Date().toISOString(), kind, text, ...(origin ? { origin } : {}) };
-    appendFileSync(path, JSON.stringify(rec) + '\n');
+    withQueueLock(path, () => appendFileSync(path, JSON.stringify(rec) + '\n'));
     console.error(`[outbound] 야간 무음(00:00~06:30 KST) — 보류 적재 (${kind})`);
     return true;
   } catch (e) {
@@ -171,9 +175,12 @@ function resolveBotToken(botId?: string): string | null {
 function deliverToOrigin(origin: MissionOrigin, text: string, onBot?: (bot: string) => void): boolean {
   if (origin.channel === 'discord') {
     if (!origin.channelId) return false;
+    let token: string | undefined;
+    try { token = resolveChannelBotToken('discord', getUserConfig())?.token; } catch { return false; }
+    if (!token) return false;
+    // Outside the swallowing try below: a refused test send must surface, not read as «delivery failed».
+    assertTestSendFaked('send a real Discord message');
     try {
-      const token = resolveChannelBotToken('discord', getUserConfig())?.token;
-      if (!token) return false;
       onBot?.('discord:configured');
       const channelId = origin.discordThreadId || origin.channelId;
       const out = spillLongContent(text).text;
@@ -184,6 +191,7 @@ function deliverToOrigin(origin: MissionOrigin, text: string, onBot?: (bot: stri
           `https://discord.com/api/v10/channels/${channelId}/messages`,
           JSON.stringify({ content: out.slice(start, end) }),
           [`Authorization: Bot ${token}`, 'Content-Type: application/json'],
+          'send a real Discord message',
         );
         if (typeof response?.id !== 'string' || !response.id) return false;
         start = end;
@@ -195,35 +203,200 @@ function deliverToOrigin(origin: MissionOrigin, text: string, onBot?: (bot: stri
   const token = resolveBotToken(origin.botId);
   if (!token) return false;
   onBot?.(botLabel(token));
+  assertTestSendFaked('send a real Telegram message to the origin');
   try { return sendTelegramRaw(token, origin.chatId, text, origin.threadId); } catch { return false; }
 }
 
-/** 보류분 일괄 발송 — 묶음 1건(아침 폭주 방지). 발송 건수 반환.
- *  무음 창 밖 첫 sendOutbound 가 자동 호출 + 06:31 플러시 크론이 보장. */
-export function flushDeferred(path = DEFERRED_PATH): number {
+/** 보류 큐 재시도 상한 env — config `outbound.deferredMaxAttempts` 가 없을 때만 읽는다. */
+export const DEFERRED_MAX_ATTEMPTS_ENV = 'ELANOUS_OUTBOUND_DEFERRED_MAX_ATTEMPTS';
+
+/** 보류 항목이 격리되기 전까지 허용하는 실패 flush 수 — config > env > 5. */
+export function deferredMaxAttempts(config?: Pick<UserConfig, 'outbound'>): number {
+  try {
+    const v = (config ?? getUserConfig()).outbound?.deferredMaxAttempts;
+    if (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) return v;
+  } catch { /* unreadable config: env, then default */ }
+  const raw = Number(process.env[DEFERRED_MAX_ATTEMPTS_ENV]?.trim() || NaN);
+  if (Number.isSafeInteger(raw) && raw > 0) return raw;
+  return 5;
+}
+
+/** 격리 파일 — 보류 큐 옆 `<name>.failed.jsonl`. */
+export function deferredQuarantinePath(path: string): string {
+  return path.endsWith('.jsonl') ? `${path.slice(0, -'.jsonl'.length)}.failed.jsonl` : `${path}.failed`;
+}
+
+function pidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+/** 큐 적재·claim 이 서로를 가로지르지 않게 하는 짧은 배타 잠금(`<queue>.lock`, O_EXCL).
+ *  적재는 open→write→close 를 잠금 안에서 하므로 claim 의 rename 이 «열린 채 쓰기 전»인 적재를 가져가지 않는다.
+ *  잠금을 못 얻으면(2초 · 30초 넘은 잔여 잠금은 걷는다) 그대로 진행한다 — 알림을 잃는 것보다 낫다. */
+function withQueueLock<T>(path: string, fn: () => T): T {
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + 2_000;
+  let fd: number | null = null;
+  while (fd === null && Date.now() <= deadline) {
+    try { fd = openSync(lock, 'wx'); break; } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') { try { mkdirSync(dirname(path), { recursive: true }); } catch { break; } continue; }
+      if (code !== 'EEXIST') break;
+      try { if (Date.now() - statSync(lock).mtimeMs > 30_000) { unlinkSync(lock); continue; } } catch { continue; }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  if (fd === null) { try { debug.log('outbound.send', 'deferred-lock-unavailable', { lock: basename(lock) }); } catch { /* */ } }
+  try { return fn(); } finally {
+    if (fd !== null) { try { closeSync(fd); } catch { /* */ } try { unlinkSync(lock); } catch { /* */ } }
+  }
+}
+
+/** 이보다 오래된 claim 은 소유 pid 가 살아 있어도 회수한다(pid 재사용 대비 · 정상 flush 는 이보다 훨씬 짧다). */
+const STALE_CLAIM_MS = 15 * 60_000;
+
+let claimSeq = 0;
+/** 큐를 «가져간다» — 원자적 rename 으로 이 flush 만의 파일로 옮긴다. flush 도중 적재되는 항목은 새 큐 파일에
+ *  쌓이므로 잃지 않는다. 죽은 flusher(또는 이 프로세스의 앞 호출)가 남긴 claim 도 같이 회수한다. */
+function claimDeferred(path: string): string[] {
+  const claims: string[] = [];
+  const next = (): string => `${path}.flushing-${process.pid}-${Date.now()}-${claimSeq++}`;
+  const dir = dirname(path);
+  const prefix = `${basename(path)}.flushing-`;
+  try {
+    for (const name of readdirSync(dir)) {
+      if (!name.startsWith(prefix)) continue;
+      const m = /^(\d+)-(\d+)-/.exec(name.slice(prefix.length));
+      const pid = Number(m?.[1]);
+      const at = Number(m?.[2]);
+      if (!Number.isSafeInteger(pid)) continue;
+      // flushDeferred 는 동기라 같은 pid 의 claim 은 «지난 호출의 잔여»다. 남의 것은 죽었거나 오래됐을 때만.
+      const stale = Number.isFinite(at) && Date.now() - at > STALE_CLAIM_MS;
+      if (pid !== process.pid && !stale && pidAlive(pid)) continue;
+      const own = next();
+      try { renameSync(join(dir, name), own); claims.push(own); } catch { /* another flusher took it */ }
+    }
+  } catch { /* no directory yet */ }
+  withQueueLock(path, () => {
+    if (!existsSync(path)) return;
+    const own = next();
+    try { renameSync(path, own); claims.push(own); } catch { /* another flusher took it */ }
+  });
+  return claims;
+}
+
+/** flushDeferred 주입점 — 시험은 실제 발송 대신 sendBatch 를 준다. */
+export type FlushDeferredDeps = {
+  sendBatch?: (text: string, kind: string, origin?: MissionOrigin) => boolean;
+  maxAttempts?: number;
+};
+
+/** 보류분 일괄 발송 — 묶음 단위. 배달 건수 반환.
+ *  무음 창 밖 첫 sendOutbound 가 자동 호출 + 06:31 플러시 크론이 보장.
+ *  ⭐ 실패한 묶음의 항목만 큐에 남긴다(성공 묶음은 다시 보내지 않는다 · 10-07 야간 11회 재발송 사고).
+ *  실패가 `maxAttempts` 번 쌓인 항목은 `<name>.failed.jsonl` 로 격리한다. */
+export function flushDeferred(path = DEFERRED_PATH, deps: FlushDeferredDeps = {}): number {
+  assertNotTestWritingOps(path, 'flush the deferred-alert queue');
   ensureOutboundLogSink();
-  const observeFlush = (count: number, lagMin: number, kinds: string[]): void => {
+  const observeFlush = (
+    count: number, lagMin: number, kinds: string[],
+    outcome: { sent: number; kept: number; quarantined: number },
+  ): void => {
     const lagWarnMin = flushLagWarnMin();
     const over = count > 0 && lagMin > lagWarnMin;
     logSend(
       'flush',
       'deferred-batch',
-      { count, lagMin, kinds: kinds.map(safeObservationLabel), path, lagWarnMin },
+      { count, lagMin, kinds: kinds.map(safeObservationLabel), path, lagWarnMin, ...outcome },
       over ? { level: 'warn' } : undefined,
     );
   };
-  if (!existsSync(path)) {
-    observeFlush(0, 0, []);
+  const none = { sent: 0, kept: 0, quarantined: 0 };
+  const claims = claimDeferred(path);
+  if (claims.length === 0) {
+    observeFlush(0, 0, [], none);
     return 0;
   }
-  type Item = { ts: string; kind: string; text: string; origin?: MissionOrigin };
-  let items: Item[] = [];
-  try {
-    items = readFileSync(path, 'utf-8').split('\n').filter(Boolean).map(l => JSON.parse(l));
-  } catch { /* 손상 라인 무시 */ }
+  type Item = { ts: string; kind: string; text: string; origin?: MissionOrigin; attempts?: number };
+  const items: Item[] = [];
+  const corrupt: string[] = [];
+  const readClaims: string[] = [];
+  for (const claim of claims) {
+    let body = '';
+    try { body = readFileSync(claim, 'utf-8'); } catch (e) {
+      // 못 읽은 claim 은 지우지 않는다 — 다음 flush 가 다시 회수한다.
+      try { debug.log('outbound.send', 'deferred-claim-unreadable', { error: e instanceof Error ? e.message : String(e) }, { level: 'warn' }); } catch { /* */ }
+      continue;
+    }
+    readClaims.push(claim);
+    for (const line of body.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const rec = JSON.parse(line) as Item;
+        if (rec && typeof rec === 'object' && typeof rec.text === 'string') items.push(rec);
+        else corrupt.push(line);
+      } catch { corrupt.push(line); }
+    }
+  }
+  const qPath = deferredQuarantinePath(path);
+  const settleFailed = (stage: string, e: unknown): void => {
+    try { debug.log('outbound.send', 'deferred-settle-failed', { stage, error: e instanceof Error ? e.message : String(e) }, { level: 'warn' }); } catch { /* */ }
+  };
+  /** 읽은 claim 을 정산한다. 격리 기록이 실패하면 그 줄은 큐로 돌린다(다음에 다시 격리).
+   *  큐 기록이 실패하면 claim 하나를 «남길 줄만»으로 바꿔 두어 다음 flush 가 배달분을 다시 보내지 않게 한다. */
+  /** 정산된 claim 을 걷는다. 삭제가 실패하면 비워 둔다 — 남은 claim 이 다음 flush 에 배달분을 다시 내지 않게. */
+  const retireClaim = (claim: string): void => {
+    try { unlinkSync(claim); return; } catch (e) { settleFailed('claim-unlink', e); }
+    try { writeFileSync(claim, ''); } catch (e) { settleFailed('claim-truncate', e); }
+  };
+  type Quarantine = { line: string; kind?: string; attempts?: number };
+  /** 반환 = 실제 정산 결과(관측은 이것으로 센다). */
+  const settle = (keep: string[], quarantine: Quarantine[]): { kept: number; quarantined: number } => {
+    let back = keep;
+    let quarantined = 0;
+    if (quarantine.length) {
+      try {
+        appendFileSync(qPath, quarantine.map(q => q.line).join('\n') + '\n');
+        quarantined = quarantine.length;
+        for (const q of quarantine) {
+          if (q.kind === undefined) continue;
+          try { debug.log('outbound.send', 'deferred-quarantined', { kind: safeObservationLabel(q.kind), attempts: q.attempts }); } catch { /* */ }
+        }
+      } catch (e) { settleFailed('quarantine', e); back = [...keep, ...quarantine.map(q => q.line)]; }
+    }
+    const result = { kept: back.length, quarantined };
+    if (readClaims.length === 0) return result;
+    let wrote = back.length === 0;
+    if (!wrote) {
+      try { withQueueLock(path, () => appendFileSync(path, back.join('\n') + '\n')); wrote = true; } catch (e) { settleFailed('queue', e); }
+    }
+    if (!wrote) {
+      const first = readClaims[0]!;
+      const tmp = join(dirname(first), `.${basename(first)}.tmp`);
+      try {
+        writeFileSync(tmp, back.join('\n') + '\n');
+        renameSync(tmp, first);
+        for (const claim of readClaims.slice(1)) retireClaim(claim);
+      } catch (e) { settleFailed('claim-rewrite', e); }
+      return result;
+    }
+    for (const claim of readClaims) retireClaim(claim);
+    return result;
+  };
+  const maxAttempts = deps.maxAttempts ?? deferredMaxAttempts();
+  const priorAttempts = (it: Item): number =>
+    typeof it.attempts === 'number' && Number.isSafeInteger(it.attempts) && it.attempts > 0 ? it.attempts : 0;
+  const quarantine: Quarantine[] = corrupt.map(line => ({ line }));
+  // 이미 상한에 닿은 줄(앞 flush 의 격리 기록이 실패해 큐로 돌아온 것)은 보내지 않고 다시 격리만 시도한다.
+  for (let i = items.length - 1; i >= 0; i--) {
+    const it = items[i]!;
+    if (priorAttempts(it) < maxAttempts) continue;
+    quarantine.push({ line: JSON.stringify(it), kind: it.kind, attempts: priorAttempts(it) });
+    items.splice(i, 1);
+  }
   if (items.length === 0) {
-    try { unlinkSync(path); } catch { /* */ }
-    observeFlush(0, 0, []);
+    const settled = settle([], quarantine);
+    observeFlush(0, 0, [], { ...none, ...settled });
     return 0;
   }
   const kst = (iso: string) => {
@@ -236,8 +409,7 @@ export function flushDeferred(path = DEFERRED_PATH): number {
     `🌙 야간 보류 알림 ${list.length}건 (00:00~06:30 KST 무음 · ⏳ 최대 ${lagMin}분 지연 — 일괄 전달)`,
     ...list.map(i => `\n── [${kst(i.ts)} · ${i.kind}] ──\n${i.text}`),
   ].join('\n');
-  observeFlush(items.length, lagMin, [...new Set(items.map(i => i.kind))]);
-  const sendBatch = (text: string, kind: string, origin?: MissionOrigin): boolean => {
+  const sendBatch = deps.sendBatch ?? ((text: string, kind: string, origin?: MissionOrigin): boolean => {
     let bot = 'unknown';
     const path = origin
       ? (deliverToOrigin(origin, text, label => { bot = label; }) ? 'origin' : false)
@@ -250,15 +422,17 @@ export function flushDeferred(path = DEFERRED_PATH): number {
       });
     } catch { /* observation must not change delivery */ }
     return path !== false;
+  });
+  const failed: Item[] = [];
+  const send = (batch: Item[], kind: string, origin?: MissionOrigin): void => {
+    if (!sendBatch(fmt(batch), kind, origin)) failed.push(...batch);
   };
-  let delivered = 0;
   // origin 없는 매매 알림만 report 묶음. 그 외는 kind 별로 운영 봇 경계를 유지한다.
   const noOrigin = items.filter(i => !i.origin);
   const tradingBatch = noOrigin.filter(i => !isOperationalKind(i.kind));
-  if (tradingBatch.length && sendBatch(fmt(tradingBatch), 'report')) delivered += tradingBatch.length;
+  if (tradingBatch.length) send(tradingBatch, 'report');
   for (const kind of new Set(noOrigin.filter(i => isOperationalKind(i.kind)).map(i => i.kind))) {
-    const batch = noOrigin.filter(i => i.kind === kind);
-    if (sendBatch(fmt(batch), kind)) delivered += batch.length;
+    send(noOrigin.filter(i => i.kind === kind), kind);
   }
   // origin 있는 것 = 발신 채널·스레드별로 묶어 서로 다른 수신자에게 섞이지 않게 발송.
   const groups = new Map<string, { origin: MissionOrigin; list: Item[] }>();
@@ -272,15 +446,34 @@ export function flushDeferred(path = DEFERRED_PATH): number {
   }
   for (const g of groups.values()) {
     const kinds = new Set(g.list.map(i => i.kind));
-    if (sendBatch(fmt(g.list), kinds.size === 1 ? g.list[0]!.kind : 'mixed', g.origin)) delivered += g.list.length;
+    send(g.list, kinds.size === 1 ? g.list[0]!.kind : 'mixed', g.origin);
   }
-  // 전량 배달 성공 시에만 파일 제거(부분 실패는 다음 flush 재시도 — 성공분 중복은 드문 엣지 수용).
-  if (delivered >= items.length) { try { unlinkSync(path); } catch { /* */ } }
+  // 실패 묶음의 항목만 되돌린다(시도 수 +1). 상한에 닿은 항목은 격리 — 영원히 재시도하지 않는다.
+  const keep: string[] = [];
+  for (const it of failed) {
+    const attempts = priorAttempts(it) + 1;
+    const line = JSON.stringify({ ...it, attempts });
+    if (attempts >= maxAttempts) quarantine.push({ line, kind: it.kind, attempts });
+    else keep.push(line);
+  }
+  const settled = settle(keep, quarantine);
+  const delivered = items.length - failed.length;
+  observeFlush(items.length, lagMin, [...new Set(items.map(i => i.kind))], { sent: delivered, ...settled });
   return delivered;
 }
 
-/** 동기 curl(POST). body 는 stdin. 파싱 실패/에러 → null. */
-function curlPost(url: string, body: string, headers: string[]): any {
+/** TEST-PROD-LEAK — a test process may not reach a real bot or the ops daemon. `external` = a third-party bot API
+ *  (refused unless curl is a test double replacing the real one); the local daemon is refused only when ops-routed. */
+function assertTestSendFaked(what: string, external = true): void {
+  let roots: string[] = [];
+  try { roots = [getElanousConfigDir(), dirname(ACP_TOKEN_PATH), effectiveInstanceRoot(), conatusDataDir(), dirname(DEFERRED_PATH)]; }
+  catch { roots = [dirname(ACP_TOKEN_PATH), dirname(DEFERRED_PATH)]; }
+  assertNoRealSendFromTest(what, { transportFaked: isTestDouble(childProcess.execFileSync, REAL_EXEC_FILE_SYNC), routingRoots: roots, external });
+}
+
+/** 동기 curl(POST). body 는 stdin. 파싱 실패/에러 → null. `what` names the send for the test guard (never the URL — it carries the token). */
+function curlPost(url: string, body: string, headers: string[], what = 'send a real outbound message', external = true): any {
+  assertTestSendFaked(what, external);
   const args = ['-s', '-m', '25', '-X', 'POST'];
   for (const h of headers) args.push('-H', h);
   args.push('--data', '@-', url);
@@ -387,6 +580,7 @@ export function setInProcessOutbound(send: InProcessOutbound | null): void { inP
 export function deliver(text: string, kind = 'alert', onBot?: (bot: string) => void, source?: string): 'daemon' | 'direct' | false {
   // 0) inside the daemon — route in-process, asynchronously; the caller's synchronous answer is «accepted».
   if (inProcessOutbound && process.env.SEND_VIA_ELANOUS !== '0') {
+    assertTestSendFaked('route through the in-process daemon sender', false);
     onBot?.('daemon:configured');
     const send = inProcessOutbound;
     const fallback = (): void => {
@@ -419,7 +613,9 @@ export function deliver(text: string, kind = 'alert', onBot?: (bot: string) => v
       ...(token ? [`Authorization: Bearer ${token}`] : [])];
     const nexus = nexusUrl();
     const j = nexus
-      ? curlPost(`${nexus}/v1/outbound`, JSON.stringify({ text, markdown: false, kind }), headers)
+      // An explicit ELANOUS_NEXUS_URL can name any daemon, the ops one included: a test treats it like a real bot API.
+      ? curlPost(`${nexus}/v1/outbound`, JSON.stringify({ text, markdown: false, kind }), headers, 'post to the daemon /v1/outbound',
+        Boolean(process.env.ELANOUS_NEXUS_URL?.trim()))
       : null;
     const classification = classifyDaemonResponse(j);
     if (classification === 'ok') { onBot?.('daemon:configured'); return 'daemon'; }
@@ -429,27 +625,33 @@ export function deliver(text: string, kind = 'alert', onBot?: (bot: string) => v
     logDaemonPath(classification, kind, extra);
   }
   // 2) fallback: 텔레그램 sendMessage 직접(3900자 분할) — 데몬 미경유라 클라가 원장 기록.
-  if (sendTelegramDirect(text, kind, {}, onBot)) return 'direct';
-  reportUndeliverable(kind, daemonPath);
+  //    The same config judges the route and explains a failure (review r1).
+  let cfg: UserConfig | undefined;
+  try { cfg = getUserConfig(); } catch { /* sendTelegramDirect fails closed without config */ }
+  if (sendTelegramDirect(text, kind, cfg ? { config: cfg } : {}, onBot)) return 'direct';
+  reportUndeliverable(kind, daemonPath, cfg);
   return false;
 }
 
 /** OB8b — both paths failed: say so loudly, with the universe this process resolved, instead of a silent false.
  *  The usual cause (10-01 · MK): an ad-hoc `bun -e` or a script from a source tree resolves a cwd-derived test
  *  universe, so it finds neither the production daemon nor the production bot token. */
-function reportUndeliverable(kind: string, daemonPath: DaemonPathClass | 'not-found' | 'disabled'): void {
+function reportUndeliverable(kind: string, daemonPath: DaemonPathClass | 'not-found' | 'disabled', cfg?: UserConfig): void {
   let root = '?';
   let universe: 'prod' | 'test' | '?' = '?';
   try {
     root = effectiveInstanceRoot();
     universe = root === prodInstanceRoot() ? 'prod' : 'test';
   } catch { /* the report still goes out */ }
+  // Which routing rule closed the direct path — «토큰 없음 또는 전송 실패» hid a missing role for four days (BRIEF-DELIVERY-1007).
+  let route: ReturnType<typeof explainReportRoute> | null = null;
+  try { if (cfg) route = explainReportRoute(cfg, kind); } catch { /* the report still goes out */ }
   ensureOutboundLogSink();
-  try { debug.log('outbound.send', 'undeliverable', { kind: safeObservationLabel(kind), daemonPath, universe, root }); } catch { /* fail-soft */ }
+  try { debug.log('outbound.send', 'undeliverable', { kind: safeObservationLabel(kind), daemonPath, universe, root, route: route?.reason ?? 'unknown' }); } catch { /* fail-soft */ }
   const hint = universe === 'prod'
     ? '운영 데몬이 떠 있는지 확인: elanous nexus show'
     : '운영으로 보내려면 설치본 elanous 로 실행하거나 ELANOUS_STATE_DIR=~/.elanous 와 --config-dir ~/.elanous 를 준다';
-  try { console.error(`[outbound] ⛔ 못 보냄(${kind}) — 데몬 ${daemonPath} · 직접 발송도 실패(토큰 없음 또는 전송 실패) · 이 프로세스의 우주 ${universe} (${root}) · ${hint}`); } catch { /* fail-soft */ }
+  try { console.error(`[outbound] ⛔ 못 보냄(${kind}) — 데몬 ${daemonPath} · 직접 발송도 실패(${route && route.reason !== 'routed' ? `${route.reason}: ${route.hint}` : '토큰 없음 또는 전송 실패'}) · 이 프로세스의 우주 ${universe} (${root}) · ${hint}`); } catch { /* fail-soft */ }
 }
 
 /** 텔레그램 raw 발송(토큰·chatId 명시) — spill + 3900자 분할(줄 경계). thread 지원. */
@@ -468,7 +670,7 @@ function sendTelegramRaw(token: string, chatId: string | number, text: string, t
   for (const ch of chunks) {
     const params: Record<string, string> = { chat_id: String(chatId), text: ch, disable_web_page_preview: 'true' };
     if (threadId !== undefined) params.message_thread_id = String(threadId);
-    if (!curlPost(url, new URLSearchParams(params).toString(), ['Content-Type: application/x-www-form-urlencoded'])) ok = false;
+    if (!curlPost(url, new URLSearchParams(params).toString(), ['Content-Type: application/x-www-form-urlencoded'], 'send a real Telegram message')) ok = false;
   }
   return ok;
 }
@@ -480,6 +682,8 @@ export function sendTelegramDirect(
   onBot?: (bot: string) => void,
 ): boolean {
   const sendRaw = deps.sendRaw ?? sendTelegramRaw;
+  // An injected sender still may not run in a test that resolved the ops universe.
+  if (deps.sendRaw) assertTestSendFaked('send a Telegram message from the ops universe', false);
   let cfg: UserConfig | undefined;
   try { cfg = deps.config ?? getUserConfig(); } catch { /* unavailable config: operational delivery still fails closed */ }
   if (cfg) {

package/src/domains/outbound-log-probe.ts

@@ -1,8 +1,23 @@
-import { sendOutbound, setInProcessOutbound } from './outbound-alert.js';
+import { inQuietHours, kstMinutes, sendOutbound, setInProcessOutbound } from './outbound-alert.js';
 import { setUserConfigOverlay } from '../user-config.js';
 
 // Focused subprocess fixture: isolated state/config roots and a fake curl on PATH.
 setUserConfigOverlay(cfg => ({ ...cfg, telegram: { ...cfg.telegram, botToken: '123456:private-secret', homeChannel: 98765 } }));
 process.env.SEND_VIA_ELANOUS = '0';
+// Quiet hours (00:00~06:30 KST) defer instead of sending, so a gate run at night saw no `sent` row.
+// Shift this fixture's clock back to 23:59 KST of the previous day; the shift stays inside this process.
+const quietShiftMs = inQuietHours() ? (kstMinutes() + 1) * 60_000 : 0;
+if (quietShiftMs > 0) {
+  const RealDate = Date;
+  const shifted = () => RealDate.now() - quietShiftMs;
+  class ShiftedDate extends RealDate {
+    constructor(...args: unknown[]) {
+      if (args.length === 0) super(shifted());
+      else super(...(args as [string | number | Date]));
+    }
+    static override now(): number { return shifted(); }
+  }
+  globalThis.Date = ShiftedDate as DateConstructor;
+}
 setInProcessOutbound(null);
 if (!sendOutbound('SECRET-BODY-DO-NOT-LOG', 'ops-alert', { channel: 'cli', surface: process.env.OUTBOUND_PROBE_SOURCE ?? 'outbound-log-probe' })) process.exitCode = 1;

package/src/domains/release-tool.ts

@@ -2,7 +2,7 @@ import type { LLMToolSpec } from '../llm.js';
 import type { ToolRuntimeContext } from '../tool-runtime/types.js';
 import { debug } from '../debug/log.js';
 import { requestConfirmation, type ConfirmOpts, type ConfirmResult } from '../hitl/confirm.js';
-import { devVersion, listChecklist, summarizeChecklist, type Checklist } from '../release-loop/checklist.js';
+import { devVersion, checklistDevVersion, listChecklist, summarizeChecklist, type Checklist } from '../release-loop/checklist.js';
 import { add, move, validateVersion } from '../release-loop/feature-store.js';
 import { formatKst, getSchedule, setSchedule, type ReleaseSchedule } from '../release-loop/release-schedule.js';
 import { latestGraphRun, type GraphRunState } from '../graph-runner/runner.js';
@@ -64,7 +64,7 @@ function dDay(days: number): string {
 export function dispatchReleaseStatus(args: Record<string, unknown>, deps: ReleaseToolDeps = {}): { text: string; structured: Record<string, unknown> } {
   const requested = args.version;
   if (requested !== undefined && (typeof requested !== 'string' || !requested.trim())) throw new Error('판 이름이 필요합니다');
-  const version = requested ? null : (deps.devVersion?.() ?? devVersion());
+  const version = requested ? null : checklistDevVersion(deps.devVersion?.() ?? devVersion());
   const versions = requested ? [requested as string] : [version!, nextVersion(version!)];
   const now = deps.now ?? new Date();
   const run = (deps.latestRun ?? latestGraphRun)('release-loop');