@asc-agent/runtime 0.2.1 → 0.3.1

package/dist/cli/asc.js

@@ -9,17 +9,19 @@
 import { execFile, spawnSync } from 'node:child_process';
 import { parseArgs, promisify } from 'node:util';
 import { existsSync, readdirSync, realpathSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { homedir, userInfo } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
-import { MINIMUM_NODE_MAJOR, checkNodeRuntime, } from "../core/distribution/node-runtime.js";
+import { MINIMUM_NODE_MAJOR, checkNodeRuntime, reexecWithCandidate, } from "../core/distribution/node-runtime.js";
+import { RELEASE_VERSION } from "../core/distribution/release.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";
 import { GitHubScm } from "../adapters/github/scm.js";
 import { MarkdownStateStore } from "../adapters/markdown/state-store.js";
 import { LocalIdentityBinding } from "../adapters/local/identity.js";
+import { IDENTITY_FILE } from "./identity-config.js";
 import { TextRenderer } from "../adapters/text/renderer.js";
 import { ApprovalService } from "../core/approval/service.js";
 import { Executor } from "../core/execution/executor.js";
@@ -32,6 +34,7 @@ import { adoptionLine, judgeAdoption, migrate } from "../core/workspace/migrate.
 import { newWorkspaceId, normalizeRemote, recoverCandidates, recoverLines } from "../core/workspace/identity.js";
 import { resolveWorkspace, resolutionLine } from "../core/workspace/resolve.js";
 import { assessSetup, renderSetup } from "../core/attach/setup.js";
+import { withIdentity } from "../core/attach/init.js";
 import { applySetupPlan, computeSetupPlan, renderSetupPlan, } from "../core/attach/setup-plan.js";
 import { CLAUDE_PROVIDER, CLAUDE_SCOPE, claudeBindings } from "../adapters/claude-code/binding.js";
 import { readHeartbeat } from "../adapters/claude-code/observer.js";
@@ -42,15 +45,23 @@ import { MonitorEngine } from "../core/monitor/engine.js";
 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 { LocalRepoAdapter } from "../adapters/local/repo.js";
+import { GitHubAdapter } from "../adapters/github/adapter.js";
+import { GitLabAdapter } from "../adapters/gitlab/adapter.js";
+import { JamAdapter } from "../adapters/jam/adapter.js";
+import { statusIndicatesDone } from "../adapters/jam/ports.js";
 import { ProgressService } from "../core/operator/progress.js";
 import { composeBindings, defaultAdapters } from "../composition/registry.js";
-import { buildRuntimePorts, rolesFor } from "../composition/runtime.js";
+import { buildRuntimePorts, closeToolClients, rolesFor } from "../composition/runtime.js";
+import { proposeBindings } from "../composition/propose.js";
 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 { DraftProvenance, issueArgs, planSessionContract, } from "../core/operator/contract-draft.js";
 import { lookupAuthority } from "../core/policy/ownership.js";
 import { renderProgress } from "../core/operator/render.js";
 import { AuditLedger, decisionLines, delegationLine, executionLines, reclaimLine, validationLines, } from "../core/runtime/audit.js";
@@ -76,7 +87,7 @@ 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 proceed [--session <id>] [--work <WORK-ID>] [--goal <text>] [--json]
 
   asc inbox list   [--all] [--priority P0|P1|P2] [--json]
   asc inbox show   <REQUEST_ID> [--json]
@@ -121,11 +132,16 @@ const USAGE = `asc — Agent Session Control
                         # without --profile: report what was detected, then stop
 
   asc setup status [--json]
+  asc setup identity [--role controller|monitor|both] [--actor <channel:actor>]
+                        # 지금 이 사람을 승인 권한자로 세우고 재고정까지 한다
   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 plan  [--id <S-ID>] [--role <role>] [--goal <text>] [--boundary <glob>...]
+                    [--criteria <text>...] [--owner <role>] [--provenance <f>=<STATUS>[:<src>]...]
+                    [--json]        # is this draft issuable? changes nothing
   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>]
@@ -189,6 +205,8 @@ Options
   --write         actually write the artefacts (default: preview)
   --role          planner|researcher|implementer|verifier
   --goal          the single goal of this session
+  --work          work item to investigate before proposing a contract (asc proceed)
+  --actor         who you are, as <channel>:<actor> (asc setup identity)
   --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)
@@ -410,6 +428,8 @@ export async function runAscCommand(argv, entry = 'runtime') {
             ownership: { type: 'string', multiple: true },
             verification: { type: 'string', multiple: true },
             why: { type: 'string', multiple: true },
+            /** 초안의 출처 — `<field>=<FACT|PROPOSAL|DECISION_REQUIRED>[:<source>]` (session plan). */
+            provenance: { type: 'string', multiple: true },
             offline: { type: 'boolean', default: false },
             id: { type: 'string' },
             intent: { type: 'string' },
@@ -458,6 +478,8 @@ export async function runAscCommand(argv, entry = 'runtime') {
             body: { type: 'string' },
             to: { type: 'string' },
             session: { type: 'string' },
+            work: { type: 'string' },
+            actor: { type: 'string' },
             position: { type: 'string' },
             next: { type: 'string' },
             done: { type: 'string', multiple: true },
@@ -500,6 +522,17 @@ export async function runAscCommand(argv, entry = 'runtime') {
     // 두면 그쪽에 정책이 생기고(C-14 불변식 ⑦), 그러면 두 진입의 답이 갈릴 수 있다.
     const runnable = await checkNodeRuntime(nodeRuntimeDeps());
     if (!runnable.ok) {
+        // 후보를 이미 찾았으면 처방 대신 실행한다 — 같은 명령, 같은 argv, 호환 Node (A6).
+        const reexec = reexecWithCandidate(runnable, argv, {
+            env: process.env,
+            entry: fileURLToPath(import.meta.url),
+            spawn: (path, args, env) => {
+                const child = spawnSync(path, args, { stdio: 'inherit', env: env });
+                return { status: child.status, signal: child.signal, ...(child.error ? { error: child.error } : {}) };
+            },
+        });
+        if (reexec !== null)
+            return reexec;
         reportNodeRuntime(runnable, Boolean(values.json) || Boolean(values.agent));
         return 1;
     }
@@ -986,7 +1019,9 @@ function declaredPolicies(resolved) {
     }
     return declared;
 }
-const ASC_VERSION = '0.2.1';
+// RELEASE_VERSION 이 정본이다 — 여기 문자열을 따로 두면 릴리스마다 낡는다 (0.3.0 에서
+// 0.2.1 로 남아 lock 의 ascVersion 표기가 실제와 어긋났다).
+const ASC_VERSION = RELEASE_VERSION;
 const CAPABILITIES = ['scm.github', 'state.markdown', 'approval.local'];
 const ADAPTER_VERSIONS = { 'scm.github': ASC_VERSION, 'state.markdown': ASC_VERSION };
 /**
@@ -1075,6 +1110,8 @@ async function runSetup(command, values, entry = 'runtime') {
     // plan/apply는 같은 판단을 나눠 쓴다 (C-14 §6). `--agent` 는 apply의 비대화 형태다.
     if (command === 'plan' || command === 'apply')
         return runSetupLifecycle(command, values, entry);
+    if (command === 'identity')
+        return runSetupIdentity(values);
     if (values.agent)
         return runSetupLifecycle('apply', values, entry);
     if (command !== undefined && command !== 'status') {
@@ -1173,6 +1210,104 @@ const nodeProcessRunner = async (command, args) => {
  * 사람이 보는 줄과 agent가 파싱하는 JSON은 **같은 plan**에서 나온다 (C-14 불변식 ①).
  * agent 경로의 stdout은 JSON 문서 하나뿐이고, 그 밖의 말은 stderr로 간다 (§7).
  */
+/**
+ * `asc setup identity` — 지금 이 사람을 이 workspace 의 승인 권한자로 세운다 (P1-F).
+ *
+ * 결정은 사람이 하고(이 명령을 실행하는 것이 그 결정이다), **파일 편집은 ASC 가 한다.**
+ * 그 전까지는 identities.json 과 override.json 을 손으로 고치는 것이 유일한 길이었고,
+ * 그 둘은 서로 다른 형식이라 한쪽만 채워 놓고 왜 안 열리는지 모르는 상태가 흔했다.
+ *
+ * 비밀은 읽지도 쓰지도 않는다. 여기서 다루는 것은 이름과 채널뿐이다.
+ */
+async function runSetupIdentity(values) {
+    const resolution = await resolveRoot(process.cwd(), values.root);
+    if (resolution.kind === 'UNRESOLVED') {
+        console.error('Not attached yet — run `asc init --profile <id>` first.');
+        return 2;
+    }
+    const root = resolution.root;
+    const explicit = values.actor;
+    const candidate = explicit ?? (await detectSelf());
+    if (!candidate) {
+        console.error('Could not tell who you are here. Pass one: --actor local:<name>');
+        return 2;
+    }
+    const actor = candidate.includes(':') ? candidate : `local:${candidate}`;
+    const name = actor.slice(actor.indexOf(':') + 1);
+    const roles = values.role ?? 'both';
+    if (!['controller', 'monitor', 'both'].includes(roles)) {
+        console.error("--role is controller|monitor|both");
+        return 2;
+    }
+    const asController = roles !== 'monitor';
+    const asMonitor = roles !== 'controller';
+    // 어느 Profile 로 재고정할지는 lock 파일에서 읽는다. attachment 판정을 쓰면 안 되는 이유는
+    // 이 명령 자신이 drift 를 만들기 때문이다 — 한 번 실패하면 그 다음부터는 자기가 닫아야 할
+    // drift 때문에 profile 을 못 읽어 영영 못 닫는다.
+    const attachedProfile = values.profile ?? (await lockedProfileId(root));
+    if (!attachedProfile) {
+        console.error('붙어 있는 Profile 을 알 수 없다 — `asc setup status` 를 보고, 필요하면 --profile 로 지목하라.');
+        return 1;
+    }
+    const identitiesPath = join(root, IDENTITY_FILE);
+    const overridePath = join(root, 'override.json');
+    const merged = withIdentity(await readJson(identitiesPath), await readJson(overridePath), {
+        name,
+        actor,
+        controller: asController,
+        monitor: asMonitor,
+    });
+    await writeJson(identitiesPath, merged.identities);
+    await writeJson(overridePath, merged.override);
+    console.log(`${name} — ${actor}`);
+    console.log(`  identities.json  ${asController ? 'approver 등록' : '건드리지 않음'}`);
+    console.log(`  override.json    ${asController ? 'controller.identities' : ''}${asController && asMonitor ? ' · ' : ''}${asMonitor ? 'monitorIdentities' : ''}`);
+    // override 는 lock digest 에 들어간다 — 고친 뒤 재고정하지 않으면 다음 명령이 멈춘다.
+    // 어느 Profile 로 재고정할지는 지금 붙어 있는 것이 답이다 — 사람에게 다시 묻지 않는다.
+    const relocked = await runProfile('resolve', { ...values, profile: attachedProfile, write: true }, root);
+    if (relocked !== 0)
+        return relocked;
+    console.log('');
+    console.log(renderSetup(await inspectSetup(root)));
+    return 0;
+}
+/** 지금 붙어 있는 Profile id. lock 이 어긋나 있어도 읽힌다 — 파일에 그대로 남아 있다. */
+async function lockedProfileId(root) {
+    try {
+        const lock = JSON.parse(await readFile(join(root, 'profile.lock'), 'utf8'));
+        return lock.profile?.id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** git·계정에서 "지금 이 사람"의 이름만 읽는다. 자격 값은 읽지 않는다. */
+async function detectSelf() {
+    const fromGit = await execText('git', ['config', 'user.name']);
+    if (fromGit)
+        return fromGit;
+    const user = userInfo().username;
+    return user || null;
+}
+async function execText(command, args) {
+    try {
+        const { stdout } = await execFileAsync(command, args);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readJson(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const writeJson = (path, value) => writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 async function runSetupLifecycle(command, values, entry) {
     const asJson = Boolean(values.json) || Boolean(values.agent);
     const plan = computeSetupPlan(await detectSetupState(values, entry));
@@ -1399,9 +1534,18 @@ async function runProfile(command, values, root) {
         ...(values.preset ? { presetId: values.preset } : {}),
         overridePath: join(root, 'override.json'),
     });
-    // 무엇이 실제로 제공되는지는 붙어 있는 Adapter가 정한다
-    const capabilities = ['scm.github', 'state.markdown', 'approval.local'];
-    const result = resolveRuntime(layers, capabilities, ASC_VERSION);
+    // 무엇이 실제로 제공되는지는 붙어 있는 Adapter가 정한다 — 상수가 아니라 실측이다 (A5).
+    // discover→probe 를 실제로 돌린다: glab 로그인 같은 상태 변화가 resolve 재실행으로
+    // 반영된다 (re-probe 수단이 따로 필요 없다). 실측 실패는 그 갈래가 빠질 뿐이다.
+    const composed = await composeBindings({ context: { projectRoot: root, env: process.env } }).catch(() => ({ bindings: [] }));
+    for (const binding of composed.bindings) {
+        console.log(`Binding: ${binding.adapterId}/${binding.resource} — ${binding.state}${binding.detail ? ` (${binding.detail})` : ''}`);
+    }
+    // lock 의 capability 표기는 아직 상수다 — 실측을 digest 재료로 쓰면 glab 로그인 여부에
+    // 따라 lock 이 흔들린다. 실측을 lock 체계에 관통시키는 것은 P1 로 넘기고(재설계 영역),
+    // 여기서는 probe 실측을 사람에게 보이는 것까지 한다. 실사용 read 경로(proceed)는
+    // buildWorkIngress 가 이미 composeBindings 실측으로 조립한다.
+    const result = resolveRuntime(layers, CAPABILITIES, ASC_VERSION);
     if (!result.ok) {
         console.error('resolve failed:');
         for (const failure of result.failures) {
@@ -1414,7 +1558,7 @@ async function runProfile(command, values, root) {
     const lock = buildLock({
         runtime,
         ascVersion: ASC_VERSION,
-        adapters: { 'scm.github': ASC_VERSION, 'state.markdown': ASC_VERSION },
+        adapters: ADAPTER_VERSIONS,
         generatedAt,
     });
     console.log(`Layers: ${runtime.resolved.policy.layers.join(' → ')}`);
@@ -1713,11 +1857,18 @@ async function runProceed(values, store, root, resolved) {
         canonicalSources: (resolved?.canonicalSources ?? []).map((sourceId) => ({ sourceId })),
         ...(resolved?.ownership ? { ownership: resolved.ownership } : {}),
     });
+    const workRef = values.work ?? undefined;
+    const ingress = workRef ? await buildWorkIngress(store, root, sessions, resolved) : undefined;
+    if (workRef && !ingress) {
+        console.error(`작업 항목 '${workRef}' 을 읽을 통로가 없다 — Profile bindings 에 작업 항목 provider 를 선언하라.`);
+        return 2;
+    }
     const operator = new Operator({
         store,
         sessions,
         // 막힌 node만 보고 판단한다 — checkpoint를 발행했다는 이유로 멈추지 않는다 (C-13 §3.1)
         escalations: escalationLedger(store),
+        ...(ingress ? { ingress } : {}),
         // main()의 checkBootstrap과 같은 원천(bootstrapGuard)이다 — 중복 판단이 아니라 같은 문
         guard: async () => {
             const outcome = await checkBootstrap(root);
@@ -1727,7 +1878,10 @@ async function runProceed(values, store, root, resolved) {
     const outcome = await operator.proceed({
         ...(values.session ? { sessionId: values.session } : {}),
         ...(values.goal ? { goal: values.goal } : {}),
+        ...(workRef ? { workRef } : {}),
     });
+    // 도구 자식(JAM MCP 서버 등)을 여기서 닫는다 — 안 닫으면 출력까지 끝내고도 종료하지 못한다.
+    await closeToolClients();
     if (values.json) {
         console.log(JSON.stringify(outcome, null, 2));
         return outcome.kind.startsWith('BLOCKED') || outcome.kind === 'FAILED' ? 1 : 0;
@@ -1781,7 +1935,39 @@ async function runProceed(values, store, root, resolved) {
                 console.log(`  ${c.id}  ${c.status.padEnd(7)}  ${c.wouldDo.padEnd(8)}  ${c.goal}`);
             }
             return 1;
+        case 'WORK_STATE': {
+            const shown = outcome.result.leaning
+                ? `${outcome.result.state} (${outcome.result.leaning})`
+                : outcome.result.state;
+            console.log(`${outcome.workRef}: ${shown}`);
+            for (const line of outcome.result.evidence)
+                console.log(`  근거      ${line}`);
+            for (const line of outcome.result.limitations)
+                console.log(`  한계      ${line}`);
+            for (const line of outcome.result.missing)
+                console.log(`  미확인    ${line}`);
+            console.log(`\n다음 행동: ${outcome.nextAction}`);
+            return outcome.result.state === 'UNDECIDABLE' ? 1 : 0;
+        }
         case 'PROPOSE_CONTRACT':
+            if (outcome.plan) {
+                console.log(`${outcome.plan.status}${outcome.full?.id ? ` — ${outcome.full.id}` : ''}`);
+                for (const fact of outcome.plan.facts)
+                    console.log(`  fact      ${fact.field} (${fact.source})`);
+                for (const proposal of outcome.plan.proposals) {
+                    console.log(`  proposal  ${proposal.field} — ${proposal.reason ?? proposal.source}`);
+                }
+                for (const item of outcome.plan.invalid)
+                    console.log(`  invalid   ${item.field}: ${item.detail}`);
+                for (const item of outcome.plan.unresolved) {
+                    console.log(`  decide    ${item.field} [${item.reason}]: ${item.detail}`);
+                }
+                if (outcome.forController) {
+                    console.log(`\n계약은 성립한다. 발급은 Controller 의 것이다 — ${outcome.plan.issuance.detail}:`);
+                    console.log(`  ${shorthandCommand(outcome.forController.slice(1))}`);
+                }
+                return outcome.plan.status === 'READY_TO_ISSUE' ? 0 : 1;
+            }
             console.log('No runnable session. If a new contract is needed, the Controller issues it:');
             console.log(`  asc session issue S-<date>-<n> --role ${outcome.draft.role} --goal "${outcome.draft.goal || '<goal>'}"`);
             return 1;
@@ -1806,6 +1992,203 @@ async function runProceed(values, store, root, resolved) {
             return 1;
     }
 }
+/**
+ * 이미 쓴 세션 id. **회수돼 보관된 것까지 센다** — 그 번호를 다시 쓰면 앞의 계약 기록
+ * 위에 다른 계약이 앉는다. 실제로 그렇게 기록 하나를 잃었다.
+ */
+async function usedSessionIds(store, root) {
+    const active = (await store.list('session')).map((session) => session.id);
+    let archived = [];
+    try {
+        archived = (await readdir(join(root, 'sessions', 'archive')))
+            .filter((name) => name.endsWith('.md'))
+            .map((name) => name.slice(0, -3));
+    }
+    catch {
+        archived = [];
+    }
+    return [...new Set([...active, ...archived])];
+}
+/**
+ * 저장소의 최상위 자리와 그 아래 `src`. 분류 이름이 어느 모듈에 맞는지 재는 재료다 —
+ * 목록일 뿐이고, 이것이 쓰기 범위가 되지는 않는다 (derive 가 최상위는 범위로 쓰지 않는다).
+ */
+async function topLevelModules(projectRoot) {
+    try {
+        const entries = await readdir(projectRoot, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
+            .flatMap((entry) => [entry.name, `${entry.name}/src`]);
+    }
+    catch {
+        return [];
+    }
+}
+/** 선행·의존으로 볼 후보. 링크가 먼저고, 본문이 말한 키가 그다음이다. 상한은 5. */
+const DEPENDENCY_CAP = 5;
+function dependencyCandidates(workItem) {
+    if (!workItem)
+        return [];
+    // 본문이 "BLOCKED BY: KEY-1" 처럼 말한 것은 링크가 없어도 의존이다 — 링크가 없다는
+    // 사실이 의존이 없다는 뜻은 아니다.
+    const fromBody = new Set();
+    const project = workItem.reference.split('-')[0];
+    if (project) {
+        const pattern = new RegExp(`(?:blocked\\s*by|선행|의존)[^\\n]*?(${project}-\\d+)`, 'gi');
+        for (const [, key] of `${workItem.body ?? ''}`.matchAll(pattern))
+            if (key)
+                fromBody.add(key);
+    }
+    // 부모·하위 작업은 포함 관계이지 선행이 아니다 — 그것까지 세면 거의 모든 작업이 막힌다.
+    const ordered = [...(workItem.blockedBy ?? []), ...fromBody].filter((key) => key !== workItem.reference);
+    return [...new Set(ordered)].slice(0, DEPENDENCY_CAP);
+}
+/**
+ * 작업 항목 하나를 조사해 계약까지 잇는 통로 (P0-D).
+ *
+ * 여기서 판정하지 않는다. 모으고(gather·observeRepo), 도출하고(derive), **기존 판정기에
+ * 넘긴다**(plan = planSessionContract, issue = SessionRuntime). 범위·책임·발급 권한은
+ * 그것들이 답하는 것을 그대로 쓴다.
+ *
+ * buildMonitorEngine 을 거치지 않는 이유: 그 함수는 GitHub 토큰이 없으면 멈춘다. 감시에는
+ * 맞는 문이지만, GitLab·JAM 프로젝트에서 저장소 조사까지 막아 버린다 — 그것이 "원격이
+ * 막혔으니 저장소도 못 본다"는 잘못된 결론을 만든 구조다.
+ */
+async function buildWorkIngress(store, root, runtime, resolved) {
+    const { root: projectRoot } = await discoverProjectRoot(process.cwd());
+    // JAM 은 아직 `jam` 바이너리를 깔지 않는 설치가 기본이다 — 그 경우 launcher 를 통해 부른다.
+    const jamCommand = process.env.ASC_JAM_PATH ? undefined : { command: 'npx', args: ['--yes', '@jam-mcp/launcher'] };
+    const adapters = [
+        new GitHubAdapter(),
+        new GitLabAdapter(),
+        new JamAdapter(jamCommand ?? {}),
+    ];
+    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 })),
+    });
+    // 선언이 없으면 발견된 사실로 제안한다 (P1-G). 저장하지 않고, 갈리면 고르지 않는다.
+    const proposed = declared.length === 0 ? proposeBindings(plan) : undefined;
+    if (proposed) {
+        for (const reason of proposed.reasons)
+            console.error(`  제안  ${reason}`);
+        for (const conflict of proposed.conflicts)
+            console.error(`  보류  ${conflict}`);
+    }
+    const ports = await buildRuntimePorts({
+        plan,
+        // 제안은 **말하는 것**이지 정하는 것이 아니다. 역할을 박아 넣으면 선언과 구분되지 않고,
+        // capability 해석은 후보가 유일할 때 이미 스스로 풀린다.
+        roles: rolesFor(plan, declared),
+        perPage: 30,
+        jam: { command: jamCommand?.command ?? 'jam', args: [...(jamCommand?.args ?? []), 'serve'], cwd: projectRoot },
+        endpointFor: (binding) => endpointOf(adapters, binding),
+    });
+    const work = ports.resourceContext;
+    if (!work)
+        return undefined;
+    // 저장소는 원격 provider 와 무관하게 본다. 이 한 줄이 P0-E 의 요점이다.
+    const repo = new LocalRepoAdapter({ cwd: projectRoot });
+    const canonicalSource = resolved?.layers.profile.canonical.sources[0];
+    const canonicalRef = canonicalSource?.ref;
+    // remote 를 버리면 로컬 브랜치를 정본처럼 읽는다 — 실전 오판의 경로였다.
+    const canonicalRemote = canonicalSource?.remote;
+    const canonicalPaths = resolved?.layers.profile.canonical.sources.flatMap((source) => source.paths) ?? [];
+    const changeContext = ports.changeContext;
+    return {
+        gather: async (workRef) => {
+            const workItem = await work.getResource(workRef).catch(() => undefined);
+            const comments = await work
+                .getComments(workRef, { limit: 20 })
+                .then((list) => list)
+                .catch(() => 'UNAVAILABLE');
+            const change = changeContext
+                ? await changeContext
+                    .getChange(workRef)
+                    .then((summary) => summary)
+                    .catch(() => 'UNAVAILABLE')
+                : 'UNAVAILABLE';
+            // 선행 작업이 열려 있는지는 **조회해야** 안다. 키만 넘기면 판정이 늘 "모른다"가 되고,
+            // 그러면 막힌 작업이 착수 가능으로 보인다. adapter 가 막는 것을 앞에 실어 주므로
+            // 상한에 걸려도 blocker 가 먼저 확인된다.
+            const candidates = dependencyCandidates(workItem);
+            const dependencies = await Promise.all(candidates.map(async (reference) => {
+                const item = await work.getResource(reference).catch(() => undefined);
+                const done = item && !item.missing ? statusIndicatesDone(item.state) : undefined;
+                return {
+                    reference,
+                    ...(item?.state ? { state: item.state } : {}),
+                    ...(done === undefined ? {} : { open: !done }),
+                };
+            }));
+            return {
+                ...(workItem ? { workItem } : {}),
+                ...(workItem ? { trackerDone: statusIndicatesDone(workItem.state) } : {}),
+                comments,
+                change,
+                dependencies,
+            };
+        },
+        observeRepo: async (query) => {
+            // 조회할 경로는 **작업 항목이 지목한 것**이 먼저다. 그것을 확인해야 좁은 범위를
+            // 만들 수 있고, 확인하지 않으면 넓은 범위밖에 남지 않는다. 저장소의 최상위 자리도
+            // 함께 확인한다 — 분류 이름이 어느 모듈 하나에만 맞는지 재려면 그 목록이 있어야 한다.
+            const modules = await topLevelModules(projectRoot);
+            const paths = [...new Set([...(query.paths ?? []), ...canonicalPaths])];
+            return repo.observe({
+                refHint: query.refHint,
+                ...(canonicalRef ? { canonicalRef } : {}),
+                ...(canonicalRemote ? { remote: canonicalRemote } : {}),
+                ...(paths.length > 0 ? { paths } : {}),
+                ...(modules.length > 0 ? { modulePaths: modules } : {}),
+            });
+        },
+        usedIds: () => usedSessionIds(store, root),
+        derive: (input) => deriveSessionContractDraft({
+            existingIds: input.existingIds,
+            intent: { workRef: input.workRef, ...(input.goal ? { goal: input.goal } : {}) },
+            workItem: input.workItem,
+            workState: input.workState,
+            repo: input.repo,
+            // 상한이지 출처가 아니다 — 도출한 후보가 이 밖으로 나가지 않는지 재는 데만 쓴다.
+            maxScopes: resolved?.resolved.policy.roleScopes.implementer ?? [],
+            ...(resolved?.ownership ? { ownership: resolved.ownership } : {}),
+            today: new Date().toISOString().slice(0, 10).replace(/-/g, ''),
+        }),
+        plan: async (draft) => planSessionContract({
+            draft,
+            ...(resolved?.resolved.policy ? { policy: resolved.resolved.policy } : {}),
+            ...(resolved?.ownership ? { ownership: resolved.ownership } : {}),
+            existingIds: await usedSessionIds(store, root),
+        }),
+        issue: async (draft) => {
+            // 발급 경로는 하나뿐이다 — `asc session issue` 와 같은 SessionRuntime.issue 를 부른다.
+            const issued = await runtime.issue({
+                id: draft.id,
+                role: SessionRole.parse(draft.role ?? 'implementer'),
+                goal: draft.goal ?? '',
+                ...(draft.criteria ? { doneCriteria: [...draft.criteria] } : {}),
+                ...(draft.boundary ? { writeBoundary: [...draft.boundary] } : {}),
+                ...(draft.owner ? { owner: draft.owner } : {}),
+            });
+            if (!issued.ok) {
+                return { ok: false, detail: issued.failures.map((f) => `${f.kind}: ${f.detail}`).join('; ') };
+            }
+            await auditLedger(store).delegate({
+                childSessionId: issued.session.id,
+                role: issued.session.role,
+                goal: issued.session.goal,
+                scope: issued.session.writeBoundary,
+                doneCriteria: issued.session.doneCriteria,
+                issuedBy: issued.session.owner ?? '(위임 범위 내 자동 발급)',
+                issuedAt: new Date().toISOString(),
+            });
+            return { ok: true, sessionId: issued.session.id };
+        },
+    };
+}
 /** 세션 lifecycle. 계약을 발급하고, 중단·재개하고, Handoff까지 남긴다 (OM §6.2). */
 /**
  * 이 세션이 걸린 결정마다 실제 결정권자. 세션 계약이 먼저고, 없으면 Profile 지도에서 푼다.
@@ -1840,6 +2223,94 @@ function parseAuthority(pairs) {
     }
     return { ok: true, map };
 }
+/**
+ * 초안을 재 본다. **아무것도 발급하지 않는다** (C-14 §6의 plan/apply 분리와 같은 자세).
+ *
+ * agent가 사용자 요청·work item·Profile·저장소를 읽어 계약 초안을 만들고, 여기서 그것이
+ * 구조·경계로 성립하는지 확인한다. 판정은 셋뿐이다 — 발급해도 된다 / 사람이 정할 것이
+ * 남았다 / 이 초안으로는 계약이 안 된다.
+ */
+async function runSessionPlan(values, store, resolved) {
+    const authority = parseAuthority(values.authority);
+    if (!authority.ok) {
+        console.error(authority.detail);
+        return 2;
+    }
+    // 출처는 `<field>=<status>[:<source>]` 로 받는다 — 초안을 만든 쪽이 무엇을 확인했고
+    // 무엇을 제안했는지 스스로 적게 한다. 적지 않으면 제안으로 셈한다(사실로 올리지 않는다).
+    const provenance = [];
+    for (const raw of values.provenance ?? []) {
+        const [field, rest] = raw.split('=', 2);
+        const [status, source] = (rest ?? '').split(':', 2);
+        const parsed = DraftProvenance.safeParse({
+            field,
+            status,
+            source: source ?? 'agent_proposal',
+            ...(values.why ? { reason: values.why[0] } : {}),
+        });
+        if (!parsed.success) {
+            console.error(`--provenance 는 <field>=<FACT|PROPOSAL|DECISION_REQUIRED>[:<source>] 형식이다: '${raw}'`);
+            return 2;
+        }
+        provenance.push(parsed.data);
+    }
+    const draft = {
+        ...(values.id ? { id: values.id } : {}),
+        ...(values.role ? { role: values.role } : {}),
+        ...(values.goal ? { goal: values.goal } : {}),
+        ...(values.boundary ? { boundary: values.boundary } : {}),
+        ...(values.criteria ? { criteria: values.criteria } : {}),
+        ...(values.owner ? { owner: values.owner } : {}),
+        ...(values.domain ? { decisionDomains: values.domain } : {}),
+        ...(Object.keys(authority.map).length > 0 ? { decisionAuthority: authority.map } : {}),
+        ...(provenance.length > 0 ? { provenance } : {}),
+    };
+    const plan = planSessionContract({
+        draft,
+        ...(resolved?.resolved.policy ? { policy: resolved.resolved.policy } : {}),
+        ...(resolved?.ownership ? { ownership: resolved.ownership } : {}),
+        existingIds: (await store.list('session')).map((session) => session.id),
+    });
+    // 통과했을 때만 실행 가능한 명령을 준다. 통과하지 않은 초안의 명령을 함께 주면
+    // agent는 그것을 "고치고 나서 쓸 것"이 아니라 "지금 쓸 것"으로 읽는다.
+    //
+    // 그리고 **완성된 계약이라고 해서 발급해도 되는 것은 아니다** (OM §450). 위임이 없으면
+    // 명령은 `forController` 로 간다 — actions에 넣으면 "portable을 실행하라"는 지시를 따르는
+    // agent가 사람의 권한을 대신 쓰게 된다.
+    const issuable = plan.status === 'READY_TO_ISSUE';
+    const command = {
+        display: shorthandCommand(issueArgs(draft)),
+        portable: shorthandCommand([...issueArgs(draft), '--json']),
+    };
+    const actions = issuable && plan.issuance.authority === 'delegated' ? [{ type: 'issue_session', ...command }] : [];
+    const forController = issuable && plan.issuance.authority === 'controller' ? command : undefined;
+    if (values.json || values.agent) {
+        console.log(JSON.stringify({ ...plan, nextActions: actions.map((action) => action.portable), actions, ...(forController ? { forController } : {}) }, null, 2));
+    }
+    else {
+        console.log(`${plan.status}${plan.draft.id ? ` — ${plan.draft.id}` : ''}`);
+        for (const fact of plan.facts)
+            console.log(`  fact      ${fact.field} (${fact.source})`);
+        for (const proposal of plan.proposals)
+            console.log(`  proposal  ${proposal.field} — ${proposal.reason ?? proposal.source}`);
+        for (const item of plan.invalid)
+            console.log(`  invalid   ${item.field}: ${item.detail}`);
+        for (const item of plan.unresolved) {
+            console.log(`  decide    ${item.field} [${item.reason}]: ${item.detail}`);
+            for (const [index, option] of (item.options ?? []).entries()) {
+                console.log(`              ${index + 1}. ${option}${item.recommended === index ? '   ← recommended' : ''}`);
+            }
+        }
+        for (const action of actions)
+            console.log(`\nIssue it: ${action.display}`);
+        if (forController) {
+            console.log(`\nThe contract holds. Issuing it is the Controller's — ${plan.issuance.detail}:`);
+            console.log(`  ${forController.display}`);
+        }
+    }
+    // 사람이 정할 것이 남았거나 초안이 성립하지 않으면 1이다 — setup plan과 같은 규칙.
+    return plan.status === 'READY_TO_ISSUE' ? 0 : 1;
+}
 async function runSession(command, target, values, store, resolved) {
     // Profile이 정한 Role 범위와 금지가 여기까지 와야 실제로 강제된다.
     // 정책 없이 만들면 붙어 있는 프로젝트에서도 계약 검사가 통째로 비어버린다.
@@ -1863,6 +2334,10 @@ async function runSession(command, target, values, store, resolved) {
         }
         return 0;
     }
+    // `plan` 은 **아직 세션이 없을 때** 부르는 것이므로 id를 요구하지 않는다. 초안에 id가
+    // 없다는 사실 자체가 판정 대상이다 (없으면 그것이 unresolved로 나온다).
+    if (command === 'plan')
+        return runSessionPlan(values, store, resolved);
     if (!target) {
         console.error(`Usage: asc session ${command ?? '<command>'} <SESSION_ID>`);
         return 2;