@capstone-nomos/cli 0.1.0

package/dist/executor/cli.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// Executor — 팀원 노트북에서 도는 프로그램. npm 패키지 @capstone-nomos/cli로 배포된다(bin: nomos).
+// 서버 주소는 ~/.nomos/credentials의 baseUrl에서 온다.
+//
+//   nomos connect [--server 주소] [--name 이름]
+//                              웹 안내의 한 줄. 로그인(필요하면) → 배정 대기(자동 재발급) → start. --server 기본은 운영 주소.
+//   nomos doctor [--json]      git·claude·자격 증명·MCP 서버 파일 점검
+//   nomos login [baseUrl] [--name 이름] [--connect-key]
+//                              브라우저 승인으로 연결해 자격 증명을 새로 쓴다(기본). 브라우저가 없는 환경(SSH)은
+//                              --connect-key 또는 NOMOS_CONNECT_KEY로 가입 때 받은 연결 키를 쓴다.
+//   executor refresh           토큰 재발급 (프로젝트에 배정된 뒤 한 번)
+//   executor once              READY 태스크 하나만 처리하고 종료 (개발·데모용)
+//   executor start             10초 폴링
+//   executor clean             worktree 정리
+//
+// 서버를 옮길 때 baseUrl만 바꾸면 안 된다. 토큰은 발급한 서버의 서명 키와 그 DB의 agents 행에 묶여 있어
+// 다른 서버에서는 전부 401이다. 원격에 가입해 받은 연결 키로 login을 다시 해야 한다.
+import { writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { buildMcpConfig } from '../bridge/claude-args.js';
+import { credentialsPath, readCredentials, updateAccessToken, writeCredentials, } from '../bridge/credentials.js';
+import { NomosClient } from '../bridge/nomos-client.js';
+import { connect, DEFAULT_SERVER, serverCalls } from './connect.js';
+import { deviceLogin } from './device-login.js';
+import { cliVersion, mcpServerPath } from './paths.js';
+import { checkTools } from './preflight.js';
+import { buildTaskPrompt } from './prompt.js';
+import { runClaude } from './runner.js';
+import { pollingTaskSource } from './task-source.js';
+import { runLint, runSpecTests } from './verify.js';
+import { ensureRepo } from './repo-checkout.js';
+import { cleanWorkspaces, headSha, prepareWorkspace } from './workspace.js';
+const POLL_INTERVAL_MS = 10_000;
+function log(line) {
+    process.stdout.write(`[nomos] ${line}\n`);
+}
+function createClient() {
+    const credentials = readCredentials();
+    if (!credentials) {
+        throw new Error(`${credentialsPath()}가 없습니다. 먼저 connect(또는 login)를 실행하세요`);
+    }
+    return new NomosClient({
+        baseUrl: credentials.baseUrl,
+        tokens: { accessToken: credentials.accessToken, refreshToken: credentials.refreshToken },
+        // 재발급 결과를 파일에 되돌려 쓴다. 없으면 다음 실행이 또 401로 시작한다.
+        onTokensChanged: (tokens) => updateAccessToken(tokens.accessToken),
+    });
+}
+async function handleTask(client, projectId, task) {
+    log(`태스크 ${task.id} — ${task.title}`);
+    const briefing = (await client.getBriefing(task.id));
+    // cloneUrl이 없는 옛 서버(브리핑에 필드 자체가 없음)도 github.com/{fullName}으로 받는다.
+    const checkout = ensureRepo({ fullName: briefing.repo.fullName, cloneUrl: briefing.repo.cloneUrl ?? null }, { log });
+    const workspace = prepareWorkspace({
+        repoPath: checkout.path,
+        projectId,
+        taskId: task.id,
+        branchName: briefing.task.branchName,
+        // CLI가 관리하는 클론은 방금 fetch한 origin/<기본 브랜치>에서 분기한다.
+        baseBranch: checkout.baseRef(briefing.repo.defaultBranch),
+        settings: briefing.claudeSettings,
+        policyHash: briefing.policyHash,
+    });
+    log(`작업공간 ${workspace.dir} (브랜치 ${workspace.branch})`);
+    if (workspace.createdBranch) {
+        await client.reportBranch(task.id, workspace.branch);
+    }
+    // MCP 설정은 작업공간마다 둔다. 비밀값은 없다 — 자격 증명은 ~/.nomos/credentials가 정본이다.
+    const mcpConfigPath = path.join(workspace.dir, '.nomos-mcp.json');
+    writeFileSync(mcpConfigPath, 
+    // 작업공간 경로를 넘겨야 submit_artifact가 이 worktree의 태스크 브랜치를 push한다.
+    buildMcpConfig({ serverPath: mcpServerPath(), workspaceDir: workspace.dir }));
+    const before = headSha(workspace.dir);
+    const result = await runClaude({
+        workspaceDir: workspace.dir,
+        prompt: buildTaskPrompt(briefing, workspace.branch),
+        mcpConfigPath,
+    });
+    const committed = headSha(workspace.dir) !== before;
+    // 자동 재시도는 넣지 않는다. tasks.retry_count는 서버가 관리하는 값이고,
+    // Executor가 멋대로 돌리면 M4(재작업률)가 오염된다.
+    if (result.outcome === 'completed' && committed) {
+        log(`완료 (${Math.round(result.durationMs / 1000)}초). 커밋 있음 — 제출은 모델이 이미 했을 것`);
+        await reportBridgeStages(client, task.id, workspace.dir, briefing.specTests);
+    }
+    else if (result.outcome === 'completed') {
+        log(`정상 종료했지만 커밋이 없다. 태스크는 그대로 둔다. 로그: ${result.logPath}`);
+    }
+    else if (result.outcome === 'timeout') {
+        log(`30분 초과로 종료했다. 재시도하지 않는다. 로그: ${result.logPath}`);
+    }
+    else {
+        log(`비정상 종료 (exit=${result.exitCode}). 재시도하지 않는다. 로그: ${result.logPath}`);
+    }
+}
+// 모델이 submit_artifact를 불렀다면 산출물이 생겼을 것이다. 그 위에 V2·V4를 얹는다.
+// 제출이 없으면(모델이 도구를 안 불렀거나 거부당했으면) 붙일 곳이 없으므로 건너뛴다.
+async function reportBridgeStages(client, taskId, workspaceDir, specTests) {
+    const [latest] = await client.listArtifacts(taskId);
+    if (!latest) {
+        log('산출물이 없다 — V2·V4를 붙일 곳이 없어 건너뛴다');
+        return;
+    }
+    const artifactId = String(latest.id);
+    const reports = [
+        await runSpecTests(workspaceDir, specTests),
+        await runLint(workspaceDir),
+    ];
+    for (const report of reports) {
+        log(`${report.stage} ${report.result} (${Math.round(report.durationMs / 1000)}초)`);
+        try {
+            const summary = (await client.reportVerification(artifactId, report));
+            log(`  보고됨 — 결론 ${summary.outcome ?? '?'} / 태스크 ${summary.taskState ?? '?'}`);
+        }
+        catch (err) {
+            // 보고 실패로 작업 자체를 되돌리지 않는다. 서버에는 아직 결과가 없으므로
+            // 태스크는 VERIFYING에 머물고, 사람이 보면 무엇이 빠졌는지 알 수 있다.
+            log(`  보고 실패: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+async function once() {
+    const client = createClient();
+    const self = await client.describeSelf();
+    const source = pollingTaskSource(client, self.projectId);
+    const [task] = await source.nextTasks(1);
+    if (!task) {
+        log('READY 태스크가 없다');
+        return;
+    }
+    await handleTask(client, self.projectId, task);
+}
+async function start() {
+    const client = createClient();
+    const self = await client.describeSelf();
+    const source = pollingTaskSource(client, self.projectId);
+    log(`시작 — 프로젝트 ${self.projectId}, 역할 ${self.teamRole}, 동시 실행 ${self.maxConcurrent} (${source.kind})`);
+    const inFlight = new Set();
+    for (;;) {
+        try {
+            const capacity = self.maxConcurrent - inFlight.size;
+            if (capacity > 0) {
+                for (const task of await source.nextTasks(capacity)) {
+                    // 이미 처리 중인 태스크는 건너뛴다. 폴링은 같은 목록을 여러 번 준다.
+                    if (inFlight.has(task.id))
+                        continue;
+                    inFlight.add(task.id);
+                    void handleTask(client, self.projectId, task)
+                        .catch((err) => log(`태스크 ${task.id} 실패: ${err instanceof Error ? err.message : String(err)}`))
+                        .finally(() => inFlight.delete(task.id));
+                }
+            }
+        }
+        catch (err) {
+            log(`폴링 실패: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+}
+// 토큰이 헤더로 다니므로 원격은 https만 받는다. 로컬 개발 서버만 예외다.
+function normalizeBaseUrl(raw) {
+    const url = new URL(raw ?? DEFAULT_SERVER);
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !local) {
+        throw new Error(`원격 서버는 https여야 한다: ${raw}`);
+    }
+    return url.origin;
+}
+async function postJson(url, body) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || !json.data) {
+        throw new Error(`${res.status} ${json.error?.code ?? ''} ${json.error?.message ?? ''}`.trim());
+    }
+    return json.data;
+}
+function parseArgs(argv) {
+    const out = { positional: undefined, server: undefined, name: undefined, connectKey: false, json: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--name')
+            out.name = argv[(i += 1)];
+        else if (arg === '--server')
+            out.server = argv[(i += 1)];
+        else if (arg === '--connect-key')
+            out.connectKey = true;
+        else if (arg === '--json')
+            out.json = true;
+        else
+            out.positional ??= arg;
+    }
+    return out;
+}
+// 서버에 붙어 ~/.nomos/credentials를 새로 쓴다. 기본은 브라우저 승인,
+// 연결 키를 명시했거나(--connect-key) 환경변수로 줬으면 기존 경로(SSH 등 브라우저가 없는 환경).
+async function loginTo(baseUrl, agentName, viaConnectKey) {
+    if (!viaConnectKey && process.env.NOMOS_CONNECT_KEY === undefined) {
+        const { credentials, account } = await deviceLogin({ baseUrl, agentName });
+        writeCredentials(credentials);
+        // 연결된 계정을 반드시 보여 준다 — 내가 아닌 계정이면 누군가 내 코드를 승인한 것이다.
+        const org = account.orgName ? ` · 조직 ${account.orgName}` : ' · 조직 없음';
+        log(`연결됨: ${account.nickname ?? account.loginId ?? '?'} (${account.loginId ?? '?'})${org} — 에이전트 ${agentName}`);
+        log(`${credentialsPath()}에 저장했다. 내 계정이 아니면 바로 웹에서 이 에이전트를 확인하라.`);
+        return;
+    }
+    // 연결 키는 NOMOS_CONNECT_KEY로도 받는다 — 인자로 받으면 셸 기록에 남는다.
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const connectKey = (process.env.NOMOS_CONNECT_KEY ?? (await rl.question('연결 키 (가입할 때 받은 값): '))).trim();
+        rl.close();
+        const data = await postJson(`${baseUrl}/api/agents/connect`, {
+            connectKey,
+            agentName,
+            harness: 'claude-code',
+            skills: [],
+            maxConcurrent: 2,
+        });
+        writeCredentials({
+            baseUrl,
+            accessToken: String(data.accessToken),
+            refreshToken: String(data.refreshToken),
+            agentId: String(data.agentId),
+        });
+        log(`${credentialsPath()}에 저장했다 (에이전트 ${String(data.agentId)})`);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function login(argv) {
+    const args = parseArgs(argv);
+    const baseUrl = normalizeBaseUrl(args.positional ?? args.server);
+    const previous = readCredentials();
+    if (previous && previous.baseUrl !== baseUrl) {
+        log(`기존 자격 증명(${previous.baseUrl})을 ${baseUrl}용으로 교체한다`);
+    }
+    await loginTo(baseUrl, args.name?.trim() || os.hostname(), args.connectKey);
+    log('대표에게 이 에이전트를 프로젝트에 배정해 달라고 한 뒤 connect를 실행하라(배정되면 자동으로 시작한다)');
+}
+async function connectCommand(argv) {
+    const args = parseArgs(argv);
+    const server = normalizeBaseUrl(args.server ?? args.positional ?? process.env.NOMOS_SERVER);
+    const agentName = args.name?.trim() || os.hostname();
+    log(`NOMOS CLI ${cliVersion()} — 서버 ${server}`);
+    const missing = checkTools().filter((t) => !t.ok);
+    if (missing.length > 0) {
+        for (const t of missing)
+            log(`${t.name}을 실행할 수 없다: ${t.detail}\n        → ${t.hint}`);
+        throw new Error('필요한 도구가 없어 시작하지 않는다');
+    }
+    await connect({
+        server,
+        agentName,
+        readCredentials,
+        login: () => loginTo(server, agentName, args.connectKey),
+        ...serverCalls({ read: readCredentials, updateAccessToken }),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        log,
+    });
+    await start();
+}
+async function doctor(argv) {
+    const { json } = parseArgs(argv);
+    let mcp;
+    try {
+        mcp = { ok: true, detail: mcpServerPath() };
+    }
+    catch (err) {
+        mcp = { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+    let server = null;
+    try {
+        server = readCredentials()?.baseUrl ?? null;
+    }
+    catch {
+        server = null;
+    }
+    const report = { version: cliVersion(), node: process.version, mcpServer: mcp, tools: checkTools(), server };
+    if (json) {
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        log(`버전 ${report.version} (node ${report.node})`);
+        log(`MCP 서버: ${mcp.ok ? 'OK' : '없음'} — ${mcp.detail}`);
+        for (const t of report.tools)
+            log(`${t.name}: ${t.ok ? t.detail : `없음 — ${t.hint}`}`);
+        log(`연결된 서버: ${server ?? '없음 (connect를 실행하라)'}`);
+    }
+    // 패키지 자체가 깨진 경우만 실패로 끝낸다. git·claude가 없는 건 안내로 충분하다.
+    if (!mcp.ok)
+        process.exitCode = 1;
+}
+// 배정 전에 받은 토큰에는 project_id가 없다. 배정 뒤 한 번 재발급해야 태스크 API를 쓸 수 있다.
+async function refresh() {
+    const credentials = readCredentials();
+    if (!credentials)
+        throw new Error(`${credentialsPath()}가 없다. 먼저 connect(또는 login)를 실행하라`);
+    const data = await postJson(`${credentials.baseUrl}/api/agents/token/refresh`, { refreshToken: credentials.refreshToken });
+    updateAccessToken(String(data.accessToken));
+    try {
+        const self = await createClient().describeSelf();
+        log(`재발급 완료 — 프로젝트 ${self.projectId}, 역할 ${self.teamRole ?? '없음'}`);
+    }
+    catch (err) {
+        log(`재발급은 됐지만 아직 프로젝트에 배정되지 않은 것 같다: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function main() {
+    const command = process.argv[2];
+    if (command === 'connect')
+        return connectCommand(process.argv.slice(3));
+    if (command === 'doctor')
+        return doctor(process.argv.slice(3));
+    if (command === '--version' || command === '-v' || command === 'version') {
+        process.stdout.write(`${cliVersion()}\n`);
+        return;
+    }
+    if (command === 'login')
+        return login(process.argv.slice(3));
+    if (command === 'refresh')
+        return refresh();
+    if (command === 'once')
+        return once();
+    if (command === 'start')
+        return start();
+    if (command === 'clean') {
+        const { pruned, removed } = cleanWorkspaces();
+        log(`worktree prune: ${pruned.join(', ') || '없음'} / 삭제: ${removed ?? '없음'}`);
+        return;
+    }
+    process.stderr.write([
+        '사용법: nomos <명령>',
+        '  connect [--server 주소] [--name 이름]        로그인 → 배정 대기 → 작업 시작 (처음이라면 이것만)',
+        '  doctor                                       설치 상태 점검',
+        '  login [주소] [--name 이름] [--connect-key]   로그인만',
+        '  refresh | once | start | clean | --version',
+        '',
+    ].join('\n'));
+    process.exitCode = 1;
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/executor/connect.js

@@ -0,0 +1,74 @@
+// nomos connect — 웹 안내 한 줄(npx @capstone-nomos/cli connect)로 끝까지 가게 한다.
+//   자격 증명 없음·다른 서버 것·더 이상 안 통함 → 브라우저 승인 로그인
+//   프로젝트 배정 전 → 안내하고 주기적으로 토큰을 재발급해 배정을 확인(사람이 하던 executor refresh를 자동으로)
+//   배정됨 → 호출부가 start(폴링)로 넘어간다
+// 테스트할 수 있게 입출력은 전부 바깥에서 받는다.
+export const DEFAULT_SERVER = 'https://nomos-team.duckdns.org';
+export async function connect(deps) {
+    const current = deps.readCredentials();
+    if (!current || current.baseUrl !== deps.server) {
+        if (current)
+            deps.log(`기존 자격 증명(${current.baseUrl})을 ${deps.server}용으로 교체한다`);
+        await deps.login();
+    }
+    else if ((await deps.refresh()) === 'rejected') {
+        deps.log('저장된 자격 증명이 더 이상 통하지 않는다 — 다시 로그인한다');
+        await deps.login();
+    }
+    let announced = false;
+    for (;;) {
+        const self = await deps.describeSelf();
+        if (self) {
+            deps.log(`배정 확인 — 프로젝트 ${self.projectId}, 역할 ${self.teamRole ?? '없음'}`);
+            return self;
+        }
+        if (!announced) {
+            deps.log(`아직 프로젝트에 배정되지 않았다. 대표에게 에이전트 "${deps.agentName}"의 배정을 요청하라.`);
+            deps.log('배정되면 자동으로 시작한다 — 이 창을 켜 두면 된다 (Ctrl+C로 종료)');
+            announced = true;
+        }
+        await deps.sleep(deps.intervalMs ?? 15_000);
+        // 배정 전에 받은 토큰에는 project_id가 없다. 재발급해야 배정이 토큰에 실린다.
+        if ((await deps.refresh()) === 'rejected') {
+            deps.log('자격 증명이 거부됐다 — 다시 로그인한다');
+            await deps.login();
+        }
+    }
+}
+export function serverCalls(store, fetchImpl = fetch) {
+    return {
+        // 4xx는 "이 자격 증명은 더 이상 안 통한다"(지워진 에이전트·다른 서버 DB) — 다시 로그인할 일이다. 5xx·네트워크 오류는 throw.
+        async refresh() {
+            const credentials = store.read();
+            if (!credentials)
+                return 'rejected';
+            const res = await fetchImpl(`${credentials.baseUrl}/api/agents/token/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refreshToken: credentials.refreshToken }),
+            });
+            if (res.status >= 400 && res.status < 500)
+                return 'rejected';
+            const json = (await res.json().catch(() => ({})));
+            if (!res.ok || !json.data?.accessToken)
+                throw new Error(`토큰 재발급 실패: ${res.status}`);
+            store.updateAccessToken(json.data.accessToken);
+            return 'ok';
+        },
+        // 방금 재발급한 토큰으로 묻는다. 배정 전이면 서버가 403 NOT_PROJECT_MEMBER — null.
+        async describeSelf() {
+            const credentials = store.read();
+            if (!credentials)
+                throw new Error('자격 증명이 없다');
+            const res = await fetchImpl(`${credentials.baseUrl}/api/agents/me`, {
+                headers: { Authorization: `Bearer ${credentials.accessToken}` },
+            });
+            const json = (await res.json().catch(() => ({})));
+            if (res.status === 403 && json.error?.code === 'NOT_PROJECT_MEMBER')
+                return null;
+            if (!res.ok || !json.data)
+                throw new Error(`${res.status} ${json.error?.code ?? ''} ${json.error?.message ?? ''}`.trim());
+            return json.data;
+        },
+    };
+}

package/dist/executor/device-login.js

@@ -0,0 +1,85 @@
+import { spawn } from 'node:child_process';
+export class DeviceLoginError extends Error {
+}
+async function post(fetchImpl, url, body) {
+    const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || !json.data) {
+        throw new DeviceLoginError(`${res.status} ${json.error?.code ?? ''} ${json.error?.message ?? ''}`.trim());
+    }
+    return json.data;
+}
+// 브라우저 열기. shell을 쓰지 않는다(Windows에서 shell: true면 URL의 & 등이 명령으로 해석된다 — runner.ts와 같은 이유).
+// 실패해도 괜찮다 — 출력한 주소를 사용자가 직접 연다.
+export function openInBrowser(url) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+            : ['xdg-open', [url]];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { stdio: 'ignore', detached: true });
+            child.once('error', () => resolve(false));
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+export async function deviceLogin(deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const openUrl = deps.openUrl ?? openInBrowser;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const out = deps.out ?? ((line) => process.stdout.write(`${line}\n`));
+    const started = await post(fetchImpl, `${deps.baseUrl}/api/agents/device/start`, {
+        agentName: deps.agentName,
+        harness: 'claude-code',
+        skills: [],
+        maxConcurrent: 2,
+    });
+    const deviceCode = String(started.deviceCode);
+    const complete = String(started.verificationUriComplete);
+    let intervalSec = Number(started.interval) || 5;
+    const deadline = Date.now() + (Number(started.expiresIn) || 600) * 1000;
+    out(`브라우저에서 승인하세요: ${complete}`);
+    out(`코드: ${String(started.userCode)}   (웹 화면의 코드와 같은지 확인하세요)`);
+    if (!(await openUrl(complete)))
+        out('브라우저를 열지 못했습니다 — 위 주소를 직접 여세요.');
+    while (Date.now() < deadline) {
+        await sleep(intervalSec * 1000);
+        const polled = await post(fetchImpl, `${deps.baseUrl}/api/agents/device/poll`, { deviceCode });
+        switch (polled.status) {
+            case 'pending':
+                continue;
+            case 'slow_down':
+                intervalSec = Number(polled.interval) || intervalSec + 5;
+                continue;
+            case 'denied':
+                throw new DeviceLoginError('승인이 거부됐습니다. 직접 실행한 게 맞다면 login을 다시 실행하세요.');
+            case 'expired':
+                throw new DeviceLoginError('코드가 만료됐습니다(10분). login을 다시 실행하세요.');
+            case 'approved':
+                return {
+                    credentials: {
+                        baseUrl: deps.baseUrl,
+                        accessToken: String(polled.accessToken),
+                        refreshToken: String(polled.refreshToken),
+                        agentId: String(polled.agentId),
+                    },
+                    account: polled.account,
+                };
+            default:
+                throw new DeviceLoginError(`알 수 없는 응답: ${JSON.stringify(polled)}`);
+        }
+    }
+    throw new DeviceLoginError('코드가 만료됐습니다(10분). login을 다시 실행하세요.');
+}

package/dist/executor/paths.js

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// 이 CLI는 npm 패키지(@capstone-nomos/cli)로 배포되어 **아무 폴더에서나** 실행된다.
+// 그래서 파일 위치는 실행 폴더(process.cwd())가 아니라 이 파일 위치(import.meta.url) 기준으로 찾는다.
+// 예전 path.resolve('dist/bridge/mcp-server.js')는 backend 폴더에서 실행할 때만 맞았다.
+// Claude Code가 띄우는 MCP 서버(submit_artifact 등). process.execPath로 실행하므로 컴파일된 .js여야 한다.
+export function mcpServerPath() {
+    // 패키지·서버 빌드(dist/executor/cli.js) → dist/bridge/mcp-server.js
+    const sibling = fileURLToPath(new URL('../bridge/mcp-server.js', import.meta.url));
+    if (existsSync(sibling))
+        return sibling;
+    // 소스에서 tsx로 실행(npm run executor, src/executor/cli.ts) → 서버 빌드 결과 dist/bridge/mcp-server.js
+    const built = fileURLToPath(new URL('../../dist/bridge/mcp-server.js', import.meta.url));
+    if (existsSync(built))
+        return built;
+    throw new Error(`MCP 서버 파일을 찾지 못했다(${sibling}). 소스에서 실행 중이면 npm run build를 먼저 하라`);
+}
+// 패키지 버전. 패키지에서는 packages/cli/package.json, 소스에서는 backend의 package.json이 읽힌다.
+export function cliVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf-8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/executor/preflight.js

@@ -0,0 +1,22 @@
+import { spawnSync } from 'node:child_process';
+import { resolveClaudeCommand } from './runner.js';
+function versionOf(command, args) {
+    // shell을 쓰지 않는다(runner.ts와 같은 이유). 실행 파일이 없으면 error가 채워진다.
+    const r = spawnSync(command, args, { encoding: 'utf-8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.error || r.status !== 0)
+        return { ok: false, detail: r.error?.message ?? (r.stderr || `exit ${r.status}`).trim() };
+    return { ok: true, detail: r.stdout.trim().split('\n')[0] ?? '' };
+}
+export function checkTools() {
+    const git = versionOf('git', ['--version']);
+    const claudeCmd = resolveClaudeCommand(['--version']);
+    const claude = versionOf(claudeCmd.command, claudeCmd.commandArgs);
+    return [
+        { name: 'git', ...git, hint: 'https://git-scm.com 에서 설치하세요' },
+        {
+            name: 'claude',
+            ...claude,
+            hint: 'Claude Code를 설치하고(npm install -g @anthropic-ai/claude-code) 터미널에서 claude를 한 번 실행해 로그인하세요',
+        },
+    ];
+}

package/dist/executor/prompt.js

@@ -0,0 +1,30 @@
+export function buildTaskPrompt(briefing, branch) {
+    const { task, repo, spec } = briefing;
+    const sections = [];
+    sections.push([
+        '# 태스크',
+        `id: ${task.id}`,
+        `제목: ${task.title}`,
+        `역할: ${task.teamRole ?? '제한 없음'}`,
+        `레포: ${repo.fullName}`,
+        `브랜치: ${branch} (이미 이 워크트리에서 체크아웃돼 있다)`,
+    ].join('\n'));
+    if (spec) {
+        sections.push(`# 명세 ${spec.featureKey} — ${spec.title}\n${spec.content}`);
+    }
+    if (briefing.notesBlock) {
+        sections.push(briefing.notesBlock);
+    }
+    sections.push(['# 수정할 수 있는 경로', ...briefing.writablePaths.map((p) => `- ${p.pathPattern}`)].join('\n'));
+    sections.push([
+        '# 규칙',
+        '- 작업을 시작하기 전에 claim_task를 부르고 성공을 확인한다. 실패하면 파일을 건드리지 않는다.',
+        '- 위 목록 밖의 경로는 수정하지 않는다. 비밀 파일(.env, *.pem, *.key, secrets/)은 절대 건드리지 않는다.',
+        '- 작업이 끝나면 커밋하고, submit_artifact에 **실제 커밋 sha와 실제로 바꾼 모든 경로**를 넣는다.',
+        '  바꾸지 않은 경로를 적거나 sha를 지어내지 않는다 — 서버가 제출 시점에 다시 검증한다.',
+        '- 다음 사람이 알아야 할 결정이나 함정이 있으면 publish_note로 남긴다.',
+        '- 다른 에이전트의 잘못을 노트에 적지 않는다. 그건 raise_dispute의 몫이다.',
+    ].join('\n'));
+    sections.push(`# 지금 할 일\n태스크 ${task.id}를 claim_task로 받고 위 규칙에 따라 진행하라.`);
+    return sections.join('\n\n');
+}

package/dist/executor/repo-checkout.js

@@ -0,0 +1,74 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readRepoMap, repoMapPath } from './workspace.js';
+export function managedReposRoot() {
+    return path.join(os.homedir(), '.nomos', 'repos');
+}
+// owner/repo. 클론 경로(~/.nomos/repos/<owner>/<repo>)가 되므로 '.'·'..' 세그먼트는 받지 않는다(폴더 밖으로 나간다).
+const FULL_NAME = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function isFullName(value) {
+    return FULL_NAME.test(value) && value.split('/').every((part) => part !== '.' && part !== '..');
+}
+// 서버가 준 clone_url을 그대로 git에 넘기지 않는다. 서버도 검증하지만(validateCloneUrl) 이건 사용자 노트북에서 도는 명령이다.
+// https(자격 증명 없는)·로컬 절대 경로·file://만. `-`로 시작(옵션 주입)·ext::·ssh·http는 거부.
+export function resolveCloneSource(fullName, cloneUrl) {
+    if (cloneUrl === null) {
+        if (!isFullName(fullName))
+            throw new Error(`레포 이름이 owner/repo 형식이 아니다: ${fullName}`);
+        return `https://github.com/${fullName}.git`;
+    }
+    const value = cloneUrl.trim();
+    if (value.startsWith('-') || value.includes('::'))
+        throw new Error(`받을 수 없는 clone 주소: ${cloneUrl}`);
+    if (/^https:\/\//i.test(value)) {
+        const url = new URL(value);
+        if (url.username || url.password)
+            throw new Error('clone 주소에 자격 증명이 들어 있다 — 받지 않는다');
+        return value;
+    }
+    if (/^file:\/\//i.test(value) || path.isAbsolute(value))
+        return value;
+    throw new Error(`받을 수 없는 clone 주소(https·로컬 경로만): ${cloneUrl}`);
+}
+function isGitRepo(dir) {
+    return existsSync(path.join(dir, '.git'));
+}
+const defaultGit = (args, cwd) => {
+    execFileSync('git', args, { cwd, stdio: 'inherit' });
+};
+export function ensureRepo(repo, deps = {}) {
+    const log = deps.log ?? (() => { });
+    const git = deps.git ?? defaultGit;
+    const mapped = (deps.readMap ?? readRepoMap)()[repo.fullName];
+    if (mapped) {
+        if (!isGitRepo(mapped))
+            throw new Error(`${repoMapPath()}의 "${repo.fullName}" 경로(${mapped})가 git 레포가 아니다`);
+        return { path: mapped, managed: false, baseRef: (b) => b };
+    }
+    if (!isFullName(repo.fullName))
+        throw new Error(`레포 이름이 owner/repo 형식이 아니다: ${repo.fullName}`);
+    const [owner, name] = repo.fullName.split('/');
+    const dir = path.join(deps.root ?? managedReposRoot(), owner, name);
+    if (isGitRepo(dir)) {
+        log(`레포 최신화: ${repo.fullName}`);
+        git(['fetch', '--prune', 'origin'], dir);
+    }
+    else {
+        if (existsSync(dir))
+            throw new Error(`${dir}가 있지만 git 레포가 아니다. 지우고 다시 실행하라`);
+        const source = resolveCloneSource(repo.fullName, repo.cloneUrl);
+        log(`레포 받는 중: ${repo.fullName} → ${dir}`);
+        mkdirSync(path.dirname(dir), { recursive: true });
+        try {
+            // `--`로 주소가 옵션으로 해석되지 않게 한 겹 더 막는다(서버 mirror 검사기와 같은 방식).
+            git(['clone', '--', source, dir], path.dirname(dir));
+        }
+        catch (err) {
+            throw new Error(`${repo.fullName}을 받지 못했다. 이 노트북의 git이 그 레포에 접근할 수 있어야 한다(gh auth login 또는 Git Credential Manager). ` +
+                `이미 받아 둔 레포를 쓰려면 ${repoMapPath()}에 {"${repo.fullName}": "경로"}를 적어라. (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return { path: dir, managed: true, baseRef: (b) => `origin/${b}` };
+}