@asc-agent/runtime 0.1.0 → 0.2.1

package/dist/cli/asc.js

@@ -8,11 +8,12 @@
 // 읽기 전용이다. 결정 제출은 사람의 명시적 의사표현을 받는 별도 경로로 나간다 (B-06).
 import { execFile, spawnSync } from 'node:child_process';
 import { parseArgs, promisify } from 'node:util';
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
+import { MINIMUM_NODE_MAJOR, checkNodeRuntime, } from "../core/distribution/node-runtime.js";
 import { GitHubClient, discoverToken } from "../adapters/github/client.js";
 import { GitHubChangeContext, GitHubInventory, GitHubResourceContext } from "../adapters/github/context.js";
 import { GitHubEventSource } from "../adapters/github/event-source.js";
@@ -25,6 +26,7 @@ import { Executor } from "../core/execution/executor.js";
 import { GrantService } from "../core/execution/grant.js";
 import { DecisionKind } from "../core/model/entities.js";
 import { discoverProjectRoot, excludeFromGit, identitiesTemplate, overrideTemplate, writeIfAbsent } from "../core/attach/init.js";
+import { AdoptError, buildAdoptedProfile } from "../core/attach/adopt.js";
 import { locatorsOf, lookupLocator, readIndex, register, writeIndex } from "../core/workspace/index-store.js";
 import { adoptionLine, judgeAdoption, migrate } from "../core/workspace/migrate.js";
 import { newWorkspaceId, normalizeRemote, recoverCandidates, recoverLines } from "../core/workspace/identity.js";
@@ -47,6 +49,7 @@ import { buildEventObservation } from "../composition/observe.js";
 import { availableProfiles, planBootstrap, renderPlan } from "../core/attach/bootstrap.js";
 import { detectStableInstall, installStableRuntime, verifyStableInstall, } from "../core/distribution/runtime-install.js";
 import { readRuntimeSelection, remediationAction, remediationLines, resolveRuntimeTarget, runtimeSelectionLine, selectionPath, writeRuntimeSelection, } from "../core/distribution/runtime-select.js";
+import { portableCommand, shorthandCommand } from "../core/distribution/release.js";
 import { preflight } from "../core/operator/preflight.js";
 import { lookupAuthority } from "../core/policy/ownership.js";
 import { renderProgress } from "../core/operator/render.js";
@@ -66,137 +69,139 @@ import { FreezeLedger, freezeLines, judgeAction } from "../core/policy/remote-fr
 import { SessionRuntime } from "../core/runtime/session.js";
 import { Checkpoint, Handoff, SessionRole } from "../core/model/entities.js";
 import { archiveLock, bootstrapGuard, buildLock, compareLock, loadLayers, resolveRuntime } from "../core/resolver/load.js";
+import { ProfileSourceError } from "../core/resolver/profile-source.js";
 import { renderAscMd, renderControllerMd } from "../core/resolver/render.js";
-import { ProfileLock } from "../schemas/profile.js";
+import { ProfileLock, ProjectProfile } from "../schemas/profile.js";
 import { LocalOperator } from "../core/operator/local-operator.js";
 import { loadIdentityMap } from "./identity-config.js";
-const USAGE = `asc — Agent Session Control
-
-  asc proceed [--session <id>] [--goal <text>] [--json]
-
-  asc inbox list   [--all] [--priority P0|P1|P2] [--json]
-  asc inbox show   <REQUEST_ID> [--json]
-  asc inbox trace  <REQUEST_ID> [--json]   # how it got here — an exploratory trace
-  asc inbox digest [--flush] [--json]      # batched view (P0 stays separate)
-  asc inbox latest [--priority P0|P1|P2] [--json]
-  asc inbox decide <REQUEST_ID> <approve|revise|defer|dismiss|queue> --as <actor>
-                   [--revision <text>] [--expect <version>]
-
-  asc grant issue <REQUEST_ID> --action <key> --target <ref> --as <actor>
-                  [--grant-id <id>] [--expires <iso>]
-  asc grant run   <GRANT_ID> [--run-id <id>]
-
-  asc monitor scan      [--backfill] [--as <controller>]   # fast path
-  asc monitor reconcile [--as <controller>]   # recover what was missed — re-list
-  asc monitor census    [--as <controller>]   # full reconcile + detect disappearances
-  asc monitor status    [--json]              # how far coverage has been confirmed
-
-  asc profile resolve --profile <id> [--preset <id>] [--install <path>] [--write]
-
-  asc runtime start [--interval-min <n>] [--delta-min <n>] [--reconcile-min <n>]
-                    [--census-min <n>] [--digest-min <n>]
-  asc runtime tick
-  asc runtime status [--json]              # which build is in use (C-14 §4)
-  asc runtime use package
-  asc runtime use development <checkout>   # run a built checkout instead
-  asc front [status] [--json]
-  asc escalate open <S-ID> --predicate <p>... --question <t> --blocked <node>...
-                           --evidence <ref>... [--blocked-scope <path>...] [--previous <ESC-ID> --why <t>]
-  asc escalate list
-  asc escalate resolve <ESC-ID>
-  asc freeze [status]
-  asc freeze on --reason <text> [--offline]
-  asc freeze defer --id <id> --intent <text> [--evidence <ref>]
-  asc freeze release --id <id>
-  asc thaw
-  asc workspace list
-  asc workspace migrate [--force]
-  asc init [--profile <id>] [--preset <id>] [--install <path>]
-           [--scope local|project] [--workspace <W-id>]
-                        # without --profile: report what was detected, then stop
-
-  asc setup status [--json]
-  asc setup plan   [--profile <id>] [--scope local|project] [--json]
-                        # says what it would change — changes nothing
-  asc setup apply  [--profile <id>] [--scope local|project] [--json]
-  asc setup --agent     # non-interactive apply. stdout is a single JSON document
-
-  asc session issue <ID> --role <role> --goal <text> [--block <id>]
-                         [--parent <S-ID>] [--issued-by <principal>]
-  asc session pause  <S-ID> --position <t> --next <t> [--physical <id>]
-                            [--judgment <t>] [--blocker <t>] [--risk <t>] [--evidence <ref>]
-  asc session validate <target S-ID> --validator <validator S-ID> --result PASS|FAIL [--finding <t>]
-  asc session audit  <S-ID>
-  asc session report <S-ID> [--json]
-  asc session decision <S-ID> --class <c> --selected <t> --why <t>... --evidence <ref>...
-                              [--alternative <t>...] [--ownership <scope>...] [--verification <t>...]
-                        [--boundary <glob>...] [--exception <item>...]
-                        [--criteria <text>...] [--owner <role>]
-                        [--domain <decision-domain>...] [--authority <domain>=<role>...]
-                        [--dependency <text>...]
-  asc session start  <ID>
-  asc session pause  <ID> --position <text> --next <text> [--done <task>...]
-  asc session resume <ID>
-  asc session done   <ID> --verified <text> --next <text> [--done <task>...]
-                        [--changed <path>...] [--unresolved <text>...]
-  asc session list
-
-  asc controller collect
-
-  asc closure list    [<S-ID>]
-  asc closure confirm <S-ID> --item <id>...
-
-  asc preflight --path <p>... (--role <r> | --session <S-ID>) [--json]
-
-  asc query open   <X-ID> --session <S-ID> --domain <decision-domain>
-                        --question <text> [--context <text>] [--default <text>]
-                        [--blocking <text>] [--expect-response DECIDE|ANSWER]
-                        [--in-reply-to <X-ID>]
-  asc query answer <X-ID> --kind DECIDE|ANSWER|ESCALATE --by <role> --body <text>
-                        [--to <authority>]
-  asc query list   [--json]
-
-  asc progress show   [<S-ID>]
-  asc progress report <S-ID> --physical <id> --phase <text>
-                      [--milestone <text>...] [--next <text>] [--unresolved <text>...]
-                      [--decision none|later|now] [--decision-ref <text>]
-                      [--verifier none|running|pass|fail] [--verifier-detail <text>] [--terminal]
-
-  asc host claude install [--force]     # --force: overwrite ASC files a person has edited
-  asc host claude uninstall|probe [--report <cap>=<bool>...]
-  asc host claude guard
-  asc host claude bind <S-ID> --physical <id> [--principal <p>] [--worker <id>] [--kind <k>] [--force]
-  asc host claude release <S-ID> --physical <id>
-  asc host claude contract <S-ID>
-
-Options
-  --root <path>   runtime directory (otherwise: registered workspace, then repo-local .asc)
-  --json          machine-readable output
-  --as <actor>    who is deciding. Must be mapped as an approver
-  --revision      what was changed, when approving with revisions
-  --expect        the version you read. Rejected if it changed since
-  --action        action key to emit (e.g. github.issue_comment.create)
-  --target        target reference (e.g. owner/repo#19)
-  --backfill      sweep history on the first run (default: from now on)
-  --profile       Project Profile id
-  --preset        Operational Preset id
-  --install       ASC installation path (default: where this CLI lives)
-  --write         actually write the artefacts (default: preview)
-  --role          planner|researcher|implementer|verifier
-  --goal          the single goal of this session
-  --boundary      write scope (must be narrower than the Profile's)
-  --exception     SOFT DENY item allowed for this session only
-  --criteria      a verifiable done-criterion (repeatable)
-  --path          output path to check (preflight, repeatable)
-  --item          confirmed closure item id (closure confirm, repeatable)
-  --phase         one line on what is happening right now (progress report)
-  --milestone     a meaningfully finished chunk (repeatable)
-  --decision      does a person need to decide: none|later|now
-  --verifier      independent verification state: none|running|pass|fail
-  --terminal      final report — stays as the closing screen after collect
-
-decide assumes a person is operating it, and only checks that the name given with --as
-is registered as an approver. Approval is not permission to publish: anything reaching an
+const USAGE = `asc — Agent Session Control
+
+  asc proceed [--session <id>] [--goal <text>] [--json]
+
+  asc inbox list   [--all] [--priority P0|P1|P2] [--json]
+  asc inbox show   <REQUEST_ID> [--json]
+  asc inbox trace  <REQUEST_ID> [--json]   # how it got here — an exploratory trace
+  asc inbox digest [--flush] [--json]      # batched view (P0 stays separate)
+  asc inbox latest [--priority P0|P1|P2] [--json]
+  asc inbox decide <REQUEST_ID> <approve|revise|defer|dismiss|queue> --as <actor>
+                   [--revision <text>] [--expect <version>]
+
+  asc grant issue <REQUEST_ID> --action <key> --target <ref> --as <actor>
+                  [--grant-id <id>] [--expires <iso>]
+  asc grant run   <GRANT_ID> [--run-id <id>]
+
+  asc monitor scan      [--backfill] [--as <controller>]   # fast path
+  asc monitor reconcile [--as <controller>]   # recover what was missed — re-list
+  asc monitor census    [--as <controller>]   # full reconcile + detect disappearances
+  asc monitor status    [--json]              # how far coverage has been confirmed
+
+  asc profile adopt   [--id <name>] [--json]  # make a profile for this repository
+  asc profile resolve --profile <id> [--preset <id>] [--install <path>] [--write]
+
+  asc runtime start [--interval-min <n>] [--delta-min <n>] [--reconcile-min <n>]
+                    [--census-min <n>] [--digest-min <n>]
+  asc runtime tick
+  asc runtime status [--json]              # which build is in use (C-14 §4)
+  asc runtime use package
+  asc runtime use development <checkout>   # run a built checkout instead
+  asc front [status] [--json]
+  asc escalate open <S-ID> --predicate <p>... --question <t> --blocked <node>...
+                           --evidence <ref>... [--blocked-scope <path>...] [--previous <ESC-ID> --why <t>]
+  asc escalate list
+  asc escalate resolve <ESC-ID>
+  asc freeze [status]
+  asc freeze on --reason <text> [--offline]
+  asc freeze defer --id <id> --intent <text> [--evidence <ref>]
+  asc freeze release --id <id>
+  asc thaw
+  asc workspace list
+  asc workspace migrate [--force]
+  asc init [--profile <id>] [--preset <id>] [--install <path>]
+           [--scope local|project] [--workspace <W-id>]
+                        # without --profile: report what was detected, then stop
+
+  asc setup status [--json]
+  asc setup plan   [--profile <id>] [--scope local|project] [--json]
+                        # says what it would change — changes nothing
+  asc setup apply  [--profile <id>] [--scope local|project] [--json]
+  asc setup apply --json   # non-interactive apply. stdout is a single JSON document
+
+  asc session issue <ID> --role <role> --goal <text> [--block <id>]
+                         [--parent <S-ID>] [--issued-by <principal>]
+  asc session pause  <S-ID> --position <t> --next <t> [--physical <id>]
+                            [--judgment <t>] [--blocker <t>] [--risk <t>] [--evidence <ref>]
+  asc session validate <target S-ID> --validator <validator S-ID> --result PASS|FAIL [--finding <t>]
+  asc session audit  <S-ID>
+  asc session report <S-ID> [--json]
+  asc session decision <S-ID> --class <c> --selected <t> --why <t>... --evidence <ref>...
+                              [--alternative <t>...] [--ownership <scope>...] [--verification <t>...]
+                        [--boundary <glob>...] [--exception <item>...]
+                        [--criteria <text>...] [--owner <role>]
+                        [--domain <decision-domain>...] [--authority <domain>=<role>...]
+                        [--dependency <text>...]
+  asc session start  <ID>
+  asc session pause  <ID> --position <text> --next <text> [--done <task>...]
+  asc session resume <ID>
+  asc session done   <ID> --verified <text> --next <text> [--done <task>...]
+                        [--changed <path>...] [--unresolved <text>...]
+  asc session list
+
+  asc controller collect
+
+  asc closure list    [<S-ID>]
+  asc closure confirm <S-ID> --item <id>...
+
+  asc preflight --path <p>... (--role <r> | --session <S-ID>) [--json]
+
+  asc query open   <X-ID> --session <S-ID> --domain <decision-domain>
+                        --question <text> [--context <text>] [--default <text>]
+                        [--blocking <text>] [--expect-response DECIDE|ANSWER]
+                        [--in-reply-to <X-ID>]
+  asc query answer <X-ID> --kind DECIDE|ANSWER|ESCALATE --by <role> --body <text>
+                        [--to <authority>]
+  asc query list   [--json]
+
+  asc progress show   [<S-ID>]
+  asc progress report <S-ID> --physical <id> --phase <text>
+                      [--milestone <text>...] [--next <text>] [--unresolved <text>...]
+                      [--decision none|later|now] [--decision-ref <text>]
+                      [--verifier none|running|pass|fail] [--verifier-detail <text>] [--terminal]
+
+  asc host claude install [--force]     # --force: overwrite ASC files a person has edited
+  asc host claude uninstall|probe [--report <cap>=<bool>...]
+  asc host claude guard
+  asc host claude bind <S-ID> --physical <id> [--principal <p>] [--worker <id>] [--kind <k>] [--force]
+  asc host claude release <S-ID> --physical <id>
+  asc host claude contract <S-ID>
+
+Options
+  --root <path>   runtime directory (otherwise: registered workspace, then repo-local .asc)
+  --json          machine-readable output
+  --as <actor>    who is deciding. Must be mapped as an approver
+  --revision      what was changed, when approving with revisions
+  --expect        the version you read. Rejected if it changed since
+  --action        action key to emit (e.g. github.issue_comment.create)
+  --target        target reference (e.g. owner/repo#19)
+  --backfill      sweep history on the first run (default: from now on)
+  --profile       Project Profile id
+  --preset        Operational Preset id
+  --install       ASC installation path (default: where this CLI lives)
+  --write         actually write the artefacts (default: preview)
+  --role          planner|researcher|implementer|verifier
+  --goal          the single goal of this session
+  --boundary      write scope (must be narrower than the Profile's)
+  --exception     SOFT DENY item allowed for this session only
+  --criteria      a verifiable done-criterion (repeatable)
+  --path          output path to check (preflight, repeatable)
+  --item          confirmed closure item id (closure confirm, repeatable)
+  --phase         one line on what is happening right now (progress report)
+  --milestone     a meaningfully finished chunk (repeatable)
+  --decision      does a person need to decide: none|later|now
+  --verifier      independent verification state: none|running|pass|fail
+  --terminal      final report — stays as the closing screen after collect
+
+decide assumes a person is operating it, and only checks that the name given with --as
+is registered as an approver. Approval is not permission to publish: anything reaching an
 external system goes out through a separate Execution Grant.`;
 /**
  * 지금 여기가 어느 ASC runtime인가. **모든 명령이 같은 문을 지난다** (C-11 §3, B-45).
@@ -293,6 +298,12 @@ const DECISION_ERROR = {
     ALREADY_DECIDED: '이미 결정된 요청이다.',
     STALE: '읽은 뒤 요청이 바뀌었다. 다시 확인하고 결정하라.',
 };
+/**
+ * bootstrap이 자기 USAGE에 적을 값. **거기서 손으로 적지 않게 하려고 내보낸다** —
+ * 두 패키지가 각자 버전 문자열을 들면 릴리스마다 한쪽이 뒤처지고, 그 지연은 곧
+ * 사용자가 실행하는 명령이 된다 (0.2.0 회차의 skill.ts가 그랬다).
+ */
+export { BOOTSTRAP_SPEC } from "../core/distribution/release.js";
 /**
  * CLI 한 번의 실행. **다른 진입도 이 함수를 부른다** (C-14 불변식 ①).
  *
@@ -300,6 +311,82 @@ const DECISION_ERROR = {
  * 진입이 둘이어도 판단은 하나다. 그래서 export이고, 그래서 아래 자동 실행은 이 파일이
  * 진짜 진입점일 때만 돈다.
  */
+/**
+ * 설정을 읽다 실패한 것을 **사람이 읽을 문장**으로 바꾼다.
+ *
+ * 여기가 없으면 Profile 하나가 잘못됐을 때 사용자가 보는 것은 Node의 stack dump다 —
+ * 내부 파일 이름과 프레임이 줄줄이 나오고, 정작 "무엇을 고쳐야 하는지"는 없다.
+ * 독립 검증이 다섯 갈래(충돌·깨진 JSON·디렉터리가 아닌 것·EISDIR·긴 id)에서 같은 모양을
+ * 관측했다. 예상 못 한 오류는 그대로 던진다 — 삼키면 그게 더 나쁘다.
+ */
+function explainConfigError(error) {
+    if (error instanceof ProfileSourceError)
+        return error.message;
+    const failure = error;
+    const path = failure?.path ? ` (${failure.path})` : '';
+    switch (failure?.code) {
+        case 'ENOENT':
+            return `That profile is not there${path}. \`asc setup status\` lists what is.`;
+        case 'EISDIR':
+            return `A profile has to be a file, and that is a directory${path}.`;
+        case 'EACCES':
+        case 'EPERM':
+            return `No permission to read that profile${path}.`;
+        default:
+            break;
+    }
+    if (error instanceof SyntaxError)
+        return `That profile is not valid JSON — ${error.message}`;
+    return null;
+}
+/** 실제 파일시스템·프로세스를 물린다. Core는 이 중 아무것도 직접 하지 않는다. */
+function nodeRuntimeDeps() {
+    return {
+        version: process.version,
+        exists: (path) => existsSync(path),
+        list: (path) => {
+            try {
+                return readdirSync(path);
+            }
+            catch {
+                // 없는 디렉터리는 "후보 없음"이다. 이 machine에 그 배치가 없을 뿐이다.
+                return [];
+            }
+        },
+        run: nodeProcessRunner,
+        home: homedir(),
+        join,
+    };
+}
+/**
+ * 못 돌린다는 사실과, 이 machine에서 실제로 쓸 수 있는 것을 함께 준다.
+ *
+ * 후보가 있으면 **같은 canonical 명령을 그 Node로 돌리는 형태**를 낸다 — 이것은 per-invocation
+ * 환경변수이지 PATH·profile 수정이 아니다 (불변식 ⑰). 이 형태마저 host가 실행을 거부하면
+ * 그때는 ASC의 문제가 아니라 host 경계이며, AGENTS.md가 그 자리를 정의한다.
+ */
+function reportNodeRuntime(check, asJson) {
+    const actions = check.candidates.map((candidate) => ({
+        type: 'use_node_runtime',
+        display: `PATH="${dirname(candidate.path)}:$PATH" ${shorthandCommand(['setup', 'apply', '--json'])}`,
+        portable: `PATH="${dirname(candidate.path)}:$PATH" ${portableCommand(['setup', 'apply', '--json'])}`,
+        node: candidate,
+    }));
+    if (asJson) {
+        console.log(JSON.stringify({
+            code: check.code,
+            detail: check.detail,
+            runtime: { node: process.execPath, version: check.version, required: `>=${MINIMUM_NODE_MAJOR}` },
+            candidates: check.candidates,
+            nextActions: actions.map((action) => action.portable),
+            actions,
+        }, null, 2));
+        return;
+    }
+    console.error(check.detail);
+    for (const action of actions)
+        console.error(`  ${action.node.version} at ${action.node.path}\n    ${action.display}`);
+}
 export async function runAscCommand(argv, entry = 'runtime') {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -405,6 +492,17 @@ export async function runAscCommand(argv, entry = 'runtime') {
         console.log(USAGE);
         return 0;
     }
+    // **지원 하한을 먼저 답한다** (C-14 §3). `engines` 는 npm에게 하는 말이라 기본값에서
+    // 경고로만 나가고, 그러면 "경고 뒤에 그래도 돌아감"이 된다 — 사용자는 자기가 지원
+    // 범위 안인지 끝내 모른다. 여기서 한 번, 결정적으로 답한다.
+    //
+    // 이 자리인 이유: 설치된 `asc` 와 bootstrap이 **같은 문으로 들어온다**. bootstrap에
+    // 두면 그쪽에 정책이 생기고(C-14 불변식 ⑦), 그러면 두 진입의 답이 갈릴 수 있다.
+    const runnable = await checkNodeRuntime(nodeRuntimeDeps());
+    if (!runnable.ok) {
+        reportNodeRuntime(runnable, Boolean(values.json) || Boolean(values.agent));
+        return 1;
+    }
     // 선택된 build로 넘길 것이 있으면 여기서 넘긴다. **선택 자체를 다루는 명령은 넘기지
     // 않는다** — 잘못 가리키는 선택을 고치거나 들여다보는 명령이 그 선택 때문에 못 돌면
     // 사람이 갇힌다.
@@ -427,6 +525,10 @@ export async function runAscCommand(argv, entry = 'runtime') {
     // 그러면 "아직 안 붙었다"를 확인하려고 부른 명령이 안 붙었다는 이유로 죽는다.
     if (group === 'setup')
         return runSetup(command, values, entry);
+    // adopt는 **붙기 전의 명령이다.** 붙을 Profile을 만드는 것이 일이므로 attach를 요구하면
+    // 순서가 뒤집힌다. 나머지 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)) {
         console.error(`Unknown command: ${group}\n\n${USAGE}`);
         return 2;
@@ -616,7 +718,7 @@ async function attachLocalWorkspace(projectRoot, git, declaredWorkspace) {
         return existing.root;
     }
     const remotes = git ? await gitRemotes(projectRoot) : [];
-    const aliases = remotes.map(normalizeRemote).filter((alias) => alias !== null);
+    const aliases = remoteAliases(remotes);
     // 사람이 "이건 그 프로젝트다"라고 말한 경우 — 이어붙인다. 추론이 아니라 선언이다.
     if (declaredWorkspace) {
         const known = index.workspaces[declaredWorkspace];
@@ -635,7 +737,7 @@ async function attachLocalWorkspace(projectRoot, git, declaredWorkspace) {
         console.log(`Registered this location under workspace ${known.workspaceId} — runtime lives at ${root}`);
         return root;
     }
-    const hits = recoverCandidates(Object.values(index.workspaces), remotes);
+    const hits = recoverCandidates(Object.values(index.workspaces), aliases);
     if (hits.length > 0) {
         // 붙일지는 사람이 정한다. 여기서 이어붙이면 남의 workspace를 조용히 가져올 수 있다.
         for (const line of recoverLines(hits))
@@ -658,20 +760,33 @@ async function attachLocalWorkspace(projectRoot, git, declaredWorkspace) {
         console.log(`Recognisable as: ${aliases.join(', ')}`);
     return root;
 }
-/** 모든 remote를 evidence로 모은다. origin을 primary로 단정하지 않는다 (C-11 불변식 ④). */
+/**
+ * 모든 remote를 evidence로 모은다. origin을 primary로 단정하지 않는다 (C-11 불변식 ④).
+ *
+ * 이름을 함께 든다 — identity alias는 이름이 필요 없지만, `profile adopt` 는 어느 remote가
+ * 이 프로젝트를 대표하는지 골라야 하고 `git remote -v` 의 출력 순서는 알파벳순이라
+ * "첫 줄이 origin"이 아니다.
+ */
 async function gitRemotes(projectRoot) {
     try {
         const { stdout } = await execFileAsync('git', ['-C', projectRoot, 'remote', '-v']);
-        const urls = stdout
-            .split(/\r?\n/)
-            .map((line) => line.split(/\s+/)[1])
-            .filter((url) => Boolean(url));
-        return [...new Set(urls)];
+        const seen = new Map();
+        for (const line of stdout.split(/\r?\n/)) {
+            const [name, url] = line.split(/\s+/);
+            if (!name || !url || seen.has(`${name}${url}`))
+                continue;
+            seen.set(`${name}${url}`, { name, url });
+        }
+        return [...seen.values()];
     }
     catch {
         return [];
     }
 }
+/** identity alias는 이름을 쓰지 않는다 — URL만 정규화한다. */
+const remoteAliases = (remotes) => [...new Set(remotes.map((remote) => remote.url))]
+    .map(normalizeRemote)
+    .filter((alias) => alias !== null);
 /**
  * 저장소 안에 있던 `.asc/` 를 사용자 소유 공간으로 옮긴다 (C-11 §6).
  *
@@ -679,8 +794,8 @@ async function gitRemotes(projectRoot) {
  */
 async function runWorkspace(command, values) {
     if (command !== 'migrate' && command !== 'list') {
-        console.error(`Unknown workspace command: ${command ?? '(none)'}
-
+        console.error(`Unknown workspace command: ${command ?? '(none)'}
+
 ${USAGE}`);
         return 2;
     }
@@ -726,7 +841,7 @@ ${USAGE}`);
         workspaceId,
         root: target,
         locator: { path: projectRoot, platform: process.platform, observedAt: new Date().toISOString() },
-        aliases: remotes.map(normalizeRemote).filter((alias) => alias !== null),
+        aliases: remoteAliases(remotes),
         now: new Date().toISOString(),
     }));
     console.log(`Copied and verified ${outcome.plan.entries} entries into ${target} (workspace ${workspaceId}).`);
@@ -773,6 +888,7 @@ async function runInit(values) {
         const plan = await planBootstrap({
             cwd: process.cwd(),
             installRoot: installRoot(),
+            externalProfileRoot: externalProfileRoot(),
             ...(attachedRoot ? { ascRoot: attachedRoot } : {}),
             hosts: [{ id: 'claude', installed: await verifyInstalled(defaultPaths()) }],
             bindings,
@@ -788,6 +904,24 @@ async function runInit(values) {
     }
     const { root: projectRoot, git } = await discoverProjectRoot(process.cwd());
     console.log(`Project: ${projectRoot}${git ? '' : ' (not a git repository)'}`);
+    // **읽을 수 있는 Profile인지 먼저 본다.** 아래부터는 `.git/info/exclude` 를 고치고
+    // 템플릿을 만드는 등 세상을 바꾸는 일이고, 그 뒤에 Profile이 잘못된 것을 알면 반쯤 만든
+    // `.asc/` 가 남는다 — 독립 검증이 실제로 그 상태를 만들었다. 여기서 멈추면 아무것도 남지 않는다.
+    try {
+        await loadLayers({
+            installRoot: installRoot(),
+            externalProfileRoot: externalProfileRoot(),
+            profileId: values.profile,
+        });
+    }
+    catch (error) {
+        const explained = explainConfigError(error);
+        if (explained === null)
+            throw error;
+        console.error(explained);
+        console.error('Nothing was changed.');
+        return 2;
+    }
     const ascRoot = scope === 'project'
         ? join(projectRoot, '.asc')
         : await attachLocalWorkspace(projectRoot, git, values.workspace);
@@ -824,6 +958,7 @@ async function attachedRuntime(ascRoot) {
     const outcome = await bootstrapGuard({
         ascRoot,
         installRoot: installRoot(),
+        externalProfileRoot: externalProfileRoot(),
         capabilities: CAPABILITIES,
         adapters: ADAPTER_VERSIONS,
         ascVersion: ASC_VERSION,
@@ -851,7 +986,7 @@ function declaredPolicies(resolved) {
     }
     return declared;
 }
-const ASC_VERSION = '0.1.0';
+const ASC_VERSION = '0.2.1';
 const CAPABILITIES = ['scm.github', 'state.markdown', 'approval.local'];
 const ADAPTER_VERSIONS = { 'scm.github': ASC_VERSION, 'state.markdown': ASC_VERSION };
 /**
@@ -981,11 +1116,12 @@ async function detectSetupState(values, entry) {
     const scope = values.scope === 'project' ? 'project' : 'local';
     const hostReport = await verifyInstall(defaultPaths());
     return {
+        entry,
         projectRoot,
         git,
         ...(ascRoot ? { ascRoot } : {}),
         ...(values.profile ? { requestedProfile: values.profile } : {}),
-        profileCandidates: await availableProfiles(installRoot()),
+        profileCandidates: await availableProfiles(installRoot(), externalProfileRoot()),
         scope,
         host: [{ id: 'claude', status: hostReport.status }],
         // **bootstrap으로 들어왔을 때만 본다.** 설치된 runtime이 자기를 다시 설치할 이유가
@@ -1101,6 +1237,7 @@ async function inspectSetup(root) {
     const outcome = await bootstrapGuard({
         ascRoot: root,
         installRoot: installRoot(),
+        externalProfileRoot: externalProfileRoot(),
         capabilities: CAPABILITIES,
         adapters: ADAPTER_VERSIONS,
         ascVersion: ASC_VERSION,
@@ -1115,6 +1252,9 @@ async function inspectSetup(root) {
     const runtime = outcome.ok ? outcome.runtime : undefined;
     return assessSetup({
         attachment,
+        ...(runtime
+            ? { profile: { id: runtime.layers.profile.id, origin: runtime.layers.profileOrigin } }
+            : {}),
         hasApprovers: Object.keys(await loadIdentityMap(root)).length > 0,
         hasControllerIdentities: Object.keys(runtime?.controllerIdentities ?? {}).length > 0,
         hasMonitorIdentities: (runtime?.monitor.identities?.length ?? 0) > 0,
@@ -1129,10 +1269,18 @@ const hasToken = async () => (await discoverToken()) !== null;
  */
 /** 이 저장소(또는 설치된 패키지)의 뿌리. profiles/ · presets/ 를 여기서 읽는다. */
 const installRoot = () => join(dirname(fileURLToPath(import.meta.url)), '..');
+/**
+ * 사용자 소유 Profile 디렉터리. 팀이 나눠 갖는 실 Profile이 여기 온다 —
+ * 배포본에는 예시만 있고, 남의 프로젝트 설정은 패키지에 실리지 않는다.
+ *
+ * **경로를 아는 것은 Surface의 몫이다.** Core에 홈을 알려 주지 않는다 (C-11).
+ */
+const externalProfileRoot = () => join(ascHome(), 'profiles');
 async function checkBootstrap(root) {
     const outcome = await bootstrapGuard({
         ascRoot: root,
         installRoot: installRoot(),
+        externalProfileRoot: externalProfileRoot(),
         capabilities: CAPABILITIES,
         adapters: ADAPTER_VERSIONS,
         ascVersion: ASC_VERSION,
@@ -1160,6 +1308,76 @@ async function checkBootstrap(root) {
     console.error('\nOnce you have checked it, re-lock with `asc profile resolve --write`.');
     return { code: 2 };
 }
+/**
+ * 지금 이 저장소를 설명하는 Profile을 사용자 소유 공간에 만든다 (P0).
+ *
+ * **이것이 되물음을 없앤다.** 배포본에 담긴 Profile은 예시뿐이고, 그래서 URL만 받은 agent는
+ * `ASC_PROFILE_SELECTION_REQUIRED` 앞에서 고를 것이 없어 사람에게 물었다. 여기서 만드는 것은
+ * git remote가 증명하는 사실뿐이다 — 정본 branch·role 경계·정책은 짓지 않는다 (adopt.ts 주석).
+ *
+ * 쓰는 곳은 `$ASC_HOME/profiles/<id>/` 이고 저장소는 건드리지 않는다. 이미 있으면 덮지 않고
+ * 멈춘다 — 남이 쓰던 Profile을 조용히 갈아 끼우는 것이 이 명령의 일이 아니다.
+ */
+async function runProfileAdopt(values, entry) {
+    const asJson = Boolean(values.json) || Boolean(values.agent);
+    const { root: projectRoot, git } = await discoverProjectRoot(process.cwd());
+    const remotes = git ? await gitRemotes(projectRoot) : [];
+    let adopted;
+    try {
+        adopted = buildAdoptedProfile({
+            dirName: basename(projectRoot),
+            remotes,
+            // provider를 아는 것은 Adapter를 아는 이 층이다 (C-09 §6.1). host 하나로 단정하는
+            // 것은 여기까지고, 모르는 host는 `git` 이라고만 적는다 — 그것이 사실이다.
+            scmForHost: (host) => (host === 'github.com' ? 'github' : 'git'),
+            ...(values.id ? { requestedId: values.id } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof AdoptError))
+            throw error;
+        console.error(error.message);
+        return 2;
+    }
+    // 스스로 만든 것이 스키마를 통과하는지 **쓰기 전에** 본다. 통과하지 못하는 파일을 놓고
+    // 나가면 그 다음 명령이 남의 설정 오류처럼 죽는다 (95250da가 닫은 것과 같은 모양).
+    const parsed = ProjectProfile.safeParse(adopted.profile);
+    if (!parsed.success) {
+        console.error(`Built a profile that ASC itself rejects — this is a bug in \`profile adopt\`:`);
+        for (const issue of parsed.error.issues)
+            console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+        return 1;
+    }
+    const dir = join(externalProfileRoot(), adopted.id);
+    const path = join(dir, 'profile.json');
+    if (existsSync(path)) {
+        console.error(`A profile called '${adopted.id}' is already there: ${path}\n` +
+            `Attach with it (\`asc setup apply --profile ${adopted.id}\`), or adopt under another name with --id <name>.`);
+        return 1;
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, `${JSON.stringify(adopted.profile, null, 2)}\n`, 'utf8');
+    // 다음 한 걸음은 두 형태로 준다 — agent는 portable, 사람은 display (C-14 불변식 ⑯).
+    // 여기서는 설치 상태를 다시 관측하지 않는다: 이 명령이 도는 방식이 곧 그 답이다.
+    const args = ['setup', 'apply', '--profile', adopted.id];
+    // portable은 agent가 그대로 실행한다 — 기계가 읽는 형태로 끝난다 (setup-plan.ts와 같은 규칙).
+    const machine = [...args, '--json'];
+    const action = {
+        type: 'apply_setup',
+        display: shorthandCommand(args),
+        portable: entry === 'bootstrap' ? portableCommand(machine) : shorthandCommand(machine),
+    };
+    if (asJson) {
+        console.log(JSON.stringify({ id: adopted.id, path, project: parsed.data.project, warnings: adopted.warnings, nextActions: [action.portable], actions: [action] }, null, 2));
+        return 0;
+    }
+    console.log(`Adopted ${projectRoot} as profile '${adopted.id}' — ${path}`);
+    console.log(`Project: ${parsed.data.project.scm} ${parsed.data.project.repository}`);
+    for (const warning of adopted.warnings)
+        console.log(`  note: ${warning}`);
+    console.log(`\nAttach with it: ${action.display}`);
+    return 0;
+}
 /**
  * 계층을 합쳐 산출물 셋을 만든다. 기본은 미리보기다 — 무엇이 바뀌는지 보고 나서 쓴다.
  * lock이 어긋나면 알리기만 하고 저절로 맞추지 않는다 (OM §4.9).
@@ -1176,6 +1394,7 @@ async function runProfile(command, values, root) {
     const installPath = values.install ?? installRoot();
     const layers = await loadLayers({
         installRoot: installPath,
+        externalProfileRoot: externalProfileRoot(),
         profileId: values.profile,
         ...(values.preset ? { presetId: values.preset } : {}),
         overridePath: join(root, 'override.json'),
@@ -2724,15 +2943,15 @@ async function runFreeze(group, command, values, store) {
         console.log(removed ? `${id} removed from the list — execution goes through the approval path` : `${id} was not found`);
         return removed ? 0 : 1;
     }
-    console.error(`Unknown freeze command: ${command}
-
+    console.error(`Unknown freeze command: ${command}
+
 ${USAGE}`);
     return 2;
 }
 async function runFront(command, values, store, root) {
     if (command !== undefined && command !== 'status') {
-        console.error(`Unknown front command: ${command}
-
+        console.error(`Unknown front command: ${command}
+
 ${USAGE}`);
         return 2;
     }
@@ -2910,5 +3129,15 @@ const invokedDirectly = (() => {
         return false;
     }
 })();
-if (invokedDirectly)
-    process.exitCode = await runAscCommand(process.argv.slice(2));
+if (invokedDirectly) {
+    try {
+        process.exitCode = await runAscCommand(process.argv.slice(2));
+    }
+    catch (error) {
+        const explained = explainConfigError(error);
+        if (explained === null)
+            throw error; // 모르는 고장은 감추지 않는다
+        console.error(explained);
+        process.exitCode = 1;
+    }
+}