@asc-agent/runtime 0.3.1 → 0.3.2

package/README.md

@@ -7,7 +7,7 @@ proceed-by-default, escalation, audit, the external-write guard, host integratio
 here.
 
 ```bash
-npm install -g @asc-agent/runtime@0.3.1
+npm install -g @asc-agent/runtime@0.3.2
 ```
 
 npm owns the executable link (on Windows, npm's own `asc.cmd`). This package never edits

package/dist/adapters/claude-code/probe.js

@@ -7,6 +7,7 @@
 // 호스트 세션이 자기 도구 목록을 보고 채우는 것은 별도 경로(host-report)다.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { resolveExternalCommand } from "../../core/distribution/external-command.js";
 const run = promisify(execFile);
 export const CAPABILITIES = [
     'cross_session_message',
@@ -26,8 +27,12 @@ export const CAPABILITIES = [
 /** 안전에 필수인 capability — 없으면 degrade가 아니라 STOP이다 (C-03 §5.2). */
 export const SAFETY_CRITICAL = ['external_write_guard'];
 const tryRun = async (command, args) => {
+    // Windows에서 `claude` 는 npm이 만든 `.cmd` shim이라 bare 이름 execFile은
+    // 실패한다 — PATH에 실재하는데 "못 찾았다"가 되는 오판이 실측에서 나왔다.
+    // 실행 형태를 먼저 해석해 세 OS에서 같은 의미로 부른다.
+    const resolved = resolveExternalCommand(command, args);
     try {
-        const { stdout } = await run(command, args, { timeout: 15_000 });
+        const { stdout } = await run(resolved.command, resolved.args, { timeout: 15_000 });
         return { ok: true, stdout };
     }
     catch {

package/dist/adapters/jam/mcp-client.js

@@ -10,6 +10,7 @@
 //   stderr를 프로토콜로 읽지 않는다 — 진단용으로만 쓰고, 그것도 길이를 제한한다
 //   자격 값을 절대 기록하지 않는다 — 이 파일은 토큰을 받지도, 보지도, 남기지도 않는다
 import { spawn } from 'node:child_process';
+import { resolveExternalCommand } from "../../core/distribution/external-command.js";
 const PROTOCOL_VERSION = '2024-11-05';
 /** 진단으로 남길 stderr 최대 길이. 무한히 모으면 그 자체가 새는 곳이 된다. */
 const STDERR_KEEP = 2000;
@@ -30,9 +31,12 @@ export class JamMcpClient {
         if (this.#ready && this.#child)
             return { ok: true, value: { name: '', version: '' } };
         try {
+            // Windows에서 `jam` 은 npm `.cmd` shim이다 — bare 이름 spawn은 ENOENT가 나고
+            // (asc init 실측: "spawn jam ENOENT"), 실행 형태를 해석해야 세 OS에서 같다.
+            const resolved = resolveExternalCommand(this.#deps.command, this.#deps.args ?? []);
             this.#child = this.#deps.spawnProcess
                 ? this.#deps.spawnProcess()
-                : spawn(this.#deps.command, [...(this.#deps.args ?? [])], {
+                : spawn(resolved.command, resolved.args, {
                     stdio: ['pipe', 'pipe', 'pipe'],
                     ...(this.#deps.cwd ? { cwd: this.#deps.cwd } : {}),
                 });

package/dist/cli/asc.js

@@ -64,7 +64,7 @@ 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";
+import { AuditLedger, decisionLines, delegationLine, executionLines, reclaimLine, validationLines, DecisionClass, } from "../core/runtime/audit.js";
 import { ClosureLedger } from "../core/runtime/closure.js";
 import { Orchestrator, renderTick } from "../core/runtime/orchestrator.js";
 import { QueryLedger } from "../core/runtime/query.js";
@@ -159,7 +159,7 @@ const USAGE = `asc — Agent Session Control
   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>...]
+                        [--changed <path>...] [--unresolved <text>...] [--physical <id>]
   asc session list
 
   asc controller collect
@@ -406,10 +406,32 @@ function reportNodeRuntime(check, asJson) {
         console.error(`  ${action.node.version} at ${action.node.path}\n    ${action.display}`);
 }
 export async function runAscCommand(argv, entry = 'runtime') {
-    const { values, positionals } = parseArgs({
+    let parsed;
+    try {
+        parsed = parseArgsOrThrow(argv);
+    }
+    catch (error) {
+        // 모르는 옵션은 사용자 입력 오류다 — Node 스택을 던지면 그때부터 도구를 의심하게 된다.
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Could not read the arguments: ${message.split('\n')[0]}`);
+        console.error('Run `asc --help` for the commands and flags this build understands.');
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    // 실행 중인 버전을 묻는 유일한 공식 통로. 설치 안내가 버전을 핀으로 고정하는데
+    // 정작 지금 도는 것이 무엇인지 물을 방법이 없었다 (SSAFESTA Windows 실측 ASC-1).
+    if (values.version || positionals[0] === 'version') {
+        console.log(RELEASE_VERSION);
+        return 0;
+    }
+    return runParsedCommand(values, positionals, entry, argv);
+}
+function parseArgsOrThrow(argv) {
+    return parseArgs({
         args: argv,
         allowPositionals: true,
         options: {
+            version: { type: 'boolean', default: false },
             root: { type: 'string' },
             parent: { type: 'string' },
             'issued-by': { type: 'string' },
@@ -509,6 +531,8 @@ export async function runAscCommand(argv, entry = 'runtime') {
             help: { type: 'boolean', short: 'h', default: false },
         },
     });
+}
+async function runParsedCommand(values, positionals, entry, argv) {
     const [group, command, target, extra] = positionals;
     if (values.help || group === undefined) {
         console.log(USAGE);
@@ -612,7 +636,7 @@ export async function runAscCommand(argv, entry = 'runtime') {
         return runFreeze(group, command, values, store);
     switch (command) {
         case 'list': {
-            const items = await operator.list({ all: values.all, ...(priority ? { priority } : {}) });
+            const items = await operator.list({ all: Boolean(values.all), ...(priority ? { priority } : {}) });
             console.log(values.json ? JSON.stringify(items, null, 2) : renderer.renderList(items).text);
             return 0;
         }
@@ -1150,6 +1174,9 @@ async function detectSetupState(values, entry) {
     const { root: projectRoot, git } = await discoverProjectRoot(process.cwd());
     const resolution = await resolveRoot(process.cwd(), values.root);
     const ascRoot = resolution.kind === 'UNRESOLVED' ? undefined : resolution.root;
+    // 디렉터리가 있다고 붙은 것이 아니다 — profile.lock까지 서야 붙은 것이다. 빈 skeleton을
+    // "붙어 있음"으로 넘기면 plan이 applied를 답하며 실패할 proceed를 준다 (실측 ASC-2).
+    const attachmentBroken = ascRoot ? (await inspectSetup(ascRoot)).attachment === 'BROKEN' : false;
     const scope = values.scope === 'project' ? 'project' : 'local';
     const hostReport = await verifyInstall(defaultPaths());
     return {
@@ -1157,6 +1184,7 @@ async function detectSetupState(values, entry) {
         projectRoot,
         git,
         ...(ascRoot ? { ascRoot } : {}),
+        ...(attachmentBroken ? { attachmentBroken } : {}),
         ...(values.profile ? { requestedProfile: values.profile } : {}),
         profileCandidates: await availableProfiles(installRoot(), externalProfileRoot()),
         scope,
@@ -2345,9 +2373,16 @@ async function runSession(command, target, values, store, resolved) {
     const at = new Date().toISOString();
     switch (command) {
         case 'issue': {
+            // 누락과 오값은 다른 실수다 — "필수"라고 답하면 이미 준 사람은 자기가 무엇을
+            // 틀렸는지 모른다 (SSAFESTA Windows 실측 ASC-3).
+            const roleChoices = SessionRole.options.join('|');
+            if (values.role === undefined || !values.goal) {
+                console.error(`--role and --goal are required (role: ${roleChoices})`);
+                return 2;
+            }
             const role = SessionRole.safeParse(values.role);
-            if (!role.success || !values.goal) {
-                console.error('--role and --goal are required (role: planner|researcher|implementer|verifier)');
+            if (!role.success) {
+                console.error(`'${String(values.role)}' is not a role this build knows — choose one of: ${roleChoices}`);
                 return 2;
             }
             const authority = parseAuthority(values.authority);
@@ -2407,12 +2442,19 @@ async function runSession(command, target, values, store, resolved) {
                 console.error('At least one --evidence and one --why are required (C-13 §4).');
                 return 2;
             }
+            // 오값을 Core까지 흘리면 ZodError 원문이 사람에게 떨어진다 (실측 ASC-5).
+            // 사용자 입력 검증은 Surface의 몫이다 — 여기서 고를 수 있는 값을 그대로 준다.
+            const parsedClass = DecisionClass.safeParse(decisionClass);
+            if (!parsedClass.success) {
+                console.error(`'${decisionClass}' is not a decision class — choose one of: ${DecisionClass.options.join(', ')}`);
+                return 2;
+            }
             const audit = auditLedger(store);
             const recorded = await audit.decide({
                 sessionId: target,
                 actor: values.as ?? values.principal ?? '(미상)',
                 ownership: values.ownership ?? [],
-                class: decisionClass,
+                class: parsedClass.data,
                 evidenceRefs: [evidence[0], ...evidence.slice(1)],
                 selectedOption: selected,
                 alternatives: values.alternative ?? [],

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

@@ -14,6 +14,14 @@ export type SetupState = {
     git: boolean;
     /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */
     ascRoot?: string;
+    /**
+     * runtime 디렉터리는 있는데 profile.lock을 읽지 못하는 상태 — 붙이다 만 것이다.
+     *
+     * 이것을 "붙어 있음"으로 읽으면 plan은 `applied`를 답하면서 실패할 `asc proceed`를
+     * 다음 행동으로 준다 (SSAFESTA Windows 실측 ASC-2: 파일 잠금이 빈 skeleton만 남긴
+     * 경우). 붙이다 만 상태는 붙일 것이 남은 상태다 — repair가 plan에 드러나야 한다.
+     */
+    attachmentBroken?: boolean;
     /** 붙어 있다면 무엇으로 붙었는가. */
     attachedProfile?: string;
     /** 사람이 `--profile` 로 지정한 것. */

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

@@ -17,7 +17,9 @@ export function computeSetupPlan(state) {
     const evidence = [
         `project=${state.projectRoot}`,
         state.git ? 'git=yes' : 'git=no',
-        state.ascRoot ? `attached=${state.ascRoot}` : 'attached=no',
+        state.ascRoot
+            ? `attached=${state.ascRoot}${state.attachmentBroken ? ' (BROKEN — profile.lock unreadable)' : ''}`
+            : 'attached=no',
         `scope=${state.scope}`,
     ];
     // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
@@ -76,7 +78,7 @@ export function computeSetupPlan(state) {
             changes.push({ target: 'host-install', host: host.id, from: host.status });
         }
     }
-    if (state.ascRoot) {
+    if (state.ascRoot && !state.attachmentBroken) {
         // 붙어 있어도 **무엇을 고를 수 있었는지**는 사실이다. 사용자 소유 Profile을 새로 놓고
         // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
         if (state.profileCandidates.length > 0) {
@@ -84,7 +86,8 @@ export function computeSetupPlan(state) {
         }
         return finish(changes, evidence, state, mode, command);
     }
-    // 아직 안 붙었다. 무엇으로 붙을지는 사람이 정한다.
+    // 아직 안 붙었거나, 붙이다 말았다(BROKEN). 무엇으로 붙을지는 사람이 정한다 —
+    // BROKEN이면 같은 선택으로 다시 붙이는 것이 repair다.
     const profile = state.requestedProfile ?? soleCandidate(state.profileCandidates);
     if (!profile) {
         evidence.push(`profile candidates=${state.profileCandidates.join(', ') || '(none)'}`);

package/dist/core/distribution/external-command.d.ts

@@ -0,0 +1,22 @@
+export type ResolvedInvocation = {
+    command: string;
+    args: string[];
+};
+export type ResolveDeps = {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    /** 테스트 주입용 — 실제 파일시스템을 보지 않게 한다. */
+    exists?: (path: string) => boolean;
+    readText?: (path: string) => string | null;
+    nodePath?: string;
+};
+/**
+ * npm `.cmd` shim이 가리키는 JS 진입점.
+ *
+ * npm이 쓰는 shim은 두 세대가 있고 둘 다 `"%dp0%\<상대경로>" %*` 형태로 JS를 부른다:
+ *   "%_prog%"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ *   "%dp0%\node.exe"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ * 형태가 다르면 null — 아는 척하지 않고 cmd.exe 경로로 넘어간다.
+ */
+export declare function shimTarget(shimText: string): string | null;
+export declare function resolveExternalCommand(command: string, args: readonly string[], deps?: ResolveDeps): ResolvedInvocation;

package/dist/core/distribution/external-command.js

@@ -0,0 +1,79 @@
+// 바깥 CLI를 Windows에서도 실제로 찾아 부른다 (C-14 §11의 연장).
+//
+// Node는 보안 수정 이후 shell 없이 `.cmd` 를 실행하지 않는다. 그런데 npm이 전역 설치로
+// 만들어 주는 명령은 Windows에서 전부 `.cmd` shim이다 — bare 이름을 Unix 방식으로만
+// spawn하면 ENOENT/EINVAL이 나고, 호출자는 "설치돼 있지 않다"고 오판한다
+// (SSAFESTA Windows 실측: shim이 PATH에 실재하는데 host probe가 not found →
+// external_write_guard STOP까지 이어졌다).
+//
+// shell을 켜는 것은 답이 아니다 — 인자가 escape 없이 이어붙는다(DEP0190). 대신:
+//   ① PATH에서 `.exe` 를 찾으면 그대로 부른다 (shell 불필요).
+//   ② `.cmd` shim이면 그 안이 가리키는 JS 진입점을 읽어 지금 도는 node로 직접 부른다 —
+//      cli/asc.ts의 npm 해석(resolveCommand)과 같은 태도다.
+//   ③ shim을 못 읽으면 cmd.exe /d /c 로 그 .cmd 를 부른다 — cmd.exe는 진짜 실행 파일이라
+//      shell 옵션이 필요 없다.
+// 셋 다 실패하면 이름 그대로 돌려준다 — PATH에 진짜 실행 파일이 있는 환경이 그 경우다.
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter as winDelimiter, dirname, extname, isAbsolute, join } from 'node:path/win32';
+const defaultRead = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * npm `.cmd` shim이 가리키는 JS 진입점.
+ *
+ * npm이 쓰는 shim은 두 세대가 있고 둘 다 `"%dp0%\<상대경로>" %*` 형태로 JS를 부른다:
+ *   "%_prog%"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ *   "%dp0%\node.exe"  "%dp0%\node_modules\<pkg>\<bin>.js" %*
+ * 형태가 다르면 null — 아는 척하지 않고 cmd.exe 경로로 넘어간다.
+ */
+export function shimTarget(shimText) {
+    const match = /"%dp0%\\([^"%]+\.(?:js|mjs|cjs))"/i.exec(shimText);
+    return match ? match[1] : null;
+}
+export function resolveExternalCommand(command, args, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== 'win32')
+        return { command, args: [...args] };
+    // 경로나 확장자를 이미 갖췄으면 호출자가 알고 부르는 것이다 — 손대지 않는다.
+    if (isAbsolute(command) || command.includes('/') || command.includes('\\') || extname(command) !== '') {
+        return { command, args: [...args] };
+    }
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const readText = deps.readText ?? defaultRead;
+    const nodePath = deps.nodePath ?? process.execPath;
+    const pathValue = env.PATH ?? env.Path ?? '';
+    let firstShim = null;
+    for (const dir of pathValue.split(winDelimiter)) {
+        if (!dir)
+            continue;
+        const exe = join(dir, `${command}.exe`);
+        if (exists(exe))
+            return { command: exe, args: [...args] };
+        if (!firstShim) {
+            for (const ext of ['.cmd', '.bat']) {
+                const shim = join(dir, `${command}${ext}`);
+                if (exists(shim)) {
+                    firstShim = shim;
+                    break;
+                }
+            }
+        }
+    }
+    if (firstShim) {
+        const text = readText(firstShim);
+        const target = text ? shimTarget(text) : null;
+        if (target) {
+            const script = join(dirname(firstShim), target);
+            if (exists(script))
+                return { command: nodePath, args: [script, ...args] };
+        }
+        return { command: 'cmd.exe', args: ['/d', '/c', firstShim, ...args] };
+    }
+    return { command, args: [...args] };
+}

package/dist/core/distribution/release.d.ts

@@ -1,9 +1,9 @@
 export declare const RUNTIME_PACKAGE = "@asc-agent/runtime";
 export declare const BOOTSTRAP_PACKAGE = "@asc-agent/bootstrap";
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export declare const RELEASE_VERSION = "0.3.1";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.3.1";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.3.1";
+export declare const RELEASE_VERSION = "0.3.2";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.3.2";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.3.2";
 /**
  * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
  *

package/dist/core/distribution/release.js

@@ -9,7 +9,7 @@
 export const RUNTIME_PACKAGE = '@asc-agent/runtime';
 export const BOOTSTRAP_PACKAGE = '@asc-agent/bootstrap';
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export const RELEASE_VERSION = '0.3.1';
+export const RELEASE_VERSION = '0.3.2';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**

package/dist/core/operator/progress.js

@@ -76,7 +76,9 @@ export class ProgressService {
             return {
                 ok: false,
                 reason: 'NOT_OWNER',
-                detail: `${logicalSessionId} 에 Runtime이 붙어 있지 않다 — 먼저 소유권을 주장하라`,
+                // "주장하라"만으로는 다음 명령을 모른다 — 복구 명령까지가 오류 메시지다 (실측 ASC-4).
+                // Core는 host 이름을 모른다(B-17) — 자리만 비워 두면 Surface가 채운다.
+                detail: `${logicalSessionId} 에 Runtime이 붙어 있지 않다 — 먼저 소유권을 주장하라: asc host <host> bind ${logicalSessionId} --physical <id>`,
             };
         }
         if (binding.physicalSessionId !== physicalSessionId) {

package/dist/core/runtime/session.js

@@ -70,7 +70,12 @@ export class SessionRuntime {
             return {
                 ok: false,
                 reason: 'NOT_OWNER',
-                detail: `${id} 에는 Runtime이 붙어 있다 — owner(${binding.physicalSessionId})만 기록할 수 있다`,
+                // owner가 누구인지만 말하면 owner 본인도 다음 명령을 모른다 — pause/done은
+                // `--physical <owner>` 로 자격을 대고, 아니면 소유권을 먼저 놓는다 (실측 ASC-6).
+                // Core는 host 이름을 모른다(B-17) — `<host>` 자리는 Surface의 어휘다.
+                detail: `${id} 에는 Runtime이 붙어 있다 — owner(${binding.physicalSessionId})만 기록할 수 있다. ` +
+                    `owner라면 --physical ${binding.physicalSessionId} 을 붙여 다시 실행하고, ` +
+                    `그 세션이 끝났다면 asc host <host> release ${id} --physical ${binding.physicalSessionId} 로 소유권을 놓아라`,
             };
         }
         if (binding.physicalSessionId !== physicalSessionId) {

package/dist/core/workspace/resolve.js

@@ -66,7 +66,13 @@ async function findProjectLocal(start, stopAt, exists) {
         // 정지선 자체는 보지 않는다 — 홈의 `.asc` 는 user runtime이지 프로젝트 상태가 아니다
         if (boundary && normalized === boundary)
             return null;
-        if (await exists(join(dir, ASC_DIR)))
+        const candidate = join(dir, ASC_DIR);
+        // 정지선이 홈이어도 **다른 홈**의 `.asc` 는 걸러지지 않는다. Windows는 temp
+        // 디렉터리가 사용자 프로필 아래라, temp의 프로젝트에서 위로 걷다 실사용자
+        // `~/.asc` 를 프로젝트 상태로 오인했다 (SSAFESTA 실측 — setup status가
+        // UNATTACHED 대신 BROKEN을 답한 원인). user runtime은 내용으로 알아본다:
+        // workspaces/·profiles/·runtime.json 은 홈에만 생긴다.
+        if ((await exists(candidate)) && !(await looksLikeUserRuntime(candidate, exists)))
             return dir;
         const parent = dirname(dir);
         if (parent === dir)
@@ -74,6 +80,14 @@ async function findProjectLocal(start, stopAt, exists) {
         dir = parent;
     }
 }
+/** `~/.asc` 꼴인가 — 프로젝트 부착이 아니라 이 기계의 user runtime 홈인가. */
+async function looksLikeUserRuntime(ascDir, exists) {
+    for (const marker of ['workspaces', 'profiles', 'runtime.json']) {
+        if (await exists(join(ascDir, marker)))
+            return true;
+    }
+    return false;
+}
 /** 사람이 읽는 한 줄. 왜 그 뿌리인지가 함께 와야 사람이 틀린 결합을 알아챈다. */
 export function resolutionLine(resolution) {
     switch (resolution.kind) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asc-agent/runtime",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "ASC (Agent Session Control) \u2014 local-first human-in-the-loop agent control plane: core, CLI, and adapters",
   "keywords": [
     "agent",