elanous 0.2.22 → 0.2.24

package/src/budget/unified-usage.ts

@@ -9,6 +9,7 @@ import { createCodexFetcher, type CodexFetcherOpts } from './fetchers/codex.js';
 import {
   fetchGrokUsage,
   GROK_SUBSCRIPTION_AXIS,
+  grokUsageToSubscriptionAxis,
   grokUsageToCreditAxis,
   type GrokUsageResult,
 } from '../grok/usage.js';
@@ -20,6 +21,10 @@ import { envLiteral } from '../platform/env-literal.js';
 import { describeResetCreditExpiry } from './codex-reset-credit-state.js';
 import { visibleWidth } from '../tui.js';
 import { listCodexResetCredits, type CodexResetCreditsResult } from './codex-reset-credits.js';
+import {
+  buildZaiUsageView, fetchZaiQuota, getZaiApiKey, readZaiLedger,
+  type ZaiLedgerRecord, type ZaiQuotaResult, type ZaiUsageView,
+} from '../llm/zai-coding-plan.js';
 import type {
   AccountUsageRow,
   CreditAxis,
@@ -50,24 +55,93 @@ export interface UnifiedUsageDeps {
   /** 결정 2026-09-23 — OpenRouter 선불 크레딧 조회 seam. 없으면 실키로 `/api/v1/credits`. */
   readonly openRouterKey?: () => string | undefined;
   readonly fetchOpenRouterImpl?: typeof fetch;
+  /** ZAI-CODING-PLAN-PROVIDER seam — 키 «있음» 판정(값은 안 쓴다) · 공식 조회 · 원장. */
+  readonly zaiKey?: () => string | undefined;
+  readonly fetchZaiQuota?: () => Promise<ZaiQuotaResult>;
+  readonly readZaiLedger?: () => ZaiLedgerRecord[];
 }
 
 export async function collectUnifiedUsage(deps: UnifiedUsageDeps = {}): Promise<UnifiedUsageReport> {
-  const [codexRows, grokRows, openRouterRows] = await Promise.all([
+  const [codexRows, grokRows, openRouterRows, zai] = await Promise.all([
     collectCodexRows(deps),
     collectGrokRows(deps),
     collectOpenRouterRows(deps),
+    collectZaiRows(deps),
   ]);
   return {
-    rows: [...codexRows, ...grokRows, ...openRouterRows],
+    rows: [...codexRows, ...grokRows, ...openRouterRows, ...(zai?.rows ?? [])],
     accountCounts: {
       codex: codexRows.length,
       grok: grokRows.length,
       openrouter: openRouterRows.length,
+      // ⛔ 키가 없으면 칸 자체를 안 싣는다 — 종전 JSON·문면과 바이트 동일.
+      ...(zai ? { zai: 1 } : {}),
     },
+    ...(zai ? { zaiCodingPlan: zai.view } : {}),
   };
 }
 
+/** ZAI-CODING-PLAN-PROVIDER — GLM Coding Plan 의 5h·주 창 ⊕ 잔액(extra usage) 사용.
+ *  ⓒ 공식 조회(`/api/monitor/usage/quota/limit`)가 되면 그 값 · 안 되면 ⓐ 우리 적산 ⊕ ⓑ 429 리셋 시각으로 «추정».
+ *  ⛔ 키가 없으면 행을 «안» 만든다. ⛔ 시험 런타임은 seam 이 없으면 «키 없음»(키 캐시는 파일이라 스크럽을 통과한다). */
+async function collectZaiRows(deps: UnifiedUsageDeps): Promise<{ rows: AccountUsageRow[]; view: ZaiUsageView } | null> {
+  // ⛔ 시험 런타임(NODE_ENV=test)은 seam 이 없으면 «env 의 ZAI_API_KEY 만» 본다 — 키 캐시 «파일»은 env 스크럽을 통과해
+  //   seam 을 모르는 옛 usage 시험이 실제 Z.ai 를 치게 되기 때문이다. env 로 키를 주면 test 에서도 행이 선다.
+  const key = (deps.zaiKey ?? (process.env.NODE_ENV === 'test' ? () => process.env.ZAI_API_KEY?.trim() || undefined : () => getZaiApiKey()))();
+  if (!key) return null;
+  const nowMs = (deps.now ?? Date.now)();
+  // ⛔ 조회가 «던져도» usage 전체를 죽이지 않는다 — 실패는 결과값으로 바꿔 추정 표로 간다.
+  const quota: ZaiQuotaResult = await (deps.fetchZaiQuota ?? (() => fetchZaiQuota()))()
+    .catch((error: unknown) => ({ status: 'error' as const, detail: error instanceof Error ? error.message : String(error) }));
+  const view = buildZaiUsageView(quota, (deps.readZaiLedger ?? (() => readZaiLedger()))(), nowMs);
+  const base = { provider: 'zai' as const, accountCount: 1, soleAccount: true, resetCredits: { status: 'not-applicable' } as const };
+  const sourceLabel = { official: '공식', next_flush_time: 'next_flush_time', estimated: '추정' } as const;
+  const rows: AccountUsageRow[] = view.windows.map((w) => {
+    const windowMs = w.window === '5h' ? 5 * 3_600_000 : 7 * 86_400_000;
+    const usedPercent = w.limit > 0 ? Math.round((w.used / w.limit) * 1000) / 10 : null;
+    const end = w.resetAt !== null && isValidEpochMs(w.resetAt) ? new Date(w.resetAt) : null;
+    const kind: WindowKind = w.window === '5h' ? 'session' : 'weekly';
+    return {
+      ...base,
+      accountName: w.window === '5h' ? 'plan-5h' : 'plan-week',
+      credits: {
+        status: 'ok',
+        usedPercent,
+        periodType: kind,
+        periodStart: end ? new Date(end.getTime() - windowMs).toISOString() : null,
+        periodEnd: end?.toISOString() ?? null,
+        monthlyLimit: null,
+        used: w.used,
+        onDemandCap: null,
+        onDemandUsed: null,
+        prepaidBalance: null,
+        balance: null,
+        hasCredits: null,
+        unlimited: false,
+      },
+      // 리셋 시각을 모르면 «available» 로 NaN 을 흘리지 않는다.
+      subscription: usedPercent === null || !end
+        ? { status: 'unavailable', reason: 'query-does-not-supply' }
+        : { status: 'available', remainingPercent: Math.round((100 - usedPercent) * 10) / 10, resetsAt: end.getTime(), windowKind: kind },
+      // ⓐ 우리 적산을 공식 값 옆에 같이 둔다 — 공식은 정수 크레딧으로 내려 작은 호출이 0 으로 보인다(10-11 실측).
+      note: `${w.used}/${w.limit} 크레딧 · 출처=${sourceLabel[w.source]}${w.resetAt === null ? ' · 리셋 시각 모름' : ''}`
+        + (w.source === 'official' ? ` · elanous 적산 ${w.window === '5h' ? view.local.fiveHour.used : view.local.weekly.used}` : ''),
+    };
+  });
+  rows.push({
+    ...base,
+    accountName: 'extra-usage',
+    credits: {
+      status: 'ok', usedPercent: null, periodType: 'extra-usage', periodStart: null, periodEnd: null,
+      monthlyLimit: null, used: view.balanceCredits, onDemandCap: null, onDemandUsed: null,
+      prepaidBalance: null, balance: null, hasCredits: null, unlimited: false,
+    },
+    subscription: { status: 'unavailable', reason: 'not-a-subscription' },
+    note: `잔액 사용 ${view.balanceCredits} 크레딧(추정 · 최근 7일)${view.lastLimit ? ` · 마지막 한도 코드 ${view.lastLimit.code}` : ''}`,
+  });
+  return { rows, view };
+}
+
 async function collectCodexRows(deps: UnifiedUsageDeps): Promise<AccountUsageRow[]> {
   const listed = (deps.listCodexAccounts ?? listCodexAccountsInStore)();
   const accounts = listed;
@@ -138,7 +212,11 @@ async function collectGrokRows(deps: UnifiedUsageDeps): Promise<AccountUsageRow[
     resetCredits: { status: 'not-applicable' } as const,
   };
   if (result.status === 'ok') {
-    return [{ ...base, credits: grokUsageToCreditAxis(result.usage) }];
+    return [{
+      ...base,
+      subscription: grokUsageToSubscriptionAxis(result.usage),
+      credits: grokUsageToCreditAxis(result.usage),
+    }];
   }
   if (result.status === 'no-subscription') {
     return [{ ...base, credits: { status: 'no-subscription' } }];
@@ -284,7 +362,7 @@ export function formatUsageCompact(report: UnifiedUsageReport, options: { width:
     const reset = subscription.status === 'available' ? subscription.resetsAt
       : credits.status === 'ok' && credits.periodEnd ? Date.parse(credits.periodEnd) : Number.NaN;
     const periodLabel = period ? `${formatCompactPeriod(period)} ` : '';
-    const when = period === 'prepaid-usd' ? '' : !isValidEpochMs(reset)
+    const when = period === 'prepaid-usd' || period === 'extra-usage' ? '' : !isValidEpochMs(reset)
       ? ` · ${periodLabel}시각 모름`
       : reset <= options.nowMs
         ? ` · ${periodLabel}재조회 필요`
@@ -351,6 +429,8 @@ export function formatUnifiedUsage(report: UnifiedUsageReport): string {
     const count = report.accountCounts[provider];
     lines.push(`  ${provider}  accounts=${count}${count === 1 ? '  (하나뿐)' : count === 0 ? '  (없음)' : ''}`);
   }
+  // ⛔ 키가 없으면 줄을 안 낸다 — 종전 문면과 바이트 동일.
+  if (report.accountCounts.zai !== undefined) lines.push(`  zai  accounts=${report.accountCounts.zai}  (GLM Coding Plan)`);
   lines.push('  provider    account     accounts  credits.usedPercent  credits.window              window-resets-in       reset-credit-expiry                  subscription');
   for (const row of report.rows) {
     lines.push(formatRow(row));
@@ -364,7 +444,7 @@ function formatRow(row: AccountUsageRow): string {
   const resetsIn = formatWindowResetsIn(row.credits);
   const resetCredits = formatResetCreditExpiryCell(row.resetCredits);
   const subscription = formatSubscriptionCell(row.subscription);
-  return `  ${row.provider.padEnd(10)} ${row.accountName.padEnd(11)} ${String(row.accountCount).padEnd(8)} ${credits.padEnd(20)} ${window.padEnd(26)} ${resetsIn.padEnd(22)} ${resetCredits.padEnd(36)} ${subscription}`;
+  return `  ${row.provider.padEnd(10)} ${row.accountName.padEnd(11)} ${String(row.accountCount).padEnd(8)} ${credits.padEnd(20)} ${window.padEnd(26)} ${resetsIn.padEnd(22)} ${resetCredits.padEnd(36)} ${subscription}${row.note ? `  — ${row.note}` : ''}`;
 }
 
 function formatResetCreditExpiryCell(expiry: ResetCreditExpiryAxis): string {
@@ -381,6 +461,7 @@ function formatResetCreditExpiryCell(expiry: ResetCreditExpiryAxis): string {
 
 function formatCreditsCell(credits: CreditAxis): string {
   if (credits.status !== 'ok') return credits.status;
+  if (credits.periodType === 'extra-usage') return `${credits.used ?? 0} cr`;
   if (credits.usedPercent === null) return 'unknown';
   // 선불 달러 — 퍼센트만으로는 «얼마 남았나»를 못 읽는다.
   if (credits.periodType === 'prepaid-usd' && credits.balance !== null) return `${credits.usedPercent}% ($${credits.balance} left)`;
@@ -390,6 +471,7 @@ function formatCreditsCell(credits: CreditAxis): string {
 function formatCreditsWindow(credits: CreditAxis): string {
   if (credits.status !== 'ok') return '—';
   if (credits.periodType === 'prepaid-usd') return 'prepaid (창 없음)';
+  if (credits.periodType === 'extra-usage') return 'extra-usage (잔액)';
   const type = credits.periodType ?? '—';
   if (credits.periodStart && credits.periodEnd) {
     return `${type} ${credits.periodStart.slice(0, 10)}~${credits.periodEnd.slice(0, 10)}`;
@@ -407,7 +489,7 @@ function formatCreditsWindow(credits: CreditAxis): string {
  */
 export function formatWindowResetsIn(credits: CreditAxis, nowMs: number = Date.now()): string {
   if (credits.status !== 'ok') return '—';
-  if (credits.periodType === 'prepaid-usd') return 'n/a (리셋 없음)';
+  if (credits.periodType === 'prepaid-usd' || credits.periodType === 'extra-usage') return 'n/a (리셋 없음)';
   const end = credits.periodEnd ? Date.parse(credits.periodEnd) : Number.NaN;
   if (!Number.isFinite(end)) return 'unknown';
   const remainMs = end - nowMs;

package/src/chat/index.ts

@@ -55,7 +55,8 @@ export interface CursorSink {
  *  tests can inject a fake. */
 export interface ModalSink {
   pushModal(surface: ModalSurface): { id: string; dispose: () => void };
-  /** F-E2 — force the coordinator to repaint the modal overlay. Chat
+  /** F-E2 — ask the coordinator to repaint the modal overlay (a plain
+   *  dirty frame — NOT force; see TUI-SLASH-FLICKER). Chat
    *  calls this after every keystroke so the picker's paint closure
    *  re-evaluates `getFiltered()` / `getItems()` — without it, the
    *  picker handle stays mounted but its filter output doesn't flow
@@ -345,11 +346,19 @@ export function createTextInputRenderActions(opts: {
     if (opts.shouldRequestModalRender?.() === false) return;
     if (debug.enabled) {
       debug.log('chat.modal.requestRender', 'user-mutation', {
-        force: true,
+        force: false,
         painted,
       });
     }
-    opts.modalSink?.requestRender?.({ force: true });
+    // TUI-SLASH-FLICKER (2026-10-09) — ⛔ NOT `force: true`. A forced
+    // frame reaches tui.ts::render as `\x1b[1;1H\x1b[J` + every row, so
+    // each keystroke / ↑↓ in the picker erased and repainted the WHOLE
+    // screen (visible flicker). The picker surfaces carry no paint-cache
+    // `generation`, so a plain dirty frame already re-runs their paint
+    // closure and the dashboard frame re-emits the overlay every flush;
+    // rows the picker vacates are invalidated by the coordinator's
+    // region tracking. Regression: src/ux-sim/slash-menu-frames.test.ts.
+    opts.modalSink?.requestRender?.();
   };
   return { repaintHost, repaintUserMutation };
 }

package/src/cli/agent-cli.ts

@@ -668,6 +668,26 @@ export function buildCliAgentTools(
   const shared = (require('../agent/shared-app-tools.js') as typeof import('../agent/shared-app-tools.js')).buildSharedAppTools(cfg);
   for (const s of shared.specs) specs.push(s);
   for (const name of shared.names) dispatchByName.set(name, async (args) => shared.dispatch(name, args));
+  // Installed knowledge is queryable in CLI chat as well as the dashboard runtime.
+  // No installed packs => preserve the existing CLI tool list and avoid creating a KGS database.
+  const { kgsDefaultDbPath } = require('../knowledge/kgs/sqlite-store.js') as typeof import('../knowledge/kgs/sqlite-store.js');
+  const { existsSync } = require('node:fs') as typeof import('node:fs');
+  let hasInstalledPacks = false;
+  try {
+    if (existsSync(kgsDefaultDbPath())) {
+      const { listInstalledPacks } = require('../knowledge/query.js') as typeof import('../knowledge/query.js');
+      hasInstalledPacks = listInstalledPacks().length > 0;
+    }
+  } catch (err) {
+    // An unreadable/corrupt KGS store must not break chat tool assembly for turns that never query knowledge.
+    debug.log('cli.agent', 'knowledge-query.tool-skipped', { reason: err instanceof Error ? err.message : String(err) });
+  }
+  if (hasInstalledPacks) {
+    const { buildKnowledgeQueryTool, dispatchKnowledgeQuery } = require('../knowledge/tools/knowledge-query.js') as typeof import('../knowledge/tools/knowledge-query.js');
+    const knowledgeSpec = buildKnowledgeQueryTool();
+    specs.push(knowledgeSpec);
+    dispatchByName.set(knowledgeSpec.name, async (args) => dispatchKnowledgeQuery(args));
+  }
   if (harnessPlan) {
     specs.push(buildPlanTool(), buildMarkStepDoneTool());
     const planCtx = {

package/src/cli/bench-cli.ts

@@ -0,0 +1,34 @@
+/** BENCH-ISOLATED-ARMS ④ — `elanous bench ls <id>`: 벤치 원장(`<config dir>/bench/<id>.jsonl`)을 읽는 한 자리. */
+import type { Command } from 'commander';
+import { benchLedgerPath, parseBenchSpec, readBenchLedger, renderBenchLs } from '../bench/bench.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export interface BenchCliDeps {
+  readonly configDir?: () => string;
+  readonly write?: (line: string) => void;
+}
+
+export function registerBenchCommands(program: Command, deps: BenchCliDeps = {}): Command {
+  const bench = program.command('bench').description('벤치 팔(같은 골 · 모델만 다른 발사) 원장 — harness ask/say --bench 가 쓴다');
+  bench.command('ls <id>')
+    .description('벤치 원장 줄(bench id · base sha · 이미지 pin · 자식 모델 · 라운드)을 읽는다')
+    .option('--json', 'JSON 배열로')
+    .action((id: string, opts: { json?: boolean }) => {
+      const write = deps.write ?? ((line: string) => console.log(line));
+      let benchId: string;
+      try { benchId = parseBenchSpec(id).id; }
+      catch (error) {
+        console.error(`❌ ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 2;
+        return;
+      }
+      const configDir = (deps.configDir ?? getElanousConfigDir)();
+      const rows = readBenchLedger(benchId, configDir);
+      if (opts.json) write(JSON.stringify(rows));
+      else {
+        write(renderBenchLs(benchId, rows));
+        if (rows.length === 0) write(`원장 경로: ${benchLedgerPath(benchId, configDir)}`);
+      }
+    });
+  return bench;
+}

package/src/cli/brief-cli.ts

@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import { BRIEF_DOMAINS, BRIEF_PRIORITIES, BRIEF_REACTIONS, BRIEF_SLOTS, BriefItemsInputError, BriefItemsLedger, type BriefDomain, type BriefPriority, type BriefReaction, type BriefSlot } from '../briefing/brief-items.js';
+import { BRIEF_DOMAINS, BRIEF_PRIORITIES, BRIEF_REACTIONS, BRIEF_SLOTS, BriefItemsInputError, BriefItemsLedger, type BriefDomain, type BriefPriority, type BriefReaction, type BriefSendSlot } from '../briefing/brief-items.js';
 import { kindRouteTarget } from '../domains/telegram-kind-route.js';
 import { sendTelegramReturningId } from '../autopilot/mission-notify.js';
 import { getUserConfig } from '../user-config.js';
@@ -31,6 +31,20 @@ export function registerBriefCommands(program: Command, deps: BriefCliDeps = {})
         output(`이번 주 브리핑 중 대표가 움직인 것 ${acted}/${total}`);
       } catch (cause) { fail('', cause); }
     });
+  const deliver = (slot: BriefSendSlot): string => ledger().withSendLock(slot, ({ markdown, ids }, markSent) => {
+    if (ids.length === 0) return '(보낼 항목 없음)';
+    const send = deps.send ?? ((text: string) => {
+      const target = kindRouteTarget(getUserConfig(), 'ops-report');
+      if (!target) return null;
+      return sendTelegramReturningId(target.botToken, target.chatId, text);
+    });
+    const messageId = send(markdown);
+    if (typeof messageId !== 'number' || !Number.isFinite(messageId) || messageId <= 0) {
+      throw new Error('발송 실패: 양수 메시지 id 없음');
+    }
+    markSent(ids, slot);
+    return `sent ${messageId} (${ids.length} items)`;
+  });
 
   brief.command('add')
     .description('주장 한 줄을 원장에 추가한다 (원문 그대로)')
@@ -41,9 +55,11 @@ export function registerBriefCommands(program: Command, deps: BriefCliDeps = {})
     .option('--deadline <deadline>', '마감 (YYYY-MM-DD 또는 ISO)')
     .option('--evidence <evidence>', '근거 링크')
     .option('--created-at <iso>', '작성 시각 (ISO, 생략 시 지금)')
+    .option('--send-now', 'P0 추가 직후 실시간 발송')
     .option('--json', 'JSON 출력')
-    .action((opts: { text: string; domain: string; priority: string; source: string; deadline?: string; evidence?: string; createdAt?: string; json?: boolean }) => {
+    .action((opts: { text: string; domain: string; priority: string; source: string; deadline?: string; evidence?: string; createdAt?: string; sendNow?: boolean; json?: boolean }) => {
       try {
+        if (opts.sendNow && opts.priority !== 'P0') throw new BriefItemsInputError('--send-now requires --priority P0');
         const item = ledger().add({
           text: opts.text,
           domain: opts.domain as BriefDomain,
@@ -54,6 +70,7 @@ export function registerBriefCommands(program: Command, deps: BriefCliDeps = {})
           ...(opts.createdAt !== undefined ? { createdAt: opts.createdAt } : {}),
         });
         output(opts.json ? JSON.stringify(item) : `added ${item.id} [${item.priority}] ${item.domain}`);
+        if (opts.sendNow) output(deliver('realtime'));
       } catch (cause) { fail('add', cause); }
     });
 
@@ -95,31 +112,20 @@ export function registerBriefCommands(program: Command, deps: BriefCliDeps = {})
 
   brief.command('send')
     .description('슬롯 이전의 미발송 항목을 한 장 발송하고 성공한 항목만 표시한다')
-    .requiredOption('--slot <slot>', `슬롯 (${BRIEF_SLOTS.join('|')})`)
+    .option('--slot <slot>', `슬롯 (${BRIEF_SLOTS.join('|')}, --realtime 시 불필요)`)
+    .option('--realtime', '미발송 P0 및 오늘 마감 항목을 즉시 한 장 발송한다')
     .option('--dry-run', '한 장만 출력하고 발송·표시하지 않는다')
-    .action((opts: { slot: string; dryRun?: boolean }) => {
+    .action((opts: { slot?: string; realtime?: boolean; dryRun?: boolean }) => {
       try {
-        const store = ledger();
+        if (opts.realtime && opts.slot !== undefined) throw new BriefItemsInputError('--realtime cannot be combined with --slot');
+        if (!opts.realtime && opts.slot === undefined) throw new BriefItemsInputError('--slot is required unless --realtime');
+        const slot = opts.realtime ? 'realtime' : opts.slot!;
         if (opts.dryRun) {
-          const { markdown, ids } = store.composeWithIds(opts.slot);
+          const { markdown, ids } = ledger().composeWithIds(slot);
           output(ids.length === 0 ? '(보낼 항목 없음)' : markdown);
           return;
         }
-        const result = store.withSendLock(opts.slot, ({ markdown, ids }, markSent) => {
-          if (ids.length === 0) return '(보낼 항목 없음)';
-          const send = deps.send ?? ((text: string) => {
-            const target = kindRouteTarget(getUserConfig(), 'ops-report');
-            if (!target) return null;
-            return sendTelegramReturningId(target.botToken, target.chatId, text);
-          });
-          const messageId = send(markdown);
-          if (typeof messageId !== 'number' || !Number.isFinite(messageId) || messageId <= 0) {
-            throw new Error('발송 실패: 양수 메시지 id 없음');
-          }
-          markSent(ids, opts.slot as BriefSlot);
-          return `sent ${messageId} (${ids.length} items)`;
-        });
-        output(result);
+        output(deliver(slot as BriefSendSlot));
       } catch (cause) { fail('send', cause); }
     });
 }

package/src/cli/cli-user-error.ts

@@ -1,5 +1,3 @@
-import { HarnessCliInputError } from '../harness/harness-cli-command.js';
-
 const cliUserErrorBrand = Symbol.for('elanous.cli.CliUserError');
 const harnessCliInputErrorBrand = Symbol.for('elanous.cli.HarnessCliInputError');
 
@@ -11,6 +9,15 @@ export class CliUserError extends Error {
   }
 }
 
+/** A command-line value was rejected before any harness work began. */
+export class HarnessCliInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HarnessCliInputError';
+    Object.defineProperty(this, harnessCliInputErrorBrand, { value: true });
+  }
+}
+
 export function isCliUserError(err: unknown): err is Error & { hint?: string } {
   return err instanceof HarnessCliInputError || err instanceof CliUserError || (
     err instanceof Error && (

package/src/cli/guardian-cli.ts

@@ -27,7 +27,32 @@ export function registerGuardianCommands(program: Command): void {
         const cfg = getUserConfig();
         // Live activation (and crontab retirement) is a separate operational change.
         if (cfg.guardian?.mode === 'live') throw new Error('guardian live activation is outside GUARD-ONE-a');
-        const result = await guardianTick(new Date(), plan, { config: cfg });
+        // The shadow observation is for the tick's entry time, however long the GC's evidence collection takes.
+        const tickAt = new Date();
+        // Local orphan GC is separate from the guardian's shadow-only schedule execution.
+        const orphanGc = cfg.guardian?.orphanGc ?? 'shadow';
+        try {
+          // off never loads the collector, so no ps snapshot is taken.
+          if (orphanGc !== 'off') {
+            // Loading the collector is inside the guard too: a GC that cannot even load only observes.
+            const { runMachineHeartbeat } = await import('../ops/machine-heartbeat.js');
+            await runMachineHeartbeat(plan.jobs.filter((job): job is typeof job & { command: string; cron: string } =>
+              job.source === 'crontab' && job.run_via === 'crontab' && !!job.enabled
+              && typeof job.command === 'string' && typeof job.cron === 'string')
+              .map(job => ({ command: job.command, cron: job.cron })), { timeZone: plan.timeZone, mode: orphanGc });
+          } else {
+            // Still one decision line per tick, so «switched off» is distinguishable from «tick never ran».
+            const { debug } = await import('../debug/log.js');
+            debug.log('ops.orphan-cli', 'decision', { mode: 'off', candidates: 0, collected: 0, alreadyEvidenced: 0, killed: 0 });
+          }
+        } catch (error) {
+          // The logger import is inside the guard as well: if it is the failing module, the shadow tick still runs.
+          try {
+            const { debug } = await import('../debug/log.js');
+            debug.log('ops.orphan-cli', 'observation-failed', { error: String(error) });
+          } catch { /* guardian shadow still runs */ }
+        }
+        const result = await guardianTick(tickAt, plan, { config: cfg });
         await writeStdoutJson(JSON.stringify(result, null, 2) + '\n');
       } finally { db.close(); }
     });

package/src/cli/image-cli.ts

@@ -0,0 +1,101 @@
+import type { Command } from 'commander';
+import { debug } from '../debug/log.js';
+import {
+  appendImageLedgerEvent, baselinePinEvent, foldImageLedger, imageLedgerPath, readImageLedger, readRegistryTags,
+  type ImageLedgerRow, type RegistryRead,
+} from '../images/image-ledger.js';
+import { isPodImageCommit, podImageRegistry } from '../task-orchestrator/surfaces/pod-image-source.js';
+
+const SSH_HOST = /^[A-Za-z0-9][A-Za-z0-9._@-]*$/u;
+
+export interface ImageLsDeps {
+  readonly ledgerPath?: string;
+  readonly readRegistry?: (opts: { port: string; sshHost?: string }) => RegistryRead;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly out?: (line: string) => void;
+}
+
+export interface ImageLsResult {
+  readonly ledger: { readonly path: string; readonly exists: boolean; readonly events: number; readonly unreadableLines: number };
+  readonly registry: { readonly read: boolean; readonly where: string; readonly tags: number | null; readonly reason?: string };
+  readonly rows: readonly ImageLedgerRow[];
+  readonly counts: { readonly baseline: number; readonly transient: number | null; readonly ledgered: number };
+}
+
+/** `image ls` — read only: ledger rows ⊕ registry tags without a ledger row (= transient). */
+export function imageLs(opts: { json?: boolean; ssh?: string; registry?: boolean }, deps: ImageLsDeps = {}): ImageLsResult {
+  const out = deps.out ?? ((line: string) => console.log(line));
+  if (opts.ssh !== undefined && !SSH_HOST.test(opts.ssh)) throw new Error(`invalid --ssh host: ${opts.ssh}`);
+  const ledger = readImageLedger(deps.ledgerPath ?? imageLedgerPath());
+  const registryAddr = podImageRegistry(deps.env ?? process.env);
+  const port = registryAddr.slice(registryAddr.lastIndexOf(':') + 1);
+  const where = `${opts.ssh ?? 'this machine'} localhost:${port}`;
+  let registry: RegistryRead | null = null;
+  if (opts.registry !== false) {
+    registry = /^[1-9][0-9]{0,4}$/u.test(port) && Number(port) <= 65535
+      ? (deps.readRegistry ?? readRegistryTags)({ port, ...(opts.ssh ? { sshHost: opts.ssh } : {}) })
+      : { ok: false, reason: `invalid registry port: ${registryAddr}` };
+  }
+  const tags = registry?.ok ? registry.tags : null;
+  const rows = foldImageLedger(ledger.events, tags);
+  const result: ImageLsResult = {
+    ledger: { path: ledger.path, exists: ledger.exists, events: ledger.events.length, unreadableLines: ledger.unreadableLines },
+    registry: registry === null
+      ? { read: false, where, tags: null, reason: 'skipped (--no-registry)' }
+      : registry.ok ? { read: true, where, tags: registry.tags.length } : { read: false, where, tags: null, reason: registry.reason },
+    rows,
+    counts: {
+      baseline: rows.filter((r) => r.current).length,
+      transient: tags === null ? null : rows.filter((r) => r.unledgered).length,
+      ledgered: rows.filter((r) => !r.unledgered).length,
+    },
+  };
+  try { debug.log('image.ledger', 'ls', { ledgerEvents: result.ledger.events, unreadableLines: result.ledger.unreadableLines, registryRead: result.registry.read, registryTags: result.registry.tags, transient: result.counts.transient }); } catch { /* log sink optional */ }
+  if (opts.json) { out(JSON.stringify(result, null, 2)); return result; }
+  out(`image ledger · ${ledger.path}${ledger.exists ? '' : ' (no ledger yet)'} · events ${ledger.events.length}${ledger.unreadableLines ? ` · ⚠️ unreadable lines ${ledger.unreadableLines}` : ''}`);
+  out(result.registry.read
+    ? `registry · ${where} · tags ${result.registry.tags}`
+    : `registry · ${where} · ⚠️ not read — ${result.registry.reason} (transient count unknown, not 0)`);
+  for (const r of rows.filter((x) => !x.unledgered)) {
+    const reg = r.inRegistry === null ? '?' : r.inRegistry ? 'reg' : '⚠️ not-in-registry';
+    out(`  ${r.tag}  ${r.role}${r.role === 'baseline' ? (r.current ? '*' : ' (previous)') : ''}  keep=${r.keep}  ${r.origin ? `${r.origin.reason}@${r.origin.host}` : '-'}  ${r.lastTs}  ${reg}`);
+  }
+  const transient = rows.filter((x) => x.unledgered);
+  if (transient.length > 0) out(`  transient (registry tags without a ledger row) · ${transient.length} · ${transient.slice(0, 8).map((r) => r.tag).join(' ')}${transient.length > 8 ? ' …' : ''}`);
+  out(`baseline ${result.counts.baseline} · ledgered ${result.counts.ledgered} · transient ${result.counts.transient ?? 'unknown'}`);
+  return result;
+}
+
+/**
+ * Recording site: `config set harness.imageCommit <commit>` (the rail pins the baseline through it).
+ * Appends a `baseline ⊕ pin` event (none when that tag is already the current baseline). A failed ledger write never fails the config write; it warns
+ * and leaves an observation.
+ */
+export function recordImagePinFromConfigSet(path: string, value: unknown, deps: { ledgerPath?: string; warn?: (msg: string) => void; now?: () => Date; host?: string } = {}): 'recorded' | 'unchanged' | 'skipped' | 'failed' {
+  if (path !== 'harness.imageCommit' || !isPodImageCommit(value)) return 'skipped';
+  const ledgerPath = deps.ledgerPath ?? imageLedgerPath();
+  try {
+    // The rail re-pins the same commit on quiet cycles — one event per baseline change, not per call.
+    const current = foldImageLedger(readImageLedger(ledgerPath).events, null).find((r) => r.current);
+    if (current && current.tag === value.trim().toLowerCase().slice(0, 12)) return 'unchanged';
+    const event = baselinePinEvent(value, { ...(deps.now ? { now: deps.now } : {}), ...(deps.host ? { host: deps.host } : {}) });
+    appendImageLedgerEvent(event, ledgerPath);
+    try { debug.log('image.ledger', 'baseline-pinned', { tag: event.tag, commit: event.commit, reason: event.origin.reason, host: event.origin.host, ledgerPath }); } catch { /* */ }
+    return 'recorded';
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    try { debug.log('image.ledger', 'baseline-pin-record-failed', { error: message, ledgerPath }); } catch { /* */ }
+    (deps.warn ?? ((m: string) => console.error(m)))(`⚠️ image ledger: baseline pin was set in config but not recorded in ${ledgerPath} — ${message}`);
+    return 'failed';
+  }
+}
+
+export function registerImageCommands(program: Command): void {
+  const image = program.command('image').description('하니스 이미지 원장 — 신분 표지(역할·보존·출신) · 원장 없는 레지스트리 태그 = transient');
+  image.command('ls')
+    .description('원장 행 ⊕ 레지스트리 태그(원장에 없으면 transient) — 읽기 전용')
+    .option('--json', 'JSON 출력')
+    .option('--ssh <host>', '레지스트리가 있는 노드(그 노드의 localhost 포트로 조회)')
+    .option('--no-registry', '레지스트리를 읽지 않는다(원장만)')
+    .action((opts: { json?: boolean; ssh?: string; registry?: boolean }) => { imageLs(opts); });
+}

package/src/cli/log-event-names.ts

@@ -121,7 +121,9 @@ export const KNOWN_LOG_EVENT_NAMES: ReadonlySet<string> = new Set([
   "background-drain",
   "background-finish",
   "barge.in",
+  "base-ensured",
   "base-preexisting",
+  "base-refused",
   "base-selection",
   "base.default-branch",
   "base.remote-unreachable",
@@ -703,6 +705,9 @@ export const KNOWN_LOG_EVENT_NAMES: ReadonlySet<string> = new Set([
   "install-start",
   "installed",
   "instantiated",
+  "intent-stall-exhausted",
+  "intent-stall-provider-unresolved",
+  "intent-stall-reprompt",
   "interceptor",
   "interrupt",
   "interview-round-classified",
@@ -733,6 +738,7 @@ export const KNOWN_LOG_EVENT_NAMES: ReadonlySet<string> = new Set([
   "launch-overrides",
   "layered-load",
   "ledger",
+  "ledger-unwritten",
   "ledger-write-failed",
   "legacy-codex-invoked",
   "legacy-finalize",
@@ -770,6 +776,7 @@ export const KNOWN_LOG_EVENT_NAMES: ReadonlySet<string> = new Set([
   "luna-failed",
   "luna-no-allowlist",
   "made-public",
+  "main-sync-skipped",
   "main-tree-reject",
   "malformed-tail",
   "manifest-frame-fail",

package/src/cli/logs-cli.ts

@@ -36,6 +36,7 @@ import { LOG_LEVEL_ORDER, type LogLevel } from '../mss/logging/record.js';
 import { isRenderCategory, RENDER_ORIENTED_PREFIXES } from '../mss/logging/render-categories.js';
 import { readScopedRenderLogs } from '../mss/logging/scoped-level.js';
 import { formatClock } from '../time/format.js';
+import '../user-config.js'; // Register the saved timezone for standalone logs CLI formatting.
 import { HARNESS_SPACE_KINDS } from '../harness/harness-space.js';
 import { LOG_RETENTION_DEFAULTS, LogCursorNotFoundError, STORE_SAFETY_MAX } from '../mss/logging/log-store.js';
 import { resolveDaemonEndpoint } from '../nexus/daemon-endpoint.js';