@asc-agent/runtime 0.4.0 → 0.5.1

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[];
 };
@@ -50,6 +53,23 @@ export declare function closeToolClients(): Promise<void>;
  * 후보가 갈리면 만들지 않는다 — `AMBIGUOUS_BINDING`은 사람이 정할 문제이고, 여기서 하나를
  * 고르면 그 선택을 아무도 보지 못한다 (C-09 §4.2).
  */
+/**
+ * 작업 항목을 읽는 통로의 역할 이름 (P0 F7).
+ *
+ * `rolesFor` 는 **선언된 binding 이 하나일 때만** 역할을 정한다. 그래서 code binding 과
+ * work binding 이 둘 다 `context.resource` 를 제공하면 아무 역할도 서지 않고, 작업 항목
+ * 조회는 "통로가 없다" 로 끝난다 — 실기계에서 감시는 되는데 `proceed --work` 만 실패한
+ * 자리가 여기다. 없는 것이 아니라 **누구에게 물을지 정하지 않은 것**이었다.
+ *
+ * 가르는 기준은 provider 이름이 아니라 capability 모양이다: 작업 항목 통로는 목록과 자원을
+ * 알고 **변경을 모른다**. 코드 통로는 변경을 안다. 그 차이가 곧 두 축의 정의다
+ * (C-09 §2.1 — Port 를 좁게 나눈 이유가 그것이다).
+ */
+export declare function workItemRoles(plan: BindingPlan, declared: readonly {
+    role: string;
+    adapter: string;
+    resource: string;
+}[]): Partial<Record<Capability, string>>;
 /**
  * Profile이 선언한 역할 배정을 capability별 역할로 옮긴다 (C-09 §3.1·§4).
  *

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를 만든다.
@@ -119,6 +124,32 @@ const PORT_OF = {
  * 후보가 갈리면 만들지 않는다 — `AMBIGUOUS_BINDING`은 사람이 정할 문제이고, 여기서 하나를
  * 고르면 그 선택을 아무도 보지 못한다 (C-09 §4.2).
  */
+/**
+ * 작업 항목을 읽는 통로의 역할 이름 (P0 F7).
+ *
+ * `rolesFor` 는 **선언된 binding 이 하나일 때만** 역할을 정한다. 그래서 code binding 과
+ * work binding 이 둘 다 `context.resource` 를 제공하면 아무 역할도 서지 않고, 작업 항목
+ * 조회는 "통로가 없다" 로 끝난다 — 실기계에서 감시는 되는데 `proceed --work` 만 실패한
+ * 자리가 여기다. 없는 것이 아니라 **누구에게 물을지 정하지 않은 것**이었다.
+ *
+ * 가르는 기준은 provider 이름이 아니라 capability 모양이다: 작업 항목 통로는 목록과 자원을
+ * 알고 **변경을 모른다**. 코드 통로는 변경을 안다. 그 차이가 곧 두 축의 정의다
+ * (C-09 §2.1 — Port 를 좁게 나눈 이유가 그것이다).
+ */
+export function workItemRoles(plan, declared) {
+    const candidates = plan.bindings
+        .filter((binding) => binding.role !== undefined)
+        .filter((binding) => declared.some((d) => d.adapter === binding.adapterId && d.resource === binding.resource))
+        .filter((binding) => binding.provides.includes('context.resource') &&
+        binding.provides.includes('inventory.enumerate') &&
+        !binding.provides.includes('context.change'));
+    const roles = new Set(candidates.map((binding) => binding.role));
+    // 갈리면 고르지 않는다 — 그것은 사람이 정할 문제다 (C-09 §4.2).
+    if (roles.size !== 1)
+        return {};
+    const role = [...roles][0];
+    return { 'context.resource': role, 'inventory.enumerate': role, 'context.thread': role, 'context.history': role };
+}
 /**
  * Profile이 선언한 역할 배정을 capability별 역할로 옮긴다 (C-09 §3.1·§4).
  *

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

@@ -61,6 +61,46 @@ export type SetupState = {
      * 사람에게 "그 도구를 설정할까요?"라고 되물으면, 사람은 자기가 이미 적어 둔 것을 다시
      * 답하게 된다. 고칠 수 있는 것은 고치고, 사람만 할 수 있는 것에서만 멈춘다.
      */
+    /**
+     * 이 저장소 자신의 remote 에서 읽히는 Profile id (P0 fresh onboarding).
+     *
+     * **다른 논리 workspace 를 추측해 합치는 것이 아니다** (C-11 금지사항). 이 저장소가
+     * 스스로 증명하는 신원 하나이고, 그 이름의 Profile 이 이미 있으면 그것을 쓰고 없으면
+     * 만든다. 이것이 없어서 fresh 설치가 `ASC_PROFILE_SELECTION_REQUIRED` 앞에 멈췄고,
+     * 사람이 `profile adopt` 를 따로 쳐야 했다.
+     */
+    adoptable?: {
+        id: string;
+        exists: boolean;
+    };
+    /**
+     * 이 workspace 에 승인 권한자가 서 있는가, 그리고 지금 이 사람을 무엇으로 알아볼 수
+     * 있는가. `actor` 는 인증된 provider 가 말한 값이며 ASC 가 지어내지 않는다.
+     */
+    identity?: {
+        wired: boolean;
+        actor?: string;
+    };
+    /**
+     * 발견이 **갈리지 않고** 제안하는 결합. Profile 에 결합 선언이 없을 때만 본다.
+     * 갈리면 비어 있다 — 고르는 것은 사람이다 (C-09 §4.2).
+     */
+    bindingProposal?: readonly {
+        role: string;
+        adapter: string;
+        resource: string;
+    }[];
+    /**
+     * 이 checkout 이 증명하는 정본 갈래. remote 가 스스로 말한 기본 branch 하나이며,
+     * Profile 에 정본 선언이 비어 있을 때만 관측한다. 알 수 없으면 없다 — 지어내면 세션이
+     * 읽지 못하는 정본을 딛고 서게 된다.
+     */
+    canonicalProposal?: {
+        id: string;
+        provider: string;
+        remote: string;
+        ref: string;
+    };
     workBinding?: {
         adapter: string;
         resource: string;
@@ -86,12 +126,63 @@ export type SetupChange =
     strategy: 'npm-global';
     from: string;
 }
+/**
+ * 이 저장소를 설명하는 Profile 을 만든다 (P0 fresh onboarding).
+ *
+ * 근거는 이 저장소의 remote 하나뿐이다. 다른 workspace 를 추측하지 않는다.
+ */
+ | {
+    target: 'adopt-profile';
+    profile: string;
+}
 /** 이 checkout에 runtime을 붙인다. local scope면 저장소에는 아무것도 만들지 않는다. */
  | {
     target: 'attach-workspace';
     scope: 'local' | 'project';
     profile: string;
 }
+/**
+ * 지금 이 사람을 이 workspace 의 승인 권한자로 세운다.
+ *
+ * **비밀은 다루지 않는다** — 이름과 채널뿐이다. 이것이 계획에 없으면 fresh 설치가
+ * 승인자 0 인 채로 READY 가 되고, 사람이 `setup identity` 를 따로 쳐야 했다.
+ */
+ | {
+    target: 'identity';
+    actor: string;
+}
+/**
+ * 발견이 증명한 결합을 Profile 에 적는다.
+ *
+ * 갈리는 것은 담지 않는다. 여기 없으면 사람이 Profile 을 손으로 고쳐야 했고, 그것이
+ * fresh onboarding 에서 실제로 필요했던 단계다.
+ */
+ | {
+    target: 'profile-bindings';
+    profile: string;
+    bindings: readonly {
+        role: string;
+        adapter: string;
+        resource: string;
+    }[];
+}
+/**
+ * Profile 에 정본 갈래를 적는다.
+ *
+ * 이것이 비어 있으면 판정이 전부 "확인 못 함" 으로 나온다 — relevance 도
+ * responsibility 도 정본을 딛고 서기 때문이다. 근거는 remote 가 스스로 말한 기본
+ * branch 이고, 그 값을 얻지 못하면 이 변경은 계획에 들지 않는다.
+ */
+ | {
+    target: 'profile-canonical';
+    profile: string;
+    source: {
+        id: string;
+        provider: string;
+        remote: string;
+        ref: string;
+    };
+}
 /** Host 설치물을 지금 source에 맞춘다. 왜 필요한지까지 든다. */
  | {
     target: 'host-install';
@@ -190,17 +281,27 @@ export type SetupEffects = {
     registerPersistentRuntime?(change: Extract<SetupChange, {
         target: 'persistent-runtime';
     }>): Promise<void>;
+    /** 이 저장소를 설명하는 Profile 을 만든다. */
+    adoptProfile?(change: Extract<SetupChange, {
+        target: 'adopt-profile';
+    }>): Promise<void>;
+    /** 승인 권한자를 세운다. 비밀은 다루지 않는다. */
+    wireIdentity?(change: Extract<SetupChange, {
+        target: 'identity';
+    }>): Promise<void>;
+    /** 발견이 증명한 결합을 Profile 에 적는다. */
+    declareBindings?(change: Extract<SetupChange, {
+        target: 'profile-bindings';
+    }>): Promise<void>;
+    /** remote 가 말한 정본 갈래를 Profile 에 적는다. */
+    declareCanonical?(change: Extract<SetupChange, {
+        target: 'profile-canonical';
+    }>): Promise<void>;
 };
 export type ApplyResult = {
     applied: SetupChange[];
     changesApplied: boolean;
 };
-/**
- * plan에 적힌 것만 실행한다. **다시 판단하지 않는다** (C-14 불변식 ⑩).
- *
- * 여기서 상태를 다시 보고 마음을 바꾸면, 사람이 승인한 plan과 실제로 일어난 일이
- * 달라진다. 그 순간 plan은 아무것도 보장하지 않는 문서가 된다.
- */
 export declare function applySetupPlan(plan: SetupPlan, effects: SetupEffects): Promise<ApplyResult>;
 /** 사람이 읽는 줄. 같은 plan에서 나온다 — agent가 보는 JSON과 다른 판단이 아니다. */
 export declare function renderSetupPlan(plan: SetupPlan): string[];

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

@@ -66,7 +66,7 @@ export function computeSetupPlan(state) {
                 code: 'ASC_HOST_INSTALL_MODIFIED',
                 // 사람이 고친 것을 덮는 것은 사람이 정한다 — plan에 담아 몰래 적용하지 않는다.
                 // 다만 runtime 설치처럼 이 결정과 무관한 준비는 계획에 남는다.
-                changes,
+                changes: orderChanges(changes, false),
                 requiresUserAction: true,
                 ...actions(mode, evidence, [
                     { type: 'force_host_install', ...command(['host', host.id, 'install', '--force']) },
@@ -96,7 +96,7 @@ export function computeSetupPlan(state) {
             return {
                 status: 'user_action_required',
                 code: 'ASC_WORK_BINDING_NEEDS_USER',
-                changes,
+                changes: orderChanges(changes, false),
                 requiresUserAction: true,
                 ...actions(mode, evidence, [{ type: 'proceed', ...command(['setup', 'status']) }]),
             };
@@ -112,6 +112,7 @@ export function computeSetupPlan(state) {
         }
     }
     if (state.ascRoot && !state.attachmentBroken) {
+        pushWorkspaceChanges(changes, state, evidence);
         // 붙어 있어도 **무엇을 고를 수 있었는지**는 사실이다. 사용자 소유 Profile을 새로 놓고
         // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
         if (state.profileCandidates.length > 0) {
@@ -121,13 +122,23 @@ export function computeSetupPlan(state) {
     }
     // 아직 안 붙었거나, 붙이다 말았다(BROKEN). 무엇으로 붙을지는 사람이 정한다 —
     // BROKEN이면 같은 선택으로 다시 붙이는 것이 repair다.
-    const profile = state.requestedProfile ?? soleCandidate(state.profileCandidates);
+    // 이 저장소가 스스로 증명하는 Profile 이 있으면 그것이 답이다 — 이름이 이미 있으면
+    // 그것을 쓰고, 없으면 만든다. 둘 다 "다른 workspace 를 추측"하는 것이 아니다.
+    const adoptable = state.adoptable;
+    const profile = state.requestedProfile ??
+        (adoptable && state.profileCandidates.includes(adoptable.id) ? adoptable.id : undefined) ??
+        (adoptable ? adoptable.id : undefined) ??
+        soleCandidate(state.profileCandidates);
+    if (adoptable && !state.requestedProfile && !adoptable.exists) {
+        evidence.push(`profile=${adoptable.id} (adopted from this repository)`);
+        changes.push({ target: 'adopt-profile', profile: adoptable.id });
+    }
     if (!profile) {
         evidence.push(`profile candidates=${state.profileCandidates.join(', ') || '(none)'}`);
         return {
             status: 'user_action_required',
             code: 'ASC_PROFILE_SELECTION_REQUIRED',
-            changes,
+            changes: orderChanges(changes, false),
             requiresUserAction: true,
             profiles: state.profileCandidates,
             // 고를 것이 **없을** 수도 있다 — 배포본이 들고 있는 것은 예시뿐이고, 이 프로젝트를
@@ -153,9 +164,36 @@ export function computeSetupPlan(state) {
         evidence.push('adoption=project (explicit)');
     }
     changes.push({ target: 'attach-workspace', scope: state.scope, profile });
-    evidence.push(`profile=${profile}${state.requestedProfile ? ' (given)' : ' (sole candidate)'}`);
+    if (!changes.some((c) => c.target === 'adopt-profile')) {
+        evidence.push(`profile=${profile}${state.requestedProfile ? ' (given)' : ' (sole candidate)'}`);
+    }
+    pushWorkspaceChanges(changes, state, evidence, profile);
     return finish(changes, evidence, state, mode, command);
 }
+/**
+ * workspace 가 서고 나서 필요한 것들 — 승인자와 결합 선언.
+ *
+ * 둘 다 **관측된 사실이 있을 때만** 계획에 든다. 승인자는 인증된 provider 가 말한 이름이고,
+ * 결합은 발견이 갈리지 않고 제안한 것이다. 없으면 담지 않는다 — 지어내면 그 값이 곧
+ * 사람이 겪는 오작동이 된다.
+ */
+function pushWorkspaceChanges(changes, state, evidence, attachingProfile) {
+    if (state.identity && !state.identity.wired && state.identity.actor) {
+        evidence.push(`identity=${state.identity.actor} (not yet recorded)`);
+        changes.push({ target: 'identity', actor: state.identity.actor });
+    }
+    const profile = attachingProfile ?? state.attachedProfile;
+    if (!profile)
+        return;
+    if (state.bindingProposal && state.bindingProposal.length > 0) {
+        evidence.push(`bindings proposed=${state.bindingProposal.map((b) => `${b.role}:${b.adapter}`).join(', ')}`);
+        changes.push({ target: 'profile-bindings', profile, bindings: state.bindingProposal });
+    }
+    if (state.canonicalProposal) {
+        evidence.push(`canonical proposed=${state.canonicalProposal.remote}/${state.canonicalProposal.ref}`);
+        changes.push({ target: 'profile-canonical', profile, source: state.canonicalProposal });
+    }
+}
 /** 후보가 하나뿐이어도 대신 고르지 않는다 — 여기서 돌려주는 것은 "고를 것이 없다"뿐이다. */
 function soleCandidate(candidates) {
     return candidates.length === 1 ? candidates[0] : undefined;
@@ -172,7 +210,9 @@ function actions(mode, evidence, list) {
         evidence,
     };
 }
-function finish(changes, evidence, state, mode, command) {
+function finish(raw, evidence, state, mode, command) {
+    const settled = (Boolean(state.ascRoot) && !state.attachmentBroken) || raw.some((c) => c.target === 'attach-workspace');
+    const changes = orderChanges(raw, settled);
     if (changes.length === 0) {
         return {
             status: 'already_configured',
@@ -194,6 +234,34 @@ function finish(changes, evidence, state, mode, command) {
  * 여기서 상태를 다시 보고 마음을 바꾸면, 사람이 승인한 plan과 실제로 일어난 일이
  * 달라진다. 그 순간 plan은 아무것도 보장하지 않는 문서가 된다.
  */
+/**
+ * 실행 순서 (설계 §9 — fresh onboarding).
+ *
+ * **등록이 맨 마지막이다.** 예전에는 등록이 붙이기보다 먼저 계획에 들어가, OS 가 아직
+ * identity·binding 이 서지 않은 workspace 를 회차로 돌렸다. 그 회차는 실패했고, 사람은
+ * 자기가 setup 을 끝내기도 전에 실패 기록을 봤다.
+ */
+const CHANGE_ORDER = {
+    'runtime-install': 0,
+    'adopt-profile': 1,
+    'attach-workspace': 2,
+    identity: 3,
+    'profile-bindings': 4,
+    'profile-canonical': 5,
+    'work-binding-setup': 6,
+    'host-install': 7,
+    'persistent-runtime': 8,
+};
+/**
+ * 순서를 고정하고, **아직 설 자리가 아닌 등록은 뺀다.**
+ *
+ * 붙는 것이 이번 계획으로 끝나지 않으면 이 기계에 등록할 이유가 없다 — 등록물은
+ * workspace 를 돌보는 것이고, 돌볼 workspace 가 아직 없기 때문이다.
+ */
+function orderChanges(changes, attachmentSettled) {
+    const kept = attachmentSettled ? [...changes] : changes.filter((change) => change.target !== 'persistent-runtime');
+    return kept.sort((a, b) => CHANGE_ORDER[a.target] - CHANGE_ORDER[b.target]);
+}
 export async function applySetupPlan(plan, effects) {
     const applied = [];
     for (const change of plan.changes) {
@@ -220,6 +288,26 @@ export async function applySetupPlan(plan, effects) {
                     continue;
                 await effects.setupWorkBinding(change);
                 break;
+            case 'adopt-profile':
+                if (!effects.adoptProfile)
+                    continue;
+                await effects.adoptProfile(change);
+                break;
+            case 'identity':
+                if (!effects.wireIdentity)
+                    continue;
+                await effects.wireIdentity(change);
+                break;
+            case 'profile-bindings':
+                if (!effects.declareBindings)
+                    continue;
+                await effects.declareBindings(change);
+                break;
+            case 'profile-canonical':
+                if (!effects.declareCanonical)
+                    continue;
+                await effects.declareCanonical(change);
+                break;
         }
         applied.push(change);
     }
@@ -254,5 +342,15 @@ function changeLine(change) {
             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}`;
+        case 'adopt-profile':
+            return `  create profile ${change.profile} from this repository's remote`;
+        case 'identity':
+            return `  record ${change.actor} as this workspace's approver`;
+        case 'profile-bindings':
+            return `  declare bindings in ${change.profile}: ${change.bindings
+                .map((b) => `${b.role}=${b.adapter}:${b.resource}`)
+                .join(', ')}`;
+        case 'profile-canonical':
+            return `  declare canonical source in ${change.profile}: ${change.source.remote}/${change.source.ref}`;
     }
 }

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

@@ -8,7 +8,7 @@ export type AttachmentState = 'READY' | 'UNATTACHED' | 'BROKEN' | 'LOCK_DRIFT';
  */
 export type GateState = 'OPEN' | 'BLOCKED' | 'DEGRADED';
 export type SetupGate = {
-    id: 'approval' | 'monitor' | 'external-write';
+    id: 'approval' | 'monitor' | 'external-write' | 'canonical';
     label: string;
     state: GateState;
     /** 무엇이 없어서 막혔는지. */
@@ -30,6 +30,8 @@ export type SetupStatus = {
     gates: SetupGate[];
 };
 export type SetupInput = {
+    /** Profile 이 선언한 정본 갈래 수. 붙지 않았으면 알 수 없으므로 `undefined` 다. */
+    canonicalSources?: number;
     attachment: AttachmentState;
     /** 붙어 있는 Profile의 id와 출처. **Surface가 읽어 넘긴다** — Core는 경로를 모른다. */
     profile?: {

package/dist/core/attach/setup.js

@@ -28,7 +28,7 @@ export function assessSetup(input) {
         attachment: input.attachment,
         ...(input.profile ? { profile: input.profile } : {}),
         ready: [...ALWAYS_READY],
-        gates: [approvalGate(input), monitorGate(input), externalWriteGate(input)],
+        gates: [approvalGate(input), canonicalGate(input), monitorGate(input), externalWriteGate(input)],
     };
 }
 /** 승인 결정. identities.json은 lock digest에 없어 재고정이 필요 없다. */
@@ -46,6 +46,30 @@ function approvalGate(input) {
         howTo: ['open identities.json and add an approver in the $example form (no re-lock needed)'],
     };
 }
+/**
+ * 정본 조회 (C-08 · C-11).
+ *
+ * 코드 결합은 선언돼 있는데 정본 갈래가 비어 있으면, 판정은 "확인 못 함" 으로만 나온다 —
+ * relevance 도 responsibility 도 정본을 딛고 서기 때문이다. 실기계에서 그 상태가 READY 로
+ * 보였고, 사람은 무엇이 빠졌는지 알 방법이 없었다. 없는 것을 없다고 말한다.
+ */
+function canonicalGate(input) {
+    // 붙지 않았으면 이 축을 판정하지 않는다 — 아직 Profile 이 없다.
+    if (input.attachment !== 'READY' || input.canonicalSources === undefined) {
+        return { id: 'canonical', label: 'canonical evidence', state: 'OPEN', missing: [], warnings: [], howTo: [] };
+    }
+    if (input.canonicalSources > 0) {
+        return { id: 'canonical', label: 'canonical evidence', state: 'OPEN', missing: [], warnings: [], howTo: [] };
+    }
+    return {
+        id: 'canonical',
+        label: 'canonical evidence',
+        state: 'BLOCKED',
+        missing: ['the profile declares no canonical source, so nothing can be judged against a baseline'],
+        warnings: [],
+        howTo: [`declare one in the profile's canonical.sources — ${RESOLVE_AGAIN}`],
+    };
+}
 /**
  * 외부 감시. 두 설정이 서로 다른 것을 막는다 —
  * controller.identities가 없으면 실행 자체가 안 되고(단 --as로 우회 가능),

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

@@ -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

@@ -14,6 +14,15 @@ export type ServiceCommand = {
     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 = 

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.4.0";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.4.0";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.4.0";
+export declare const RELEASE_VERSION = "0.5.1";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.5.1";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.5.1";
 /**
  * 아직 설치되지 않은 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.4.0';
+export const RELEASE_VERSION = '0.5.1';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**