elanous 0.2.14 → 0.2.16

package/src/nexus/api/loop-edges.ts

@@ -0,0 +1,173 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { listCoordEvents } from '../../context-bus/coord-events.js';
+import { CardStore, cardIndexPath, type TaskCard } from '../../task-cards/card-store.js';
+import { loadRunLedger, resolveFederatedRunLedgerDirectories, type RunLedgerEntry } from '../../self-implement/run-ledger.js';
+import { listLoops } from '../../loops/registry.js';
+import { listSubSeatCharters } from './sub-seat-charters.js';
+import { SEATS } from './ops-seats.js';
+import { jsonResponse } from './json-response.js';
+
+export interface LoopEdge {
+  at: string;
+  kind: 'request' | 'decision' | 'report' | 'card' | 'run';
+  from: string;
+  to: string;
+  ref: string;
+}
+
+export interface LoopEdgesDeps {
+  listCoord?: typeof listCoordEvents;
+  cardRoot?: string;
+  ledgerDir?: string;
+  listCards?: () => TaskCard[];
+  listRunStarts?: (since: string) => Array<{ runId: string; at: string; seat: string }>;
+  listLoopOwners?: () => Array<{ id: string; owner?: string | null }>;
+  seatIds?: () => string[];
+}
+
+const ID = /^[a-zA-Z0-9_-]{1,128}$/;
+const SURFACES = new Set(['telegram', 'pwa', 'linear', 'tui', 'discord', 'api', 'cli', 'voice', 'folder', 'wish']);
+const KINDS: Record<string, LoopEdge['kind']> = { '요청': 'request', '결정': 'decision', '보고': 'report' };
+
+function seat(value: unknown, seats: ReadonlySet<string>): value is string {
+  return typeof value === 'string' && seats.has(value);
+}
+function surface(value: unknown): value is string {
+  return typeof value === 'string' && SURFACES.has(value);
+}
+function object(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+function parse(content: string): Record<string, unknown> | null {
+  try { return object(JSON.parse(content) as unknown); } catch { return null; }
+}
+function inWindow(at: string, since: number, now: number): boolean {
+  const ms = Date.parse(at);
+  return Number.isFinite(ms) && ms >= since && ms <= now;
+}
+
+function cardEdges(card: TaskCard, since: number, now: number, seats: ReadonlySet<string>): LoopEdge[] {
+  if (!card.goalId.startsWith('wish:') || !ID.test(card.id)) return [];
+  const node = `card:${card.id}`;
+  const ref = card.id;
+  const edges: LoopEdge[] = [];
+  const intake = card.sections.find(s => s.key === 'intake:wish:0');
+  const intakeData = intake && parse(intake.content);
+  if (intake && surface(intakeData?.source) && inWindow(intake.createdAt, since, now)) {
+    edges.push({ at: intake.createdAt, kind: 'card', from: `surface:${intakeData.source}`, to: node, ref });
+  }
+  const split = card.sections.find(s => s.key === 'flow:split:0');
+  const splitData = split && parse(split.content);
+  const cells = Array.isArray(splitData?.cells) ? splitData.cells : [];
+  const owners = new Map<string, string>();
+  for (const item of cells) {
+    const cell = object(item);
+    if (typeof cell?.id === 'string' && ID.test(cell.id) && seat(cell.owner, seats)) owners.set(cell.id, cell.owner);
+  }
+  const placedOwners = new Set<string>();
+  for (const section of card.sections) {
+    if (!section.key.startsWith('flow:placed:')) continue;
+    const cellId = section.key.slice('flow:placed:'.length);
+    const saved = parse(section.content);
+    const placement = object(saved?.decision);
+    const owner = owners.get(cellId);
+    if (!owner || !placement || placement.id !== cellId || !ID.test(cellId)
+      || typeof placement.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(placement.version)) continue;
+    placedOwners.add(owner);
+    if (inWindow(section.createdAt, since, now)) {
+      const cellNode = `loop:${cellId}`;
+      edges.push({ at: section.createdAt, kind: 'card', from: node, to: cellNode, ref });
+      edges.push({ at: section.createdAt, kind: 'card', from: cellNode, to: owner, ref });
+    }
+  }
+  const reply = card.sections.find(s => s.key === 'intake:reply:0');
+  const replyData = reply && parse(reply.content);
+  // The destination section alone is not a send; flow:result records a completed card flow.
+  const result = card.sections.find(s => s.key === 'flow:result:0');
+  if (result && reply && surface(replyData?.surface) && inWindow(result.createdAt, since, now)) {
+    for (const owner of placedOwners) {
+      edges.push({ at: result.createdAt, kind: 'card', from: owner, to: `surface:${replyData.surface}`, ref });
+    }
+  }
+  return edges;
+}
+
+function runStarts(since: string, dir: string, owners: ReadonlyMap<string, string>, seats: ReadonlySet<string>): Array<{ runId: string; at: string; seat: string }> {
+  if (!existsSync(dir)) return [];
+  const result: Array<{ runId: string; at: string; seat: string }> = [];
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return []; }
+  for (const name of names) {
+    if (!/^run-[a-zA-Z0-9-]+\.jsonl$/.test(name)) continue;
+    const path = join(dir, name);
+    try { if (!statSync(path).isFile() || statSync(path).size > 5 * 1024 * 1024) continue; }
+    catch { continue; }
+    const runId = name.slice(0, -6);
+    let entries: RunLedgerEntry[] | null;
+    try { entries = loadRunLedger(runId, dir); } catch { continue; }
+    const start = entries?.find(entry => entry.event === 'start' && entry.runId === runId);
+    const feature = typeof start?.data.feature === 'string' ? start.data.feature : '';
+    const launchSeat = start?.data.launchSeat ?? start?.data.seat ?? owners.get(feature)
+      ?? start?.data.originAgent ?? start?.data.controller;
+    if (start?.timestamp && start.timestamp >= since && seat(launchSeat, seats)) {
+      result.push({ runId, at: start.timestamp, seat: launchSeat });
+    }
+  }
+  return result;
+}
+
+/** GET only; project an allowlist of fields from the three ledgers. Never serialize ledger records. */
+export function handleLoopEdgesGet(req: Request, deps: LoopEdgesDeps = {}): Response {
+  const params = new URL(req.url).searchParams;
+  const rawSince = params.get('since');
+  const since = rawSince === null ? Date.now() - 60 * 60 * 1000 : Date.parse(rawSince);
+  const rawLimit = params.get('limit');
+  const limit = rawLimit === null ? 100 : Number(rawLimit);
+  const now = Date.now();
+  if (rawSince !== null && !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(rawSince)
+    || !Number.isFinite(since) || since > now || !Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+    return jsonResponse({ error: 'usage: GET /v1/loops/edges?since=<ISO>&limit=<1..500>' }, 400);
+  }
+  const sinceIso = new Date(since).toISOString();
+  const seats = new Set((deps.seatIds ?? (() => [...SEATS.map(s => s.seat), ...listSubSeatCharters().map(s => s.id)]))());
+  const edges: LoopEdge[] = [];
+  for (const event of (deps.listCoord ?? listCoordEvents)({ since: sinceIso, channelOnly: true })) {
+    if (!seat(event.refs.seat, seats) || !inWindow(event.at, since, now)) continue;
+    const kind = KINDS[event.refs.kind ?? ''];
+    if (!kind || !Array.isArray(event.refs.recipients)) continue;
+    const ref = typeof event.refs.url === 'string' && /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(?:pull|issues)\/\d+#issuecomment-\d+$/.test(event.refs.url)
+      ? event.refs.url : event.id;
+    if (!ID.test(ref) && !ref.startsWith('https://github.com/')) continue;
+    for (const recipient of new Set(event.refs.recipients)) {
+      if (seat(recipient, seats)) edges.push({ at: event.at, kind, from: event.refs.seat, to: recipient, ref });
+    }
+  }
+  if (deps.listCards) {
+    for (const card of deps.listCards()) edges.push(...cardEdges(card, since, now, seats));
+  } else {
+    const root = deps.cardRoot;
+    if (existsSync(cardIndexPath(root))) {
+      const store = new CardStore(root, true);
+      try { for (const card of store.listCards()) edges.push(...cardEdges(card, since, now, seats)); }
+      finally { store.close(); }
+    }
+  }
+  const readStarts = deps.listRunStarts ?? ((from: string) => {
+    const owners = new Map<string, string>();
+    try {
+      for (const entry of (deps.listLoopOwners ?? (() => listLoops()))()) {
+        if (seat(entry.owner, seats)) owners.set(entry.id, entry.owner);
+      }
+    } catch { /* A registry outage does not erase explicit launch-seat evidence. */ }
+    return (deps.ledgerDir ? [deps.ledgerDir] : resolveFederatedRunLedgerDirectories({ includeTest: false }))
+      .flatMap(dir => runStarts(from, dir, owners, seats));
+  });
+  for (const run of readStarts(sinceIso)) {
+    if (seat(run.seat, seats) && ID.test(run.runId) && inWindow(run.at, since, now)) {
+      edges.push({ at: run.at, kind: 'run', from: run.seat, to: `loop:${run.runId}`, ref: run.runId });
+    }
+  }
+  edges.sort((a, b) => b.at.localeCompare(a.at) || a.kind.localeCompare(b.kind) || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+  return jsonResponse({ edges: edges.slice(0, limit) });
+}

package/src/nexus/api/schedules-read.ts

@@ -15,6 +15,7 @@ import { tasksDbPath } from '../../task-orchestrator/paths.js';
 import { jsonResponse } from './http-server.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { listScheduleRuns } from '../../domains/schedule-runs.js';
+import { listLoops } from '../../loops/registry.js';
 
 export interface SchedulesReadDeps {
   rows?: () => ScheduleRow[];
@@ -24,6 +25,7 @@ export interface SchedulesReadDeps {
   logsPath?: () => string;
   /** 발화 이력 원천(`schedule_runs`) — 기본은 schedules.db 를 읽기 전용으로 연다. */
   schedulesDbPath?: () => string;
+  loopOwners?: () => Array<{ id: string; title: string; owner?: string | null; enabled: boolean; lastRun: { at: string; status: string } | null; jobs: Array<{ id: string }> }>;
   now?: () => Date;
 }
 
@@ -201,6 +203,17 @@ export function handleSchedulesList(req: Request, opts: MetaApiOpts, deps: Sched
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   const cards = readSchedulesInventory(deps);
   const schedules = new URL(req.url).searchParams.get('includeOff') === '1' ? cards : cards.filter(c => c.state !== 'off');
+  if (new URL(req.url).searchParams.get('includeOwners') === '1') {
+    try {
+      const owners = (deps.loopOwners ?? (() => listLoops({ schedules: registryRows() })))().map(loop => ({ id: loop.id, title: redactSecretText(loop.title), owner: loop.owner ?? null,
+        enabled: loop.enabled, lastRun: loop.lastRun ? { at: loop.lastRun.at, status: loop.lastRun.status } : null,
+        jobs: loop.jobs.map(job => job.id) }));
+      return jsonResponse({ schedules, count: schedules.length, owners }, 200);
+    } catch {
+      // The ordinary inventory stays readable; an opted-in map must not mistake an outage for unowned loops.
+      return jsonResponse({ schedules, count: schedules.length, owners: null }, 200);
+    }
+  }
   return jsonResponse({ schedules, count: schedules.length }, 200);
 }
 

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

@@ -6,6 +6,7 @@ import { resolveAttachmentPath } from '../../boot/attachment-store.js';
 import { runGh } from '../../decisions/decision-cards.js';
 import { openMsgStore, canonicalSeatId } from '../../msg/msg-store.js';
 import { dispatchCeoTask, type CeoCommandDeps } from '../../seat-dispatch/ceo-commands.js';
+import { appendSeatRequestRows, withSeatRequestLedgerLock } from '../../seat-dispatch/seat-request-ledger.js';
 import { acknowledgeSeatAnswers, askSeat, deliverSeatAnswers, parseSeatAsk, type SeatAskDeps } from '../../seat-dispatch/seat-ask.js';
 import { getUserConfig } from '../../user-config.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
@@ -36,10 +37,12 @@ interface PendingRequest {
   queuedAt: string;
   ref: string;
   attachments?: string[];
+  reason?: string;
+  closedAt?: string;
 }
 
 interface RejectedRequest extends Omit<PendingRequest, 'status'> {
-  status: 'rejected';
+  status: 'rejected' | 'done';
 }
 
 type RecordEntry = (SeatRequestItem & { key: string }) | PendingRequest | RejectedRequest;
@@ -73,19 +76,7 @@ function file(root: string): string {
 }
 
 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;
-  }
+  appendSeatRequestRows(path, [entry]);
 }
 
 function records(path: string): Map<string, RecordEntry> {
@@ -100,7 +91,7 @@ function records(path: string): Map<string, RecordEntry> {
     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)
+      || typeof entry.queuedAt !== 'string' || !['pending', 'queued', 'rejected', 'done'].includes(entry.status)
       || (entry.status === 'queued' && typeof entry.receiptId !== 'string')
       || (entry.status !== 'queued' && typeof entry.ref !== 'string')) {
       throw new Error('invalid seat request journal');
@@ -121,7 +112,7 @@ function records(path: string): Map<string, RecordEntry> {
       throw new Error('invalid seat request outcome');
     }
     const current = entries.get(item.key);
-    if (current?.status === 'queued') continue;
+    if (current?.status === 'queued' || current?.status === 'done' || current?.closedAt) continue;
     if (current?.status === 'pending') {
       if (item.status === 'rejected' && current.ref !== item.ref) continue;
       if (item.status === 'queued' && current.queuedAt !== item.queuedAt) continue;
@@ -135,27 +126,32 @@ 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`;
+function persistOutcome(path: string, entry: RecordEntry, write: typeof append): RecordEntry {
+  return withSeatRequestLedgerLock(path, () => {
+    const current = records(path).get(entry.key);
+    if (current && ('closedAt' in current || current.status === 'done')) return current;
+    if (current?.status === 'queued') return current;
     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;
+      write(path, entry);
+      const sidecar = outcomeFile(path, entry.key);
+      if (existsSync(sidecar)) unlinkSync(sidecar);
+    } catch {
+      // A committed external delivery still needs a durable outcome if the journal write failed.
+      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;
+      }
     }
-  }
+    return entry;
+  });
 }
 
 function receipt(item: SeatRequestItem): Response {
@@ -298,13 +294,18 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   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); }
+    // A settled request answers from the journal before attachments are resolved — a retry
+    // must return its receipt even when the uploaded file is gone. The locked re-check below still guards races.
+    let settled: RecordEntry | undefined;
+    try { settled = records(path).get(key); }
     catch { return unavailable(); }
-    if (existing) {
-      if (existing.seat !== seat.id || existing.text !== text
-        || JSON.stringify(existing.attachments ?? []) !== JSON.stringify(attachmentIds)) return jsonResponse({ error: 'idempotency-conflict' }, 409);
-      if (existing.status === 'queued') return receipt(existing);
+    if (settled) {
+      if (settled.seat !== seat.id || settled.text !== text
+        || JSON.stringify(settled.attachments ?? []) !== JSON.stringify(attachmentIds)) return jsonResponse({ error: 'idempotency-conflict' }, 409);
+      if ('closedAt' in settled || settled.status === 'done') {
+        return jsonResponse({ error: 'request-closed', status: settled.status, reason: 'reason' in settled ? settled.reason : undefined }, 409);
+      }
+      if (settled.status === 'queued') return receipt(settled);
     }
     const attachments: Array<{ name: string; path: string }> = [];
     for (const id of attachmentIds) {
@@ -316,18 +317,36 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
       const metadata = (input.attachments as Array<{ name?: unknown }>)[attachments.length];
       attachments.push({ name: typeof metadata?.name === 'string' && metadata.name.trim() ? metadata.name : basename(resolved), path: resolved });
     }
-    const intent: PendingRequest = existing?.status === 'pending'
-      ? existing : { key, seat: seat.id, text, queuedAt: now, status: 'pending', ref: `pwa:${randomUUID()}`,
-        ...(attachmentIds.length ? { attachments: attachmentIds } : {}) };
-    if (existing?.status !== 'pending') {
-      try {
-        (deps.append ?? append)(path, intent);
-        if (existing?.status === 'rejected') {
-          const sidecar = outcomeFile(path, key);
-          if (existsSync(sidecar)) unlinkSync(sidecar);
+    let initial: { intent?: PendingRequest; response?: Response };
+    try {
+      initial = withSeatRequestLedgerLock(path, () => {
+        const existing = records(path).get(key);
+        if (existing) {
+          if (existing.seat !== seat.id || existing.text !== text
+            || JSON.stringify(existing.attachments ?? []) !== JSON.stringify(attachmentIds)) {
+            return { response: jsonResponse({ error: 'idempotency-conflict' }, 409) };
+          }
+          if ('closedAt' in existing || existing.status === 'done') {
+            return { response: jsonResponse({ error: 'request-closed', status: existing.status,
+              reason: 'reason' in existing ? existing.reason : undefined }, 409) };
+          }
+          if (existing.status === 'queued') return { response: receipt(existing) };
         }
-      } catch { return unavailable(); }
-    }
+        const intent: PendingRequest = existing?.status === 'pending'
+          ? existing : { key, seat: seat.id, text, queuedAt: now, status: 'pending', ref: `pwa:${randomUUID()}`,
+            ...(attachmentIds.length ? { attachments: attachmentIds } : {}) };
+        if (existing?.status !== 'pending') {
+          (deps.append ?? append)(path, intent);
+          if (existing?.status === 'rejected') {
+            const sidecar = outcomeFile(path, key);
+            if (existsSync(sidecar)) unlinkSync(sidecar);
+          }
+        }
+        return { intent };
+      });
+    } catch { return unavailable(); }
+    if (initial.response) return initial.response;
+    const intent = initial.intent!;
     const ceoSeat = canonicalSeatId(seat.id);
     if (['OP', 'TC', 'MK', 'UX'].includes(ceoSeat)) {
       let result: Awaited<ReturnType<typeof dispatchCeoTask>>;
@@ -342,10 +361,12 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
         ...(attachmentIds.length ? { attachments: attachmentIds } : {}), channel: result.channel,
         ...(result.channelError ? { channelError: result.channelError } : {}),
       };
-      try { persistOutcome(path, item, deps.append ?? append); }
+      let persisted: RecordEntry;
+      try { persisted = persistOutcome(path, item, deps.append ?? append); }
       catch { return unavailable(); }
+      if (persisted.status !== 'queued') return jsonResponse({ error: 'request-closed', status: persisted.status, reason: persisted.reason }, 409);
       publishInsideEvent({ kind: 'seat', seat: item.seat, receiptId: item.receiptId, status: item.status, ts: item.queuedAt });
-      return receipt(item);
+      return receipt(persisted);
     }
     let result: Awaited<ReturnType<typeof submitIntakeWork>>;
     try {
@@ -363,11 +384,13 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
     }
     const item: RecordEntry & SeatRequestItem = { key, receiptId: result.acceptanceId, seat: seat.id, text, queuedAt: intent.queuedAt,
       status: 'queued', ...(attachmentIds.length ? { attachments: attachmentIds } : {}) };
-    try { persistOutcome(path, item, deps.append ?? append); }
+    let persisted: RecordEntry;
+    try { persisted = persistOutcome(path, item, deps.append ?? append); }
     catch { return unavailable(); }
+    if (persisted.status !== 'queued') return jsonResponse({ error: 'request-closed', status: persisted.status, reason: persisted.reason }, 409);
     debug.log('seat-address.pwa', 'enqueued', { seat: seat.id, receiptId: item.receiptId });
     publishInsideEvent({ kind: 'seat', seat: item.seat, receiptId: item.receiptId, status: item.status, ts: item.queuedAt });
-    return receipt(item);
+    return receipt(persisted);
   })();
   inFlight.set(lock, { payload, task });
   start();

package/src/oauth/overload-failover-launch.ts

@@ -0,0 +1,75 @@
+// Launch-time application of the overload gate. Kept out of dev-cli.ts so a
+// unit test can import it without the dev-cli module graph (yaml, typescript).
+
+import type { ChildLlmSelection } from '../agent/run-context.js';
+import { debug } from '../debug/log.js';
+import { resolveGrokCredential } from '../grok/credential.js';
+import {
+  applyOverloadFailoverToChild,
+  readLlmCallOutcomes,
+  type OverloadFailoverLaunchDecision,
+} from './overload-failover.js';
+
+const CODEX_NAMES = new Set(['codex', 'openai-codex']);
+
+export function codexProviderNamed(provider: string | undefined): boolean {
+  if (!provider?.trim()) return false;
+  return CODEX_NAMES.has(provider.trim().toLowerCase());
+}
+
+let launchOverloadOutcomesForTesting: (() => ReturnType<typeof readLlmCallOutcomes>) | undefined;
+
+/** Test seam. `undefined` restores the real log store. */
+export function setLaunchOverloadOutcomesForTesting(
+  reader: (() => ReturnType<typeof readLlmCallOutcomes>) | undefined,
+): void {
+  launchOverloadOutcomesForTesting = reader;
+}
+
+export interface LaunchOverloadFlags {
+  provider?: string;
+  model?: string;
+  /** Pinned childLlm config naming codex. A flag is handled via `provider`. */
+  codexPinned?: boolean;
+  /** Test seam. Default: a grok credential resolves on this host. */
+  grokAvailable?: boolean;
+}
+
+/** Explicit codex stays. Otherwise k `llm.call`/`outcome` overload rows move
+ *  the unpinned child to grok before spawn. */
+export function applyLaunchOverloadFailover(
+  selection: ChildLlmSelection | undefined,
+  flags: LaunchOverloadFlags = {},
+  readOutcomes?: () => ReturnType<typeof readLlmCallOutcomes>,
+  env: NodeJS.ProcessEnv = process.env,
+): ChildLlmSelection | undefined {
+  // Test processes never read this machine's operational logs.db — results must not depend on the host's history.
+  const inTest = env.NODE_ENV === 'test' || Boolean(env.ELANOUS_TEST_HOME);
+  const reader = launchOverloadOutcomesForTesting ?? readOutcomes ?? (inTest ? () => [] : () => readLlmCallOutcomes());
+  let outcomes: ReturnType<typeof readLlmCallOutcomes> = [];
+  try { outcomes = reader(); } catch { outcomes = []; }
+  const explicit = codexProviderNamed(flags.provider) || flags.codexPinned === true;
+  let grokAvailable = flags.grokAvailable;
+  if (grokAvailable === undefined && outcomes.length > 0 && !inTest) {
+    // Only resolve when a switch is possible — a host without grok credentials must stay on codex. Tests inject it.
+    try { grokAvailable = resolveGrokCredential() !== null; } catch { grokAvailable = false; }
+  }
+  const { selection: next, decision } = applyOverloadFailoverToChild(selection, {
+    codexExplicit: explicit,
+    outcomes,
+    ...(grokAvailable !== undefined ? { grokAvailable } : {}),
+    defaultProvider: selection?.provider ?? 'openai-codex',
+  });
+  if (decision.switched && next?.provider === 'grok' && next.model) {
+    debug.log('self-dev', 'overload-failover', {
+      from: selection?.provider ?? 'openai-codex',
+      to: next.provider,
+      model: next.model,
+      why: decision.why,
+    }, { level: 'warn' });
+    return { provider: next.provider, model: next.model, source: 'config' };
+  }
+  return selection;
+}
+
+export type { OverloadFailoverLaunchDecision };

package/src/oauth/overload-failover.ts

@@ -0,0 +1,137 @@
+// Launch-time codex → grok switch driven only by `llm.call` / `outcome`.
+//
+// #24256 read `llm.response` / `llm.stream`. Those rows do not carry
+// provider + status + kind, so a launch that consulted them never saw
+// overload. This module refuses every other category.
+//
+// Boundaries:
+//   • an explicit codex child (flag or pinned config) never switches (#24183)
+//   • k consecutive codex overload/5xx/rate-limit outcomes switch the next
+//     child to grok before that child is spawned
+//   • k later successful outcomes restore codex
+//   • a 400 (kind `other`) never counts
+
+import { logsDbPath, LogStore, type LogStoreRow } from '../mss/logging/log-store.js';
+import {
+  codexOverloadStreakReached,
+  overloadRecovered,
+  OVERLOAD_FAILOVER_STREAK,
+  type LlmCallOutcome,
+  type LlmCallOutcomeKind,
+} from '../session-runtime/retry-policy.js';
+import { lookupLlmTierSpec } from '../model-tier/llm-tier-map.js';
+
+export const LLM_CALL_CATEGORY = 'llm.call';
+export const LLM_CALL_EVENT = 'outcome';
+
+const KINDS = new Set<LlmCallOutcomeKind>(['ok', 'overloaded', '5xx', 'rate-limit', 'other']);
+
+export interface OverloadFailoverLaunchInput {
+  /** True when the launch named codex (flag or pinned childLlm). */
+  readonly codexExplicit: boolean;
+  /** Provider the launch would have used before this gate. */
+  readonly provider: string;
+  readonly model?: string;
+  readonly outcomes: readonly LlmCallOutcome[];
+  readonly streak?: number;
+  /** grok may be selected. Unknown is not a reason to stay on a hot codex. */
+  readonly grokAvailable?: boolean;
+}
+
+export interface OverloadFailoverLaunchDecision {
+  readonly provider: string;
+  readonly model?: string;
+  readonly switched: boolean;
+  readonly why: 'explicit-codex' | 'not-codex' | 'streak' | 'recovered' | 'below-streak' | 'grok-unavailable';
+}
+
+export function parseLlmCallOutcome(row: Pick<LogStoreRow, 'category' | 'event' | 'data'>): LlmCallOutcome | undefined {
+  if (row.category !== LLM_CALL_CATEGORY || row.event !== LLM_CALL_EVENT || !row.data) return undefined;
+  let parsed: unknown;
+  try { parsed = JSON.parse(row.data); } catch { return undefined; }
+  if (!parsed || typeof parsed !== 'object') return undefined;
+  const rec = parsed as { provider?: unknown; status?: unknown; kind?: unknown };
+  if (typeof rec.provider !== 'string' || rec.provider.length === 0) return undefined;
+  if (typeof rec.status !== 'number' || !Number.isFinite(rec.status)) return undefined;
+  if (typeof rec.kind !== 'string' || !KINDS.has(rec.kind as LlmCallOutcomeKind)) return undefined;
+  return { provider: rec.provider, status: rec.status, kind: rec.kind as LlmCallOutcomeKind };
+}
+
+/** Newest-last. Rows that are not `llm.call`/`outcome` are dropped, never guessed. */
+export function outcomesFromCallRows(rows: readonly (Pick<LogStoreRow, 'category' | 'event' | 'data' | 'ts_ms'> & { id?: number })[]): LlmCallOutcome[] {
+  // The store returns newest first; calls in the same millisecond keep that order unless ties break on row id.
+  return [...rows]
+    .filter((row) => row.category === LLM_CALL_CATEGORY && row.event === LLM_CALL_EVENT)
+    .sort((a, b) => a.ts_ms - b.ts_ms || (a.id ?? 0) - (b.id ?? 0))
+    .flatMap((row) => {
+      const parsed = parseLlmCallOutcome(row);
+      return parsed ? [parsed] : [];
+    });
+}
+
+export function readLlmCallOutcomes(opts: {
+  dbPath?: string;
+  sinceMs?: number;
+  limit?: number;
+  open?: (path: string) => Pick<LogStore, 'query' | 'close'>;
+} = {}): LlmCallOutcome[] {
+  const path = opts.dbPath ?? logsDbPath();
+  const open = opts.open ?? ((dbPath: string) => LogStore.openReadOnly(dbPath));
+  let store: Pick<LogStore, 'query' | 'close'> | undefined;
+  try {
+    store = open(path);
+    const rows = store.query({
+      exactCategories: [LLM_CALL_CATEGORY],
+      events: [LLM_CALL_EVENT],
+      ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
+      limit: opts.limit ?? 50,
+    });
+    return outcomesFromCallRows(rows);
+  } catch {
+    return [];
+  } finally {
+    try { store?.close(); } catch { /* a missing store is "no sample", not a launch failure */ }
+  }
+}
+
+export function decideOverloadFailoverLaunch(input: OverloadFailoverLaunchInput): OverloadFailoverLaunchDecision {
+  const streak = input.streak ?? OVERLOAD_FAILOVER_STREAK;
+  const base = { provider: input.provider, ...(input.model !== undefined ? { model: input.model } : {}) };
+  if (input.codexExplicit) return { ...base, switched: false, why: 'explicit-codex' };
+  const onCodex = input.provider === 'openai-codex' || input.provider === 'codex';
+  if (!onCodex) return { ...base, switched: false, why: 'not-codex' };
+  if (overloadRecovered(input.outcomes, streak)) return { ...base, switched: false, why: 'recovered' };
+  if (!codexOverloadStreakReached(input.outcomes, streak)) return { ...base, switched: false, why: 'below-streak' };
+  if (input.grokAvailable === false) return { ...base, switched: false, why: 'grok-unavailable' };
+  return {
+    provider: 'grok',
+    model: lookupLlmTierSpec('grok', 'better').model,
+    switched: true,
+    why: 'streak',
+  };
+}
+
+/** Apply the gate to a not-yet-pinned child selection. Explicit codex is left untouched. */
+export function applyOverloadFailoverToChild<T extends { provider: string; model: string; source: 'flag' | 'config' }>(
+  selection: T | undefined,
+  opts: {
+    codexExplicit: boolean;
+    outcomes: readonly LlmCallOutcome[];
+    grokAvailable?: boolean;
+    defaultProvider?: string;
+  },
+): { selection: T | { provider: string; model: string; source: 'config' } | undefined; decision: OverloadFailoverLaunchDecision } {
+  const provider = selection?.provider ?? opts.defaultProvider ?? 'openai-codex';
+  const decision = decideOverloadFailoverLaunch({
+    codexExplicit: opts.codexExplicit,
+    provider,
+    ...(selection?.model !== undefined ? { model: selection.model } : {}),
+    outcomes: opts.outcomes,
+    grokAvailable: opts.grokAvailable,
+  });
+  if (!decision.switched || !decision.model) return { selection, decision };
+  return {
+    selection: { provider: decision.provider, model: decision.model, source: 'config' },
+    decision,
+  };
+}

package/src/prompt-enhance/enhance.ts

@@ -99,6 +99,8 @@ export interface EnhanceOpts {
   reasoningEffort?: 'low' | 'medium' | 'high';
   /** 산출물 유형 힌트(선택) — 예: 'PPT 발표덱', 'PLAN 문서'. 제약 문구 조정. */
   deliverableHint?: string;
+  /** Optional usage observer for the caller's authoring phase; missing usage stays unknown. */
+  onUsage?: (usage: LLMUsage) => void;
   /** 인핸싱 끄기(순수 verbatim). true 면 원문만 fenced 로 감싸 반환. */
   disabled?: boolean;
   /** Ask 원문 밖 스캐폴드에만 렌더할, 저작기가 관측한 디렉터리 실물 수. */
@@ -368,7 +370,10 @@ export async function enhancePrompt(raw: string, opts: EnhanceOpts = {}): Promis
     const rawOut = await streamLLM(messages, () => {}, {
       model,
       reasoningEffort: opts.reasoningEffort ?? 'high',
-      onUsage: (usage) => logLlmUsage(model, usage),
+      onUsage: (usage) => {
+        logLlmUsage(model, usage);
+        try { opts.onUsage?.(usage); } catch { /* usage observation must not change enhancement */ }
+      },
     });
     const parsed = parseEnhanceJson(rawOut);
     if (parsed) {