@asc-agent/runtime 0.3.2 → 0.5.0

package/dist/adapters/gitlab/coordination.js

@@ -0,0 +1,111 @@
+// GitLab 조율 표면 — 밖에 있는 durable 한 조율 게시물 하나를 찾고, 만들고, 되읽는다.
+//
+// 이 파일은 provider 를 아는 자리다. Core 는 `CoordinationSurfacePort` 만 알고 여기 이름을
+// 모른다 (C-09 §6). 그래서 여기서 GitLab 어휘를 쓰는 것은 계약대로이고, Core 쪽에 같은
+// 어휘가 새는 것은 결함이다.
+//
+// 신원을 무엇으로 삼는가가 이 adapter 의 핵심 결정이다. 주소(web_url)는 쓰지 않는다 —
+// 호스트가 바뀌고, 프로젝트가 옮겨 다니고, 같은 게시물이 다른 주소로 보인다. 대신
+// `group/project#iid` 를 쓴다. 이 값은 그 시스템 안에서 안정적이고, 스스로 어느 프로젝트인지
+// 말하므로 되읽기가 다른 정보를 필요로 하지 않는다.
+import { encodeProject, parseRef } from "./client.js";
+/** 상관 관계를 심는 방법. 라벨 하나이고, 그 안에 들어가는 것은 기대 id 뿐이다. */
+export const CORRELATION_LABEL = 'asc-coordination';
+const correlationLabel = (correlation) => `${CORRELATION_LABEL}:${correlation}`;
+export class GitLabCoordinationSurface {
+    id = 'gitlab';
+    #reader;
+    #writer;
+    #project;
+    constructor(deps) {
+        this.#reader = deps.reader;
+        this.#writer = deps.writer;
+        this.#project = deps.project;
+    }
+    #identity(issue, project = this.#project) {
+        return {
+            adapter: this.id,
+            objectType: 'issue',
+            // 주소가 아니라 이 값이 정본이다.
+            objectId: `${project}#${issue.iid}`,
+            resource: project,
+            ...(issue.web_url ? { locator: issue.web_url } : {}),
+            ...(issue.updated_at ? { revisionMarker: issue.updated_at } : {}),
+        };
+    }
+    #candidate(issue, matchedBy) {
+        return {
+            identity: this.#identity(issue),
+            title: issue.title,
+            matchedBy,
+            ...(issue.state === 'closed' ? { closed: true } : {}),
+        };
+    }
+    async find(query) {
+        const out = [];
+        const seen = new Set();
+        const add = (candidate) => {
+            if (seen.has(candidate.identity.objectId))
+                return;
+            seen.add(candidate.identity.objectId);
+            out.push(candidate);
+        };
+        // 1) 이미 아는 게시물. 가장 강한 근거이고, 여기서 걸리면 나머지를 볼 이유가 없다.
+        for (const known of query.known ?? []) {
+            const snapshot = await this.read(known);
+            if (snapshot) {
+                add({
+                    identity: snapshot.identity,
+                    title: snapshot.title,
+                    matchedBy: 'known-identity',
+                    ...(snapshot.closed ? { closed: true } : {}),
+                });
+            }
+        }
+        // 2) 우리가 심어 둔 상관 관계. 라벨은 그 시스템이 색인하는 값이라 제목처럼 흔들리지 않는다.
+        const labelled = await this.#reader.get(`/projects/${encodeProject(this.#project)}/issues?labels=${encodeURIComponent(correlationLabel(query.correlation))}&state=all&per_page=20`);
+        if (!labelled.ok) {
+            // 못 찾은 것을 없는 것으로 넘기지 않는다. 호출자가 이 차이로 판단한다.
+            throw new Error(labelled.error ?? `issue search failed (${labelled.status})`);
+        }
+        for (const issue of labelled.data ?? [])
+            add(this.#candidate(issue, 'correlation'));
+        // 3) 작업 항목으로 훑는다. **약한 근거다** — 같은 작업에 여러 조율이 붙을 수 있다.
+        if (query.workReference) {
+            const searched = await this.#reader.get(`/projects/${encodeProject(this.#project)}/issues?search=${encodeURIComponent(query.workReference)}&in=title,description&state=all&per_page=20`);
+            if (searched.ok)
+                for (const issue of searched.data ?? [])
+                    add(this.#candidate(issue, 'work-reference'));
+        }
+        return out;
+    }
+    async create(payload, query) {
+        if (!this.#writer)
+            throw new Error('this binding has no write channel — nothing was created');
+        // **여기를 지나는 것이 밖으로 나가는 전부다.** payload 밖의 값은 이 함수에 오지 않고,
+        // 라벨 하나만 우리가 덧붙인다 — 다음 회차가 이 게시물을 다시 찾는 근거다.
+        const labels = [...(payload.labels ?? []), correlationLabel(query.correlation)].join(',');
+        const created = await this.#writer.post(`/projects/${encodeProject(this.#project)}/issues`, {
+            title: payload.title,
+            description: payload.body,
+            labels,
+        });
+        if (!created.ok || !created.data) {
+            throw new Error(created.error ?? `issue create failed (${created.status})`);
+        }
+        return this.#identity(created.data);
+    }
+    async read(identity) {
+        const parsed = parseRef(identity.objectId);
+        if (!parsed || parsed.kind !== 'issue')
+            return null;
+        const response = await this.#reader.get(`/projects/${encodeProject(parsed.project)}/issues/${parsed.iid}`);
+        if (!response.ok || !response.data)
+            return null;
+        return {
+            identity: this.#identity(response.data, parsed.project),
+            title: response.data.title,
+            ...(response.data.state === 'closed' ? { closed: true } : {}),
+        };
+    }
+}

package/dist/adapters/gitlab/ports.d.ts

@@ -21,6 +21,12 @@ declare abstract class GitLabBase {
  * 할 일 목록(todo)으로 증분을 받는다. GitHub의 알림과 같은 자리이고, 같은 한계를 갖는다 —
  * 지정이 빠지면 오지 않는다. 그래서 Inventory가 따로 있다.
  */
+/**
+ * 두 시각 중 늦은 것. ISO 문자열이지만 **문자열 비교를 하지 않는다** — 이 API 는 계정 설정에
+ * 따라 `+09:00` 과 `Z` 를 섞어 돌려주고, 그 둘은 사전순과 시간순이 다르다. 해석이 안 되는
+ * 값은 비교하지 않고 있는 쪽을 택한다.
+ */
+export declare function laterOf(a: string | undefined, b: string | undefined): string | undefined;
 export declare class GitLabEventSource extends GitLabBase implements EventSource {
     readonly id = "gitlab-todo";
     cursorFrom(since: string): Cursor;

package/dist/adapters/gitlab/ports.js

@@ -33,6 +33,22 @@ class GitLabBase {
  * 할 일 목록(todo)으로 증분을 받는다. GitHub의 알림과 같은 자리이고, 같은 한계를 갖는다 —
  * 지정이 빠지면 오지 않는다. 그래서 Inventory가 따로 있다.
  */
+/**
+ * 두 시각 중 늦은 것. ISO 문자열이지만 **문자열 비교를 하지 않는다** — 이 API 는 계정 설정에
+ * 따라 `+09:00` 과 `Z` 를 섞어 돌려주고, 그 둘은 사전순과 시간순이 다르다. 해석이 안 되는
+ * 값은 비교하지 않고 있는 쪽을 택한다.
+ */
+export function laterOf(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (Number.isNaN(ta) || Number.isNaN(tb))
+        return a >= b ? a : b;
+    return tb > ta ? b : a;
+}
 export class GitLabEventSource extends GitLabBase {
     id = 'gitlab-todo';
     cursorFrom(since) {
@@ -46,8 +62,13 @@ export class GitLabEventSource extends GitLabBase {
         const response = await this.client.get(`/todos?${params}`);
         if (!response.ok || !response.data)
             return { events: [], cursor };
+        // 이번 회차(페이지 전체)에서 본 가장 늦은 시각. **반환 순서를 믿지 않는다** — 이 목록은
+        // 최신순으로 오므로 마지막 항목이 가장 오래된 것이었고, 그것을 다음 기준선으로 삼자
+        // 커서가 옛 시각에 고정돼 같은 것을 매 회차 다시 읽었다. 기준선은 뒤로 가지 않는다.
+        let highWater = parsed.highWater ?? parsed.since;
         const events = [];
         for (const todo of response.data) {
+            highWater = laterOf(highWater, todo.updated_at);
             // 기준선 이전 것은 버린다. provider가 since를 지원하지 않아 여기서 거른다 —
             // 겹쳐 읽고 key로 중복을 거르는 편이 놓치는 것보다 싸다 (OM §10.5).
             if (parsed.since && todo.updated_at < parsed.since)
@@ -69,8 +90,13 @@ export class GitLabEventSource extends GitLabBase {
             });
         }
         const next = response.nextPage
-            ? JSON.stringify({ ...(parsed.since ? { since: parsed.since } : {}), page: response.nextPage })
-            : JSON.stringify({ since: events.at(-1)?.detectedAt ?? parsed.since });
+            ? JSON.stringify({
+                ...(parsed.since ? { since: parsed.since } : {}),
+                page: response.nextPage,
+                ...(highWater ? { highWater } : {}),
+            })
+            : // 페이지를 다 돌았으면 기준선은 지금까지 본 최대값이다 — 이전 기준선보다 앞서지 않는다.
+                JSON.stringify(highWater ? { since: highWater } : {});
         return { events, cursor: next, ...(response.nextPage ? { hasMore: true } : {}) };
     }
 }
@@ -149,6 +175,7 @@ export class GitLabResourceContext extends GitLabBase {
             body: note.body ?? '',
             // 여기는 resolvable 여부를 알려준다 — 아는 것만 적는다.
             ...(note.resolvable ? { unresolved: note.resolved !== true } : {}),
+            ...(note.system ? { system: true } : {}),
         }));
     }
 }

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');

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

@@ -0,0 +1,62 @@
+/** JAM 의 zero-install 진입. **버전을 여기 박지 않는다** — JAM 이 말한 값을 쓴다. */
+export declare const JAM_BOOTSTRAP = "@jam-mcp/bootstrap";
+/**
+ * 정확한 버전으로 고정한 공식 명령.
+ *
+ * JAM 문서가 `@latest` 를 금지하고 정확한 핀을 요구한다. 그 버전을 ASC 가 정하면 두
+ * 제품의 릴리스가 묶이므로, **돌고 있는 JAM 이 스스로 말한 버전**(doctor 의
+ * `axes.packageVersion`)을 그대로 쓴다.
+ */
+export declare function jamBootstrapCommand(version: string, args: readonly string[]): {
+    command: string;
+    args: string[];
+};
+/** `setup plan --json` 에서 우리가 읽는 부분. */
+export type JamSetupPlan = {
+    status?: string;
+    /** 사람이 결정해야 하는 것이 남아 있는가. 남아 있으면 ASC 는 손대지 않는다. */
+    requiresUserAction?: boolean;
+    changes?: unknown[];
+    project?: {
+        key?: string;
+        keySource?: string;
+    };
+    code?: string;
+    error?: string;
+};
+export type JamHealOutcome = 
+/** 고칠 것이 없었다. */
+{
+    kind: 'ALREADY_READY';
+}
+/** ASC 가 JAM 공식 setup 으로 고쳤다. */
+ | {
+    kind: 'HEALED';
+    changes: number;
+}
+/** 사람이 해야 한다 — 자격, 또는 진짜 프로젝트 선택. */
+ | {
+    kind: 'NEEDS_HUMAN';
+    detail: string;
+}
+/** 다시 돌려도 달라지지 않는다. */
+ | {
+    kind: 'FAILED';
+    detail: string;
+};
+export type JamSetupDeps = {
+    cwd: string;
+    /** JAM 이 말한 자기 버전. 없으면 부를 수 없다 — 버전을 지어내지 않는다. */
+    version: string;
+    /** 프로세스 실행 통로. 테스트가 실제 npx 를 부르지 않기 위한 주입점. */
+    exec?: (command: string, args: readonly string[], cwd: string) => Promise<string>;
+};
+/**
+ * 준비되지 않은 JAM 을 공식 경로로 되살린다.
+ *
+ * **계획을 먼저 본다.** 계획이 사람을 요구하면 적용하지 않는다 — 그것이 자격이거나 진짜
+ * 프로젝트 선택이고, 둘 다 ASC 가 대신할 수 없는 것이다 (설계 §9.4).
+ */
+export declare function healJam(deps: JamSetupDeps): Promise<JamHealOutcome>;
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export declare function healLine(outcome: JamHealOutcome): string;

package/dist/adapters/jam/setup.js

@@ -0,0 +1,85 @@
+// JAM 준비 상태를 JAM 의 공식 경로로 되살린다 (설계 §9.2·§9.3).
+//
+// **진단도 수리도 JAM 이 한다.** ASC 가 하는 일은 셋뿐이다:
+//
+//   언제 부를지 정한다      Profile 이 work binding 을 선언했는데 JAM 이 준비되지 않았을 때
+//   무엇을 부를지 고른다     JAM 이 스스로 말한 버전의 공식 bootstrap
+//   어디서 멈출지 판단한다   사람만 할 수 있는 것은 사람에게 넘긴다
+//
+// ASC 는 Jira 토큰을 받지도 저장하지도 않고, 프로젝트 키를 만들어 내지도 않는다.
+// 키는 Profile 에 이미 사람이 적어 둔 것이고, 그 결정을 다시 묻지 않는다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+/** JAM 의 zero-install 진입. **버전을 여기 박지 않는다** — JAM 이 말한 값을 쓴다. */
+export const JAM_BOOTSTRAP = '@jam-mcp/bootstrap';
+/**
+ * 정확한 버전으로 고정한 공식 명령.
+ *
+ * JAM 문서가 `@latest` 를 금지하고 정확한 핀을 요구한다. 그 버전을 ASC 가 정하면 두
+ * 제품의 릴리스가 묶이므로, **돌고 있는 JAM 이 스스로 말한 버전**(doctor 의
+ * `axes.packageVersion`)을 그대로 쓴다.
+ */
+export function jamBootstrapCommand(version, args) {
+    return { command: 'npx', args: ['--yes', `${JAM_BOOTSTRAP}@${version}`, ...args] };
+}
+const defaultExec = async (command, args, cwd) => {
+    try {
+        const { stdout } = await run(command, [...args], { cwd, maxBuffer: 8 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        // JAM 은 준비되지 않았을 때도 JSON 을 내면서 0 이 아닌 코드로 끝난다.
+        const stdout = error.stdout;
+        if (stdout)
+            return stdout;
+        throw error;
+    }
+};
+/**
+ * 준비되지 않은 JAM 을 공식 경로로 되살린다.
+ *
+ * **계획을 먼저 본다.** 계획이 사람을 요구하면 적용하지 않는다 — 그것이 자격이거나 진짜
+ * 프로젝트 선택이고, 둘 다 ASC 가 대신할 수 없는 것이다 (설계 §9.4).
+ */
+export async function healJam(deps) {
+    const exec = deps.exec ?? defaultExec;
+    const read = async (args) => {
+        const { command, args: full } = jamBootstrapCommand(deps.version, args);
+        try {
+            return JSON.parse(await exec(command, full, deps.cwd));
+        }
+        catch (error) {
+            return { error: String(error.message ?? error).slice(0, 300) };
+        }
+    };
+    const plan = await read(['setup', 'plan', '--json']);
+    if (plan.error)
+        return { kind: 'FAILED', detail: `JAM setup plan 을 읽지 못했다 — ${plan.error}` };
+    if (plan.requiresUserAction) {
+        // 사람만 할 수 있는 것이 남았다. 대신 하지 않고, 무엇인지 그대로 전한다.
+        return { kind: 'NEEDS_HUMAN', detail: plan.code ?? plan.status ?? 'JAM setup requires a person' };
+    }
+    if ((plan.changes?.length ?? 0) === 0)
+        return { kind: 'ALREADY_READY' };
+    const applied = await read(['setup', 'apply', '--non-interactive', '--json']);
+    if (applied.error)
+        return { kind: 'FAILED', detail: `JAM setup apply 가 실패했다 — ${applied.error}` };
+    if (applied.requiresUserAction) {
+        return { kind: 'NEEDS_HUMAN', detail: applied.code ?? applied.status ?? 'JAM setup requires a person' };
+    }
+    return { kind: 'HEALED', changes: plan.changes?.length ?? 0 };
+}
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export function healLine(outcome) {
+    switch (outcome.kind) {
+        case 'ALREADY_READY':
+            return 'JAM: already set up for this project';
+        case 'HEALED':
+            return `JAM: repaired through its own setup (${outcome.changes} change${outcome.changes === 1 ? '' : 's'})`;
+        case 'NEEDS_HUMAN':
+            return `JAM: needs you — ${outcome.detail}. ASC does not sign in for you.`;
+        case 'FAILED':
+            return `JAM: ${outcome.detail}`;
+    }
+}

package/dist/adapters/local/canonical.d.ts

@@ -0,0 +1,20 @@
+import type { CanonicalSnapshot } from '../../core/model/entities.ts';
+import type { BaselineQuery, ExternalAction, ExternalActionResult, ScmPort, ThreadSnapshot } from '../../ports/scm.ts';
+export type LocalCanonicalDeps = {
+    cwd: string;
+    /** sourceId → 어느 ref 를 읽는가. Profile 이 준다. */
+    sourceRefs: Readonly<Record<string, {
+        ref: string;
+        remote?: string;
+    }>>;
+    exec?: (args: readonly string[], cwd: string) => Promise<string>;
+};
+export declare class LocalCanonicalReader implements ScmPort {
+    #private;
+    readonly id = "git";
+    constructor(deps: LocalCanonicalDeps);
+    getBaselines(queries: readonly BaselineQuery[]): Promise<CanonicalSnapshot[]>;
+    /** 스레드는 이 통로의 것이 아니다. 모르는 것을 아는 척하지 않는다. */
+    getThread(reference: string): Promise<ThreadSnapshot>;
+    execute(action: ExternalAction): Promise<ExternalActionResult>;
+}

package/dist/adapters/local/canonical.js

@@ -0,0 +1,58 @@
+// 정본 baseline 을 **선언된 대로** 읽는다.
+//
+// Profile 은 정본 갈래마다 provider 를 적는다. `git` 이라고 적힌 갈래는 이 checkout 이
+// 이미 들고 있는 사실이다 — 원격 API 로 갈 이유가 없고, 갈 수 있다는 보장도 없다.
+// 실제로 그 자리에서 한 provider 의 API 로만 읽으려다, 다른 host 를 쓰는 프로젝트에서
+// 세션 발급이 통째로 막혔다. 정본을 못 읽으면 무엇을 딛고 시작하는지 적을 수 없기 때문이다.
+//
+// 여기는 **읽기만** 한다. 쓰기 통로가 아니고, 그 사실을 execute 가 그대로 말한다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+export class LocalCanonicalReader {
+    id = 'git';
+    #cwd;
+    #refs;
+    #exec;
+    constructor(deps) {
+        this.#cwd = deps.cwd;
+        this.#refs = deps.sourceRefs;
+        this.#exec =
+            deps.exec ??
+                (async (args, cwd) => {
+                    const { stdout } = await run('git', [...args], { cwd });
+                    return stdout.trim();
+                });
+    }
+    async getBaselines(queries) {
+        const out = [];
+        for (const query of queries) {
+            const configured = this.#refs[query.sourceId];
+            const ref = query.ref ?? configured?.ref;
+            if (!ref) {
+                out.push({ sourceId: query.sourceId, baseline: 'unknown' });
+                continue;
+            }
+            // 원격 추적 ref 를 먼저 본다. 로컬 브랜치를 정본처럼 읽으면 내 작업이 정본이 된다.
+            const remote = configured?.remote;
+            const candidates = remote ? [`${remote}/${ref}`, ref] : [ref];
+            let baseline = 'unknown';
+            for (const candidate of candidates) {
+                const sha = await this.#exec(['rev-parse', '--verify', `${candidate}^{commit}`], this.#cwd).catch(() => '');
+                if (sha) {
+                    baseline = sha;
+                    break;
+                }
+            }
+            out.push({ sourceId: query.sourceId, baseline });
+        }
+        return out;
+    }
+    /** 스레드는 이 통로의 것이 아니다. 모르는 것을 아는 척하지 않는다. */
+    async getThread(reference) {
+        return { reference, lastEventId: 'unknown', missing: true };
+    }
+    async execute(action) {
+        return { ok: false, error: `this canonical reader performs no external action: ${action.action}` };
+    }
+}