makdoong2-team 2.3.1 → 3.0.0

package/dist/opencode-plugin.js

@@ -16,7 +16,7 @@
 // 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";
@@ -26,15 +26,16 @@ import { classifyVerifierOutcome, nextVerifierErrorStreak, verifierErrorStreakEx
 import { nextModel, applyConfigOverrides, POLICIES } from "./model-fallback-policy.js";
 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, 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.
@@ -113,7 +114,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",
@@ -598,10 +598,19 @@ 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(),
+    ];
+    logger.debug(`[permission] plugin-own allows: ${pluginOwnPatterns.length}개 ` +
+        `(${pluginOwnPatterns.join(", ")})`);
     logger.debug(`[permission] configured external_directory allows: ${configuredAllowPatterns.length}개` +
         (configuredAllowPatterns.length ? ` (${configuredAllowPatterns.slice(0, 3).join(", ")}…)` : ""));
     const sessionLastToolExecuteAt = new Map();
@@ -657,6 +666,23 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         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);
@@ -879,8 +905,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
@@ -912,10 +936,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 위임은
         // 동일하게 금지 — 수집·마스킹·등록 전 과정을 자기 세션에서 완결해야 하며,
         // 위임하면 마스킹·승인 게이트가 위임처에서 우회될 수 있다.
@@ -928,7 +948,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",
@@ -1008,9 +1027,23 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             await spawnPaneForSession(sid);
         },
         "chat.params": async (input) => {
-            if (input.sessionID && input.agent) {
-                sessionAgent.set(input.sessionID, input.agent);
+            if (!input.sessionID || !input.agent)
+                return;
+            // 정체성은 downgrade 하지 않는다 (2차 방어).
+            // sessionAgent 는 sealed 서브에이전트 판정의 입력이므로, 한 번 sealed 로
+            // 확정된 세션이 makdoong2 소속이 아닌 이름으로 덮어써지면 그 세션의
+            // outer-world 차단·산출물 경로 제한이 조용히 풀린다. agent 를 빠뜨린
+            // 프롬프트 하나로 그렇게 되어선 안 된다 — 실제로 NUDGE 가 그랬다 (issue #9).
+            // 호출부(1차 방어)는 전부 agent 를 싣지만, 새 호출부가 또 빠뜨려도
+            // 보안 속성은 유지되어야 한다.
+            const known = sessionAgent.get(input.sessionID);
+            if (known && SEALED_SUBAGENTS.has(known) && !SEALED_SUBAGENTS.has(input.agent)) {
+                logger.warn(`[makdoong2-team hook] chat.params agent downgrade ignored: session=${input.sessionID} ` +
+                    `known="${known}" incoming="${input.agent}" — sealed 정체성을 유지한다. ` +
+                    `이 프롬프트 호출부가 agent 를 싣지 않았을 가능성이 높다.`);
+                return;
             }
+            sessionAgent.set(input.sessionID, input.agent);
         },
         // ─────────────────────────────────────────────────────────────
         // PreToolUse — block destructive bash, gate `git push`,
@@ -1143,31 +1176,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 단계로 넘겨라.`);
                     }
                 }
@@ -1312,23 +1376,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;
+                        }
                     }
                 }
             }
@@ -1808,18 +1878,26 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             logger.debug(`[dispatch_stage] engineer session ready — ` +
                                 `session_id=${subSessionID} stage=${args.target_stage} attempt=${attempt}\n` +
                                 `  monitor: opencode attach http://127.0.0.1:44707 --session ${subSessionID}`);
+                            // 종전 문구는 2번에서 state.sh 마커 기록을 요구하면서 마지막 줄에서
+                            // "새 tool 호출 추가 금지" 라고 못박아 서로 모순됐다. 실제로 planner 가
+                            // Jira 검증 6/6 을 끝내고도 "마커 기록 전 시한 도달" 이라며 마커를
+                            // 하나도 남기지 않고 종료해 27분이 통째로 버려졌다 (GitHub issue #9).
+                            // 마커 기록은 금지의 예외임을 문구 안에서 명시한다.
                             const nudgeText = [
-                                "⚠ 작업 시한 80% 도달 — 현재 작업을 마무리하고 즉시 세션을 종료하시오.",
+                                "⚠ 작업 시한 80% 도달 — 지금부터는 마커 기록과 요약만 하고 즉시 세션을 종료하시오.",
                                 "",
-                                "허용된 남은 작업:",
-                                "1. 진행 중인 단일 tool call 완료",
-                                `2. bash ${SCRIPTS_DIR}/state.sh 로 .done 마커 확인 후 완료 시 true 설정`,
+                                "순서대로 수행:",
+                                "1. 진행 중인 단일 tool call 만 마무리한다. 새 조사·탐색·구현은 시작하지 않는다.",
+                                `2. **이미 끝낸 작업의 state.json 마커를 지금 전부 기록한다.** bash ${SCRIPTS_DIR}/state.sh set 호출은`,
+                                "   아래 금지 규칙의 예외이며 필요한 횟수만큼 호출한다. 완료한 substage 는 .done=true 까지 기록한다.",
+                                "   마커 없이 종료하면 그 작업은 수행되지 않은 것으로 판정되어 substage 전체가 처음부터 재실행된다",
+                                "   — 지금까지의 결과가 통째로 버려진다. 기록할 시간이 없다는 판단은 하지 말 것.",
                                 "3. 3줄 이상 한국어 요약 텍스트 출력:",
                                 "   - 처리한 substage 결과 (완료/차단/조기종료)",
                                 "   - 변경한 state.json 마커 목록",
                                 "   - 다음 단계 안내",
                                 "",
-                                "금지: 새 tool 호출 추가. 요약 텍스트 출력 직후 즉시 종료.",
+                                "금지: 새로운 조사·구현 tool 호출. 허용: state.sh 마커 기록. 요약 출력 직후 즉시 종료.",
                             ].join("\n");
                             const engineerNudge = async (sid, elapsedMs) => {
                                 logger.debug(`[dispatch_stage] NUDGE sid=${sid} elapsed=${Math.round(elapsedMs / 1000)}s`);
@@ -1827,6 +1905,13 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     .promptAsync({
                                     path: { id: sid },
                                     body: {
+                                        // agent 를 빼면 opencode 가 기본 에이전트(`build`)로 이 turn 을
+                                        // 돌리고, `chat.params` 가 sessionAgent[sid] 를 그 값으로 덮어쓴다.
+                                        // 그 순간부터 이 세션은 sealed sub-agent 로 인식되지 않아
+                                        // outer-world 위임 차단과 산출물 경로 제한이 전부 풀린다.
+                                        // 실측 로그에서 NUDGE 직후 bash 호출이 agent="build" 로 기록됐다
+                                        // (GitHub issue #9 부수 관찰). 여기서만 누락돼 있었다.
+                                        agent: spec.id,
                                         parts: [{ type: "text", text: nudgeText }],
                                         model: { providerID: activeProviderID, modelID: activeModelID },
                                     },
@@ -2028,30 +2113,60 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                 }
                             }
                             promptPromise.catch(() => { });
-                            if (success) {
-                                // hang_history 리셋 조건은 "dispatch 정상 반환" 이 아니라 "substage
-                                // 실제 완료(done=true)" 다. 종전에는 세션이 텍스트만 뱉고 done=false
-                                // 로 끝나도 리셋됐고, 재-dispatch 를 반복하는 동안 이력이 매번
-                                // 비워져 stall_escalate_threshold 가 사실상 도달 불가였다 (issue #8).
-                                // cwd 는 effectiveWorktree — 이 substage 의 다른 state.json 접근과
-                                // 같은 파일을 봐야 한다 (args.worktree 를 쓰면 교정 발동 시 갈린다).
-                                const resetDonePath = `${stageJqPath(args.target_stage)}.done`;
-                                const resetDoneR = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${resetDonePath}`
+                            // 완료 판정은 sub-agent 의 문장이 아니라 substage 마커로 한다 (issue #9).
+                            // pollSubSession 의 kind="text" 는 "최종 turn 이 나왔다" 일 뿐이고,
+                            // 예산을 다 쓰고 "조기종료 — 마커 기록 없음" 이라고 말한 세션도 같은 kind 를
+                            // 낸다. 그 둘을 구분하는 유일한 값이 게이트·verifier 가 읽는 그 .done 이다.
+                            // cwd 는 effectiveWorktree — 이 substage 의 다른 state.json 접근과
+                            // 같은 파일을 봐야 한다 (args.worktree 를 쓰면 교정 발동 시 갈린다).
+                            const readMarker = async (field) => {
+                                const r = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${`${stageJqPath(args.target_stage)}.${field}`}`
                                     .cwd(effectiveWorktree).quiet().nothrow();
-                                const resetDoneValue = resetDoneR.exitCode === 0
-                                    ? (resetDoneR.stdout?.toString().trim() ?? null)
-                                    : null;
-                                if (resetDoneValue === "true") {
-                                    const resetPath = `${stageJqPath(args.target_stage)}.hang_history`;
-                                    const resetR = await $ `bash ${SCRIPTS_DIR}/state.sh set ${args.issue} ${resetPath} ${"[]"}`
-                                        .cwd(effectiveWorktree).quiet().nothrow();
-                                    logger.debug(`[hang_history] reset issue=${args.issue} stage=${args.target_stage} ` +
-                                        `exit=${resetR.exitCode} — substage done=true`);
-                                }
-                                else {
-                                    logger.debug(`[hang_history] reset skipped issue=${args.issue} stage=${args.target_stage} ` +
-                                        `done=${resetDoneValue} — dispatch 는 정상 반환했지만 substage 미완료`);
-                                }
+                                return r.exitCode === 0 ? (r.stdout?.toString().trim() ?? null) : null;
+                            };
+                            const completion = classifyStageCompletion({
+                                outcomeKind: finalOutcome.kind,
+                                success,
+                                doneValue: success ? await readMarker("done") : null,
+                                interviewRequiredValue: success ? await readMarker("interview_required") : null,
+                            });
+                            if (completion.resetHangHistory) {
+                                // 리셋 조건은 "dispatch 정상 반환" 이 아니라 "substage 실제 완료(done=true)"
+                                // 다. 종전에는 세션이 텍스트만 뱉고 done=false 로 끝나도 리셋됐고,
+                                // 재-dispatch 를 반복하는 동안 이력이 매번 비워져
+                                // stall_escalate_threshold 가 사실상 도달 불가였다 (issue #8).
+                                const resetPath = `${stageJqPath(args.target_stage)}.hang_history`;
+                                const resetR = await $ `bash ${SCRIPTS_DIR}/state.sh set ${args.issue} ${resetPath} ${"[]"}`
+                                    .cwd(effectiveWorktree).quiet().nothrow();
+                                logger.debug(`[hang_history] reset issue=${args.issue} stage=${args.target_stage} ` +
+                                    `exit=${resetR.exitCode} — substage done=true`);
+                            }
+                            else if (success) {
+                                logger.debug(`[hang_history] reset skipped issue=${args.issue} stage=${args.target_stage} ` +
+                                    `completion=${completion.completion} — dispatch 는 정상 반환했지만 substage 미완료`);
+                            }
+                            if (completion.recordHang) {
+                                // hang_history 는 dispatch_stage 호출 사이를 넘어 살아남는 유일한
+                                // 카운터다. 여기에 남기지 않으면 이 실패 모드는 cross-call 상한
+                                // (stall_escalate_threshold) 에 영영 도달하지 못하고, 매 호출이
+                                // 타임아웃 전체를 태우며 무한히 재실행된다 (issue #9).
+                                const incompleteEntry = JSON.stringify({
+                                    attempt,
+                                    at: new Date().toISOString(),
+                                    reason: INCOMPLETE_HANG_REASON,
+                                    elapsed_ms: finalOutcome.elapsedMs,
+                                    polls: finalOutcome.polls,
+                                    session_id: subSessionID,
+                                    model: activeModelFull,
+                                    fallback_depth: activeFallbackDepth,
+                                    final: true,
+                                });
+                                const incompleteJqPath = stageJqPath(args.target_stage) + ".hang_history";
+                                const incompleteR = await $ `bash ${SCRIPTS_DIR}/state.sh append ${args.issue} ${incompleteJqPath} ${incompleteEntry}`
+                                    .cwd(effectiveWorktree).quiet().nothrow();
+                                logger.warn(`[dispatch_stage] STAGE_INCOMPLETE issue=${args.issue} stage=${args.target_stage} ` +
+                                    `session=${subSessionID} outcome_kind=${finalOutcome.kind} elapsed_ms=${finalOutcome.elapsedMs} ` +
+                                    `— 최종 텍스트는 나왔으나 .done=false. hang_history append exit=${incompleteR.exitCode}`);
                             }
                             const retryDisallowed = finalOutcome.kind === "timeout" &&
                                 finalOutcome.transientFailures === 0;
@@ -2061,7 +2176,7 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     `동일 dispatch_stage 를 재호출하지 말고 사용자에게 상황을 보고한 뒤 지시를 기다리거나 get_fallback_model 로 다른 모델을 요청하세요.`
                                 : undefined;
                             finalResultJson = JSON.stringify({
-                                ok: success,
+                                ok: completion.ok,
                                 stage: args.target_stage,
                                 agent: spec.id,
                                 model: activeModelFull,
@@ -2071,6 +2186,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                 fallback_depth: activeFallbackDepth,
                                 output: finalLegacy.text.slice(0, 8000),
                                 outcome_kind: finalOutcome.kind,
+                                // 완료 여부는 이 두 필드로 읽는다. output 문구를 해석하지 말 것 (issue #9).
+                                stage_done: completion.stageDone,
+                                completion: completion.completion,
                                 polls: finalOutcome.polls,
                                 elapsed_ms: finalOutcome.elapsedMs,
                                 transient_failures: finalOutcome.kind === "timeout"
@@ -2078,9 +2196,10 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     : undefined,
                                 retry_disallowed: retryDisallowed || undefined,
                                 retry_disallowed_reason: retryDisallowedReason,
-                                reason: success
+                                next_action: completion.nextAction,
+                                reason: completion.ok
                                     ? overriddenReason
-                                    : finalLegacy.text,
+                                    : (completion.incompleteReason ?? finalLegacy.text),
                             });
                         }
                         finally {
@@ -2425,259 +2544,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;
-                    logger.debug(`[dispatch_research] fan-out done issue=${args.issue} ok=${okCount}/${outcomes.length} ` +
-                        `findings=${artifact.counts.findings_total} elapsed_ms=${Date.now() - startedAll}`);
-                    return JSON.stringify({
-                        // 부분 성공도 ok=true. 한 소스가 죽었다고 나머지 조사 결과를 버리면
-                        // fan-out 의 실패 격리가 의미를 잃는다. 호출자는 failed 배열을 본다.
-                        ok: okCount > 0,
-                        issue: args.issue,
-                        artifact_path: artifactWritten ? relPath : null,
-                        artifact_error: artifactError,
-                        elapsed_ms: Date.now() - startedAll,
-                        counts: artifact.counts,
-                        summary: summarizeOutcomes(outcomes),
-                        failed: outcomes.filter((o) => o.status === "failed").map((o) => ({
-                            source: o.source,
-                            error: o.error,
-                        })),
-                        rejected,
-                        deferred,
-                        next_action: okCount > 0
-                            ? `조사 결과를 읽고 요구사항 체크리스트에 반영하라: ${relPath}`
-                            : "모든 소스 조사가 실패했다. failed 사유를 사용자에게 보고하라.",
-                    });
-                },
-            }),
             get_fallback_model: tool({
                 description: "Return the next model in this agent's fallback chain after a failure (rate_limit/5xx/context_exceeded).",
                 args: {
@@ -2771,8 +2637,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();
@@ -2785,10 +2667,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 를 호출하지 마세요.`,
                         });