makdoong2-team 2.3.2 → 3.0.1

package/dist/poll-sub-session.d.ts

@@ -5,6 +5,19 @@ export type MessagePartLike = {
     state?: {
         status?: string;
     };
+    /** ToolPart 의 호출 ID — `tool.execute.before/after` 훅의 callID 와 같은 값. */
+    callID?: string;
+};
+/**
+ * 폴 시점 스냅샷에서 읽은 툴 호출 상태. `isToolExecuting` 에 넘겨 훅 레지스트리와
+ * 대조하게 한다 — throw 로 끝난 툴은 after 훅이 돌지 않아 레지스트리에 남는데,
+ * 스냅샷의 completed/error part 가 그 호출이 끝났음을 확정해 준다.
+ */
+export type ToolSnapshot = {
+    /** completed / error 로 끝난 호출 ID (스냅샷 전체 메시지 기준). */
+    settledCallIDs: ReadonlySet<string>;
+    /** pending / running 인 호출 ID (마지막 assistant 메시지 기준). */
+    inFlightCallIDs: ReadonlySet<string>;
 };
 export type MessageInfoLike = {
     id?: string;
@@ -56,6 +69,7 @@ export interface PollClientLike {
         }) => Promise<unknown>;
     };
 }
+export type PermissionStallReason = "outside_allowed_roots" | "non_external_permission" | "tool_call_stall";
 export type PollOutcome = {
     kind: "text";
     text: string;
@@ -84,6 +98,7 @@ export type PollOutcome = {
     permissionID?: string;
     permissionType?: string;
     permissionPatterns?: string[];
+    permissionReason?: PermissionStallReason;
 } | {
     kind: "session_gone";
     polls: number;
@@ -107,7 +122,7 @@ export interface PollOptions {
     messageStallThresholdMs?: number;
     statusAbsentGraceMs?: number;
     isRecentlyActive?: () => boolean;
-    isToolExecuting?: () => boolean;
+    isToolExecuting?: (snapshot: ToolSnapshot) => boolean;
     contentStableCompletionMs?: number;
     preambleOnlyTextThreshold?: number;
     nudgeAtFraction?: number;

package/dist/poll-sub-session.js

@@ -29,6 +29,37 @@
 const TOOL_CALL_PART_TYPES = new Set(["tool", "tool_call", "tool-call", "tool_use"]);
 /** 아직 끝나지 않은 툴 상태 (ToolStatePending / ToolStateRunning). */
 const IN_FLIGHT_TOOL_STATUSES = new Set(["pending", "running"]);
+/** 확실히 끝난 툴 상태 (ToolStateCompleted / ToolStateError). */
+const SETTLED_TOOL_STATUSES = new Set(["completed", "error"]);
+/**
+ * 스냅샷에서 툴 호출 ID 를 상태별로 모은다. settled 는 전체 메시지를 훑는다 —
+ * 레지스트리에 남은 항목은 이전 turn 의 호출일 수도 있다. inFlight 는 마지막
+ * assistant 메시지만 본다 (`hasPendingToolCall` 과 같은 기준).
+ */
+function collectToolSnapshot(messages, lastAssistant) {
+    const settledCallIDs = new Set();
+    const inFlightCallIDs = new Set();
+    for (const m of messages) {
+        if (m.info?.role !== "assistant")
+            continue;
+        for (const part of m.parts ?? []) {
+            if (!TOOL_CALL_PART_TYPES.has(part.type))
+                continue;
+            if (typeof part.callID !== "string" || part.callID.length === 0)
+                continue;
+            const status = part.state?.status;
+            if (typeof status === "string" && SETTLED_TOOL_STATUSES.has(status))
+                settledCallIDs.add(part.callID);
+        }
+    }
+    for (const part of lastAssistant?.parts ?? []) {
+        if (!isInFlightToolPart(part))
+            continue;
+        if (typeof part.callID === "string" && part.callID.length > 0)
+            inFlightCallIDs.add(part.callID);
+    }
+    return { settledCallIDs, inFlightCallIDs };
+}
 /**
  * "지금 실행 중인 툴 호출이 있는가".
  *
@@ -236,7 +267,9 @@ export async function pollSubSession(client, sessionId, options = {}) {
         // 둘 중 하나라도 "툴이 떠 있다" 고 하면 완료로 판정하지 않는다 — 스냅샷은
         // 서버 반영이 늦고(issue #7), 훅 신호는 훅이 안 붙은 환경에서 아예 없다.
         // OR 로 묶어야 각자의 사각지대를 서로 덮는다.
-        const toolExecuting = isToolExecuting?.() === true;
+        const toolExecuting = isToolExecuting
+            ? isToolExecuting(collectToolSnapshot(messages, lastAssistant)) === true
+            : false;
         const toolInFlight = hasPendingToolCall || toolExecuting;
         const stalledMs = now() - lastProgressAt;
         // session_gone (status_absent) has two admission paths with different
@@ -314,9 +347,15 @@ export async function pollSubSession(client, sessionId, options = {}) {
                         .catch(() => undefined);
                 }
                 else {
+                    // 두 실패를 뭉뚱그리지 않는다. "허용 경로 밖" 은 대안 경로를 알려주면
+                    // 회복 가능하고, "external_directory 가 아닌 권한" 은 경로와 무관한
+                    // 에이전트 설정 문제라 조치가 정반대다. 종전에는 한 문장이었다.
+                    const reason = p.permission === "external_directory"
+                        ? "outside_allowed_roots"
+                        : "non_external_permission";
                     err(`[pollSubSession] PERMISSION_STALL session=${sessionId} polls=${pollCount}` +
                         ` permissionID=${p.id} type=${p.permission} patterns=${JSON.stringify(p.patterns)}` +
-                        ` — auto-rejecting (outside worktree scope or non-external_directory)`);
+                        ` reason=${reason} — auto-rejecting`);
                     await client.permission
                         .reply({ path: { requestID: p.id }, body: { reply: "reject" } })
                         .catch(() => undefined);
@@ -329,6 +368,7 @@ export async function pollSubSession(client, sessionId, options = {}) {
                         permissionID: p.id,
                         permissionType: p.permission,
                         permissionPatterns: p.patterns,
+                        permissionReason: reason,
                     };
                 }
             }
@@ -369,7 +409,9 @@ export async function pollSubSession(client, sessionId, options = {}) {
             err(`[pollSubSession] PERMISSION_STALL session=${sessionId} polls=${pollCount} stalledMs=${stalledMs}` +
                 (stalledPerm
                     ? ` pending permissionID=${stalledPerm.id} type=${stalledPerm.permission} patterns=${JSON.stringify(stalledPerm.patterns)}`
-                    : ` pending permission unknown (permission.list unavailable or empty)`));
+                    : client.permission
+                        ? ` no pending permission observed for this session (tool part in flight, no tool.execute signal)`
+                        : ` pending permission unknown (permission source unavailable)`));
             await client.session.abort({ path: { id: sessionId } }).catch(() => undefined);
             return {
                 kind: "permission_stall",
@@ -379,6 +421,7 @@ export async function pollSubSession(client, sessionId, options = {}) {
                 permissionID: stalledPerm?.id,
                 permissionType: stalledPerm?.permission,
                 permissionPatterns: stalledPerm?.patterns,
+                permissionReason: "tool_call_stall",
             };
         }
         // Message stall: sub-agent registered (sessionEverAppeared) and appears
@@ -601,17 +644,39 @@ export function pollOutcomeToLegacy(outcome) {
             };
         case "aborted":
             return { text: `(aborted: ${outcome.reason})`, success: false };
-        case "permission_stall":
+        case "permission_stall": {
+            // 사유별로 **처방이 다르다.** 종전에는 셋을 한 문장으로 보고해서, 워크스페이스
+            // 밖 접근(대안 경로를 알려주면 끝날 일)과 부분 설치(재설치가 필요한 일)와
+            // 에이전트 오설정이 전부 같은 메시지로 나왔다.
+            const detail = outcome.permissionType
+                ? `${outcome.permissionType} permission (id=${outcome.permissionID}` +
+                    `${outcome.permissionPatterns ? `, patterns=${JSON.stringify(outcome.permissionPatterns)}` : ""})`
+                : "an unidentified permission request";
+            const remedy = (() => {
+                switch (outcome.permissionReason) {
+                    case "outside_allowed_roots":
+                        return "워크스페이스 밖 경로 접근이라 차단됐다. " +
+                            "임시 파일이 필요하면 `/tmp` 이 아니라 worktree 안의 " +
+                            "`.makdoong2-team/<이슈키>/tmp/` 에 만들어라 — 그 경로는 cwd 안이라 승인이 필요 없고, " +
+                            "git exclude 와 worktree 동기화 대상이다. `/tmp` 에 쓴 것은 동기화도 커밋도 되지 않아 조용히 사라진다.";
+                    case "non_external_permission":
+                        return "external_directory 가 아닌 권한 요청이 서브에이전트에 도달했다 — 경로 문제가 아니라 " +
+                            "에이전트 permission 설정 문제다. 해당 에이전트의 frontmatter `permission:` 블록을 점검하라 " +
+                            "(정식 키는 `edit`; `write` 키는 존재하지 않아 조용히 무시된다).";
+                    default:
+                        return "툴 호출 part 가 떠 있는데 실행 신호(tool.execute.before)도 권한 요청도 관측되지 않았다. 점검: " +
+                            "(1) 세션의 디렉토리에서도 플러그인이 로드되는가 — 로그의 `[init] plugin instance directory=…` 가 " +
+                            "worktree 경로로도 찍혀야 한다 (opencode 는 디렉토리마다 플러그인을 따로 초기화한다) " +
+                            "(2) opencode.json 의 permission.external_directory 시드 (`npx makdoong2-team doctor`).";
+                }
+            })();
             return {
-                text: outcome.permissionType
-                    ? `(permission_stall: sub-agent blocked on ${outcome.permissionType} permission ` +
-                        `(id=${outcome.permissionID}${outcome.permissionPatterns ? `, patterns=${JSON.stringify(outcome.permissionPatterns)}` : ""}) ` +
-                        `— cannot be answered in subagent context; aborted after ${outcome.stalledMs}ms)`
-                    : `(permission_stall: sub-agent tool call stalled for ${outcome.stalledMs}ms — likely waiting for a permission approval ` +
-                        `that cannot be answered in subagent context; pending permission could not be identified (permission.list unavailable or empty). ` +
-                        `점검: opencode.json 의 permission.external_directory 시드 존재 여부 (npx makdoong2-team doctor))`,
+                text: `(permission_stall: sub-agent blocked on ${detail} — cannot be answered in subagent context; ` +
+                    `aborted after ${outcome.stalledMs}ms. reason=${outcome.permissionReason ?? "unknown"})\n` +
+                    `→ ${remedy}`,
                 success: false,
             };
+        }
         case "session_gone":
             return {
                 text: outcome.reason === "message_stall"

package/dist/sub-session-registry.d.ts

@@ -0,0 +1,74 @@
+export type PendingPermission = {
+    id: string;
+    sessionID: string;
+    permission: string;
+    patterns: string[];
+    askedAt: number;
+};
+export interface SubSessionRegistry {
+    readonly version: 1;
+    /** sessionID → (callID → startedAt). before 에서 넣고 after / 툴 part 종결에서 뺀다. */
+    readonly activeToolCalls: Map<string, Map<string, number>>;
+    /** sessionID → 마지막 tool.execute.* 발화 시각. */
+    readonly lastToolExecuteAt: Map<string, number>;
+    /** sessionID → (requestID → 요청). permission.asked 로 넣고 replied 로 뺀다. */
+    readonly pendingPermissions: Map<string, Map<string, PendingPermission>>;
+    /** sessionID → 이슈키. dispatch 사본이 쓰고 훅 사본(guard-bash.sh 인자)이 읽는다. */
+    readonly sessionIssue: Map<string, string>;
+    /** sessionID → worktree 절대경로. auto-git-add 가 읽는다. */
+    readonly sessionWorktree: Map<string, string>;
+    /** session.deleted 대기자. abort 후 재디스패치 전 race window 를 닫는다. */
+    readonly sessionDeletedWaiters: Map<string, Array<() => void>>;
+    /** callID 가 없는 before 훅에 붙일 대체 키 일련번호. */
+    anonSeq: number;
+}
+export declare function createSubSessionRegistry(): SubSessionRegistry;
+/**
+ * 프로세스 전역 레지스트리. 첫 호출이 만들고 이후 호출은 같은 객체를 돌려준다.
+ * 키에 버전을 박아 두어, 형태가 다른 미래 버전이 같은 프로세스에 섞여도 서로의
+ * 객체를 깨뜨리지 않는다.
+ */
+export declare function sharedSubSessionRegistry(): SubSessionRegistry;
+/** 테스트 전용 — 전역 객체를 비운다. */
+export declare function resetSharedSubSessionRegistryForTests(): void;
+/** `tool.execute.before` — 이 세션에서 callID 툴이 실행을 시작했다. 사용한 키를 돌려준다. */
+export declare function toolStarted(reg: SubSessionRegistry, sessionID: string, callID: string | undefined, now?: number): string;
+/**
+ * `tool.execute.after` 또는 툴 part 의 completed/error 관측 — 실행이 끝났다.
+ * 멱등이다: 같은 callID 를 두 번 끝내도, 모르는 callID 를 끝내도 아무 일도 없다.
+ * callID 가 없으면 가장 최근에 시작한 항목을 뺀다 (종전 카운터 의미 유지).
+ */
+export declare function toolFinished(reg: SubSessionRegistry, sessionID: string, callID: string | undefined, now?: number): boolean;
+/**
+ * 메시지 스냅샷과 대조해 이미 끝난 호출을 정리한다.
+ *
+ * 툴이 throw 하면(권한 거부 · 파일 없음 · MCP 오류) opencode 는 `tool.execute.after`
+ * 를 부르지 않는다 — 항목이 영영 남아 `isToolExecuting()` 이 참으로 굳고, 그러면
+ * 완료 판정이 유보돼 substage 가 절대 타임아웃까지 기다린다. 스냅샷의 tool part
+ * 가 completed/error 면 그 호출은 확실히 끝난 것이므로 여기서 뺀다. 스냅샷에
+ * **아직 없는** 호출은 건드리지 않는다 (issue #7 의 110ms 창 — 훅은 발화했는데
+ * 서버가 part 를 아직 반영하지 않은 상태). 정리한 개수를 돌려준다.
+ */
+export declare function settleToolCalls(reg: SubSessionRegistry, sessionID: string, settledCallIDs: Iterable<string>): number;
+/** 지금 이 순간 이 세션에서 실행 중인 툴이 있는가 (순간값). */
+export declare function isToolExecuting(reg: SubSessionRegistry, sessionID: string): boolean;
+export declare function activeToolCount(reg: SubSessionRegistry, sessionID: string): number;
+/** 세션이 idle 로 전이했다 — 실행 중인 툴은 정의상 없다. */
+export declare function clearToolCalls(reg: SubSessionRegistry, sessionID: string): void;
+/**
+ * 플러그인 `event` 훅이 받는 권한 요청 이벤트를 공통 형태로 바꾼다.
+ *
+ * 1.18 v1 브리지는 `permission.asked` 를 `PermissionRequest` 그대로 싣는다
+ * (`id / sessionID / permission / patterns`). 더 오래된 SDK 형태 `permission.updated`
+ * 는 `type` · `pattern`(문자열 또는 배열) 을 쓴다. 둘 다 받아 둔다 — 어느 쪽이 오든
+ * 폴러가 보는 것은 같은 shape 이어야 한다. 요청으로 볼 수 없는 페이로드는 null.
+ */
+export declare function normalizePermissionEvent(type: string, properties: unknown, now?: number): PendingPermission | null;
+export declare function permissionAsked(reg: SubSessionRegistry, req: PendingPermission): void;
+export declare function permissionReplied(reg: SubSessionRegistry, sessionID: string, requestID: string): void;
+/** 이 세션에 답을 기다리는 권한 요청 — 오래된 순. */
+export declare function pendingPermissionsFor(reg: SubSessionRegistry, sessionID: string): PendingPermission[];
+/** 세션 하나의 흔적을 전부 지운다 (cleanupSubSession · session.deleted). */
+export declare function forgetSession(reg: SubSessionRegistry, sessionID: string): void;
+/** session.deleted — 대기자를 전부 깨운다. 깨운 수를 돌려준다. */
+export declare function notifySessionDeleted(reg: SubSessionRegistry, sessionID: string): number;

package/dist/sub-session-registry.js

@@ -0,0 +1,204 @@
+// 프로세스 전역 서브세션 레지스트리 — 플러그인 사본 사이의 공유 신호.
+//
+// opencode 1.18 은 **디렉토리(Instance)마다 플러그인을 따로 초기화한다**.
+// `dispatch_stage` 는 서브세션을 `directory=<worktree>` 로 만들므로 그 세션의
+// `tool.execute.before/after` · `event` 훅은 worktree Instance 의 플러그인 사본에서
+// 발화하고, 그 세션을 감시하는 `pollSubSession` 은 main Instance 의 사본에서 돈다.
+// 사본마다 자기 Map 을 들고 있으면 폴러는 언제나 빈 Map 을 본다 —
+// `isToolExecuting()` 이 영영 false 라 60초를 넘는 모든 툴(sbt test 등)이
+// `permission_stall`(reason=tool_call_stall) 로 abort 됐다 (GitHub issue #10).
+//
+// 그래서 사본을 가로지르는 신호는 전부 여기, `globalThis` 에 둔다. 같은 프로세스
+// 안의 모든 사본이 — 모듈 경로가 달라 module cache 가 갈리더라도 — 한 객체를 본다.
+// 여기 두는 것은 "훅 사본이 쓰고 폴러 사본이 읽는" 세션 단위 신호뿐이다.
+// `pendingDispatch` 같은 디스패치 소유 상태는 공유하지 않는다 — 공유하면 worktree
+// 사본의 `session.created` 핸들러가 pane 을 한 번 더 띄운다.
+//
+// 이 파일은 src/opencode-plugin.ts 에서 import 만 한다 (re-export 금지 —
+// 로더가 모든 named export 를 plugin factory 로 호출한다).
+const SHARED_KEY = Symbol.for("makdoong2-team.sub-session-registry.v1");
+export function createSubSessionRegistry() {
+    return {
+        version: 1,
+        activeToolCalls: new Map(),
+        lastToolExecuteAt: new Map(),
+        pendingPermissions: new Map(),
+        sessionIssue: new Map(),
+        sessionWorktree: new Map(),
+        sessionDeletedWaiters: new Map(),
+        anonSeq: 0,
+    };
+}
+/**
+ * 프로세스 전역 레지스트리. 첫 호출이 만들고 이후 호출은 같은 객체를 돌려준다.
+ * 키에 버전을 박아 두어, 형태가 다른 미래 버전이 같은 프로세스에 섞여도 서로의
+ * 객체를 깨뜨리지 않는다.
+ */
+export function sharedSubSessionRegistry() {
+    const g = globalThis;
+    const existing = g[SHARED_KEY];
+    if (existing && existing.version === 1)
+        return existing;
+    const created = createSubSessionRegistry();
+    g[SHARED_KEY] = created;
+    return created;
+}
+/** 테스트 전용 — 전역 객체를 비운다. */
+export function resetSharedSubSessionRegistryForTests() {
+    delete globalThis[SHARED_KEY];
+}
+// ── 툴 실행 신호 ─────────────────────────────────────────────────────────────
+const ANON_PREFIX = "anon#";
+/** `tool.execute.before` — 이 세션에서 callID 툴이 실행을 시작했다. 사용한 키를 돌려준다. */
+export function toolStarted(reg, sessionID, callID, now = Date.now()) {
+    const key = typeof callID === "string" && callID.length > 0 ? callID : `${ANON_PREFIX}${++reg.anonSeq}`;
+    let calls = reg.activeToolCalls.get(sessionID);
+    if (!calls) {
+        calls = new Map();
+        reg.activeToolCalls.set(sessionID, calls);
+    }
+    calls.set(key, now);
+    reg.lastToolExecuteAt.set(sessionID, now);
+    return key;
+}
+/**
+ * `tool.execute.after` 또는 툴 part 의 completed/error 관측 — 실행이 끝났다.
+ * 멱등이다: 같은 callID 를 두 번 끝내도, 모르는 callID 를 끝내도 아무 일도 없다.
+ * callID 가 없으면 가장 최근에 시작한 항목을 뺀다 (종전 카운터 의미 유지).
+ */
+export function toolFinished(reg, sessionID, callID, now = Date.now()) {
+    reg.lastToolExecuteAt.set(sessionID, now);
+    const calls = reg.activeToolCalls.get(sessionID);
+    if (!calls || calls.size === 0)
+        return false;
+    let key;
+    if (typeof callID === "string" && callID.length > 0) {
+        if (!calls.has(callID))
+            return false;
+        key = callID;
+    }
+    else {
+        let latest = -Infinity;
+        for (const [k, startedAt] of calls) {
+            if (startedAt >= latest) {
+                latest = startedAt;
+                key = k;
+            }
+        }
+    }
+    if (key === undefined)
+        return false;
+    calls.delete(key);
+    if (calls.size === 0)
+        reg.activeToolCalls.delete(sessionID);
+    return true;
+}
+/**
+ * 메시지 스냅샷과 대조해 이미 끝난 호출을 정리한다.
+ *
+ * 툴이 throw 하면(권한 거부 · 파일 없음 · MCP 오류) opencode 는 `tool.execute.after`
+ * 를 부르지 않는다 — 항목이 영영 남아 `isToolExecuting()` 이 참으로 굳고, 그러면
+ * 완료 판정이 유보돼 substage 가 절대 타임아웃까지 기다린다. 스냅샷의 tool part
+ * 가 completed/error 면 그 호출은 확실히 끝난 것이므로 여기서 뺀다. 스냅샷에
+ * **아직 없는** 호출은 건드리지 않는다 (issue #7 의 110ms 창 — 훅은 발화했는데
+ * 서버가 part 를 아직 반영하지 않은 상태). 정리한 개수를 돌려준다.
+ */
+export function settleToolCalls(reg, sessionID, settledCallIDs) {
+    const calls = reg.activeToolCalls.get(sessionID);
+    if (!calls || calls.size === 0)
+        return 0;
+    let n = 0;
+    for (const id of settledCallIDs) {
+        if (calls.delete(id))
+            n++;
+    }
+    if (calls.size === 0)
+        reg.activeToolCalls.delete(sessionID);
+    return n;
+}
+/** 지금 이 순간 이 세션에서 실행 중인 툴이 있는가 (순간값). */
+export function isToolExecuting(reg, sessionID) {
+    return (reg.activeToolCalls.get(sessionID)?.size ?? 0) > 0;
+}
+export function activeToolCount(reg, sessionID) {
+    return reg.activeToolCalls.get(sessionID)?.size ?? 0;
+}
+/** 세션이 idle 로 전이했다 — 실행 중인 툴은 정의상 없다. */
+export function clearToolCalls(reg, sessionID) {
+    reg.activeToolCalls.delete(sessionID);
+}
+// ── 권한 요청 관측 ───────────────────────────────────────────────────────────
+/**
+ * 플러그인 `event` 훅이 받는 권한 요청 이벤트를 공통 형태로 바꾼다.
+ *
+ * 1.18 v1 브리지는 `permission.asked` 를 `PermissionRequest` 그대로 싣는다
+ * (`id / sessionID / permission / patterns`). 더 오래된 SDK 형태 `permission.updated`
+ * 는 `type` · `pattern`(문자열 또는 배열) 을 쓴다. 둘 다 받아 둔다 — 어느 쪽이 오든
+ * 폴러가 보는 것은 같은 shape 이어야 한다. 요청으로 볼 수 없는 페이로드는 null.
+ */
+export function normalizePermissionEvent(type, properties, now = Date.now()) {
+    if (type !== "permission.asked" && type !== "permission.updated")
+        return null;
+    if (!properties || typeof properties !== "object")
+        return null;
+    const p = properties;
+    const id = typeof p.id === "string" ? p.id : undefined;
+    const sessionID = typeof p.sessionID === "string" ? p.sessionID : undefined;
+    if (!id || !sessionID)
+        return null;
+    const permission = typeof p.permission === "string" ? p.permission
+        : typeof p.type === "string" ? p.type
+            : "unknown";
+    const rawPatterns = p.patterns ?? p.pattern;
+    const patterns = Array.isArray(rawPatterns)
+        ? rawPatterns.filter((x) => typeof x === "string")
+        : typeof rawPatterns === "string" ? [rawPatterns]
+            : [];
+    return { id, sessionID, permission, patterns, askedAt: now };
+}
+export function permissionAsked(reg, req) {
+    let bySession = reg.pendingPermissions.get(req.sessionID);
+    if (!bySession) {
+        bySession = new Map();
+        reg.pendingPermissions.set(req.sessionID, bySession);
+    }
+    bySession.set(req.id, req);
+}
+export function permissionReplied(reg, sessionID, requestID) {
+    const bySession = reg.pendingPermissions.get(sessionID);
+    if (!bySession)
+        return;
+    bySession.delete(requestID);
+    if (bySession.size === 0)
+        reg.pendingPermissions.delete(sessionID);
+}
+/** 이 세션에 답을 기다리는 권한 요청 — 오래된 순. */
+export function pendingPermissionsFor(reg, sessionID) {
+    const bySession = reg.pendingPermissions.get(sessionID);
+    if (!bySession)
+        return [];
+    return [...bySession.values()].sort((a, b) => a.askedAt - b.askedAt);
+}
+// ── 수명 ─────────────────────────────────────────────────────────────────────
+/** 세션 하나의 흔적을 전부 지운다 (cleanupSubSession · session.deleted). */
+export function forgetSession(reg, sessionID) {
+    reg.activeToolCalls.delete(sessionID);
+    reg.lastToolExecuteAt.delete(sessionID);
+    reg.pendingPermissions.delete(sessionID);
+    reg.sessionIssue.delete(sessionID);
+    reg.sessionWorktree.delete(sessionID);
+}
+/** session.deleted — 대기자를 전부 깨운다. 깨운 수를 돌려준다. */
+export function notifySessionDeleted(reg, sessionID) {
+    const waiters = reg.sessionDeletedWaiters.get(sessionID);
+    if (!waiters || waiters.length === 0)
+        return 0;
+    const copy = [...waiters];
+    for (const w of copy) {
+        try {
+            w();
+        }
+        catch { /* waiter 오류는 이벤트 처리를 막지 않는다 */ }
+    }
+    return copy.length;
+}

package/gates/stage-analysis-verify.sh

@@ -5,7 +5,8 @@
 #
 # 진입 조건:
 #   1. state.json 존재
-#   2. 1_planning.scope substage done=true
+#   2. 1_planning.requirements substage done=true + 승인 + 품질 게이트
+#      (scope 흡수 전 stage3-scope-verify.sh 가 하던 검사를 그대로 이어받는다)
 #
 # SKIP 조건:
 #   프로젝트 루트에 build tool 마커 파일이 하나도 없음
@@ -41,11 +42,68 @@ q() {
 ANALYSIS_DONE="$(q '.stages."2_implementation".substages."analysis".done')"
 [ "$ANALYSIS_DONE" != "true" ] || fail "이미 done=true 완료됨 — auto_advance_stage 로 다음 단계 진행"
 
-# 3. scope substage 완료 확인
-SCOPE_DONE="$(q '.stages."1_planning".substages."scope".done')"
-[ "$SCOPE_DONE" = "true" ] || fail "1_planning.scope 미완료 (done=$SCOPE_DONE)"
+# 3. requirements substage 완료 + 승인 + 품질 확인
+#
+# 종전에는 `1_planning.scope` substage 의 done 만 봤다. scope 가 requirements 로
+# 흡수되면서(범위 확정은 요구사항 확정과 같은 판단의 연속이다) 그 자리를 지키던
+# stage3-scope-verify.sh 의 검사가 통째로 이 게이트로 넘어왔다. 검사를 옮기지 않고
+# 게이트만 지우면 승인·모호성·spec drift 검증이 파이프라인에서 사라진다.
+REQ_DONE="$(q '.stages."1_planning".substages."requirements".done')"
+[ "$REQ_DONE" = "true" ] || fail "1_planning.requirements 미완료 (done=$REQ_DONE)"
+
+if [ "$(q '.policy.auto_approve."1_planning.requirements"')" != "true" ]; then
+  [ "$(q '.stages."1_planning".substages."requirements".approved_by_user')" = "true" ] \
+    || fail "requirements substage 사용자 승인 없음 (또는 .policy.auto_approve.\"1_planning.requirements\" 미설정)"
+  if [ "$(q '.stages."1_planning".substages."requirements".verification_pending')" = "true" ]; then
+    fail "requirements substage 검증 대기 중 (verification_pending) — 사용자 승인 후 approved_by_user를 기록하라"
+  fi
+fi
+
+if [ "$(q '.stages."1_planning".substages."requirements".interview_required')" = "true" ]; then
+  [ "$(q '.stages."1_planning".substages."requirements".interview_completed')" = "true" ] \
+    || fail "requirements substage 인터뷰 미완료 — 모든 미결 항목 해소 후 interview_completed=true 기록 필요"
+fi
+
+# --- 요구사항 품질 게이트 (조건부 — 마커 존재 시에만 검사, 구형 state 호환) ---
+# 1) Ambiguity Score 수렴: 기록된 값이 0.2 초과면 요구사항 미수렴 (stages/02-requirements.md)
+AMB="$(q '.stages."1_planning".substages."requirements".ambiguity_score')"
+if [ "$AMB" != "__MISSING__" ] && [ "$AMB" != "null" ] && [ -n "$AMB" ]; then
+  awk -v a="$AMB" 'BEGIN { exit (a + 0 <= 0.2) ? 0 : 1 }' \
+    || fail "ambiguity_score=$AMB > 0.2 — 요구사항 미수렴. 인터뷰로 미결 항목 해소 후 재산정하라"
+fi
+
+# 2) 명세 동결(spec drift) 검증: spec_hash 기록 시 draft 파일 해시 재계산 일치 필요
+SPEC_HASH="$(q '.stages."1_planning".substages."requirements".spec_hash')"
+if [ "$SPEC_HASH" != "__MISSING__" ] && [ "$SPEC_HASH" != "null" ] && [ -n "$SPEC_HASH" ]; then
+  DRAFT="$(q '.stages."1_planning".substages."requirements".draft_path')"
+  ROOT="$("$SCRIPTS/state.sh" root)"
+  # 마커 누락과 파일 부재를 구분해서 알린다. 둘 다 "확정 명세 파일 없음" 으로
+  # 뭉뚱그리면 파일은 멀쩡하고 마커만 빠진 흔한 경우(issue #6-①)에 무엇을 해야
+  # 하는지 알 수 없다.
+  DEFAULT_DRAFT=".makdoong2-team/${ISSUE}/requirements-draft.md"
+  if [ "$DRAFT" = "__MISSING__" ] || [ "$DRAFT" = "null" ] || [ -z "$DRAFT" ]; then
+    if [ -f "$ROOT/$DEFAULT_DRAFT" ]; then
+      fail "spec_hash 는 기록됐는데 draft_path 마커가 없다 — 파일은 ${DEFAULT_DRAFT} 에 있다.
+  복구: (1) sha256sum \"${ROOT}/${DEFAULT_DRAFT}\" 가 spec_hash(${SPEC_HASH}) 와 같은지 대조하고,
+        (2) 같으면 state.sh set 으로 requirements.draft_path 에 \"${DEFAULT_DRAFT}\" 를 기록한다,
+        (3) 다르면 명세가 동결 후 변경된 것이므로 requirements substage 를 재작업한다."
+    fi
+    fail "spec_hash 는 기록됐는데 draft_path 마커도 확정 명세 파일도 없다 — requirements substage 를 재작업하라 (stages/02-requirements.md)"
+  fi
+  # "생성된 적 없음" 을 안내에서 빼면 복구 방향을 잘못 잡는다 — 실제로 가장 흔한
+  # 경우인데 종전 메시지는 동기화 누락·삭제만 언급해 리더가 동기화 문제부터
+  # 의심했다 (issue #8).
+  [ -f "$ROOT/$DRAFT" ] \
+    || fail "draft_path=${DRAFT} 마커는 있으나 파일이 없다 (기준 경로 ${ROOT}). 가능한 원인 순서대로:
+  (1) 애초에 생성된 적 없음 — planner 가 마커만 기록하고 파일 생성에 실패한 경우. requirements substage 를 재작업해 쓰기 툴로 초안부터 생성하라 (stages/02-requirements.md),
+  (2) worktree 동기화 누락 — 다른 cwd(main repo/worktree)의 같은 상대경로에 파일이 있는지 확인,
+  (3) 파일이 삭제됨 — 삭제 경위 확인 후 requirements 재작업"
+  ACTUAL="$(sha256sum "$ROOT/$DRAFT" | cut -d' ' -f1)"
+  [ "$ACTUAL" = "$SPEC_HASH" ] \
+    || fail "확정 명세 무단 변경 감지 (spec drift) — 동결 후 변경은 사용자 재승인 + spec_hash 재기록 절차만 허용 (stages/02-requirements.md)"
+fi
 
-# 3. SKIP 판정: worktree 루트에서 build tool 마커 파일 존재 여부
+# 4. SKIP 판정: worktree 루트에서 build tool 마커 파일 존재 여부
 WT="$(q '.worktree' | tr -d '"')"
 [ -d "$WT" ] || WT="$(pwd)"
 

package/gates/stage4-dev-verify.sh

@@ -23,7 +23,7 @@ assert_worktree_sibling(){
   [ "$pwt" = "$pmain" ] || fail "worktree가 메인 repo의 형제 디렉토리가 아님: $wt (메인: $main)"
 }
 [ "$(q '.stages."2_implementation".substages."dev".done')" != "true" ] || fail "이미 done=true 완료됨 — auto_advance_stage 로 다음 단계 진행"
-[ "$(q '.stages."1_planning".substages."scope".done')" = "true" ] || fail "scope substage 미완료"
+[ "$(q '.stages."1_planning".substages."requirements".done')" = "true" ] || fail "requirements substage 미완료"
 # analysis substage 는 게이트가 SKIP 시 done=true 로 마킹하므로 skipped 여부와 무관하게 done=true 검사만 하면 된다.
 [ "$(q '.stages."2_implementation".substages."analysis".done')" = "true" ] || fail "analysis substage 미완료 (skipped 도 done=true 로 처리됨)"
 
@@ -31,11 +31,11 @@ WT="$(q '.worktree')"
 [ -n "$WT" ] && [ "$WT" != "__MISSING__" ] || fail "worktree 경로 미설정 — state.json의 .worktree 필드 확인"
 assert_worktree_sibling "$WT"
 
-if [ "$(q '.policy.auto_approve."1_planning.scope"')" != "true" ]; then
-  [ "$(q '.stages."1_planning".substages."scope".approved_by_user')" = "true" ] \
-    || fail "scope substage 사용자 승인 없음 (또는 .policy.auto_approve.\"1_planning.scope\" 미설정)"
-  if [ "$(q '.stages."1_planning".substages."scope".verification_pending')" = "true" ]; then
-    fail "scope substage 검증 대기 중 (verification_pending) — 사용자 승인 후 approved_by_user를 기록하라"
+if [ "$(q '.policy.auto_approve."1_planning.requirements"')" != "true" ]; then
+  [ "$(q '.stages."1_planning".substages."requirements".approved_by_user')" = "true" ] \
+    || fail "requirements substage 사용자 승인 없음 (또는 .policy.auto_approve.\"1_planning.requirements\" 미설정)"
+  if [ "$(q '.stages."1_planning".substages."requirements".verification_pending')" = "true" ]; then
+    fail "requirements substage 검증 대기 중 (verification_pending) — 사용자 승인 후 approved_by_user를 기록하라"
   fi
 fi
 echo "MAKDOONG2-GATE OK: 2_implementation.dev"

package/gates/verify.sh

@@ -23,8 +23,6 @@ case "$TARGET" in
     echo "MAKDOONG2-GATE OK: $TARGET (jira validation handled by extension gate)" ;;
   1_planning.requirements)
     "$HERE/stage2-requirements-verify.sh" "$ISSUE" ;;
-  1_planning.scope)
-    "$HERE/stage3-scope-verify.sh" "$ISSUE" ;;
   2_implementation.analysis)
     "$HERE/stage-analysis-verify.sh" "$ISSUE" ;;
   2_implementation.dev)

package/opencode.json.example

@@ -34,7 +34,6 @@
     "verify_stage": true,
     "dispatch_stage": true,
     "dispatch_verifier": true,
-    "dispatch_research": true,
     "auto_advance_stage": true,
     "get_fallback_model": true
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makdoong2-team",
-  "version": "2.3.2",
+  "version": "3.0.1",
   "publishConfig": {
     "access": "public"
   },