@capstone-nomos/cli 0.1.19 → 0.1.21

package/dist/bridge/credentials.js

@@ -1,4 +1,4 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 // NOMOS의 로컬 상태(자격 증명·작업공간·레포)를 두는 곳. 기본 ~/.nomos.
@@ -26,7 +26,18 @@ export function readCredentials() {
 export function writeCredentials(credentials) {
     mkdirSync(credentialsDir(), { recursive: true, mode: 0o700 });
     const file = credentialsPath();
-    writeFileSync(file, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    // 임시 파일에 다 쓴 뒤 이름을 바꾼다 — 읽는 쪽이 반쯤 쓰인 파일을 보지 않게(토큰 재발급마다 쓴다).
+    // 같은 NOMOS_HOME을 두 프로세스가 쓰다 "Unexpected end of JSON input"으로 죽은 일이 있었다(운영 실험) — 공유 자체는 executor/home-lock.ts가 막는다.
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    try {
+        renameSync(tmp, file);
+    }
+    catch {
+        // Windows에서 다른 프로세스가 그 순간 파일을 열고 있으면 바꾸기가 거부될 수 있다 — 직접 쓴다.
+        writeFileSync(file, readFileSync(tmp), { mode: 0o600 });
+        rmSync(tmp, { force: true });
+    }
     try {
         chmodSync(file, 0o600);
     }

package/dist/executor/cli.js

@@ -23,7 +23,7 @@ import { createInterface } from 'node:readline/promises';
 import { writeBriefingNotes } from '../bridge/briefing-notes.js';
 import { ALLOWED_BASH_PREFIXES, buildMcpConfig } from '../bridge/claude-args.js';
 import { prepareDependencies } from './setup.js';
-import { credentialsPath, readCredentials, updateAccessToken, writeCredentials, } from '../bridge/credentials.js';
+import { credentialsPath, nomosHome, readCredentials, updateAccessToken, writeCredentials, } from '../bridge/credentials.js';
 import { NomosApiError, NomosClient } from '../bridge/nomos-client.js';
 import { ActivityReporter, ActivityTracker, RunObserver } from './activity.js';
 import { accountLine, connect, DEFAULT_SERVER, serverCalls } from './connect.js';
@@ -33,6 +33,8 @@ import { deviceLogin } from './device-login.js';
 import { cliVersion, mcpServerPath } from './paths.js';
 import { checkTools } from './preflight.js';
 import { handleNextPmJob } from './pm-worker.js';
+import { experimentCli } from './experiment-command.js';
+import { acquireHomeLock } from './home-lock.js';
 import { buildTaskPrompt } from './prompt.js';
 import { DEFAULT_IDLE_MS, runClaude } from './runner.js';
 import { streamTaskSource } from './stream-source.js';
@@ -41,7 +43,7 @@ import { runLint, runSpecTests } from './verify.js';
 import { ensureRepo } from './repo-checkout.js';
 import { runConsult } from './consult.js';
 import { runContractBatch, runContractDraft } from './contract.js';
-import { cleanWorkspaces, headSha, prepareWorkspace } from './workspace.js';
+import { cleanWorkspaces, fetchCommit, headSha, mergePredecessors, prepareWorkspace } from './workspace.js';
 // 푸시가 오지 않아도 이 간격으로 한 번씩 다시 본다(끊겼을 때는 이 간격으로 폴링한다).
 const POLL_INTERVAL_MS = 10_000;
 function log(line) {
@@ -209,17 +211,35 @@ async function handleTask(client, projectId, task) {
     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 serverBase = briefing.base && fetchCommit(checkout.path, briefing.base.branchName, briefing.base.commitSha) ? briefing.base : null;
+    if (briefing.base && !serverBase)
+        log(`서버 기준점 ${briefing.base.branchName}을 받지 못했다 — 선행을 직접 합친다`);
     const workspace = prepareWorkspace({
         repoPath: checkout.path,
         projectId,
         taskId: task.id,
         branchName: briefing.task.branchName,
-        // CLI가 관리하는 클론은 방금 fetch한 origin/<기본 브랜치>에서 분기한다.
-        baseBranch: checkout.baseRef(briefing.repo.defaultBranch),
+        // CLI가 관리하는 클론은 방금 fetch한 origin/<기본 브랜치>에서 분기한다. 서버 기준점이 있으면 그 커밋에서.
+        baseBranch: serverBase?.commitSha ?? checkout.baseRef(briefing.repo.defaultBranch),
         settings: briefing.claudeSettings,
         policyHash: briefing.policyHash,
     });
     log(`작업공간 ${workspace.dir} (브랜치 ${workspace.branch})`);
+    // 선행 작업 위에서 시작한다 — 새로 딴 브랜치일 때만(이어 가는 브랜치에는 이미 들어 있다).
+    let predecessorMerge;
+    if (workspace.startedFresh && serverBase && (briefing.predecessors?.length ?? 0) > 0) {
+        // 서버가 이미 합쳤다 — 프롬프트에 "선행 코드가 들어 있다"만 알린다.
+        predecessorMerge = { merged: briefing.predecessors, failed: [] };
+        log(`  서버 기준점에서 시작: ${serverBase.branchName} (${serverBase.commitSha.slice(0, 12)}) — 선행 ${briefing.predecessors.length}개 포함`);
+    }
+    else if (workspace.startedFresh && (briefing.predecessors?.length ?? 0) > 0) {
+        predecessorMerge = mergePredecessors(workspace.dir, briefing.predecessors);
+        for (const p of predecessorMerge.merged)
+            log(`  선행 합침: ${p.title} (${p.commitSha.slice(0, 12)})`);
+        for (const f of predecessorMerge.failed)
+            log(`  선행 합치지 못함: ${f.predecessor.title} — ${f.reason}`);
+    }
     activeWorkspaces.set(task.id, { dir: workspace.dir, repo: briefing.repo.fullName });
     // 프롬프트에 넣는 노트·결정 = 제출 때 "받은 것"으로 함께 보낼 노트·결정. MCP 서버(submit_artifact)가 읽는다.
     writeBriefingNotes(workspace.dir, task.id, (briefing.notes ?? []).map((n) => n.id), (briefing.decisions ?? []).map((d) => d.id));
@@ -250,7 +270,7 @@ async function handleTask(client, projectId, task) {
     const before = headSha(workspace.dir);
     const result = await runClaude({
         workspaceDir: workspace.dir,
-        prompt: buildTaskPrompt(briefing, workspace.branch, { allowedCommands: ALLOWED_BASH_PREFIXES, setup: setup.steps }),
+        prompt: buildTaskPrompt({ ...briefing, predecessorMerge }, workspace.branch, { allowedCommands: ALLOWED_BASH_PREFIXES, setup: setup.steps }),
         mcpConfigPath,
         pathPrepend: setup.venvBin,
         // 질문 중계가 꺼진 프로젝트(또는 옛 서버)면 권한 도구를 붙이지 않는다 — AskUserQuestion이 없어진다.
@@ -337,6 +357,7 @@ async function reportBridgeStages(client, taskId, workspaceDir, specTests) {
     }
 }
 async function once() {
+    acquireHomeLock('once');
     const client = createClient();
     const self = await client.describeSelf();
     const source = pollingTaskSource(client);
@@ -349,6 +370,7 @@ async function once() {
 }
 // 멈춘 이유를 돌려준다 — connect는 배정이 풀린 경우(해제·프로젝트 중단) 다시 배정을 기다린다.
 async function start() {
+    acquireHomeLock('start');
     const client = createClient();
     const self = await client.describeSelf();
     // 서버 푸시(웹소켓)로 받는다. 끊겨 있는 동안은 같은 목록을 HTTP로 읽는다.
@@ -524,6 +546,8 @@ async function loginWithCode(baseUrl, agentName, code) {
     log(`${credentialsPath()}에 저장했다. 내 계정이 아니면 바로 Ctrl+C로 멈추고 웹에서 이 에이전트를 연결 해제하라.`);
 }
 async function login(argv) {
+    // 돌고 있는 에이전트의 자격 증명을 덮어쓰지 않게 — 같은 폴더를 쓰는 프로세스가 있으면 멈춘다.
+    acquireHomeLock('login');
     const args = parseArgs(argv);
     const baseUrl = normalizeBaseUrl(args.positional ?? args.server);
     const previous = readCredentials();
@@ -557,6 +581,8 @@ async function connectCommand(argv) {
         log('상태: nomos status · 끄기: nomos stop · 진행 상황은 웹의 룸에서 본다');
         return;
     }
+    // 한 NOMOS_HOME = 한 에이전트(home-lock.ts). 백그라운드를 띄우는 부모는 바로 끝나므로 잡지 않고, 실제로 도는 자식이 여기서 잡는다.
+    acquireHomeLock('connect');
     // 배정이 풀리면(해제·프로젝트 중단) 창을 닫지 않고 다시 배정을 기다린다. 연결 해제면 멈춘다.
     // 1회용 코드는 처음 한 번만 쓴다 — 그 뒤로는 그 코드로 받은 자격 증명이 저장돼 있다.
     let code = args.code?.trim() || undefined;
@@ -627,6 +653,7 @@ async function refresh() {
 }
 const PM_POLL_INTERVAL_MS = 3_000;
 async function pmWorker() {
+    acquireHomeLock('pm-worker');
     const client = createClient();
     log('pm-worker 시작 — 대표가 PM에 계획을 요청하면 여기서 claude가 돈다 (Ctrl+C로 종료)');
     for (;;) {
@@ -684,6 +711,9 @@ async function main() {
     }
     if (command === 'pm-worker')
         return pmWorker();
+    // 무인 실험 감독 — 대표 계정으로 서버 API만 부른다. 에이전트가 아니라 폴더 잠금(home-lock)을 잡지 않는다(에이전트와 같은 NOMOS_HOME에서 돌아도 된다).
+    if (command === 'experiment')
+        return experimentCli(process.argv.slice(3), { command: 'nomos experiment', runsDir: path.join(nomosHome(), 'experiment-runs') });
     if (command === 'clean') {
         const { pruned, removed } = cleanWorkspaces();
         log(`worktree prune: ${pruned.join(', ') || '없음'} / 삭제: ${removed ?? '없음'}`);
@@ -697,6 +727,7 @@ async function main() {
         '  login [주소] [--name 이름] [--connect-key]   로그인만',
         '  refresh | once | start | clean | --version',
         '  pm-worker                                    (대표 전용, 서버가 PM_PROVIDER=relay일 때) PM 모델 호출을 이 노트북의 Claude Code로',
+        '  experiment --project <id> --login <대표> --requirements <파일> [--until 24]   (대표 전용) 실험 모드 프로젝트 무인 감독 — 인자 없이 실행하면 사용법',
         '',
     ].join('\n'));
     process.exitCode = 1;

package/dist/executor/experiment-command.js

@@ -0,0 +1,218 @@
+// 무인 실험 감독(034) — 실험 모드 프로젝트에 요구사항을 넣고, 서버가 사람 없이 진행하는 것을 지켜보며 회차를 반복한다.
+// question-harvest(033)를 대체한다(그 반복 로직을 흡수했다).
+// 진입점은 둘이고 이 함수 한 벌을 쓴다: CLI `nomos experiment …`(서버 레포 없이 npx로 — 상태 파일 <NOMOS_HOME>/experiment-runs/)와
+// 레포의 `npm run experiment:run -- …`(scripts/experiment-run.ts — 상태 파일 scripts/data/experiment-runs/).
+// 대표 계정(사람 토큰)으로만 서버 API를 부른다 — 에이전트 자격 증명(credentials)은 읽지도 쓰지도 않고, 폴더 잠금(home-lock)도 잡지 않는다.
+//
+//   nomos experiment --project <id> --login <대표 loginId> --requirements <파일.json> --repeat 3
+//   nomos experiment ... --dry-run                 # 확인만(요청하지 않는다)
+//   nomos experiment ... --run e202611021530       # 끊긴 실행을 이어 간다(상태 파일 <run>.json)
+//   nomos experiment --project <id> --login <대표> --report --run <이름>   # 단계별·요구사항·회차별 질문 수, 자동 처리 건수, 라우터 분포
+//   --server <주소>(기본 운영) --interval <초>(30) --round-timeout <분>(90) --planning-timeout <분>(120)
+//   --offline <분>(10) --unclaimed <분>(15) --failures <K>(3)
+//   --until <시간>       이 시간 동안 회차를 늘려 가며 계속 돈다(요구사항을 한 바퀴씩, 바퀴마다 --repeat회 더). 마감은 상태 파일에 남아 이어 가도 늘지 않는다. --keep-going을 함께 켠다.
+//   --keep-going         멈춤·일시 오류에도 끝내지 않고 알린 뒤 --retry-wait <분>(5) 기다렸다가 이어 간다(설정 문제만 끝낸다). 24시간 무인 실행용.
+//
+// 요구사항 파일: [{ "key": "study-list", "instruction": "대표가 PM에게 하듯 자연어 요구", "repeat"?: 3 }] — 예시 scripts/examples/experiment-requirements.json.
+// 자동으로 풀 수 없는 고장(로그인 만료·노트북 꺼짐·예산 소진 등)은 멈추고 원인과 할 일을 한 줄로 출력한다(종료 코드 3).
+// EXPERIMENT_ALERT_WEBHOOK이 있으면 같은 문장을 { text }로 POST한다(슬랙 호환). 비밀값은 싣지 않는다.
+// 대표 권한 HTTP만 쓴다. 비밀번호는 NOMOS_PASSWORD 또는 입력 창, 받은 토큰이 있으면 NOMOS_TOKEN. 규칙과 이유는 experiment-supervisor.ts.
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { DEFAULT_SERVER } from './connect.js';
+import { DEFAULTS, emptyState, experimentReport, formatExperimentReport, HaltError, newRunId, requirementsSchema, RUN_ID, Supervisor, superviseWithRetry, } from './experiment-supervisor.js';
+import { NomosHttp, signIn } from './human-http.js';
+// 사용법 문구의 명령 이름(진입점마다 다르다).
+let commandName = 'nomos experiment';
+function out(line = '') {
+    process.stdout.write(`${line}\n`);
+}
+// 오래 도는 감독의 출력에는 시각을 붙인다 — 몇 시간 뒤 로그를 볼 때 언제 일어난 일인지 알 수 있게.
+function stamped(line = '') {
+    const t = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    out(line ? `${pad(t.getMonth() + 1)}-${pad(t.getDate())} ${pad(t.getHours())}:${pad(t.getMinutes())} ${line}` : '');
+}
+function usage(message) {
+    if (message)
+        process.stderr.write(`${message}\n`);
+    process.stderr.write(`사용법: ${commandName} --project <id> --login <대표 loginId> --requirements <파일.json> [--repeat N] [--run <이름>] [--dry-run]\n` +
+        `        ${commandName} --project <id> --login <대표 loginId> --report --run <이름>\n` +
+        '        [--server <주소>] [--interval <초>] [--round-timeout <분>] [--planning-timeout <분>] [--offline <분>] [--unclaimed <분>] [--failures <K>]\n' +
+        '        [--until <시간>] [--keep-going] [--retry-wait <분>]\n');
+    process.exit(2);
+}
+function parseArgs(argv) {
+    const value = (i) => {
+        const v = argv[i + 1];
+        if (!v || v.startsWith('--'))
+            usage(`${argv[i]}에 값이 없다`);
+        return v;
+    };
+    const positive = (raw, flag) => {
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < 1)
+            usage(`${flag}는 1 이상의 정수다`);
+        return n;
+    };
+    let project;
+    const a = {
+        server: DEFAULT_SERVER,
+        repeat: 1,
+        dryRun: false,
+        report: false,
+        intervalSec: DEFAULTS.pollMs / 1000,
+        roundTimeoutMin: DEFAULTS.roundTimeoutMs / 60_000,
+        planningTimeoutMin: DEFAULTS.planningTimeoutMs / 60_000,
+        offlineMin: DEFAULTS.offlineMs / 60_000,
+        unclaimedMin: DEFAULTS.unclaimedMs / 60_000,
+        failures: DEFAULTS.failureLimit,
+        keepGoing: false,
+        retryWaitMin: 5,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--server')
+            a.server = value(i++);
+        else if (arg === '--project')
+            project = value(i++);
+        else if (arg === '--login')
+            a.login = value(i++);
+        else if (arg === '--requirements')
+            a.requirements = value(i++);
+        else if (arg === '--repeat')
+            a.repeat = positive(value(i++), '--repeat');
+        else if (arg === '--run')
+            a.run = value(i++);
+        else if (arg === '--interval')
+            a.intervalSec = positive(value(i++), '--interval');
+        else if (arg === '--round-timeout')
+            a.roundTimeoutMin = positive(value(i++), '--round-timeout');
+        else if (arg === '--planning-timeout')
+            a.planningTimeoutMin = positive(value(i++), '--planning-timeout');
+        else if (arg === '--offline')
+            a.offlineMin = positive(value(i++), '--offline');
+        else if (arg === '--unclaimed')
+            a.unclaimedMin = positive(value(i++), '--unclaimed');
+        else if (arg === '--failures')
+            a.failures = positive(value(i++), '--failures');
+        else if (arg === '--until')
+            a.untilHours = positive(value(i++), '--until');
+        else if (arg === '--keep-going')
+            a.keepGoing = true;
+        else if (arg === '--retry-wait')
+            a.retryWaitMin = positive(value(i++), '--retry-wait');
+        else if (arg === '--dry-run')
+            a.dryRun = true;
+        else if (arg === '--report')
+            a.report = true;
+        else
+            usage(`모르는 인자: ${arg}`);
+    }
+    if (!project)
+        usage('--project가 필요하다');
+    if (a.run !== undefined && !RUN_ID.test(a.run))
+        usage('--run은 영문·숫자·하이픈 24자 이내다');
+    if (a.report && !a.run)
+        usage('--report에는 --run이 필요하다(상태 파일로 요구사항·회차를 안다)');
+    if (!a.report && !a.requirements)
+        usage('--requirements가 필요하다');
+    // 하루짜리 실행이 고장 한 번에 끝나면 --until의 의미가 없다.
+    if (a.untilHours !== undefined)
+        a.keepGoing = true;
+    return { ...a, project, server: a.server.replace(/\/+$/, '') };
+}
+function fileStore(runsDir, run) {
+    const file = path.join(runsDir, `${run}.json`);
+    return {
+        async load() {
+            try {
+                return JSON.parse(await readFile(file, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        },
+        async save(state) {
+            await mkdir(runsDir, { recursive: true });
+            // 임시 파일에 쓰고 바꿔 끼운다 — 쓰는 도중 꺼지면(정전·강제 종료) 상태 파일이 반쯤 남아 이어 가지 못한다.
+            const tmp = `${file}.tmp`;
+            await writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`);
+            await rename(tmp, file);
+        },
+    };
+}
+async function alert(text) {
+    const url = process.env.EXPERIMENT_ALERT_WEBHOOK;
+    if (!url)
+        return;
+    try {
+        await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text: `[NOMOS 무인 실험] ${text}` }) });
+    }
+    catch (err) {
+        process.stderr.write(`알림 웹훅 실패: ${err.message}\n`);
+    }
+}
+// 자동으로 풀 수 없는 멈춤은 종료 코드 3, 그 밖의 실패는 1, 사용법 오류는 2.
+export async function experimentCli(argv, opts) {
+    commandName = opts.command;
+    try {
+        await runExperiment(argv, opts.runsDir);
+    }
+    catch (err) {
+        const message = err.message;
+        if (err instanceof HaltError) {
+            process.stderr.write(`멈춤: ${message}\n`);
+            await alert(message);
+            process.exit(3);
+        }
+        process.stderr.write(`실패: ${message}\n`);
+        process.exit(1);
+    }
+}
+async function runExperiment(argv, runsDir) {
+    const args = parseArgs(argv);
+    const api = new NomosHttp(args.server);
+    out(`서버: ${args.server}`);
+    await signIn(api, args.login);
+    if (args.report) {
+        const state = (await fileStore(runsDir, args.run).load()) ?? emptyState(args.run, args.project);
+        for (const line of formatExperimentReport(await experimentReport(api, args.project, state)))
+            out(line);
+        return;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(args.requirements, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${args.requirements}를 읽지 못했다: ${err.message}`);
+    }
+    const parsed = requirementsSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`${args.requirements} 형식이 틀렸다:\n${parsed.error.issues.map((i) => `  - ${i.path.join('.')}: ${i.message}`).join('\n')}`);
+    const run = args.run ?? newRunId(new Date());
+    const io = { log: stamped, sleep: (ms) => sleep(ms).then(() => undefined), now: () => Date.now() };
+    const make = () => new Supervisor(api, {
+        projectId: args.project,
+        requirements: parsed.data,
+        repeat: args.repeat,
+        run,
+        dryRun: args.dryRun,
+        pollMs: args.intervalSec * 1000,
+        roundTimeoutMs: args.roundTimeoutMin * 60_000,
+        planningTimeoutMs: args.planningTimeoutMin * 60_000,
+        offlineMs: args.offlineMin * 60_000,
+        unclaimedMs: args.unclaimedMin * 60_000,
+        failureLimit: args.failures,
+        ...(args.untilHours !== undefined ? { untilMs: args.untilHours * 3_600_000 } : {}),
+    }, fileStore(runsDir, run), io);
+    if (args.keepGoing && !args.dryRun) {
+        stamped(`--keep-going: 멈춰도 ${args.retryWaitMin}분 뒤 이어 간다(Ctrl+C로 끝낸다). 끝낸 뒤에도 --run ${run}으로 이어 갈 수 있다`);
+        await superviseWithRetry(make, io, { retryWaitMs: args.retryWaitMin * 60_000, notify: alert });
+    }
+    else {
+        await make().run();
+    }
+}

package/dist/executor/experiment-supervisor.js

@@ -0,0 +1,605 @@
+import { z } from 'zod';
+// 무인 실험 감독(034) — experiment-command.ts(CLI `nomos experiment`·레포 `npm run experiment:run`)가 쓴다. question-harvest(033)의 반복 로직을 흡수했다.
+// CLI 패키지에 실려 나가므로 서버 코드(config·domain)를 import하지 않는다 — 상태는 전부 서버 API로 읽는다.
+//
+// 서버(실험 모드)가 사람 결정 지점을 자동으로 통과시키므로 감독은 "요청 → 기다림 → 정리 → 다음 회차"만 한다:
+//   요구사항마다 기능 명세 요청(POST /pm/features) → 서버가 질문·자동 답·재작성·적용·계약·태스크 나누기까지 진행 → 시작 전이면 시작 →
+//   그 태스크가 끝나기를 기다린다(r1) → 회차마다 같은 태스크 묶음을 [exp <run> r<n>] 꼬리표로 다시 만들어 돌린다.
+// 태스크 정리: BLOCKED(AGENT_STOPPED) → 재개 1회, 또 멈추면 취소 / ESCALATED → 취소 / 회차 시간 초과 → 취소할 수 있는 것은 취소하고 다음 회차.
+// 승인 대기(AWAITING_APPROVAL)는 서버가 자동 승인하므로 기다리기만 한다. G3는 서버도 감독도 건드리지 않는다.
+//
+// 자동으로 풀 수 없는 것은 **멈추고 알린다**(HaltError — 원인과 사람이 할 일 한 줄, 종료 코드 3):
+//   같은 실패 K번 연속 · 역할 에이전트 offline · PM 워커 offline · PM 예산 소진 · READY 태스크를 아무도 안 가져감 · 계약 포기(태스크 나누기가 막힌다).
+// 진행 상태는 상태 파일(<run>.json — CLI는 <NOMOS_HOME>/experiment-runs/, 레포는 scripts/data/experiment-runs/, 커밋하지 않음)에 남겨 같은 --run으로 다시 실행하면 이어서 돈다.
+// 서버 판정을 흉내 내지 않는다 — 상태는 전부 API로 읽는다.
+export const requirementsSchema = z
+    .array(z
+    .object({
+    key: z.string().trim().regex(/^[A-Za-z0-9_-]{1,32}$/, '영문·숫자·_·- 32자 이내'),
+    // 대표가 PM에게 하듯 자연어 요구.
+    instruction: z.string().trim().min(1).max(4000),
+    // 이 요구사항만 회차 수를 따로 정할 때(없으면 --repeat).
+    repeat: z.number().int().min(1).max(50).optional(),
+})
+    .strict())
+    .min(1)
+    .max(20)
+    .refine((items) => new Set(items.map((i) => i.key)).size === items.length, '같은 key가 두 번 있다');
+export const RUN_ID = /^[A-Za-z0-9-]{1,24}$/;
+export function newRunId(now) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `e${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}`;
+}
+const TAG = /\s*\[exp ([A-Za-z0-9-]+) r(\d+)\]$/;
+export function roundTitle(title, run, round) {
+    return round === 1 ? title : `${title} [exp ${run} r${round}]`;
+}
+export function parseRoundTitle(title) {
+    const m = TAG.exec(title);
+    return m ? { base: title.slice(0, m.index), run: m[1], round: Number(m[2]) } : null;
+}
+export function emptyState(run, projectId) {
+    return { run, projectId, requirements: {}, counters: { resumed: 0, cancelled: 0, timedOutRounds: 0, skippedRequirements: 0 }, resumedTaskIds: [] };
+}
+// permanent: 기다려도 저절로 풀리지 않는 설정 문제(실험 모드 아님·프로젝트가 끝남) — --keep-going도 다시 시도하지 않는다.
+export class HaltError extends Error {
+    permanent;
+    constructor(message, permanent = false) {
+        super(message);
+        this.permanent = permanent;
+    }
+}
+export const DEFAULTS = {
+    pollMs: 30_000,
+    roundTimeoutMs: 90 * 60_000,
+    planningTimeoutMs: 120 * 60_000,
+    offlineMs: 10 * 60_000,
+    unclaimedMs: 15 * 60_000,
+    failureLimit: 3,
+};
+const FINISHED = new Set(['DONE', 'CANCELLED']);
+const CANCELLABLE = new Set(['READY', 'BLOCKED', 'ESCALATED']);
+const IN_FLIGHT = new Set(['CLAIMED', 'IN_PROGRESS', 'VERIFYING', 'AWAITING_APPROVAL']);
+// 고장 감지 — 감독이 한 번 확인할 때마다 부른다. 자동으로 풀 수 없으면 HaltError(사람이 할 일 한 줄).
+export class HealthMonitor {
+    api;
+    opts;
+    io;
+    offlineSince = new Map();
+    workerOfflineSince = null;
+    readySince = new Map();
+    lastFailure = null;
+    constructor(api, opts, io) {
+        this.api = api;
+        this.opts = opts;
+        this.io = io;
+    }
+    // 같은 실패가 연속 K번이면 멈춘다. 성공(태스크 DONE·초안 적용)이 오면 센 것을 비운다.
+    failure(key, advice) {
+        this.lastFailure = this.lastFailure?.key === key ? { key, count: this.lastFailure.count + 1 } : { key, count: 1 };
+        if (this.lastFailure.count >= this.opts.failureLimit) {
+            throw new HaltError(`같은 실패(${key})가 연속 ${this.lastFailure.count}번 났다 — ${advice}`);
+        }
+    }
+    success() {
+        this.lastFailure = null;
+    }
+    async check(tasks, projectStatus) {
+        const now = this.io.now();
+        const [status, rooms] = await Promise.all([
+            this.api.call('GET', `/projects/${this.opts.projectId}/pm/status`),
+            this.api.call('GET', `/projects/${this.opts.projectId}/rooms`),
+        ]);
+        if (status.spentUsd >= status.budgetUsd) {
+            throw new HaltError(`PM 예산이 다 떨어졌다($${status.spentUsd.toFixed(2)} / $${status.budgetUsd}) — 대표가 프로젝트 PM 예산을 늘린 뒤 같은 명령을 다시 실행`);
+        }
+        if (status.reason === 'WORKER_OFFLINE') {
+            this.workerOfflineSince ??= now;
+            if (now - this.workerOfflineSince >= this.opts.offlineMs) {
+                throw new HaltError(`대표 노트북의 pm-worker가 ${Math.round((now - this.workerOfflineSince) / 60000)}분째 응답하지 않는다 — 노트북이 꺼졌거나 절전 중이거나 Claude 로그인이 만료됐을 수 있다. pm-worker를 다시 띄운 뒤 같은 명령을 다시 실행`);
+            }
+        }
+        else {
+            this.workerOfflineSince = null;
+        }
+        for (const room of rooms.rooms) {
+            if (!room.agent)
+                continue;
+            if (room.agent.online) {
+                this.offlineSince.delete(room.role);
+                continue;
+            }
+            const since = this.offlineSince.get(room.role) ?? now;
+            this.offlineSince.set(room.role, since);
+            if (now - since >= this.opts.offlineMs) {
+                throw new HaltError(`${room.role} 에이전트가 ${Math.round((now - since) / 60000)}분째 연결돼 있지 않다 — ${room.role} 노트북이 꺼졌거나 절전 중일 수 있다. ` +
+                    '그 노트북에서 npx @capstone-nomos/cli@latest connect --background 후 같은 명령을 다시 실행');
+            }
+        }
+        // READY인데 아무도 가져가지 않는다 — 진행 중인 태스크가 하나도 없을 때만 본다(선행을 기다리는 READY를 고장으로 세지 않게).
+        if (projectStatus !== 'active')
+            return;
+        const busy = tasks.some((t) => IN_FLIGHT.has(t.state));
+        for (const t of tasks) {
+            if (t.state !== 'READY' || busy) {
+                this.readySince.delete(t.id);
+                continue;
+            }
+            const since = this.readySince.get(t.id) ?? now;
+            this.readySince.set(t.id, since);
+            if (now - since >= this.opts.unclaimedMs) {
+                throw new HaltError(`READY 태스크 "${t.title}"(${t.teamRole ?? '역할 없음'})를 ${Math.round((now - since) / 60000)}분 동안 아무도 가져가지 않았다 — ` +
+                    `${t.teamRole ?? '그 역할'} 노트북의 connect가 돌고 있는지, Claude 로그인·사용량 한도를 확인한 뒤 같은 명령을 다시 실행`);
+            }
+        }
+    }
+}
+// ── 감독 ──
+export class Supervisor {
+    api;
+    opts;
+    store;
+    io;
+    health;
+    state;
+    constructor(api, opts, store, io) {
+        this.api = api;
+        this.opts = opts;
+        this.store = store;
+        this.io = io;
+        this.health = new HealthMonitor(api, opts, io);
+    }
+    // 담당이 있어야 하는 역할 = 프로젝트 레포의 경로 규칙이 소유자로 지정한 역할. BE 레포만 넣은 프로젝트는 FE 태스크가 생기지 않으므로 FE 담당을 요구하지 않는다.
+    // 레포 목록을 모르면(옛 서버) 두 역할 모두.
+    async requiredRoles(detail) {
+        if (!detail.repos || detail.repos.length === 0)
+            return ['FRONTEND', 'BACKEND'];
+        const roles = new Set();
+        for (const repo of detail.repos) {
+            const { paths } = await this.api.call('GET', `/repos/${repo.id}/paths`);
+            for (const p of paths)
+                if (p.ownerRole)
+                    roles.add(p.ownerRole);
+        }
+        return ['FRONTEND', 'BACKEND'].filter((r) => roles.has(r));
+    }
+    async preflight() {
+        const detail = await this.api.call('GET', `/projects/${this.opts.projectId}`);
+        const problems = [];
+        if (detail.project.questionMode !== 'experiment') {
+            problems.push(`실험 모드가 아니다(questionMode=${detail.project.questionMode ?? '없음'}) — 시작 전에 PATCH /projects/:id/settings { questionMode: 'experiment' }`);
+        }
+        if (!['planning', 'active'].includes(detail.project.status))
+            problems.push(`프로젝트 상태가 ${detail.project.status}다(planning·active만)`);
+        for (const role of await this.requiredRoles(detail)) {
+            const m = detail.members.find((x) => x.teamRole === role);
+            if (!m)
+                problems.push(`${role} 담당이 배정되지 않았다`);
+            else if (!m.agentId)
+                problems.push(`${role} 담당의 에이전트가 연결돼 있지 않다 — 그 노트북에서 connect`);
+        }
+        const status = await this.api.call('GET', `/projects/${this.opts.projectId}/pm/status`);
+        if (!status.ready)
+            problems.push(`PM을 부를 수 없다(${status.reason}) — ${status.reason === 'WORKER_OFFLINE' ? '대표 노트북에서 pm-worker를 띄운다' : '서버의 PM 설정을 확인한다'}`);
+        const permanent = detail.project.questionMode !== 'experiment' || !['planning', 'active'].includes(detail.project.status);
+        if (problems.length > 0)
+            throw new HaltError(`시작할 수 없다:\n${problems.map((p) => `  - ${p}`).join('\n')}`, permanent);
+        return detail;
+    }
+    async run() {
+        const detail = await this.preflight();
+        this.state = (await this.store.load()) ?? emptyState(this.opts.run, this.opts.projectId);
+        if (this.state.projectId !== this.opts.projectId)
+            throw new HaltError(`상태 파일의 프로젝트(${this.state.projectId})가 --project와 다르다 — 다른 --run을 쓴다`);
+        this.io.log(`프로젝트: ${detail.project.name} (${detail.project.status}) · 실행 이름 ${this.opts.run} — 끊기면 --run ${this.opts.run}으로 이어 간다`);
+        if (this.opts.dryRun) {
+            for (const r of this.opts.requirements) {
+                const s = this.state.requirements[r.key];
+                this.io.log(`  [${r.key}] ${s ? `이어 감(${s.status})` : '새로'} · 회차 ${r.repeat ?? this.opts.repeat} · "${r.instruction.slice(0, 80)}"`);
+            }
+            this.io.log('--dry-run: 아무것도 요청하지 않았다');
+            return this.state;
+        }
+        if (this.opts.untilMs !== undefined) {
+            if (this.state.untilAt === undefined) {
+                this.state.untilAt = this.io.now() + this.opts.untilMs;
+                await this.save();
+            }
+            await this.runUntil(this.state.untilAt);
+        }
+        else {
+            for (const r of this.opts.requirements)
+                await this.runRequirement(r, r.repeat ?? this.opts.repeat);
+        }
+        this.io.log(`다 돌았다 — npm run experiment:run -- --project ${this.opts.projectId} --report --run ${this.opts.run}`);
+        return this.state;
+    }
+    pastDeadline() {
+        return this.state.untilAt !== undefined && this.io.now() >= this.state.untilAt;
+    }
+    // --until: 요구사항을 차례로 한 바퀴(각 repeat회) 돈 뒤, 마감 전이면 다음 바퀴에서 회차를 repeat만큼 더 늘린다(r3, r4, …).
+    // 같은 요구사항만 몇 시간 도는 대신 바퀴마다 모든 요구사항이 고르게 쌓인다. 마감이 지나면 새 회차를 시작하지 않는다(돌던 회차는 끝까지 — 회차 시간 제한이 있다).
+    async runUntil(untilAt) {
+        this.io.log(`마감 ${new Date(untilAt).toISOString()}까지 회차를 늘려 가며 돈다`);
+        for (let lap = 1; !this.pastDeadline(); lap += 1) {
+            for (const r of this.opts.requirements) {
+                if (this.pastDeadline())
+                    break;
+                await this.runRequirement(r, (r.repeat ?? this.opts.repeat) * lap);
+            }
+            // 모든 요구사항이 포기됐다면 바퀴를 돌아도 할 일이 없다 — 빈 바퀴로 마감까지 헛돌지 않는다.
+            if (this.opts.requirements.every((r) => this.state.requirements[r.key]?.status === 'skipped')) {
+                this.io.log('돌릴 수 있는 요구사항이 없다(전부 포기) — 마감 전이지만 끝낸다');
+                return;
+            }
+        }
+        this.io.log('마감이 지났다 — 새 회차를 시작하지 않는다');
+    }
+    async save() {
+        await this.store.save(this.state);
+    }
+    reqState(key) {
+        this.state.requirements[key] ??= { status: 'pending', rounds: {} };
+        return this.state.requirements[key];
+    }
+    // upTo회차까지 돌린다.
+    async runRequirement(r, upTo) {
+        const s = this.reqState(r.key);
+        const roundsDone = Array.from({ length: upTo }, (_, i) => s.rounds[String(i + 1)]?.done === true).every(Boolean);
+        if (s.status === 'skipped' || (s.status === 'done' && roundsDone)) {
+            this.io.log(`[${r.key}] 이미 ${s.status === 'done' ? '끝났다' : `포기했다(${s.skipReason})`} — 건너뜀`);
+            return;
+        }
+        if (!s.rootPlanId) {
+            s.rootPlanId = await this.requestFeature(r);
+            s.status = 'planning';
+            await this.save();
+            this.io.log(`[${r.key}] 기능 명세 요청 ${s.rootPlanId}`);
+        }
+        if (!s.template) {
+            const planned = await this.waitPlanning(r, s);
+            if (!planned) {
+                s.status = 'skipped';
+                this.state.counters.skippedRequirements += 1;
+                await this.save();
+                return;
+            }
+        }
+        s.status = 'running';
+        await this.save();
+        await this.ensureStarted();
+        for (let round = 1; round <= upTo; round += 1) {
+            const rs = s.rounds[String(round)];
+            if (rs?.done)
+                continue;
+            if (this.pastDeadline())
+                return; // 마감 — 남은 회차는 시작하지 않는다(running으로 남는다)
+            await this.runRound(r, s, round);
+        }
+        s.status = 'done';
+        await this.save();
+    }
+    async requestFeature(r) {
+        for (;;) {
+            try {
+                const plan = await this.api.call('POST', `/projects/${this.opts.projectId}/pm/features`, { instruction: r.instruction });
+                return plan.id;
+            }
+            catch (err) {
+                const message = err.message;
+                if (message.includes('PM_PLAN_IN_PROGRESS')) {
+                    await this.io.sleep(this.opts.pollMs); // 다른 초안이 작성 중 — 끝나면 다시
+                    continue;
+                }
+                if (message.includes('PM_BUDGET_EXCEEDED'))
+                    throw new HaltError('PM 예산이 다 떨어졌다 — 대표가 프로젝트 PM 예산을 늘린 뒤 같은 명령을 다시 실행');
+                throw err;
+            }
+        }
+    }
+    // 기능 명세 체인 적용 → 계약 확정 → 태스크 나누기 적용까지(전부 서버가 자동으로 한다). 태스크 묶음(r1)을 template으로 남긴다.
+    // 포기(서버가 다시 시켜도 끝내지 못함)면 false.
+    async waitPlanning(r, s) {
+        const started = this.io.now();
+        let failedSince = null;
+        // 계획 단계는 몇십 분씩 걸릴 수 있다 — 무엇을 기다리는지 바뀔 때마다(그리고 5분마다) 한 줄 남긴다. 조용하면 멈춘 것과 구분이 안 된다.
+        let lastStage = '';
+        let lastStageAt = 0;
+        const report = (stage) => {
+            if (stage === lastStage && this.io.now() - lastStageAt < 5 * 60_000)
+                return;
+            lastStage = stage;
+            lastStageAt = this.io.now();
+            this.io.log(`  [${r.key}] 계획 대기 ${Math.round((this.io.now() - started) / 60_000)}분 — ${stage}`);
+        };
+        for (;;) {
+            const plans = (await this.api.call('GET', `/projects/${this.opts.projectId}/pm/plans`)).plans;
+            const chain = chainOf(plans, s.rootPlanId);
+            const applied = chain.find((p) => p.status === 'applied');
+            const leaf = chain.find((p) => !plans.some((c) => c.parentPlanId === p.id));
+            if (!applied) {
+                report(`기능 명세 초안 ${chain.length}판째 ${leaf?.status ?? '?'}${leaf?.error ? `(${leaf.error.reason})` : ''}${leaf?.status === 'ready' ? ' — 질문 답·자동 적용 대기' : ''}`);
+            }
+            if (!applied && leaf?.status === 'failed') {
+                if (leaf.error?.reason === 'budget')
+                    throw new HaltError('PM 예산이 다 떨어졌다 — 대표가 프로젝트 PM 예산을 늘린 뒤 같은 명령을 다시 실행');
+                // 서버는 실패하면 바로 다시 낸다 — 다음 판이 두 번 확인하는 동안 생기지 않으면 포기한 것이다(EXPERIMENT_SKIPPED).
+                failedSince ??= this.io.now();
+                if (this.io.now() - failedSince >= this.opts.pollMs * 2) {
+                    s.skipReason = `기능 명세 초안 실패(${leaf.error?.reason ?? '?'})`;
+                    this.io.log(`[${r.key}] 포기 — ${s.skipReason}`);
+                    this.health.failure(`plan_failed:${leaf.error?.reason ?? '?'}`, 'PM이 같은 이유로 계속 실패한다 — 서버 로그와 PM 설정(모델·키·pm-worker)을 확인한 뒤 같은 명령을 다시 실행');
+                    return false;
+                }
+            }
+            else {
+                failedSince = null;
+            }
+            if (applied) {
+                s.featureKeys = (applied.featureDraft?.features ?? []).map((f) => f.featureKey);
+                const template = await this.templateFor(plans, s.featureKeys);
+                if (template) {
+                    s.template = template;
+                    s.rounds['1'] = { taskIds: [], done: false };
+                    this.health.success();
+                    await this.save();
+                    this.io.log(`[${r.key}] 계획 끝 — 기능 ${s.featureKeys.join(', ')}, 태스크 ${template.length}개`);
+                    return true;
+                }
+                const contracts = (await this.api.call('GET', `/projects/${this.opts.projectId}/contracts`)).contracts.filter((c) => s.featureKeys.includes(c.featureKey));
+                const failed = contracts.filter((c) => c.status === 'failed');
+                const split = plans.filter((p) => p.kind === 'tasks').sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+                report(`명세 적용됨(${s.featureKeys.join(', ')}) · 계약 ${contracts.map((c) => `${c.featureKey}=${c.status}`).join(', ') || '없음'} · ` +
+                    `최근 태스크 나누기 ${split ? `${split.status}${split.error ? `(${split.error.reason})` : ''}` : '없음'}`);
+                if (failed.length > 0 && failedSince === null)
+                    failedSince = this.io.now();
+                if (failed.length > 0 && this.io.now() - (failedSince ?? 0) >= this.opts.pollMs * 2) {
+                    throw new HaltError(`API 계약 ${failed.map((c) => c.featureKey).join(', ')}을(를) 자동으로 다시 시켜도 쓰지 못했다 — 태스크 나누기가 막힌다. ` +
+                        'BE 노트북의 connect·Claude 로그인을 확인하고 웹에서 계약 수정 요청을 누른 뒤 같은 명령을 다시 실행');
+                }
+            }
+            if (this.io.now() - started >= this.opts.planningTimeoutMs) {
+                throw new HaltError(`[${r.key}] 계획(기능 명세 → 계약 → 태스크 나누기)이 ${Math.round(this.opts.planningTimeoutMs / 60000)}분 안에 끝나지 않았다 — 웹에서 계획·계약 상태를 확인`);
+            }
+            await this.health.check([], 'planning');
+            await this.io.sleep(this.opts.pollMs);
+        }
+    }
+    // 이 요구사항의 기능에 붙은 태스크 나누기(적용된 것)를 찾아 태스크 묶음을 만든다. 아직이면 null.
+    async templateFor(plans, featureKeys) {
+        const split = plans
+            .filter((p) => p.kind === 'tasks' && p.status === 'applied')
+            .find((p) => (p.draft?.tasks ?? []).some((t) => t.spec !== null && featureKeys.includes(t.spec)));
+        if (!split?.draft?.tasks)
+            return null;
+        const tasks = (await this.api.call('GET', `/projects/${this.opts.projectId}/tasks?limit=200`)).tasks;
+        const byRef = new Map(split.draft.tasks.map((t) => [t.ref, t.title]));
+        const template = [];
+        for (const t of split.draft.tasks) {
+            const real = tasks.find((x) => x.title === t.title);
+            if (!real)
+                return null;
+            template.push({
+                title: t.title,
+                teamRole: real.teamRole,
+                kind: real.kind,
+                repoId: real.repoId,
+                specId: real.specId,
+                dependsOn: t.dependsOn.map((d) => byRef.get(d)).filter(Boolean),
+            });
+        }
+        return template;
+    }
+    async ensureStarted() {
+        const detail = await this.api.call('GET', `/projects/${this.opts.projectId}`);
+        if (detail.project.status === 'planning') {
+            await this.api.call('POST', `/projects/${this.opts.projectId}/start`);
+            this.io.log('프로젝트를 시작했다(G1)');
+        }
+    }
+    async runRound(r, s, round) {
+        const template = s.template;
+        const rs = (s.rounds[String(round)] ??= { taskIds: [], done: false });
+        let tasks = (await this.api.call('GET', `/projects/${this.opts.projectId}/tasks?limit=200`)).tasks;
+        // r1은 PM이 만든 그 태스크, r2부터는 꼬리표를 붙여 새로 만든다(이미 있는 제목은 건너뛴다 — 같은 --run으로 다시 돌린 경우).
+        const idByTitle = new Map();
+        for (const t of template) {
+            const title = roundTitle(t.title, this.opts.run, round);
+            const existing = tasks.find((x) => x.title === title);
+            if (existing) {
+                idByTitle.set(t.title, existing.id);
+                continue;
+            }
+            const created = await this.api.call('POST', `/projects/${this.opts.projectId}/tasks`, {
+                title,
+                teamRole: t.teamRole,
+                kind: t.kind,
+                repoId: t.repoId,
+                specId: t.specId,
+                dependsOn: t.dependsOn.map((d) => idByTitle.get(d)).filter((x) => x !== undefined),
+            });
+            idByTitle.set(t.title, created.id);
+            this.io.log(`  [${r.key}] r${round} 만듦 ${title}`);
+        }
+        rs.taskIds = [...idByTitle.values()];
+        await this.save();
+        this.io.log(`[${r.key}] r${round} 실행 중 (${rs.taskIds.length}개)`);
+        const started = this.io.now();
+        for (;;) {
+            tasks = (await this.api.call('GET', `/projects/${this.opts.projectId}/tasks?limit=200`)).tasks;
+            const mine = tasks.filter((t) => rs.taskIds.includes(t.id));
+            for (const t of mine)
+                await this.tidy(t);
+            const refreshed = (await this.api.call('GET', `/projects/${this.opts.projectId}/tasks?limit=200`)).tasks;
+            const open = refreshed.filter((t) => rs.taskIds.includes(t.id) && !FINISHED.has(t.state));
+            if (open.length === 0)
+                break;
+            if (this.io.now() - started >= this.opts.roundTimeoutMs) {
+                for (const t of open.filter((x) => CANCELLABLE.has(x.state)))
+                    await this.cancel(t, `r${round} 시간 초과`);
+                const left = open.filter((x) => !CANCELLABLE.has(x.state));
+                if (left.length > 0)
+                    this.io.log(`  ! r${round} 시간 초과 — 진행 중이라 취소하지 못한 태스크: ${left.map((t) => `${t.title}(${t.state})`).join(', ')}`);
+                rs.timedOut = true;
+                this.state.counters.timedOutRounds += 1;
+                break;
+            }
+            const detail = await this.api.call('GET', `/projects/${this.opts.projectId}`);
+            await this.health.check(refreshed, detail.project.status);
+            await this.io.sleep(this.opts.pollMs);
+        }
+        rs.done = true;
+        await this.save();
+        this.io.log(`[${r.key}] r${round} 끝`);
+    }
+    // 태스크 정리 규칙.
+    async tidy(t) {
+        if (t.state === 'DONE') {
+            this.health.success();
+            return;
+        }
+        const role = t.teamRole ?? '역할 없음';
+        if (t.state === 'BLOCKED' && t.blockedReason === 'AGENT_STOPPED') {
+            if (!this.state.resumedTaskIds.includes(t.id)) {
+                await this.api.call('POST', `/tasks/${t.id}/resume`, { note: '실험 감독 자동 재개(1회)' });
+                this.state.resumedTaskIds.push(t.id);
+                this.state.counters.resumed += 1;
+                await this.save();
+                this.io.log(`  재개 ${t.title}`);
+            }
+            else {
+                await this.cancel(t, '재개 뒤에도 멈춤');
+            }
+            // 역할을 가리지 않고 센다 — 로그인 만료·사용량 한도는 FE·BE 태스크가 번갈아 멈추는 모양으로도 나온다.
+            this.health.failure('task_stopped', `${role} 노트북의 Claude 로그인이 만료됐거나 사용량 한도에 닿았을 수 있다 — claude 로그인·사용량을 확인한 뒤 같은 명령을 다시 실행`);
+            return;
+        }
+        if (t.state === 'ESCALATED') {
+            await this.cancel(t, '재시도 소진(ESCALATED)');
+            this.health.failure('task_escalated', `${role} 태스크가 계속 검증·반려로 끝난다 — 명세·경로 소유권·검사기 설정을 확인한 뒤 같은 명령을 다시 실행`);
+        }
+    }
+    async cancel(t, why) {
+        await this.api.call('POST', `/tasks/${t.id}/cancel`, { reason: `실험 감독: ${why}` });
+        this.state.counters.cancelled += 1;
+        await this.save();
+        this.io.log(`  취소 ${t.title} (${why})`);
+    }
+}
+// --keep-going(24시간 무인용): 멈춤(HaltError)·일시 오류가 나도 끝내지 않고 알린 뒤 기다렸다가 같은 상태 파일로 이어 간다.
+// 노트북 재연결·pm-worker 재시작·예산 증액처럼 사람이 고치면 다음 시도에서 저절로 이어진다. 기다려도 풀리지 않는 설정 문제(permanent)만 끝낸다.
+// 감독은 매 시도 새로 만든다(make) — 고장 감지의 연속 실패 수·offline 시각을 이전 시도에서 끌고 오지 않는다.
+export async function superviseWithRetry(make, io, opts) {
+    let lastNotified = '';
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await make().run();
+        }
+        catch (err) {
+            if (err instanceof HaltError && err.permanent)
+                throw err;
+            const message = err.message;
+            const waitMin = Math.round(opts.retryWaitMs / 60_000);
+            io.log(`! ${err instanceof HaltError ? '멈춤' : '오류'}(${attempt}번째): ${message}`);
+            io.log(`  ${waitMin}분 뒤 이어 간다(--keep-going) — 그 사이 위 안내대로 고치면 된다`);
+            // 같은 문장을 계속 보내지 않는다 — 몇 시간 같은 고장이면 알림이 쌓인다.
+            if (message !== lastNotified) {
+                lastNotified = message;
+                await opts.notify(`${message} — ${waitMin}분 뒤 자동으로 이어 간다`);
+            }
+            await io.sleep(opts.retryWaitMs);
+        }
+    }
+}
+function chainOf(plans, rootId) {
+    const ids = new Set([rootId]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const p of plans)
+            if (p.parentPlanId && ids.has(p.parentPlanId) && !ids.has(p.id))
+                (ids.add(p.id), (grew = true));
+    }
+    return plans.filter((p) => ids.has(p.id));
+}
+export function buildExperimentReport(input) {
+    const byStage = {};
+    for (const item of input.dataset)
+        byStage[item.stage] = (byStage[item.stage] ?? 0) + 1;
+    const titleOf = new Map(input.tasks.map((t) => [t.id, t.title]));
+    const perTitle = new Map();
+    for (const item of input.dataset) {
+        const title = item.input.task?.title;
+        if (title)
+            perTitle.set(title, (perTitle.get(title) ?? 0) + 1);
+    }
+    const requirements = Object.entries(input.state.requirements).map(([key, s]) => {
+        const keys = new Set(s.featureKeys ?? []);
+        const planningQuestions = input.dataset.filter((d) => d.stage !== 'implementation' && d.input.spec && keys.has(d.input.spec.featureKey)).length;
+        const rounds = Object.entries(s.rounds)
+            .map(([n, rs]) => {
+            const counts = rs.taskIds.map((id) => perTitle.get(titleOf.get(id) ?? '') ?? 0);
+            return { round: Number(n), tasks: rs.taskIds.length, tasksWithQuestions: counts.filter((c) => c > 0).length, questions: counts.reduce((a, b) => a + b, 0) };
+        })
+            .sort((a, b) => a.round - b.round);
+        return { key, status: s.status, planningQuestions, rounds };
+    });
+    const routers = {};
+    const count = (router, target) => {
+        const k = target ?? '(실패)';
+        routers[router] ??= {};
+        routers[router][k] = (routers[router][k] ?? 0) + 1;
+    };
+    const rowOf = new Map(input.report.rows.map((r) => [r.questionId, r]));
+    for (const item of input.dataset) {
+        const row = rowOf.get(item.id);
+        if (row && Object.keys(row.decisions).length > 0)
+            for (const [router, target] of Object.entries(row.decisions))
+                count(router, target);
+        else
+            count(item.primary.router, item.primary.target);
+    }
+    return {
+        questions: input.dataset.length,
+        byStage,
+        requirements,
+        automatic: {
+            planRetries: input.plans.filter((p) => p.revisionCause === 'retry').length,
+            contractRetries: input.contracts.reduce((a, c) => a + (c.experimentRetries ?? 0), 0),
+            ...input.state.counters,
+        },
+        routers,
+    };
+}
+const pct = (a, b) => (b === 0 ? '-' : `${Math.round((a / b) * 100)}%`);
+export function formatExperimentReport(r) {
+    const lines = [];
+    lines.push(`질문 ${r.questions}건 (질문 행 기준) · 단계별: ${Object.entries(r.byStage).map(([s, n]) => `${s} ${n}`).join(' · ') || '없음'}`);
+    lines.push('');
+    lines.push('요구사항별 (기획 단계 질문 / 회차: 태스크 · 질문한 태스크 = 발생률 · 질문 수 · 태스크당 질문)');
+    for (const req of r.requirements) {
+        lines.push(`  [${req.key}] ${req.status} · 기획 단계 질문 ${req.planningQuestions}`);
+        for (const x of req.rounds) {
+            lines.push(`    r${x.round}: ${x.tasks} · ${x.tasksWithQuestions} = ${pct(x.tasksWithQuestions, x.tasks)} · ${x.questions} · ${(x.questions / Math.max(1, x.tasks)).toFixed(2)}`);
+        }
+    }
+    lines.push('');
+    const a = r.automatic;
+    lines.push(`자동 처리: 초안 재요청 ${a.planRetries} · 계약 재시도 ${a.contractRetries} · 재개 ${a.resumed} · 취소 ${a.cancelled} · 시간 초과 회차 ${a.timedOutRounds} · 포기한 요구사항 ${a.skippedRequirements}`);
+    lines.push('');
+    lines.push('라우터별 판정 분포 (primary + shadow + baseline, 대상별 건수)');
+    for (const [router, targets] of Object.entries(r.routers).sort((x, y) => x[0].localeCompare(y[0]))) {
+        lines.push(`  ${router}: ${Object.entries(targets).sort((x, y) => y[1] - x[1]).map(([t, n]) => `${t} ${n}`).join(' · ')}`);
+    }
+    return lines;
+}
+export async function experimentReport(api, projectId, state) {
+    const [dataset, report, tasks, plans, contracts] = await Promise.all([
+        api.call('GET', `/projects/${projectId}/routing-dataset`),
+        api.call('GET', `/projects/${projectId}/routing-report`),
+        api.call('GET', `/projects/${projectId}/tasks?limit=200`),
+        api.call('GET', `/projects/${projectId}/pm/plans`),
+        api.call('GET', `/projects/${projectId}/contracts`),
+    ]);
+    return buildExperimentReport({ state, dataset: dataset.items, report, tasks: tasks.tasks, plans: plans.plans, contracts: contracts.contracts });
+}

package/dist/executor/home-lock.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { nomosHome } from '../bridge/credentials.js';
+export function homeLockPath() {
+    return path.join(nomosHome(), 'agent.lock');
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // 권한이 없을 뿐 살아 있다.
+        return err.code === 'EPERM';
+    }
+}
+export function readHomeLock() {
+    try {
+        return JSON.parse(readFileSync(homeLockPath(), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// 잡지 못하면 이유를 담아 던진다. 끝날 때 자동으로 놓는다.
+export function acquireHomeLock(command) {
+    const file = homeLockPath();
+    const held = existsSync(file) ? readHomeLock() : null;
+    if (held && held.pid !== process.pid && alive(held.pid)) {
+        throw new Error(`이 폴더(${nomosHome()})는 다른 nomos 프로세스(pid ${held.pid}, ${held.command}, ${held.startedAt}부터)가 쓰고 있다. ` +
+            '한 노트북에서 에이전트를 여럿 돌리려면 창마다 NOMOS_HOME을 다르게 지정한다 — cmd: set NOMOS_HOME=%USERPROFILE%\.nomos-fe / PowerShell: $env:NOMOS_HOME="$HOME\.nomos-fe"');
+    }
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ pid: process.pid, command, startedAt: new Date().toISOString() })}\n`);
+    process.once('exit', () => {
+        if (readHomeLock()?.pid === process.pid)
+            rmSync(file, { force: true });
+    });
+}

package/dist/executor/human-http.js

@@ -0,0 +1,142 @@
+// 사람(대표) 계정으로 서버 API를 부르는 HTTP 도우미 — 서버 코드(env.ts·DB)를 거치지 않는다. 에이전트 쪽 nomos-client(bridge)와 달리 사람 토큰이다.
+// CLI의 무인 실험 감독(nomos experiment)과 레포 스크립트(question-probe·routing-report·experiment-run, scripts/lib/nomos-http.ts가 다시 내보낸다)가 같이 쓴다.
+// 인증: NOMOS_TOKEN(이미 받은 사람 토큰) 또는 --login + NOMOS_PASSWORD(없으면 화면에 안 보이는 입력 창). 토큰·비밀번호는 출력하지 않는다.
+// 입력한 글자를 화면에 찍지 않는 비밀번호 입력.
+export async function readHidden(prompt) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY)
+        throw new Error('비밀번호를 입력받을 터미널이 없다 — NOMOS_PASSWORD 또는 NOMOS_TOKEN을 설정하라');
+    process.stdout.write(prompt);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    return new Promise((resolve, reject) => {
+        let buf = '';
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n') {
+                    cleanup();
+                    process.stdout.write('\n');
+                    resolve(buf);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    cleanup();
+                    reject(new Error('취소했다'));
+                    return;
+                }
+                if (ch === '\u007f' || ch === '\b')
+                    buf = buf.slice(0, -1);
+                else
+                    buf += ch;
+            }
+        };
+        const cleanup = () => {
+            stdin.off('data', onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+        };
+        stdin.on('data', onData);
+    });
+}
+// 일시적인 실패(연결 끊김·응답 없음·배포 중 502/503/504)에는 GET만 다시 시도한다. POST 등은 서버가 이미 처리했을 수 있어(태스크·기능 명세가 두 번 생긴다) 다시 보내지 않는다 —
+// 그런 실패는 감독의 --keep-going이 상태 파일에서 이어 가며 메운다(이미 만든 것은 다시 만들지 않는다).
+const TRANSIENT_STATUS = new Set([502, 503, 504]);
+const GET_RETRY_DELAYS_MS = [2_000, 5_000, 15_000, 30_000, 60_000];
+export class NomosHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class NomosHttp {
+    base;
+    token;
+    retryDelaysMs;
+    relogin = null;
+    constructor(base, token = '', retryDelaysMs = GET_RETRY_DELAYS_MS) {
+        this.base = base;
+        this.token = token;
+        this.retryDelaysMs = retryDelaysMs;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    // 사람 토큰은 24시간이면 만료된다 — 하루 넘게 도는 감독이 그 순간 죽지 않게, 401이면 같은 아이디·비밀번호로 다시 로그인하고 원 요청을 1회 재시도한다.
+    // 비밀번호는 이 프로세스 메모리에만 있다(파일·로그에 남기지 않는다).
+    setRelogin(relogin) {
+        this.relogin = relogin;
+    }
+    async call(method, path, body) {
+        try {
+            return await this.callWithRetry(method, path, body);
+        }
+        catch (err) {
+            if (!(err instanceof NomosHttpError) || err.status !== 401 || !this.relogin || path === '/auth/login')
+                throw err;
+            await this.relogin();
+            return this.callWithRetry(method, path, body);
+        }
+    }
+    async callWithRetry(method, path, body) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await this.once(method, path, body);
+            }
+            catch (err) {
+                const transient = !(err instanceof NomosHttpError) || TRANSIENT_STATUS.has(err.status);
+                const delay = this.retryDelaysMs[attempt];
+                if (method !== 'GET' || !transient || delay === undefined)
+                    throw err;
+                process.stderr.write(`  (일시 오류, ${Math.round(delay / 1000)}초 뒤 다시: ${err.message.slice(0, 160)})\n`);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+    }
+    async once(method, path, body) {
+        const res = await fetch(`${this.base}/api${path}`, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            // 응답 없이 매달린 연결이 감독을 영원히 붙잡지 않게(감독은 long-poll API를 부르지 않는다).
+            signal: AbortSignal.timeout(60_000),
+        });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // HTML 오류 페이지 등
+        }
+        if (!res.ok) {
+            const err = json?.error;
+            const detail = err?.details ? ` ${JSON.stringify(err.details)}` : '';
+            throw new NomosHttpError(res.status, `${method} ${path} → ${res.status} ${err?.code ?? ''} ${err?.message ?? text.slice(0, 200)}${detail}`);
+        }
+        return json.data;
+    }
+}
+export async function signIn(api, loginId) {
+    const preset = process.env.NOMOS_TOKEN;
+    if (preset) {
+        api.setToken(preset); // 받은 토큰은 다시 발급할 수단이 없다 — 만료되면 401로 멈춘다.
+        return;
+    }
+    if (!loginId)
+        throw new Error('--login이 필요하다 (또는 NOMOS_TOKEN)');
+    let password = process.env.NOMOS_PASSWORD ?? (await readHidden(`${loginId} 비밀번호: `));
+    // 붙여 넣은 명령 끝의 줄바꿈이 입력 창에 그대로 들어가 빈 비밀번호가 나간 일이 있었다(400 VALIDATION_ERROR) — 비었으면 다시 묻는다.
+    while (password === '' && process.env.NOMOS_PASSWORD === undefined)
+        password = await readHidden(`비밀번호가 비었다. ${loginId} 비밀번호: `);
+    const login = async () => {
+        const auth = await api.call('POST', '/auth/login', { loginId, password });
+        api.setToken(auth.accessToken);
+    };
+    await login();
+    api.setRelogin(login);
+}

package/dist/executor/prompt.js

@@ -53,6 +53,24 @@ export function buildTaskPrompt(briefing, branch, environment) {
         ].join('\n'));
     }
     // 사람(그 역할 담당·대표)이 룸에서 보낸 메시지 — 이번 실행이 시작되기 전에 온 것만 들어온다(실행 중에는 끼워 넣지 않는다).
+    // 선행 작업 위에서 시작했다 — 선행이 만든 코드가 이미 이 브랜치에 있다. 못 합친 선행은 다시 만들지 말고 멈추게 한다
+    // (남의 작업을 지어내면 V3·리뷰에서 엉뚱한 diff가 된다 — 운영 실험의 BE도 그래서 멈췄다).
+    const pm = briefing.predecessorMerge;
+    if (pm && (pm.merged.length > 0 || pm.failed.length > 0)) {
+        sections.push([
+            '# 선행 작업 위에서 시작한다',
+            ...(pm.merged.length > 0
+                ? ['이 브랜치에 선행 태스크의 코드가 이미 합쳐져 있다 — 그 위에 이어서 구현한다(다시 만들지 않는다):', ...pm.merged.map((m) => `- ${m.title} (${m.commitSha.slice(0, 12)})`)]
+                : []),
+            ...(pm.failed.length > 0
+                ? [
+                    '합치지 못한 선행 태스크가 있다 — 그 코드는 이 브랜치에 없다:',
+                    ...pm.failed.map((f) => `- ${f.predecessor.title}: ${f.reason}`),
+                    '그 코드가 꼭 필요하면 직접 다시 만들지 말고, 커밋하지 말고 멈춘 뒤 마지막 메시지에 무엇이 없어서 막혔는지 적는다.',
+                ]
+                : []),
+        ].join('\n'));
+    }
     if (briefing.humanMessages && briefing.humanMessages.length > 0) {
         sections.push([
             '# 담당자가 보낸 메시지 (팀의 사람이 이 역할 에이전트에게 남긴 지시 — 오래된 것부터)',

package/dist/executor/workspace.js

@@ -46,6 +46,7 @@ export function prepareWorkspace(input) {
     const dir = workspaceDir(input.projectId, input.taskId);
     const branch = input.branchName ?? `task/${input.taskId}`;
     const existed = branchExists(input.repoPath, branch);
+    let startedFresh = false;
     excludeNomosFiles(input.repoPath);
     if (!existsSync(dir)) {
         mkdirSync(path.dirname(dir), { recursive: true });
@@ -57,6 +58,7 @@ export function prepareWorkspace(input) {
             : refExists(input.repoPath, remote)
                 ? ['worktree', 'add', '-b', branch, dir, `origin/${branch}`]
                 : ['worktree', 'add', '-b', branch, dir, input.baseBranch];
+        startedFresh = args.at(-1) === input.baseBranch;
         git(input.repoPath, args);
     }
     const claudeDir = path.join(dir, '.claude');
@@ -64,7 +66,58 @@ export function prepareWorkspace(input) {
     const settingsPath = path.join(claudeDir, 'settings.json');
     writeFileSync(settingsPath, `${JSON.stringify(input.settings, null, 2)}\n`);
     writeFileSync(path.join(claudeDir, '.nomos-policy.json'), `${JSON.stringify({ policyHash: input.policyHash, taskId: input.taskId, generatedAt: new Date().toISOString() }, null, 2)}\n`);
-    return { dir, branch, createdBranch: !existed, settingsPath };
+    return { dir, branch, createdBranch: !existed, startedFresh, settingsPath };
+}
+const SHA = /^[0-9a-f]{7,64}$/i;
+const BRANCH = /^[A-Za-z0-9._/-]+$/;
+// 원격 브랜치의 커밋을 이 레포로 받아 둔다(서버가 만든 시작 기준점, 선행 브랜치). 이미 있거나 받았으면 true.
+export function fetchCommit(repoPath, branchName, commitSha) {
+    if (!SHA.test(commitSha))
+        return false;
+    if (refExists(repoPath, `${commitSha}^{commit}`))
+        return true;
+    if (branchName && BRANCH.test(branchName) && !branchName.startsWith('-')) {
+        try {
+            execFileSync('git', ['fetch', '--quiet', 'origin', `refs/heads/${branchName}`], { cwd: repoPath, stdio: 'ignore' });
+        }
+        catch {
+            // origin이 없거나(로컬 레포) 브랜치가 없다.
+        }
+    }
+    return refExists(repoPath, `${commitSha}^{commit}`);
+}
+// 새로 딴 태스크 브랜치에 선행 커밋을 오래된 것부터 합친다(앞서면 빨리 감기, 아니면 병합 커밋). 모델이 아니라 Executor가 한다 —
+// 모델의 git은 merge·cherry-pick이 막혀 있다. 커밋이 없으면 선행 브랜치를 받아 온다. 충돌이나 실패는 되돌리고 건너뛴다 —
+// 실행을 막으면 태스크가 READY로 남아 같은 실패를 되풀이하므로, 프롬프트에 "합치지 못했다"를 적고 모델이 멈출지 판단하게 한다.
+// 서버의 V3는 같은 커밋들을 비교 기준으로 써서 선행의 파일을 이 태스크의 변경으로 세지 않는다.
+export function mergePredecessors(dir, predecessors) {
+    const result = { merged: [], failed: [] };
+    for (const p of predecessors) {
+        if (!SHA.test(p.commitSha)) {
+            result.failed.push({ predecessor: p, reason: '커밋 형식이 아니다' });
+            continue;
+        }
+        if (!fetchCommit(dir, p.branchName, p.commitSha)) {
+            result.failed.push({ predecessor: p, reason: `커밋 ${p.commitSha.slice(0, 12)}을 찾지 못했다(선행 브랜치 ${p.branchName ?? '?'}가 push되지 않았거나 지워졌다)` });
+            continue;
+        }
+        try {
+            execFileSync('git', ['merge', '--no-edit', '-m', `nomos: 선행 태스크 합침 — ${p.title.slice(0, 120)}`, p.commitSha], { cwd: dir, stdio: 'pipe' });
+            result.merged.push(p);
+        }
+        catch (err) {
+            try {
+                execFileSync('git', ['merge', '--abort'], { cwd: dir, stdio: 'ignore' });
+            }
+            catch {
+                // 병합이 시작되지도 않았다(신원 미설정 등) — 되돌릴 것이 없다.
+            }
+            // 충돌 안내(CONFLICT ...)는 stdout으로, 그 밖의 실패는 stderr로 나온다.
+            const stderr = `${String(err.stdout ?? '')}\n${String(err.stderr ?? '')}`.trim();
+            result.failed.push({ predecessor: p, reason: /conflict/i.test(stderr) ? '병합 충돌' : `병합 실패: ${stderr.split('\n')[0]?.slice(0, 200) ?? ''}` });
+        }
+    }
+    return result;
 }
 // Executor가 작업공간에 쓰는 파일(MCP 설정·실행 로그·브리핑 노트·정책 표시·settings.json)이 모델의 `git add`에 섞이지 않게 한다.
 // 커밋에 섞이면 신고 경로와 실제 diff가 어긋나 V3가 FAIL을 낸다. info/exclude는 레포 공통이라 모든 worktree에 걸린다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capstone-nomos/cli",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "NOMOS 에이전트 CLI — 노트북의 Claude Code를 NOMOS 서버에 연결하고 배정된 태스크를 실행한다",
   "type": "module",
   "bin": {