@asc-agent/runtime 0.3.2 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ proceed-by-default, escalation, audit, the external-write guard, host integratio
 here.
 
 ```bash
-npm install -g @asc-agent/runtime@0.3.2
+npm install -g @asc-agent/runtime@0.4.0
 ```
 
 npm owns the executable link (on Windows, npm's own `asc.cmd`). This package never edits

package/dist/adapters/claude-code/install.d.ts

@@ -1,6 +1,13 @@
 export type InstallPaths = {
     /** 보통 ~/.claude — 테스트가 격리 디렉터리를 넘긴다. */
     claudeHome: string;
+    /**
+     * 이 hook들을 부를 ASC CLI의 경로. SessionStart hook이 상태를 물어볼 곳이다.
+     *
+     * 없으면 SessionStart는 설치되지 않는다 — 어디를 부를지 모르는 hook을 심느니
+     * 그 기능이 없는 편이 낫다.
+     */
+    entry?: string;
 };
 export declare const defaultPaths: () => InstallPaths;
 export type InstallOutcome = {

package/dist/adapters/claude-code/install.js

@@ -14,12 +14,15 @@ import { mkdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { hookScript } from "./guard.js";
+import { sessionStartScript } from "./session-start.js";
 import { skillBundle } from "./skill.js";
 const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
 export const defaultPaths = () => ({ claudeHome: join(homedir(), '.claude') });
-const HOOK_MATCHER = 'Bash';
 const HOOK_MARKER = 'asc-external-write-guard';
+const FRONT_MARKER = 'asc-front-binding';
 function locate(paths) {
+    const guard = join(paths.claudeHome, 'asc', 'guard-hook.mjs');
+    const front = join(paths.claudeHome, 'asc', 'front-hook.mjs');
     return {
         /** Bundle 전체. 파일이 늘어도 아래 계약(manifest·digest·멱등)은 그대로다 (C-05 §5). */
         skills: skillBundle().map((skill) => ({
@@ -28,11 +31,84 @@ function locate(paths) {
             text: skill.text,
         })),
         /** hook은 **하나**로 둔다. guard는 안전 층이고 중복 등록은 그 자체가 위험이다. */
-        hook: join(paths.claudeHome, 'asc', 'guard-hook.mjs'),
+        hook: guard,
+        front,
         settings: join(paths.claudeHome, 'settings.json'),
         manifest: join(paths.claudeHome, 'asc', 'install-manifest.json'),
+        hooks: (() => {
+            const specs = [
+                { event: 'PreToolUse', marker: HOOK_MARKER, matcher: 'Bash', script: guard },
+            ];
+            // 부를 곳을 모르면 심지 않는다 (§InstallPaths.entry)
+            if (paths.entry)
+                specs.push({ event: 'SessionStart', marker: FRONT_MARKER, script: front });
+            return specs;
+        })(),
     };
 }
+/**
+ * settings.json 의 hook 목록에서 **우리 항목만** 손본다 (C-03 §5.1).
+ *
+ * 표식이 없는 남의 항목은 읽지도 고치지도 않는다. 여기가 "사용자의 host integration을
+ * 보존한다"가 실제로 지켜지는 자리다 — 사람이 넣어 둔 SessionStart hook 옆에 우리 것을
+ * **더할** 뿐이다.
+ *
+ * 표식 없이 우리 스크립트를 가리키는 항목은 **옛 설치본이다.** 그것을 남으로 보면 재설치가
+ * 같은 guard를 하나 더 등록해 버린다 (실측: 표식 이전 버전으로 설치한 기계에서 그렇게
+ * 됐다). 그래서 명령이 우리 스크립트를 가리키면 그 항목을 우리 것으로 **입양한다**.
+ */
+function reconcileHooks(settings, specs) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    const changed = [];
+    for (const spec of specs) {
+        const command = hookCommand(spec.script);
+        const entries = [...(hooks[spec.event] ?? [])];
+        let touched = false;
+        // 표식 없이 우리 스크립트를 가리키는 옛 항목을 입양한다
+        for (const entry of entries) {
+            for (const hook of entry.hooks ?? []) {
+                if (hook._asc === undefined && hook.command === command) {
+                    hook._asc = spec.marker;
+                    touched = true;
+                }
+            }
+        }
+        const ours = entries.filter((entry) => entry.hooks?.some((h) => h._asc === spec.marker));
+        if (ours.length === 0) {
+            entries.push({
+                ...(spec.matcher ? { matcher: spec.matcher } : {}),
+                hooks: [{ type: 'command', command, _asc: spec.marker }],
+            });
+            touched = true;
+        }
+        else {
+            // 등록은 돼 있는데 **다른 곳을 가리키는** 경우가 있다 — 그 상태에서 "설치됨"이라고
+            // 하면 hook이 없는데 있다고 믿는다. 우리 항목만 지금 경로로 고친다.
+            for (const entry of ours) {
+                for (const hook of entry.hooks ?? []) {
+                    if (hook._asc === spec.marker && hook.command !== command) {
+                        hook.command = command;
+                        touched = true;
+                    }
+                }
+            }
+            // 같은 표식이 여럿이면 하나만 남긴다 — 중복 등록은 그 자체가 결함이다
+            if (ours.length > 1) {
+                for (const extra of ours.slice(1)) {
+                    const at = entries.indexOf(extra);
+                    if (at >= 0)
+                        entries.splice(at, 1);
+                }
+                touched = true;
+            }
+        }
+        if (touched) {
+            hooks[spec.event] = entries;
+            changed.push(spec.event);
+        }
+    }
+    return { settings: changed.length > 0 ? { ...settings, hooks } : settings, changed };
+}
 async function readJson(path) {
     try {
         return JSON.parse(await readFile(path, 'utf8'));
@@ -60,6 +136,8 @@ export async function install(paths, now = () => new Date().toISOString(), opts
     for (const [path, content] of [
         ...where.skills.map((skill) => [skill.path, skill.text]),
         [where.hook, hookScript()],
+        // 부를 CLI를 모르면 SessionStart hook 자체를 만들지 않는다
+        ...(paths.entry ? [[where.front, sessionStartScript(paths.entry)]] : []),
     ]) {
         const existing = await readFile(path, 'utf8').catch(() => null);
         const state = fileState(existing, content, manifest.files[path]);
@@ -81,30 +159,12 @@ export async function install(paths, now = () => new Date().toISOString(), opts
         manifest.files[path] = sha(content);
         written.push(path);
     }
-    // settings.json에 PreToolUse hook 등록 — ASC 항목만 다루고 나머지는 손대지 않는다
-    const settings = (await readJson(where.settings)) ?? {};
-    const hooks = (settings.hooks ?? {});
-    const preToolUse = (hooks.PreToolUse ?? []);
-    const command = hookCommand(where.hook);
-    const ours = preToolUse.filter((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER));
-    // 등록은 돼 있는데 **다른 곳을 가리키는** 경우가 있다 — 그 상태에서 "설치됨"이라고
-    // 하면 guard가 없는데 있다고 믿는다. 우리 항목만 지금 경로로 고친다.
-    const misdirected = ours.some((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER && h.command !== command));
-    if (ours.length === 0) {
-        preToolUse.push({ matcher: HOOK_MATCHER, hooks: [{ type: 'command', command, _asc: HOOK_MARKER }] });
-    }
-    else if (misdirected) {
-        for (const entry of ours) {
-            for (const h of entry.hooks ?? [])
-                if (h._asc === HOOK_MARKER)
-                    h.command = command;
-        }
-    }
-    if (ours.length === 0 || misdirected) {
-        settings.hooks = { ...hooks, PreToolUse: preToolUse };
+    // settings.json 의 hook 등록 — **ASC 항목만** 다루고 나머지는 한 글자도 건드리지 않는다
+    const reconciled = reconcileHooks((await readJson(where.settings)) ?? {}, where.hooks);
+    if (reconciled.changed.length > 0) {
         await mkdir(dirname(where.settings), { recursive: true });
-        await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-        written.push(`${where.settings} (PreToolUse hook)`);
+        await writeFile(where.settings, JSON.stringify(reconciled.settings, null, 2) + '\n', 'utf8');
+        written.push(`${where.settings} (${reconciled.changed.join(', ')} hook)`);
     }
     manifest.settingsHook = true;
     await mkdir(dirname(where.manifest), { recursive: true });
@@ -131,6 +191,7 @@ export async function verifyInstall(paths) {
     const expected = [
         ...where.skills.map((skill) => [skill.path, skill.text]),
         [where.hook, hookScript()],
+        ...(paths.entry ? [[where.front, sessionStartScript(paths.entry)]] : []),
     ];
     const files = [];
     for (const [path, content] of expected) {
@@ -138,11 +199,16 @@ export async function verifyInstall(paths) {
         files.push({ path, state: fileState(existing, content, manifest?.files[path]) });
     }
     const settings = await readJson(where.settings);
-    const preToolUse = (settings?.hooks?.PreToolUse ?? []);
-    const ourHooks = preToolUse.flatMap((entry) => (entry.hooks ?? []).filter((h) => h._asc === HOOK_MARKER));
-    const hookRegistered = ourHooks.length > 0;
+    // 이벤트마다 우리 항목이 있는가. 하나라도 없으면 등록이 성립하지 않은 것으로 본다 —
+    // 반쯤 등록된 상태를 "설치됨"이라 부르면 없는 hook을 있다고 믿게 된다.
+    const registrations = where.hooks.map((spec) => {
+        const entries = (settings?.hooks?.[spec.event] ?? []);
+        const mine = entries.flatMap((entry) => (entry.hooks ?? []).filter((h) => h._asc === spec.marker));
+        return { present: mine.length > 0, pointsHere: mine.some((h) => h.command === hookCommand(spec.script)) };
+    });
+    const hookRegistered = registrations.every((r) => r.present);
     // 등록은 있는데 다른 곳을 가리키면 설치본이 뒤처진 것이다 — 없는 것으로 치지 않고 stale로 본다
-    const hookMisdirected = hookRegistered && !ourHooks.some((h) => h.command === hookCommand(where.hook));
+    const hookMisdirected = registrations.some((r) => r.present && !r.pointsHere);
     const status = (() => {
         if (!manifest && files.every((f) => f.state === 'missing') && !hookRegistered)
             return 'NOT_INSTALLED';
@@ -179,7 +245,7 @@ export function installReportLines(report) {
         lines.push(`  [${file.state}] ${file.path}`);
     }
     if (!report.hookRegistered)
-        lines.push('  [missing] PreToolUse hook registration in settings.json');
+        lines.push('  [missing] an ASC hook registration in settings.json');
     return lines;
 }
 /** manifest로 증명되는 것만 제거한다. 사용자가 고친 파일은 남기고 이유를 말한다. */
@@ -201,22 +267,32 @@ export async function uninstall(paths) {
         await rm(path);
         removed.push(path);
     }
-    // settings에서 ASC hook 항목만 걷어낸다 — 무관한 설정은 그대로
+    // settings에서 ASC hook 항목만 걷어낸다 — 무관한 설정은 그대로.
+    // 표식(`_asc`)이 소유권의 근거다: 사람이 넣은 SessionStart hook은 그 자리에 남는다.
     const settings = await readJson(where.settings);
     if (settings?.hooks) {
         const hooks = settings.hooks;
-        const preToolUse = (hooks.PreToolUse ?? []);
-        const filtered = preToolUse.filter((entry) => !entry.hooks?.some((h) => h._asc === HOOK_MARKER));
-        if (filtered.length !== preToolUse.length) {
-            if (filtered.length > 0)
-                hooks.PreToolUse = filtered;
+        // 지금 설치가 SessionStart를 안 심었더라도 옛 설치가 남긴 것은 걷는다 —
+        // 우리 표식이 붙은 것은 전부 우리 것이다.
+        const markers = new Set([HOOK_MARKER, FRONT_MARKER]);
+        const dropped = [];
+        for (const [event, value] of Object.entries(hooks)) {
+            const entries = (value ?? []);
+            const kept = entries.filter((entry) => !entry.hooks?.some((h) => h._asc && markers.has(h._asc)));
+            if (kept.length === entries.length)
+                continue;
+            if (kept.length > 0)
+                hooks[event] = kept;
             else
-                delete hooks.PreToolUse;
+                delete hooks[event];
+            dropped.push(event);
+        }
+        if (dropped.length > 0) {
             // 우리가 만든 hooks 컨테이너가 비면 키째 걷는다 — 빈 {}도 원래 없던 흔적이다
             if (Object.keys(hooks).length === 0)
                 delete settings.hooks;
             await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-            removed.push(`${where.settings} (PreToolUse hook entry)`);
+            removed.push(`${where.settings} (${dropped.join(', ')} hook entry)`);
         }
     }
     await rm(where.manifest, { force: true });

package/dist/adapters/claude-code/session-start.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SessionStart hook이 stdout으로 내는 봉투.
+ *
+ * 보여 줄 것이 없으면 **아무것도 내지 않는다** (`null`). 빈 봉투를 내면 ASC와 무관한
+ * 프로젝트의 모든 세션 첫 화면에 빈 블록이 붙는다 — 남의 도구를 방해하지 않는다
+ * (C-11 불변식 ⑪).
+ */
+export declare function sessionStartPayload(lines: readonly string[]): string | null;
+/**
+ * SessionStart hook 본문.
+ *
+ * `entry` 는 이 hook을 설치한 CLI의 경로다. 그 CLI가 다시 선택된 build로 넘긴다
+ * (`runtime use development` 도 그래서 그대로 먹는다) — hook이 build를 고르지 않는다.
+ *
+ * 계약 셋:
+ *   세션을 절대 막지 않는다        — 무슨 일이 나도 exit 0, stdout은 비거나 봉투 하나
+ *   ASC 무관 프로젝트에서 조용하다  — index에 없으면 CLI를 부르지도 않는다
+ *   기다리게 하지 않는다           — 상한을 두고, 넘으면 그냥 지나간다
+ */
+export declare function sessionStartScript(entry: string): string;

package/dist/adapters/claude-code/session-start.js

@@ -0,0 +1,111 @@
+// Claude Host — 세션이 열리면 지금 상태를 되찾는다 (C-12 §4·C-03 §5.6).
+//
+// Core는 "여기서 Front가 열렸다"까지만 안다 (`openFront`). 이 파일이 하는 일은 그 판정을
+// **Claude Code의 형식으로 옮기는 것**뿐이다:
+//
+//   Host lifecycle (SessionStart)  →  asc front open  →  additionalContext
+//
+// hook은 관찰이지 전이 권한이 아니다 (C-03 §5.6). 여기서 세션을 만들지 않고, 상태를
+// 옮기지 않으며, 승인 대기를 소비하지 않는다 — 읽고 보여 주는 것이 전부다.
+//
+// **다른 Host가 생겨도 Core는 그대로다.** 바뀌는 것은 이 파일 같은 adapter 하나다.
+/**
+ * SessionStart hook이 stdout으로 내는 봉투.
+ *
+ * 보여 줄 것이 없으면 **아무것도 내지 않는다** (`null`). 빈 봉투를 내면 ASC와 무관한
+ * 프로젝트의 모든 세션 첫 화면에 빈 블록이 붙는다 — 남의 도구를 방해하지 않는다
+ * (C-11 불변식 ⑪).
+ */
+export function sessionStartPayload(lines) {
+    if (lines.length === 0)
+        return null;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext: ['ASC — what is open in this workspace right now:', ...lines].join('\n'),
+        },
+    });
+}
+/**
+ * SessionStart hook 본문.
+ *
+ * `entry` 는 이 hook을 설치한 CLI의 경로다. 그 CLI가 다시 선택된 build로 넘긴다
+ * (`runtime use development` 도 그래서 그대로 먹는다) — hook이 build를 고르지 않는다.
+ *
+ * 계약 셋:
+ *   세션을 절대 막지 않는다        — 무슨 일이 나도 exit 0, stdout은 비거나 봉투 하나
+ *   ASC 무관 프로젝트에서 조용하다  — index에 없으면 CLI를 부르지도 않는다
+ *   기다리게 하지 않는다           — 상한을 두고, 넘으면 그냥 지나간다
+ */
+export function sessionStartScript(entry) {
+    return `#!/usr/bin/env node
+// ASC front binding (SessionStart) — 설치·갱신은 \`asc host claude install\` 로만.
+// 이 자리에 붙은 ASC workspace가 있으면 지금 무엇이 걸려 있는지 세션 첫 화면에 얹는다.
+// ASC와 무관한 프로젝트에서는 아무것도 하지 않는다.
+//
+// **이 hook은 무엇도 막지 않는다.** 어떤 실패도 exit 0 이고, 그때 stdout은 비어 있다 —
+// 상태를 못 읽었다고 사람의 세션이 안 열리면 그것이 더 큰 고장이다.
+//
+// **workspace 신원을 여기서 판정하지 않는다.** 예전에는 index를 직접 뒤져 걸리지 않으면
+// 빠져나갔는데, 그러면 아직 등록되지 않은 linked worktree에서 Host를 처음 여는 경우가
+// 통째로 빠진다 — 그 자리를 풀 수 있는 것은 공용 resolver뿐이다 (C-11 §1.3).
+// 여기서 보는 것은 "이 기계가 ASC를 쓰기는 하는가" 한 가지이고, 그것은 신원이 아니다.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const ENTRY = ${JSON.stringify(entry)}
+/** 이 안에 못 끝내면 지나간다. 세션 시작을 기다리게 하지 않는다. */
+const BUDGET_MS = 10_000
+
+/**
+ * 이 기계에 ASC runtime state가 있는가 — 파일 존재 확인 하나.
+ *
+ * 없으면 어느 경로도 ASC 자리일 수 없으므로 CLI를 부르지 않는다. 이것은 workspace
+ * 판정이 아니라 "부를 이유가 있는가"이며, 그 판정은 아래 \`front open\` 이 한다.
+ */
+function ascUsedHere() {
+  const home = process.env.ASC_HOME || join(homedir(), '.asc')
+  return existsSync(join(home, 'workspace-index.json')) || existsSync(join(home, 'workspaces'))
+}
+
+function main() {
+  let cwd = process.cwd()
+  try {
+    // SessionStart 입력에 cwd가 실린다. 없으면 프로세스의 cwd가 곧 그 자리다.
+    const raw = readFileSync(0, 'utf8')
+    if (raw.trim()) cwd = JSON.parse(raw).cwd || cwd
+  } catch {
+    // 읽지 못해도 계속한다 — 입력 형식 하나 때문에 복원을 통째로 버리지 않는다
+  }
+
+  if (!ascUsedHere()) return
+
+  // 붙지 않은 자리에서도 이 명령은 성공하고 조용하다. 판정은 전부 저쪽이 한다.
+  const run = spawnSync(process.execPath, [ENTRY, 'front', 'open', '--json'], {
+    cwd,
+    encoding: 'utf8',
+    timeout: BUDGET_MS,
+    env: process.env,
+  })
+  if (run.status !== 0 || !run.stdout) return
+
+  let payload
+  try {
+    payload = JSON.parse(run.stdout).payload
+  } catch {
+    return
+  }
+  if (typeof payload === 'string' && payload) process.stdout.write(payload)
+}
+
+try {
+  main()
+} catch {
+  // 세션을 막지 않는다
+}
+process.exit(0)
+`;
+}

package/dist/adapters/jam/adapter.d.ts

@@ -7,8 +7,8 @@ export type JamAdapterDeps = {
      */
     command?: string;
     args?: readonly string[];
-    /** 상태 조회 통로. 테스트가 실제 프로세스를 띄우지 않기 위한 주입점. */
-    authStatus?: (context: DiscoveryContext) => Promise<AuthStatus>;
+    /** 진단 통로. 테스트가 실제 프로세스를 띄우지 않기 위한 주입점. */
+    doctor?: (context: DiscoveryContext) => Promise<JamDoctor>;
     /** 선언 파일 읽기 통로. */
     readDeclaration?: (projectRoot: string) => Promise<string | null>;
     /** 개인 선언 파일 읽기 통로. */
@@ -16,16 +16,51 @@ export type JamAdapterDeps = {
     /** 이 저장소의 remote 들. 개인 선언과 맞출 때만 쓴다. */
     listRemotes?: (projectRoot: string) => Promise<string[]>;
 };
-/** `jam auth status --json` 의 응답. **토큰 값은 여기 오지 않는다.** */
-export type AuthStatus = {
-    status?: 'configured' | 'not_configured';
-    code?: string;
-    source?: string;
-    /** 어느 인스턴스인지. 사람이 "맞는 곳인가"를 확인하는 데 쓴다. */
-    baseUrl?: string;
+/**
+ * `doctor --json` 의 응답에서 우리가 읽는 부분. **토큰 값은 여기 오지 않는다.**
+ *
+ * JAM 이 진단의 정본이다 (설계 §9.2). ASC 는 그 판정을 다시 만들지 않고 번역만 한다 —
+ * 예전에는 `auth status` 하나만 보고 준비 상태를 정했는데, 그러면 자격은 멀쩡한데
+ * 프로젝트 결합이나 host 등록이 어긋난 상태를 "쓸 수 있다"로 읽는다.
+ */
+export type JamDoctor = {
+    status?: 'ready' | 'failed' | string;
+    diagnosis?: Record<string, {
+        state?: string;
+        code?: string;
+        detail?: string;
+    }>;
+    axes?: Record<string, string>;
     /** 실행 자체가 안 됐을 때의 이유. */
     error?: string;
 };
+/** 되살릴 수 있는가, 사람이 해야 하는가 (설계 §9.4). */
+export type JamRemedy = 
+/** 사람만 할 수 있다 — 자격 입력. ASC 는 토큰을 받지도 저장하지도 않는다. */
+{
+    kind: 'HUMAN';
+    code: string;
+    detail: string;
+}
+/** ASC 가 JAM 의 공식 setup 으로 스스로 고칠 수 있다. */
+ | {
+    kind: 'SELF_HEAL';
+    code: string;
+    detail: string;
+}
+/** 다시 돌려도 달라지지 않는다. */
+ | {
+    kind: 'HARD';
+    code: string;
+    detail: string;
+};
+/**
+ * doctor 판정을 ASC 가 쓰는 세 갈래로 옮긴다.
+ *
+ * **코드로만 분기한다** — JAM 이 산문을 바꿔도 판정이 흔들리지 않아야 하고, 우리가 모르는
+ * 코드는 사람에게 넘긴다(조용히 자가 치유를 시도하지 않는다).
+ */
+export declare function remedyFor(doctor: JamDoctor): JamRemedy | null;
 /**
  * 어떻게 실행할 것인가.
  *
@@ -54,6 +89,8 @@ export declare class JamAdapter implements Adapter {
     probe(candidate: BindingCandidate, context: DiscoveryContext): Promise<ProbeResult>;
     /** 프로젝트와 무관하게 "도구가 지금 쓸 수 있는가". binding 유무와 별개 사실이다. */
     runtime(context: DiscoveryContext): Promise<RuntimeStatus>;
+    /** 직전 진단이 무엇을 요구했는가. 없으면 문제 없거나 아직 안 물어봤다. */
+    lastRemedy(): JamRemedy | null;
 }
 /**
  * 개인 선언에서 `workspace` 와 `key` 짝만 꺼낸다. YAML 파서를 들이지 않는다 —

package/dist/adapters/jam/adapter.js

@@ -37,6 +37,40 @@ const DECLARATION = join('.jira-agent', 'project.yaml');
  * 개인 선언은 remote 로 맞춘다(파일의 `path` 는 출처 기록일 뿐이다).
  */
 const PERSONAL_BINDINGS = join('.jam', 'projects.yaml');
+/**
+ * doctor 판정을 ASC 가 쓰는 세 갈래로 옮긴다.
+ *
+ * **코드로만 분기한다** — JAM 이 산문을 바꿔도 판정이 흔들리지 않아야 하고, 우리가 모르는
+ * 코드는 사람에게 넘긴다(조용히 자가 치유를 시도하지 않는다).
+ */
+export function remedyFor(doctor) {
+    if (doctor.status === 'ready')
+        return null;
+    const failed = Object.entries(doctor.diagnosis ?? {}).filter(([, axis]) => axis.state === 'FAILED');
+    if (failed.length === 0)
+        return null;
+    for (const [axis, value] of failed) {
+        const code = value.code ?? axis;
+        const detail = value.detail ?? axis;
+        // 자격은 사람 몫이다. JAM 이 그렇게 설계돼 있고 ASC 가 그것을 우회하지 않는다.
+        if (code === 'JAM_AUTH_REQUIRED' || axis === 'credentials' || axis === 'jiraAuthentication') {
+            return { kind: 'HUMAN', code, detail };
+        }
+    }
+    const [firstAxis, first] = failed[0];
+    const code = first.code ?? firstAxis;
+    const detail = first.detail ?? firstAxis;
+    // 프로젝트 결합·runtime 설정·host 등록은 JAM 의 공식 setup 이 고친다.
+    const healable = new Set([
+        'JAM_PROJECT_SELECTION_REQUIRED',
+        'JAM_RUNTIME_CONFIG_MISSING',
+        'HOST_REGISTRATION_STALE',
+        'HOST_REGISTRATION_MISSING',
+    ]);
+    if (healable.has(code))
+        return { kind: 'SELF_HEAL', code, detail };
+    return { kind: 'HARD', code, detail };
+}
 /**
  * 어떻게 실행할 것인가.
  *
@@ -61,14 +95,14 @@ export function parseProjectKey(text) {
 export class JamAdapter {
     #command;
     #args;
-    #authStatus;
+    #doctor;
     #readDeclaration;
     #readPersonalBindings;
     #listRemotes;
     constructor(deps = {}) {
         this.#command = deps.command ?? 'jam';
         this.#args = deps.args ?? [];
-        this.#authStatus = deps.authStatus;
+        this.#doctor = deps.doctor;
         this.#readDeclaration = deps.readDeclaration ?? defaultRead;
         this.#readPersonalBindings = deps.readPersonalBindings ?? defaultReadPersonal;
         this.#listRemotes = deps.listRemotes ?? defaultListRemotes;
@@ -79,10 +113,10 @@ export class JamAdapter {
             version: '1',
             provides: PROVIDES,
             // 자격이 필요하다는 사실과 **사람이 해야 한다는 사실**까지. 값은 오지 않는다.
-            requiresCredential: ['사람이 직접 `jam auth login` — ASC가 대신 로그인하지 않는다'],
+            requiresCredential: ['사람이 직접 JAM 에 로그인해야 한다 — ASC가 대신 로그인하지 않는다'],
             prerequisites: [
-                '프로젝트 루트에 .jira-agent/project.yaml 이 있어야 한다',
-                'JAM 실행 경로를 ASC_JAM_PATH 로 알려 줘야 한다 (아직 패키지로 배포되지 않았다)',
+                // 개인 결합이 기본값이다. 저장소에 파일을 두는 것은 팀이 채택했을 때뿐이다.
+                'JAM 이 이 workspace 를 Jira 프로젝트에 결합하고 있어야 한다 (개인 결합이 기본, 팀 채택 시 .jira-agent/project.yaml)',
             ],
         };
     }
@@ -99,9 +133,19 @@ export class JamAdapter {
             return [{ adapterId: 'jam', resource: key, provides: PROVIDES, discoveredBy: DECLARATION }];
         // 저장소에 선언이 없다고 붙어 있지 않은 것은 아니다 — 개인 자리를 본다.
         const personal = await this.#personalKey(context);
-        if (!personal)
-            return [];
-        return [{ adapterId: 'jam', resource: personal, provides: PROVIDES, discoveredBy: PERSONAL_BINDINGS }];
+        if (personal) {
+            return [{ adapterId: 'jam', resource: personal, provides: PROVIDES, discoveredBy: PERSONAL_BINDINGS }];
+        }
+        // 지역 흔적이 없어도 **Profile 이 이미 정해 둔 것**은 후보다 (설계 §9.3).
+        // 이것은 추측이 아니다 — 사람이 적은 결정이고, 실제로 되는지는 probe 가 정한다.
+        // 이 갈래가 없으면 "선언은 있는데 아무 일도 일어나지 않는" 상태가 남는다.
+        const declared = (context.declared ?? []).filter((entry) => entry.adapterId === 'jam');
+        return declared.map((entry) => ({
+            adapterId: 'jam',
+            resource: entry.resource,
+            provides: PROVIDES,
+            discoveredBy: 'Profile bindings',
+        }));
     }
     /** 개인 선언에서 이 저장소의 키를 찾는다. remote 가 일치할 때만 — 이름이 비슷한 것은 근거가 아니다. */
     async #personalKey(context) {
@@ -129,29 +173,46 @@ export class JamAdapter {
     async runtime(context) {
         return this.#status(context);
     }
+    /** 마지막 진단. setup 경로가 자가 치유 여부를 정할 때 읽는다 — 다시 돌리지 않기 위해서다. */
+    #lastRemedy = null;
+    /** 직전 진단이 무엇을 요구했는가. 없으면 문제 없거나 아직 안 물어봤다. */
+    lastRemedy() {
+        return this.#lastRemedy;
+    }
     async #status(context) {
-        const read = this.#authStatus ?? ((ctx) => this.#defaultAuthStatus(ctx));
-        const status = await read(context).catch((error) => ({ error: String(error) }));
-        if (status.error) {
-            return { state: 'UNAVAILABLE', detail: `JAM을 실행하지 못했다 — ${status.error}` };
+        const read = this.#doctor ?? ((ctx) => this.#defaultDoctor(ctx));
+        const doctor = await read(context).catch((error) => ({ error: String(error) }));
+        if (doctor.error) {
+            this.#lastRemedy = null;
+            return { state: 'UNAVAILABLE', detail: `JAM을 실행하지 못했다 — ${doctor.error}` };
         }
-        if (status.status === 'configured') {
-            return { state: 'AVAILABLE', ...(status.baseUrl ? { detail: `연결 대상 ${status.baseUrl}` } : {}) };
+        const remedy = remedyFor(doctor);
+        this.#lastRemedy = remedy;
+        if (!remedy)
+            return { state: 'AVAILABLE', ...(jamTarget(doctor) ? { detail: jamTarget(doctor) } : {}) };
+        switch (remedy.kind) {
+            case 'HUMAN':
+                // 설정이 안 된 것은 고장이 아니다. 사람이 할 일이 남았다는 뜻이고, 그 일을 알려 준다.
+                return {
+                    state: 'UNCONFIGURED',
+                    detail: `${remedy.code} — 사람이 직접 JAM 에 로그인해야 한다 (ASC가 대신하지 않는다): ${remedy.detail}`,
+                };
+            case 'SELF_HEAL':
+                // 고칠 수 있는 것을 "못 쓴다"로 적지 않는다 — 그 판단이 setup 을 멈추게 만든다.
+                return { state: 'UNCONFIGURED', detail: `${remedy.code} — JAM 공식 setup 으로 고칠 수 있다: ${remedy.detail}` };
+            case 'HARD':
+                return { state: 'UNAVAILABLE', detail: `${remedy.code} — ${remedy.detail}` };
         }
-        // 설정이 안 된 것은 고장이 아니다. 사람이 할 일이 남았다는 뜻이고, 그 일을 알려 준다.
-        return {
-            state: 'UNCONFIGURED',
-            detail: '자격이 없다 — 사람이 직접 `jam auth login` 을 실행해야 한다 (ASC가 대신하지 않는다)',
-        };
     }
-    async #defaultAuthStatus(context) {
+    async #defaultDoctor(context) {
         const { command, args } = resolveJamCommand(context.env, this.#command, this.#args);
         try {
-            const { stdout } = await run(command, [...args, 'auth', 'status', '--json']);
+            const { stdout } = await run(command, [...args, 'doctor', '--json'], { cwd: context.projectRoot });
             return JSON.parse(stdout);
         }
         catch (error) {
-            // 실행 실패와 "자격 없음"을 합치지 않는다. 전자는 설치·경로 문제다.
+            // 실행 실패와 "준비 안 됨"을 합치지 않는다. 전자는 설치·경로 문제다.
+            // doctor 는 준비되지 않았을 때 0 이 아닌 코드로 끝나면서도 JSON 을 낸다.
             const stdout = error.stdout;
             if (stdout) {
                 try {
@@ -165,6 +226,11 @@ export class JamAdapter {
         }
     }
 }
+/** 어느 인스턴스에 붙었는지. 사람이 "맞는 곳인가"를 확인하는 데 쓴다. */
+function jamTarget(doctor) {
+    const detail = doctor.diagnosis?.credentials?.detail ?? doctor.diagnosis?.jiraAuthentication?.detail;
+    return detail ? `연결 확인됨 (${detail})` : null;
+}
 async function defaultRead(projectRoot) {
     try {
         return await readFile(join(projectRoot, DECLARATION), 'utf8');