elanous 0.2.25 → 0.2.28

package/scripts/verify-kpack6-live.ts

@@ -0,0 +1,230 @@
+// KPACK6 — 선택 실행 운영 스모크 (읽기 전용)
+//
+// #25780 으로 두 공개 표본 팩의 서명 설치·CLI KnowledgeQuery·그래프 검색 인용은 착지했다.
+// 이 스크립트는 그 다음 칸이다: 설치된 두 팩에 대해 실제 CLI 채팅 LLM 답변이
+// 팩 출처(`slug@version#cardId`)를 인용하는지 확인한다.
+//
+//   팩 미설치 / LLM 호출 불가 / 스토어 오류  → 미측정 (실패 아님)
+//   답변은 왔으나 팩 출처 인용 없음          → 실패
+//   두 팩 모두 인용 답변 실물 확보 전까지    → green 금지
+//
+// 실행: KPACK6_LIVE=1 bun scripts/verify-kpack6-live.ts
+// CLI 명령은 KPACK6_AGENT_CMD 로 바꿀 수 있다(기본 `bun bin/elanous.mjs agent --new --json`).
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { listInstalledPacks, queryInstalledPack } from '../src/knowledge/query.js';
+
+export const KPACK6_TARGET_SLUGS = ['semiconductor-process-public', 'b2b-sales-public'] as const;
+
+export type Kpack6PackStatus =
+  | 'pack-not-installed'
+  | 'pack-unreadable'
+  | 'llm-unavailable'
+  | 'llm-timeout'
+  | 'cli-contract-error'
+  | 'citation-missing'
+  | 'cited';
+
+export type Kpack6PackResult = {
+  slug: string;
+  packId: string | null;
+  status: Kpack6PackStatus;
+  measured: boolean;
+  question?: string;
+  reply?: string;
+  ref?: string;
+  reason?: string;
+};
+
+export type Kpack6SmokeStatus = 'green' | 'fail' | 'not-measured' | 'skipped';
+
+export type Kpack6SmokeReport = {
+  status: Kpack6SmokeStatus;
+  reason?: string;
+  packs: Kpack6PackResult[];
+  generatedAt: string;
+};
+
+export type Kpack6Deps = {
+  installedPacks?: () => Array<{ id: string; title: string }>;
+  queryTopCard?: (packId: string) => { id: string; title: string; ref: string };
+  ask?: (question: string) => Promise<{ reply: string }>;
+  env?: Record<string, string | undefined>;
+};
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** 설치된 팩에서 조회한 바로 그 카드의 ref만 인용으로 인정한다. */
+export function packCitationIn(reply: string, expectedRef: string): string | null {
+  const exactRef = new RegExp(`(?<![\\w./@#-])${escapeRegExp(expectedRef)}(?=$|[^\\w./@#-])`);
+  return exactRef.test(reply) ? expectedRef : null;
+}
+
+function defaultQueryTopCard(packId: string): { id: string; title: string; ref: string } {
+  const hits = queryInstalledPack(packId, '');
+  if (hits.length === 0) throw new Error(`팩에 카드가 없다: ${packId}`);
+  return { id: hits[0].id, title: hits[0].title, ref: hits[0].ref };
+}
+
+export class Kpack6CliContractError extends Error {}
+export class Kpack6LlmTimeoutError extends Error {}
+
+function isProviderUnavailable(stderr: string): boolean {
+  return /No LLM provider available|usage_limit_reached|(?:^|\W)429(?:\W|$)/i.test(stderr);
+}
+
+export async function askViaCli(question: string, env: Record<string, string | undefined>): Promise<{ reply: string }> {
+  const argv = (env.KPACK6_AGENT_CMD ?? 'bun bin/elanous.mjs agent --new --json').split(/\s+/);
+  const timeoutMs = Number(env.KPACK6_TIMEOUT_MS ?? 180_000);
+  return await new Promise((resolve, reject) => {
+    const child = spawn(argv[0], [...argv.slice(1), question], {
+      cwd: REPO_ROOT, env: { ...process.env, ...env }, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(new Kpack6CliContractError(`agent CLI 실행 실패 — ${err.message}`));
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(new Kpack6LlmTimeoutError(`agent CLI LLM 응답 시간 초과 (${timeoutMs}ms)`));
+        return;
+      }
+      const jsonLine = stdout.split('\n').filter((line) => line.trim().startsWith('{')).pop();
+      if (code !== 0) {
+        const message = `agent CLI exit=${code} stderr=${stderr.slice(0, 300)}`;
+        reject(isProviderUnavailable(stderr) ? new Error(message) : new Kpack6CliContractError(message));
+        return;
+      }
+      if (!jsonLine) {
+        reject(new Kpack6CliContractError('agent CLI 성공 출력에 JSON 객체가 없다'));
+        return;
+      }
+      try {
+        const parsed = JSON.parse(jsonLine) as { reply?: unknown };
+        if (typeof parsed.reply !== 'string' || parsed.reply.trim() === '') {
+          reject(new Kpack6CliContractError('agent CLI 응답에 reply 문자열이 없다'));
+          return;
+        }
+        resolve({ reply: parsed.reply });
+      } catch (err) {
+        reject(err instanceof Kpack6CliContractError
+          ? err : new Kpack6CliContractError(`agent CLI 출력 JSON 파싱 실패 — ${(err as Error).message}`));
+      }
+    });
+  });
+}
+
+export function kpack6ExitCode(report: Kpack6SmokeReport): number {
+  switch (report.status) {
+    case 'green': return 0;
+    case 'fail': return 1;
+    case 'skipped': return 3;
+    default: return 4;
+  }
+}
+
+export async function runKpack6LiveSmoke(deps: Kpack6Deps = {}): Promise<Kpack6SmokeReport> {
+  const env = deps.env ?? process.env;
+  const generatedAt = new Date().toISOString();
+
+  if (env.KPACK6_LIVE !== '1') {
+    return {
+      status: 'skipped',
+      reason: '선택 실행 스모크다: KPACK6_LIVE=1 없이는 돌지 않는다 (두 팩 인용 답변 실물 1회 전까지 green 금지)',
+      packs: [],
+      generatedAt,
+    };
+  }
+
+  const ask = deps.ask ?? ((question: string) => askViaCli(question, env));
+  let installed: Array<{ id: string; title: string }>;
+  try {
+    installed = deps.installedPacks?.() ?? listInstalledPacks();
+  } catch (err) {
+    return {
+      status: 'not-measured',
+      reason: `KGS 스토어 조회 불가 — ${(err as Error).message}`,
+      packs: KPACK6_TARGET_SLUGS.map((slug) => ({
+        slug, packId: null, status: 'pack-unreadable' as const, measured: false,
+        reason: `스토어 오류: ${(err as Error).message}`,
+      })),
+      generatedAt,
+    };
+  }
+
+  const packs: Kpack6PackResult[] = [];
+  for (const slug of KPACK6_TARGET_SLUGS) {
+    const match = installed.find((pack) => pack.id === slug || pack.id.startsWith(`${slug}@`));
+    if (!match) {
+      packs.push({
+        slug, packId: null, status: 'pack-not-installed', measured: false,
+        reason: 'KGS 스토어에 설치된 팩이 없다 (미측정)',
+      });
+      continue;
+    }
+    const packId = match.id;
+
+    let top: { id: string; title: string; ref: string };
+    try {
+      top = deps.queryTopCard?.(packId) ?? defaultQueryTopCard(packId);
+    } catch (err) {
+      packs.push({
+        slug, packId, status: 'pack-unreadable', measured: false,
+        reason: `설치됐으나 카드 조회 불가 — ${(err as Error).message}`,
+      });
+      continue;
+    }
+
+    const question = `설치된 ${packId} (${match.title}) 팩의 «${top.title}» 카드를 지식 조회 도구로 읽고 요약하라. 답변에 카드 제목을 쓰고, 도구가 반환한 출처를 그대로 인용해 붙여라. 출처를 추측하지 마라.`;
+    let reply: string;
+    try {
+      reply = (await ask(question)).reply;
+    } catch (err) {
+      const contractError = err instanceof Kpack6CliContractError;
+      const timeoutError = err instanceof Kpack6LlmTimeoutError;
+      packs.push({
+        slug, packId, status: contractError ? 'cli-contract-error' : timeoutError ? 'llm-timeout' : 'llm-unavailable',
+        measured: false, question,
+        reason: `${contractError ? 'CLI JSON 계약 오류' : timeoutError ? 'LLM 응답 시간 초과' : 'CLI 채팅 LLM 호출 불가'} — ${(err as Error).message}`,
+      });
+      continue;
+    }
+
+    const ref = packCitationIn(reply, top.ref);
+    if (ref && reply.includes(top.title)) {
+      packs.push({ slug, packId, status: 'cited', measured: true, question, reply, ref });
+    } else {
+      packs.push({
+        slug, packId, status: 'citation-missing', measured: true, question, reply,
+        reason: '답변은 왔으나 조회한 설치 카드의 제목과 정확한 출처 인용이 함께 없다 — 실패',
+      });
+    }
+  }
+
+  const failed = packs.some((pack) => pack.status === 'citation-missing' || pack.status === 'cli-contract-error');
+  const allCited = packs.length > 0 && packs.every((pack) => pack.status === 'cited');
+  const status: Kpack6SmokeStatus = failed ? 'fail' : allCited ? 'green' : 'not-measured';
+  return { status, packs, generatedAt };
+}
+
+if (import.meta.main) {
+  const report = await runKpack6LiveSmoke();
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(kpack6ExitCode(report));
+}

package/src/acp/codex-plugins.ts

@@ -43,6 +43,23 @@ export interface FetchCodexPluginsOpts {
   noCache?: boolean;
 }
 
+/** Read the full inventory for an explicit package import. Unlike the chip projector, this keeps
+ *  the package location and never substitutes a stale cached inventory after an RPC failure. */
+export async function readCodexPluginList(
+  spawn: typeof spawnCodexAppServer = spawnCodexAppServer,
+): Promise<unknown> {
+  const server = spawn({ requestTimeoutMs: 5000 });
+  try {
+    await server.client.request('initialize', {
+      clientInfo: { name: 'elanous', version: '0.x' }, capabilities: { experimentalApi: true },
+    });
+    return await server.client.request<Record<string, never>, unknown>('plugin/list', {});
+  } finally {
+    try { await server.client.close(); }
+    finally { server.child.kill(); }
+  }
+}
+
 /** Uncached inventory probe: distinguish no session / RPC failure from an empty installed list. */
 export async function readCodexPluginsObservation(client: CodexAppServerClient | null | undefined): Promise<
   { status: 'ok'; plugins: ReadonlyArray<CodexPlugin> } | { status: 'unknown'; plugins: readonly [] }

package/src/agent/task-notification.ts

@@ -62,11 +62,39 @@ export class TaskNotificationQueue {
    *  listens to both runner events and a separate `onTaskDone` hook.
    *  Keyed by taskId. */
   private seen = new Set<string>();
+  /** Wake listeners — fired once per REAL enqueue (not on seen-dup).
+   *  TUI-SEAT-READY ③ first shard: one completion event = one wake
+   *  signal so an idle parent can open the next turn. Opening the turn
+   *  itself is deliberately NOT wired here (next shard). */
+  private wakeListeners = new Set<(n: PendingTaskNotification) => void>();
+
+  /** Register a wake listener; returns an unsubscribe function.
+   *  Listeners survive `clear()` — they belong to the wiring, not the
+   *  queue contents. */
+  onEnqueue(listener: (n: PendingTaskNotification) => void): () => void {
+    this.wakeListeners.add(listener);
+    return () => { this.wakeListeners.delete(listener); };
+  }
 
   enqueue(n: PendingTaskNotification): void {
     if (this.seen.has(n.taskId)) return;
     this.seen.add(n.taskId);
     this.queue.push(n);
+    debug.log('agent.task-notification', 'wake', { taskId: n.taskId, size: this.queue.length });
+    for (const listener of this.wakeListeners) {
+      try {
+        listener(n);
+      } catch (error) {
+        // fail-soft — a throwing wake listener must not lose the
+        // queued notification or break sibling listeners.
+        try {
+          debug.log('agent.task-notification', 'wake-listener-failed', {
+            taskId: n.taskId,
+            reason: error instanceof Error ? error.message : String(error),
+          });
+        } catch { /* */ }
+      }
+    }
   }
 
   /** Return all pending notifications AND clear the queue. Parents
@@ -85,7 +113,8 @@ export class TaskNotificationQueue {
     return this.queue.length;
   }
 
-  /** Forget everything — tests use this for isolation. */
+  /** Forget everything — tests use this for isolation. Listeners are
+   *  preserved: clear() empties queue + seen, not the wake wiring. */
   clear(): void {
     this.queue = [];
     this.seen.clear();
@@ -194,7 +223,8 @@ function escapeXml(s: string): string {
   return s
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
 }
 
 function formatDuration(ms: number): string {

package/src/agent-mission/in-agent-plugin.ts

@@ -2,7 +2,8 @@ import type { PtyHandle } from '../pty-shell/registry.js';
 import { classifierFrameLines } from '../capture/frame-state-detect.js';
 import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
 import { debug } from '../debug/log.js';
-import { streamLLM, type LLMMessage } from '../llm.js';
+import * as llm from '../llm.js';
+import { resolveRoleLlm } from '../user-config.js';
 
 export interface PluginRequest { agent: 'codex' | 'claude'; plugin: string; marketplace: string }
 export type PluginResult = { outcome: 'installed' } | { outcome: 'escalate'; reason: 'plugins-disabled' | 'unknown-menu' | 'timeout' | 'wrong-target' | 'credentials' };
@@ -103,11 +104,15 @@ export async function installPluginInsideAgent(request: PluginRequest, pty: Pick
       ? ['[credential screen]']
       : lines(screen).slice(-10).map(line => line.slice(0, 160));
   const brain = deps.brain ?? (async (screen: string, target: string) => {
-    const messages: LLMMessage[] = [
+    const messages: llm.LLMMessage[] = [
       { role: 'system', content: 'You navigate a plugin menu using only up/down/tab/enter/wait/unknown. Return exactly one of those words. Do not choose enter unless the requested plugin@marketplace is visibly selected. Never enter credentials.' },
       { role: 'user', content: `Target: ${target}\nScreen:\n${screen.slice(-3500)}` },
     ];
-    const answer = (await streamLLM(messages, () => {}, { maxTokens: 20 })).trim().toLowerCase();
+    const resolved = resolveRoleLlm('classify');
+    const provider = llm.PROVIDERS[resolved.provider];
+    if (!provider) throw new Error(`Unknown classify provider: ${resolved.provider}`);
+    debug.log('llm.role-pin', 'resolved', { site: 'in-agent-plugin', role: 'classify', model: resolved.model, provider: resolved.provider, source: resolved.source });
+    const answer = (await llm.streamLLM(messages, () => {}, { model: resolved.model, provider, usageRole: 'classify', maxTokens: 20 })).trim().toLowerCase();
     return /^(up|down|tab|enter|wait)$/.test(answer) ? answer as 'up' | 'down' | 'tab' | 'enter' | 'wait' : 'unknown';
   });
   const target = `${request.plugin}@${request.marketplace}`;

package/src/agent-substrate/review-observation.ts

@@ -60,8 +60,11 @@ interface ReviewObservationInput {
   readonly fallbackAttempted?: boolean;
   /** 폴백이 실제로 시도한 백엔드. */
   readonly fallbackBackend?: string;
+  /** Explicitly requested primary model and the ACP backend that actually completed review. */
+  readonly requestedModel?: string;
+  readonly actualBackend?: string;
   /** 폴백을 시도하지 않은 이유. */
-  readonly fallbackNotAttemptedReason?: 'explicit-acp' | 'primary-review-succeeded';
+  readonly fallbackNotAttemptedReason?: 'explicit-acp' | 'primary-review-succeeded' | 'explicit-model';
   /** 1차가 왜 못 돌았나 — 폴백의 «사인». */
   readonly fallbackTriggerReason?: string;
   /** Each failed ACP fallback attempt, retained in order for diagnosis. */
@@ -80,7 +83,9 @@ interface ReviewObservation {
   readonly reviewRoute?: 'api' | 'acp' | 'acp-fallback';
   readonly fallbackAttempted?: boolean;
   readonly fallbackBackend?: string;
-  readonly fallbackNotAttemptedReason?: 'explicit-acp' | 'primary-review-succeeded';
+  readonly requestedModel?: string;
+  readonly actualBackend?: string;
+  readonly fallbackNotAttemptedReason?: 'explicit-acp' | 'primary-review-succeeded' | 'explicit-model';
   readonly fallbackTriggerReason?: string;
   readonly fallbackFailures?: readonly { backend: string; reason: string }[];
   readonly skippedAcpFallbackBackends?: readonly { backend: string; reason: string }[];
@@ -168,6 +173,8 @@ export function buildReviewObservation(input: ReviewObservationInput): ReviewObs
     ...(input.reviewRoute ? { reviewRoute: input.reviewRoute } : {}),
     ...(input.fallbackAttempted !== undefined ? { fallbackAttempted: input.fallbackAttempted } : {}),
     ...(input.fallbackBackend ? { fallbackBackend: safeLogText(input.fallbackBackend) } : {}),
+    ...(input.requestedModel ? { requestedModel: safeLogText(input.requestedModel) } : {}),
+    ...(input.actualBackend ? { actualBackend: safeLogText(input.actualBackend) } : {}),
     ...(input.fallbackNotAttemptedReason ? { fallbackNotAttemptedReason: input.fallbackNotAttemptedReason } : {}),
     ...(input.fallbackTriggerReason ? { fallbackTriggerReason: safeLogText(input.fallbackTriggerReason) } : {}),
     ...(input.fallbackFailures?.length ? {

package/src/agent-substrate/self-review-cli.ts

@@ -14,9 +14,10 @@
 //
 // index.ts 의 액션은 옵션 파싱과 실제 의존 배선만 남는다(얇은 껍데기).
 
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { tierModel } from '../llm/model-defaults.js';
 import { buildReviewObservation, safeLogText } from './review-observation.js';
 import { DEFAULT_REVIEW_BACKEND } from './acp-reviewer.js';
@@ -24,7 +25,7 @@ import { ACP_BACKENDS, canonicalizeBackendId } from '../acp/backend-registry.js'
 import { buildManualReviewIntent, intentFromPr, prIntentSectionCoverage, reviewIntentTruncationFromPr, reviewIntentTruncationObservation } from './review-intent.js';
 import { budgetReviewerContext, reviewDiffBudgetObservation, splitDiffByFile, type ReviewImage, type ReviewInput, type ReviewerContextItem, type ReviewResult } from './pr-reviewer.js';
 import type { ReferencedFileReader } from '../self-implement/goal-file-reader.js';
-import type { SubscriptionReviewerSpec } from '../user-config.js';
+import { getUserConfig, type SubscriptionReviewerSpec } from '../user-config.js';
 import { listRunLedgers, lookupPrGoalAcceptance, lookupRunLedger, type PrGoalAcceptanceLookup, type RunLedgerEntry, type RunLedgerLookup } from '../self-implement/run-ledger.js';
 
 /** SUBSCRIPTION-EXHAUST-REROUTE — API reviewer when the configured `roleLlm.reviewer` lane is unavailable (off codex). */
@@ -37,6 +38,8 @@ export interface SelfReviewCliOpts {
   acpModel?: string | undefined;
   acpBackend?: string | undefined;
   configuredAcpBackend?: string | undefined;
+  /** ACP review backends excluded from automatic fallback by `acp.reviewDenyBackends`. */
+  reviewDenyBackends?: string[] | undefined;
   /** `roleLlm.reviewer` (same resolution as the harness). Used only when no explicit reviewer flag is given. */
   roleReviewer?: SubscriptionReviewerSpec | undefined;
   acpTimeout?: string | undefined;
@@ -44,6 +47,8 @@ export interface SelfReviewCliOpts {
   contextText?: string[] | undefined;
   contextOrder?: Array<{ kind: 'file' | 'text'; value: string }> | undefined;
   json?: boolean | undefined;
+  /** Save completed reviews under the task-agent state's review-results directory. */
+  save?: string | undefined;
 }
 
 /** 셸/네트워크/로그 경계 — 테스트는 전부 대역으로 채운다. */
@@ -1120,10 +1125,11 @@ function roleAcpErrorReason(error: unknown): 'acp-handshake-timeout' | 'acp-erro
 
 type AcpFallbackSkip = { backend: string; reason: string };
 
-function orderedAcpReviewFallbackBackends(configuredBackend: string | undefined): {
+function orderedAcpReviewFallbackBackends(configuredBackend: string | undefined, denyBackends: readonly string[] = []): {
   backends: string[];
   skipped: AcpFallbackSkip[];
 } {
+  const denied = new Set(denyBackends.map((backend) => backend.trim().toLowerCase()).filter(Boolean));
   const candidates = [configuredBackend, ...Object.keys(ACP_BACKENDS)]
     .map((backend) => backend?.trim())
     .filter((backend): backend is string => Boolean(backend));
@@ -1135,6 +1141,10 @@ function orderedAcpReviewFallbackBackends(configuredBackend: string | undefined)
     const spec = ACP_BACKENDS[backend];
     if (!spec || seen.has(backend)) continue;
     seen.add(backend);
+    if (denied.has(backend)) {
+      skipped.push({ backend, reason: 'denied-by-acp.reviewDenyBackends' });
+      continue;
+    }
     if (spec.unsupportedReason) {
       skipped.push({ backend, reason: spec.unsupportedReason });
       continue;
@@ -1269,6 +1279,11 @@ async function runSelfReviewCliCommandPinned(
     return { results: [], failed: 0 };
   }
 
+  if (opts.save !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(opts.save)) {
+    deps.error('--save 이름은 영문자·숫자로 시작하고 영문자·숫자·점·밑줄·하이픈만 포함해야 합니다.');
+    return { results: [], failed: 1 };
+  }
+
   const useAcp = opts.acp === true;
   const acpModel = opts.acpModel?.trim() || undefined;
   const acpBackendResolution = opts.acpBackend
@@ -1277,7 +1292,12 @@ async function runSelfReviewCliCommandPinned(
       ? { backend: opts.configuredAcpBackend, source: 'config' as const }
       : { backend: DEFAULT_REVIEW_BACKEND, source: 'default' as const };
   const acpBackend = acpBackendResolution.backend;
-  const automaticFallbacks = orderedAcpReviewFallbackBackends(opts.configuredAcpBackend);
+  const requestedModel = opts.model?.trim() || undefined;
+  const rawReviewDenyBackends = (getUserConfig().raw?.acp as { reviewDenyBackends?: unknown } | undefined)?.reviewDenyBackends;
+  const configuredReviewDenyBackends = Array.isArray(rawReviewDenyBackends)
+    ? rawReviewDenyBackends.filter((backend): backend is string => typeof backend === 'string')
+    : [];
+  const automaticFallbacks = orderedAcpReviewFallbackBackends(opts.configuredAcpBackend, opts.reviewDenyBackends ?? configuredReviewDenyBackends);
   const fallbackAcpBackends = opts.acpBackend
     ? [canonicalizeBackendId(opts.acpBackend)]
     : automaticFallbacks.backends;
@@ -1300,6 +1320,14 @@ async function runSelfReviewCliCommandPinned(
   const envModel = deps.envModel();
   const roleFallbackModel = !useAcp && !opts.model && !envModel && reviewerSource === 'role-config'
     ? deps.roleFallbackModel?.()?.trim() || undefined : undefined;
+  if (requestedModel && /^glm-\d+(?:\.\d+)?$/i.test(requestedModel)) {
+    const canonical = requestedModel.toLowerCase() === 'glm-5.3' ? 'openrouter/z-ai/glm-5.3' : undefined;
+    const suggestion = canonical ? ` 정본 모델 ID 후보: ${canonical}` : ' `local:<model>` 또는 공급자 정본 ID를 지정하세요.';
+    const message = `모델 ID가 모호합니다: ${requestedModel}.${suggestion} 짧은 별칭을 공급자 정본 ID로 바꿔 다시 시도하세요.`;
+    deps.log('model-rejected', { requestedModel: safeLogText(requestedModel), reason: 'ambiguous-model-id', ...(canonical ? { canonicalModelCandidate: canonical } : {}) }, { level: 'warn' });
+    deps.error(message);
+    return { results: opts.json ? [{ error: message, requestedModel }] : [], failed: 1 };
+  }
   const model = useAcp ? `acp:${acpBackend}${acpModel ? `/${acpModel}` : ''}` : (opts.model || envModel || roleFallbackModel || tierModel('better'));
   let roleReviewer: { llm: (prompt: string, images?: readonly ReviewImage[]) => Promise<string>; model: string } | undefined;
   let roleReviewerUnavailableReason: string | undefined;
@@ -1411,8 +1439,8 @@ async function runSelfReviewCliCommandPinned(
         { pr: safeLogText(pr), exit: diff.status, error: safeLogText(diff.stderr || err, 160) },
         { level: 'warn' });
       const contextOutput = reviewerContextOutput(reviewerContext, decompositionContext);
-      if (opts.json) results.push({ pr, error: err, ...contextOutput, ...comparisonData, ...(mismatchWarning ?? {}) });
-      else deps.error(`PR ${pr}: ${err}\n${reviewerContextStatus}`);
+      if (opts.json || opts.save !== undefined) results.push({ pr, error: err, ...contextOutput, ...comparisonData, ...(mismatchWarning ?? {}) });
+      if (!opts.json) deps.error(`PR ${pr}: ${err}\n${reviewerContextStatus}`);
       failed += 1;
       continue;
     }
@@ -1472,8 +1500,8 @@ async function runSelfReviewCliCommandPinned(
         pr, model: primaryModel, verdict: null, mustFix: [], shouldFix: [], reviewed: false,
         refusal: 'stale-head', ...provenance, ...reviewerSourceObservation(), ...contextOutput,
       };
-      if (opts.json) results.push(refused);
-      else deps.print(`\n━━ PR ${pr} (${primaryModel}) ━━\n${renderStaleRefusal(diffRead)}\n${reviewerContextStatus}`);
+      if (opts.json || opts.save !== undefined) results.push(refused);
+      if (!opts.json) deps.print(`\n━━ PR ${pr} (${primaryModel}) ━━\n${renderStaleRefusal(diffRead)}\n${reviewerContextStatus}`);
       continue;
     }
     // ⭐ 머지된 PR 만 머지 커밋 detached worktree 에서 리뷰한다 — main 최신이 아니라 그 PR 이 머지된 시점의 코드를 본다.
@@ -1558,9 +1586,9 @@ async function runSelfReviewCliCommandPinned(
     let fallbackAttempted = false;
     let fallbackBackend: string | undefined;
     let fallbackTriggerReason: string | undefined;
-    let fallbackNotAttemptedReason: 'explicit-acp' | 'primary-review-succeeded' | undefined;
+    let fallbackNotAttemptedReason: 'explicit-acp' | 'primary-review-succeeded' | 'explicit-model' | undefined;
     const fallbackFailures: Array<{ backend: string; reason: string }> = [];
-    if (!useAcp && !roleReview && review.reviewed !== true) {
+    if (!useAcp && !roleReview && !opts.acpModel?.trim() && (!requestedModel || Boolean(opts.acpBackend)) && review.reviewed !== true) {
       fallbackAttempted = true;
       fallbackTriggerReason = safeLogText(review.failureReason || 'reviewed=false', 400);
       for (const backend of fallbackAcpBackends) {
@@ -1569,6 +1597,7 @@ async function runSelfReviewCliCommandPinned(
           pr: safeLogText(pr),
           failureReason: fallbackTriggerReason,
           fallbackBackend: safeLogText(backend),
+          requestedModel: safeLogText(primaryModel),
         }, { level: 'warn' });
         try {
           const fallbackReview = await deps.reviewPullRequest(
@@ -1598,12 +1627,13 @@ async function runSelfReviewCliCommandPinned(
       ...(reviewCwdPinFallbackReason ? { reviewCwdPinFallbackReason } : {}),
     };
     if (!fallbackAttempted) {
-      fallbackNotAttemptedReason = useAcp ? 'explicit-acp' : 'primary-review-succeeded';
+      fallbackNotAttemptedReason = useAcp ? 'explicit-acp' : requestedModel && review.reviewed !== true ? 'explicit-model' : 'primary-review-succeeded';
     }
     const reviewProvenance = {
       reviewRoute,
       fallbackAttempted,
       ...(fallbackBackend ? { fallbackBackend } : {}),
+      ...(fallbackBackend ? { requestedModel: primaryModel, actualBackend: `acp:${fallbackBackend}` } : {}),
       ...(fallbackNotAttemptedReason ? { fallbackNotAttemptedReason } : {}),
       ...(fallbackTriggerReason ? { fallbackTriggerReason } : {}),
       ...(fallbackFailures.length ? { fallbackFailures } : {}),
@@ -1644,17 +1674,33 @@ async function runSelfReviewCliCommandPinned(
     if (useAcp && review.reviewed === false) {
       const err = 'ACP 리뷰 실행 실패(reviewed=false) — 관측: elanous logs --category acp-review';
       const contextOutput = reviewerContextOutput(reviewerContext, decompositionContext);
-      if (opts.json) results.push({ pr, error: err, ...review, verdict: null, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput });
-      else deps.error(`PR ${pr}: ${err}\n${renderProvenance(diffRead)}\n${reviewerContextStatus}`);
+      if (opts.json || opts.save !== undefined) results.push({ pr, error: err, ...review, verdict: null, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput });
+      if (!opts.json) deps.error(`PR ${pr}: ${err}\n${renderProvenance(diffRead)}\n${reviewerContextStatus}`);
       failed += 1;
       continue;
     }
     const contextOutput = reviewerContextOutput(reviewerContext, decompositionContext);
     const jsonReview = review.reviewed === true ? review : { ...review, verdict: null };
-    if (opts.json) results.push({ pr, model: selectedModel, ...jsonReview, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles, ...(evidence.authoredFiles !== undefined ? { authoredFiles: evidence.authoredFiles } : {}) });
-    else deps.print(`\n━━ PR ${pr} (${selectedModel}) ━━\n${renderProvenance(diffRead)}\n${evidenceLine}\n${reviewerContextStatus}\n${deps.renderReview(review)}`);
+    if (opts.json || opts.save !== undefined) results.push({ pr, model: selectedModel, ...jsonReview, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles, ...(evidence.authoredFiles !== undefined ? { authoredFiles: evidence.authoredFiles } : {}) });
+    if (!opts.json) deps.print(`\n━━ PR ${pr} (${selectedModel}) ━━\n${renderProvenance(diffRead)}\n${evidenceLine}\n${reviewerContextStatus}\n${deps.renderReview(review)}`);
     // REVIEW-ERROR-RC — 기본(API)·role 경로가 1차·폴백 모두 실패해 reviewed≠true 로 끝나도 «못 리뷰한 PR» 이다(verdict:null).
     if (review.reviewed !== true) failed += 1;
+    if (opts.save !== undefined) {
+      if (review.reviewed !== true || diffRead.headCommitState !== 'known' || diffRead.currentHeadCommitState !== 'known' || diffRead.currentHeadCommit !== diffRead.headCommit || diffRead.headCommit.length !== 40) {
+        deps.error(`PR ${pr}: --save 불가 — 완료된 리뷰와 확인된 40자 PR head가 필요합니다.`);
+        if (review.reviewed === true) failed += 1;
+      } else {
+        const path = join(effectiveInstanceRoot(), 'review-results', `${opts.save}-${pr}-${diffRead.headCommit.slice(0, 12)}.json`);
+        const result = results.at(-1);
+        try {
+          mkdirSync(dirname(path), { recursive: true });
+          writeFileSync(path, selfReviewJsonLine([result]));
+        } catch (error) {
+          failed += 1;
+          deps.error(`PR ${pr}: --save 실패: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
   }
   return { results, failed };
 }