@asc-agent/runtime 0.4.0 → 0.5.0

package/dist/cli/asc.js

@@ -46,6 +46,8 @@ import { CoverageLedger, renderHealth } from "../core/monitor/coverage.js";
 import { evaluateHealth, healthAlertLines } from "../core/monitor/health-alerts.js";
 import { Operator } from "../core/operator/proceed.js";
 import { deriveSessionContractDraft } from "../core/operator/derive-draft.js";
+import { servicePath } from "../core/distribution/external-command.js";
+import { LocalCanonicalReader } from "../adapters/local/canonical.js";
 import { LocalRepoAdapter } from "../adapters/local/repo.js";
 import { GitHubAdapter } from "../adapters/github/adapter.js";
 import { GitLabAdapter } from "../adapters/gitlab/adapter.js";
@@ -69,12 +71,14 @@ import { AuditLedger, decisionLines, delegationLine, executionLines, reclaimLine
 import { ClosureLedger } from "../core/runtime/closure.js";
 import { Orchestrator, renderTick } from "../core/runtime/orchestrator.js";
 import { LAST_RUN_KEY, RuntimeLease, fileScope, readBackground, renderBackground, staleAfter, } from "../core/runtime/background.js";
-import { dueWorkspaces, renderWorkspaces, viewWorkspaces, } from "../core/runtime/workspaces.js";
+import { dueWorkspaces, renderWorkspaces, summarizePass, viewWorkspaces } from "../core/runtime/workspaces.js";
 import { persistentRuntimeLine, planPersistentRuntime, } from "../core/distribution/persistent-runtime.js";
 import { launchdAdapter } from "../adapters/service/launchd.js";
 import { schtasksAdapter } from "../adapters/service/schtasks.js";
 import { serviceAdapterFor, systemdUserAdapter } from "../adapters/service/systemd-user.js";
 import { QueryLedger } from "../core/runtime/query.js";
+import { CoordinationLedger, coordinationLines, responsesFrom, viewCoordination, } from "../core/runtime/coordination.js";
+import { publishLine, publishOnce, recordPublication } from "../core/runtime/publish.js";
 import { ObservationLedger } from "../core/monitor/observation.js";
 import { DeliveryLedger, deliver, planDigest } from "../core/presentation/digest.js";
 import { LocalPresentation } from "../adapters/local/presentation.js";
@@ -191,6 +195,11 @@ const USAGE = `asc — Agent Session Control
                         [--to <authority>]
   asc query list   [--json]
 
+  asc coordination [status] [--json]   # what was asked outside, and whether it reached anyone
+  asc coordination publish --query <ID> --title <text> --body-file <path>
+                   [--audience <who>] [--known <objectId>] [--work <ref>] [--json]
+  asc coordination observe [--json]    # did anything come back on what we published
+
   asc progress show   [<S-ID>]
   asc progress report <S-ID> --physical <id> --phase <text>
                       [--milestone <text>...] [--next <text>] [--unresolved <text>...]
@@ -577,6 +586,11 @@ function parseArgsOrThrow(argv) {
             validator: { type: 'string' },
             result: { type: 'string' },
             finding: { type: 'string', multiple: true },
+            query: { type: 'string' },
+            title: { type: 'string' },
+            'body-file': { type: 'string' },
+            audience: { type: 'string', multiple: true },
+            known: { type: 'string', multiple: true },
             blocker: { type: 'string', multiple: true },
             risk: { type: 'string', multiple: true },
             evidence: { type: 'string', multiple: true },
@@ -718,7 +732,7 @@ async function runParsedCommand(values, positionals, entry, argv) {
     // 순서가 뒤집힌다. 나머지 profile 명령은 아래 attach 경로에 그대로 남는다.
     if (group === 'profile' && command === 'adopt')
         return runProfileAdopt(values, entry);
-    if (!['inbox', 'grant', 'monitor', 'runtime', 'front', 'freeze', 'thaw', 'escalate', 'profile', 'session', 'controller', 'proceed', 'progress', 'preflight', 'closure', 'query'].includes(group)) {
+    if (!['inbox', 'grant', 'monitor', 'runtime', 'front', 'coordination', 'freeze', 'thaw', 'escalate', 'profile', 'session', 'controller', 'proceed', 'progress', 'preflight', 'closure', 'query'].includes(group)) {
         console.error(`Unknown command: ${group}\n\n${USAGE}`);
         return 2;
     }
@@ -760,6 +774,9 @@ async function runParsedCommand(values, positionals, entry, argv) {
     // 새 대화가 붙었을 때 지금 상태를 되찾는다 (C-12 §4). 읽기만 한다.
     if (group === 'front')
         return runFront(command, values, store, root);
+    // 밖에 물은 것이 실제로 전달됐는가. 읽기만 한다.
+    if (group === 'coordination')
+        return runCoordination(command, values, store, root, guard.runtime);
     // 사람에게 올릴 자격이 있는가 (C-13). 자격 없으면 request가 만들어지지 않는다.
     if (group === 'escalate')
         return runEscalate(command, target, values, store, guard.runtime);
@@ -1929,11 +1946,23 @@ async function runProfile(command, values, root) {
 async function scmFor(resolved) {
     if (!resolved)
         return undefined;
+    const sources = resolved.layers.profile.canonical.sources;
+    // Profile 은 갈래마다 provider 를 적는다. `git` 이라고 적힌 것은 이 checkout 이 이미
+    // 들고 있는 사실이므로 원격 API 로 가지 않는다 — 갈 수 있다는 보장도 없다.
+    if (sources.length > 0 && sources.every((source) => source.provider === 'git')) {
+        const { root } = await discoverProjectRoot(process.cwd());
+        const refs = {};
+        for (const source of sources) {
+            if (source.ref)
+                refs[source.id] = { ref: source.ref, ...(source.remote ? { remote: source.remote } : {}) };
+        }
+        return new LocalCanonicalReader({ cwd: root, sourceRefs: refs });
+    }
     const token = await discoverToken();
     if (!token)
         return undefined;
     const sourceRefs = {};
-    for (const source of resolved.layers.profile.canonical.sources) {
+    for (const source of sources) {
         if (source.ref)
             sourceRefs[source.id] = { ref: source.ref };
     }
@@ -3095,6 +3124,25 @@ const CLOSURE_CHECKLIST = 'closureChecklist';
 /** Orchestration Audit (C-10). 회수 후에도 남는 기록이라 Progress와 다른 자리에 산다. */
 const auditLedger = (store) => new AuditLedger(store.scope('audit'));
 const closureLedger = (store) => new ClosureLedger(store.scope('closure'));
+/**
+ * 조율 증거 원장. Bounded Query 와 **다른 scope** 에 산다 — 기대와 증거는 다른 사실이고,
+ * 한 자리에 두면 "물어봤다"와 "전달됐다"가 다시 한 레코드가 된다.
+ */
+const coordinationLedger = (store) => new CoordinationLedger(store.scope('coordination'));
+/**
+ * 지금 이 workspace 의 조율 상태.
+ *
+ * 기대는 Bounded Query 에서 오고 증거는 원장에서 온다. **여기서 상태를 만들지 않는다** —
+ * 둘을 맞춰 파생할 뿐이다.
+ */
+async function coordinationNow(store, resolved) {
+    const queries = await queryLedger(store, resolved).list();
+    return viewCoordination(coordinationLedger(store), 
+    // 답이 이미 안에서 쓰인 질의는 조율 대상이 아니다 — 밖에 물을 이유가 끝났다.
+    queries
+        .filter((entry) => entry.answer === null)
+        .map((entry) => ({ id: entry.query.id, expectsResponse: entry.query.expectedResponse !== undefined })));
+}
 /** Bounded Query (B-25). 결정권 판정에 Profile 책임 지도가 필요하다. */
 const queryLedger = (store, resolved) => new QueryLedger(store.scope('query'), resolved?.ownership);
 /**
@@ -3521,8 +3569,24 @@ function serviceCommand(intervalSeconds) {
         program: process.execPath,
         args: [fileURLToPath(import.meta.url), 'runtime', 'tick', '--all'],
         intervalSeconds,
+        ...serviceEnvironment(),
+        logPath: join(ascHome(), 'service.log'),
     };
 }
+/**
+ * 서비스가 외부 통로를 열 수 있게 하는 환경 (P0-R1).
+ *
+ * 여기가 어떤 실행 파일이 필요한지 아는 자리다 — 조립 계층은 provider 를 안다. 지금 도는
+ * node 의 디렉터리를 맨 앞에 둬서 같은 node 의 npx 가 먼저 잡히게 한다. Windows 의 예약
+ * 작업은 사용자 환경을 그대로 물려받으므로 환경을 싣지 않는다.
+ */
+function serviceEnvironment() {
+    if (process.platform === 'win32')
+        return {};
+    const tools = [process.execPath, jamLauncher().command, 'glab', 'git'];
+    const { path } = servicePath(tools);
+    return { environment: { PATH: path } };
+}
 const serviceInterval = (values) => values['interval-min'] === undefined ? 5 * 60 : Math.max(60, Number(values['interval-min']) * 60);
 /**
  * `asc runtime service` — 이 기계의 지속 등록 (설계 §4).
@@ -3626,11 +3690,15 @@ async function tickAllWorkspaces(values, lease) {
         // 죽은 것으로 보이고 두 번째 프로세스가 끼어든다.
         await lease.renew();
     }
+    const skippedViews = skipped.map((view) => ({ workspaceId: view.workspaceId, health: view.health }));
+    const summary = summarizePass(results, skippedViews);
     if (values.json) {
         console.log(JSON.stringify({
             ran: results,
             // 건너뛴 것을 조용히 빼지 않는다 — "아무 일도 없었다"와 다른 사실이다
-            skipped: skipped.map((view) => ({ workspaceId: view.workspaceId, health: view.health })),
+            skipped: skippedViews,
+            outcome: summary.outcome,
+            failed: summary.failed,
         }, null, 2));
     }
     else {
@@ -3638,9 +3706,11 @@ async function tickAllWorkspaces(values, lease) {
             console.log(`${result.workspaceId}: pass exited ${result.code}`);
         for (const view of skipped)
             console.log(`${view.workspaceId}: ${view.health} — not observed this pass`);
+        console.log(summary.line);
     }
-    // 한 workspace 가 실패해도 회차 자체는 성공이다. 다음 회차가 다시 본다.
-    return 0;
+    // 한 workspace 가 실패해도 다른 workspace 는 전부 돌았다. 그러나 실패했다는 사실은 회차의
+    // 종료 코드에 남는다 — OS 가 보는 것은 그것 하나뿐이다 (P0-R2).
+    return summary.code;
 }
 /**
  * 상시 Runtime (C-12). 대화를 켜 두지 않고 **상태를 지속시키고 계산을 짧게 돌린다.**
@@ -4136,11 +4206,178 @@ async function runFrontOpen(values) {
                 escalations: await escalationLedger(store).pending(),
                 health: evaluateHealth(await new CoverageLedger(store.scope(scope)).health(), new Date().toISOString(), HEALTH_THRESHOLDS),
                 ...(workspace ? { workspace } : {}),
+                // 안에서 할 일이 없는 것과 밖에서 답이 안 온 것은 다른 사실이다
+                coordination: await coordinationNow(store),
                 bindings: claudeBindings(store),
             });
         },
     }));
 }
+/**
+ * 이 workspace 의 조율 표면. 없으면 없다고 말한다 — 아무 데나 대신 게시하지 않는다.
+ */
+async function coordinationSurfaceFor(resolved) {
+    const { root: projectRoot } = await discoverProjectRoot(process.cwd());
+    const adapters = monitorAdapters();
+    const declared = resolved?.layers.profile.bindings ?? [];
+    const plan = await composeBindings({
+        context: { projectRoot, env: process.env },
+        adapters,
+        roles: declared.map((b) => ({ adapterId: b.adapter, resource: b.resource, role: b.role })),
+    });
+    const ports = await buildRuntimePorts({
+        plan,
+        roles: rolesFor(plan, declared),
+        ...jamComposition(projectRoot),
+        endpointFor: (binding) => endpointOf(adapters, binding),
+    });
+    return { surface: ports.coordinationSurface, unavailable: ports.unavailable };
+}
+/**
+ * `asc coordination publish` — 기대 하나를 밖에 실제로 내보낸다.
+ *
+ * 본문을 파일로 받는 이유는 하나다: 사람이 읽을 글이 셸을 지나며 조용히 달라지는 것을
+ * 막는다. 그리고 **내부 메모가 섞일 자리를 주지 않는다** — 나가는 것은 제목·본문·라벨뿐이다.
+ */
+async function runCoordinationPublish(values, store, resolved) {
+    const queryId = typeof values.query === 'string' ? values.query : undefined;
+    const title = typeof values.title === 'string' ? values.title : undefined;
+    const bodyFile = typeof values['body-file'] === 'string' ? values['body-file'] : undefined;
+    if (!queryId || !title || !bodyFile) {
+        console.error('coordination publish needs --query, --title and --body-file\n\n' + USAGE);
+        return 2;
+    }
+    const { surface, unavailable } = await coordinationSurfaceFor(resolved);
+    if (!surface) {
+        console.error('No coordination surface is bound to this workspace — nothing was published.');
+        for (const line of unavailable)
+            console.error(`  ${line}`);
+        return 1;
+    }
+    const body = await readFile(bodyFile, 'utf8');
+    const audience = values.audience ?? [];
+    const known = (values.known ?? []).map((objectId) => ({
+        objectType: 'issue',
+        objectId,
+    }));
+    const workReference = typeof values.work === 'string' ? values.work : undefined;
+    const outcome = await publishOnce({
+        queryId,
+        publicPayload: { title, body },
+        ...(audience.length > 0 ? { audience } : {}),
+        ...(known.length > 0 ? { known } : {}),
+        ...(workReference ? { workReference } : {}),
+    }, { surface, bindingRole: 'coordination-surface' });
+    if (outcome.ok) {
+        const recorded = await recordPublication(coordinationLedger(store), outcome);
+        if (values.json) {
+            console.log(JSON.stringify({ publish: outcome, recorded: recorded.ok }, null, 2));
+            return 0;
+        }
+        console.log(publishLine(outcome));
+        // 이미 적힌 사실을 다시 적지 않는다. 그것은 실패가 아니라 같은 것을 두 번 안 세는 것이다.
+        console.log(recorded.ok ? 'recorded as communication evidence' : 'already recorded');
+        return 0;
+    }
+    if (values.json)
+        console.log(JSON.stringify({ publish: outcome }, null, 2));
+    else
+        console.error(publishLine(outcome));
+    return 1;
+}
+/**
+ * `asc coordination observe` — 게시한 것에 답이 왔는가.
+ *
+ * **답의 의미를 정하지 않는다.** 여기서 남는 것은 "밖에서 사람이 글을 남겼다"까지이고,
+ * 그것이 결정인지 승인인지는 다른 계약의 몫이다. 그 시스템이 스스로 남긴 자국과 우리가
+ * 쓴 글은 세지 않는다 — 그 둘을 세면 아무도 답하지 않은 스레드가 답이 온 것으로 보인다.
+ */
+async function runCoordinationObserve(values, store, root, resolved) {
+    const ledger = coordinationLedger(store);
+    const communications = await ledger.communications();
+    if (communications.length === 0) {
+        console.log('Nothing has been published from here yet.');
+        return 0;
+    }
+    const { root: projectRoot } = await discoverProjectRoot(process.cwd());
+    const adapters = monitorAdapters();
+    const declared = resolved?.layers.profile.bindings ?? [];
+    const plan = await composeBindings({
+        context: { projectRoot, env: process.env },
+        adapters,
+        roles: declared.map((b) => ({ adapterId: b.adapter, resource: b.resource, role: b.role })),
+    });
+    // **그 게시물을 만든 통로에게 묻는다.** 프로젝트 전체의 자원 조회를 하나 고르면
+    // 어느 것을 고를지 갈리고(실제로 갈렸다), 갈리지 않더라도 다른 시스템에게 남의 게시물을
+    // 묻게 된다. 증거에 적힌 adapter 가 곧 그 통로다.
+    const built = await buildObservationChannels({
+        plan,
+        roles: rolesFor(plan, declared),
+        ...jamComposition(projectRoot),
+        endpointFor: (binding) => endpointOf(adapters, binding),
+    });
+    const contextOf = (adapterId) => built.channels.find((channel) => channel.adapterId === adapterId && channel.resourceContext)?.resourceContext;
+    // 나를 나로 알아보는 곳은 identities.json 하나다. 채널 접두사를 떼면 계정 이름이 남는다.
+    const identity = await loadIdentityMap(root);
+    const mine = new Set();
+    for (const [name, accounts] of Object.entries(identity)) {
+        mine.add(name);
+        for (const account of accounts)
+            mine.add(account.includes(':') ? account.slice(account.indexOf(':') + 1) : account);
+    }
+    let added = 0;
+    let looked = 0;
+    for (const communication of communications) {
+        const context = contextOf(communication.identity.adapter);
+        if (!context) {
+            // 못 본 것을 "답이 없다"로 넘기지 않는다.
+            console.error(`  ${communication.identity.objectId}: ${communication.identity.adapter} 통로가 열리지 않아 보지 못했다`);
+            continue;
+        }
+        looked += 1;
+        const remarks = await context
+            .getComments(communication.identity.objectId, { limit: 100 })
+            .catch(() => []);
+        for (const response of responsesFrom(communication, remarks, mine)) {
+            const outcome = await ledger.responseRecorded(response);
+            if (outcome.ok)
+                added += 1;
+        }
+    }
+    const views = await coordinationNow(store, resolved);
+    if (values.json) {
+        console.log(JSON.stringify({ published: communications.length, observed: looked, recorded: added, coordination: views }, null, 2));
+        return 0;
+    }
+    console.log(`Looked at ${looked} of ${communications.length} published artefact(s) — ${added} new response(s).`);
+    for (const line of coordinationLines(views))
+        console.log(line);
+    return 0;
+}
+/**
+ * `asc coordination` — 밖에 물은 것이 실제로 나갔는가, 답이 왔는가.
+ *
+ * **읽기만 한다.** 이 화면이 상태를 만들지 않는다는 것이 요점이다 — 보이는 것은 전부
+ * 기대와 증거에서 파생한 값이다.
+ */
+async function runCoordination(command, values, store, root, resolved) {
+    if (command === 'publish')
+        return runCoordinationPublish(values, store, resolved);
+    if (command === 'observe')
+        return runCoordinationObserve(values, store, root, resolved);
+    if (command !== undefined && command !== 'status') {
+        console.error(`Unknown coordination command: ${command}\n\n${USAGE}`);
+        return 2;
+    }
+    const views = await coordinationNow(store, resolved);
+    if (values.json) {
+        console.log(JSON.stringify({ coordination: views }, null, 2));
+        return 0;
+    }
+    for (const line of coordinationLines(views))
+        console.log(line);
+    return 0;
+}
 async function runFront(command, values, store, root) {
     if (command !== undefined && command !== 'status') {
         console.error(`Unknown front command: ${command}
@@ -4158,6 +4395,7 @@ ${USAGE}`);
         escalations: await escalationLedger(store).pending(),
         health: evaluateHealth(await new CoverageLedger(store.scope(scope)).health(), new Date().toISOString(), HEALTH_THRESHOLDS),
         ...(located ? { workspace: { workspaceId: located.workspaceId, locator: located.locator } } : {}),
+        coordination: await coordinationNow(store),
         // 도는 세션을 누가 집고 있는지. --physical 을 다시 물어보게 하지 않는다 (L-4).
         bindings: claudeBindings(store),
     });

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[];
 };

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를 만든다.

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.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.4.0';
+export const RELEASE_VERSION = '0.5.0';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**