makdoong2-team 2.3.2 → 3.0.1

package/dist/opencode-plugin.js

@@ -16,11 +16,12 @@
 // Install path (default): ~/.config/opencode/plugins/makdoong2-team/
 // Place this file at ~/.config/opencode/plugins/makdoong2-team/src/opencode-plugin.ts
 // (or load the npm package via opencode.json "plugin": ["./plugins/makdoong2-team/src/opencode-plugin.ts"]).
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename as pathBasename, dirname as pathDirname, join, resolve as pathResolve, sep as pathSep } from "node:path";
 import { tool } from "@opencode-ai/plugin";
 import { appendSessionIndex, findWorktreeRoot, lookupSessionFromIndex } from "./session-index.js";
+import { activeToolCount, clearToolCalls, forgetSession, isToolExecuting as registryIsToolExecuting, normalizePermissionEvent, notifySessionDeleted, pendingPermissionsFor, permissionAsked, permissionReplied, settleToolCalls, sharedSubSessionRegistry, toolFinished, toolStarted, } from "./sub-session-registry.js";
 import { computeVerdictHash } from "./verdict-hash.js";
 import { classifyVerifierOutcome, nextVerifierErrorStreak, verifierErrorStreakExceeded, VERIFIER_ERROR_STREAK_LIMIT, } from "./verifier-verdict.js";
 import { nextModel, applyConfigOverrides, POLICIES } from "./model-fallback-policy.js";
@@ -28,14 +29,14 @@ import { agentForStage, STAGE_SPEC_FILES } from "./agent-stage-config.js";
 import { shouldEscalateStall } from "./stall-escalation.js";
 import { classifyStageCompletion, INCOMPLETE_HANG_REASON } from "./stage-completion.js";
 import { buildStateWriteBlockMessage, classifyStateJsonAccess, looksLikeRedirection, splitUnquotedSegments, WRITE_INDICATORS_UNQUOTED, STATE_SH_CALL_RE, stripQuotedSpans, } from "./state-access-guard.js";
-import { RESEARCH_SOURCES, DEFAULT_RESEARCH_TIMEOUT_MINUTES, buildResearchPrompt, classifyFanoutOutcome, mergeResearchFindings, normalizeQueries, parseResearchOutput, resolveParallelism, summarizeOutcomes, } from "./research-fanout.js";
 import { TmuxMonitor, readTmuxConfig, orphanCleanupGuard } from "./tmux-monitor.js";
-import { resolvePaths, loadConfig, loadOpencodeExternalDirAllows, readLoggingConfig, DEFAULT_STALL_ESCALATE_THRESHOLD, } from "./config.js";
+import { resolvePaths, loadConfig, loadOpencodeExternalDirAllows, pluginOwnAllowPatterns, readLoggingConfig, DEFAULT_STALL_ESCALATE_THRESHOLD, } from "./config.js";
 import { scanSkillMcpRegistry, extractMcpName, looksLikeMcpNotFound, looksLikeMcpConnectionFailed, } from "./skill-mcp-registry.js";
 import { injectAllSecrets } from "./mcp-secret-injector.js";
 import { pollSubSession as pollSubSessionCore, pollOutcomeToLegacy } from "./poll-sub-session.js";
 import { logger } from "./logger.js";
 import { redactAndTruncate } from "./redact-secrets.js";
+import { extractApplyPatchPaths, isApplyPatchTool } from "./apply-patch-paths.js";
 import { issueReporterSkillLoadViolation, issueReporterTaskSpawnViolation, ISSUE_REPORTER_AGENT, classifyGithubApiCall, payloadDisplayPaths, displayMismatch, sha256Hex, } from "./issue-reporter-guard.js";
 // All runtime paths come from makdoong2-team.json (paths.* overrides) or are
 // derived from the opencode config dir. No MAKDOONG2 environment variables.
@@ -114,7 +115,6 @@ export function shouldOverrideSessionGoneOutcome(outcomeKind, currentSuccess, do
 const STAGE_ORDER = [
     "1_planning.jira",
     "1_planning.requirements",
-    "1_planning.scope",
     "2_implementation.analysis",
     "2_implementation.dev",
     "2_implementation.test",
@@ -328,6 +328,15 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const cwd = worktree || directory || ".";
     const config = loadConfig();
     applyConfigOverrides(config.agents, config.model_policy);
+    // opencode 는 디렉토리(Instance)마다 이 factory 를 따로 부른다 — 같은 pid 안에
+    // 사본이 여럿이다. 어느 사본이 어떤 로그를 찍는지 구분하려고 진입 시점에 남긴다.
+    // 로그에 worktree 경로의 `[init]` 이 없으면 서브세션 훅이 어디서도 발화하지
+    // 않는 것이고, 그것이 issue #10 의 `tool_call_stall` 처방 1번이다.
+    logger.debug(`[init] plugin instance directory=${directory} worktree=${worktree} pid=${process.pid}`);
+    // 사본을 가로지르는 세션 신호(툴 실행 · 권한 요청 · 이슈키 · worktree · deleted
+    // 대기자)는 프로세스 전역 레지스트리에 둔다. 사본마다 Map 을 들면 worktree 사본의
+    // 훅이 올린 신호를 main 사본의 폴러가 영영 보지 못한다 (issue #10).
+    const registry = sharedSubSessionRegistry();
     // Sub-session monitor — splits a tmux pane next to 부장님 for each spawned
     // 막둥이 when invoked inside tmux with tmux.enabled=true in makdoong2-team.json.
     // No-op otherwise, so non-tmux runs are unaffected.
@@ -423,8 +432,8 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 const guard = orphanCleanupGuard(p, {
                     nowMs,
                     ownerPid: tmuxMonitor.ownerProcessId,
-                    lastToolExecuteAtMs: sessionLastToolExecuteAt.get(sid),
-                    activeToolCount: sessionActiveToolCount.get(sid),
+                    lastToolExecuteAtMs: registry.lastToolExecuteAt.get(sid),
+                    activeToolCount: activeToolCount(registry, sid),
                     toolAliveWindowMs: TOOL_EXECUTE_ALIVE_WINDOW_MS,
                 });
                 if (guard) {
@@ -449,11 +458,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 if (sessionGone) {
                     logger.debug(`[orphan-scan] pane-kill-only (session gone) sid=${sid} reason=${reason}`);
                     await tmuxMonitor.forceKillBySessionId(sid).catch(() => undefined);
-                    sessionIssue.delete(sid);
+                    forgetSession(registry, sid);
                     pendingDispatch.delete(sid);
                     subSessionIds.delete(sid);
-                    sessionLastToolExecuteAt.delete(sid);
-                    sessionActiveToolCount.delete(sid);
                 }
                 else {
                     logger.debug(`[orphan-scan] cleaning sid=${sid} reason=${reason}`);
@@ -599,29 +606,38 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     // threshold caps the accumulated hang_history across calls — the stall-path
     // counterpart of same_reason_streak on the REJECTED-verdict path.
     const stallEscalateThreshold = Math.max(1, Math.round(config.timeout?.stall_escalate_threshold ?? DEFAULT_STALL_ESCALATE_THRESHOLD));
-    // 사용자가 opencode.json 에 명시적으로 allow 한 외부 디렉터리 패턴.
-    // 종전에는 makdoong2-team.json(=`config`)에서 읽어 **항상 빈 배열**이었다 —
-    // 그 스키마에는 permission 키가 없다. 자세한 내용은 config.ts 의 함수 주석 참조.
-    const configuredAllowPatterns = loadOpencodeExternalDirAllows();
+    // 자동 승인 대상 외부 디렉터리 패턴 = 플러그인 자기 경로(항상) + 사용자 시드.
+    //
+    // 앞쪽이 2차 방어다: 설치가 opencode.json 패치를 남기지 못해도 서브에이전트가
+    // state.sh / 게이트 / stage spec 에 접근할 수 있어야 한다 (GitHub #8 의 부분 설치가
+    // PERMISSION_STALL 로 나타나던 경로). 뒤쪽은 사용자가 opencode.json 에 명시적으로
+    // allow 한 것 — 종전에는 makdoong2-team.json 에서 읽어 **항상 빈 배열**이었다.
+    const pluginOwnPatterns = pluginOwnAllowPatterns();
+    const configuredAllowPatterns = [
+        ...pluginOwnPatterns,
+        ...loadOpencodeExternalDirAllows((reason) => logger.warn(`[permission] opencode.json external_directory allows unavailable — ${reason} directory=${directory}`)),
+    ];
+    // 사본마다 한 번씩 찍힌다 — 같은 pid 에 개수가 다른 두 줄이 있으면 사본이
+    // 둘이라는 뜻이지 설정이 바뀐 것이 아니다 (issue #10 의 7개→5개). directory 를
+    // 같이 남겨 어느 사본이 몇 개를 읽었는지 바로 대응시킨다.
+    logger.debug(`[permission] plugin-own allows: ${pluginOwnPatterns.length}개 ` +
+        `(${pluginOwnPatterns.join(", ")}) directory=${directory}`);
     logger.debug(`[permission] configured external_directory allows: ${configuredAllowPatterns.length}개` +
-        (configuredAllowPatterns.length ? ` (${configuredAllowPatterns.slice(0, 3).join(", ")}…)` : ""));
-    const sessionLastToolExecuteAt = new Map();
-    const sessionActiveToolCount = new Map();
-    /** 활성 툴 카운터를 1 감소시킨다 (0 이면 항목 삭제). */
-    function releaseActiveTool(sid) {
-        const cur = sessionActiveToolCount.get(sid) ?? 0;
-        if (cur <= 1)
-            sessionActiveToolCount.delete(sid);
-        else
-            sessionActiveToolCount.set(sid, cur - 1);
-    }
+        (configuredAllowPatterns.length ? ` (${configuredAllowPatterns.slice(0, 3).join(", ")}…)` : "") +
+        ` directory=${directory}`);
+    // 툴 실행 신호는 레지스트리(`registry.activeToolCalls` / `lastToolExecuteAt`)에
+    // 있다 — before 훅에서 toolStarted, after 훅·툴 part 종결·idle 에서 toolFinished /
+    // clearToolCalls. 종전의 사본-로컬 카운터는 issue #10 으로 제거됐다.
     const TOOL_EXECUTE_ALIVE_WINDOW_MS = 300_000;
     // MESSAGE_STALL 후 client.session.abort() 는 즉시 반환하지만 opencode 서버는 잠시 후
     // session.deleted 이벤트를 fire 한다. 그 사이(관측 최대 112s) sub-agent 가 tool call 을
     // 계속 발사할 수 있어 좀비 실행이 발생한다. abort 직후 session.deleted 를 대기하는
     // 헬퍼로 이 race window 를 닫는다. event 핸들러가 session.deleted 를 수신하면 이 map 의
     // pending waiter 를 resolve 한다.
-    const sessionDeletedWaiters = new Map();
+    // 대기자 목록은 레지스트리에 있다 — session.deleted 이벤트는 세션의 디렉토리
+    // 사본에만 도착하므로(worktree 서브세션이면 worktree 사본), 여기서 기다리는
+    // main 사본과 이벤트를 받는 사본이 같은 목록을 봐야 한다.
+    const sessionDeletedWaiters = registry.sessionDeletedWaiters;
     const waitForSessionDeleted = (sessionId, maxWaitMs) => {
         return new Promise((resolve) => {
             let done = false;
@@ -651,13 +667,32 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const SESSION_DELETED_WAIT_MS = 30_000;
     const eventMaxChars = readLoggingConfig(config.logging).eventMaxChars;
     const WRITE_TOOLS = new Set(["write", "edit", "apply_patch"]);
-    const sessionWorktree = new Map();
+    // dispatch 사본이 채우고 worktree 사본의 tool.execute.after 가 읽는다 — 레지스트리.
+    // 디스크의 session-index.ndjson 은 사본이 다른 프로세스에 있을 때의 2차 경로로 남는다.
+    const sessionWorktree = registry.sessionWorktree;
     const extractFilePathFromToolArgs = (args) => {
         if (!args || typeof args !== "object")
             return undefined;
         const fp = args.filePath;
         return typeof fp === "string" && fp.length > 0 ? fp : undefined;
     };
+    // 쓰기 툴이 건드리는 **모든** 대상 경로. write/edit 는 filePath 하나지만
+    // apply_patch 는 패치 본문 안에 여러 개가 들어 있다 — opencode 가 gpt-5 계열
+    // 세션에서 write/edit 대신 apply_patch 만 노출하므로(src/apply-patch-paths.ts
+    // 주석 참조) filePath 만 보는 코드는 그 세션에서 전부 장님이 된다.
+    //
+    // 반환: paths=대상 목록, resolved=대상을 확정했는가.
+    // resolved=false 는 "쓰기인데 대상을 모른다" 이고 정책상 차단이 기본값이다.
+    const extractWriteTargets = (toolName, args) => {
+        if (isApplyPatchTool(toolName)) {
+            const parsed = extractApplyPatchPaths(args);
+            return parsed.ok
+                ? { paths: parsed.paths, resolved: true }
+                : { paths: [], resolved: false, reason: parsed.reason };
+        }
+        const fp = extractFilePathFromToolArgs(args);
+        return fp ? { paths: [fp], resolved: true } : { paths: [], resolved: false, reason: "no_file_path" };
+    };
     const trackAndStageEngineerWrite = async (sessionID, filePath) => {
         let wt = sessionWorktree.get(sessionID) ?? pendingDispatch.get(sessionID)?.worktree;
         let issue = sessionIssue.get(sessionID);
@@ -724,7 +759,41 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         }
         return { ok: true, relPath };
     };
-    const pollSubSession = (sessionId, timeoutMs = substageTimeoutMs, allowedWorktree, onNudge, messageStallThresholdMs) => pollSubSessionCore(client, sessionId, {
+    // 폴러에 건네는 권한 요청 소스. v1 SDK 클라이언트에는 `permission` 네임스페이스가
+    // 없고, `GET /permission` 은 클라이언트가 묶인 디렉토리 스코프라 worktree
+    // 서브세션의 요청이 보이지 않는다 — 종전에는 이 소스가 항상 undefined 라
+    // 자동 승인·거부 루프가 한 번도 돌지 않았고 stall 메시지는 언제나 "unknown" 이었다
+    // (issue #10). 대신 그 세션의 사본이 `permission.asked` 이벤트로 레지스트리에
+    // 넣은 것을 읽고, 응답은 세션-라우팅 엔드포인트
+    // (`POST /session/{id}/permissions/{permissionID}`) 로 보낸다 — 세션 ID 로
+    // 라우팅되므로 어느 사본에서 불러도 맞는 Instance 에 닿는다.
+    const permissionSourceFor = (sessionId) => ({
+        list: async () => ({
+            data: pendingPermissionsFor(registry, sessionId).map((p) => ({
+                id: p.id,
+                sessionID: p.sessionID,
+                permission: p.permission,
+                patterns: p.patterns,
+            })),
+        }),
+        reply: async (req) => {
+            const c = client;
+            if (typeof c.postSessionIdPermissionsPermissionId !== "function") {
+                throw new Error("permission reply endpoint unavailable on this client");
+            }
+            const res = await c.postSessionIdPermissionsPermissionId({
+                path: { id: sessionId, permissionID: req.path.requestID },
+                body: { response: req.body.reply },
+            });
+            // permission.replied 이벤트는 세션의 사본에 도착하지만, 그 사본이 이벤트를
+            // 놓치더라도 다음 폴이 같은 요청을 다시 처리하지 않도록 즉시 뺀다.
+            permissionReplied(registry, sessionId, req.path.requestID);
+            return res;
+        },
+    });
+    const pollSubSession = (sessionId, timeoutMs = substageTimeoutMs, allowedWorktree, onNudge, messageStallThresholdMs) => 
+    // 클래스 인스턴스를 spread 하면 프로토타입 메서드가 빠지므로 필요한 것만 집는다.
+    pollSubSessionCore({ session: client.session, permission: permissionSourceFor(sessionId) }, sessionId, {
         timeoutMs,
         allowedWorktree,
         configuredAllowPatterns,
@@ -739,16 +808,26 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         contentStableCompletionMs: 300_000,
         preambleOnlyTextThreshold: 200,
         isRecentlyActive: () => {
-            if ((sessionActiveToolCount.get(sessionId) ?? 0) > 0)
+            if (registryIsToolExecuting(registry, sessionId))
                 return true;
-            const last = sessionLastToolExecuteAt.get(sessionId);
+            const last = registry.lastToolExecuteAt.get(sessionId);
             return typeof last === "number" && Date.now() - last < TOOL_EXECUTE_ALIVE_WINDOW_MS;
         },
-        // "지금 이 순간 툴이 실행 중인가" — before 훅에서 올리고 after 훅에서 내리는
-        // 활성 카운터 그대로다. isRecentlyActive 의 5분 창과 달리 순간값이라 완료
+        // "지금 이 순간 툴이 실행 중인가" — before 훅에서 넣고 after 훅에서 빼는
+        // callID 집합 그대로다. isRecentlyActive 의 5분 창과 달리 순간값이라 완료
         // 판정에 쓸 수 있다. 폴러가 읽는 메시지 스냅샷보다 항상 앞선다 (issue #7:
         // tool.execute.before 발화 110ms 뒤의 폴이 tool part 를 아직 못 봤다).
-        isToolExecuting: () => (sessionActiveToolCount.get(sessionId) ?? 0) > 0,
+        //
+        // 읽기 전에 스냅샷과 대조한다: 툴이 throw 하면 after 훅이 오지 않아 항목이
+        // 남는데, 스냅샷에서 이미 completed/error 인 callID 는 확실히 끝난 것이다.
+        // 스냅샷에 아직 없는 callID 는 그대로 둔다 (110ms 창).
+        isToolExecuting: (snapshot) => {
+            const settled = settleToolCalls(registry, sessionId, snapshot.settledCallIDs);
+            if (settled > 0) {
+                logger.debug(`[pollSubSession] settled ${settled} stale tool call(s) from snapshot sid=${sessionId}`);
+            }
+            return registryIsToolExecuting(registry, sessionId);
+        },
     });
     // ── sessionID → agent 매핑. chat.params hook에서 채우고, tool.execute.before
     //    hook에서 조회한다. 이 매핑을 통해 hook input에 없는 agent 식별을 우회한다.
@@ -771,7 +850,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     // git branch 이름이나 worktree 경로를 추론하지 않고 신뢰할 수 있는 ISSUE를
     // 직접 전달받을 수 있다. 이 설계로 multi-worktree / 비-makdoong2-team 워크트리
     // 오탐 문제가 근본적으로 해결된다.
-    const sessionIssue = new Map();
+    // 레지스트리에 둔다 — dispatch 사본이 넣고, 서브세션의 훅 사본(guard-bash.sh /
+    // sync-state.sh 인자)이 읽는다.
+    const sessionIssue = registry.sessionIssue;
     // ── skill_mcp lazy-load 방어 (mcp_name → skill_name 매핑).
     //    SKILL.md frontmatter 를 스캔해 각 MCP 서버가 어떤 skill 에 embedded 인지
     //    캐시한다. `skill(name="...")` 로 skill 이 로드되기 전에는 opencode 가
@@ -848,11 +929,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             }
         }
         finally {
-            sessionIssue.delete(sid);
+            forgetSession(registry, sid);
             pendingDispatch.delete(sid);
             subSessionIds.delete(sid);
-            sessionLastToolExecuteAt.delete(sid);
-            sessionActiveToolCount.delete(sid);
         }
     };
     // team-leader가 직접 실행 시 물리적으로 차단할 툴 목록.
@@ -880,8 +959,6 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         ["makdoong2-publisher", /(^|\/)\.makdoong2-team\/[^/]+\/(change-report\.md|review-comment-plan\.json)$/],
         // planner: 요구사항 초안 · 리서치 산출물
         ["makdoong2-planner", /(^|\/)\.makdoong2-team\/[^/]+\/[^/]+\.(md|json)$/],
-        // researcher: 쓰기 없음
-        ["makdoong2-researcher", null],
     ]);
     // ══════════════════════════════════════════════════════════════════════════
     // Sealed Workflow Enforcement — Outer-World Tool Blocking
@@ -913,10 +990,6 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         "makdoong2-engineer",
         "makdoong2-publisher",
         "makdoong2-verifier",
-        // Research fan-out worker. Sealed like every other sub-agent: its frontmatter
-        // already omits Task (L1), but sealed workflow is defence in depth — a worker
-        // missing here would be caught by nothing at runtime (L2).
-        "makdoong2-researcher",
         // User-only issue reporter. 워크플로우에 참여하지 않지만 outer-world 위임은
         // 동일하게 금지 — 수집·마스킹·등록 전 과정을 자기 세션에서 완결해야 하며,
         // 위임하면 마스킹·승인 게이트가 위임처에서 우회될 수 있다.
@@ -929,7 +1002,6 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const KNOWN_SAFE_TOOLS = new Set([
         "dispatch_stage",
         "dispatch_verifier",
-        "dispatch_research",
         "verify_stage",
         "auto_advance_stage",
         "get_fallback_model",
@@ -974,26 +1046,72 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         }
     })();
     return {
+        // 이벤트는 **세션의 디렉토리 사본**에만 도착한다 (opencode 의 이벤트 브리지가
+        // `location.directory` 로 필터링한다). worktree 서브세션의 permission.asked ·
+        // message.part.updated · session.deleted 는 worktree 사본이 받고, 그 세션을
+        // 폴링하는 것은 main 사본이다. 그래서 여기서 관측한 것은 전부 레지스트리에
+        // 쓴다 — 사본-로컬 변수에 쓰면 폴러는 영영 보지 못한다 (issue #10).
         event: async ({ event }) => {
-            if (logger.isDebug() && event?.type?.startsWith("session.")) {
+            if (logger.isDebug() && (event?.type?.startsWith("session.") || event?.type?.startsWith("permission."))) {
                 try {
-                    logger.debug(`[event] type=${event.type} properties=${JSON.stringify(event.properties).slice(0, eventMaxChars)}`);
+                    logger.debug(`[event] type=${event.type} directory=${directory} properties=${JSON.stringify(event.properties).slice(0, eventMaxChars)}`);
                 }
                 catch { /* ignore */ }
             }
+            if (event?.type === "permission.asked" || event?.type === "permission.updated") {
+                const req = normalizePermissionEvent(event.type, event.properties);
+                if (req) {
+                    permissionAsked(registry, req);
+                    logger.debug(`[event] permission pending sid=${req.sessionID} requestID=${req.id} ` +
+                        `permission=${req.permission} patterns=${JSON.stringify(req.patterns)}`);
+                }
+                return;
+            }
+            if (event?.type === "permission.replied") {
+                const props = event.properties;
+                const sid = typeof props?.sessionID === "string" ? props.sessionID : undefined;
+                const requestID = typeof props?.requestID === "string" ? props.requestID
+                    : typeof props?.permissionID === "string" ? props.permissionID
+                        : undefined;
+                if (sid && requestID)
+                    permissionReplied(registry, sid, requestID);
+                return;
+            }
+            if (event?.type === "message.part.updated") {
+                // 툴 part 가 completed/error 로 바뀌면 그 호출은 끝났다. 툴이 throw 한
+                // 경우 tool.execute.after 가 오지 않으므로 이것이 유일한 종결 신호다.
+                const props = event.properties;
+                const part = props?.part;
+                if (part && part.type === "tool") {
+                    const state = part.state;
+                    const status = typeof state?.status === "string" ? state.status : undefined;
+                    if (status === "completed" || status === "error") {
+                        const sid = typeof part.sessionID === "string" ? part.sessionID
+                            : typeof props?.sessionID === "string" ? props.sessionID
+                                : undefined;
+                        const callID = typeof part.callID === "string" ? part.callID : undefined;
+                        if (sid)
+                            toolFinished(registry, sid, callID);
+                    }
+                }
+                return;
+            }
+            if (event?.type === "session.idle") {
+                // idle 로 전이한 세션에 실행 중인 툴은 정의상 없다 — 남은 항목은 전부 누수다.
+                const props = event.properties;
+                if (typeof props?.sessionID === "string")
+                    clearToolCalls(registry, props.sessionID);
+                return;
+            }
             if (event?.type === "session.deleted") {
                 const props = event.properties;
                 const sid = props?.info?.id ?? props?.sessionID;
                 if (sid) {
-                    const waiters = sessionDeletedWaiters.get(sid);
-                    if (waiters && waiters.length > 0) {
-                        for (const w of [...waiters]) {
-                            try {
-                                w();
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
+                    notifySessionDeleted(registry, sid);
+                    // 세션이 사라졌으니 실행 신호·권한 요청도 의미가 없다. sessionIssue /
+                    // sessionWorktree 는 dispatch 사본의 cleanupSubSession 이 지운다.
+                    clearToolCalls(registry, sid);
+                    registry.pendingPermissions.delete(sid);
                 }
                 return;
             }
@@ -1048,16 +1166,17 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 : undefined;
             const toolLower = (input.tool || "").toLowerCase();
             logger.debug(`[makdoong2-team hook] tool.execute.before fired: tool="${input.tool}" sessionID="${sessionID}" agent="${agent ?? "unknown"}" callID="${input.callID}"`);
-            // 활성 툴 카운터는 **증분과 감소가 반드시 짝을 이뤄야 한다**.
+            // 활성 툴 집합은 **넣기와 빼기가 반드시 짝을 이뤄야 한다**.
             // tool.execute.after 는 툴이 실제로 실행된 뒤에만 돈다. 아래 가드들이 throw 하면
             // (차단된 bash · sealed 서브에이전트의 outer-world 툴 · leader 의 파일 쓰기 등)
-            // after 훅이 돌지 않아 카운터가 영구히 ≥1 로 남고, 그러면 isRecentlyActive() 가
+            // after 훅이 돌지 않아 항목이 영구히 남고, 그러면 isRecentlyActive() 가
             // 항상 true 가 되어 그 세션의 gone 감지와 orphan 회수가 **영구 비활성**된다.
             // 차단은 정상 동작이라 반드시 일어나므로 확정적으로 누수됐다.
-            if (sessionID) {
-                sessionLastToolExecuteAt.set(sessionID, Date.now());
-                sessionActiveToolCount.set(sessionID, (sessionActiveToolCount.get(sessionID) ?? 0) + 1);
-            }
+            // (툴 자체가 throw 하는 경우 — 권한 거부 · 파일 없음 — 는 여기서 잡을 수 없다.
+            // 그쪽은 폴러가 스냅샷의 completed/error part 로 정리한다: settleToolCalls.)
+            const activeToolKey = sessionID
+                ? toolStarted(registry, sessionID, input.callID)
+                : undefined;
             try {
                 if (sessionID && (toolLower === "dispatch_stage" || toolLower === "dispatch_verifier")) {
                     const callID = input.callID;
@@ -1158,31 +1277,62 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                         }
                     }
                 }
+                // ── Universal state.json hardrule (write 계열 툴) ──
+                // bash 우회는 classifyStateJsonAccess 가 막지만 쓰기 **툴**은 종전에 무방비였다.
+                // 산출물 허용 패턴(.makdoong2-team/<이슈키>/*.json)이 state.json 을 포함하므로
+                // 여기서 명시적으로 도려낸다 — state.json 쓰기는 오직 state.sh 를 통해서만 한다.
+                if (LEADER_FORBIDDEN_TOOLS.has(toolLower) || WRITE_TOOLS.has(toolLower)) {
+                    const stateTargets = extractWriteTargets(toolLower, output.args);
+                    const hit = stateTargets.paths
+                        .map((p) => p.replace(/\\/g, "/"))
+                        .find((p) => /(^|\/)\.makdoong2-team\/[^/]+\/state\.json$/.test(p));
+                    if (hit) {
+                        logger.error(`[makdoong2-team hook] BLOCKED: state.json 을 '${input.tool}' 툴로 쓰려 했다 ` +
+                            `(agent="${agent ?? "unknown"}", path="${hit}")`);
+                        throw new Error(`[makdoong2-team state hardrule] state.json 은 '${input.tool}' 툴로 쓸 수 없다 ("${hit}").\n` +
+                            `마커 기록은 반드시 'bash ${SCRIPTS_DIR}/state.sh set <이슈키> <키경로> <값>' 으로 하라. ` +
+                            `읽기는 'bash ${SCRIPTS_DIR}/state.sh get' / 'status' 를 쓴다.`);
+                    }
+                }
                 // ── 산출물 제한 서브에이전트의 write 계열 툴 차단 ──
                 //
-                // filePath 를 추출할 수 없으면(예: apply_patch — 경로가 패치 본문 안에
-                // 있다) 보수적으로 차단한다. 이 방향이 안전하다: 산출물이 제한된
-                // 에이전트가 대상 불명의 패치를 미는 것 자체가 정책 위반이고, 이들은
-                // 산출물을 Write 툴(filePath 인자 보유)로만 만든다. 실제로 네 에이전트
-                // 모두 frontmatter 에서 Patch 툴이 비활성이라 이 경로는 도달 불가에 가깝다.
+                // 판정 대상은 **툴이 건드리는 모든 경로**다. write/edit 는 filePath 하나,
+                // apply_patch 는 패치 본문에서 파싱한 목록이다 — 후자를 "대상 불명" 으로
+                // 뭉뚱그려 차단하면, opencode 가 write/edit 를 노출하지 않는 gpt-5 계열
+                // 세션에서는 산출물을 만들 합법적 수단이 하나도 남지 않아 워크플로가
+                // 구조적으로 정지한다 (GitHub #8 재발).
+                //
+                // 대상을 **확정하지 못한** 경우(패치 파싱 실패 등)에는 종전대로 차단한다.
+                // 미탐에는 복구 수단이 없고 오탐에는 안내가 있다.
                 if (agent && ARTIFACT_RESTRICTED_AGENTS.has(agent)
                     && (LEADER_FORBIDDEN_TOOLS.has(toolLower) || WRITE_TOOLS.has(toolLower))) {
                     const allowed = ARTIFACT_RESTRICTED_AGENTS.get(agent) ?? null;
-                    const filePath = extractFilePathFromToolArgs(output.args);
-                    const normalized = (filePath ?? "").replace(/\\/g, "/");
-                    const permitted = allowed !== null && normalized !== "" && allowed.test(normalized);
+                    const targets = extractWriteTargets(toolLower, output.args);
+                    const normalized = targets.paths.map((p) => p.replace(/\\/g, "/"));
+                    const permitted = allowed !== null
+                        && targets.resolved
+                        && normalized.length > 0
+                        && normalized.every((p) => allowed.test(p));
                     if (!permitted) {
+                        const shown = normalized.length > 0
+                            ? normalized.join(", ")
+                            : `unknown(${targets.reason ?? "no_target"})`;
                         logger.error(`[makdoong2-team hook] BLOCKED: ${agent} 가 허용되지 않은 대상에 ` +
-                            `${input.tool} 을 시도했다 (filePath=${filePath ?? "unknown"})`);
+                            `${input.tool} 을 시도했다 (targets=${shown})`);
                         throw new Error(`[makdoong2-team artifact hardrule] "${agent}" 는 '${input.tool}' 로 ` +
-                            `${filePath ? `"${filePath}" 에 ` : ""}쓸 수 없다.\n` +
+                            `${normalized.length > 0 ? `"${shown}" 에 ` : ""}쓸 수 없다.\n` +
                             (allowed === null
                                 ? `이 에이전트는 파일을 쓰지 않는다 — 조사 결과는 최종 응답 텍스트로 반환하라.\n`
                                 : `허용된 산출물은 .makdoong2-team/<이슈키>/ 아래의 지정된 파일뿐이다 ` +
                                     `(패턴: ${allowed.source}).\n` +
-                                    `그 경로에는 지금 즉시 'write' 툴(filePath 인자)로 쓸 수 있다 — ` +
-                                    `bash 리디렉션·apply_patch 우회가 차단된 것이지 산출물 쓰기 자체가 금지된 것이 아니다. ` +
-                                    `산출물이 필요하면 포기하지 말고 write 툴로 재시도하라.\n`) +
+                                    (targets.resolved
+                                        ? `대상 경로를 허용 패턴 안으로 바꿔 **지금 즉시 재시도**하라 — ` +
+                                            `산출물 쓰기 자체가 금지된 것이 아니다.\n`
+                                        : `이번 호출은 대상 경로를 확정하지 못해 차단됐다(${targets.reason ?? "unknown"}). ` +
+                                            `'write' 툴이 있으면 filePath 로 직접 쓰고, 없으면 apply_patch 본문을 ` +
+                                            `'*** Begin Patch' / '*** Add File: <허용 경로>' / '*** End Patch' 형식으로 ` +
+                                            `정확히 작성해 재시도하라 — 형식이 맞으면 허용 경로에 대해 통과한다.\n`) +
+                                    `bash 리디렉션 우회는 어느 경우에도 차단된다. 포기하지 말고 위 경로로 재시도하라.\n`) +
                             `소스 코드 변경이 필요하면 그 사실을 산출물/응답에 적고 engineer 단계로 넘겨라.`);
                     }
                 }
@@ -1273,9 +1423,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 }
             }
             catch (err) {
-                // 차단으로 끝난 호출은 실행되지 않았다 → 증분을 되돌린다.
+                // 차단으로 끝난 호출은 실행되지 않았다 → 넣은 항목을 되돌린다.
                 if (sessionID)
-                    releaseActiveTool(sessionID);
+                    toolFinished(registry, sessionID, activeToolKey);
                 throw err;
             }
         },
@@ -1288,8 +1438,7 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             const toolLowerAfter = (input.tool || "").toLowerCase();
             const afterSessionID = input.sessionID;
             if (afterSessionID) {
-                sessionLastToolExecuteAt.set(afterSessionID, Date.now());
-                releaseActiveTool(afterSessionID);
+                toolFinished(registry, afterSessionID, input.callID);
             }
             // ── Issue-reporter 표시 증명 기록·소멸 ──
             // 기록: 단독 `cat <payload>` 가 실행되면 그 시점의 파일 해시를 남긴다. 이
@@ -1327,23 +1476,29 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             if (afterSessionID && WRITE_TOOLS.has(toolLowerAfter)) {
                 const agentAfter = sessionAgent.get(afterSessionID)
                     ?? pendingDispatch.get(afterSessionID)?.agent;
-                const filePath = extractFilePathFromToolArgs(input.args);
+                // apply_patch 는 filePath 인자가 없다 — 패치 본문에서 대상을 뽑는다.
+                // gpt-5 계열 세션에는 write/edit 가 아예 없어 engineer 의 모든 편집이
+                // 이 경로로 오므로, filePath 만 보면 auto git add 가 통째로 무력화되고
+                // dev exit gate 가 unstaged 파일로 하드 차단된다.
+                const targets = extractWriteTargets(toolLowerAfter, input.args);
                 logger.debug(`[auto-git-add-hook] tool=${toolLowerAfter} session=${afterSessionID} ` +
-                    `agent=${agentAfter ?? "unknown"} filePath=${filePath ?? "N/A"} ` +
+                    `agent=${agentAfter ?? "unknown"} targets=${targets.paths.length > 0 ? targets.paths.join(",") : `N/A(${targets.reason ?? "none"})`} ` +
                     `wt=${sessionWorktree.get(afterSessionID) ?? pendingDispatch.get(afterSessionID)?.worktree ?? "N/A"} ` +
                     `issue=${sessionIssue.get(afterSessionID) ?? "N/A"}`);
-                if (agentAfter === "makdoong2-engineer" && filePath) {
-                    const result = await trackAndStageEngineerWrite(afterSessionID, filePath)
-                        .catch((err) => ({
-                        ok: false,
-                        relPath: filePath,
-                        error: `hook exception: ${err?.message ?? String(err)}`,
-                    }));
-                    if (!result.ok && result.relPath) {
-                        const warn = `\n\n[makdoong2-team] auto git add FAILED for "${result.relPath}": ${redactAndTruncate(result.error ?? "", 200)}\n` +
-                            `→ 조치: bash 로 'git add -- ${result.relPath}' 를 직접 실행해 stage 하시오. dev exit gate 가 unstaged 파일을 차단한다.`;
-                        const outAny = output;
-                        outAny.output = (outAny.output ?? "") + warn;
+                if (agentAfter === "makdoong2-engineer") {
+                    for (const filePath of targets.paths) {
+                        const result = await trackAndStageEngineerWrite(afterSessionID, filePath)
+                            .catch((err) => ({
+                            ok: false,
+                            relPath: filePath,
+                            error: `hook exception: ${err?.message ?? String(err)}`,
+                        }));
+                        if (!result.ok && result.relPath) {
+                            const warn = `\n\n[makdoong2-team] auto git add FAILED for "${result.relPath}": ${redactAndTruncate(result.error ?? "", 200)}\n` +
+                                `→ 조치: bash 로 'git add -- ${result.relPath}' 를 직접 실행해 stage 하시오. dev exit gate 가 unstaged 파일을 차단한다.`;
+                            const outAny = output;
+                            outAny.output = (outAny.output ?? "") + warn;
+                        }
                     }
                 }
             }
@@ -2489,267 +2644,6 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
              * get_fallback_model — fallback advisor.
              * Returns the next model in the chain, or exhausted=true.
              */
-            /**
-             * dispatch_research — parallel multi-source research fan-out.
-             *
-             * Why the plugin does the fan-out instead of the agent: sealed sub-agents
-             * cannot delegate (ARCHITECTURE.md §4.2), and a prompt asking the model to
-             * "call the sources in parallel" cannot be enforced — the model may call
-             * them one at a time and nothing detects it. Doing it in code makes the
-             * parallelism deterministic, and gives each source its own session so one
-             * source's material never crowds out another's (DESIGN.md §3.7).
-             *
-             * Failure is isolated per source: one source failing yields a partial
-             * artifact plus an explicit failure row, never an aborted fan-out.
-             */
-            dispatch_research: tool({
-                description: "여러 리서치 소스(jira / confluence / bitbucket / github-oss)를 병렬 서브세션으로 동시 조사하고 " +
-                    "결과를 research-findings.json 으로 병합한다. 소스별 컨텍스트가 격리되며 한 소스의 실패가 " +
-                    "다른 소스를 막지 않는다. 1_planning.requirements 의 다출처 교차 조사에 사용.",
-                args: {
-                    issue: tool.schema.string().describe("Jira issue key"),
-                    worktree: tool.schema.string().describe("작업 디렉토리 절대경로 (state.sh 실행 컨텍스트)"),
-                    queries: tool.schema
-                        .array(tool.schema.object({
-                        source: tool.schema
-                            .string()
-                            .describe("jira | confluence | bitbucket | github-oss"),
-                        focus: tool.schema
-                            .string()
-                            .describe("이 소스에서 확인할 것. 구체적일수록 좋다."),
-                    }))
-                        .describe("소스별 조사 지시. 동시 실행되므로 서로 의존하면 안 된다."),
-                    context: tool.schema
-                        .string()
-                        .optional()
-                        .describe("모든 조사 세션에 공통 주입할 배경 (예: Jira 요약)"),
-                },
-                async execute(args, context) {
-                    const startedAll = Date.now();
-                    const parallelLimit = resolveParallelism(config.research?.max_parallel);
-                    const { queries, rejected, deferred } = normalizeQueries(args.queries, parallelLimit);
-                    if (queries.length === 0) {
-                        return JSON.stringify({
-                            ok: false,
-                            reason: "실행 가능한 query 가 없다.",
-                            rejected,
-                            deferred,
-                            allowed_sources: Object.keys(RESEARCH_SOURCES),
-                        });
-                    }
-                    const parentSessionID = context?.sessionID ?? dispatchParentSessionID(undefined);
-                    if (!parentSessionID) {
-                        return JSON.stringify({
-                            ok: false,
-                            reason: "dispatch_research 호출자의 sessionID를 얻지 못했다.",
-                        });
-                    }
-                    const researcherId = "makdoong2-researcher";
-                    // Recursion guard: a research session must never start its own fan-out.
-                    // The researcher's frontmatter omits this tool (L1), but a fan-out that
-                    // could nest would multiply sessions without bound, so it is refused at
-                    // runtime too — same defence-in-depth reasoning as SEALED_SUBAGENTS.
-                    if (sessionAgent.get(parentSessionID) === researcherId) {
-                        logger.error(`[dispatch_research] BLOCKED: researcher session ${parentSessionID} attempted a nested fan-out`);
-                        return JSON.stringify({
-                            ok: false,
-                            reason: "리서치 세션은 dispatch_research 를 다시 호출할 수 없다 (중첩 fan-out 금지). " +
-                                "배정받은 소스만 조사하고 JSON 을 반환하라.",
-                        });
-                    }
-                    const policy = POLICIES[researcherId];
-                    if (!policy) {
-                        return JSON.stringify({
-                            ok: false,
-                            reason: `POLICIES 에 ${researcherId} 항목이 없다. 모델 정책 설정을 확인하라.`,
-                        });
-                    }
-                    const [providerID, ...modelRest] = policy.primary.id.split("/");
-                    const modelID = modelRest.join("/");
-                    const timeoutMs = Math.max(60_000, Math.round((config.research?.timeout_minutes ?? DEFAULT_RESEARCH_TIMEOUT_MINUTES) * 60_000));
-                    logger.debug(`[dispatch_research] fan-out start issue=${args.issue} sources=` +
-                        `${queries.map((q) => q.spec.source).join(",")} parallel_limit=${parallelLimit} ` +
-                        `timeout_ms=${timeoutMs} parentID=${parentSessionID}`);
-                    const runOne = async (q) => {
-                        const startedAt = Date.now();
-                        const base = {
-                            source: q.spec.source,
-                            label: q.spec.label,
-                            focus: q.focus,
-                            session_id: null,
-                            elapsed_ms: 0,
-                        };
-                        const fail = (error, sid) => ({
-                            ...base,
-                            session_id: sid,
-                            elapsed_ms: Date.now() - startedAt,
-                            status: "failed",
-                            findings: [],
-                            gaps: [],
-                            error,
-                        });
-                        const createResult = await client.session
-                            .create({
-                            body: {
-                                parentID: parentSessionID,
-                                title: `research:${q.spec.source} (${args.issue})`,
-                            },
-                            query: { directory: args.worktree },
-                        })
-                            .catch((e) => ({ error: e, data: null }));
-                        if (createResult.error || !createResult.data) {
-                            return fail(`session create 실패: ${JSON.stringify(createResult.error)}`, null);
-                        }
-                        const sid = createResult.data.id;
-                        sessionIssue.set(sid, args.issue);
-                        subSessionIds.add(sid);
-                        sessionWorktree.set(sid, args.worktree);
-                        pendingDispatch.set(sid, {
-                            stage: `research:${q.spec.source}`,
-                            agent: researcherId,
-                            worktree: args.worktree,
-                            startedAt,
-                        });
-                        appendSessionIndex({
-                            sessionID: sid,
-                            agent: researcherId,
-                            worktree: args.worktree,
-                            issue: args.issue,
-                            stage: `research:${q.spec.source}`,
-                            createdAt: new Date().toISOString(),
-                        });
-                        let outcomeText = "";
-                        try {
-                            const promptText = buildResearchPrompt(q, {
-                                issue: args.issue,
-                                scriptsDir: SCRIPTS_DIR,
-                                worktree: args.worktree,
-                                context: args.context,
-                            });
-                            const promptPromise = client.session
-                                .prompt({
-                                path: { id: sid },
-                                body: {
-                                    agent: researcherId,
-                                    tools: { question: false },
-                                    parts: [{ type: "text", text: promptText }],
-                                    model: { providerID, modelID },
-                                },
-                                query: { directory: args.worktree },
-                            })
-                                .catch((e) => ({ error: e }));
-                            const early = await Promise.race([
-                                promptPromise,
-                                new Promise((r) => setTimeout(() => r("pending"), 2_000)),
-                            ]);
-                            if (early !== "pending" && early?.error) {
-                                return fail(`prompt 실패: ${JSON.stringify(early.error)}`, sid);
-                            }
-                            await spawnPaneForSession(sid);
-                            const outcome = await pollSubSession(sid, timeoutMs, args.worktree);
-                            const legacy = pollOutcomeToLegacy(outcome);
-                            outcomeText = legacy.text;
-                            promptPromise.catch(() => { });
-                            if (outcome.kind === "session_gone") {
-                                await cleanupSubSession(sid, {
-                                    success: false,
-                                    reason: `research ${q.spec.source} session_gone`,
-                                    skipSessionOps: outcome.reason !== "message_stall",
-                                });
-                                return fail(`세션 종료 (${outcome.reason ?? "status_absent"})`, sid);
-                            }
-                            if (outcome.kind === "timeout") {
-                                await cleanupSubSession(sid, {
-                                    success: false,
-                                    reason: `research ${q.spec.source} timeout`,
-                                });
-                                return fail(`시간 초과 (${Math.round(timeoutMs / 60_000)}분)`, sid);
-                            }
-                            const parsed = parseResearchOutput(outcomeText);
-                            await cleanupSubSession(sid, { success: parsed.ok });
-                            if (!parsed.ok) {
-                                return fail(`출력 파싱 실패: ${parsed.reason}`, sid);
-                            }
-                            return {
-                                ...base,
-                                session_id: sid,
-                                elapsed_ms: Date.now() - startedAt,
-                                status: "ok",
-                                findings: parsed.data.findings,
-                                gaps: parsed.data.gaps,
-                                error: null,
-                            };
-                        }
-                        catch (e) {
-                            await cleanupSubSession(sid, {
-                                success: false,
-                                reason: `research ${q.spec.source} threw`,
-                            }).catch(() => undefined);
-                            return fail(`예외: ${e instanceof Error ? e.message : String(e)}`, sid);
-                        }
-                    };
-                    // Promise.all, not a loop: the whole point is that the sources run at
-                    // the same time. runOne never rejects (every path returns an outcome),
-                    // so one source cannot take the others down with it.
-                    const outcomes = await Promise.all(queries.map(runOne));
-                    const artifact = mergeResearchFindings(args.issue, new Date().toISOString(), outcomes, rejected, deferred);
-                    // state.json 산출물 경로는 상대경로만 저장한다 (ARCHITECTURE.md §5.3).
-                    const relPath = `.makdoong2-team/${args.issue}/research-findings.json`;
-                    let artifactWritten = false;
-                    let artifactError = null;
-                    try {
-                        const absDir = join(args.worktree, ".makdoong2-team", args.issue);
-                        mkdirSync(absDir, { recursive: true });
-                        writeFileSync(join(absDir, "research-findings.json"), JSON.stringify(artifact, null, 2));
-                        artifactWritten = true;
-                    }
-                    catch (e) {
-                        artifactError = e instanceof Error ? e.message : String(e);
-                        logger.error(`[dispatch_research] artifact write 실패: ${artifactError}`);
-                    }
-                    if (artifactWritten) {
-                        // cwd 는 반드시 args.worktree — state.sh root() 가 cwd 의 git toplevel 을
-                        // 쓰므로 여기서 어긋나면 다른 state.json 에 기록된다 (ARCHITECTURE.md §10.2).
-                        const setR = await $ `bash ${SCRIPTS_DIR}/state.sh set ${args.issue} ${'.stages."1_planning".substages."requirements".research_path'} ${JSON.stringify(relPath)}`
-                            .cwd(args.worktree).quiet().nothrow();
-                        if (setR.exitCode !== 0) {
-                            logger.debug(`[dispatch_research] research_path 마커 기록 실패 exit=${setR.exitCode} ` +
-                                `stderr=${redactAndTruncate(setR.stderr?.toString() ?? "", 160)}`);
-                        }
-                    }
-                    const okCount = artifact.counts.ok;
-                    const failedOutcomes = outcomes.filter((o) => o.status === "failed");
-                    const fanout = classifyFanoutOutcome(artifact.counts, artifactWritten ? relPath : null, failedOutcomes.map((o) => o.label));
-                    logger.debug(`[dispatch_research] fan-out done issue=${args.issue} ok=${okCount}/${outcomes.length} ` +
-                        `findings=${artifact.counts.findings_total} status=${fanout.status} ` +
-                        `elapsed_ms=${Date.now() - startedAll}`);
-                    if (fanout.partial) {
-                        // debug 가 아니라 warn — 기본 로깅 레벨에서도 보여야 하는 결손이다.
-                        logger.warn(`[dispatch_research] PARTIAL issue=${args.issue} ok=${okCount}/${artifact.counts.requested} ` +
-                            `failed=${failedOutcomes.map((o) => `${o.source}:${o.error ?? "unknown"}`).join(" | ")}`);
-                    }
-                    return JSON.stringify({
-                        // 부분 성공도 ok=true. 한 소스가 죽었다고 나머지 조사 결과를 버리면
-                        // fan-out 의 실패 격리가 의미를 잃는다. 결손은 status/partial 로 알린다.
-                        ok: fanout.ok,
-                        status: fanout.status,
-                        partial: fanout.partial,
-                        issue: args.issue,
-                        artifact_path: artifactWritten ? relPath : null,
-                        artifact_error: artifactError,
-                        elapsed_ms: Date.now() - startedAll,
-                        counts: artifact.counts,
-                        summary: summarizeOutcomes(outcomes),
-                        failed: failedOutcomes.map((o) => ({
-                            source: o.source,
-                            error: o.error,
-                        })),
-                        rejected,
-                        deferred,
-                        next_action: fanout.next_action,
-                    });
-                },
-            }),
             get_fallback_model: tool({
                 description: "Return the next model in this agent's fallback chain after a failure (rate_limit/5xx/context_exceeded).",
                 args: {
@@ -2843,8 +2737,24 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                     // current=null 로 남아 target_stage="1_planning.jira" 로 되돌아가는
                     // silent regression 이 발생한다. `.issue` 필드를 probe 하여 이 상황을
                     // 명시적 에러로 분리한다.
-                    const probe = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${".issue"}`
+                    let probe = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${".issue"}`
                         .cwd(effectiveCwd).quiet().nothrow();
+                    // ── 자가 복구 1회: forward sync 는 플러그인 몫이다 ──
+                    // worktree cwd 에서 state.json 이 안 보이는 가장 흔한 원인은 forward sync
+                    // 미수행이다. 종전에는 그 복구를 next_action 으로 **team-leader 에게 시켰는데**,
+                    // 그 안내 문구에 worktree 절대경로가 박혀 있었다. opencode 는 bash 명령이
+                    // 참조하는 디렉토리마다 external_directory 승인을 묻으므로(ARCHITECTURE §4.2a),
+                    // 리더가 그 명령을 실행하는 순간 primary 세션이 사용자에게 승인을 물었다 —
+                    // 정작 다른 모든 동기화는 플러그인이 조용히 처리하는데 이 경로만 예외였다.
+                    // 여기서 직접 한 번 시도하면 승인 요청도, 왕복도 사라진다.
+                    if (probe.exitCode !== 0 && args.worktree && args.worktree !== cwd) {
+                        const heal = await $ `bash ${SCRIPTS_DIR}/wt-sync-ignored.sh ${args.worktree} ${args.issue}`
+                            .cwd(effectiveCwd).quiet().nothrow();
+                        probe = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${".issue"}`
+                            .cwd(effectiveCwd).quiet().nothrow();
+                        logger.debug(`[wt-sync] SELF_HEAL issue=${args.issue} worktree=${args.worktree} ` +
+                            `sync_exit=${heal.exitCode} probe_after=${probe.exitCode}`);
+                    }
                     if (probe.exitCode !== 0) {
                         const rootR = await $ `bash ${SCRIPTS_DIR}/state.sh root`
                             .cwd(effectiveCwd).quiet().nothrow();
@@ -2857,10 +2767,14 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             effective_cwd: effectiveCwd,
                             reason: `state.json 을 판독할 수 없습니다. worktree cwd 기준 예상 경로: ${expectedPath}. ` +
                                 `주요 원인: (1) wt-sync-ignored.sh 로 worktree 동기화 미수행, (2) 다른 cwd(main repo)에서 state.json 을 조작하여 worktree 사본과 불일치, (3) state.json 손상.`,
-                            next_action: `① 먼저 'bash ${SCRIPTS_DIR}/state.sh status ${args.issue}' 로 존재/유효성을 확인하세요 ` +
+                            // 안내에 **절대경로를 싣지 않는다.** 리더가 그 경로를 명령에 넣어 실행하면
+                            // primary 세션이 external_directory 승인을 사용자에게 묻는다. 아래 명령은
+                            // 전부 cwd 기준으로 동작하므로 경로 인자가 필요 없다.
+                            next_action: `동기화는 이미 1회 자동 시도했고 실패했습니다 — 같은 동기화를 직접 실행하지 마세요. ` +
+                                `① 먼저 'bash ${SCRIPTS_DIR}/state.sh status ${args.issue}' 로 존재/유효성을 확인하세요 ` +
                                 `(승인된 읽기 명령입니다 — 훅이 차단하지 않습니다). ` +
-                                `② exists=false 면 'bash ${SCRIPTS_DIR}/wt-sync-ignored.sh ${effectiveCwd} ${args.issue}' 로 재동기화하거나, ` +
-                                `'bash ${SCRIPTS_DIR}/state.sh init ${args.issue} ${effectiveCwd}' 로 초기화하세요. ` +
+                                `② exists=false 면 'bash ${SCRIPTS_DIR}/state.sh init ${args.issue}' 로 초기화하세요 ` +
+                                `(경로 인자 없이 — cwd 의 git toplevel 을 자동으로 씁니다). ` +
                                 `③ readable=false (JSON 손상) 면 사용자에게 에스컬레이션하세요. ` +
                                 `근본 원인이 해소되기 전에는 dispatch_stage 를 호출하지 마세요.`,
                         });