@asc-agent/runtime 0.3.2 → 0.5.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

@@ -4,12 +4,15 @@ import type { EventSource } from '../ports/event-source.ts';
 import type { InventoryPort } from '../ports/inventory.ts';
 import type { ResourceContextPort } from '../ports/resource-context.ts';
 import type { ScmPort } from '../ports/scm.ts';
+import type { CoordinationSurfacePort } from '../ports/coordination-surface.ts';
 export type RuntimePorts = {
     eventSource?: EventSource;
     scm?: ScmPort;
     inventory?: InventoryPort;
     resourceContext?: ResourceContextPort;
     changeContext?: ChangeContextPort;
+    /** 밖에 물은 것이 실제로 있게 하는 통로 (C-04·C-10). 없으면 게시는 일어나지 않는다. */
+    coordinationSurface?: CoordinationSurfacePort;
     /** 무엇을 왜 못 만들었는지. 조용히 빠지면 사람이 이유를 알 수 없다. */
     unavailable: string[];
 };
@@ -62,4 +65,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

@@ -13,6 +13,7 @@ import { GitHubChangeContext, GitHubInventory, GitHubResourceContext } from "../
 import { GitHubEventSource } from "../adapters/github/event-source.js";
 import { GitHubScm } from "../adapters/github/scm.js";
 import { GitLabClient, GlabApiClient, discoverToken as discoverGitLabToken, glabAvailable, } from "../adapters/gitlab/client.js";
+import { GitLabCoordinationSurface } from "../adapters/gitlab/coordination.js";
 import { GitLabChangeContext, GitLabEventSource, GitLabInventory, GitLabResourceContext, } from "../adapters/gitlab/ports.js";
 import { JamMcpClient } from "../adapters/jam/mcp-client.js";
 import { JamEventSource } from "../adapters/jam/event-source.js";
@@ -30,7 +31,10 @@ const FACTORIES = {
             inventory: new GitLabInventory({ client, project }),
             resourceContext: new GitLabResourceContext({ client, project }),
             changeContext: new GitLabChangeContext({ client, project }),
-            // canonical·외부 write 통로는 아직 없다. 없는 것을 있는 척하지 않는다.
+            // 조율 표면. 토큰 통로일 때만 쓰기가 가능하다 — 도구를 통로로 쓰는 경우도 POST 를
+            // 대신 보내 준다. 둘 다 아니면 create 가 그 사실을 그대로 말한다.
+            coordinationSurface: new GitLabCoordinationSurface({ reader: client, writer: client, project }),
+            // canonical 통로는 아직 없다. 없는 것을 있는 척하지 않는다.
         };
     },
     github(binding, input, token) {
@@ -112,6 +116,7 @@ const PORT_OF = {
     'context.change': 'changeContext',
     'context.resource': 'resourceContext',
     'canonical.read': 'scm',
+    'coordination.surface': 'coordinationSurface',
 };
 /**
  * capability가 필요한 자리마다 어느 binding이 맡을지 정해 Port를 만든다.
@@ -140,6 +145,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

@@ -18,7 +18,7 @@ export type SetupState = {
      * runtime 디렉터리는 있는데 profile.lock을 읽지 못하는 상태 — 붙이다 만 것이다.
      *
      * 이것을 "붙어 있음"으로 읽으면 plan은 `applied`를 답하면서 실패할 `asc proceed`를
-     * 다음 행동으로 준다 (SSAFESTA Windows 실측 ASC-2: 파일 잠금이 빈 skeleton만 남긴
+     * 다음 행동으로 준다 (Windows 실전 실측 ASC-2: 파일 잠금이 빈 skeleton만 남긴
      * 경우). 붙이다 만 상태는 붙일 것이 남은 상태다 — repair가 plan에 드러나야 한다.
      */
     attachmentBroken?: boolean;
@@ -42,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 = 
 /**
@@ -67,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 = 
@@ -75,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, 불변식 ⑯).
  *
@@ -126,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

@@ -78,6 +78,39 @@ export function computeSetupPlan(state) {
             changes.push({ target: 'host-install', host: host.id, from: host.status });
         }
     }
+    // 이 기계의 지속 등록. 프로젝트와 무관하므로 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을 새로 놓고
         // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
@@ -174,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);
     }
@@ -204,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/binding/types.d.ts

@@ -4,7 +4,7 @@
  * 여기에 provider 이름을 넣지 않는다 — `scm.<제품>` 같은 값은 capability가 아니라
  * adapter identity이며, 그것으로 갈라지기 시작하면 Core가 provider를 아는 셈이 된다.
  */
-export declare const CAPABILITIES: readonly ["observe.delta", "inventory.enumerate", "context.resource", "context.thread", "context.change", "context.history", "canonical.read", "action.comment", "action.update", "presentation.digest", "presentation.priority", "approval.interactive", "identity.resolve"];
+export declare const CAPABILITIES: readonly ["observe.delta", "inventory.enumerate", "context.resource", "context.thread", "context.change", "context.history", "canonical.read", "action.comment", "coordination.surface", "action.update", "presentation.digest", "presentation.priority", "approval.interactive", "identity.resolve"];
 export type Capability = (typeof CAPABILITIES)[number];
 /** describe() 산출물 — 호출도 네트워크도 없는 정적 선언 (C-09 §5). */
 export type AdapterDescriptor = {

package/dist/core/binding/types.js

@@ -21,6 +21,7 @@ export const CAPABILITIES = [
     'context.history',
     'canonical.read',
     'action.comment',
+    'coordination.surface',
     'action.update',
     'presentation.digest',
     'presentation.priority',

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

@@ -20,3 +20,29 @@ export type ResolveDeps = {
  */
 export declare function shimTarget(shimText: string): string | null;
 export declare function resolveExternalCommand(command: string, args: readonly string[], deps?: ResolveDeps): ResolvedInvocation;
+/**
+ * PATH 에서 실행 파일 하나를 찾는다 (POSIX). 없으면 null — 있는 척하지 않는다.
+ *
+ * Windows 는 위 `resolveExternalCommand` 가 shim 까지 풀어 주므로 여기서는 다루지 않는다.
+ */
+export declare function findOnPath(command: string, deps?: {
+    env?: NodeJS.ProcessEnv;
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+}): string | null;
+/** 시스템 기본 자리. 서비스 관리자가 주는 PATH 가 대개 이것이다. */
+export declare const SYSTEM_PATH: readonly ["/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+/**
+ * 서비스에 실어 보낼 PATH — **지금 이 셸의 PATH 를 통째로 옮기지 않는다.** 세션마다 붙는
+ * 임시 디렉터리가 그대로 들어가면 등록물이 매번 STALE 이 되고, 사라진 경로가 남는다.
+ * 대신 필요한 실행 파일이 **실제로 있는 디렉터리만** 고른다. 못 찾은 도구는 조용히 빠지지
+ * 않고 `missing` 에 남는다 — 그 도구를 쓰는 통로는 서비스에서도 열리지 않을 것이다.
+ */
+export declare function servicePath(tools: readonly string[], deps?: {
+    env?: NodeJS.ProcessEnv;
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+}): {
+    path: string;
+    missing: string[];
+};

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

@@ -3,7 +3,7 @@
 // Node는 보안 수정 이후 shell 없이 `.cmd` 를 실행하지 않는다. 그런데 npm이 전역 설치로
 // 만들어 주는 명령은 Windows에서 전부 `.cmd` shim이다 — bare 이름을 Unix 방식으로만
 // spawn하면 ENOENT/EINVAL이 나고, 호출자는 "설치돼 있지 않다"고 오판한다
-// (SSAFESTA Windows 실측: shim이 PATH에 실재하는데 host probe가 not found →
+// (Windows 실전 실측: shim이 PATH에 실재하는데 host probe가 not found →
 // external_write_guard STOP까지 이어졌다).
 //
 // shell을 켜는 것은 답이 아니다 — 인자가 escape 없이 이어붙는다(DEP0190). 대신:
@@ -13,7 +13,7 @@
 //   ③ shim을 못 읽으면 cmd.exe /d /c 로 그 .cmd 를 부른다 — cmd.exe는 진짜 실행 파일이라
 //      shell 옵션이 필요 없다.
 // 셋 다 실패하면 이름 그대로 돌려준다 — PATH에 진짜 실행 파일이 있는 환경이 그 경우다.
-import { existsSync, readFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
 import { delimiter as winDelimiter, dirname, extname, isAbsolute, join } from 'node:path/win32';
 const defaultRead = (path) => {
     try {
@@ -77,3 +77,60 @@ export function resolveExternalCommand(command, args, deps = {}) {
     }
     return { command, args: [...args] };
 }
+/**
+ * PATH 에서 실행 파일 하나를 찾는다 (POSIX). 없으면 null — 있는 척하지 않는다.
+ *
+ * Windows 는 위 `resolveExternalCommand` 가 shim 까지 풀어 주므로 여기서는 다루지 않는다.
+ */
+export function findOnPath(command, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform === 'win32')
+        return null;
+    if (command.includes('/'))
+        return (deps.exists ?? isExecutable)(command) ? command : null;
+    const exists = deps.exists ?? isExecutable;
+    const pathValue = (deps.env ?? process.env).PATH ?? '';
+    for (const dir of pathValue.split(':')) {
+        if (!dir)
+            continue;
+        const candidate = `${dir}/${command}`;
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+const isExecutable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** 시스템 기본 자리. 서비스 관리자가 주는 PATH 가 대개 이것이다. */
+export const SYSTEM_PATH = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+/**
+ * 서비스에 실어 보낼 PATH — **지금 이 셸의 PATH 를 통째로 옮기지 않는다.** 세션마다 붙는
+ * 임시 디렉터리가 그대로 들어가면 등록물이 매번 STALE 이 되고, 사라진 경로가 남는다.
+ * 대신 필요한 실행 파일이 **실제로 있는 디렉터리만** 고른다. 못 찾은 도구는 조용히 빠지지
+ * 않고 `missing` 에 남는다 — 그 도구를 쓰는 통로는 서비스에서도 열리지 않을 것이다.
+ */
+export function servicePath(tools, deps = {}) {
+    const dirs = [];
+    const missing = [];
+    const push = (dir) => {
+        if (!dirs.includes(dir))
+            dirs.push(dir);
+    };
+    for (const tool of tools) {
+        const found = findOnPath(tool, deps);
+        if (found)
+            push(found.slice(0, found.lastIndexOf('/')) || '/');
+        else
+            missing.push(tool);
+    }
+    for (const dir of SYSTEM_PATH)
+        push(dir);
+    return { path: dirs.join(':'), missing };
+}

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

@@ -0,0 +1,82 @@
+/** 이 기계에서 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;
+    /**
+     * 등록물이 돌 때의 환경. **서비스는 로그인 셸의 PATH 를 물려받지 않는다** — 실기계에서
+     * launchd 가 준 PATH 는 `/usr/bin:/bin:/usr/sbin:/sbin` 뿐이라 외부 통로 실행 파일을
+     * 하나도 못 찾았다. 등록하는 쪽이 필요한 것을 결정해 여기 실어 보내고, 내용이 바뀌면
+     * 등록물이 STALE 로 드러난다 — 셸 설정을 추측하는 경로는 없다.
+     */
+    environment?: Readonly<Record<string, string>>;
+    /** 회차의 표준 출력·오류를 남길 파일. 없으면 OS 기본(대개 버려진다). */
+    logPath?: string;
+};
+/** 지금 이 기계의 등록 상태. */
+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.2";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.3.2";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.3.2";
+export declare const RELEASE_VERSION = "0.5.0";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.5.0";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.5.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.2';
+export const RELEASE_VERSION = '0.5.0';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**