@asc-agent/runtime 0.2.1 → 0.3.0

package/dist/cli/asc.js

@@ -9,9 +9,9 @@
 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 { GitHubClient, discoverToken } from "../adapters/github/client.js";
@@ -20,6 +20,7 @@ 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 +33,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 +44,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 +86,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 +131,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 +204,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 +427,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 +477,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 },
@@ -1075,6 +1096,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 +1196,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));
@@ -1713,11 +1834,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 +1855,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 +1912,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 +1969,199 @@ 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 canonicalRef = resolved?.layers.profile.canonical.sources[0]?.ref;
+    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 } : {}),
+                ...(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 +2196,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 +2307,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;

package/dist/composition/propose.d.ts

@@ -0,0 +1,19 @@
+import type { BindingPlan, Capability } from '../core/binding/types.ts';
+export type BindingProposal = {
+    /**
+     * capability → 이 통로를 맡을 adapter.
+     *
+     * **조립에 밀어 넣는 값이 아니다.** 후보가 유일하면 capability 해석은 스스로 풀리므로,
+     * 여기서 역할을 박으면 선언과 제안이 같은 자리에 섞인다. 이 표는 "무엇이 무엇을 맡게
+     * 됐는지"를 사람에게 말하기 위한 것이다.
+     */
+    roles: Partial<Record<Capability, string>>;
+    /** 사람이 읽는 근거. 제안이라는 사실을 문장 안에 남긴다. */
+    reasons: string[];
+    /** 후보가 갈려 제안하지 않은 것들. */
+    conflicts: string[];
+};
+/**
+ * 선언이 하나도 없을 때만 부른다. 선언이 있으면 그것이 답이고, 여기서 다시 정하지 않는다.
+ */
+export declare function proposeBindings(plan: BindingPlan): BindingProposal;

package/dist/composition/propose.js

@@ -0,0 +1,35 @@
+// Binding 자동 제안 (P1-G).
+//
+// Profile 은 **팀이 정한 것**을 담는다. 그런데 지금까지는 발견하면 알 수 있는 사실까지
+// 거기 적어야 했다 — 원격이 하나뿐이고 그 원격을 다룰 adapter 도 하나뿐인데도, 누가
+// bindings 에 적어 주기 전에는 아무 통로가 서지 않았다.
+//
+// 여기서 하는 일은 그 한 가지뿐이다: **후보가 유일할 때만** 역할을 제안한다. 저장하지
+// 않고, Profile 을 고치지 않으며, 둘 이상이면 고르지 않는다 — 고르는 것은 사람의 일이고,
+// 틀린 연결은 없는 연결보다 나쁘다.
+const USABLE = new Set(['AVAILABLE', 'DEGRADED']);
+/**
+ * 선언이 하나도 없을 때만 부른다. 선언이 있으면 그것이 답이고, 여기서 다시 정하지 않는다.
+ */
+export function proposeBindings(plan) {
+    const proposal = { roles: {}, reasons: [], conflicts: [] };
+    const usable = plan.bindings.filter((binding) => USABLE.has(binding.state));
+    const byCapability = new Map();
+    for (const binding of usable) {
+        for (const capability of binding.provides) {
+            byCapability.set(capability, [...(byCapability.get(capability) ?? []), binding]);
+        }
+    }
+    for (const [capability, candidates] of byCapability) {
+        const distinct = new Map(candidates.map((c) => [`${c.adapterId}:${c.resource}`, c]));
+        if (distinct.size !== 1) {
+            proposal.conflicts.push(`${capability}: 후보가 ${distinct.size}개다 (${[...distinct.keys()].join(', ')}) — 어느 쪽인지는 사람이 정한다`);
+            continue;
+        }
+        const only = [...distinct.values()][0];
+        const role = only.role ?? only.adapterId;
+        proposal.roles[capability] = role;
+        proposal.reasons.push(`${capability} ← ${only.adapterId}:${only.resource} (유일한 후보라 제안한다 — Profile 에 저장하지 않는다)`);
+    }
+    return proposal;
+}

package/dist/composition/runtime.d.ts

@@ -42,6 +42,8 @@ export type BuildInput = {
     /** 이 binding이 어느 주소를 가리키는지. 발견 단계가 알아낸 값을 그대로 잇는다. */
     endpointFor?: (binding: ResolvedBinding) => string | undefined;
 };
+/** 이 프로세스가 띄운 도구 자식들을 정리한다. 여러 번 불러도 안전하다. */
+export declare function closeToolClients(): Promise<void>;
 /**
  * capability가 필요한 자리마다 어느 binding이 맡을지 정해 Port를 만든다.
  *