@asc-agent/runtime 0.3.2 → 0.4.0

package/dist/core/runtime/background.js

@@ -0,0 +1,225 @@
+// Background Runtime — 대화가 닫혀 있어도 도는 자리 (C-12 §0·§1.1).
+//
+// Orchestrator는 "언제 무엇을 부를지"를 이미 안다. 없던 것은 그 회차를 **누가 계속
+// 돌리는가**와, 돌고 있는지를 **사람이 어떻게 보는가**였다:
+//
+//   asc runtime start   터미널을 잡고 있어야 했다 — 창을 닫으면 감시가 죽는다
+//   asc runtime tick    한 회차만 돈다. 부를 사람이 없으면 아무 일도 안 일어난다
+//   asc runtime status  어느 빌드를 쓰는지만 답했다 (C-14 §4) — 감시가 사는지는 몰랐다
+//
+// 여기는 그 셋을 잇는 **상태**만 다룬다. 판정도, 감시도, 승인도 하지 않는다
+// (C-12 불변식 ②). scheduler 제품도 모른다 (불변식 ④) — cron이 tick을 부르든, 떨어져
+// 나간 프로세스가 스스로 돌든 같은 lease를 지난다.
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 이 lease가 사는 열쇠. Monitor의 scan-lease와 다른 층이다 — 저쪽은 한 회차, 이쪽은 루프. */
+export const RUNTIME_LEASE_KEY = 'runtime-lease';
+/** 마지막 회차 시각이 사는 열쇠. Orchestrator가 쓰고 status가 읽는다. */
+export const LAST_RUN_KEY = 'last-run';
+/**
+ * lease가 죽은 것으로 보이기까지의 최소 시간.
+ *
+ * **주기보다 길어야 한다.** 10분마다 도는 루프에 5분 만료를 걸면 회차 사이에 자기 lease가
+ * 죽은 것으로 보이고, 두 번째 프로세스가 조용히 끼어든다. 그래서 회수 기준은 주기의
+ * 3배이며, 이 값은 그 아래로 내려가지 않게 막는 바닥이다.
+ */
+export const MIN_STALE_MS = 5 * 60_000;
+/** 주기에서 회수 기준을 정한다. 상수를 Core에 박지 않는다 (C-12 불변식 ③). */
+export const staleAfter = (intervalMs) => Math.max(MIN_STALE_MS, intervalMs * 3);
+/**
+ * 루프 하나만 돌게 하는 lease.
+ *
+ * **이중 기동은 오류가 아니다** (C-12 불변식 ⑥). 늦게 온 쪽은 조용히 물러나고, 이미
+ * 도는 쪽이 계속한다. 비정상 종료로 남은 lease는 시간이 지나면 회수된다 — 한 번 죽었다고
+ * 영영 못 켜지면 그것이 더 나쁜 고장이다.
+ */
+export class RuntimeLease {
+    #scope;
+    #owner;
+    #pid;
+    #staleMs;
+    #now;
+    #startedAt;
+    constructor(deps) {
+        this.#scope = deps.scope;
+        this.#owner = deps.owner;
+        this.#pid = deps.pid ?? process.pid;
+        this.#staleMs = deps.staleMs ?? MIN_STALE_MS;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    /** 지금 누가 잡고 있는가. 읽기만 한다 — status가 이것을 그린다. */
+    async read() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (!raw)
+            return { kind: 'FREE' };
+        let record;
+        try {
+            record = JSON.parse(raw);
+        }
+        catch {
+            // 읽을 수 없는 lease는 죽은 것으로 본다. 다만 무엇이 있었는지는 남긴다.
+            return { kind: 'STALE', record: { owner: '(unreadable)', pid: 0, at: '', startedAt: '' }, silentFor: Infinity };
+        }
+        const silentFor = new Date(this.#now()).getTime() - new Date(record.at).getTime();
+        // 시계가 뒤로 갔거나 기록이 깨졌으면 살아 있는 쪽으로 읽는다 — 남의 lease를 뺏는
+        // 것보다 한 회차 쉬는 편이 싸다.
+        if (Number.isNaN(silentFor))
+            return { kind: 'HELD', record };
+        return silentFor >= this.#staleMs ? { kind: 'STALE', record, silentFor } : { kind: 'HELD', record };
+    }
+    /**
+     * 잡는다. 이미 살아 있는 주인이 있으면 `false` — 조용히 물러나는 것이 계약이다.
+     *
+     * Monitor scan-lease와 같은 모양이다: `setIfAbsent` 로 원자적으로 걸고, 오래된 것만
+     * 지우고 다시 건다. 확인과 쓰기 사이의 틈은 Adapter가 막는다.
+     */
+    async acquire() {
+        const at = this.#now();
+        this.#startedAt = at;
+        const mine = JSON.stringify({ owner: this.#owner, pid: this.#pid, at, startedAt: at });
+        if (await this.#scope.setIfAbsent(RUNTIME_LEASE_KEY, mine))
+            return true;
+        const state = await this.read();
+        if (state.kind === 'HELD')
+            return false;
+        await this.#scope.delete(RUNTIME_LEASE_KEY);
+        return this.#scope.setIfAbsent(RUNTIME_LEASE_KEY, mine);
+    }
+    /**
+     * 살아 있다고 말한다. 회차마다 부른다 — 이것이 없으면 주기가 만료보다 긴 순간
+     * 자기 lease가 죽은 것으로 보인다.
+     *
+     * **남의 lease를 갱신하지 않는다.** 주인이 바뀌어 있으면 `false` 를 돌려주고, 호출자는
+     * 그것을 "내가 밀려났다"로 읽는다.
+     */
+    async renew() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (raw) {
+            try {
+                const held = JSON.parse(raw);
+                if (held.owner !== this.#owner)
+                    return false;
+                this.#startedAt ??= held.startedAt;
+            }
+            catch {
+                // 못 읽는 lease 위에 내 것을 덮어쓴다 — 아래에서 다시 쓴다
+            }
+        }
+        const at = this.#now();
+        this.#startedAt ??= at;
+        await this.#scope.set(RUNTIME_LEASE_KEY, JSON.stringify({ owner: this.#owner, pid: this.#pid, at, startedAt: this.#startedAt }));
+        return true;
+    }
+    /** 내 것일 때만 놓는다. 남이 이미 잡았으면 건드리지 않는다. */
+    async release() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (!raw)
+            return;
+        try {
+            if (JSON.parse(raw).owner !== this.#owner)
+                return;
+        }
+        catch {
+            // 못 읽는 것은 내가 남긴 것으로 보고 치운다
+        }
+        await this.#scope.delete(RUNTIME_LEASE_KEY);
+    }
+}
+/** 상태를 모은다. **읽기만 한다** — 보는 것이 상태를 바꾸면 아무도 못 본다. */
+export async function readBackground(scope, staleMs, now = () => new Date().toISOString()) {
+    const lease = await new RuntimeLease({ scope, owner: '(reader)', staleMs, now }).read();
+    const raw = await scope.get(LAST_RUN_KEY);
+    let lastRun = {};
+    if (raw) {
+        try {
+            lastRun = JSON.parse(raw);
+        }
+        catch {
+            // 깨진 기록은 없는 것으로 본다 — 아래 렌더가 "한 번도 돌지 않았다"로 말한다
+        }
+    }
+    return { lease, lastRun, staleMs };
+}
+const ORDER = ['delta', 'reconcile', 'census', 'digest'];
+/**
+ * 사람이 읽는 줄.
+ *
+ * **"안 돌고 있다"와 "돌았는데 변화가 없다"를 합치지 않는다** (C-12 불변식 ⑫과 같은 태도).
+ * 그래서 lease 상태와 마지막 회차 시각을 각각 말한다 — 둘 중 하나만 보면 오해한다.
+ */
+export function renderBackground(status) {
+    const lines = [];
+    switch (status.lease.kind) {
+        case 'FREE':
+            lines.push('Background runtime: not running — `asc runtime start --detach` keeps it observing');
+            break;
+        case 'HELD':
+            lines.push(`Background runtime: running (pid ${status.lease.record.pid}, since ${status.lease.record.startedAt}, last heartbeat ${status.lease.record.at})`);
+            break;
+        case 'STALE':
+            lines.push(`Background runtime: not running — a lease from pid ${status.lease.record.pid} has been silent for ` +
+                `${Math.round(status.lease.silentFor / 60_000)} min and will be reclaimed on the next start`);
+            break;
+    }
+    const ran = ORDER.filter((kind) => status.lastRun[kind]);
+    if (ran.length === 0) {
+        // 설정만 하고 켜지 않은 상태다. 조용한 것과 구분해서 말한다.
+        lines.push('  no pass has run yet');
+        return lines;
+    }
+    for (const kind of ORDER) {
+        lines.push(`  ${kind}: ${status.lastRun[kind] ?? 'never run'}`);
+    }
+    return lines;
+}
+/**
+ * 파일 하나짜리 ScopedStore (설계 §5.1).
+ *
+ * **서비스 lease 와 workspace lease 는 다른 소유 영역이다.** 저쪽은 "이 workspace 의
+ * 이번 회차를 누가 잡았는가"이고, 이쪽은 "이 기계의 runtime 을 지금 누가 도는가"다.
+ * 둘을 합치면 workspace 가 늘 때마다 기계 수준 직렬화가 무너진다.
+ *
+ * workspace 상태 저장소를 기계 뿌리에 열지 않는 이유: 그러면 ~/.asc 에 workspace 용
+ * 파일들이 생기고, 그것은 그 자리에 없어야 할 것들이다.
+ */
+export function fileScope(path) {
+    const read = async () => {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            // 없거나 깨진 파일은 빈 것으로 본다 — lease 는 시간으로 회수되므로 안전하다
+            return {};
+        }
+    };
+    // tmp+rename. 반쯤 쓰인 lease 를 다른 프로세스가 읽으면 판정이 흔들린다 (C-11 불변식 ⑨).
+    const write = async (data) => {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp-${process.pid}`;
+        await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+        await rename(tmp, path);
+    };
+    return {
+        async get(key) {
+            return (await read())[key] ?? null;
+        },
+        async set(key, value) {
+            await write({ ...(await read()), [key]: value });
+        },
+        async delete(key) {
+            const data = await read();
+            delete data[key];
+            await write(data);
+        },
+        async keys(prefix) {
+            return Object.keys(await read()).filter((key) => (prefix ? key.startsWith(prefix) : true));
+        },
+        async setIfAbsent(key, value) {
+            const data = await read();
+            if (key in data)
+                return false;
+            await write({ ...data, [key]: value });
+            return true;
+        },
+    };
+}

package/dist/core/runtime/front.d.ts

@@ -85,6 +85,54 @@ export type RestoreInput = {
  * 새로 계산하지 않는다. 여기서 파생을 만들면 그 파생이 곧 두 번째 정본이 된다.
  */
 export declare function restoreFront(input: RestoreInput): Promise<FrontState>;
+/**
+ * 새 Front Session이 열렸을 때의 판정 (C-12 §4).
+ *
+ * **Host를 모른다.** Claude Code든 다른 무엇이든 "여기서 세션이 열렸다"는 사실 하나를
+ * 받고, 붙을 수 있는지와 무엇이 걸려 있는지를 답한다. Host adapter는 이 답을 자기
+ * 호스트의 형식으로 옮기기만 한다 — Core에 `if (host === 'claude')` 가 생기면 그 순간
+ * 두 번째 호스트는 Core를 고쳐야 들어온다.
+ *
+ * 세 갈래를 **구분한다**:
+ *
+ *   NOT_ASC       이 경로는 ASC 소관이 아니다. 조용히 지나간다 — 남의 도구를 방해하지
+ *                 않는다 (C-11 불변식 ⑪).
+ *   UNAVAILABLE   붙어야 하는데 못 붙었다. **빈 화면을 주지 않고 왜인지 말한다**
+ *                 (C-12 불변식 ⑰).
+ *   BOUND         붙었다. 지금 무엇이 걸려 있는지가 함께 온다.
+ */
+export type FrontOpening = {
+    kind: 'NOT_ASC';
+} | {
+    kind: 'UNAVAILABLE';
+    detail: string;
+} | {
+    kind: 'BOUND';
+    state: FrontState;
+};
+/**
+ * 세션이 열렸다 — 붙을 수 있는가.
+ *
+ * **읽기만 한다.** 세션을 만들지 않는다: 실제 작업 요청이 없는데 Session Contract를
+ * 만들어 내는 것은 없던 사실을 제조하는 일이다 (AGENTS.md "Do not create a session to
+ * demonstrate that setup worked" 와 같은 선).
+ */
+export declare function openFront(input: {
+    /** 이 경로가 어느 workspace인가. `null` 이면 ASC 소관이 아니다. */
+    workspace: {
+        workspaceId: string;
+        locator: string;
+    } | null;
+    /** 상태를 읽는다. 던지면 UNAVAILABLE 로 접힌다 — 못 읽은 것을 "없음"으로 그리지 않는다. */
+    restore: () => Promise<FrontState>;
+}): Promise<FrontOpening>;
+/**
+ * Host가 사람에게 보여 줄 줄. **Host별 포장은 여기 없다** — 문자열 목록까지가 Core다.
+ *
+ * `NOT_ASC` 는 빈 목록이다. 할 말이 없는 것과 "아무 일도 없다"는 다르고, 전자는
+ * 아무것도 띄우지 않는 것이 맞다.
+ */
+export declare function frontOpeningLines(opening: FrontOpening): string[];
 /**
  * 사람이 읽는 복원 화면.
  *

package/dist/core/runtime/front.js

@@ -63,6 +63,40 @@ export async function restoreFront(input) {
         ...(input.workspace ? { workspace: input.workspace } : {}),
     };
 }
+/**
+ * 세션이 열렸다 — 붙을 수 있는가.
+ *
+ * **읽기만 한다.** 세션을 만들지 않는다: 실제 작업 요청이 없는데 Session Contract를
+ * 만들어 내는 것은 없던 사실을 제조하는 일이다 (AGENTS.md "Do not create a session to
+ * demonstrate that setup worked" 와 같은 선).
+ */
+export async function openFront(input) {
+    if (!input.workspace)
+        return { kind: 'NOT_ASC' };
+    try {
+        return { kind: 'BOUND', state: await input.restore() };
+    }
+    catch (error) {
+        return { kind: 'UNAVAILABLE', detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Host가 사람에게 보여 줄 줄. **Host별 포장은 여기 없다** — 문자열 목록까지가 Core다.
+ *
+ * `NOT_ASC` 는 빈 목록이다. 할 말이 없는 것과 "아무 일도 없다"는 다르고, 전자는
+ * 아무것도 띄우지 않는 것이 맞다.
+ */
+export function frontOpeningLines(opening) {
+    switch (opening.kind) {
+        case 'NOT_ASC':
+            return [];
+        case 'UNAVAILABLE':
+            // 조용히 빈 화면을 주지 않는다 (C-12 불변식 ⑰)
+            return [`ASC is attached here but its state could not be read — ${opening.detail}`];
+        case 'BOUND':
+            return renderFront(opening.state);
+    }
+}
 /**
  * 사람이 읽는 복원 화면.
  *

package/dist/core/runtime/workspaces.d.ts

@@ -0,0 +1,39 @@
+/** 운영 상태 — 별도 state machine 이 아니라 읽기 모델이다. */
+export type WorkspaceHealth = 'ACTIVE' | 'DEGRADED' | 'DORMANT';
+export type WorkspaceView = {
+    workspaceId: string;
+    /** 이 workspace 의 runtime 뿌리. */
+    root: string;
+    /** 지금 살아 있는 checkout 들. 비어 있으면 DORMANT 다. */
+    liveLocators: string[];
+    /** 등록돼 있지만 지금 없는 checkout 들. 지우지 않는다 — 돌아올 수 있다. */
+    missingLocators: string[];
+    health: WorkspaceHealth;
+    aliases: readonly string[];
+};
+export type WorkspaceInput = {
+    workspaceId: string;
+    root: string;
+    aliases: readonly string[];
+    locators: readonly string[];
+};
+/**
+ * 지금 이 기계의 상태를 계산한다. **판정도 삭제도 하지 않는다.**
+ *
+ * `rootExists` 가 거짓이면 runtime 자체가 사라진 것이다 — locator 가 살아 있어도
+ * 관측할 수 없으므로 DEGRADED 로 든다. 사라진 것을 조용히 지우지 않는 이유는 위와 같다.
+ */
+export declare function viewWorkspaces(workspaces: readonly WorkspaceInput[], exists: (path: string) => boolean): WorkspaceView[];
+/**
+ * 이번 회차에 실제로 돌 곳.
+ *
+ * DORMANT 는 **밖을 치지 않는다** (설계 §19). 살아 있는 checkout 이 없으면 그 저장소를
+ * 대신해 무엇을 물어볼 자리도 없고, 없는 자리를 대신해 외부에 질문하면 그것은 관측이
+ * 아니라 잡음이다.
+ */
+export declare function dueWorkspaces(views: readonly WorkspaceView[]): {
+    workspaceId: string;
+    cwd: string;
+}[];
+/** 사람이 읽는 기계 전체 화면. `cd` 없이 지금 무엇이 도는지 보여야 한다 (설계 §13.2). */
+export declare function renderWorkspaces(views: readonly WorkspaceView[]): string[];

package/dist/core/runtime/workspaces.js

@@ -0,0 +1,64 @@
+// 이 기계가 돌보는 workspace 들 (설계 §6·§7).
+//
+// **두 번째 등록부를 만들지 않는다.** `monitorEnabled=true` 같은 플래그를 새로 두면 그것이
+// 곧 두 번째 정본이 되고, 붙어 있는데 감시되지 않는(또는 그 반대의) 상태가 생긴다.
+// 운영 상태는 **이미 있는 사실에서 계산한다**:
+//
+//   workspace 가 index 에 있다        → 이 기계가 아는 workspace 다
+//   살아 있는 locator 가 하나라도 있다 → 관측할 수 있다
+//   하나도 없다                        → DORMANT — 상태는 남기고 밖을 치지 않는다
+//
+// DORMANT 는 삭제 대상이 아니다 (설계 §3.9). checkout 을 잠시 지웠다고 몇 달치 기록을
+// 버리면, 그 삭제를 되돌릴 방법이 없다. 새 locator 가 나타나면 다시 ACTIVE 가 된다.
+/**
+ * 지금 이 기계의 상태를 계산한다. **판정도 삭제도 하지 않는다.**
+ *
+ * `rootExists` 가 거짓이면 runtime 자체가 사라진 것이다 — locator 가 살아 있어도
+ * 관측할 수 없으므로 DEGRADED 로 든다. 사라진 것을 조용히 지우지 않는 이유는 위와 같다.
+ */
+export function viewWorkspaces(workspaces, exists) {
+    return workspaces.map((workspace) => {
+        const liveLocators = workspace.locators.filter((locator) => exists(locator));
+        const missingLocators = workspace.locators.filter((locator) => !exists(locator));
+        const rootExists = exists(workspace.root);
+        const health = liveLocators.length === 0 ? 'DORMANT' : rootExists ? 'ACTIVE' : 'DEGRADED';
+        return {
+            workspaceId: workspace.workspaceId,
+            root: workspace.root,
+            liveLocators,
+            missingLocators,
+            health,
+            aliases: workspace.aliases,
+        };
+    });
+}
+/**
+ * 이번 회차에 실제로 돌 곳.
+ *
+ * DORMANT 는 **밖을 치지 않는다** (설계 §19). 살아 있는 checkout 이 없으면 그 저장소를
+ * 대신해 무엇을 물어볼 자리도 없고, 없는 자리를 대신해 외부에 질문하면 그것은 관측이
+ * 아니라 잡음이다.
+ */
+export function dueWorkspaces(views) {
+    return views
+        .filter((view) => view.health === 'ACTIVE')
+        // 여러 checkout 이 있으면 아무 곳에서나 한 번이면 된다 — 관측 대상은 workspace 이지
+        // checkout 이 아니다. 첫 번째를 쓰는 것은 안정적인 선택이다(목록 순서가 index 순서다).
+        .map((view) => ({ workspaceId: view.workspaceId, cwd: view.liveLocators[0] }));
+}
+/** 사람이 읽는 기계 전체 화면. `cd` 없이 지금 무엇이 도는지 보여야 한다 (설계 §13.2). */
+export function renderWorkspaces(views) {
+    if (views.length === 0)
+        return ['No workspaces are registered on this machine.'];
+    const lines = [];
+    for (const view of views) {
+        const alias = view.aliases[0] ?? '(no alias)';
+        lines.push(`${view.workspaceId}  ${view.health}  ${alias}`);
+        for (const locator of view.liveLocators)
+            lines.push(`  ${locator}`);
+        // 없어진 checkout 도 든다 — 지우지 않았다는 사실이 보여야 사람이 놀라지 않는다
+        for (const locator of view.missingLocators)
+            lines.push(`  ${locator} (gone)`);
+    }
+    return lines;
+}

package/dist/core/workspace/resolve.d.ts

@@ -11,6 +11,21 @@ export type Resolution = {
     workspaceId: string;
     locator: string;
 }
+/**
+ * 등록된 적은 없지만 **같은 Git repository의 다른 checkout이 등록돼 있다.**
+ * 같은 논리 workspace의 다른 execution instance다 (C-11 §1.3) — 쪼개지도 합치지도 않는다.
+ */
+ | {
+    kind: 'LINKED_WORKTREE';
+    root: string;
+    workspaceId: string;
+    /** 지금 이 checkout의 최상위. 호출자가 이 값을 index에 등록해 다음 번을 빠르게 만든다. */
+    locator: string;
+    /** 근거가 된, 이미 등록돼 있던 형제 checkout. */
+    via: string;
+    /** main checkout인가 linked worktree인가. */
+    kindOfLocator: 'checkout' | 'worktree';
+}
 /** 저장소 안의 `.asc/` — 팀이 채택했거나 아직 이전하지 않은 개인 legacy다. */
  | {
     kind: 'PROJECT_LOCAL';
@@ -28,7 +43,28 @@ export type ResolveInput = {
     /** 여기를 넘어서는 위로 올라가지 않는다. 보통 사용자 홈. */
     stopAt?: string;
     exists?: (path: string) => Promise<boolean>;
+    /**
+     * 이 경로가 속한 Git repository의 checkout 전부(main + linked). 없으면 이 갈래를 건너뛴다.
+     *
+     * **주입이 기본값이다** — guard hook처럼 매 호출마다 도는 소비자는 이것을 넘기지 않고,
+     * 그러면 예전과 똑같이 index만 본다.
+     */
+    worktrees?: WorktreeProbe;
 };
+/**
+ * 같은 Git repository에 속한 checkout 경로들. 첫 번째가 main worktree다.
+ * git이 없거나 저장소가 아니면 `null` — "없다"와 "못 봤다"를 구분한다.
+ */
+export type WorktreeProbe = (cwd: string) => Promise<readonly string[] | null>;
 export declare function resolveWorkspace(input: ResolveInput): Promise<Resolution>;
+/**
+ * 기본 통로 — `git worktree list --porcelain`. 첫 `worktree` 항목이 main checkout이다.
+ *
+ * git이 없거나 저장소가 아니면 `null`을 돌려준다. 빈 배열이 아니다 — "checkout이 하나도
+ * 없다"와 "물어보지 못했다"는 다른 사실이고, 후자를 전자로 적으면 조용한 오판이 된다.
+ */
+export declare const gitWorktrees: WorktreeProbe;
+/** porcelain 출력에서 checkout 경로만. 순서를 보존한다 — 첫 줄이 main worktree다. */
+export declare function parseWorktreeList(stdout: string): string[];
 /** 사람이 읽는 한 줄. 왜 그 뿌리인지가 함께 와야 사람이 틀린 결합을 알아챈다. */
 export declare function resolutionLine(resolution: Resolution): string;

package/dist/core/workspace/resolve.js

@@ -9,8 +9,12 @@
 //
 //   1. explicit root      사람이 말한 것이 이긴다
 //   2. workspace index    이 기계에 등록된 locator (경로가 바뀌어도 따라온다)
-//   3. project-adopted    저장소 안의 `.asc/` — 팀이 채택한 경우 (legacy 개인 사용 포함)
-//   4. UNRESOLVED         모르면 모른다고 한다
+//   3. linked worktree    같은 Git repository의 다른 checkout이 등록돼 있다 (C-11 §1.3)
+//   4. project-adopted    저장소 안의 `.asc/` — 팀이 채택한 경우 (legacy 개인 사용 포함)
+//   5. UNRESOLVED         모르면 모른다고 한다
+//
+// **3번은 index가 빗나갔을 때만 돈다.** 등록된 locator로 풀리는 정상 경로는 예전 그대로
+// 파일 접근 하나이며, Git을 부르지 않는다 — guard hook이 매 Bash 호출마다 지나는 길이다.
 //
 // **3번의 탐색에는 경계가 있다.** 예전에는 파일시스템 루트까지 올라갔는데, 사용자 홈에
 // `~/.asc` 가 생기는 순간 홈 아래 아무 저장소나 그 뿌리로 오인 매칭된다. 그래서 홈을
@@ -47,11 +51,112 @@ export async function resolveWorkspace(input) {
                 };
         }
     }
+    // index가 빗나갔다. 여기서 처음으로 Git에게 **구조**를 묻는다 — remote가 같다는 이유로
+    // 이어붙이지 않는다 (C-11 불변식 ③). 같은 linked repository라는 것은 로컬에서 증명된다.
+    if (input.index && input.worktrees) {
+        const linked = await resolveLinkedWorktree(input.cwd, input.index, input.worktrees, exists);
+        if (linked)
+            return linked;
+    }
     const local = await findProjectLocal(input.cwd, input.stopAt, exists);
     if (local)
         return { kind: 'PROJECT_LOCAL', root: join(local, ASC_DIR), projectRoot: local };
     return { kind: 'UNRESOLVED', detail: '이 경로에 붙은 ASC workspace가 없다' };
 }
+/**
+ * 이 checkout이 **이미 등록된 checkout과 같은 Git repository**인가.
+ *
+ * `git worktree list` 는 그 저장소의 checkout만 든다. 그래서 remote가 같은 **독립 clone**은
+ * 서로의 경로를 담지 않고, 여기서 절대 이어붙지 않는다 — 그것이 이 판정이 alias 대조가
+ * 아니라 worktree 목록을 쓰는 이유다 (C-11 불변식 ③: alias 일치는 recover candidate일 뿐).
+ *
+ * 후보 workspace가 둘 이상이면 **고르지 않는다.** 고르면 사람이 그 선택을 보지 못한다.
+ */
+async function resolveLinkedWorktree(cwd, index, probe, exists) {
+    const paths = await probe(cwd);
+    if (!paths || paths.length === 0)
+        return null;
+    const normalized = paths.map(normalizeLocator);
+    const here = currentWorktree(normalized, normalizeLocator(cwd));
+    if (!here)
+        return null;
+    const hits = new Map();
+    for (const path of normalized) {
+        if (path === here)
+            continue;
+        const found = lookupLocator(index, path);
+        if (found)
+            hits.set(found.workspaceId, { root: found.root, via: found.locator });
+    }
+    if (hits.size === 0)
+        return null;
+    if (hits.size > 1) {
+        return {
+            kind: 'UNRESOLVED',
+            detail: `이 저장소의 다른 checkout들이 서로 다른 workspace에 등록돼 있다 (${[...hits.keys()].join(', ')}) — 고르지 않는다`,
+        };
+    }
+    const [[workspaceId, hit]] = [...hits.entries()];
+    // 등록은 돼 있는데 뿌리가 없으면 넘어가지 않는다 — REGISTERED와 같은 태도다.
+    if (!(await exists(hit.root))) {
+        return {
+            kind: 'UNRESOLVED',
+            detail: `${workspaceId} 가 등록돼 있으나 runtime(${hit.root})이 없다 — 옮겼거나 지워졌다`,
+        };
+    }
+    return {
+        kind: 'LINKED_WORKTREE',
+        root: hit.root,
+        workspaceId,
+        locator: here,
+        via: hit.via,
+        // 목록의 첫 항목이 main worktree다 (git worktree list 의 계약).
+        kindOfLocator: here === normalized[0] ? 'checkout' : 'worktree',
+    };
+}
+/**
+ * 목록 중 지금 서 있는 checkout. cwd는 그 아래 하위 디렉터리일 수 있으므로 **가장 긴
+ * 접두어**를 고른다. 경계는 구분자에서만 인정한다 — `/a/repo` 가 `/a/repo-2` 를 삼키면 안 된다.
+ */
+function currentWorktree(paths, cwd) {
+    let best = null;
+    for (const path of paths) {
+        if (cwd !== path && !cwd.startsWith(`${path}/`))
+            continue;
+        if (best === null || path.length > best.length)
+            best = path;
+    }
+    return best;
+}
+/**
+ * 기본 통로 — `git worktree list --porcelain`. 첫 `worktree` 항목이 main checkout이다.
+ *
+ * git이 없거나 저장소가 아니면 `null`을 돌려준다. 빈 배열이 아니다 — "checkout이 하나도
+ * 없다"와 "물어보지 못했다"는 다른 사실이고, 후자를 전자로 적으면 조용한 오판이 된다.
+ */
+export const gitWorktrees = async (cwd) => {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    try {
+        const { stdout } = await promisify(execFile)('git', ['worktree', 'list', '--porcelain'], {
+            cwd,
+            // 목록은 짧다. 오래 걸리면 그것 자체가 "물어보지 못했다"이다 — 명령을 세우지 않는다.
+            timeout: 5_000,
+        });
+        return parseWorktreeList(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+/** porcelain 출력에서 checkout 경로만. 순서를 보존한다 — 첫 줄이 main worktree다. */
+export function parseWorktreeList(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('worktree '))
+        .map((line) => line.slice('worktree '.length).trim())
+        .filter(Boolean);
+}
 /**
  * 저장소 안의 `.asc/` 를 위로 올라가며 찾되 **경계를 지킨다**.
  *
@@ -69,7 +174,7 @@ async function findProjectLocal(start, stopAt, exists) {
         const candidate = join(dir, ASC_DIR);
         // 정지선이 홈이어도 **다른 홈**의 `.asc` 는 걸러지지 않는다. Windows는 temp
         // 디렉터리가 사용자 프로필 아래라, temp의 프로젝트에서 위로 걷다 실사용자
-        // `~/.asc` 를 프로젝트 상태로 오인했다 (SSAFESTA 실측 — setup status가
+        // `~/.asc` 를 프로젝트 상태로 오인했다 (실 프로젝트 실측 — setup status가
         // UNATTACHED 대신 BROKEN을 답한 원인). user runtime은 내용으로 알아본다:
         // workspaces/·profiles/·runtime.json 은 홈에만 생긴다.
         if ((await exists(candidate)) && !(await looksLikeUserRuntime(candidate, exists)))
@@ -95,6 +200,8 @@ export function resolutionLine(resolution) {
             return `runtime: ${resolution.root} (given with --root)`;
         case 'REGISTERED':
             return `runtime: ${resolution.root} (workspace ${resolution.workspaceId} · ${resolution.locator})`;
+        case 'LINKED_WORKTREE':
+            return `runtime: ${resolution.root} (workspace ${resolution.workspaceId} · same git repository as ${resolution.via})`;
         case 'PROJECT_LOCAL':
             return `runtime: ${resolution.root} (.asc inside the repository — team-adopted, or personal state not yet migrated)`;
         case 'UNRESOLVED':

package/dist/ports/adapter.d.ts

@@ -5,6 +5,18 @@ export type DiscoveryContext = {
     projectRoot: string;
     /** 환경변수. 자격 **존재 여부** 판단에만 쓰고 값을 실어 나르지 않는다. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Profile 이 이 adapter 에 대해 선언한 자원들 (C-09 §3.1).
+     *
+     * **추측의 반대다.** adapter 가 지역 흔적에서 아무것도 못 찾아도, 사람이 Profile 에
+     * 적어 둔 것은 이미 내려진 결정이다 — 그것을 못 본 척하면 "선언은 있는데 아무 일도
+     * 일어나지 않는" 상태가 된다. adapter 는 이 값을 후보로 올릴 수 있고, 실제로 되는지는
+     * 여전히 probe 가 정한다.
+     */
+    declared?: readonly {
+        adapterId: string;
+        resource: string;
+    }[];
 };
 export type ProbeResult = {
     state: ProbeState;