@asc-agent/runtime 0.2.0 → 0.3.0

package/dist/composition/propose.d.ts

@@ -0,0 +1,19 @@
+import type { BindingPlan, Capability } from '../core/binding/types.ts';
+export type BindingProposal = {
+    /**
+     * capability → 이 통로를 맡을 adapter.
+     *
+     * **조립에 밀어 넣는 값이 아니다.** 후보가 유일하면 capability 해석은 스스로 풀리므로,
+     * 여기서 역할을 박으면 선언과 제안이 같은 자리에 섞인다. 이 표는 "무엇이 무엇을 맡게
+     * 됐는지"를 사람에게 말하기 위한 것이다.
+     */
+    roles: Partial<Record<Capability, string>>;
+    /** 사람이 읽는 근거. 제안이라는 사실을 문장 안에 남긴다. */
+    reasons: string[];
+    /** 후보가 갈려 제안하지 않은 것들. */
+    conflicts: string[];
+};
+/**
+ * 선언이 하나도 없을 때만 부른다. 선언이 있으면 그것이 답이고, 여기서 다시 정하지 않는다.
+ */
+export declare function proposeBindings(plan: BindingPlan): BindingProposal;

package/dist/composition/propose.js

@@ -0,0 +1,35 @@
+// Binding 자동 제안 (P1-G).
+//
+// Profile 은 **팀이 정한 것**을 담는다. 그런데 지금까지는 발견하면 알 수 있는 사실까지
+// 거기 적어야 했다 — 원격이 하나뿐이고 그 원격을 다룰 adapter 도 하나뿐인데도, 누가
+// bindings 에 적어 주기 전에는 아무 통로가 서지 않았다.
+//
+// 여기서 하는 일은 그 한 가지뿐이다: **후보가 유일할 때만** 역할을 제안한다. 저장하지
+// 않고, Profile 을 고치지 않으며, 둘 이상이면 고르지 않는다 — 고르는 것은 사람의 일이고,
+// 틀린 연결은 없는 연결보다 나쁘다.
+const USABLE = new Set(['AVAILABLE', 'DEGRADED']);
+/**
+ * 선언이 하나도 없을 때만 부른다. 선언이 있으면 그것이 답이고, 여기서 다시 정하지 않는다.
+ */
+export function proposeBindings(plan) {
+    const proposal = { roles: {}, reasons: [], conflicts: [] };
+    const usable = plan.bindings.filter((binding) => USABLE.has(binding.state));
+    const byCapability = new Map();
+    for (const binding of usable) {
+        for (const capability of binding.provides) {
+            byCapability.set(capability, [...(byCapability.get(capability) ?? []), binding]);
+        }
+    }
+    for (const [capability, candidates] of byCapability) {
+        const distinct = new Map(candidates.map((c) => [`${c.adapterId}:${c.resource}`, c]));
+        if (distinct.size !== 1) {
+            proposal.conflicts.push(`${capability}: 후보가 ${distinct.size}개다 (${[...distinct.keys()].join(', ')}) — 어느 쪽인지는 사람이 정한다`);
+            continue;
+        }
+        const only = [...distinct.values()][0];
+        const role = only.role ?? only.adapterId;
+        proposal.roles[capability] = role;
+        proposal.reasons.push(`${capability} ← ${only.adapterId}:${only.resource} (유일한 후보라 제안한다 — Profile 에 저장하지 않는다)`);
+    }
+    return proposal;
+}

package/dist/composition/runtime.d.ts

@@ -42,6 +42,8 @@ export type BuildInput = {
     /** 이 binding이 어느 주소를 가리키는지. 발견 단계가 알아낸 값을 그대로 잇는다. */
     endpointFor?: (binding: ResolvedBinding) => string | undefined;
 };
+/** 이 프로세스가 띄운 도구 자식들을 정리한다. 여러 번 불러도 안전하다. */
+export declare function closeToolClients(): Promise<void>;
 /**
  * capability가 필요한 자리마다 어느 binding이 맡을지 정해 Port를 만든다.
  *

package/dist/composition/runtime.js

@@ -5,12 +5,14 @@
 // 변경으로 끝난다 — 그것이 "provider 교체는 Binding 교체" 의 실제 모습이다.
 //
 // **Core는 이 파일을 import하지 않는다.** 방향은 언제나 Composition → Core다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { resolveCapability } from "../core/binding/types.js";
 import { GitHubClient, discoverToken } from "../adapters/github/client.js";
 import { GitHubChangeContext, GitHubInventory, GitHubResourceContext } from "../adapters/github/context.js";
 import { GitHubEventSource } from "../adapters/github/event-source.js";
 import { GitHubScm } from "../adapters/github/scm.js";
-import { GitLabClient, discoverToken as discoverGitLabToken } from "../adapters/gitlab/client.js";
+import { GitLabClient, GlabApiClient, discoverToken as discoverGitLabToken, glabAvailable, } from "../adapters/gitlab/client.js";
 import { GitLabChangeContext, GitLabEventSource, GitLabInventory, GitLabResourceContext, } from "../adapters/gitlab/ports.js";
 import { JamMcpClient } from "../adapters/jam/mcp-client.js";
 import { JamEventSource } from "../adapters/jam/event-source.js";
@@ -19,7 +21,9 @@ const FACTORIES = {
     gitlab(binding, input, token) {
         // 자체 호스팅이 흔하다. 어디를 가리키는지는 발견 단계가 이미 알아냈으므로 같은 값을 쓴다.
         const baseUrl = input.endpointFor?.(binding);
-        const client = new GitLabClient({ token, ...(baseUrl ? { baseUrl } : {}) });
+        // 토큰이 빈 문자열이면 자격이 도구 안에 있다는 뜻이다 (P1-H). 값을 꺼내 오지 않고
+        // 그 도구에게 요청을 대신 보내 달라고 한다 — 읽기 전용이다.
+        const client = token === '' ? new GlabApiClient(defaultGlabRun) : new GitLabClient({ token, ...(baseUrl ? { baseUrl } : {}) });
         const project = binding.resource;
         return {
             eventSource: new GitLabEventSource({ client, project, perPage: input.perPage ?? 30 }),
@@ -44,11 +48,11 @@ const FACTORIES = {
         // JAM은 토큰을 받지 않는다 — 자격은 도구가 자기 안에서 관리하고 ASC는 상태만 읽는다.
         if (!input.jam)
             return {};
-        const client = new JamMcpClient({
+        const client = registerToolClient(new JamMcpClient({
             command: input.jam.command,
             ...(input.jam.args ? { args: input.jam.args } : {}),
             ...(input.jam.cwd ? { cwd: input.jam.cwd } : {}),
-        });
+        }));
         const projectKey = binding.resource;
         const timezone = input.jam.timezone;
         const inventory = new JamInventory({ client, projectKey, ...(timezone ? { timezone } : {}) });
@@ -64,8 +68,40 @@ const FACTORIES = {
         };
     },
 };
+const execFileAsync = promisify(execFile);
+/** glab 실행 통로. 실패는 예외로 올라가고, 호출측이 "없다"로 접는다. */
+const defaultGlabRun = async (command, args) => {
+    const { stdout } = await execFileAsync(command, [...args]);
+    return stdout;
+};
+/**
+ * gitlab 자격 찾기. env 토큰이 먼저고, 없으면 로그인된 `glab` 을 통로로 인정해 빈 문자열을
+ * 돌려준다 — **값이 아니라 "통로가 있다"는 사실이다.** 둘 다 없으면 null 이고, 그때만
+ * 조립하지 않는다.
+ */
+const discoverGitLabAccess = async () => {
+    const token = discoverGitLabToken();
+    if (token)
+        return token;
+    return (await glabAvailable(defaultGlabRun)) ? '' : null;
+};
 /** 이 adapter는 토큰 없이 조립된다. 자격은 도구가 자기 안에서 진다. */
 const TOKENLESS = new Set(['jam']);
+/**
+ * 자식 프로세스를 띄우는 도구 클라이언트들. 명령이 끝나면 닫아야 한다 — 안 닫으면
+ * CLI 가 할 일을 다 하고도 종료하지 못하고 서버 프로세스가 남는다(실제로 그렇게 됐다).
+ */
+const toolClients = new Set();
+function registerToolClient(client) {
+    toolClients.add(client);
+    return client;
+}
+/** 이 프로세스가 띄운 도구 자식들을 정리한다. 여러 번 불러도 안전하다. */
+export async function closeToolClients() {
+    const clients = [...toolClients];
+    toolClients.clear();
+    await Promise.all(clients.map((client) => client.stop().catch(() => undefined)));
+}
 /**
  * capability와 Port의 대응. **이 표가 없으면 조립이 덮어쓰기가 된다** —
  * 두 binding이 각각 다른 capability를 맡았는데 나중 것이 앞 것의 Port까지 밀어낸다.
@@ -108,7 +144,7 @@ export async function buildRuntimePorts(input) {
     const ports = { unavailable: [] };
     // 자격은 adapter마다 다른 곳에 있다. Core는 이 사실을 모르고, 여기서만 안다.
     const findToken = input.findToken ??
-        (async (adapterId) => adapterId === 'gitlab' ? discoverGitLabToken() : await discoverToken());
+        (async (adapterId) => adapterId === 'gitlab' ? await discoverGitLabAccess() : await discoverToken());
     // capability마다 따로 푼다. 한 binding이 여럿을 제공해도, 서로 다른 binding이 나눠
     // 맡아도 같은 경로로 조립된다 — 어느 갈래가 어디서 왔는지가 Port마다 정확해야 한다.
     const wanted = Object.keys(PORT_OF);

package/dist/core/attach/init.d.ts

@@ -27,3 +27,20 @@ export declare function overrideTemplate(): string;
 export declare function identitiesTemplate(): string;
 /** 이미 있으면 건드리지 않는다. 사람이 채운 것을 덮지 않기 위해서다. */
 export declare function writeIfAbsent(path: string, content: string): Promise<boolean>;
+/**
+ * 지금 이 사람을 승인 권한자·감시 대상으로 세운 두 파일의 내용 (P1-F).
+ *
+ * 순수 함수인 이유: 이 결정은 두 파일에 서로 다른 형식으로 적히고, 한쪽만 채워 두면
+ * 게이트가 왜 안 열리는지 알 수 없는 상태가 된다. 그 짝을 코드 한 곳에서 만든다.
+ *
+ * **비밀은 다루지 않는다** — 이름과 채널만 적힌다.
+ */
+export declare function withIdentity(identities: Record<string, unknown>, override: Record<string, unknown>, input: {
+    name: string;
+    actor: string;
+    controller: boolean;
+    monitor: boolean;
+}): {
+    identities: Record<string, unknown>;
+    override: Record<string, unknown>;
+};

package/dist/core/attach/init.js

@@ -98,3 +98,31 @@ export async function writeIfAbsent(path, content) {
         throw error;
     }
 }
+/**
+ * 지금 이 사람을 승인 권한자·감시 대상으로 세운 두 파일의 내용 (P1-F).
+ *
+ * 순수 함수인 이유: 이 결정은 두 파일에 서로 다른 형식으로 적히고, 한쪽만 채워 두면
+ * 게이트가 왜 안 열리는지 알 수 없는 상태가 된다. 그 짝을 코드 한 곳에서 만든다.
+ *
+ * **비밀은 다루지 않는다** — 이름과 채널만 적힌다.
+ */
+export function withIdentity(identities, override, input) {
+    const nextIdentities = { ...identities };
+    const nextOverride = { ...override };
+    if (input.controller) {
+        nextIdentities[input.name] = [input.actor];
+        const controller = { ...(nextOverride.controller ?? {}) };
+        controller.identities = {
+            ...(controller.identities ?? {}),
+            [input.name]: [input.actor],
+        };
+        nextOverride.controller = controller;
+    }
+    if (input.monitor) {
+        const existing = Array.isArray(nextOverride.monitorIdentities)
+            ? nextOverride.monitorIdentities.filter((v) => typeof v === 'string')
+            : [];
+        nextOverride.monitorIdentities = [...new Set([...existing, input.name])];
+    }
+    return { identities: nextIdentities, override: nextOverride };
+}

package/dist/core/attach/setup-plan.d.ts

@@ -1,6 +1,15 @@
 import type { StableInstallState } from '../distribution/runtime-install.ts';
 /** 세상의 스냅샷. 읽기만 해서 만든다. */
 export type SetupState = {
+    /**
+     * 이 판단이 **어느 실행물 안에서** 나오는가 (C-14 §3.4).
+     *
+     * `runtime` 이면 지금 도는 것이 곧 설치된 `asc` 다 — 그 사실은 관측할 것이 아니라
+     * 이미 아는 것이다. 예전에는 이 축이 없어 `stableRuntime` 의 부재를 "설치 안 됨"으로
+     * 읽었고, 그래서 설치된 `asc` 가 자기를 bootstrap이라고 말하며 agent에게 `npx …` 를
+     * 돌려줬다 (v0.2.0 registry 관측). 진입점 자체가 이미 답의 일부다.
+     */
+    entry: 'runtime' | 'bootstrap';
     projectRoot: string;
     git: boolean;
     /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */

package/dist/core/attach/setup-plan.js

@@ -22,11 +22,22 @@ export function computeSetupPlan(state) {
     ];
     // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
     // `asc …` 를 실행하라고 주면 안 된다 (C-14 §3.4 · 불변식 ⑯).
-    const mode = state.stableRuntime?.status === 'CURRENT' ? 'installed-runtime' : 'bootstrap';
-    const command = (args) => ({
-        display: shorthandCommand(args),
-        portable: mode === 'installed-runtime' ? shorthandCommand(args) : portableCommand(args),
-    });
+    //
+    // **진입점이 먼저다.** `asc` 로 들어왔다면 그 `asc` 는 이미 이 machine에 있다 — 그것을
+    // npm에게 물어볼 이유가 없다. bootstrap으로 들어왔을 때만 설치 축이 판정에 쓰인다.
+    const mode = state.entry === 'runtime' || state.stableRuntime?.status === 'CURRENT'
+        ? 'installed-runtime'
+        : 'bootstrap';
+    const command = (args) => {
+        // portable은 **agent가 그대로 실행하는 것**이므로 기계가 읽을 수 있는 형태로 끝나야
+        // 한다. `--json` 이 빠져 있으면 agent는 자기가 실행한 명령의 답을 산문으로 받는다 —
+        // "산문을 파싱하지 마라"고 적어 놓고 산문을 주는 꼴이었다. display는 사람 형태 그대로.
+        const machine = args.includes('--json') ? args : [...args, '--json'];
+        return {
+            display: shorthandCommand(args),
+            portable: mode === 'installed-runtime' ? shorthandCommand(machine) : portableCommand(machine),
+        };
+    };
     const changes = [];
     // stable runtime은 **프로젝트와도, profile 선택과도 무관하다.** 사람이 profile을
     // 고르는 중이어도 이 설치는 안전한 준비이고, 그것 때문에 통째로 WAIT 하지 않는다

package/dist/core/distribution/node-runtime.d.ts

@@ -0,0 +1,44 @@
+import type { ProcessRunner } from './runtime-install.ts';
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export declare const MINIMUM_NODE_MAJOR = 24;
+export type NodeCandidate = {
+    path: string;
+    version: string;
+};
+export type NodeRuntimeCheck = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    code: 'NODE_RUNTIME_REQUIRED';
+    version: string;
+    detail: string;
+    /**
+     * 이 machine에서 찾은, 하한을 넘는 Node. **비어 있는 것이 실패가 아니다** —
+     * 그때는 Node를 놓는 일 자체가 사람의 경계다.
+     */
+    candidates: NodeCandidate[];
+};
+export type NodeRuntimeDeps = {
+    /** 지금 이 프로세스의 Node 버전 (`process.version` 형태: `v22.23.2`). */
+    version: string;
+    /** 후보 경로가 실제로 있는가. */
+    exists: (path: string) => boolean;
+    /** 디렉터리 목록. 없으면 빈 배열 — 없는 것은 오류가 아니다. */
+    list: (path: string) => string[];
+    /** `<node> -v` 를 돌린다. 실패는 후보 탈락일 뿐이다. */
+    run: ProcessRunner;
+    /** 사용자 홈. nvm 배치를 찾는 데만 쓴다. */
+    home: string;
+    /** 경로를 잇는다 — 호출자가 `node:path` 를 준다 (core는 파일시스템을 모른다). */
+    join: (...parts: string[]) => string;
+};
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export declare function majorOf(version: string): number | null;
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export declare function checkNodeRuntime(deps: NodeRuntimeDeps): Promise<NodeRuntimeCheck>;

package/dist/core/distribution/node-runtime.js

@@ -0,0 +1,75 @@
+// 이 프로세스를 돌리고 있는 Node가 ASC를 돌릴 수 있는가 (C-14 §3).
+//
+// **왜 판정이 필요한가**: `engines` 는 npm에게 하는 말이고, npm은 기본값에서 그것을
+// 경고로만 낸다. 그래서 Node 22에서 설치하면 "무서운 경고 한 줄 → 그래도 돌아감"이 되고,
+// 사용자는 자기가 지원 범위 안에 있는지 알 수 없다. 지원 하한은 결정적으로 답해야 한다.
+//
+// **여기서 하지 않는 것**: Node를 설치하지 않고, PATH·shell 설정을 고치지 않으며,
+// version manager를 다루지 않는다. 이미 이 machine에 있는 것을 **best-effort로 찾아
+// 알려 줄** 뿐이다 — 못 찾는 것은 정상이고, 그때는 사람이 답할 일이다.
+import { RELEASE_VERSION } from "./release.js";
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export const MINIMUM_NODE_MAJOR = 24;
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export function majorOf(version) {
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 이미 있는 Node를 찾아본다. **탐색이지 관리가 아니다.**
+ *
+ * Homebrew와 nvm의 관례적 배치만 본다. 여기에 없다고 해서 Node가 없는 것은 아니고,
+ * 그 경우 후보 없이 돌려주는 것이 정직한 답이다 — 없는 것을 지어내지 않는다.
+ */
+function candidatePaths(deps) {
+    const found = [];
+    // Homebrew: /opt/homebrew/opt/node@26/bin/node · /usr/local/opt/node/bin/node
+    for (const prefix of ['/opt/homebrew/opt', '/usr/local/opt']) {
+        for (const entry of deps.list(prefix)) {
+            if (!/^node(@\d+)?$/.test(entry))
+                continue;
+            const path = deps.join(prefix, entry, 'bin', 'node');
+            if (deps.exists(path))
+                found.push(path);
+        }
+    }
+    // nvm: ~/.nvm/versions/node/v24.1.0/bin/node
+    const nvm = deps.join(deps.home, '.nvm', 'versions', 'node');
+    for (const entry of deps.list(nvm)) {
+        const path = deps.join(nvm, entry, 'bin', 'node');
+        if (deps.exists(path))
+            found.push(path);
+    }
+    return [...new Set(found)];
+}
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export async function checkNodeRuntime(deps) {
+    const major = majorOf(deps.version);
+    if (major !== null && major >= MINIMUM_NODE_MAJOR)
+        return { ok: true, version: deps.version };
+    const candidates = [];
+    for (const path of candidatePaths(deps)) {
+        const probed = await deps.run(path, ['-v']);
+        if (!probed.ok)
+            continue;
+        const version = probed.stdout.trim().split(/\r?\n/)[0] ?? '';
+        const found = majorOf(version);
+        if (found !== null && found >= MINIMUM_NODE_MAJOR)
+            candidates.push({ path, version });
+    }
+    return {
+        ok: false,
+        code: 'NODE_RUNTIME_REQUIRED',
+        version: deps.version,
+        detail: `ASC ${RELEASE_VERSION} needs Node ${MINIMUM_NODE_MAJOR} or newer; this process is ${deps.version}.` +
+            (candidates.length > 0
+                ? ' A newer Node is already on this machine — use it for the same command.'
+                : ' No newer Node was found in the usual places. Installing one is yours to do.'),
+        candidates,
+    };
+}

package/dist/core/distribution/release.d.ts

@@ -1,9 +1,9 @@
 export declare const RUNTIME_PACKAGE = "@asc-agent/runtime";
 export declare const BOOTSTRAP_PACKAGE = "@asc-agent/bootstrap";
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export declare const RELEASE_VERSION = "0.2.0";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.2.0";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.2.0";
+export declare const RELEASE_VERSION = "0.3.0";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.3.0";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.3.0";
 /**
  * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
  *

package/dist/core/distribution/release.js

@@ -9,7 +9,7 @@
 export const RUNTIME_PACKAGE = '@asc-agent/runtime';
 export const BOOTSTRAP_PACKAGE = '@asc-agent/bootstrap';
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export const RELEASE_VERSION = '0.2.0';
+export const RELEASE_VERSION = '0.3.0';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**

package/dist/core/monitor/investigation.d.ts

@@ -5,6 +5,18 @@ import { type OwnershipMap } from '../policy/ownership.ts';
 import type { Relevance } from './relevance.ts';
 export declare const STEPS: readonly ["resource", "delta", "responsibility", "work", "thread", "change", "work-context", "canonical", "relevance", "recommendation", "draft"];
 export type StepId = (typeof STEPS)[number];
+/**
+ * 확인하지 못한 이유. "안 봤다"와 "볼 수 없다"가 같은 결과로 뭉개지면, 조사 누락이
+ * 접근 불가처럼 보이고 그 상태로 추천이 나간다.
+ *
+ * - `MISSING`        — 통로 자체가 없어 **보지 않았다** (Port 미배선)
+ * - `UNAVAILABLE`    — 보려 했으나 실패했다 (조회 오류·접근 거부·사라짐)
+ * - `NOT_APPLICABLE` — 이 사건에 해당하지 않는다
+ *
+ * 이전 판의 결과가 `done` 으로 되돌아오면 이 필드가 없다. 그때는 MISSING 으로 읽는다 —
+ * 모르는 쪽을 "확인했다"로 읽는 것보다 "안 봤다"로 읽는 편이 안전하다.
+ */
+export type StepReason = 'MISSING' | 'UNAVAILABLE' | 'NOT_APPLICABLE';
 export type StepResult = {
     id: StepId;
     kind: 'DONE';
@@ -15,13 +27,17 @@ export type StepResult = {
     id: StepId;
     kind: 'UNDECIDABLE';
     detail: string;
+    reason?: Extract<StepReason, 'MISSING' | 'UNAVAILABLE'>;
 }
 /** 이 사건에는 해당하지 않는다 (변경이 없는 사건의 change 단계 등). */
  | {
     id: StepId;
     kind: 'SKIPPED';
     detail: string;
+    reason?: Extract<StepReason, 'NOT_APPLICABLE'>;
 };
+/** 단계 결과를 세 상태로 읽는다. reason 이 없는 옛 결과는 보수적으로 읽는다. */
+export declare function stepReason(step: StepResult): 'DONE' | StepReason;
 export type Investigation = {
     steps: StepResult[];
     /** 사람이 읽는 상황. 단계 산출을 이어 붙인 것이며 요약하지 않는다. */

package/dist/core/monitor/investigation.js

@@ -21,10 +21,19 @@ export const STEPS = [
     'recommendation', // ⑩ 무엇을 하면 되는가
     'draft', // ⑪ 초안 (조건을 만족할 때만)
 ];
+/** 단계 결과를 세 상태로 읽는다. reason 이 없는 옛 결과는 보수적으로 읽는다. */
+export function stepReason(step) {
+    if (step.kind === 'DONE')
+        return 'DONE';
+    if (step.kind === 'SKIPPED')
+        return step.reason ?? 'NOT_APPLICABLE';
+    return step.reason ?? 'MISSING';
+}
 const missingPort = (id, what) => ({
     id,
     kind: 'UNDECIDABLE',
     detail: `${what} 를 제공하는 binding이 없다 — 이 단계는 확인하지 못했다`,
+    reason: 'MISSING',
 });
 /**
  * 단계를 순서대로 밟는다. **각 단계는 자기가 필요한 Port만 요청한다** — 어떤 외부 시스템이
@@ -45,7 +54,7 @@ export async function investigate(input, ports, done = []) {
     if (!ports.resource)
         put(missingPort('resource', '리소스 조회'));
     else if (!resource || resource.missing) {
-        put({ id: 'resource', kind: 'UNDECIDABLE', detail: '리소스를 읽지 못했다 (사라졌거나 접근 불가)' });
+        put({ id: 'resource', kind: 'UNDECIDABLE', detail: '리소스를 읽지 못했다 (사라졌거나 접근 불가)', reason: 'UNAVAILABLE' });
     }
     else {
         put({
@@ -60,7 +69,7 @@ export async function investigate(input, ports, done = []) {
     }
     // ② Delta — 현재 모습만 보면 무엇이 새로운지 알 수 없다.
     if (!input.previous) {
-        put({ id: 'delta', kind: 'SKIPPED', detail: '지난 관측이 없다 — 처음 보는 사건이다' });
+        put({ id: 'delta', kind: 'SKIPPED', detail: '지난 관측이 없다 — 처음 보는 사건이다', reason: 'NOT_APPLICABLE' });
     }
     else if (!resource) {
         put(missingPort('delta', '리소스 조회'));
@@ -88,11 +97,11 @@ export async function investigate(input, ports, done = []) {
     }
     put(responsibility.length > 0
         ? { id: 'responsibility', kind: 'DONE', findings: responsibility }
-        : { id: 'responsibility', kind: 'SKIPPED', detail: 'owner·결정 영역이 선언되지 않았다' });
+        : { id: 'responsibility', kind: 'SKIPPED', detail: 'owner·결정 영역이 선언되지 않았다', reason: 'NOT_APPLICABLE' });
     // ④ 지금 돌고 있는 것과의 관계.
     put(input.activeSessions?.length
         ? { id: 'work', kind: 'DONE', findings: [`활성 세션: ${input.activeSessions.join(', ')}`] }
-        : { id: 'work', kind: 'SKIPPED', detail: '지금 돌고 있는 세션이 없다' });
+        : { id: 'work', kind: 'SKIPPED', detail: '지금 돌고 있는 세션이 없다', reason: 'NOT_APPLICABLE' });
     // ⑤ Thread — 전부 읽지 않는다. 판단에 필요한 만큼만 (C-05 §3).
     if (!ports.resource)
         put(missingPort('thread', '스레드 조회'));
@@ -101,7 +110,7 @@ export async function investigate(input, ports, done = []) {
             .getComments(input.reference, { limit: input.commentLimit ?? 5 })
             .catch(() => null);
         put(comments === null
-            ? { id: 'thread', kind: 'UNDECIDABLE', detail: '논의를 읽지 못했다' }
+            ? { id: 'thread', kind: 'UNDECIDABLE', detail: '논의를 읽지 못했다', reason: 'UNAVAILABLE' }
             : {
                 id: 'thread',
                 kind: 'DONE',
@@ -128,7 +137,7 @@ export async function investigate(input, ports, done = []) {
     }
     // ⑦ Work Context — 작업 항목의 상태·연결. 코드 쪽과 다른 Binding일 수 있다.
     if (!input.workReference) {
-        put({ id: 'work-context', kind: 'SKIPPED', detail: '연결된 작업 항목이 선언되지 않았다' });
+        put({ id: 'work-context', kind: 'SKIPPED', detail: '연결된 작업 항목이 선언되지 않았다', reason: 'NOT_APPLICABLE' });
     }
     else if (!ports.work) {
         put(missingPort('work-context', '작업 항목 조회'));
@@ -136,7 +145,7 @@ export async function investigate(input, ports, done = []) {
     else {
         const item = await ports.work.getResource(input.workReference).catch(() => null);
         if (!item || item.missing) {
-            put({ id: 'work-context', kind: 'UNDECIDABLE', detail: '작업 항목을 읽지 못했다' });
+            put({ id: 'work-context', kind: 'UNDECIDABLE', detail: '작업 항목을 읽지 못했다', reason: 'UNAVAILABLE' });
         }
         else {
             // 경위는 있으면 더한다. 없다고 이 단계 전체가 무너지지는 않는다 —
@@ -163,7 +172,7 @@ export async function investigate(input, ports, done = []) {
     else {
         const snapshots = await ports.baselines().catch(() => null);
         if (!snapshots)
-            put({ id: 'canonical', kind: 'UNDECIDABLE', detail: '정본을 읽지 못했다' });
+            put({ id: 'canonical', kind: 'UNDECIDABLE', detail: '정본을 읽지 못했다', reason: 'UNAVAILABLE' });
         else {
             const touched = (change?.changedPaths ?? []).filter((path) => input.canonicalPaths?.length && isWithinScopes(path, input.canonicalPaths));
             canonicalConflict = touched.length > 0;
@@ -184,7 +193,7 @@ export async function investigate(input, ports, done = []) {
             kind: 'DONE',
             findings: input.relevance.evidence.map((e) => `${e.supports ? '+' : '-'} ${e.detail}`),
         }
-        : { id: 'relevance', kind: 'SKIPPED', detail: '관련성 판정을 받지 못했다' });
+        : { id: 'relevance', kind: 'SKIPPED', detail: '관련성 판정을 받지 못했다', reason: 'NOT_APPLICABLE' });
     const undecidable = steps
         .filter((s) => s.kind === 'UNDECIDABLE')
         .map((s) => `${s.id}: ${s.detail}`);