@asc-agent/runtime 0.3.1 → 0.4.0

package/dist/composition/registry.js

@@ -28,21 +28,29 @@ export async function composeBindings(input) {
     const adapters = input.adapters ?? defaultAdapters();
     const bindings = [];
     const runtimes = [];
+    // Profile 이 선언한 것을 발견 단계에 알려 준다. adapter 가 지역 흔적을 못 찾아도
+    // 사람이 적어 둔 결정은 후보가 될 수 있다 — 되는지는 여전히 probe 가 정한다 (C-09 §3.1).
+    const context = {
+        ...input.context,
+        ...(input.roles?.length
+            ? { declared: input.roles.map((role) => ({ adapterId: role.adapterId, resource: role.resource })) }
+            : {}),
+    };
     for (const adapter of adapters) {
         // 도구가 쓸 수 있는가와 이 프로젝트가 그 도구에 붙어 있는가는 다른 사실이다.
         // 합치면 사람이 "설치할 일인지 붙일 일인지"를 알 수 없다.
         if (adapter.runtime) {
             const status = await adapter
-                .runtime(input.context)
+                .runtime(context)
                 .catch((error) => ({ state: 'UNAVAILABLE', detail: String(error) }));
             runtimes.push({ adapterId: adapter.describe().id, ...status });
         }
-        const candidates = await adapter.discover(input.context).catch(() => []);
+        const candidates = await adapter.discover(context).catch(() => []);
         for (const candidate of candidates) {
             // probe가 터지는 것과 "안 된다"는 다르다. 예외를 UNAVAILABLE로 옮겨 적되
             // 이유를 남긴다 — 조용히 후보에서 빼면 왜 안 보이는지 알 수 없다.
             const result = await adapter
-                .probe(candidate, input.context)
+                .probe(candidate, context)
                 .catch((error) => ({ state: 'UNAVAILABLE', detail: String(error) }));
             const role = input.roles?.find((r) => r.adapterId === candidate.adapterId && r.resource === candidate.resource)?.role;
             bindings.push({

package/dist/composition/runtime.d.ts

@@ -62,4 +62,37 @@ export declare function rolesFor(plan: BindingPlan, declared: readonly {
     adapter: string;
     resource: string;
 }[]): Partial<Record<Capability, string>>;
+/**
+ * 한 binding 이 여는 관측 통로 하나.
+ *
+ * **Monitor Core 는 이것을 여러 개 받는 것이 아니라, 하나씩 여러 번 받는다** — 채널마다
+ * 자기 cursor·coverage·observation ledger 를 갖는 별개의 Run 이다. 그래서 Core 에
+ * provider 분기도, multi-source 개념도 생기지 않는다 (설계 §8.1).
+ */
+export type ObservationChannel = {
+    /** Profile 이 선언한 역할. 선언이 없으면 발견된 자리라는 뜻으로 비어 있다. */
+    role?: string;
+    adapterId: string;
+    resource: string;
+    /** DEGRADED 도 채널이다 — 일부만 되는 것과 안 되는 것은 다르다. */
+    state: ResolvedBinding['state'];
+    detail?: string;
+    eventSource: EventSource;
+    inventory?: InventoryPort;
+    resourceContext?: ResourceContextPort;
+    changeContext?: ChangeContextPort;
+};
+export type ObservationChannels = {
+    channels: ObservationChannel[];
+    /** 무엇을 왜 못 열었는지. 조용히 빠지면 사람이 이유를 알 수 없다. */
+    unavailable: string[];
+};
+/**
+ * 선언된 binding 마다 관측 통로를 하나씩 연다.
+ *
+ * **선언이 있으면 선언만 본다.** 과거 mirror 로 남은 remote 가 발견됐다는 이유로 채널이
+ * 하나 더 생기면, 사람이 고르지 않은 곳을 감시하게 된다 — 발견은 후보이지 결합이 아니다
+ * (C-11 §7). 선언이 하나도 없으면 발견된 것을 쓰되, 그때는 갈리면 갈린다고 말한다.
+ */
+export declare function buildObservationChannels(input: BuildInput): Promise<ObservationChannels>;
 export declare function buildRuntimePorts(input: BuildInput): Promise<RuntimePorts>;

package/dist/composition/runtime.js

@@ -140,6 +140,80 @@ export function rolesFor(plan, declared) {
     }
     return roles;
 }
+/**
+ * 관측 capability — 이 셋은 **하나를 고르는 문제가 아니다** (설계 §8).
+ *
+ * 코드가 GitLab 에 있고 작업 항목이 Jira 에 있는 프로젝트에서 둘 다 봐야 한다는 것은
+ * 요구이지 모호함이 아니다. 그런데 지금까지는 같은 capability 를 둘이 제공한다는
+ * 이유만으로 AMBIGUOUS 가 되어 감시가 통째로 서지 않았다.
+ *
+ * 그래서 capability 를 두 부류로 가른다:
+ *
+ *   singular    canonical.read 처럼 **한 곳이어야** 의미가 서는 것 → 역할로 하나를 고른다
+ *   observation observe.delta · inventory.enumerate · context.resource → binding 마다 하나씩
+ */
+const OBSERVATION_CAPABILITIES = [
+    'observe.delta',
+    'inventory.enumerate',
+    'context.resource',
+];
+/**
+ * 선언된 binding 마다 관측 통로를 하나씩 연다.
+ *
+ * **선언이 있으면 선언만 본다.** 과거 mirror 로 남은 remote 가 발견됐다는 이유로 채널이
+ * 하나 더 생기면, 사람이 고르지 않은 곳을 감시하게 된다 — 발견은 후보이지 결합이 아니다
+ * (C-11 §7). 선언이 하나도 없으면 발견된 것을 쓰되, 그때는 갈리면 갈린다고 말한다.
+ */
+export async function buildObservationChannels(input) {
+    const usable = input.plan.bindings.filter((binding) => (binding.state === 'AVAILABLE' || binding.state === 'DEGRADED') &&
+        OBSERVATION_CAPABILITIES.some((capability) => binding.provides.includes(capability)));
+    const declared = usable.filter((binding) => binding.role !== undefined);
+    const chosen = declared.length > 0 ? declared : usable;
+    const channels = [];
+    const unavailable = [];
+    if (chosen.length === 0) {
+        const blocked = input.plan.bindings.filter((binding) => OBSERVATION_CAPABILITIES.some((capability) => binding.provides.includes(capability)));
+        unavailable.push(blocked.length > 0
+            ? `관측 통로를 제공하는 binding 이 있으나 지금 쓸 수 없다 (${blocked
+                .map((binding) => `${binding.adapterId}: ${binding.state}`)
+                .join(', ')})`
+            : '관측 통로를 제공하는 binding 이 없다');
+        return { channels, unavailable };
+    }
+    const findToken = input.findToken ??
+        (async (adapterId) => adapterId === 'gitlab' ? await discoverGitLabAccess() : await discoverToken());
+    for (const binding of chosen) {
+        const where = `${binding.adapterId}:${binding.resource}`;
+        const factory = FACTORIES[binding.adapterId];
+        if (!factory) {
+            unavailable.push(`${where}: 이 빌드에 조립 경로가 없다`);
+            continue;
+        }
+        const token = TOKENLESS.has(binding.adapterId) ? '' : await findToken(binding.adapterId);
+        if (token === null) {
+            // 자격이 없는 것은 "변화 없음"이 아니다 — 그 채널만 빠지고 이유가 남는다
+            unavailable.push(`${where}: 자격이 없어 관측 통로를 만들지 않았다`);
+            continue;
+        }
+        const made = factory(binding, input, token);
+        if (!made.eventSource) {
+            unavailable.push(`${where}: ${binding.adapterId} 가 관측 통로를 만들지 않았다`);
+            continue;
+        }
+        channels.push({
+            ...(binding.role ? { role: binding.role } : {}),
+            adapterId: binding.adapterId,
+            resource: binding.resource,
+            state: binding.state,
+            ...(binding.detail ? { detail: binding.detail } : {}),
+            eventSource: made.eventSource,
+            ...(made.inventory ? { inventory: made.inventory } : {}),
+            ...(made.resourceContext ? { resourceContext: made.resourceContext } : {}),
+            ...(made.changeContext ? { changeContext: made.changeContext } : {}),
+        });
+    }
+    return { channels, unavailable };
+}
 export async function buildRuntimePorts(input) {
     const ports = { unavailable: [] };
     // 자격은 adapter마다 다른 곳에 있다. Core는 이 사실을 모르고, 여기서만 안다.

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

@@ -14,6 +14,14 @@ export type SetupState = {
     git: boolean;
     /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */
     ascRoot?: string;
+    /**
+     * runtime 디렉터리는 있는데 profile.lock을 읽지 못하는 상태 — 붙이다 만 것이다.
+     *
+     * 이것을 "붙어 있음"으로 읽으면 plan은 `applied`를 답하면서 실패할 `asc proceed`를
+     * 다음 행동으로 준다 (Windows 실전 실측 ASC-2: 파일 잠금이 빈 skeleton만 남긴
+     * 경우). 붙이다 만 상태는 붙일 것이 남은 상태다 — repair가 plan에 드러나야 한다.
+     */
+    attachmentBroken?: boolean;
     /** 붙어 있다면 무엇으로 붙었는가. */
     attachedProfile?: string;
     /** 사람이 `--profile` 로 지정한 것. */
@@ -34,6 +42,36 @@ export type SetupState = {
      * 그때는 설치된 `asc` 를 전제하지 않는다.
      */
     stableRuntime?: StableInstallState;
+    /**
+     * 이 기계의 지속 등록 상태 (설계 §6, Gate 7).
+     *
+     * **별도 onboarding 을 만들지 않는다.** 사용자가 `runtime enable` 을 따로 치게 하면
+     * 그것이 곧 "켜는 행위"가 되고, 이 제품이 없애려던 바로 그 단계다. 같은 plan 이
+     * runtime·host·workspace 와 함께 판단한다.
+     */
+    persistentRuntime?: {
+        action: 'none' | 'install' | 'unsupported';
+        adapter: string;
+        detail?: string;
+    };
+    /**
+     * Profile 이 선언한 작업 항목 결합의 준비 상태 (설계 §9.3).
+     *
+     * **선언은 이미 내려진 결정이다.** 그런데 그 도구가 준비되지 않았다는 이유로 setup 이
+     * 사람에게 "그 도구를 설정할까요?"라고 되물으면, 사람은 자기가 이미 적어 둔 것을 다시
+     * 답하게 된다. 고칠 수 있는 것은 고치고, 사람만 할 수 있는 것에서만 멈춘다.
+     */
+    workBinding?: {
+        adapter: string;
+        resource: string;
+        /** 지금 쓸 수 있는가. 쓸 수 있으면 아래 값들은 보지 않는다. */
+        ready: boolean;
+        /** 고칠 수 있는가, 사람이 해야 하는가, 다시 돌려도 소용없는가. */
+        remedy?: 'SELF_HEAL' | 'HUMAN' | 'HARD';
+        detail?: string;
+        /** 그 도구가 말한 자기 버전. 없으면 부를 수 없다 — 버전을 지어내지 않는다. */
+        version?: string;
+    };
 };
 export type SetupChange = 
 /**
@@ -59,6 +97,27 @@ export type SetupChange =
     target: 'host-install';
     host: string;
     from: string;
+}
+/**
+ * Profile 이 선언한 작업 도구를 **그 도구의 공식 setup 으로** 되살린다 (설계 §9.3).
+ *
+ * ASC 가 그 도구의 설정을 손으로 조립하지 않는다 — 부르기만 한다.
+ */
+ | {
+    target: 'work-binding-setup';
+    adapter: string;
+    resource: string;
+    version: string;
+}
+/**
+ * 이 기계에 ASC runtime 을 등록한다 (설계 §4).
+ *
+ * **workspace 마다가 아니라 기계당 하나다.** 그래서 이 변경은 프로젝트와 무관하고,
+ * 붙는 것과 같은 계획에 함께 실린다.
+ */
+ | {
+    target: 'persistent-runtime';
+    adapter: string;
 };
 export type SetupStatus = 'already_configured' | 'ready_to_apply' | 'user_action_required';
 export type SetupCode = 
@@ -67,7 +126,12 @@ export type SetupCode =
 /** 저장소에 두는 것은 팀의 결정이다 (C-11 불변식 ⑤). */
  | 'ASC_PROJECT_SCOPE_REQUIRES_CONSENT'
 /** 설치물을 사람이 고쳤다 — 덮는 것은 사람이 정한다 (L-5). */
- | 'ASC_HOST_INSTALL_MODIFIED';
+ | 'ASC_HOST_INSTALL_MODIFIED'
+/**
+ * 작업 도구가 사람을 기다린다 — 자격 입력처럼 ASC 가 대신할 수 없는 것 (설계 §9.4).
+ * ASC 는 토큰을 받지도 저장하지도 않는다.
+ */
+ | 'ASC_WORK_BINDING_NEEDS_USER';
 /**
  * 다음에 할 일 하나. **두 형태를 함께 든다** (C-14 §3.4, 불변식 ⑯).
  *
@@ -118,6 +182,14 @@ export type SetupEffects = {
     installHost(change: Extract<SetupChange, {
         target: 'host-install';
     }>): Promise<void>;
+    /** 작업 도구의 공식 setup 을 부른다. ASC 가 그 설정을 조립하지 않는다. */
+    setupWorkBinding?(change: Extract<SetupChange, {
+        target: 'work-binding-setup';
+    }>): Promise<void>;
+    /** 이 기계에 runtime 을 등록한다. OS 별 형식은 adapter 뒤에 있다. */
+    registerPersistentRuntime?(change: Extract<SetupChange, {
+        target: 'persistent-runtime';
+    }>): Promise<void>;
 };
 export type ApplyResult = {
     applied: SetupChange[];

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

@@ -17,7 +17,9 @@ export function computeSetupPlan(state) {
     const evidence = [
         `project=${state.projectRoot}`,
         state.git ? 'git=yes' : 'git=no',
-        state.ascRoot ? `attached=${state.ascRoot}` : 'attached=no',
+        state.ascRoot
+            ? `attached=${state.ascRoot}${state.attachmentBroken ? ' (BROKEN — profile.lock unreadable)' : ''}`
+            : 'attached=no',
         `scope=${state.scope}`,
     ];
     // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
@@ -76,7 +78,40 @@ export function computeSetupPlan(state) {
             changes.push({ target: 'host-install', host: host.id, from: host.status });
         }
     }
-    if (state.ascRoot) {
+    // 이 기계의 지속 등록. 프로젝트와 무관하므로 profile 선택을 기다리지 않는다 —
+    // stable runtime 설치와 같은 자리다.
+    if (state.persistentRuntime) {
+        const persistent = state.persistentRuntime;
+        evidence.push(`persistent=${persistent.action} (${persistent.adapter})`);
+        // 쓸 수 없는 OS 에서는 계획에 담지 않는다. 못 하는 것을 "할 일"로 적지 않는다.
+        if (persistent.action === 'install') {
+            changes.push({ target: 'persistent-runtime', adapter: persistent.adapter });
+        }
+    }
+    // Profile 이 선언한 작업 도구. **다시 묻지 않는다** — 결정은 이미 Profile 에 있다.
+    if (state.workBinding && !state.workBinding.ready) {
+        const work = state.workBinding;
+        evidence.push(`work:${work.adapter}=${work.remedy ?? 'NOT_READY'}`);
+        if (work.remedy === 'HUMAN') {
+            return {
+                status: 'user_action_required',
+                code: 'ASC_WORK_BINDING_NEEDS_USER',
+                changes,
+                requiresUserAction: true,
+                ...actions(mode, evidence, [{ type: 'proceed', ...command(['setup', 'status']) }]),
+            };
+        }
+        // 고칠 수 있는 것만 계획에 담는다. HARD 는 담지 않는다 — 다시 돌려도 달라지지 않는다.
+        if (work.remedy === 'SELF_HEAL' && work.version) {
+            changes.push({
+                target: 'work-binding-setup',
+                adapter: work.adapter,
+                resource: work.resource,
+                version: work.version,
+            });
+        }
+    }
+    if (state.ascRoot && !state.attachmentBroken) {
         // 붙어 있어도 **무엇을 고를 수 있었는지**는 사실이다. 사용자 소유 Profile을 새로 놓고
         // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
         if (state.profileCandidates.length > 0) {
@@ -84,7 +119,8 @@ export function computeSetupPlan(state) {
         }
         return finish(changes, evidence, state, mode, command);
     }
-    // 아직 안 붙었다. 무엇으로 붙을지는 사람이 정한다.
+    // 아직 안 붙었거나, 붙이다 말았다(BROKEN). 무엇으로 붙을지는 사람이 정한다 —
+    // BROKEN이면 같은 선택으로 다시 붙이는 것이 repair다.
     const profile = state.requestedProfile ?? soleCandidate(state.profileCandidates);
     if (!profile) {
         evidence.push(`profile candidates=${state.profileCandidates.join(', ') || '(none)'}`);
@@ -171,6 +207,19 @@ export async function applySetupPlan(plan, effects) {
             case 'host-install':
                 await effects.installHost(change);
                 break;
+            case 'persistent-runtime':
+                // 이 갈래를 모르는 호출자에게는 이 변경이 없던 것으로 남는다.
+                if (!effects.registerPersistentRuntime)
+                    continue;
+                await effects.registerPersistentRuntime(change);
+                break;
+            case 'work-binding-setup':
+                // 이 갈래를 모르는 호출자에게는 이 변경이 없던 것으로 남는다 —
+                // 안 한 것을 "했다"로 적지 않는다.
+                if (!effects.setupWorkBinding)
+                    continue;
+                await effects.setupWorkBinding(change);
+                break;
         }
         applied.push(change);
     }
@@ -201,5 +250,9 @@ function changeLine(change) {
             return `  attach: ${change.profile} · scope ${change.scope}`;
         case 'host-install':
             return `  converge host installation: ${change.host} (currently ${change.from})`;
+        case 'work-binding-setup':
+            return `  repair ${change.adapter} for ${change.resource} through its own setup (${change.version})`;
+        case 'persistent-runtime':
+            return `  register this machine's ASC runtime with ${change.adapter}`;
     }
 }

package/dist/core/distribution/external-command.d.ts

@@ -0,0 +1,22 @@
+export type ResolvedInvocation = {
+    command: string;
+    args: string[];
+};
+export type ResolveDeps = {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    /** 테스트 주입용 — 실제 파일시스템을 보지 않게 한다. */
+    exists?: (path: string) => boolean;
+    readText?: (path: string) => string | null;
+    nodePath?: string;
+};
+/**
+ * npm `.cmd` shim이 가리키는 JS 진입점.
+ *
+ * npm이 쓰는 shim은 두 세대가 있고 둘 다 `"%dp0%\<상대경로>" %*` 형태로 JS를 부른다:
+ *   "%_prog%"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ *   "%dp0%\node.exe"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ * 형태가 다르면 null — 아는 척하지 않고 cmd.exe 경로로 넘어간다.
+ */
+export declare function shimTarget(shimText: string): string | null;
+export declare function resolveExternalCommand(command: string, args: readonly string[], deps?: ResolveDeps): ResolvedInvocation;

package/dist/core/distribution/external-command.js

@@ -0,0 +1,79 @@
+// 바깥 CLI를 Windows에서도 실제로 찾아 부른다 (C-14 §11의 연장).
+//
+// Node는 보안 수정 이후 shell 없이 `.cmd` 를 실행하지 않는다. 그런데 npm이 전역 설치로
+// 만들어 주는 명령은 Windows에서 전부 `.cmd` shim이다 — bare 이름을 Unix 방식으로만
+// spawn하면 ENOENT/EINVAL이 나고, 호출자는 "설치돼 있지 않다"고 오판한다
+// (Windows 실전 실측: shim이 PATH에 실재하는데 host probe가 not found →
+// external_write_guard STOP까지 이어졌다).
+//
+// shell을 켜는 것은 답이 아니다 — 인자가 escape 없이 이어붙는다(DEP0190). 대신:
+//   ① PATH에서 `.exe` 를 찾으면 그대로 부른다 (shell 불필요).
+//   ② `.cmd` shim이면 그 안이 가리키는 JS 진입점을 읽어 지금 도는 node로 직접 부른다 —
+//      cli/asc.ts의 npm 해석(resolveCommand)과 같은 태도다.
+//   ③ shim을 못 읽으면 cmd.exe /d /c 로 그 .cmd 를 부른다 — cmd.exe는 진짜 실행 파일이라
+//      shell 옵션이 필요 없다.
+// 셋 다 실패하면 이름 그대로 돌려준다 — PATH에 진짜 실행 파일이 있는 환경이 그 경우다.
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter as winDelimiter, dirname, extname, isAbsolute, join } from 'node:path/win32';
+const defaultRead = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * npm `.cmd` shim이 가리키는 JS 진입점.
+ *
+ * npm이 쓰는 shim은 두 세대가 있고 둘 다 `"%dp0%\<상대경로>" %*` 형태로 JS를 부른다:
+ *   "%_prog%"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ *   "%dp0%\node.exe"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ * 형태가 다르면 null — 아는 척하지 않고 cmd.exe 경로로 넘어간다.
+ */
+export function shimTarget(shimText) {
+    const match = /"%dp0%\\([^"%]+\.(?:js|mjs|cjs))"/i.exec(shimText);
+    return match ? match[1] : null;
+}
+export function resolveExternalCommand(command, args, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== 'win32')
+        return { command, args: [...args] };
+    // 경로나 확장자를 이미 갖췄으면 호출자가 알고 부르는 것이다 — 손대지 않는다.
+    if (isAbsolute(command) || command.includes('/') || command.includes('\\') || extname(command) !== '') {
+        return { command, args: [...args] };
+    }
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const readText = deps.readText ?? defaultRead;
+    const nodePath = deps.nodePath ?? process.execPath;
+    const pathValue = env.PATH ?? env.Path ?? '';
+    let firstShim = null;
+    for (const dir of pathValue.split(winDelimiter)) {
+        if (!dir)
+            continue;
+        const exe = join(dir, `${command}.exe`);
+        if (exists(exe))
+            return { command: exe, args: [...args] };
+        if (!firstShim) {
+            for (const ext of ['.cmd', '.bat']) {
+                const shim = join(dir, `${command}${ext}`);
+                if (exists(shim)) {
+                    firstShim = shim;
+                    break;
+                }
+            }
+        }
+    }
+    if (firstShim) {
+        const text = readText(firstShim);
+        const target = text ? shimTarget(text) : null;
+        if (target) {
+            const script = join(dirname(firstShim), target);
+            if (exists(script))
+                return { command: nodePath, args: [script, ...args] };
+        }
+        return { command: 'cmd.exe', args: ['/d', '/c', firstShim, ...args] };
+    }
+    return { command, args: [...args] };
+}

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

@@ -0,0 +1,73 @@
+/** 이 기계에서 ASC 가 소유하는 등록물 하나. 이름이 곧 소유권 증거다. */
+export declare const SERVICE_LABEL = "com.asc-agent.runtime";
+/**
+ * 등록물이 실행할 명령.
+ *
+ * **한 회차만 돈다** (`runtime tick`). 계속 도는 프로세스를 등록하지 않는 이유는 셋이다:
+ * OS 가 이미 주기를 관리할 줄 알고, 죽었을 때 되살리는 것도 OS 가 더 잘하며, 짧게 도는
+ * 프로세스는 죽어 있는 동안 자원을 쓰지 않는다.
+ */
+export type ServiceCommand = {
+    /** 실행 파일. 보통 지금 도는 node. */
+    program: string;
+    /** 인자. 첫 항목이 ASC 진입점이다. */
+    args: readonly string[];
+    /** 회차 간격(초). Core 상수가 아니다 — 호출자가 정한다 (C-12 불변식 ③). */
+    intervalSeconds: number;
+};
+/** 지금 이 기계의 등록 상태. */
+export type ServiceState = 
+/** 등록된 적이 없다. */
+{
+    kind: 'ABSENT';
+}
+/** 지금 우리가 쓰려는 것과 같다. */
+ | {
+    kind: 'CURRENT';
+    detail?: string;
+}
+/** 우리 것인데 낡았다 — 경로나 간격이 달라졌다. 수렴시킨다. */
+ | {
+    kind: 'STALE';
+    detail: string;
+}
+/** 이 OS 에서는 등록할 방법을 모른다. 없는 것을 있는 척하지 않는다. */
+ | {
+    kind: 'UNSUPPORTED';
+    detail: string;
+};
+/**
+ * OS 하나가 지켜야 할 계약.
+ *
+ * `uninstall` 은 **ASC 가 소유한 등록물만** 지운다. 사람이 만든 같은 이름의 무언가가
+ * 있으면 그것은 사람의 것이다 (C-03 §5.1 의 소유권 규칙과 같은 선).
+ */
+export type PersistentRuntimeAdapter = {
+    id: 'launchd' | 'schtasks' | 'systemd-user';
+    /** 이 기계에서 쓸 수 있는가. 쓸 수 없으면 install 을 시도하지 않는다. */
+    supported(): Promise<boolean>;
+    status(command: ServiceCommand): Promise<ServiceState>;
+    install(command: ServiceCommand): Promise<void>;
+    uninstall(): Promise<void>;
+};
+/**
+ * 무엇을 해야 하는가 — **아무것도 하지 않는다.**
+ *
+ * setup 의 detect→plan→apply 와 같은 모양이다: 판정과 실행을 나누고, 계획에 없는 것은
+ * 일어나지 않는다 (C-14 불변식 ⑩).
+ */
+export type PersistentRuntimePlan = {
+    action: 'none';
+    state: ServiceState;
+} | {
+    action: 'install';
+    state: ServiceState;
+} | {
+    action: 'unsupported';
+    state: Extract<ServiceState, {
+        kind: 'UNSUPPORTED';
+    }>;
+};
+export declare function planPersistentRuntime(adapter: PersistentRuntimeAdapter, command: ServiceCommand): Promise<PersistentRuntimePlan>;
+/** 사람이 읽는 한 줄. 왜 그 판정인지가 함께 와야 한다. */
+export declare function persistentRuntimeLine(id: string, plan: PersistentRuntimePlan): string;

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

@@ -0,0 +1,49 @@
+// Persistent Runtime Port — 사용자가 켜지 않아도 도는 자리 (설계 §4·§5).
+//
+// C-12 는 상시성을 "상태를 지속시키고 계산을 짧게 돌리는 것"으로 정의했고, 불변식 ④ 는
+// **Core 에 scheduler 제품을 박지 말라**고 했다. 그 둘을 함께 지키는 방법은 하나다:
+// Core 는 "무엇을 등록해야 하는가"만 말하고, launchd·Task Scheduler·systemd 는 그 말을
+// 자기 형식으로 옮기는 adapter 뒤에 둔다.
+//
+//   Core        이 기계에 ASC runtime 하나가 등록돼 있어야 한다
+//   Adapter     그것을 이 OS 에서 어떻게 표현하는가
+//
+// **workspace 마다 하나가 아니다.** 사용자/기계당 하나이고, 그 하나가 여러 workspace 를
+// 돌본다 (설계 §4.1) — workspace 가 늘 때마다 OS 서비스가 늘면 그것은 제품이 아니라 짐이다.
+//
+// root daemon 으로 올리지 않는다. 사용자 로그인 이후가 이 계약의 경계다 (설계 §4.3).
+/** 이 기계에서 ASC 가 소유하는 등록물 하나. 이름이 곧 소유권 증거다. */
+export const SERVICE_LABEL = 'com.asc-agent.runtime';
+export async function planPersistentRuntime(adapter, command) {
+    if (!(await adapter.supported())) {
+        return {
+            action: 'unsupported',
+            state: { kind: 'UNSUPPORTED', detail: `${adapter.id} is not usable on this machine` },
+        };
+    }
+    const state = await adapter.status(command);
+    switch (state.kind) {
+        case 'CURRENT':
+            return { action: 'none', state };
+        case 'UNSUPPORTED':
+            return { action: 'unsupported', state };
+        // 없는 것과 낡은 것은 다른 사실이지만 할 일은 같다 — 지금 형태로 수렴시킨다.
+        case 'ABSENT':
+        case 'STALE':
+            return { action: 'install', state };
+    }
+}
+/** 사람이 읽는 한 줄. 왜 그 판정인지가 함께 와야 한다. */
+export function persistentRuntimeLine(id, plan) {
+    switch (plan.action) {
+        case 'none':
+            return `Persistent runtime: registered with ${id}${plan.state.kind === 'CURRENT' && plan.state.detail ? ` (${plan.state.detail})` : ''}`;
+        case 'install':
+            return plan.state.kind === 'STALE'
+                ? `Persistent runtime: registration is behind — ${plan.state.detail}`
+                : `Persistent runtime: not registered yet`;
+        case 'unsupported':
+            // 못 하는 것을 "안 해도 된다"로 적지 않는다
+            return `Persistent runtime: this machine has no user-scope service manager ASC knows — ${plan.state.detail}`;
+    }
+}

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

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

package/dist/core/distribution/release.js

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

package/dist/core/operator/progress.js

@@ -76,7 +76,9 @@ export class ProgressService {
             return {
                 ok: false,
                 reason: 'NOT_OWNER',
-                detail: `${logicalSessionId} 에 Runtime이 붙어 있지 않다 — 먼저 소유권을 주장하라`,
+                // "주장하라"만으로는 다음 명령을 모른다 — 복구 명령까지가 오류 메시지다 (실측 ASC-4).
+                // Core는 host 이름을 모른다(B-17) — 자리만 비워 두면 Surface가 채운다.
+                detail: `${logicalSessionId} 에 Runtime이 붙어 있지 않다 — 먼저 소유권을 주장하라: asc host <host> bind ${logicalSessionId} --physical <id>`,
             };
         }
         if (binding.physicalSessionId !== physicalSessionId) {