@asc-agent/runtime 0.1.0 → 0.2.1

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

@@ -0,0 +1,38 @@
+/** git이 부르는 이름과 URL. 이름을 버리지 않는 이유는 `origin` 을 알아보기 위해서다. */
+export type RemoteEntry = {
+    name: string;
+    url: string;
+};
+export type AdoptInput = {
+    /** 프로젝트 뿌리의 디렉터리 이름. remote가 없을 때 id와 repository의 근거가 된다. */
+    dirName: string;
+    remotes: readonly RemoteEntry[];
+    /** 사람이 `--id` 로 준 이름. 있으면 추론보다 앞선다. */
+    requestedId?: string;
+    /**
+     * 이 host를 어느 SCM 이름으로 적을 것인가. 모르면 `'git'` 이면 된다 — 그것이 사실이다.
+     * provider를 아는 쪽(조립부)이 넘긴다.
+     */
+    scmForHost?: (host: string) => string;
+};
+export type AdoptedProfile = {
+    id: string;
+    /** `ProjectProfile` 로 파싱되는 객체. 파일에 그대로 쓴다. */
+    profile: Record<string, unknown>;
+    /** 추론하지 못해 비워 둔 것. 숨기지 않고 사람에게 보인다. */
+    warnings: string[];
+};
+export declare class AdoptError extends Error {
+    readonly code: 'NO_USABLE_ID';
+    constructor(code: 'NO_USABLE_ID', message: string);
+}
+/**
+ * 이름 하나를 id 문법으로 깎는다. 못 깎으면 `null` — 조용히 아무 이름이나 만들지 않는다.
+ * `.` 과 `..` 은 문법은 통과하지만 디렉터리로서 뜻이 다르므로 여기서 뺀다.
+ */
+export declare function toProfileId(name: string): string | null;
+/**
+ * 이 저장소를 설명하는 최소 Profile. **파일을 읽지도 쓰지도 않는다** — 사실은 호출자가
+ * 관측해 넘기고, 여기서는 판단만 한다. 그래야 같은 판단을 테스트가 그대로 돌린다.
+ */
+export declare function buildAdoptedProfile(input: AdoptInput): AdoptedProfile;

package/dist/core/attach/adopt.js

@@ -0,0 +1,104 @@
+// 지금 이 저장소를 설명하는 Profile을 만든다 (P0 — Two-URL agent bootstrap).
+//
+// **왜 필요한가**: 배포본에는 예시 Profile 둘뿐이고 둘 다 실 프로젝트용이 아니다. URL만
+// 받은 agent는 `ASC_PROFILE_SELECTION_REQUIRED` 앞에서 고를 것이 없어 사람에게 되물었다.
+// 되물음을 없애려면 "고른다"가 아니라 "만든다"가 있어야 한다.
+//
+// **무엇을 만드는가 — 추론 가능한 최소치뿐이다.** git remote에서 읽히는 사실
+// (id · scm · repository)만 적는다. branch 정본·role 경계·정책은 이 저장소를 봐서
+// 알 수 없다. 모르는 것을 그럴듯하게 채우면 두 가지가 같이 무너진다:
+//
+//   canonical source를 지어내면  세션 발급이 그 정본을 실제로 읽으려 하고, 자격이 없는
+//                               기계에서 issue 자체가 실패한다 (session.ts §readBaselines)
+//   role 경계를 지어내면         지어낸 경계가 곧 사람이 겪는 SCOPE_ESCALATION이 된다 —
+//                               FAIL 회차에서 번들 Profile이 정확히 그렇게 막았다
+//
+// 그래서 adopt의 산출물은 **시작점**이다. 팀의 정책은 팀이 이 파일을 키워서 정한다.
+//
+// **provider 어휘는 여기 없다** (C-09 §6.1). 어느 host가 어느 provider인지는 Adapter를
+// 아는 쪽이 정하고, 여기서는 `scmForHost` 로 받는다 — core가 특정 provider 이름으로
+// 갈라지기 시작하면 그 다음 provider는 반드시 이 파일을 고쳐야 들어온다.
+import { normalizeRemote } from "../workspace/identity.js";
+export class AdoptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AdoptError';
+        this.code = code;
+    }
+}
+/** Profile id는 디렉터리 이름 한 칸이다 (profile-source.ts SAFE_ID와 같은 문법). */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * 이름 하나를 id 문법으로 깎는다. 못 깎으면 `null` — 조용히 아무 이름이나 만들지 않는다.
+ * `.` 과 `..` 은 문법은 통과하지만 디렉터리로서 뜻이 다르므로 여기서 뺀다.
+ */
+export function toProfileId(name) {
+    const cut = name
+        .trim()
+        .replace(/\.git$/, '')
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .replace(/-+$/, '');
+    if (!cut || cut === '.' || cut === '..' || !SAFE_ID.test(cut))
+        return null;
+    return cut;
+}
+/** `origin` 이 있으면 그것이다. 없으면 첫 번째 — 다만 그 사실을 경고로 남긴다. */
+function primaryRemote(remotes) {
+    return remotes.find((r) => r.name === 'origin') ?? remotes[0];
+}
+/**
+ * 이 저장소를 설명하는 최소 Profile. **파일을 읽지도 쓰지도 않는다** — 사실은 호출자가
+ * 관측해 넘기고, 여기서는 판단만 한다. 그래야 같은 판단을 테스트가 그대로 돌린다.
+ */
+export function buildAdoptedProfile(input) {
+    const warnings = [];
+    const remote = primaryRemote(input.remotes);
+    const distinctUrls = new Set(input.remotes.map((r) => r.url));
+    if (remote && remote.name !== 'origin' && distinctUrls.size > 1) {
+        warnings.push(`No 'origin' remote — used '${remote.name}' (${remote.url}) to identify this project.`);
+    }
+    // `host/group/project` 로 정규화된다. 자격·포트·질의는 여기 들어오지 않는다.
+    const alias = remote ? normalizeRemote(remote.url) : null;
+    const slash = alias?.indexOf('/') ?? -1;
+    const host = alias && slash > 0 ? alias.slice(0, slash) : null;
+    // repository는 host를 뺀 `owner/repo` 다 — Adapter가 API에 그대로 넘기는 형태가 그것이다.
+    const repository = alias && slash > 0 ? alias.slice(slash + 1) : null;
+    const id = input.requestedId ?? (repository ? toProfileId(repository.split('/').pop()) : null) ?? toProfileId(input.dirName);
+    if (id === null) {
+        throw new AdoptError('NO_USABLE_ID', `Could not make a profile id out of '${input.dirName}' — pass one with --id <name> (letters, digits, '.', '_', '-').`);
+    }
+    if (input.requestedId !== undefined && !SAFE_ID.test(input.requestedId)) {
+        throw new AdoptError('NO_USABLE_ID', `'${input.requestedId}' is not a profile id — use a single name made of letters, digits, '.', '_' or '-'.`);
+    }
+    if (!repository) {
+        warnings.push(remote
+            ? `Remote '${remote.url}' is not a shared repository address — this profile describes a local project.`
+            : 'This repository has no remote — this profile describes a local project.');
+    }
+    warnings.push('canonical.sources is empty: no branch is treated as the source of truth yet. Declare one before' +
+        ' relying on canonical verification.');
+    warnings.push('policy.roleScopes is empty: no role is narrowed yet. Declare scopes when the team agrees on them.');
+    return {
+        id,
+        warnings,
+        profile: {
+            schemaVersion: 1,
+            $comment: 'Adopted from this repository by `asc profile adopt`. It carries only what a git remote can prove —' +
+                ' the project identity. Canonical branches, role boundaries and policy are decisions this tool cannot' +
+                ' make for you: add them here as the team agrees on them.',
+            id,
+            project: {
+                // 공유 주소가 없으면 로컬 프로젝트다. 있으면 host를 아는 쪽이 이름을 준다.
+                scm: host === null ? 'local' : (input.scmForHost?.(host) ?? 'git'),
+                repository: repository ?? `local/${toProfileId(input.dirName) ?? id}`,
+            },
+            canonical: {
+                $comment: 'Empty means canonical verification does not apply. Add a source (id, provider, remote, ref) to' +
+                    ' have sessions check the project against a real baseline.',
+                sources: [],
+            },
+        },
+    };
+}

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

@@ -66,8 +66,13 @@ export type BootstrapPlan = {
 };
 export type BootstrapInput = {
     cwd: string;
-    /** ASC 설치 경로. `profiles/` 를 여기서 읽는다. */
+    /** ASC 설치 경로. 내장 `profiles/` 를 여기서 읽는다. */
     installRoot: string;
+    /**
+     * 사용자 소유 Profile 디렉터리(보통 `ASC_HOME/profiles`). **Surface가 정해서 넘긴다** —
+     * Core가 홈 경로를 스스로 알면 그 순간 저장소·사용자 공간의 경계를 Core가 쥐게 된다.
+     */
+    externalProfileRoot?: string;
     /**
      * 이 위치가 붙어 있다면 그 runtime 뿌리. **Surface가 정해서 넘긴다** — Core가 여기서
      * 다시 찾으면 저장소 안의 `.asc` 만 보게 되고, 그것이 기본이 아닌 지금은
@@ -94,8 +99,13 @@ export type BootstrapInput = {
     /** 정책 질문 자체를 생략할지. 계획만 보려는 호출용이다. */
     askPolicy?: boolean;
 };
-/** 설치 경로의 Profile 후보. 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다. */
-export declare function availableProfiles(installRoot: string): Promise<string[]>;
+/**
+ * 지금 고를 수 있는 Profile. 설치된 배포본 안과 **사용자 소유 공간** 둘 다 본다 —
+ * 팀이 나눠 갖는 실 Profile은 배포본에 들어가지 않으므로 후자가 없으면 후보가 없다.
+ *
+ * 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다.
+ */
+export declare function availableProfiles(installRoot: string, externalProfileRoot?: string): Promise<string[]>;
 /** 감지하고 계획을 세운다. 파일은 하나도 건드리지 않는다. */
 export declare function planBootstrap(input: BootstrapInput): Promise<BootstrapPlan>;
 /** 사람이 읽는 계획. 무엇이 정해지지 않았는지가 먼저 오도록 짠다. */

package/dist/core/attach/bootstrap.js

@@ -13,6 +13,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { availableCapabilities } from "../binding/types.js";
+import { listProfileLocations } from "../resolver/profile-source.js";
 import { discoverProjectRoot, exists } from "./init.js";
 /**
  * 정책은 사람이 정한다 (C-09 §7.1). adapter가 찾아 주는 것과 그것이 무슨 뜻인지 정하는 것은
@@ -25,22 +26,18 @@ export const POLICY_QUESTIONS = [
     { id: 'authority', question: 'decision authority는 누구인가' },
     { id: 'digest-channel', question: '기본 전달 채널은 무엇인가' },
 ];
-/** 설치 경로의 Profile 후보. 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다. */
-export async function availableProfiles(installRoot) {
-    try {
-        const entries = await readdir(join(installRoot, 'profiles'), { withFileTypes: true });
-        const ids = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            if (await exists(join(installRoot, 'profiles', entry.name, 'profile.json')))
-                ids.push(entry.name);
-        }
-        return ids.sort();
-    }
-    catch {
-        return [];
-    }
+/**
+ * 지금 고를 수 있는 Profile. 설치된 배포본 안과 **사용자 소유 공간** 둘 다 본다 —
+ * 팀이 나눠 갖는 실 Profile은 배포본에 들어가지 않으므로 후자가 없으면 후보가 없다.
+ *
+ * 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다.
+ */
+export async function availableProfiles(installRoot, externalProfileRoot) {
+    const found = await listProfileLocations({
+        installRoot,
+        ...(externalProfileRoot ? { externalRoot: externalProfileRoot } : {}),
+    });
+    return [...new Set(found.map((location) => location.id))].sort();
 }
 /** 붙어 있다면 무엇으로 붙었는가. lock을 읽지 못하면 붙이다 만 상태로 본다. */
 async function attachedProfile(ascRoot) {
@@ -58,7 +55,7 @@ export async function planBootstrap(input) {
     // 넘겨받은 것이 없을 때만 저장소 안을 본다 — 옛 경로를 계속 지원하되 기본으로 두지 않는다.
     const ascRoot = input.ascRoot ?? join(projectRoot, '.asc');
     const attached = await exists(ascRoot);
-    const candidates = await availableProfiles(input.installRoot);
+    const candidates = await availableProfiles(input.installRoot, input.externalProfileRoot);
     const hosts = [...(input.hosts ?? [])];
     const plan = input.bindings ?? { bindings: [] };
     const locked = attached ? await attachedProfile(ascRoot) : null;

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

@@ -1,6 +1,15 @@
 import type { StableInstallState } from '../distribution/runtime-install.ts';
 /** 세상의 스냅샷. 읽기만 해서 만든다. */
 export type SetupState = {
+    /**
+     * 이 판단이 **어느 실행물 안에서** 나오는가 (C-14 §3.4).
+     *
+     * `runtime` 이면 지금 도는 것이 곧 설치된 `asc` 다 — 그 사실은 관측할 것이 아니라
+     * 이미 아는 것이다. 예전에는 이 축이 없어 `stableRuntime` 의 부재를 "설치 안 됨"으로
+     * 읽었고, 그래서 설치된 `asc` 가 자기를 bootstrap이라고 말하며 agent에게 `npx …` 를
+     * 돌려줬다 (v0.2.0 registry 관측). 진입점 자체가 이미 답의 일부다.
+     */
+    entry: 'runtime' | 'bootstrap';
     projectRoot: string;
     git: boolean;
     /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */
@@ -67,7 +76,7 @@ export type SetupCode =
  * agent는 `portable` 만 실행하면 되고, 산문을 읽을 필요가 없다.
  */
 export type NextAction = {
-    type: 'select_profile' | 'install_runtime' | 'apply_setup' | 'proceed' | 'force_host_install';
+    type: 'select_profile' | 'adopt_profile' | 'install_runtime' | 'apply_setup' | 'proceed' | 'force_host_install';
     display: string;
     portable: string;
 };

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

@@ -22,11 +22,22 @@ export function computeSetupPlan(state) {
     ];
     // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
     // `asc …` 를 실행하라고 주면 안 된다 (C-14 §3.4 · 불변식 ⑯).
-    const mode = state.stableRuntime?.status === 'CURRENT' ? 'installed-runtime' : 'bootstrap';
-    const command = (args) => ({
-        display: shorthandCommand(args),
-        portable: mode === 'installed-runtime' ? shorthandCommand(args) : portableCommand(args),
-    });
+    //
+    // **진입점이 먼저다.** `asc` 로 들어왔다면 그 `asc` 는 이미 이 machine에 있다 — 그것을
+    // npm에게 물어볼 이유가 없다. bootstrap으로 들어왔을 때만 설치 축이 판정에 쓰인다.
+    const mode = state.entry === 'runtime' || state.stableRuntime?.status === 'CURRENT'
+        ? 'installed-runtime'
+        : 'bootstrap';
+    const command = (args) => {
+        // portable은 **agent가 그대로 실행하는 것**이므로 기계가 읽을 수 있는 형태로 끝나야
+        // 한다. `--json` 이 빠져 있으면 agent는 자기가 실행한 명령의 답을 산문으로 받는다 —
+        // "산문을 파싱하지 마라"고 적어 놓고 산문을 주는 꼴이었다. display는 사람 형태 그대로.
+        const machine = args.includes('--json') ? args : [...args, '--json'];
+        return {
+            display: shorthandCommand(args),
+            portable: mode === 'installed-runtime' ? shorthandCommand(machine) : portableCommand(machine),
+        };
+    };
     const changes = [];
     // stable runtime은 **프로젝트와도, profile 선택과도 무관하다.** 사람이 profile을
     // 고르는 중이어도 이 설치는 안전한 준비이고, 그것 때문에 통째로 WAIT 하지 않는다
@@ -66,6 +77,11 @@ export function computeSetupPlan(state) {
         }
     }
     if (state.ascRoot) {
+        // 붙어 있어도 **무엇을 고를 수 있었는지**는 사실이다. 사용자 소유 Profile을 새로 놓고
+        // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
+        if (state.profileCandidates.length > 0) {
+            evidence.push(`profile candidates=${state.profileCandidates.join(', ')}`);
+        }
         return finish(changes, evidence, state, mode, command);
     }
     // 아직 안 붙었다. 무엇으로 붙을지는 사람이 정한다.
@@ -78,9 +94,21 @@ export function computeSetupPlan(state) {
             changes,
             requiresUserAction: true,
             profiles: state.profileCandidates,
-            ...actions(mode, evidence, [
-                { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
-            ]),
+            // 고를 것이 **없을** 수도 있다 — 배포본이 들고 있는 것은 예시뿐이고, 이 프로젝트를
+            // 설명하는 Profile은 아직 아무도 만들지 않았다. 그때 "골라라"만 주면 막다른 길이
+            // 된다(FAIL 회차에서 agent가 사람에게 되물은 자리). 만드는 길을 함께 든다.
+            //
+            // 순서는 **지금 무엇이 실제로 길을 여는가**로 정한다. 첫 action이 늘 같으면
+            // agent는 첫 줄만 보고 막힌 길로 간다.
+            ...actions(mode, evidence, state.profileCandidates.length > 0
+                ? [
+                    { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
+                    { type: 'adopt_profile', ...command(['profile', 'adopt', '--json']) },
+                ]
+                : [
+                    { type: 'adopt_profile', ...command(['profile', 'adopt', '--json']) },
+                    { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
+                ]),
         };
     }
     if (state.scope === 'project') {

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

@@ -20,12 +20,22 @@ export type SetupGate = {
 };
 export type SetupStatus = {
     attachment: AttachmentState;
+    /** 지금 붙어 있는 Profile과 그 출처. 붙지 않았으면 없다. */
+    profile?: {
+        id: string;
+        origin: 'built-in' | 'external';
+    };
     /** 설정과 무관하게 지금 되는 것. */
     ready: string[];
     gates: SetupGate[];
 };
 export type SetupInput = {
     attachment: AttachmentState;
+    /** 붙어 있는 Profile의 id와 출처. **Surface가 읽어 넘긴다** — Core는 경로를 모른다. */
+    profile?: {
+        id: string;
+        origin: 'built-in' | 'external';
+    };
     /** 승인 권한자 매핑이 하나라도 있는가. */
     hasApprovers: boolean;
     /** override의 controller.identities가 채워졌는가. */

package/dist/core/attach/setup.js

@@ -26,6 +26,7 @@ const RESOLVE_AGAIN = 'after editing, re-lock with `asc profile resolve --write`
 export function assessSetup(input) {
     return {
         attachment: input.attachment,
+        ...(input.profile ? { profile: input.profile } : {}),
         ready: [...ALWAYS_READY],
         gates: [approvalGate(input), monitorGate(input), externalWriteGate(input)],
     };
@@ -116,6 +117,15 @@ export function renderSetup(status) {
         case 'READY':
             break;
     }
+    // 어떤 Profile로 도는지, 그리고 그것이 **어디서 왔는지**. 배포본에 딸려 온 예시로
+    // 실 프로젝트를 돌리고 있는 상태를 사람이 모르고 지나가지 않게 한다.
+    if (status.profile) {
+        const origin = status.profile.origin === 'external'
+            ? 'your own profile directory'
+            : 'bundled with the installed package';
+        lines.push(`profile: ${status.profile.id} — ${origin}`);
+        lines.push('');
+    }
     lines.push('Working now:');
     for (const item of status.ready)
         lines.push(`  ${item}`);

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

@@ -0,0 +1,44 @@
+import type { ProcessRunner } from './runtime-install.ts';
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export declare const MINIMUM_NODE_MAJOR = 24;
+export type NodeCandidate = {
+    path: string;
+    version: string;
+};
+export type NodeRuntimeCheck = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    code: 'NODE_RUNTIME_REQUIRED';
+    version: string;
+    detail: string;
+    /**
+     * 이 machine에서 찾은, 하한을 넘는 Node. **비어 있는 것이 실패가 아니다** —
+     * 그때는 Node를 놓는 일 자체가 사람의 경계다.
+     */
+    candidates: NodeCandidate[];
+};
+export type NodeRuntimeDeps = {
+    /** 지금 이 프로세스의 Node 버전 (`process.version` 형태: `v22.23.2`). */
+    version: string;
+    /** 후보 경로가 실제로 있는가. */
+    exists: (path: string) => boolean;
+    /** 디렉터리 목록. 없으면 빈 배열 — 없는 것은 오류가 아니다. */
+    list: (path: string) => string[];
+    /** `<node> -v` 를 돌린다. 실패는 후보 탈락일 뿐이다. */
+    run: ProcessRunner;
+    /** 사용자 홈. nvm 배치를 찾는 데만 쓴다. */
+    home: string;
+    /** 경로를 잇는다 — 호출자가 `node:path` 를 준다 (core는 파일시스템을 모른다). */
+    join: (...parts: string[]) => string;
+};
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export declare function majorOf(version: string): number | null;
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export declare function checkNodeRuntime(deps: NodeRuntimeDeps): Promise<NodeRuntimeCheck>;

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

@@ -0,0 +1,75 @@
+// 이 프로세스를 돌리고 있는 Node가 ASC를 돌릴 수 있는가 (C-14 §3).
+//
+// **왜 판정이 필요한가**: `engines` 는 npm에게 하는 말이고, npm은 기본값에서 그것을
+// 경고로만 낸다. 그래서 Node 22에서 설치하면 "무서운 경고 한 줄 → 그래도 돌아감"이 되고,
+// 사용자는 자기가 지원 범위 안에 있는지 알 수 없다. 지원 하한은 결정적으로 답해야 한다.
+//
+// **여기서 하지 않는 것**: Node를 설치하지 않고, PATH·shell 설정을 고치지 않으며,
+// version manager를 다루지 않는다. 이미 이 machine에 있는 것을 **best-effort로 찾아
+// 알려 줄** 뿐이다 — 못 찾는 것은 정상이고, 그때는 사람이 답할 일이다.
+import { RELEASE_VERSION } from "./release.js";
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export const MINIMUM_NODE_MAJOR = 24;
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export function majorOf(version) {
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 이미 있는 Node를 찾아본다. **탐색이지 관리가 아니다.**
+ *
+ * Homebrew와 nvm의 관례적 배치만 본다. 여기에 없다고 해서 Node가 없는 것은 아니고,
+ * 그 경우 후보 없이 돌려주는 것이 정직한 답이다 — 없는 것을 지어내지 않는다.
+ */
+function candidatePaths(deps) {
+    const found = [];
+    // Homebrew: /opt/homebrew/opt/node@26/bin/node · /usr/local/opt/node/bin/node
+    for (const prefix of ['/opt/homebrew/opt', '/usr/local/opt']) {
+        for (const entry of deps.list(prefix)) {
+            if (!/^node(@\d+)?$/.test(entry))
+                continue;
+            const path = deps.join(prefix, entry, 'bin', 'node');
+            if (deps.exists(path))
+                found.push(path);
+        }
+    }
+    // nvm: ~/.nvm/versions/node/v24.1.0/bin/node
+    const nvm = deps.join(deps.home, '.nvm', 'versions', 'node');
+    for (const entry of deps.list(nvm)) {
+        const path = deps.join(nvm, entry, 'bin', 'node');
+        if (deps.exists(path))
+            found.push(path);
+    }
+    return [...new Set(found)];
+}
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export async function checkNodeRuntime(deps) {
+    const major = majorOf(deps.version);
+    if (major !== null && major >= MINIMUM_NODE_MAJOR)
+        return { ok: true, version: deps.version };
+    const candidates = [];
+    for (const path of candidatePaths(deps)) {
+        const probed = await deps.run(path, ['-v']);
+        if (!probed.ok)
+            continue;
+        const version = probed.stdout.trim().split(/\r?\n/)[0] ?? '';
+        const found = majorOf(version);
+        if (found !== null && found >= MINIMUM_NODE_MAJOR)
+            candidates.push({ path, version });
+    }
+    return {
+        ok: false,
+        code: 'NODE_RUNTIME_REQUIRED',
+        version: deps.version,
+        detail: `ASC ${RELEASE_VERSION} needs Node ${MINIMUM_NODE_MAJOR} or newer; this process is ${deps.version}.` +
+            (candidates.length > 0
+                ? ' A newer Node is already on this machine — use it for the same command.'
+                : ' No newer Node was found in the usual places. Installing one is yours to do.'),
+        candidates,
+    };
+}

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.1.0";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.1.0";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.1.0";
+export declare const RELEASE_VERSION = "0.2.1";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.2.1";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.2.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.1.0';
+export const RELEASE_VERSION = '0.2.1';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**

package/dist/core/monitor/observation.d.ts

@@ -25,16 +25,16 @@ export declare const Observation: z.ZodObject<{
     reference: string;
     disposition: "INBOX" | "SHADOW";
     evidence: string[];
+    lastSeenAt: string;
     revisionMarker: string;
     firstSeenAt: string;
-    lastSeenAt: string;
     reason?: string | undefined;
 }, {
     reference: string;
     disposition: "INBOX" | "SHADOW";
+    lastSeenAt: string;
     revisionMarker: string;
     firstSeenAt: string;
-    lastSeenAt: string;
     evidence?: string[] | undefined;
     reason?: string | undefined;
 }>;

package/dist/core/resolver/load.d.ts

@@ -1,10 +1,13 @@
 import { OperationalPreset, ProfileLock, ProjectProfile, UserOverride } from '../../schemas/profile.ts';
 import type { MonitorConfig } from '../monitor/signals.ts';
 import type { OwnershipMap } from '../policy/ownership.ts';
+import { type ProfileOrigin } from './profile-source.ts';
 import { type ConfigLayer, type ResolvedProfile } from './resolve.ts';
 export type LoadedLayers = {
     profile: ProjectProfile;
     profileSource: string;
+    /** 그 Profile이 어디서 왔는가 — 배포본 안인가, 사용자 소유 공간인가. */
+    profileOrigin: ProfileOrigin;
     preset?: OperationalPreset;
     presetSource?: string;
     override?: UserOverride;
@@ -23,12 +26,18 @@ export type ResolvedRuntime = {
 };
 export declare const digest: (value: unknown) => string;
 /**
- * 설치 경로에서 Profile과 Preset을, 프로젝트에서 Override를 읽는다.
+ * Profile과 Preset을 읽고, 프로젝트에서 Override를 읽는다.
  * Override가 없는 것은 정상이다 — 팀 설정만으로도 돌아가야 한다.
+ *
+ * Profile은 설치 경로 안일 수도, 사용자 소유 공간일 수도 있다. **어디서 고를지는
+ * 여기서 정하지 않는다** — profile-source.ts가 정하고 여기는 그 결과를 읽는다.
+ * Preset은 아직 배포본 안에만 있다(팀이 나눠 갖는 것은 Profile 쪽이다).
  */
 export declare function loadLayers(input: {
     installRoot: string;
     profileId: string;
+    /** 사용자 소유 Profile 디렉터리. 보통 `ASC_HOME/profiles`. */
+    externalProfileRoot?: string;
     presetId?: string;
     overridePath?: string;
 }): Promise<LoadedLayers>;
@@ -113,6 +122,8 @@ export type BootstrapOutcome = {
 export declare function bootstrapGuard(input: {
     ascRoot: string;
     installRoot: string;
+    /** 사용자 소유 Profile 디렉터리. 붙을 때 쓴 것과 같은 자리를 봐야 한다. */
+    externalProfileRoot?: string;
     profileId?: string;
     presetId?: string;
     capabilities: readonly string[];

package/dist/core/resolver/load.js

@@ -13,6 +13,7 @@ import { constants } from 'node:fs';
 import { access, mkdir, readFile, rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { OperationalPreset, ProfileLock, ProjectProfile, UserOverride } from "../../schemas/profile.js";
+import { ProfileSourceError, resolveProfileLocation } from "./profile-source.js";
 import { resolveProfile } from "./resolve.js";
 import { satisfies } from "./version.js";
 async function pathExists(path) {
@@ -29,12 +30,30 @@ async function readJson(path) {
     return JSON.parse(await readFile(path, 'utf8'));
 }
 /**
- * 설치 경로에서 Profile과 Preset을, 프로젝트에서 Override를 읽는다.
+ * Profile과 Preset을 읽고, 프로젝트에서 Override를 읽는다.
  * Override가 없는 것은 정상이다 — 팀 설정만으로도 돌아가야 한다.
+ *
+ * Profile은 설치 경로 안일 수도, 사용자 소유 공간일 수도 있다. **어디서 고를지는
+ * 여기서 정하지 않는다** — profile-source.ts가 정하고 여기는 그 결과를 읽는다.
+ * Preset은 아직 배포본 안에만 있다(팀이 나눠 갖는 것은 Profile 쪽이다).
  */
 export async function loadLayers(input) {
-    const profileSource = join(input.installRoot, 'profiles', input.profileId, 'profile.json');
+    const location = await resolveProfileLocation(input.profileId, {
+        installRoot: input.installRoot,
+        ...(input.externalProfileRoot ? { externalRoot: input.externalProfileRoot } : {}),
+    });
+    const profileSource = location.path;
     const profile = ProjectProfile.parse(await readJson(profileSource));
+    // 디렉터리 이름과 선언된 id가 다르면 여기서 멈춘다.
+    //
+    // 둘이 다르면 lock에는 **선언된 id**가 박히고 다음 실행은 그 id로 파일을 찾는다 —
+    // 그런 디렉터리는 없으므로 붙자마자 아무 명령도 돌지 않는 workspace가 된다.
+    // 독립 검증이 실물로 보인 결함이고, 되돌리려면 `.asc/` 를 손으로 지워야 했다.
+    if (profile.id !== input.profileId) {
+        throw new ProfileSourceError('PROFILE_ID_MISMATCH', `${profileSource} declares id '${profile.id}' but lives in a directory named ` +
+            `'${input.profileId}'. Make the two the same — everything after this point looks ` +
+            'the profile up by the id it declares.');
+    }
     let preset;
     let presetSource;
     if (input.presetId) {
@@ -54,6 +73,7 @@ export async function loadLayers(input) {
     return {
         profile,
         profileSource,
+        profileOrigin: location.origin,
         ...(preset ? { preset } : {}),
         ...(presetSource ? { presetSource } : {}),
         ...(override ? { override } : {}),
@@ -220,6 +240,7 @@ export async function bootstrapGuard(input) {
     const locked = ProfileLock.parse(JSON.parse(lockedRaw));
     const layers = await loadLayers({
         installRoot: input.installRoot,
+        ...(input.externalProfileRoot ? { externalProfileRoot: input.externalProfileRoot } : {}),
         profileId: input.profileId ?? locked.profile.id,
         ...(input.presetId ?? locked.preset?.id ? { presetId: input.presetId ?? locked.preset.id } : {}),
         overridePath: join(input.ascRoot, 'override.json'),