elanous 0.2.5 → 0.2.7

package/src/nexus/api/seat-requests.ts

@@ -0,0 +1,254 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { submitIntakeWork } from '../../intake-plane/submit-intake-work.js';
+import { parseSeatAddress, resolveSeat } from '../../seat-address/seat-address.js';
+import trackData from '../../../scripts/coord-tracks.json';
+import { jsonResponse } from './json-response.js';
+
+export const SEAT_REQUESTS_PATH = '/v1/seat-requests';
+
+interface SeatRequestItem {
+  receiptId: string;
+  seat: string;
+  text: string;
+  queuedAt: string;
+  status: 'queued';
+}
+
+interface PendingRequest {
+  status: 'pending';
+  key: string;
+  seat: string;
+  text: string;
+  queuedAt: string;
+  ref: string;
+}
+
+interface RejectedRequest extends Omit<PendingRequest, 'status'> {
+  status: 'rejected';
+}
+
+type RecordEntry = (SeatRequestItem & { key: string }) | PendingRequest | RejectedRequest;
+
+export interface SeatRequestsDeps {
+  root?: () => string;
+  submit?: typeof submitIntakeWork;
+  now?: () => string;
+  append?: (path: string, entry: RecordEntry) => void;
+}
+
+const seats = trackData.tracks.filter((entry): entry is typeof entry & { title: string } => 'title' in entry)
+  .map(({ id, title }) => ({ id, title }));
+const inFlight = new Map<string, { payload: string; task: Promise<Response> }>();
+
+function unknownSeat(): Response {
+  debug.log('seat-address.pwa', 'rejected', { reason: 'unknown-seat' });
+  return jsonResponse({ error: 'unknown-seat', seats }, 400);
+}
+
+function file(root: string): string {
+  return join(root, 'seat-requests', 'requests.jsonl');
+}
+
+function append(path: string, entry: RecordEntry): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // Atomically replace the journal so a failed write cannot leave a truncated JSON line.
+  const previous = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${previous}${JSON.stringify(entry)}\n`);
+    const fd = openSync(temp, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(temp, path);
+  } catch (error) {
+    try { unlinkSync(temp); } catch { /* no temp file to remove */ }
+    throw error;
+  }
+}
+
+function records(path: string): Map<string, RecordEntry> {
+  let data: string;
+  try { data = readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !existsSync(path)) data = '';
+    else throw error;
+  }
+  const entries = new Map<string, RecordEntry>();
+  for (const line of data.split('\n')) {
+    if (!line) continue;
+    const entry = JSON.parse(line) as RecordEntry;
+    if (typeof entry.key !== 'string' || typeof entry.seat !== 'string' || typeof entry.text !== 'string'
+      || typeof entry.queuedAt !== 'string' || !['pending', 'queued', 'rejected'].includes(entry.status)
+      || (entry.status === 'queued' && typeof entry.receiptId !== 'string')
+      || (entry.status !== 'queued' && typeof entry.ref !== 'string')) {
+      throw new Error('invalid seat request journal');
+    }
+    entries.set(entry.key, entry);
+  }
+  const dir = join(dirname(path), 'outcomes');
+  let names: string[];
+  try { names = readdirSync(dir); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return entries;
+    throw error;
+  }
+  for (const name of names) {
+    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+    const item = JSON.parse(readFileSync(join(dir, name), 'utf8')) as RecordEntry;
+    if (item.key !== name.slice(0, -5) || (item.status !== 'queued' && item.status !== 'rejected')) {
+      throw new Error('invalid seat request outcome');
+    }
+    const current = entries.get(item.key);
+    if (current?.status === 'queued') continue;
+    if (current?.status === 'pending') {
+      if (item.status === 'rejected' && current.ref !== item.ref) continue;
+      if (item.status === 'queued' && current.queuedAt !== item.queuedAt) continue;
+    }
+    entries.set(item.key, item);
+  }
+  return entries;
+}
+
+function outcomeFile(path: string, key: string): string {
+  return join(dirname(path), 'outcomes', `${key}.json`);
+}
+
+function persistOutcome(path: string, entry: RecordEntry, write: typeof append): void {
+  try {
+    write(path, entry);
+    const sidecar = outcomeFile(path, entry.key);
+    if (existsSync(sidecar)) unlinkSync(sidecar);
+  } catch {
+    // The primary journal may be unavailable while the outcome is already committed
+    // to the intake queue. Keep a durable sidecar rather than a process-local receipt.
+    const target = outcomeFile(path, entry.key);
+    mkdirSync(dirname(target), { recursive: true });
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify(entry));
+      const fd = openSync(temp, 'r');
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(temp, target);
+    } catch (error) {
+      try { unlinkSync(temp); } catch { /* no temp file */ }
+      throw error;
+    }
+  }
+}
+
+function receipt(item: SeatRequestItem): Response {
+  return jsonResponse({ receiptId: item.receiptId, seat: item.seat, queuedAt: item.queuedAt }, 202);
+}
+
+function unavailable(): Response {
+  debug.log('seat-address.pwa', 'rejected', { reason: 'journal-unavailable' });
+  return jsonResponse({ error: 'enqueue-failed' }, 503);
+}
+
+export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps = {}): Promise<Response> {
+  const path = file((deps.root ?? effectiveInstanceRoot)());
+  if (req.method === 'GET') {
+    const params = new URL(req.url).searchParams;
+    const requestedSeat = params.get('seat');
+    const seat = requestedSeat ? resolveSeat(requestedSeat) : undefined;
+    if (requestedSeat && !seat) return unknownSeat();
+    const rawLimit = params.get('limit');
+    const limit = rawLimit === null ? 20 : Number(rawLimit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) return jsonResponse({ error: 'bad_request' }, 400);
+    try {
+      const items = [...records(path).values()].filter((entry): entry is RecordEntry & SeatRequestItem => entry.status === 'queued')
+        .reverse().filter((item) => !seat || item.seat === seat.id).slice(0, limit)
+        .map(({ receiptId, seat: id, text, queuedAt, status }) => ({ receiptId, seat: id, text, queuedAt, status }));
+      return jsonResponse({ items, seats });
+    } catch { return unavailable(); }
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'bad_request' }, 400);
+  const input = body as Record<string, unknown>;
+  if (typeof input.text !== 'string' || !input.text.trim()
+    || (input.seat !== undefined && typeof input.seat !== 'string')) {
+    debug.log('seat-address.pwa', 'rejected', { reason: 'invalid-body' });
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  // An implicit address must start the text; parseSeatAddress also accepts later lines.
+  const parsed = input.text.startsWith('@') ? parseSeatAddress(input.text) : null;
+  const prefix = parsed ? `@${parsed.seats.join(',')}` : '';
+  const firstAddress = parsed && input.text.startsWith(prefix)
+    && (input.text.length === prefix.length || /[ \t\r\n]/.test(input.text[prefix.length]!)) ? parsed : null;
+  const address = input.seat ?? (firstAddress?.seats.length === 1 ? firstAddress.seats[0] : undefined);
+  const seat = address ? resolveSeat(address) : undefined;
+  if (!seat) return unknownSeat();
+  const text = input.seat === undefined ? firstAddress!.body.trim() : input.text.trim();
+  if (!text) {
+    debug.log('seat-address.pwa', 'rejected', { reason: 'empty-text', seat: seat.id });
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  debug.log('seat-address.pwa', 'parsed', { seat: seat.id, textLength: text.length });
+  const now = (deps.now ?? (() => new Date().toISOString()))();
+  const header = req.headers.get('idempotency-key');
+  if (header !== null && (!header.trim() || header.length > 200)) return jsonResponse({ error: 'bad_request' }, 400);
+  const payload = `${seat.id}\0${text}`;
+  const key = header === null ? createHash('sha256').update(randomUUID()).digest('hex')
+    : createHash('sha256').update(`client\0${header}`).digest('hex');
+  const lock = `${path}\0${key}`;
+  const pending = inFlight.get(lock);
+  if (pending) {
+    if (pending.payload !== payload) return jsonResponse({ error: 'idempotency-conflict' }, 409);
+    return pending.task.then((response) => response.clone());
+  }
+  // Install the lock before starting disk or queue work; a second caller must
+  // wait for the first instead of independently submitting the same key.
+  let start!: () => void;
+  const gate = new Promise<void>((resolve) => { start = resolve; });
+  const task = (async (): Promise<Response> => {
+    await gate;
+    let existing: RecordEntry | undefined;
+    try { existing = records(path).get(key); }
+    catch { return unavailable(); }
+    if (existing) {
+      if (existing.seat !== seat.id || existing.text !== text) return jsonResponse({ error: 'idempotency-conflict' }, 409);
+      if (existing.status === 'queued') return receipt(existing);
+    }
+    const intent: PendingRequest = existing?.status === 'pending'
+      ? existing : { key, seat: seat.id, text, queuedAt: now, status: 'pending', ref: `pwa:${randomUUID()}` };
+    if (existing?.status !== 'pending') {
+      try {
+        (deps.append ?? append)(path, intent);
+        if (existing?.status === 'rejected') {
+          const sidecar = outcomeFile(path, key);
+          if (existsSync(sidecar)) unlinkSync(sidecar);
+        }
+      } catch { return unavailable(); }
+    }
+    let result: Awaited<ReturnType<typeof submitIntakeWork>>;
+    try {
+      result = await (deps.submit ?? submitIntakeWork)({
+        text: `@${seat.title ?? seat.id} ${text}`,
+        track: 'graph',
+        origin: { kind: 'external', ledgerSource: 'pwa', provider: 'other', ref: intent.ref, reportTo: { channel: 'pwa' } },
+      });
+    } catch { return unavailable(); }
+    if (!result.ok || result.track !== 'graph') {
+      debug.log('seat-address.pwa', 'rejected', { reason: result.ok ? 'unexpected-track' : result.reason, seat: seat.id });
+      try { persistOutcome(path, { ...intent, status: 'rejected' }, deps.append ?? append); }
+      catch { return unavailable(); }
+      return unavailable();
+    }
+    const item: RecordEntry & SeatRequestItem = { key, receiptId: result.acceptanceId, seat: seat.id, text, queuedAt: intent.queuedAt, status: 'queued' };
+    try { persistOutcome(path, item, deps.append ?? append); }
+    catch { return unavailable(); }
+    debug.log('seat-address.pwa', 'enqueued', { seat: seat.id, receiptId: item.receiptId });
+    return receipt(item);
+  })();
+  inFlight.set(lock, { payload, task });
+  start();
+  try { return await task; }
+  finally { inFlight.delete(lock); }
+}

package/src/nexus/api/trace-run-scan.ts

@@ -0,0 +1,37 @@
+import { statSync } from 'node:fs';
+import type { LogInstanceView } from '../../mss/logging/instance-registry.js';
+import type { LogStore } from '../../mss/logging/log-store.js';
+
+/** Bounded, read-only fallback when a run's ledger is not on this host. */
+export function scanStoresForRun(
+  runId: string,
+  views: readonly LogInstanceView[],
+  open: (view: LogInstanceView) => Pick<LogStore, 'queryTraceRun' | 'close'> | null,
+  opts: { sinceMs?: number; untilMs?: number; maxStores?: number; deadlineMs?: number; now?: () => number } = {},
+): { universe?: string; checked: number; truncated: boolean; unresolved?: boolean } {
+  const now = opts.now ?? Date.now;
+  const deadline = now() + (opts.deadlineMs ?? 3000);
+  const maxStores = opts.maxStores ?? 200;
+  const mtime = (view: LogInstanceView): number => {
+    try { return statSync(view.dbPath).mtimeMs; } catch { return -Infinity; }
+  };
+  const candidates = views.map((view) => ({ view, at: view.dbExists ? mtime(view) : -Infinity }))
+    .sort((a, b) => (b.at === a.at ? a.view.name.localeCompare(b.view.name) : b.at - a.at));
+  let checked = 0;
+  let unresolved = false;
+  for (const { view } of candidates) {
+    if (checked >= maxStores || now() >= deadline) return { checked, truncated: true };
+    checked++;
+    let store: ReturnType<typeof open> = null;
+    try {
+      if (!view.dbExists) continue;
+      store = open(view);
+      if (!store) { unresolved = true; continue; }
+      if (store.queryTraceRun(runId, { sinceMs: opts.sinceMs, untilMs: opts.untilMs, limit: 1 }).length) {
+        return { universe: view.name, checked, truncated: false };
+      }
+    } catch { unresolved = true; }
+    finally { try { store?.close(); } catch { /* read-only handle cleanup is best effort */ } }
+  }
+  return { checked, truncated: false, ...(unresolved ? { unresolved } : {}) };
+}

package/src/nexus/api/trace.ts

@@ -8,6 +8,7 @@ import { activeStoreNames, parseSinceParam, type LogFabricDeps, registeredLogSto
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './json-response.js';
 import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
+import { scanStoresForRun } from './trace-run-scan.js';
 
 export type TraceLevel = 'L0' | 'L1' | 'L2' | 'L3';
 export interface TraceEvent {
@@ -346,7 +347,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     }
     if (!opened) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: failures }, 503);
     const runId = url.searchParams.get('runId');
-    let resolution: { universe?: string; checked: number } | undefined;
+    let resolution: { universe?: string; checked: number; truncated?: boolean; unresolved?: boolean } | undefined;
+    let resolvedFrom: 'ledger' | 'log-scan' | undefined;
     if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url)) && !requestedUniverse) {
       // A store with no log db at all («has no log store yet» — e.g. the daemon's own tree-derived universe) cannot
       // hold the run, so it must not block the ledger lookup. A store that exists but failed to open/read still does:
@@ -356,6 +358,20 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       try { resolution = findRunUniverse(runId, names, deps); }
       catch (error) { return jsonResponse({ ok: false, error: 'run-universe-unavailable', reason: error instanceof Error ? error.message : String(error) }, 503); }
       try { debug.log('nexus.trace', 'run-universe-resolved', { runId, universe: resolution.universe ?? 'not-found', checked: resolution.checked }); } catch { /* observation must not block reads */ }
+      if (resolution.universe) resolvedFrom = 'ledger';
+      else {
+        let views: LogInstanceView[];
+        try { views = (deps.instances ?? readLogInstances)(); }
+        catch (error) { return jsonResponse({ ok: false, error: 'run-universe-unavailable', reason: error instanceof Error ? error.message : String(error) }, 503); }
+        resolution = scanStoresForRun(runId, views, (view) => {
+          const store = (deps.openRemoteStore ?? ((v: LogInstanceView) => LogStore.openReadOnly(v.dbPath)))(view);
+          if (!store) return null;
+          return { queryTraceRun: (id, query) => store.queryTraceRun(id, query),
+            close: () => (deps.closeRemoteStore ?? ((s: LogStore) => s.close()))(store) };
+        }, { sinceMs: parsed.from, untilMs: parsed.to });
+        if (resolution.universe) resolvedFrom = 'log-scan';
+        try { debug.log('nexus.trace', 'run-universe-scanned', { runId, universe: resolution.universe ?? (resolution.truncated || resolution.unresolved ? 'unresolved' : 'not-found'), checked: resolution.checked, truncated: resolution.truncated }); } catch { /* observation must not block reads */ }
+      }
       if (resolution.universe && !names.includes(resolution.universe)) {
         const name = resolution.universe;
         names.push(name);
@@ -373,9 +389,9 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       }
     }
     const filtered = rows.filter((row) => matches(row, url)).sort(sortRows);
-    const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0);
+    const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0 || resolution?.truncated === true);
     try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'rows', runs: trace.nodes.filter((node) => node.level === 'L1' && node.count > 0).length }); } catch { /* query logging must not block reads */ }
-    return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom: 'ledger' as const, runUniverse: resolution.universe } : { runUniverse: 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);
+    return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom, runUniverse: resolution.universe, ...(resolvedFrom === 'log-scan' ? { checked: resolution.checked } : {}) } : { runUniverse: resolution.truncated || resolution.unresolved ? 'unresolved' as const : 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);
   } finally { closeStores(stores, deps); }
 }
 

package/src/nexus/index.ts

@@ -2626,9 +2626,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
               getBot: () => getBotRef.current,
               allowedUsers: [...cfg.discord.allowedUsers],
             });
+            const chatChannels = cfg.discord.chatChannels ?? [];
+            debug.log('nexus.discord', 'chat-channels', { count: chatChannels.length });
             const handle = createNexusDiscordTriggerBot({
               token: discordToken,
               allowedUsers: [...cfg.discord.allowedUsers],
+              ...(chatChannels.length ? { guildTextChannels: chatChannels } : {}),
               dispatch: (event) => workflowDaemon!.dispatchDiscord(event),
               onMessage: composedOnMessage,
               onInteraction: async (raw) => {

package/src/nexus/setup-status.ts

@@ -13,6 +13,7 @@ import type { UserConfig as NexusUserConfig } from './config/types.js';
 import { resolveLaunchdEnvironment } from './install/launchd.js';
 import { resolveSystemdEnvironment } from './install/systemd.js';
 import { resolvePwaStaticDir } from './static-dir-resolve.js';
+import { SKILLS_STEP_COMMAND, unattendedSetupHint } from '../onboarding/entry-hints.js';
 
 export type SetupItemId = 'llm' | 'pwa-build' | 'channel-bot' | 'skill-dirs' | 'os-install';
 
@@ -97,8 +98,6 @@ export interface SetupCheckOpts {
   decideProviderForConfig?: typeof decideProviderForConfig;
 }
 
-const UNATTENDED_SETUP_HINT = 'unattended: `elanous setup --non-interactive --config <ans.json>`';
-
 function hasText(value: unknown): boolean {
   return typeof value === 'string' && value.trim().length > 0;
 }
@@ -146,7 +145,7 @@ function checkLlm(
     id: 'llm',
     label: 'LLM provider',
     passed,
-    hint: `run \`elanous setup llm\` or interactive \`elanous nexus\`; ${UNATTENDED_SETUP_HINT}`,
+    hint: `run \`elanous onboarding llm\` or interactive \`elanous nexus\`; ${unattendedSetupHint()}`,
     ...(detailProvider && detailProvider !== 'none' ? {
       detail: `provider=${detailProvider}${credential ? ` · credential=${credential}` : ''}`,
     } : {}),
@@ -173,7 +172,7 @@ function checkChannelBot(cfg: NexusUserConfig): SetupItem {
     id: 'channel-bot',
     label: 'Channel bot',
     passed: hasText(telegram) || hasText(discord),
-    hint: `run \`elanous nexus channel-bot setup telegram|discord\`; ${UNATTENDED_SETUP_HINT}`,
+    hint: `run \`elanous nexus channel-bot setup telegram|discord\`; ${unattendedSetupHint()}`,
   };
 }
 
@@ -187,7 +186,7 @@ function checkSkillDirs(cfg: MainUserConfig, exists: (path: string) => boolean):
     label: 'Skill dirs',
     passed: existingDirs.length > 0,
     hint: missingDirs.length > 0
-      ? `create the missing skill directories or choose an already-existing skill directory; ${UNATTENDED_SETUP_HINT}`
+      ? `create the missing skill directories or choose an already-existing skill directory; run \`${SKILLS_STEP_COMMAND}\`; ${unattendedSetupHint()}`
       : '',
     ...(dirs.length > 0 ? {
       detail: missingDirs.length > 0 ? `${detail} · missing: ${missingDirs.join(', ')}` : detail,

package/src/notify/llm-budget-alert.ts

@@ -0,0 +1,125 @@
+// NT1 — LLM 예산 알림 «모양» (UX · 대표 2026-09-30 22:30 재요청 · OP 결정 B6 ⊕ NT1).
+// 숫자·정책은 TC 의 B6 로더가 채운다(`내부 문서 `RFC-llm-policy-single-file-2026-09-30``) — 이 파일은 문구만 정한다.
+//
+// 규칙 셋(대표 가 받은 알림이 어긴 것들):
+//   ① 한 알림 = 한 결정·한 행동 — 맨 윗줄이 «무엇이 바뀌었나», 마지막 줄이 «할 일».
+//   ② 바뀐 게 없으면 침묵 — 같은 상태(key)면 send=false.
+//   ③ 모순 금지 — «한도 참»과 «크레딧으로 진행 중»을 한 알림에 같이 쓰지 않는다. 상태 하나만 고른다.
+//   ⊕ 내부 낱말 0 — «자»·«판정»·계정 내부 이름 나열을 쓰지 않는다(계정은 «계정 N개»로 센다).
+
+export interface LlmBudgetAccount {
+  name: string;
+  /** 구독 잔량 %(0~100). 모르면 undefined. */
+  subscriptionRemainingPct?: number;
+  /** 이 계정의 크레딧 잔액. */
+  credits?: number;
+  resetInHours?: number;
+}
+
+export interface LlmBudgetSnapshot {
+  /** ISO 시각(Asia/Seoul 로 날짜를 자른다). */
+  at: string;
+  credits: {
+    total: number;
+    usedToday: number;
+    /** 하루 목표 소진량(정책 `credits.pace`). */
+    paceTarget: number;
+    /** ISO 날짜 — 크레딧이 사라지는 날. */
+    expiresAt?: string;
+    /** 정책이 «크레딧 먼저»인가(`until` 전). */
+    useFirst?: boolean;
+  };
+  accounts: LlmBudgetAccount[];
+  selected: { account?: string; reason: 'subscription' | 'credits' | 'fallback' | 'none' };
+  fallback?: { provider: string; remainingPct?: number };
+}
+
+export interface LlmBudgetAlert {
+  send: boolean;
+  /** 상태 열쇠 — 다음 호출의 prevKey 로 넘긴다. */
+  key: string;
+  text: string;
+}
+
+const EXPIRY_WARN_DAYS = 7;
+/** 공개 알림에 표시할 수 있는 폴백 제공자명. 현재 폴백 체인의 외부 제공자는 grok 뿐이다. */
+const PUBLIC_FALLBACK_PROVIDERS = new Set(['grok']);
+/** 이 시각(서울) 뒤에야 «오늘 페이스가 느리다»를 말한다 — 아침에 0 인 건 정상이다. */
+const PACE_CHECK_HOUR = 18;
+
+const n = (v: number) => Math.round(v).toLocaleString('ko-KR');
+
+function seoulParts(iso: string): { date: string; hour: number } {
+  const d = new Date(iso);
+  const f = new Intl.DateTimeFormat('en-CA', { timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', hourCycle: 'h23' });
+  const p = Object.fromEntries(f.formatToParts(d).map((x) => [x.type, x.value]));
+  return { date: `${p.year}-${p.month}-${p.day}`, hour: Number(p.hour) };
+}
+
+function daysBetween(fromIso: string, toIso: string): number {
+  const a = Date.parse(seoulParts(fromIso).date);
+  const b = Date.parse(seoulParts(toIso).date);
+  return Math.round((b - a) / 86_400_000);
+}
+
+function mmdd(iso: string): string {
+  const { date } = seoulParts(iso);
+  return `${date.slice(5, 7)}-${date.slice(8, 10)}`;
+}
+
+function creditsLine(s: LlmBudgetSnapshot): string {
+  const parts = [`오늘 ${n(s.credits.usedToday)} / 목표 ${n(s.credits.paceTarget)}`, `남은 크레딧 ${n(s.credits.total)}`];
+  if (s.credits.expiresAt) parts.push(`${mmdd(s.credits.expiresAt)} 만료`);
+  return parts.join(' · ');
+}
+
+/** 지금 상태 하나를 고른다(위에서부터 먼저 맞는 것). 아무것도 아니면 침묵. */
+export function buildLlmBudgetAlert(now: LlmBudgetSnapshot, prevKey?: string): LlmBudgetAlert {
+  const { date, hour } = seoulParts(now.at);
+  const accounts = now.accounts.length;
+  let key = 'ok';
+  let lines: string[] = [];
+
+  const expiryDays = now.credits.expiresAt ? daysBetween(now.at, now.credits.expiresAt) : undefined;
+
+  if (now.selected.reason === 'none') {
+    key = 'blocked';
+    lines = [
+      '⛔ LLM 을 쓸 곳이 없어 작업이 멈췄습니다.',
+      `구독 계정 ${accounts}개 한도 · 크레딧·대체 모델도 못 씁니다.`,
+      '할 일: 크레딧 사용을 허락하거나 대체 모델 키를 확인해 주세요.',
+    ];
+  } else if (now.selected.reason === 'fallback') {
+    const soonest = now.accounts.map((a) => a.resetInHours)
+      .filter((h): h is number => typeof h === 'number' && Number.isFinite(h) && h > 0)
+      .sort((a, b) => a - b)[0];
+    const candidate = now.fallback?.provider?.trim();
+    const provider = candidate && PUBLIC_FALLBACK_PROVIDERS.has(candidate) ? candidate : undefined;
+    key = `fallback:${provider || 'unknown'}`;
+    lines = [
+      `⚠️ codex 를 못 써서 ${provider ? `${provider} 로` : '대체 모델로'} 일하고 있습니다${typeof now.fallback?.remainingPct === 'number' ? `(남은 ${Math.round(now.fallback.remainingPct)}%)` : ''}.`,
+      soonest !== undefined ? `codex 는 ${Math.ceil(soonest)}시간 뒤 돌아옵니다.` : 'codex 가 언제 돌아오는지 아직 모릅니다.',
+      '할 일: 없음 — 참고만 하세요.',
+    ];
+  } else if (expiryDays !== undefined && expiryDays >= 0 && expiryDays <= EXPIRY_WARN_DAYS && now.credits.total > 0) {
+    key = `expiry:${expiryDays}`;
+    lines = [
+      `💳 크레딧 ${n(now.credits.total)} 이 ${expiryDays === 0 ? '오늘' : `${expiryDays}일 뒤`} 사라집니다.`,
+      creditsLine(now),
+      '할 일: 만료 전에 크레딧 사용을 확인해 주세요.',
+    ];
+  } else if (now.credits.useFirst && now.credits.total > 0 && (expiryDays === undefined || expiryDays >= 0) && hour >= PACE_CHECK_HOUR && now.credits.usedToday < now.credits.paceTarget * 0.5) {
+    // 하루 한 번만 — 날짜를 열쇠에 넣는다.
+    key = `pace-behind:${date}`;
+    lines = [
+      now.selected.reason === 'credits'
+        ? '💳 크레딧을 먼저 쓰는 중인데 오늘 쓴 양이 목표의 절반이 안 됩니다.'
+        : '💳 크레딧을 먼저 쓰라는 방침인데 오늘은 구독 계정이 먼저 쓰였습니다.',
+      creditsLine(now),
+      now.selected.reason === 'credits' ? '할 일: 없음 — 맡긴 일이 적었던 날입니다.' : '할 일: 없음 — 기술 담당이 순서를 고치는 중입니다.',
+    ];
+  }
+
+  const send = key !== 'ok' && key !== prevKey;
+  return { send, key, text: send ? lines.join('\n') : '' };
+}

package/src/oauth/codex-account-rotation.ts

@@ -47,6 +47,8 @@ type RotationReason =
   | 'no-candidate'
   /** 찼고 구독 잔량이 남은 계정도 없지만 대표 가 크레딧 사용을 허가했다 — 지금 계정에 머물러 선불 크레딧으로 계속(grok 폴백 안 함). */
   | 'credits-allowed'
+  /** 오늘 크레딧 몫을 먼저 쓰기 위해 찬 계정으로 이동하거나 머문다. */
+  | 'credit-pace'
   /** 넘겼다. */
   | 'rotated';
 
@@ -101,6 +103,7 @@ interface RotationInput {
   /** 지금 계정의 크레딧 잔액·보유(모르면 없다). */
   readonly currentCreditBalance?: number;
   readonly currentHasCredits?: boolean;
+  readonly creditPace?: { active: boolean };
 }
 
 /**
@@ -182,6 +185,23 @@ export function decideCodexRotation(input: RotationInput): RotationDecision {
   });
   if (input.explicit) return { reason: 'explicit', candidateCount, accountThresholds };
   if (!input.enabled) return { reason: 'disabled', candidateCount, accountThresholds, ...(input.disabledProvenance ? { disabledProvenance: input.disabledProvenance } : {}) };
+  if (input.creditPace?.active) {
+    const self = input.candidates.find((candidate) => candidate.name === input.current.name);
+    const eligible = (name: string, balance: number | undefined, hasCredits: boolean | undefined, home: string | undefined): boolean =>
+      !!home?.trim() && typeof balance === 'number' && Number.isFinite(balance) && balance > 0
+      && hasCredits !== false && accountThresholds.some((row) => row.name === name
+        && (row.status === 'reached' || row.status === 'threshold-reached'));
+    const currentBalance = input.currentCreditBalance ?? self?.creditBalance;
+    const currentHas = input.currentHasCredits ?? self?.hasCredits;
+    const to = otherCandidates.filter((candidate) => eligible(candidate.name, candidate.creditBalance, candidate.hasCredits, candidate.home))
+      .sort((a, b) => (b.creditBalance! - a.creditBalance!) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))[0];
+    if (eligible(input.current.name, currentBalance, currentHas, self?.home ?? input.current.home)) {
+      return { reason: 'credit-pace', candidateCount, accountThresholds };
+    }
+    if (to) {
+      return { reason: 'credit-pace', candidateCount, accountThresholds, to };
+    }
+  }
   const currentUsageUnknown = input.currentReached === undefined && input.currentUsedPercent == null;
   if (input.currentReached !== true && !currentUsageUnknown && accountThresholds[0]?.status !== 'threshold-reached') {
     return { reason: 'not-reached', candidateCount, accountThresholds };
@@ -271,7 +291,7 @@ export function observeRotation(decision: RotationDecision, from: string): void
     ...(decision.reason === 'disabled' && decision.disabledProvenance
       ? { disabledProvenance: decision.disabledProvenance }
       : {}),
-  }, { level: decision.reason === 'rotated' || decision.reason === 'reset-credit-unknown' ? 'warn' : 'debug' });
+  }, { level: decision.reason === 'rotated' || decision.reason === 'reset-credit-unknown' || (decision.reason === 'credit-pace' && decision.to) ? 'warn' : 'debug' });
   for (const account of decision.accountThresholds ?? []) {
     debug.log('oauth.codex-account', 'rotation-account-threshold', account);
   }
@@ -279,7 +299,8 @@ export function observeRotation(decision: RotationDecision, from: string): void
   if (decision.reason !== 'explicit' && decision.reason !== 'disabled') {
     const fromRow = decision.accountThresholds?.find((a) => a.name === from);
     const toCredit = decision.to?.creditBalance;
-    const why = typeof toCredit === 'number'
+    const why = decision.reason === 'credit-pace' ? '오늘 크레딧 몫을 먼저 쓴다'
+      : typeof toCredit === 'number'
       // 금액은 문장에 넣지 않는다 — 판단 사유는 Live·Trace 카드에 글자로 뜨고 공개 캡처가 문장 속 숫자를 못 가린다(09-28 🅣).
       ? `구독 한도 전부 참 · ${decision.to!.name} 크레딧이 가장 많다`
       : fromRow ? `${from} ${fromRow.usedPercent ?? '?'}% · 임계 ${fromRow.thresholdPercent}%` : `판정 ${decision.reason}`;
@@ -287,7 +308,8 @@ export function observeRotation(decision: RotationDecision, from: string): void
       kind: 'ROUTE',
       what: decision.to ? `codex 계정 ${from} → ${decision.to.name}` : `codex 계정 ${from} 유지 (${decision.reason})`,
       reason: why,
-      purpose: decision.reason === 'credits-allowed' ? '한도가 찼다 — 정책상 크레딧으로 계속'
+      purpose: decision.reason === 'credit-pace' ? '하루 크레딧 몫을 채운 뒤 구독 순서로 복귀'
+        : decision.reason === 'credits-allowed' ? '한도가 찼다 — 정책상 크레딧으로 계속'
         : typeof toCredit === 'number' ? '크레딧을 세 계정에 고르게 · 한 계정이 먼저 마르지 않게' : '구독 한도 보존 · 끊김 없이 계속',
       target: decision.to?.name ?? from,
       refs: { account: decision.to?.name ?? from },
@@ -301,7 +323,7 @@ export function applyRotation(
   current: CodexAccountResolution,
   decision: RotationDecision,
 ): CodexAccountResolution {
-  if ((decision.reason !== 'rotated' && decision.reason !== 'reset-credit-unknown') || !decision.to) return current;
+  if ((decision.reason !== 'rotated' && decision.reason !== 'reset-credit-unknown' && decision.reason !== 'credit-pace') || !decision.to) return current;
   return {
     name: decision.to.name,
     storeKey: decision.to.storeKey,