elanous 0.2.5 → 0.2.7

package/src/autopilot/track-agent-shadow.ts

@@ -0,0 +1,151 @@
+import { execFile } from 'node:child_process';
+import { appendFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { TrackAgentDecision, TrackAgentInput, TrackAgentResult } from './track-agent.js';
+
+const exec = promisify(execFile);
+const dateInKst = (now: Date): string => new Intl.DateTimeFormat('en-CA', {
+  timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit',
+}).format(now);
+
+export type ShadowLedgerEntry = {
+  at: string;
+  missionId: string;
+  taskId: string;
+  track: string;
+  event: 'decision-started' | 'decision' | 'orchestrate-started' | 'orchestrate';
+  action?: TrackAgentDecision['action'];
+  status?: TrackAgentResult['status'];
+  workdir?: string | null;
+  workdirs?: (string | null)[];
+};
+
+export type ShadowOptions = {
+  ledgerDir?: string;
+  now?: () => Date;
+  maxDecisionsPerDay?: number;
+  orchestrate?: (args: string[]) => Promise<{ stdout: string }>;
+};
+
+export function shadowLedgerPath(options: ShadowOptions = {}): string {
+  const now = options.now?.() ?? new Date();
+  return join(options.ledgerDir ?? join(effectiveInstanceRoot(), 'autopilot', 'track-agent-shadow'), `${dateInKst(now)}.jsonl`);
+}
+
+function append(entry: ShadowLedgerEntry, path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', flag: 'a' });
+}
+
+function entryFor(input: TrackAgentInput, event: ShadowLedgerEntry['event'], now: Date): ShadowLedgerEntry {
+  return { at: now.toISOString(), missionId: input.missionId, taskId: input.taskId, track: input.track, event };
+}
+
+/** Reserve a daily decision slot on disk before invoking the agent. An unreadable ledger never grants a slot. */
+export async function decideShadowTrackAction(
+  input: TrackAgentInput,
+  decide: (input: TrackAgentInput) => Promise<TrackAgentDecision> | TrackAgentDecision,
+  options: ShadowOptions = {},
+): Promise<TrackAgentDecision> {
+  const now = options.now?.() ?? new Date();
+  const path = shadowLedgerPath({ ...options, now: () => now });
+  const configured = options.maxDecisionsPerDay ?? 20;
+  const limit = Number.isSafeInteger(configured) && configured >= 0 ? configured : 20;
+  const lockPath = `${path}.lock`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    // The lock spans only count + reservation, never the callback. A contested slot fails closed.
+    mkdirSync(lockPath);
+  } catch {
+    return { action: 'hold', reason: 'shadow 원장 확인 실패' };
+  }
+  let reserved = false;
+  let capped = false;
+  try {
+    let rows: string[];
+    try { rows = readFileSync(path, 'utf8').split('\n').filter(Boolean); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      rows = [];
+    }
+    const count = rows.reduce((total, row) => {
+      const value: unknown = JSON.parse(row);
+      if (!value || typeof value !== 'object' || !('event' in value)) throw new Error('invalid shadow ledger');
+      return total + ((value as { event: unknown }).event === 'decision-started' ? 1 : 0);
+    }, 0);
+    if (count >= limit) capped = true;
+    else { append(entryFor(input, 'decision-started', now), path); reserved = true; }
+  } catch { /* The callback cannot run without a durable reservation. */ }
+  finally {
+    try { rmdirSync(lockPath); }
+    catch { reserved = false; }
+  }
+  if (capped) return { action: 'hold', reason: '일일 판정 상한' };
+  if (!reserved) return { action: 'hold', reason: 'shadow 원장 확인 실패' };
+  try {
+    const decision = await decide(input);
+    append({ ...entryFor(input, 'decision', now), action: decision.action }, path);
+    return decision;
+  } catch {
+    return { action: 'hold', reason: '판정 실패 — 사람 확인' };
+  }
+}
+
+function outcomeFromOutput(stdout: string): { workdirs: (string | null)[]; succeeded: boolean } {
+  const parsed: unknown = JSON.parse(stdout.trim());
+  const results = parsed && typeof parsed === 'object' && 'results' in parsed
+    ? (parsed as { results: unknown }).results : parsed;
+  const items: unknown[] = Array.isArray(results) ? results : [results];
+  const workdirs = items.map((item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const value = item as Record<string, unknown>;
+    const path = value.worktreePath ?? value.workdir;
+    return typeof path === 'string' && path.length > 0 ? path : null;
+  });
+  return {
+    workdirs,
+    succeeded: items.length > 0 && items.every((item, index) =>
+      item !== null && typeof item === 'object' && !Array.isArray(item)
+      && (item as Record<string, unknown>).status === 'done' && workdirs[index] !== null),
+  };
+}
+
+/** Called only after the ordinary track/forbidden-task/budget gates approve the work. */
+export async function launchTrackAgentShadow(input: TrackAgentInput, options: ShadowOptions = {}): Promise<TrackAgentResult> {
+  const now = options.now?.() ?? new Date();
+  const path = shadowLedgerPath({ ...options, now: () => now });
+  try {
+    append(entryFor(input, 'orchestrate-started', now), path);
+  } catch { return { status: 'failed', detail: 'shadow 원장 기록 실패' }; }
+  const args = ['self', 'orchestrate', '--json', `${input.title}\n${input.prompt}`];
+  let status: TrackAgentResult['status'] = 'failed';
+  let workdirs: (string | null)[] = [];
+  try {
+    const run = options.orchestrate ?? (async (values: string[]) => {
+      const instanceRoot = effectiveInstanceRoot();
+      const { stdout } = await exec('bun', ['bin/elanous.mjs', '--config-dir', instanceRoot, ...values], {
+        cwd: process.env.ELANOUS_TOOL_CWD?.trim() || resolve(import.meta.dir, '../..'),
+        env: { ...process.env, ELANOUS_STATE_DIR: instanceRoot },
+        encoding: 'utf8', maxBuffer: 1024 * 1024,
+      });
+      return { stdout };
+    });
+    const outcome = outcomeFromOutput((await run(args)).stdout);
+    workdirs = outcome.workdirs;
+    if (outcome.succeeded) status = 'launched';
+  } catch (error) {
+    // self orchestrate may exit nonzero after writing its JSON results; retain every observed workdir.
+    const stdout = (error as { stdout?: unknown }).stdout;
+    if (typeof stdout === 'string') {
+      try { workdirs = outcomeFromOutput(stdout).workdirs; } catch { /* malformed result has no observed workdir */ }
+    }
+  }
+  try {
+    append({ ...entryFor(input, 'orchestrate', now), status, workdir: workdirs[0] ?? null, workdirs }, path);
+  } catch { return { status: 'failed', detail: 'shadow 원장 기록 실패' }; }
+  return status === 'launched'
+    ? { status, detail: workdirs.join(', ') }
+    : { status, detail: 'shadow 실행 실패 또는 workdir 미관측' };
+}

package/src/autopilot/track-agent.ts

@@ -6,8 +6,9 @@ import { debug, redactSecretText } from '../debug/log.js';
 import { getOrCreatePersonaSession } from '../session/index.js';
 import { getUserConfig } from '../user-config.js';
 import { decideBudget, readBudgetInputsLive } from '../self-implement/budget-gate.js';
-import { loadTrackRegistry } from './mission-phase-track.js';
+import { findTrack } from './mission-phase-track.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { decideShadowTrackAction, launchTrackAgentShadow, type ShadowOptions } from './track-agent-shadow.js';
 
 export type TrackAgentInput = { missionId: string; taskId: string; title: string; prompt: string; track: string };
 export type TrackAgentDecision = { action: 'say' | 'hold'; reason?: string };
@@ -25,6 +26,8 @@ type RunnerDeps = {
   session?: (persona: string) => string;
   root?: string;
   maxConcurrent?: number;
+  shadow?: boolean;
+  shadowOptions?: ShadowOptions;
 };
 const root = resolve(import.meta.dir, '../..');
 // The installed package is not a git checkout — the daemon's target repository comes first.
@@ -41,11 +44,12 @@ const runCli = async (args: string[]): Promise<{ stdout: string }> => {
   const { argv, env } = universeLaunch(args);
   return exec('bun', argv, { cwd: repoDir(), env, timeout: 120_000, maxBuffer: 1024 * 1024, encoding: 'utf8' });
 };
-const forbidden = /\b(?:delete|remove|deploy|publish|release|restart|reboot|merge|force|pay|purchase|secret|credential|sudo|rm\s+-rf|config\s+set)\b|(?:^|\s)--prod\b|삭제|배포|게시|릴리스|재시작|재부팅|병합|결제|자격|비밀|강제/i;
+const forbiddenActionRegex = /\b(?:delete|remove|deploy|publish|release|restart|reboot|merge|force|pay|purchase|secret|credential|sudo|rm\s+-rf|config\s+set)\b|(?:^|\s)--prod\b|삭제|배포|게시|릴리스|재시작|재부팅|병합|결제|자격|비밀|강제/i;
+export const TRACK_AGENT_FORBIDDEN_ACTION_REGEX = new RegExp(forbiddenActionRegex.source, forbiddenActionRegex.flags);
 let running = 0;
 
 function context(input: TrackAgentInput, repo: string): string {
-  const track = loadTrackRegistry().find(({ id }) => id === input.track);
+  const track = findTrack(input.track);
   if (!track) throw new Error('unknown track');
   const docs = resolve(repo, 'docs');
   let handoff = '';
@@ -70,6 +74,17 @@ function context(input: TrackAgentInput, repo: string): string {
 }
 
 export async function decideTrackAction(input: TrackAgentInput, deps: RunnerDeps = {}): Promise<TrackAgentDecision> {
+  if (!(deps.shadow ?? getUserConfig().autopilot?.trackAgent?.shadow ?? false)) {
+    return decideTrackActionOnce(input, deps);
+  }
+  return decideShadowTrackAction(input, (value) => decideTrackActionOnce(value, deps), {
+    ...deps.shadowOptions,
+    maxDecisionsPerDay: deps.shadowOptions?.maxDecisionsPerDay
+      ?? getUserConfig().autopilot?.trackAgent?.shadowMaxDecisionsPerDay ?? 20,
+  });
+}
+
+async function decideTrackActionOnce(input: TrackAgentInput, deps: RunnerDeps): Promise<TrackAgentDecision> {
   try {
     const prompt = context(input, deps.root ?? repoDir());
     const persona = `track-${input.track}`;
@@ -83,7 +98,7 @@ export async function decideTrackAction(input: TrackAgentInput, deps: RunnerDeps
     const values = decision as Record<string, unknown>;
     if (!['say', 'hold'].includes(String(values.action)) || (values.reason !== undefined && typeof values.reason !== 'string')
       || Object.keys(values).some((key) => !['action', 'reason'].includes(key))) throw new Error('invalid decision');
-    if (typeof values.reason === 'string' && forbidden.test(values.reason)) throw new Error('forbidden action');
+    if (typeof values.reason === 'string' && forbiddenActionRegex.test(values.reason)) throw new Error('forbidden action');
     return decision as TrackAgentDecision;
   } catch (error) {
     log('decision-failed', { track: input.track, taskId: input.taskId, error: redactSecretText(String(error)) });
@@ -93,8 +108,8 @@ export async function decideTrackAction(input: TrackAgentInput, deps: RunnerDeps
 
 export async function executeTrackAction(decision: TrackAgentDecision, input: TrackAgentInput, deps: RunnerDeps = {}): Promise<TrackAgentResult> {
   if (decision.action !== 'say') return { status: 'held', detail: decision.reason ?? '사람 확인' };
-  if (forbidden.test(`${input.title}\n${input.prompt}`)) return { status: 'held', detail: '금지 작업 — 사람 확인' };
-  if (!loadTrackRegistry().some(({ id }) => id === input.track)) return { status: 'held', detail: '트랙 미정 — 사람 확인' };
+  if (forbiddenActionRegex.test(`${input.title}\n${input.prompt}`)) return { status: 'held', detail: '금지 작업 — 사람 확인' };
+  if (!findTrack(input.track)) return { status: 'held', detail: '트랙 미정 — 사람 확인' };
   try {
     const checkBudget = deps.checkBudget ?? (async () => {
       const action = decideBudget(await readBudgetInputsLive()).action;
@@ -112,6 +127,11 @@ export async function executeTrackAction(decision: TrackAgentDecision, input: Tr
   running++;
   let held = false;
   try {
+    if (deps.shadow ?? getUserConfig().autopilot?.trackAgent?.shadow ?? false) {
+      const result = await launchTrackAgentShadow(input, deps.shadowOptions);
+      log('shadow-orchestrate', { track: input.track, taskId: input.taskId, status: result.status, detail: result.detail });
+      return result;
+    }
     const launch = deps.launch ?? (async (args: string[]) => {
       const { argv, env } = universeLaunch(args);
       const child = spawn('bun', argv, { cwd: repoDir(), env, stdio: 'ignore', detached: true });

package/src/autopilot/track-courier.ts

@@ -6,7 +6,7 @@ import { join, resolve } from 'node:path';
 import { debug, redactSecretText } from '../debug/log.js';
 import { TaskStore } from '../task-orchestrator/store.js';
 import { getUserConfig, type UserConfig } from '../user-config.js';
-import { inferPhaseTrack, loadTrackRegistry } from './mission-phase-track.js';
+import { inferPhaseTrack, loadTrackRegistry, trackPostIds } from './mission-phase-track.js';
 import type { TrackAgentInput, TrackAgentRunner } from './track-agent.js';
 
 type CourierConfig = NonNullable<NonNullable<UserConfig['autopilot']>['trackCourier']>;
@@ -66,7 +66,7 @@ export async function trackAlive(track: string, deps: CourierDeps = {}): Promise
     const comments = await (deps.listComments ?? (() => defaultComments(config.channelPr!, now, minutesFor(config))))();
     if (!Array.isArray(comments)) throw new Error('comments response is not an array');
     const timestamps = comments
-      .filter((c) => c && typeof c.body === 'string' && c.body.startsWith(`**[${track}]**`))
+      .filter((c) => c && typeof c.body === 'string' && trackPostIds(track).some((id) => c.body.startsWith(`**[${id}]**`)))
       .map((c) => Date.parse(c.created_at))
       .filter((at) => Number.isFinite(at) && at <= now);
     if (!timestamps.length) return { alive: false, lastPostAt: null, reason: 'no-post' };

package/src/boot/acp-server-help.ts

@@ -0,0 +1,16 @@
+export function acpServerHelpText(): string {
+  return `
+ACP server (Agent Client Protocol)
+  Usage: elanous --acp-server [--transport=stdio|unix-socket|websocket] [options]
+  Example: elanous --acp-server --transport=websocket
+
+  --transport=stdio|unix-socket|websocket  Connection transport (default: stdio)
+  --socket-path=<path>                    Unix socket path (unix-socket only)
+  --port=<number>                         Listening port (websocket only)
+  --host=<host>                           Bind host (websocket only)
+  --tool-cwd=<path>                       Default working directory for tools
+  --no-auth                               Disable websocket token authentication
+
+  Zed setup and connection check: docs/manual/MANUAL-zed-acp.md
+`;
+}

package/src/boot/daemon-prompt-turn.ts

@@ -1,3 +1,5 @@
+import { classifyShortQuestion } from '../chat/short-question.js';
+import { getUserConfig } from '../user-config.js';
 import { runCoreTurn } from '../core-turn/index.js';
 import type { LLMMessage, LLMToolSpec } from '../llm.js';
 import { maybeImageBearingResult } from '../llm.js';
@@ -83,6 +85,8 @@ export function summarizeToolResult(result: unknown): string | undefined {
 
 export async function runDaemonPromptTurn(opts: {
   history: DaemonSessionHistory;
+  /** B1 빠른 경로 스위치 — 없으면 config `chat.fastPath`(기본 true). 시험·호출부가 못 박을 때만 준다. */
+  fastPathEnabled?: boolean;
   request: DaemonPromptRequest;
   /** Optional multimodal prompt blocks for the current user turn.
    *  When present, history persistence keeps the ACP block shape
@@ -173,6 +177,19 @@ export async function runDaemonPromptTurn(opts: {
     reason: surfaceResolutionReason,
     hasUserText: request.userText.length > 0,
   });
+  const hasAttachments = (opts.promptBlocks?.length ? opts.promptBlocks : request.userContent)
+    ?.some((block) => block.type !== 'text') ?? false;
+  // SW2 스위치 `chat.fastPath`(기본 켜짐 · PWA «짧은 물음은 빠르게» 카드) — 끄면 분류하지 않는다.
+  const fastPathEnabled = opts.fastPathEnabled ?? (() => { try { return getUserConfig().chat?.fastPath !== false; } catch { return true; } })();
+  const { fast, reason } = fastPathEnabled
+    ? classifyShortQuestion(request.userText, { hasAttachments })
+    : { fast: false, reason: 'disabled' };
+  const activeToolSurface = fast ? undefined : toolSurface;
+  const toolsBefore = toolSurface && toolSurface.kind !== 'none' ? toolSurface.specs.length : 0;
+  const tools: LLMToolSpec[] = activeToolSurface && activeToolSurface.kind !== 'none'
+    ? activeToolSurface.specs
+    : [];
+  debug.log('chat.fast-path', 'decided', { fast, reason, toolsBefore, toolsAfter: tools.length });
   // Image-pipeline followup #4 (2026-05-05) — when the webterm surface
   // is active, prepend a daemon-context block ("Current ACP sessionId:
   // …" + active terminals) to the system prompt so the LLM has the
@@ -181,21 +198,18 @@ export async function runDaemonPromptTurn(opts: {
   const augmentedSystemPrompt = appendWebtermContext(
     request.effectiveSystemPrompt,
     request.sessionId,
-    toolSurface,
+    activeToolSurface,
   );
   const ctrl = new AbortController();
   if (opts.signal) {
     if (opts.signal.aborted) ctrl.abort();
     else opts.signal.addEventListener('abort', () => ctrl.abort(), { once: true });
   }
-  const tools: LLMToolSpec[] = toolSurface && toolSurface.kind !== 'none'
-    ? toolSurface.specs
-    : [];
   const toolCwdResolver = createToolCwdResolver({
-    tools: toolSurface?.kind ?? 'none',
+    tools: activeToolSurface?.kind ?? 'none',
     ...(opts.toolCwd !== undefined ? { toolCwd: opts.toolCwd } : {}),
   });
-  const rawDispatchTool = toolSurface && toolSurface.kind !== 'none'
+  const rawDispatchTool = activeToolSurface && activeToolSurface.kind !== 'none'
     ? async (name: string, args: Record<string, unknown>, perCallCtx?: { callId: string }): Promise<unknown> => {
         const dispatchCtrl = new AbortController();
         const onAbort = (): void => dispatchCtrl.abort();
@@ -204,7 +218,7 @@ export async function runDaemonPromptTurn(opts: {
           // Image-pipeline followup #1 (2026-05-05) — pass the current
           // request.sessionId through so WebTerminal* tools can auto-
           // resolve scope when the LLM omits sessionId from args.
-          return await toolSurface.dispatch(name, args, {
+          return await activeToolSurface.dispatch(name, args, {
             cwd: toolCwdResolver.cwd!,
             resolveWriteCwd: toolCwdResolver.resolveWriteCwd,
             signal: dispatchCtrl.signal,
@@ -246,9 +260,13 @@ export async function runDaemonPromptTurn(opts: {
       })
     : null;
   const dispatchTool = terminal ? terminal.dispatch : rawDispatchTool;
-  const effectiveSystemPrompt = terminal
-    ? terminal.systemPromptParts.join('\n\n')
-    : augmentedSystemPrompt;
+  const fastPathGuidance = '확인이 필요하면 "확인해 볼까요?" 한 줄로 끝낸다';
+  const effectiveSystemPrompt = fast
+    ? [augmentedSystemPrompt, fastPathGuidance].filter(Boolean).join('\n')
+    : terminal
+      ? terminal.systemPromptParts.join('\n\n')
+      : augmentedSystemPrompt;
+  const isFirstTurn = history.get(request.sessionId).length === 0;
   const messages = opts.promptBlocks && opts.promptBlocks.length > 0
     ? appendUserPromptBlocksAndBuildMessages(
         history,
@@ -262,6 +280,9 @@ export async function runDaemonPromptTurn(opts: {
         request.userText,
         effectiveSystemPrompt,
       );
+  if (fast && !isFirstTurn) {
+    messages.unshift({ role: 'system', content: fastPathGuidance });
+  }
   const result = await runCoreTurn({
     sessionId: request.sessionId,
     userText: request.userText,

package/src/boot/daemon-tools/index.ts

@@ -389,7 +389,13 @@ export function toolSurface(kind: DaemonToolSurfaceKind, cfg?: import('../../use
       }
     }
     if (shared.names.has(name)) {
-      return shared.dispatch(name, args); // L2 core + L3 finance(gated) — buildSharedAppTools 단일 dispatch
+      // L2 core + L3 finance(gated) — buildSharedAppTools 단일 dispatch · B5: 진행 한 줄(emitFeedback)·세션·호출 id 를 넘긴다.
+      return shared.dispatch(name, args, {
+        surface: 'tui',
+        ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
+        ...(ctx.toolCallId ? { toolCallId: ctx.toolCallId } : {}),
+        ...(ctx.emitFeedback ? { emitFeedback: ctx.emitFeedback } : {}),
+      });
     }
     if (name === 'Bash') {
       // PLAN-ios-rich-dev-feedback-hydrate M3 (2026-05-13) — pass

package/src/budget/codex-credit-pace.ts

@@ -0,0 +1,84 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { codexCredentialRoot } from './codex-reset-credit-state.js';
+import type { LlmPolicy } from '../policy/llm-policy.js';
+
+interface CreditDay {
+  day: string;
+  accounts: Record<string, { dayOpen: number; balance: number }>;
+}
+
+export type CreditBalances = Readonly<Record<string, number>>;
+
+function kstDay(now: Date): string {
+  return new Date(now.getTime() + 9 * 3_600_000).toISOString().slice(0, 10);
+}
+
+function dayNumber(day: string): number {
+  return Date.parse(`${day}T00:00:00Z`) / 86_400_000;
+}
+
+function creditDayPath(stateDir?: string): string {
+  return join(stateDir ?? codexCredentialRoot(), 'budget', 'codex-credit-day.json');
+}
+
+function readCreditDay(stateDir?: string): CreditDay | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(creditDayPath(stateDir), 'utf8')) as CreditDay;
+    return typeof parsed.day === 'string' && parsed.accounts && typeof parsed.accounts === 'object' && !Array.isArray(parsed.accounts)
+      ? parsed : undefined;
+  } catch { return undefined; }
+}
+
+/** Only a poller's observed balance can move the opening balance; readers never modify the ledger. */
+export function recordCreditBalances(balances: CreditBalances, now: Date = new Date(), stateDir?: string): void {
+  const day = kstDay(now);
+  const previous = readCreditDay(stateDir);
+  const accounts: CreditDay['accounts'] = previous?.day === day ? { ...previous.accounts } : {};
+  for (const [name, balance] of Object.entries(balances)) {
+    if (!Number.isFinite(balance) || balance < 0) continue;
+    const prior = Object.prototype.hasOwnProperty.call(accounts, name) ? accounts[name] : undefined;
+    const dayOpen = prior && Number.isFinite(prior.dayOpen) && Number.isFinite(prior.balance)
+      ? (balance > prior.balance ? balance : prior.dayOpen)
+      : balance;
+    Object.defineProperty(accounts, name, { value: { dayOpen, balance }, enumerable: true, configurable: true, writable: true });
+  }
+  const path = creditDayPath(stateDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ day, accounts }, null, 2)}\n`);
+  renameSync(temporary, path);
+}
+
+export function creditPaceStatus({ policy, balances, now = new Date(), stateDir }: {
+  policy: LlmPolicy;
+  balances: CreditBalances;
+  now?: Date;
+  stateDir?: string;
+}): { active: boolean; todaySpent: number; target: number; remaining: number; daysLeft: number; projectedAtUntil: number } {
+  const day = kstDay(now);
+  const ledger = readCreditDay(stateDir);
+  const observed = Object.entries(balances).filter(([, balance]) => Number.isFinite(balance) && balance >= 0);
+  const todaySpent = ledger?.day === day ? observed.reduce((sum, [name, balance]) => {
+    const open = Object.prototype.hasOwnProperty.call(ledger.accounts, name) ? ledger.accounts[name]?.dayOpen : undefined;
+    return sum + (typeof open === 'number' && Number.isFinite(open) ? Math.max(0, open - balance) : 0);
+  }, 0) : 0;
+  const remaining = observed.reduce((sum, [, balance]) => sum + balance, 0);
+  const until = policy.credits.pace?.until;
+  const expiry = until ? Date.parse(`${until}T15:00:00Z`) : NaN;
+  const daysLeft = until ? Math.max(1, dayNumber(until) - dayNumber(day) + 1) : 1;
+  // The poller's opening observation anchors today's allocation. Spending cannot lower it;
+  // a new grant or the next KST day changes the opening observation.
+  const startingBalance = ledger?.day === day
+    ? observed.reduce((sum, [name, balance]) => {
+      const entry = Object.prototype.hasOwnProperty.call(ledger.accounts, name) ? ledger.accounts[name] : undefined;
+      return sum + (entry && Number.isFinite(entry.dayOpen) ? entry.dayOpen : balance);
+    }, 0)
+    : remaining;
+  const target = until ? Math.ceil(startingBalance / daysLeft) : 0;
+  return {
+    active: policy.credits.codex === 'use' && !!until && now.getTime() < expiry && remaining > 0 && todaySpent < target,
+    todaySpent, target, remaining, daysLeft,
+    projectedAtUntil: Math.max(0, remaining - Math.max(0, target - todaySpent) - target * (daysLeft - 1)),
+  };
+}

package/src/budget/codex-credit-plan.ts

@@ -0,0 +1,154 @@
+// Codex prepaid-credit plan: days left until the credits expire, the daily spend that would use the balance up,
+// and what was actually spent over the last 7 days. Disk only — the balance history is appended by
+// writeQuotaSignal whenever a measured balance changes; nothing here touches the network.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DAY_MS = 86_400_000;
+const HISTORY_KEEP_MS = 30 * DAY_MS;
+const HISTORY_FILE = 'codex-credit-history.jsonl';
+
+export interface CreditHistoryEntry { at: string; home: string; balance: number }
+
+export function creditHistoryPath(signalDir: string): string {
+  return join(signalDir, HISTORY_FILE);
+}
+
+export function readCreditHistory(signalDir: string): CreditHistoryEntry[] {
+  try {
+    const path = creditHistoryPath(signalDir);
+    if (!existsSync(path)) return [];
+    const out: CreditHistoryEntry[] = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line) as Partial<CreditHistoryEntry>;
+        if (typeof e.at === 'string' && typeof e.home === 'string' && typeof e.balance === 'number' && Number.isFinite(e.balance)) out.push(e as CreditHistoryEntry);
+      } catch { /* a torn line is skipped */ }
+    }
+    return out;
+  } catch { return []; }
+}
+
+/** Appends only when this home's balance changed; prunes entries older than 30 days. Fail-soft. */
+export function appendCreditHistory(signalDir: string, home: string, balance: number, now: number = Date.now()): void {
+  try {
+    if (!Number.isFinite(balance)) return;
+    const history = readCreditHistory(signalDir);
+    const last = [...history].reverse().find((e) => e.home === home);
+    if (last && last.balance === balance) return;
+    mkdirSync(signalDir, { recursive: true });
+    const entry: CreditHistoryEntry = { at: new Date(now).toISOString(), home, balance };
+    const kept = history.filter((e) => now - Date.parse(e.at) <= HISTORY_KEEP_MS);
+    if (kept.length !== history.length) {
+      writeFileSync(creditHistoryPath(signalDir), [...kept, entry].map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+    } else {
+      appendFileSync(creditHistoryPath(signalDir), `${JSON.stringify(entry)}\n`, 'utf8');
+    }
+  } catch { /* observation never blocks the fetch */ }
+}
+
+/** Credits spent in the window: sum of balance drops per home (rises are top-ups and are not spend). */
+export function creditSpend(history: readonly CreditHistoryEntry[], now: number, windowMs = 7 * DAY_MS): { spent: number; spanDays: number } | null {
+  const since = now - windowMs;
+  let spent = 0;
+  let earliest = Infinity;
+  const byHome = new Map<string, CreditHistoryEntry[]>();
+  for (const e of history) {
+    const at = Date.parse(e.at);
+    if (!Number.isFinite(at) || at > now) continue;
+    byHome.set(e.home, [...(byHome.get(e.home) ?? []), e]);
+  }
+  for (const entries of byHome.values()) {
+    entries.sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+    // The last entry before the window is the baseline for the first change inside it.
+    let start = entries.findIndex((e) => Date.parse(e.at) >= since);
+    if (start === -1) continue;
+    if (start > 0) start -= 1;
+    const used = entries.slice(start);
+    if (used.length < 2) continue;
+    earliest = Math.min(earliest, Math.max(since, Date.parse(used[0]!.at)));
+    for (let i = 1; i < used.length; i++) {
+      const drop = used[i - 1]!.balance - used[i]!.balance;
+      if (drop > 0) spent += drop;
+    }
+  }
+  if (!Number.isFinite(earliest)) return null;
+  return { spent, spanDays: Math.max((now - earliest) / DAY_MS, 1 / 24) };
+}
+
+export interface CodexCreditPlan {
+  /** policy credits.pace.until, else the earliest grant expiry; null when the policy records neither. */
+  expiresAt: string | null;
+  daysLeft: number | null;
+  /** Sum of the known per-account balances; null when no balance is known. */
+  totalBalance: number | null;
+  unknownBalances: number;
+  accounts: Array<{ name: string; balance: number | null; expires: string | null }>;
+  /** Credits per day that would use the balance up by the expiry date. */
+  dailyNeeded: number | null;
+  /** policy credits.pace.targetPerDay — the declared pace, shown beside the computed one. */
+  targetPerDay: number | null;
+  /** Credits actually spent per day over the last 7 days (or the shorter recorded span). */
+  actualPerDay: number | null;
+  actualSpanDays: number | null;
+  /** policy credits.pace.why */
+  note: string | null;
+}
+
+export interface CreditPolicyView {
+  codex: string;
+  grants: ReadonlyArray<{ account: string; amount: number; expires: string }>;
+  pace?: { targetPerDay: number; until: string; why?: string };
+}
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function codexCreditPlan(input: {
+  now: number;
+  balances: ReadonlyArray<{ name: string; balance?: number }>;
+  credits: CreditPolicyView;
+  history: readonly CreditHistoryEntry[];
+}): CodexCreditPlan {
+  const { credits } = input;
+  const accounts = input.balances.map((a) => {
+    const grantDates = credits.grants.filter((g) => g.account === a.name && DATE.test(g.expires)).map((g) => g.expires).sort();
+    return { name: a.name, balance: typeof a.balance === 'number' && Number.isFinite(a.balance) ? a.balance : null, expires: grantDates[0] ?? null };
+  });
+  const known = accounts.map((a) => a.balance).filter((b): b is number => b !== null);
+  const totalBalance = known.length ? known.reduce((x, y) => x + y, 0) : null;
+  const earliestGrant = credits.grants.map((g) => g.expires).filter((d) => DATE.test(d)).sort()[0];
+  const expiresAt = credits.pace?.until && DATE.test(credits.pace.until) ? credits.pace.until : earliestGrant ?? null;
+  const expiry = expiresAt ? Date.parse(`${expiresAt}T23:59:59+09:00`) : NaN;
+  const daysLeft = Number.isFinite(expiry) ? Math.max(0, Math.ceil((expiry - input.now) / DAY_MS)) : null;
+  const spend = creditSpend(input.history, input.now);
+  return {
+    expiresAt,
+    daysLeft,
+    totalBalance,
+    unknownBalances: accounts.length - known.length,
+    accounts,
+    dailyNeeded: daysLeft && totalBalance !== null ? totalBalance / daysLeft : null,
+    targetPerDay: credits.pace?.targetPerDay ?? null,
+    actualPerDay: spend ? spend.spent / Math.min(7, spend.spanDays) : null,
+    actualSpanDays: spend ? Math.round(Math.min(7, spend.spanDays) * 10) / 10 : null,
+    note: credits.pace?.why?.trim() || null,
+  };
+}
+
+/** The lines both surfaces print under the policy line. */
+export function formatCodexCreditPlan(plan: CodexCreditPlan): string[] {
+  const n = (v: number) => String(Math.round(v));
+  const unknown = plan.unknownBalances ? ` (+${plan.unknownBalances}개 계정 모름)` : '';
+  const perAccount = plan.accounts.map((a) => `${a.name} ${a.balance === null ? '?' : n(a.balance)}${a.expires ? `(~${a.expires})` : ''}`).join(' · ');
+  const lines = [
+    `크레딧    잔액 합 ${plan.totalBalance === null ? '?' : n(plan.totalBalance)}${unknown} · 만료 ${plan.expiresAt ?? '모름 (policy credits.pace.until · credits.grants)'}${perAccount ? ` · ${perAccount}` : ''}`,
+  ];
+  const days = plan.daysLeft === null ? '만료일 모름' : `만료까지 ${plan.daysLeft}일`;
+  const needed = plan.dailyNeeded === null ? '?' : n(plan.dailyNeeded);
+  const target = plan.targetPerDay === null ? '' : ` (목표 ${n(plan.targetPerDay)})`;
+  const actual = plan.actualPerDay === null ? '기록 없음' : `${n(plan.actualPerDay)}/일${plan.actualSpanDays !== null && plan.actualSpanDays < 7 ? ` (기록 ${plan.actualSpanDays}일)` : ''}`;
+  lines.push(`계산      ${days} · 하루 소진 필요 ${needed}${target} · 최근 7일 실제 ${actual}`);
+  if (plan.note) lines.push(`메모      ${plan.note}`);
+  return lines;
+}

package/src/budget/codex-reset-credit-state.ts

@@ -9,6 +9,7 @@
 //     ⇒ 직접 부르는 쪽은 «자기가» 감싸야 한다. 여기서 삼키면 저장 실패가 영영 안 보인다.
 //   ⭐ 반면 `writeQuotaSignal` 은 «판정 신호»라 조회를 막으면 안 되므로 자기가 삼킨다(아래 주석).
 
+import { appendCreditHistory } from './codex-credit-plan.js';
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
@@ -233,6 +234,7 @@ export function writeQuotaSignal(
       ...(typeof credits?.hasCredits === 'boolean' ? { hasCredits: credits.hasCredits } : {}),
     };
     writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    if (next.creditsBalance !== undefined && next.measuredHome) appendCreditHistory(dirname(path), next.measuredHome, next.creditsBalance);
   } catch { /* fail-soft */ }
 }
 

package/src/chat/chat-cli.ts

@@ -49,5 +49,8 @@ export function toDevChatOpts(opts: ChatCliOpts): DevChatOpts {
 export async function runChatCliCommand(text: string, opts: ChatCliOpts, deps: ChatCliDeps): Promise<void> {
   const spec = buildChatDevSpec(text, toDevChatOpts(opts));
   const run = deps.runDevPipeline ?? runDevPipeline;
-  await run(spec, { runChatTurn: deps.runChatTurn });
+  await run(spec, {
+    runChatTurn: deps.runChatTurn,
+    ...(opts.json ? { progress: (message: string) => { process.stderr.write(`${message}\n`); } } : {}),
+  });
 }