elanous 0.2.24 → 0.2.27

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();

package/src/agent-substrate/acp-implementer.ts

@@ -1,7 +1,8 @@
 // ── ACP Claude Code 를 «구현» 실행기로 (CLAUDE-IMPL-LANE · `--child-llm-provider claude-acp`) ──
 //
 // acp-reviewer.ts 의 짝이다. 리뷰어는 read-only 라 읽기 툴만 허가하지만, 구현 실행기는 런 워크트리 안에서
-// 쓰기·실행을 허가해야 한다. 그래서 approver 가 «워크트리 밖 경로 쓰기»를 구조적으로 거부한다.
+// 쓰기·실행을 허가해야 한다. 대표 대표 결정(10-12): ACP 세션 권한 모드는 호스트 설정(auto)을 그대로 두고
+// 바꾸지 않으며, approver 가 불려도 «워크트리 밖 경로 쓰기»를 거부하지 않고 허가하되 insideWorktree 로 관측한다.
 // 자식은 claude 구독 ACP 어댑터(`claude-agent-acp`)이며 env 는 subscriptionReviewerSpawn 의 과금 스크럽
 // (ANTHROPIC_API_KEY 등 제거)을 그대로 쓴다 — 지우지 않으면 구독이 아니라 API 로 과금된다.
 import { isAbsolute, relative, resolve } from 'node:path';
@@ -23,6 +24,8 @@ export interface ImplementerPermissionRequest {
 export interface ImplementerPermissionDecision {
   tool: string;
   path: string | null;
+  /** 판정에 쓴 경로가 워크트리 안인가 — 경로가 없으면 null. 밖이어도 허가한다(대표 10-12); 이 칸이 그 관측이다. */
+  insideWorktree: boolean | null;
   decision: 'allow' | 'deny';
 }
 
@@ -37,18 +40,20 @@ function insideWorktree(worktree: string, target: string): boolean {
   return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
 
-/** 허가 판정(순수 함수). 쓰기 계열(edit·delete·move)은 모든 경로가 워크트리 안일 때만 허가하고,
- *  실행(execute)은 cwd 가 워크트리라 허가한다. 읽기 계열은 허가, 그 외는 경로가 있고 전부 안쪽일 때만 허가(보수적). */
+/** 허가 판정(순수 함수). 쓰기 계열(edit·delete·move)은 경로가 있으면 워크트리 안팎을 가리지 않고 허가한다
+ *  (대표 10-12 — 밖 쓰기 거부를 걷었다 · insideWorktree 로 관측만 한다). 실행(execute)·읽기 계열은 허가,
+ *  그 외(모르는 kind)는 경로가 있을 때만 허가 — 경로 없는 쓰기·모르는 요청은 여전히 거부. */
 export function decideImplementerPermission(req: ImplementerPermissionRequest, worktree: string): ImplementerPermissionDecision {
   const paths = requestedPaths(req.rawInput);
   const outside = paths.find((p) => !insideWorktree(worktree, p));
   const tool = req.title.slice(0, 80);
   const shown = outside ?? paths[0] ?? null;
-  const verdict = (allow: boolean): ImplementerPermissionDecision => ({ tool, path: shown, decision: allow ? 'allow' : 'deny' });
-  if (req.kind && WRITE_TOOL_KINDS.has(req.kind)) return verdict(paths.length > 0 && outside === undefined);
+  const inside = paths.length === 0 ? null : outside === undefined;
+  const verdict = (allow: boolean): ImplementerPermissionDecision => ({ tool, path: shown, insideWorktree: inside, decision: allow ? 'allow' : 'deny' });
+  if (req.kind && WRITE_TOOL_KINDS.has(req.kind)) return verdict(paths.length > 0);
   if (req.kind === 'execute') return verdict(true);
   if (isReadOnlyReviewTool(req.kind, req.title)) return verdict(true);
-  return verdict(paths.length > 0 && outside === undefined);
+  return verdict(paths.length > 0);
 }
 
 export interface AcpImplementerOpts {
@@ -96,7 +101,9 @@ export function makeAcpImplementer(opts: AcpImplementerOpts): (prompt: string) =
       permissionApprover: async (req) => {
         const verdict = decideImplementerPermission(req, opts.worktree);
         if (verdict.decision === 'allow') allowed++; else denied++;
-        debug.log(OBS, 'permission', { ...verdict });
+        debug.log(OBS, 'permission', {
+          tool: verdict.tool, path: verdict.path, insideWorktree: verdict.insideWorktree, allowed: verdict.decision === 'allow',
+        });
         return verdict.decision === 'allow';
       },
     };

package/src/agent-substrate/pr-reviewer.ts

@@ -683,8 +683,9 @@ function isLongNoFindingBracket(text: string): boolean {
   return NO_FINDING_HEAD.test(remark) && !LONG_REMARK_DISSENT.test(remark);
 }
 /** must-fix 항목이 «지적 없음» 표지인가 — must-fix 를 세는 자리는 전부 `parseReviewResult` 를 거친다
- *  (`self review --json` 의 `mustFix` → TA `parseReviewResultOutput` → `pr land --overlap-evidence` 의 `review-must-fix-N`). */
-function isNoneSentinelFinding(finding: string): boolean {
+ *  (`self review --json` 의 `mustFix` → TA `parseReviewResultOutput` → `pr land --overlap-evidence` 의 `review-must-fix-N`).
+ *  ⭐ export — `parseReviewResultOutput` 가 «같은» 판정으로 저장된 결과의 표지 줄을 다시 접는다(PR-LAND-MUSTFIX-NONE · 복제 금지). */
+export function isNoneSentinelFinding(finding: string): boolean {
   const text = finding.trim();
   if (BARE_SENTINEL.test(text)) return true;
   const bracketed = BRACKETED_SENTINEL.exec(text);
@@ -765,6 +766,25 @@ function reviewedResultFromRaw(raw: string, runId: string | undefined, pass?: {
   return { verdict: 'pass', mustFix: [], shouldFix: [], reviewed: false, failureReason: NO_VERDICT_LINE_REASON };
 }
 
+/** REVIEW-PROMPT-SIZE — llmReview 호출 하나(단일·청크 패스)마다 프롬프트·응답 크기를 남긴다.
+ *  관측이 리뷰를 막지 않는다(다른 review.* 관측과 같은 계약). */
+function logReviewPromptSize(
+  prompt: string,
+  response: string,
+  pass: { pass: number; chunked: boolean },
+  runId: string | undefined,
+): void {
+  try {
+    debug.log('review.prompt-size', 'call', {
+      pass: pass.pass,
+      promptChars: prompt.length,
+      responseChars: response.length,
+      chunked: pass.chunked,
+      ...(runId !== undefined ? { runId } : {}),
+    });
+  } catch { /* Observation must not prevent the review. */ }
+}
+
 function failureReasonText(error: unknown): string {
   if (error instanceof Error) return safeLogText(error.message, 400);
   if (typeof error === 'string') return safeLogText(error, 400);
@@ -916,10 +936,11 @@ export async function reviewPullRequest(
             + ' 「여기 안 보인다」를 결함으로 판정하지 마십시오.',
           ].filter(Boolean).join('\n'),
         };
-        passResults.push(reviewedResultFromRaw(await llmReview(
-          buildReviewPrompt(passInput, passBudget, '', passContext[index]?.budget),
-          reviewImages.length > 0 && index === 0 ? reviewImages : undefined,
-        ), input.reviewContext?.runId, { index, of: plan.passes.length }));
+        const passPrompt = buildReviewPrompt(passInput, passBudget, '', passContext[index]?.budget);
+        const passImages = reviewImages.length > 0 && index === 0 ? reviewImages : undefined;
+        const passRaw = await llmReview(passPrompt, passImages);
+        logReviewPromptSize(passPrompt, passRaw, { pass: index + 1, chunked: true }, input.reviewContext?.runId);
+        passResults.push(reviewedResultFromRaw(passRaw, input.reviewContext?.runId, { index, of: plan.passes.length }));
       }
       return {
         ...foldReviewResults(passResults),
@@ -943,10 +964,9 @@ export async function reviewPullRequest(
         } : {}),
       };
     }
-    const raw = await llmReview(
-      buildReviewPrompt(input, diffBudget, referencedContext.text, singleContextBudget),
-      reviewImages.length > 0 ? reviewImages : undefined,
-    );
+    const prompt = buildReviewPrompt(input, diffBudget, referencedContext.text, singleContextBudget);
+    const raw = await llmReview(prompt, reviewImages.length > 0 ? reviewImages : undefined);
+    logReviewPromptSize(prompt, raw, { pass: 1, chunked: false }, input.reviewContext?.runId);
     return {
       ...reviewedResultFromRaw(raw, input.reviewContext?.runId),
       diffBudget: {

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,6 +14,9 @@
 //
 // index.ts 의 액션은 옵션 파싱과 실제 의존 배선만 남는다(얇은 껍데기).
 
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { tierModel } from '../llm/model-defaults.js';
 import { buildReviewObservation, safeLogText } from './review-observation.js';
 import { DEFAULT_REVIEW_BACKEND } from './acp-reviewer.js';
@@ -21,7 +24,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). */
@@ -34,6 +37,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;
@@ -75,13 +80,13 @@ export interface SelfReviewCliDeps {
    *
    * ⚠️ API 백엔드(`makeApiLlm`)는 이 인자를 안 받는다 — ACP 경로만 이미지를 나른다.
    */
-  makeAcpLlm(o: { backend: string; model?: string; timeoutMs: number }): (prompt: string, images?: readonly ReviewImage[]) => Promise<string>;
+  makeAcpLlm(o: { backend: string; model?: string; timeoutMs: number; cwd?: string }): (prompt: string, images?: readonly ReviewImage[]) => Promise<string>;
   /**
    * Reviewer ACP lane selected by `roleLlm.reviewer` (no explicit flag). Returns the LLM when the
    * subscription is usable, or a reason code when it is not — the caller then reviews on the API
    * exactly as before. Absent seam = the lane is unavailable (`role-reviewer-seam-missing`).
    */
-  makeRoleReviewerLlm?(spec: SubscriptionReviewerSpec, o: { timeoutMs: number }):
+  makeRoleReviewerLlm?(spec: SubscriptionReviewerSpec, o: { timeoutMs: number; cwd?: string }):
     | { llm: (prompt: string, images?: readonly ReviewImage[]) => Promise<string>; backend: string }
     | { reason: string };
   /**
@@ -1117,10 +1122,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));
@@ -1132,6 +1138,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;
@@ -1164,6 +1174,65 @@ export function renderReviewerContextStatus(loaded: LoadedReviewerContext, decom
   return `Reviewer context: ${loaded.items.length} loaded, ${loaded.failed.length} not loaded.${source}${truncation}${decompositionStatus}${labels ? `\n${labels}` : ''}${failures ? `\n${failures}` : ''}`;
 }
 
+/**
+ * 머지된 PR 의 사후 리뷰 격리 — 리뷰어 cwd 가 main 최신이면 그 뒤 수리를 인용한다.
+ * `merged` 는 그 PR 의 머지 커밋, `open` 은 종전(cwd 불변), `unpinnable` 은 MERGED 인데 머지 커밋을 못 구한 경우다.
+ */
+type PrMergeState =
+  | { kind: 'open' }
+  | { kind: 'merged'; commit: string }
+  | { kind: 'unpinnable'; reason: 'merge-commit-unknown' };
+
+function readPrMergeState(pr: string, deps: SelfReviewCliDeps): PrMergeState {
+  const view = deps.gh(['pr', 'view', pr, '--json', 'state,mergeCommit'], 15_000);
+  if (view.status !== 0) return { kind: 'open' };
+  try {
+    const parsed = JSON.parse(view.stdout) as { state?: unknown; mergeCommit?: { oid?: unknown } | null };
+    if (parsed?.state !== 'MERGED') return { kind: 'open' };
+    const oid = parsed.mergeCommit?.oid;
+    return typeof oid === 'string' && COMMIT_OID.test(oid)
+      ? { kind: 'merged', commit: oid }
+      : { kind: 'unpinnable', reason: 'merge-commit-unknown' };
+  } catch {
+    return { kind: 'open' };
+  }
+}
+
+interface ReviewWorktree {
+  cwd: string;
+  commit: string;
+  /** 멱등 — 두 번 불러도 안전하다. */
+  remove(): void;
+}
+
+type ReviewWorktreeResult = ReviewWorktree | { reason: 'no-git-seam' | 'worktree-add-failed' };
+
+function createDetachedReviewWorktree(commit: string, deps: SelfReviewCliDeps): ReviewWorktreeResult {
+  const git = deps.git;
+  if (!git) return { reason: 'no-git-seam' };
+  const parent = mkdtempSync(join(tmpdir(), 'elanous-review-pin-'));
+  const cwd = join(parent, 'wt');
+  const add = () => git(['worktree', 'add', '--detach', cwd, commit], 120_000);
+  let added = add();
+  if (added.status !== 0) {
+    git(['fetch', 'origin', commit], 120_000);
+    added = add();
+  }
+  let removed = false;
+  const remove = (): void => {
+    if (removed) return;
+    removed = true;
+    git(['worktree', 'remove', '--force', cwd], 60_000);
+    rmSync(parent, { recursive: true, force: true });
+    // ⛔ `git worktree prune` 은 부르지 않는다 — 저장소 «전체»의 stale 메타데이터를 지워 남의 worktree 까지 건드린다.
+  };
+  if (added.status !== 0) {
+    remove();
+    return { reason: 'worktree-add-failed' };
+  }
+  return { cwd, commit, remove };
+}
+
 /** `elanous self review <pr...>` 본문. read-only — 머지하지 않는다. */
 /**
  * `self review --json` stdout 한 줄 — 결과가 하나면 객체, 여럿이면 배열. index.ts 액션이 이것을 그대로 쓴다.
@@ -1177,6 +1246,20 @@ export async function runSelfReviewCliCommand(
   prArgs: string[],
   opts: SelfReviewCliOpts,
   deps: SelfReviewCliDeps,
+): Promise<SelfReviewCliOutcome> {
+  const pins: ReviewWorktree[] = [];
+  try {
+    return await runSelfReviewCliCommandPinned(prArgs, opts, deps, pins);
+  } finally {
+    for (const pin of pins) pin.remove();
+  }
+}
+
+async function runSelfReviewCliCommandPinned(
+  prArgs: string[],
+  opts: SelfReviewCliOpts,
+  deps: SelfReviewCliDeps,
+  pins: ReviewWorktree[],
 ): Promise<SelfReviewCliOutcome> {
   // 관측 sink는 모든 종료 경로보다 먼저 등록해 거부도 운영 로그에 남긴다.
   await deps.registerSink('self-review');
@@ -1201,7 +1284,12 @@ export async function runSelfReviewCliCommand(
       ? { 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;
@@ -1224,6 +1312,14 @@ export async function runSelfReviewCliCommand(
   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;
@@ -1272,6 +1368,7 @@ export async function runSelfReviewCliCommand(
     // ⛔ `relation-unknown` 도 경고한다(위 주석 · 리뷰가 두 라운드 반복 지적) — 그 밖 unavailable 은 조용하다.
     //    ⭐ 경고 여부 판정은 `localHeadWarningDetails` 한 곳에 있다(호출부에서 같은 함수를 두 번 부르지 않는다).
     const mismatchWarning = localHeadWarningDetails(localHeadComparison);
+    const mergeState = readPrMergeState(pr, deps);
     const view = deps.gh(['pr', 'view', pr, '--json', 'title,body'], 15_000);
     let prView: { title?: string; body?: string } | undefined;
     if (view.status === 0) {
@@ -1399,6 +1496,36 @@ export async function runSelfReviewCliCommand(
       else deps.print(`\n━━ PR ${pr} (${primaryModel}) ━━\n${renderStaleRefusal(diffRead)}\n${reviewerContextStatus}`);
       continue;
     }
+    // ⭐ 머지된 PR 만 머지 커밋 detached worktree 에서 리뷰한다 — main 최신이 아니라 그 PR 이 머지된 시점의 코드를 본다.
+    //    열린 PR 은 종전 그대로(cwd = process.cwd() · 리뷰어 심이 cwd 를 받지 않는다).
+    let reviewPin: ReviewWorktree | undefined;
+    let reviewCwdPinFallbackReason: string | undefined;
+    // cwd 를 받는 레인(ACP · role 리뷰어)일 때만 worktree 를 뜬다 — API 리뷰어는 cwd 를 안 받으므로 떠도 그 위에서 돌지 않는다.
+    const pinLane = useAcp || Boolean(roleReviewer && opts.roleReviewer && deps.makeRoleReviewerLlm);
+    let rolePinned = false;
+    if (!pinLane) {
+      // 비-ACP 레인 — 격리하지 않는다(종전 그대로 · reviewCwdCommit 없음).
+    } else if (mergeState.kind === 'merged') {
+      const made = createDetachedReviewWorktree(mergeState.commit, deps);
+      if ('cwd' in made) {
+        reviewPin = made;
+        pins.push(made);
+      } else reviewCwdPinFallbackReason = made.reason;
+    } else if (mergeState.kind === 'unpinnable') reviewCwdPinFallbackReason = mergeState.reason;
+    const reviewCwd = reviewPin?.cwd;
+    const prAcpReviewLLM = reviewCwd && useAcp
+      ? deps.makeAcpLlm({ backend: acpBackend, ...(acpModel ? { model: acpModel } : {}), timeoutMs: acpTimeoutSec * 1000, cwd: reviewCwd })
+      : acpReviewLLM;
+    let prRoleReviewer = roleReviewer;
+    if (reviewCwd && roleReviewer && opts.roleReviewer && deps.makeRoleReviewerLlm) {
+      try {
+        const pinned = deps.makeRoleReviewerLlm(opts.roleReviewer, { timeoutMs: acpTimeoutSec * 1000, cwd: reviewCwd });
+        if ('llm' in pinned) { prRoleReviewer = { llm: pinned.llm, model: `acp:${pinned.backend}` }; rolePinned = true; }
+        else reviewCwdPinFallbackReason = 'role-reviewer-cwd-unavailable';
+      } catch {
+        reviewCwdPinFallbackReason = 'role-reviewer-cwd-unavailable';
+      }
+    }
     const startedAt = deps.now();
     // Role-config lane builds the API reviewer only when it falls back (`made().api` stays 0 on ACP success).
     const responded: { provider?: string; model?: string } = {};
@@ -1406,7 +1533,7 @@ export async function runSelfReviewCliCommand(
       pinProvider: Boolean(opts.model?.trim()),
       onResolved: (provider, respondedModel) => { responded.provider = provider; responded.model = respondedModel; },
     });
-    const llmReview = roleReviewer ? undefined : (acpReviewLLM ?? makeApi());
+    const llmReview = prRoleReviewer ? undefined : (prAcpReviewLLM ?? makeApi());
     // ⛔ evidenceNote 는 **별도 채널**이다 — phaseIntent 에 섞으면 의도 채널이 오염된다(실측: 그렇게
     //   했다가 intent 배선 테스트 3개가 즉시 깨졌다).
     // ⛔ 사람 `--intent`(phaseIntent) 와 골 acceptance 는 다른 인자 — 충돌하지 않고, 충돌해도 intent 가 이긴다.
@@ -1426,10 +1553,10 @@ export async function runSelfReviewCliCommand(
     let roleReview: ReviewResult | undefined;
     let roleReviewerFallbackReason = roleReviewerUnavailableReason;
     let roleReviewMs: number | undefined;
-    if (roleReviewer) {
+    if (prRoleReviewer) {
       const roleStartedAt = deps.now();
       try {
-        const attempt = await deps.reviewPullRequest(reviewInput, roleReviewer.llm);
+        const attempt = await deps.reviewPullRequest(reviewInput, prRoleReviewer.llm);
         if (attempt.reviewed === true) roleReview = attempt;
         // Code, not the reviewer's raw failure text (same rule as the throw path above).
         else roleReviewerFallbackReason = 'acp-review-not-completed';
@@ -1445,15 +1572,15 @@ export async function runSelfReviewCliCommand(
         }, { level: 'warn' });
       }
     }
-    let review = roleReview ?? await deps.reviewPullRequest(reviewInput, llmReview ?? acpReviewLLM ?? makeApi());
-    let selectedModel = roleReview && roleReviewer ? roleReviewer.model : model;
+    let review = roleReview ?? await deps.reviewPullRequest(reviewInput, llmReview ?? prAcpReviewLLM ?? makeApi());
+    let selectedModel = roleReview && prRoleReviewer ? prRoleReviewer.model : model;
     let reviewRoute: 'api' | 'acp' | 'acp-fallback' = useAcp || roleReview ? 'acp' : 'api';
     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) {
@@ -1462,11 +1589,12 @@ export async function runSelfReviewCliCommand(
           pr: safeLogText(pr),
           failureReason: fallbackTriggerReason,
           fallbackBackend: safeLogText(backend),
+          requestedModel: safeLogText(primaryModel),
         }, { level: 'warn' });
         try {
           const fallbackReview = await deps.reviewPullRequest(
             reviewInput,
-            deps.makeAcpLlm({ backend, timeoutMs: acpTimeoutSec * 1000 }),
+            deps.makeAcpLlm({ backend, timeoutMs: acpTimeoutSec * 1000, ...(reviewCwd ? { cwd: reviewCwd } : {}) }),
           );
           if (fallbackReview.reviewed === true) {
             review = fallbackReview;
@@ -1482,13 +1610,22 @@ export async function runSelfReviewCliCommand(
         }
       }
     }
+    reviewPin?.remove();
+    // reviewCwdCommit 은 «최종 판정을 낸 LLM 이 실제로 그 cwd 를 받았을 때만» 싣는다(role 실패 → API 폴백이면 안 싣는다).
+    const reviewedOnPin = Boolean(reviewPin) && (roleReview ? rolePinned : reviewRoute === 'acp-fallback' ? true : reviewRoute === 'acp' && useAcp);
+    if (reviewPin && !reviewedOnPin) reviewCwdPinFallbackReason ??= 'final-reviewer-not-pinned';
+    const reviewCwdOutput = {
+      ...(reviewPin && reviewedOnPin ? { reviewCwdCommit: reviewPin.commit } : {}),
+      ...(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 } : {}),
@@ -1522,20 +1659,21 @@ export async function runSelfReviewCliCommand(
         goalLoaded: goalAcceptance.goalLoaded,
         acceptanceChars: goalAcceptance.acceptanceChars,
         ...reviewerSelection,
+        ...reviewCwdOutput,
       },
       { level: review.reviewed === false ? 'warn' : 'info' });
     // --acp 는 대표가 명시 요청한 리뷰 — fail-soft(reviewed=false)면 조용히 pass 하지 말고 표면화(관측=acp-review).
     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, ...provenance, ...contextOutput });
+      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}`);
       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, ...provenance, ...contextOutput, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles, ...(evidence.authoredFiles !== undefined ? { authoredFiles: evidence.authoredFiles } : {}) });
+    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)}`);
     // REVIEW-ERROR-RC — 기본(API)·role 경로가 1차·폴백 모두 실패해 reviewed≠true 로 끝나도 «못 리뷰한 PR» 이다(verdict:null).
     if (review.reviewed !== true) failed += 1;

package/src/boot/daemon-tools/self-implement.ts

@@ -75,6 +75,66 @@ export function _setCreateGoalAuthorDecomposeStepsForTesting(fn?: CreateGoalAuth
 /** 진행 종료 스테이지(phase='end') — 그 외는 delta(start 제외). */
 const END_STAGES: readonly SelfImplementProgressStage[] = ['pr-opened', 'aborted', 'gate-failed', 'pr-declined'];
 
+// ⭐ 결과 네 꼴(HARNESS-RESULT-CONTRACT · RFC-tui-tool-surface-on-graph-harness §4 · 0.2.26) —
+//   종전 `{observed:true}` 한 비트는 모델이 «안 됐다 → 직접 편집»으로 읽었다(UX S1-02 · 47 도구).
+//   ⇒ launched / pending / observed-only / failed 네 꼴로 구조화해 «다음 행동»을 문면으로 고정한다.
+//   ⚠️ launched 꼴은 SelfImplementResult 필드를 **그대로 보존**한다 — runId 조인·원장 소비자 무손상.
+export type SelfImplementLaunchedToolResult = SelfImplementResult & { runId: string; kind: 'launched'; message: string; next: string; missing: string[] };
+export type SelfImplementPendingToolResult = Partial<SelfImplementResult> & { kind: 'pending'; message: string; next: string; missing: string[] };
+export type SelfImplementObservedOnlyToolResult = { kind: 'observed-only'; observed: true; message: string; next: string; missing: ['runId', 'node'] };
+export type SelfImplementFailedToolResult = Partial<SelfImplementResult> & { kind: 'failed'; reason: string; message: string; next: string; missing: string[] };
+export type SelfImplementToolResult = SelfImplementLaunchedToolResult | SelfImplementPendingToolResult | SelfImplementObservedOnlyToolResult | SelfImplementFailedToolResult;
+
+/** 하니스가 런을 맡았다 — 파일 편집은 하니스 몫이므로 모델의 직접 Write/Edit 을 문면으로 막는다. */
+export function buildLaunchedToolResult(result: SelfImplementResult): SelfImplementLaunchedToolResult | SelfImplementPendingToolResult {
+  if (!result.runId) return buildPendingToolResult(result);
+  const runId = result.runId;
+  const node = result.node || null;
+  const missing = node ? [] : ['node'];
+  const query = `eln self run ${runId}`;
+  return {
+    ...result,
+    runId,
+    kind: 'launched',
+    next: query,
+    missing,
+    message: `하니스가 맡았습니다 · 런 ${runId} · 노드 ${node ?? '미관측'} · 다음 조회: ${query} · 이 턴에서 파일을 직접 편집하지 마세요`,
+  };
+}
+
+/** 완료 또는 접수는 관측했지만 실제 런 ID가 없어 발사를 단언할 수 없다. */
+export function buildPendingToolResult(result: SelfImplementResult): SelfImplementPendingToolResult {
+  const { runId: _unconfirmedRunId, ...observed } = result;
+  return {
+    ...observed,
+    kind: 'pending',
+    next: 'eln self running-runs',
+    missing: ['runId', ...(result.node ? [] : ['node'])],
+    message: '하니스 응답을 받았지만 런 식별자는 아직 미관측입니다 · 진행 중 런 조회: eln self running-runs · 일치하는 런이 없으면 요청을 다시 보내세요 · 이 턴에서 파일을 직접 편집하지 마세요',
+  };
+}
+
+/** 관측 전용 — 런이 발사되지 «않았다»는 사실과 «구현 실패가 아니다»를 함께 말한다. */
+export function buildObservedOnlyToolResult(): SelfImplementObservedOnlyToolResult {
+  return {
+    kind: 'observed-only',
+    observed: true,
+    missing: ['runId', 'node'],
+    next: '실제 발사를 원하면 관측 전용 모드를 끈 뒤 다시 요청하세요',
+    message: '관측 전용이라 런을 발사하지 않았습니다 · 코드도 안 바꿨습니다 · 이 결과를 구현 실패로 읽고 직접 Write/Edit 하지 마세요 · 실제 발사를 원하면 관측 전용 모드를 끈 뒤 다시 요청하세요',
+  };
+}
+
+/** 거부·실패 — 이유와 다음 행동을 구조화해 모델이 재시도·포기·인계를 판단하게 한다. */
+export function buildFailedToolResult(reason: string, result?: SelfImplementResult): SelfImplementFailedToolResult {
+  const next = result?.runId ? `eln self run ${result.runId}` : '요청과 실패 이유를 확인한 뒤 다시 요청하세요';
+  return {
+    ...(result ?? {}), kind: 'failed', reason, next,
+    missing: [...(result?.runId ? [] : ['runId']), ...(result?.node ? [] : ['node'])],
+    message: `하니스가 발사되지 않았거나 실패했습니다: ${reason} · 다음: ${next} · 이 턴에서 파일을 직접 편집하지 마세요`,
+  };
+}
+
 /**
  * ★ base seam 에 막(SurfaceUx) 배선을 얹는다(P0·테스트 가능). approvePr=ux.confirm(fail-closed)·
  * onProgress=ux.progress. 코어(runSelfImplement)·다른 seam(worktree/implement/gate/openPr)은 무손상.
@@ -180,9 +240,10 @@ export async function dispatchSelfImplement(
   authorGoal: SelfImplementGoalAuthor = writeAuthoredGoal,
   runCli: RunSelfImplementCliFn = runSelfImplementCliCommand,
   seamsFactory?: SelfImplementSeamsFactory,
-): Promise<unknown> {
+): Promise<SelfImplementToolResult> {
   const feature = typeof args.feature === 'string' ? args.feature.trim() : '';
-  if (!feature) return { error: 'SelfImplement: `feature` is required' };
+  if (!feature) return buildFailedToolResult('SelfImplement: `feature` is required');
+  try {
   const base = typeof args.base === 'string' && args.base.trim() ? args.base.trim() : undefined;
   const draft = typeof args.draft === 'boolean' ? args.draft : true;
   const entry = resolveDispatchEntry(ctx);
@@ -216,7 +277,7 @@ export async function dispatchSelfImplement(
   debug.log('daemon-tools.self-implement', 'runtime.observe-only-decision', { surface: ux.surface, observeOnly: observeOnly.enabled, observeOnlySource: observeOnly.source });
   if (observeOnly.enabled) {
     debug.log('daemon-tools.self-implement', 'runtime.observed', { surface: ux.surface, observeOnly: observeOnly.enabled, observeOnlySource: observeOnly.source });
-    return { observed: true };
+    return buildObservedOnlyToolResult();
   }
 
   let goalFile: string | undefined;
@@ -298,5 +359,12 @@ export async function dispatchSelfImplement(
   // ⭐ runId 를 반드시 싣는다 — 관측이 전부 runId 로 키잉되므로(`self run <runId>`·`logs --grep`)
   //   이게 없으면 **이 경계에서 조인이 끊긴다**(N3 재측정 2026-07-28: 계약은 섰는데 로그가 못 따라갔다).
   debug.log('daemon-tools.self-implement', 'done', { runId: result.runId, stage: result.stage, ok: result.ok, pr: result.prUrl ?? null });
-  return result;
+  return !result.ok
+    ? buildFailedToolResult(result.detail ?? result.stage, result)
+    : result.runId ? buildLaunchedToolResult(result) : buildPendingToolResult(result);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    debug.log('daemon-tools.self-implement', 'failed', { reason, stage: 'dispatch' });
+    return buildFailedToolResult(reason);
+  }
 }