@asc-agent/runtime 0.3.1 → 0.4.0

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

@@ -0,0 +1,104 @@
+import type { ScopedStore } from '../../ports/state-store.ts';
+import type { TickKind } from './orchestrator.ts';
+/** 이 lease가 사는 열쇠. Monitor의 scan-lease와 다른 층이다 — 저쪽은 한 회차, 이쪽은 루프. */
+export declare const RUNTIME_LEASE_KEY = "runtime-lease";
+/** 마지막 회차 시각이 사는 열쇠. Orchestrator가 쓰고 status가 읽는다. */
+export declare const LAST_RUN_KEY = "last-run";
+/**
+ * lease가 죽은 것으로 보이기까지의 최소 시간.
+ *
+ * **주기보다 길어야 한다.** 10분마다 도는 루프에 5분 만료를 걸면 회차 사이에 자기 lease가
+ * 죽은 것으로 보이고, 두 번째 프로세스가 조용히 끼어든다. 그래서 회수 기준은 주기의
+ * 3배이며, 이 값은 그 아래로 내려가지 않게 막는 바닥이다.
+ */
+export declare const MIN_STALE_MS: number;
+/** 주기에서 회수 기준을 정한다. 상수를 Core에 박지 않는다 (C-12 불변식 ③). */
+export declare const staleAfter: (intervalMs: number) => number;
+export type LeaseRecord = {
+    /** 누가 잡고 있는가. 사람이 읽고 죽일 수 있어야 한다. */
+    owner: string;
+    pid: number;
+    /** 마지막으로 살아 있다고 말한 시각. 회차마다 갱신된다. */
+    at: string;
+    /** 언제부터 돌고 있는가. `at`과 달리 갱신되지 않는다. */
+    startedAt: string;
+};
+export type LeaseState = 
+/** 아무도 안 잡고 있다. */
+{
+    kind: 'FREE';
+}
+/** 살아 있는 주인이 있다. */
+ | {
+    kind: 'HELD';
+    record: LeaseRecord;
+}
+/** 기록은 있는데 오래됐다 — 비정상 종료로 남은 것으로 본다. */
+ | {
+    kind: 'STALE';
+    record: LeaseRecord;
+    silentFor: number;
+};
+/**
+ * 루프 하나만 돌게 하는 lease.
+ *
+ * **이중 기동은 오류가 아니다** (C-12 불변식 ⑥). 늦게 온 쪽은 조용히 물러나고, 이미
+ * 도는 쪽이 계속한다. 비정상 종료로 남은 lease는 시간이 지나면 회수된다 — 한 번 죽었다고
+ * 영영 못 켜지면 그것이 더 나쁜 고장이다.
+ */
+export declare class RuntimeLease {
+    #private;
+    constructor(deps: {
+        scope: ScopedStore;
+        owner: string;
+        pid?: number;
+        staleMs?: number;
+        now?: () => string;
+    });
+    /** 지금 누가 잡고 있는가. 읽기만 한다 — status가 이것을 그린다. */
+    read(): Promise<LeaseState>;
+    /**
+     * 잡는다. 이미 살아 있는 주인이 있으면 `false` — 조용히 물러나는 것이 계약이다.
+     *
+     * Monitor scan-lease와 같은 모양이다: `setIfAbsent` 로 원자적으로 걸고, 오래된 것만
+     * 지우고 다시 건다. 확인과 쓰기 사이의 틈은 Adapter가 막는다.
+     */
+    acquire(): Promise<boolean>;
+    /**
+     * 살아 있다고 말한다. 회차마다 부른다 — 이것이 없으면 주기가 만료보다 긴 순간
+     * 자기 lease가 죽은 것으로 보인다.
+     *
+     * **남의 lease를 갱신하지 않는다.** 주인이 바뀌어 있으면 `false` 를 돌려주고, 호출자는
+     * 그것을 "내가 밀려났다"로 읽는다.
+     */
+    renew(): Promise<boolean>;
+    /** 내 것일 때만 놓는다. 남이 이미 잡았으면 건드리지 않는다. */
+    release(): Promise<void>;
+}
+export type BackgroundStatus = {
+    lease: LeaseState;
+    /** 갈래별 마지막 실행 시각. 없는 갈래는 한 번도 돌지 않았다. */
+    lastRun: Partial<Record<TickKind, string>>;
+    /** 회수 기준. 사람이 "얼마나 조용하면 죽은 것인가"를 알아야 판단할 수 있다. */
+    staleMs: number;
+};
+/** 상태를 모은다. **읽기만 한다** — 보는 것이 상태를 바꾸면 아무도 못 본다. */
+export declare function readBackground(scope: ScopedStore, staleMs: number, now?: () => string): Promise<BackgroundStatus>;
+/**
+ * 사람이 읽는 줄.
+ *
+ * **"안 돌고 있다"와 "돌았는데 변화가 없다"를 합치지 않는다** (C-12 불변식 ⑫과 같은 태도).
+ * 그래서 lease 상태와 마지막 회차 시각을 각각 말한다 — 둘 중 하나만 보면 오해한다.
+ */
+export declare function renderBackground(status: BackgroundStatus): string[];
+/**
+ * 파일 하나짜리 ScopedStore (설계 §5.1).
+ *
+ * **서비스 lease 와 workspace lease 는 다른 소유 영역이다.** 저쪽은 "이 workspace 의
+ * 이번 회차를 누가 잡았는가"이고, 이쪽은 "이 기계의 runtime 을 지금 누가 도는가"다.
+ * 둘을 합치면 workspace 가 늘 때마다 기계 수준 직렬화가 무너진다.
+ *
+ * workspace 상태 저장소를 기계 뿌리에 열지 않는 이유: 그러면 ~/.asc 에 workspace 용
+ * 파일들이 생기고, 그것은 그 자리에 없어야 할 것들이다.
+ */
+export declare function fileScope(path: string): ScopedStore;

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/session.js

@@ -70,7 +70,12 @@ export class SessionRuntime {
             return {
                 ok: false,
                 reason: 'NOT_OWNER',
-                detail: `${id} 에는 Runtime이 붙어 있다 — owner(${binding.physicalSessionId})만 기록할 수 있다`,
+                // owner가 누구인지만 말하면 owner 본인도 다음 명령을 모른다 — pause/done은
+                // `--physical <owner>` 로 자격을 대고, 아니면 소유권을 먼저 놓는다 (실측 ASC-6).
+                // Core는 host 이름을 모른다(B-17) — `<host>` 자리는 Surface의 어휘다.
+                detail: `${id} 에는 Runtime이 붙어 있다 — owner(${binding.physicalSessionId})만 기록할 수 있다. ` +
+                    `owner라면 --physical ${binding.physicalSessionId} 을 붙여 다시 실행하고, ` +
+                    `그 세션이 끝났다면 asc host <host> release ${id} --physical ${binding.physicalSessionId} 로 소유권을 놓아라`,
             };
         }
         if (binding.physicalSessionId !== physicalSessionId) {

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;