@mcpeak/cli 0.9.0 → 0.10.0

package/README.md

@@ -22,7 +22,7 @@ mcpeak test packages/cli/tests/fixtures/weather-suite.json \
   --arg examples/weather-server/server.mjs
 ```
 
-문법은 `mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--json] [--junit <path>] [--stderr-lines <N>]`입니다. 위 예시의 command와 arg는 `node examples/weather-server/server.mjs`로 실행됩니다. `--arg`는 반복할 수 있고, 하이픈으로 시작하는 값은 `--arg=-m`, 빈 값은 `--arg=`로 전달합니다.
+문법은 `mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--json] [--junit <path>] [--stderr-lines <N>] [--record-session <path> | --session <path>]`입니다. 위 예시의 command와 arg는 `node examples/weather-server/server.mjs`로 실행됩니다. `--arg`는 반복할 수 있고, 하이픈으로 시작하는 값은 `--arg=-m`, 빈 값은 `--arg=`로 전달합니다.
 
 stdout에는 보고서만 나갑니다. 기본은 사람이 읽는 보고서이고, `--json`을 주면 `RunnerReport` JSON이 나갑니다. CLI 오류와 서버 프로세스 진단은 stderr로만 나가므로 `--json > report.json`이 깨지지 않습니다. 모든 테스트가 통과하면 종료 코드 0을, failed 또는 aborted report와 입력, 연결, 종료 오류에는 1을 반환합니다.
 
@@ -40,6 +40,11 @@ XML을 만드는 단계에서 실패하면 `CLI_INTERNAL_ERROR`와 함께 종료
 
 `RunnerReport`에는 시간 정보가 없어 모든 `time` 속성은 `0`입니다. "0초 걸렸다"가 아니라 "시간 정보를 갖고 있지 않다"는 뜻입니다. 근거는 [ADR-0016](../../docs/adr/0016-junit-time-속성-고정.md), 플래그 설계는 [ADR-0019](../../docs/adr/0019-junit-리포터-cli-노출-방식.md)에 있습니다.
 
+`--record-session <path>`는 서버가 `globalThis.fetch`로 호출한 외부 HTTP 응답을 녹화하고,
+`--session <path>`는 그 녹화본을 재생합니다. 서버는 재생 때도 실제로 실행됩니다. `node:http`와
+`node:https` 계층 호출은 범위 밖이라 실제 네트워크로 나갈 수 있으며, CLI는 녹화 0건이나 재생
+0건처럼 범위 밖 호출이 의심되는 실행을 stderr 알림으로 드러냅니다.
+
 `--stderr-lines <N>`은 실패했거나 서버가 비정상 종료·중단했을 때, 진단 내용이 있으면 stderr에 붙는 서버 프로세스 진단 블록의 stderr 표시 줄 수입니다. 기본값은 20이고, `0`을 주면 블록을 완전히 끕니다(그때 출력 바이트는 이 기능이 없던 때와 같습니다). 블록에는 종료 코드와 시그널, 서버가 남긴 stderr의 마지막 N줄이 담기며 잘린 사실은 헤더에 적힙니다. 서버가 정상 종료했고 stderr도 비어 있으면 보여줄 근거가 없으므로 블록을 쓰지 않습니다.
 
 ### 승인 지문 대조
@@ -60,7 +65,7 @@ XML을 만드는 단계에서 실패하면 `CLI_INTERNAL_ERROR`와 함께 종료
 
 지문이 없는 명세도 정상입니다. 손으로 쓴 명세와 이 기능 이전에 만든 명세가 여기에 해당하며 실패로 취급하지 않습니다.
 
-현재는 UTF-8 JSON 단일 명세와 stdio 서버만 지원합니다. shell 문법, 여러 명세, TypeScript 모듈 명세는 지원하지 않습니다. `record`, `replay`, `mock` 명령은 아직 구현되지 않았습니다.
+현재는 UTF-8 JSON 단일 명세와 stdio 서버만 지원합니다. shell 문법, 여러 명세, TypeScript 모듈 명세는 지원하지 않습니다. `record`, `mock` 명령은 아직 구현되지 않았습니다.
 
 ## generate
 

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 //#region src/cli.ts
-require("./src-Df8147pD.cjs").run(process.argv.slice(2)).then((code) => {
+require("./src-CwhDFSWk.cjs").run(process.argv.slice(2)).then((code) => {
 	process.exitCode = code;
 });
 //#endregion

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as run } from "./src-D1NW6ckv.mjs";
+import { r as run } from "./src-BzVS8KXQ.mjs";
 //#region src/cli.ts
 run(process.argv.slice(2)).then((code) => {
 	process.exitCode = code;

package/dist/commands.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_test_command = require("./test-command-BZ_94UmI.cjs");
+const require_test_command = require("./test-command-BbjJIX7j.cjs");
 exports.nodeGenerateDependencies = require_test_command.nodeGenerateDependencies;
 exports.nodeReviewIO = require_test_command.nodeReviewIO;
 exports.parseRepairCommand = require_test_command.parseRepairCommand;

package/dist/commands.d.cts

@@ -1,6 +1,7 @@
 import { a as RepairCommandDependencies, c as runRepairCommand, d as ReviewIO, f as nodeGenerateDependencies, i as runReplayCommand, l as GenerateCommandDependencies, m as runGenerateCommand, n as ReplayCommandInput, o as RepairCommandInput, p as nodeReviewIO, r as parseReplayCommand, s as parseRepairCommand, t as ReplayCommandDependencies, u as GenerateCommandInput } from "./replay-command-V0ZSJPiD.cjs";
 import { McpStdioConnection } from "@mcpeak/core";
 import { CheckDeterminismOptions, DeterminismResult, FinalizeRunnerExecutionOptions, InputContractOptions, RunSuiteOptions, RunnerExecution, RunnerReport, SpecFindingsResult, SuiteValidationIssue, SuiteValidationResult, TestSuiteSpec } from "@mcpeak/runner";
+import "@mcpeak/record/external";
 //#region src/test-command.d.ts
 interface TestCommandInput {
   readonly suitePath: string;
@@ -15,9 +16,13 @@ interface TestCommandInput {
   readonly determinism: boolean;
   /** `--reset-cmd` 로 받은 초기화 명령. 각 회차 전에 1번씩 실행한다. */
   readonly resetCmd: string | undefined;
+  /** `--session`. External 세션을 재생한다. */
+  readonly sessionPath: string | undefined;
+  /** `--record-session`. External 세션을 녹화한다. */
+  readonly recordSessionPath: string | undefined;
   readonly stderrLines: number;
 }
-type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "CLI_INTERNAL_ERROR";
+type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "EXTERNAL_SESSION_FAILED" | "CLI_INTERNAL_ERROR";
 interface CliFailure {
   readonly code: CliErrorCode;
   readonly message: string;
@@ -31,6 +36,8 @@ interface TestCommandDependencies {
   connect(options: {
     command: string;
     args: readonly string[];
+    /** External 배선이 만든 자식 환경 변수. Bootstrap 주입이 여기 실린다. */
+    env?: Readonly<Record<string, string>>;
   }): Promise<McpStdioConnection>;
   startRunner(options: RunSuiteOptions): RunnerExecution;
   finalize(options: FinalizeRunnerExecutionOptions): Promise<RunnerReport>;
@@ -62,6 +69,15 @@ interface TestCommandDependencies {
   writeStderr(text: string): void;
 }
 declare function parseTestCommand(argv: readonly string[]): TestCommandInput;
+/**
+ * `test` 실행에 External Record/Replay 수명주기를 씌운다.
+ *
+ * Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+ * 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+ * 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+ *
+ * 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+ */
 declare function runCli(argv: readonly string[], dependencies: TestCommandDependencies): Promise<number>;
 //#endregion
 export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReplayCommandDependencies, type ReplayCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };

package/dist/commands.d.mts

@@ -1,6 +1,7 @@
 import { a as RepairCommandDependencies, c as runRepairCommand, d as ReviewIO, f as nodeGenerateDependencies, i as runReplayCommand, l as GenerateCommandDependencies, m as runGenerateCommand, n as ReplayCommandInput, o as RepairCommandInput, p as nodeReviewIO, r as parseReplayCommand, s as parseRepairCommand, t as ReplayCommandDependencies, u as GenerateCommandInput } from "./replay-command-BAtSzf8R.mjs";
 import { CheckDeterminismOptions, DeterminismResult, FinalizeRunnerExecutionOptions, InputContractOptions, RunSuiteOptions, RunnerExecution, RunnerReport, SpecFindingsResult, SuiteValidationIssue, SuiteValidationResult, TestSuiteSpec } from "@mcpeak/runner";
 import { McpStdioConnection } from "@mcpeak/core";
+import "@mcpeak/record/external";
 //#region src/test-command.d.ts
 interface TestCommandInput {
   readonly suitePath: string;
@@ -15,9 +16,13 @@ interface TestCommandInput {
   readonly determinism: boolean;
   /** `--reset-cmd` 로 받은 초기화 명령. 각 회차 전에 1번씩 실행한다. */
   readonly resetCmd: string | undefined;
+  /** `--session`. External 세션을 재생한다. */
+  readonly sessionPath: string | undefined;
+  /** `--record-session`. External 세션을 녹화한다. */
+  readonly recordSessionPath: string | undefined;
   readonly stderrLines: number;
 }
-type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "CLI_INTERNAL_ERROR";
+type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "EXTERNAL_SESSION_FAILED" | "CLI_INTERNAL_ERROR";
 interface CliFailure {
   readonly code: CliErrorCode;
   readonly message: string;
@@ -31,6 +36,8 @@ interface TestCommandDependencies {
   connect(options: {
     command: string;
     args: readonly string[];
+    /** External 배선이 만든 자식 환경 변수. Bootstrap 주입이 여기 실린다. */
+    env?: Readonly<Record<string, string>>;
   }): Promise<McpStdioConnection>;
   startRunner(options: RunSuiteOptions): RunnerExecution;
   finalize(options: FinalizeRunnerExecutionOptions): Promise<RunnerReport>;
@@ -62,6 +69,15 @@ interface TestCommandDependencies {
   writeStderr(text: string): void;
 }
 declare function parseTestCommand(argv: readonly string[]): TestCommandInput;
+/**
+ * `test` 실행에 External Record/Replay 수명주기를 씌운다.
+ *
+ * Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+ * 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+ * 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+ *
+ * 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+ */
 declare function runCli(argv: readonly string[], dependencies: TestCommandDependencies): Promise<number>;
 //#endregion
 export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReplayCommandDependencies, type ReplayCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };

package/dist/commands.mjs

@@ -1,2 +1,2 @@
-import { a as runReplayCommand, c as nodeGenerateDependencies, i as parseReplayCommand, l as nodeReviewIO, n as runCli, o as parseRepairCommand, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CsJfojut.mjs";
+import { a as runReplayCommand, c as nodeGenerateDependencies, i as parseReplayCommand, l as nodeReviewIO, n as runCli, o as parseRepairCommand, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CtQbeyhy.mjs";
 export { nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-Df8147pD.cjs");
+const require_src = require("./src-CwhDFSWk.cjs");
 exports.COMMANDS = require_src.COMMANDS;
 exports.nodeRepairDependencies = require_src.nodeRepairDependencies;
 exports.run = require_src.run;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { i as unavailableReplayDependencies, n as nodeRepairDependencies, r as run, t as COMMANDS } from "./src-D1NW6ckv.mjs";
+import { i as unavailableReplayDependencies, n as nodeRepairDependencies, r as run, t as COMMANDS } from "./src-BzVS8KXQ.mjs";
 export { COMMANDS, nodeRepairDependencies, run, unavailableReplayDependencies };

package/dist/{src-D1NW6ckv.mjs → src-BzVS8KXQ.mjs}

@@ -1,4 +1,4 @@
-import { a as runReplayCommand, c as nodeGenerateDependencies, d as GLOBAL_HELP, f as VERIFY_USAGE_HINT, l as nodeReviewIO, m as version, n as runCli, p as commandHelp, r as ReplayRuntimeUnavailableError, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CsJfojut.mjs";
+import { a as runReplayCommand, c as nodeGenerateDependencies, d as GLOBAL_HELP, f as VERIFY_USAGE_HINT, l as nodeReviewIO, m as version, n as runCli, p as commandHelp, r as ReplayRuntimeUnavailableError, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CtQbeyhy.mjs";
 import { readFile, writeFile } from "node:fs/promises";
 //#region src/verify-command.ts
 /**

package/dist/{src-Df8147pD.cjs → src-CwhDFSWk.cjs}

@@ -1,4 +1,4 @@
-const require_test_command = require("./test-command-BZ_94UmI.cjs");
+const require_test_command = require("./test-command-BbjJIX7j.cjs");
 let node_fs_promises = require("node:fs/promises");
 //#region src/verify-command.ts
 /**

package/dist/{test-command-BZ_94UmI.cjs → test-command-BbjJIX7j.cjs}

@@ -6,7 +6,7 @@ let _mcpeak_record = require("@mcpeak/record");
 let node_child_process = require("node:child_process");
 let _mcpeak_core = require("@mcpeak/core");
 //#region package.json
-var version = "0.9.0";
+var version = "0.10.0";
 //#endregion
 //#region src/cassette-wiring.ts
 /**
@@ -320,7 +320,7 @@ const FINDING_GROUP = {
 };
 //#endregion
 //#region src/help.ts
-const TEST_USAGE = "사용법: mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--determinism] [--reset-cmd <command>] [--json] [--junit <path>] [--repair-bundle <path>] [--stderr-lines <N>]";
+const TEST_USAGE = "사용법: mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--determinism] [--reset-cmd <command>] [--json] [--junit <path>] [--repair-bundle <path>] [--stderr-lines <N>] [--session <path> | --record-session <path>]";
 /**
 * 시험 실행 옵션 설명. `--determinism` 은 툴을 2회 호출하므로 부작용이 있는 서버에서 모르고
 * 쓰면 사고가 난다. 그 경고가 사용법 한 줄에는 들어가지 않는다.
@@ -331,7 +331,31 @@ const TEST_OPTIONS = `옵션:
                         --reset-cmd 와 함께 쓰면 결정론성 확인이 되고, 없으면
                         "2회 결과가 같았다" 까지만 확인합니다
   --reset-cmd <command> 각 시험 실행 전에 이 명령을 한 번 실행합니다. 셸을 거치지
-                        않으므로 파이프나 && 는 쓸 수 없습니다`;
+                        않으므로 파이프나 && 는 쓸 수 없습니다
+  --record-session <path>
+                        서버가 \`globalThis.fetch\` 로 밖에 부른 HTTP 호출만 녹화합니다.
+                        서버는 실제로 실행됩니다. \`node:http\`·\`node:https\` 같은 범위 밖 호출은
+                        잡히지 않아 실제 네트워크로 나갈 수 있습니다
+  --session <path>      녹화한 외부 호출을 재생합니다. 서버는 실제로 실행되지만 외부
+                        API 호출은 \`globalThis.fetch\` 범위 안에서만 가로챕니다.
+                        범위 밖 호출은 실제 네트워크로 나갈 수 있으며, 범위 밖 호출이
+                        의심되는 경우 종료 때 알립니다
+
+두 세션 옵션은 서로, 그리고 \`--determinism\` 과 함께 쓸 수 없습니다. \`--determinism\` 은 서버에
+2회 연결하는데 세션은 연결 하나에 묶여 있어, 2회차가 같은 세션을 쓰면 반복 호출 순번이
+어긋나고 새 세션을 쓰면 비교 기준이 갈라집니다.
+
+세션은 \`--cassette\` 카세트와 다릅니다. **카세트는 우리가 서버에게 물어본 결과**를 남기고,
+**세션은 그 서버가 밖에 물어본 결과**를 남깁니다. 둘은 섞이지 않으며 파일도 따로입니다.
+
+세션 파일에는 외부 API 응답이 저장되므로 .gitignore 를 확인하세요. \`token\`·\`apiKey\` 같은
+이름의 값은 저장 전에 가려집니다.
+
+런타임에 따라 세션 옵션을 쓴 실행에서 \`ExperimentalWarning: SQLite is an experimental
+feature\` 가 stderr 에 한 줄 찍힙니다(실측: Node 22.18.0 에서 나오고 24.16.0 에서는 안 납니다).
+\`node:sqlite\` 를 처음 로드할 때 한 번 나오므로 실행당 한 줄이며, 세션 옵션이 없는 실행에는
+붙지 않습니다. Node 가 그 모듈을 아직 실험적으로 표시한다는 뜻이고, **저장된 녹화는 표준
+SQLite 파일이라 영향받지 않습니다.**`;
 const GENERATE_USAGE = "사용법: mcpeak generate --suite-id <id> --name <name> --out <suite.json> --command <executable> [--arg <value> ...] [--baseline-only] [--provider <codex|claude>] [--model <model>] [--no-dry-run] [--cassette <path>] [--record] [--reset-cmd <command>] [--no-repair] [--force]";
 /**
 * 시험 실행 옵션 설명. 사용법 한 줄로는 `--cassette` 가 무엇을 파일로 남기는지, `--reset-cmd`
@@ -403,7 +427,7 @@ auto 모드(\`--record\` 없는 실행)는 카세트에 있는 요청이면 서
 마스킹해 비교하므로, 비밀값 자체만 바뀐 경우는 감지되지 않습니다.
 
 불일치나 호출 실패가 하나라도 있으면 종료 코드 1 입니다. 확인불가는 실패로 보지 않습니다.`;
-const GLOBAL_HELP = `OhMyMCP — MCP 서버 테스트 프레임워크
+const GLOBAL_HELP = `MCPeak — MCP 서버 테스트 프레임워크
 
 사용법: mcpeak <명령> [옵션]
         mcpeak help [명령]
@@ -833,6 +857,18 @@ function dropSkippedTools(suite, skips) {
 }
 //#endregion
 //#region src/process-diagnostics.ts
+/**
+* core 의 stdio 프로세스 진단인지 구조와 값의 범위로 확인한다.
+* 일부 필드만 있거나 프로세스 상태로 표현할 수 없는 값은 렌더하지 않는다.
+*/
+function processDiagnostics(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	if (!("stderr" in value) || typeof value.stderr !== "string") return void 0;
+	if (!("stderrTruncated" in value) || typeof value.stderrTruncated !== "boolean") return void 0;
+	if (!("exitCode" in value) || !(value.exitCode === null || typeof value.exitCode === "number" && Number.isInteger(value.exitCode))) return void 0;
+	if (!("signal" in value) || !(value.signal === null || typeof value.signal === "string" && value.signal.length > 0)) return void 0;
+	return value;
+}
 /** TAB. 이 모듈만 이스케이프 대상에서 빼는 문자다. 아래 escapeTokens 주석에 근거가 있다. */
 const TAB = 9;
 /**
@@ -2793,8 +2829,14 @@ async function runGenerateCommand(argv, deps) {
 		else if (error instanceof OutputReplaceError) outputReplaceFailure(deps, error.path, error.code);
 		else if (error instanceof LinkUnsupportedError) linkUnsupportedFailure(deps, error.path, error.code);
 		else if (deps.GenerateTestsError !== void 0 && error instanceof deps.GenerateTestsError) generateTestsFailure(deps, error);
-		else if (isCoreClientError(error)) deps.writeStderr(`오류 [GENERATE_CONNECT_FAILED/${error.code}]: ${error.message}\n해결: ${error.hint}\n`);
-		else deps.writeStderr("오류 [GENERATE_FAILED]: baseline suite를 생성하거나 저장하지 못했습니다.\n해결: MCP 서버와 출력 경로를 확인한 뒤 다시 실행하세요.\n");
+		else if (isCoreClientError(error)) {
+			deps.writeStderr(`오류 [GENERATE_CONNECT_FAILED/${error.code}]: ${error.message}\n해결: ${error.hint}\n`);
+			const diagnostics = processDiagnostics(error.diagnostics);
+			if (diagnostics !== void 0 && hasDiagnosticContent(diagnostics)) {
+				const block = renderProcessDiagnostics(diagnostics, { maxLines: DRY_RUN_STDERR_LINES });
+				if (block !== "") deps.writeStderr(`\n${block}`);
+			}
+		} else deps.writeStderr("오류 [GENERATE_FAILED]: baseline suite를 생성하거나 저장하지 못했습니다.\n해결: MCP 서버와 출력 경로를 확인한 뒤 다시 실행하세요.\n");
 		return 1;
 	}
 	try {
@@ -3689,6 +3731,51 @@ function createDeterminismCapture(inner) {
 	};
 }
 //#endregion
+//#region src/external-wiring.ts
+/**
+* `@mcpeak/record/external` 은 **세션 옵션을 실제로 쓸 때만** 불러온다.
+*
+* 정적 import 로 두면 `node:sqlite` 가 CLI 를 띄우는 것만으로 로드되고, Node 22.x 는 그때
+* `ExperimentalWarning: SQLite is an experimental feature` 를 stderr 에 찍는다. 세션을 쓰지도
+* 않은 `mcpeak test` 실행마다 그 줄이 붙는다 — 터미널 출력이 곧 UI 인 도구에서 그냥 손해다.
+* (실제로 `dist-cli-e2e` 의 "stderr 가 비어 있다" 단언이 이걸 잡았다.)
+*
+* 지연 로딩이면 경고를 보는 사람은 External 을 직접 켠 사용자뿐이다. 그 경고를 아예 지울지는
+* ADR-0054 가 남겨 둔 별도 결정이며, 라이브러리가 아니라 CLI 가 정할 몫이다.
+*/
+const loadExternal = () => import("@mcpeak/record/external");
+/** 세션 파일 하나가 세션 하나이므로 식별자를 사용자에게 묻지 않는다. */
+const SESSION_ID = "default";
+async function startExternalWiring(options) {
+	const { createSqliteSessionStore, startExternalCoordinator } = await loadExternal();
+	const store = createSqliteSessionStore({ path: options.sessionPath });
+	let handle;
+	try {
+		handle = options.mode === "record" ? await startExternalCoordinator({
+			mode: "record",
+			sessionId: SESSION_ID,
+			store,
+			...options.existingNodeOptions === void 0 ? {} : { existingNodeOptions: options.existingNodeOptions }
+		}) : await startExternalCoordinator({
+			mode: "replay",
+			sourceSessionId: SESSION_ID,
+			store,
+			...options.existingNodeOptions === void 0 ? {} : { existingNodeOptions: options.existingNodeOptions }
+		});
+	} catch (error) {
+		store.close();
+		throw error;
+	}
+	let settled;
+	return {
+		env: handle.childEnvironment,
+		finish(status) {
+			settled ??= handle.finish(status).finally(() => store.close());
+			return settled;
+		}
+	};
+}
+//#endregion
 //#region src/test-command.ts
 /** --stderr-lines 기본값. 설계 문서 §6. */
 const DEFAULT_STDERR_LINES = 20;
@@ -3737,6 +3824,10 @@ const dictionary = {
 		message: "초기화 명령이 실패했습니다.",
 		hint: "`--reset-cmd` 명령이 단독으로 성공하는지 확인한 뒤 다시 실행하세요."
 	},
+	EXTERNAL_SESSION_FAILED: {
+		message: "External 세션 처리에 실패했습니다.",
+		hint: "세션 파일 경로의 디렉터리가 있는지와 쓰기 권한을 확인하세요."
+	},
 	CLI_INTERNAL_ERROR: {
 		message: "예상하지 못한 CLI 내부 오류가 발생했습니다.",
 		hint: "다시 실행한 뒤 재현 정보와 함께 이슈를 보고하세요."
@@ -3756,6 +3847,30 @@ const fail = (message) => {
 		hint: TEST_USAGE_HINT
 	});
 };
+/**
+* `--name value` 와 `--name=value` 두 형태에서 값을 꺼낸다.
+*
+* 값이 `--` 로 시작하면 거절한다. `--session --json` 처럼 값을 빠뜨리면 다음 옵션이 경로로
+* 먹히고, 그러면 "그런 파일이 없습니다" 라는 엉뚱한 곳에서 실패한다.
+*/
+const readOptionValue = (argv, token, name, index) => {
+	let value;
+	let next = index;
+	if (token === name) {
+		const candidate = argv[++next];
+		if (candidate === void 0) throw new CliCommandError({
+			code: "CLI_USAGE",
+			message: `\`${name}\` 옵션 값이 필요합니다.`,
+			hint: TEST_USAGE_HINT
+		});
+		value = candidate;
+	} else value = token.slice(`${name}=`.length);
+	if (value.trim() === "" || value.startsWith("--")) fail(`\`${name}\` 옵션 값이 필요합니다.`);
+	return {
+		value,
+		index: next
+	};
+};
 function parseTestCommand(argv) {
 	const suitePath = argv[0] ?? "";
 	if (suitePath === "") fail("테스트 명세 JSON 경로가 필요합니다.");
@@ -3766,6 +3881,8 @@ function parseTestCommand(argv) {
 	let determinism = false;
 	let resetCmd;
 	let stderrLines;
+	let sessionPath;
+	let recordSessionPath;
 	const args = [];
 	for (let index = 1; index < argv.length; index += 1) {
 		const token = argv[index] ?? "";
@@ -3859,6 +3976,16 @@ function parseTestCommand(argv) {
 			const parsedLines = Number.parseInt(value, 10);
 			if (!Number.isSafeInteger(parsedLines)) fail("`--stderr-lines` 값은 0 이상의 정수여야 합니다.");
 			stderrLines = parsedLines;
+		} else if (token === "--session" || token.startsWith("--session=")) {
+			if (sessionPath !== void 0) fail("`--session`은 한 번만 사용할 수 있습니다.");
+			const read = readOptionValue(argv, token, "--session", index);
+			sessionPath = read.value;
+			index = read.index;
+		} else if (token === "--record-session" || token.startsWith("--record-session=")) {
+			if (recordSessionPath !== void 0) fail("`--record-session`은 한 번만 사용할 수 있습니다.");
+			const read = readOptionValue(argv, token, "--record-session", index);
+			recordSessionPath = read.value;
+			index = read.index;
 		} else if (token === "--json") {
 			if (json) fail("`--json`은 한 번만 사용할 수 있습니다.");
 			json = true;
@@ -3871,6 +3998,8 @@ function parseTestCommand(argv) {
 		message: "`--command` 옵션이 필요합니다.",
 		hint: TEST_USAGE_HINT
 	});
+	if (sessionPath !== void 0 && recordSessionPath !== void 0) fail("`--session`과 `--record-session`은 함께 쓸 수 없습니다. 재생과 녹화 중 하나만 고르세요.");
+	if (determinism && (sessionPath !== void 0 || recordSessionPath !== void 0)) fail("`--determinism`은 External 세션 옵션과 함께 쓸 수 없습니다.\n→ `--determinism`은 서버에 2회 연결하지만 External 세션은 연결 하나에 묶여 있습니다.\n→ 2회차가 같은 세션을 쓰면 반복 호출 순번이 어긋나고, 새 세션을 쓰면 비교 기준이 갈라집니다.");
 	return Object.freeze({
 		suitePath,
 		command,
@@ -3880,6 +4009,8 @@ function parseTestCommand(argv) {
 		repairBundlePath,
 		determinism,
 		resetCmd,
+		sessionPath,
+		recordSessionPath,
 		stderrLines: stderrLines ?? DEFAULT_STDERR_LINES
 	});
 }
@@ -3954,18 +4085,7 @@ function format(failure) {
 	for (const issue of failure.issues ?? []) result += `\n- [${escapeTerminalText(issue.code)}] ${escapeTerminalText(issue.path)}: ${escapeTerminalText(issue.message)}\n  해결: ${escapeTerminalText(issue.hint)}`;
 	return `${result}\n`;
 }
-/**
-* core 의 McpProcessDiagnostics 인지 구조로 확인한다. core 를 import 하지 않는다.
-* 하나라도 어긋나면 undefined 다. 설계 문서 §4.3.1.
-*/
-function processDiagnostics(value) {
-	if (typeof value !== "object" || value === null) return void 0;
-	if (!("stderr" in value) || typeof value.stderr !== "string") return void 0;
-	if (!("stderrTruncated" in value) || typeof value.stderrTruncated !== "boolean") return void 0;
-	if (!("exitCode" in value) || !(typeof value.exitCode === "number" || value.exitCode === null)) return void 0;
-	if (!("signal" in value) || !(typeof value.signal === "string" || value.signal === null)) return void 0;
-	return value;
-}
+/** AggregateError 내부까지 내려가 core 오류와 검증된 프로세스 진단을 꺼낸다. */
 function coreError(error) {
 	const seen = /* @__PURE__ */ new Set();
 	const visit = (value) => {
@@ -3989,7 +4109,7 @@ function writeFailure(dependencies, failure) {
 	dependencies.writeStderr(format(failure));
 	return 1;
 }
-async function runCli(argv, dependencies) {
+async function runCliCore(argv, dependencies, childEnv) {
 	if (argv.length === 0) return writeFailure(dependencies, {
 		code: "CLI_USAGE",
 		message: "실행할 CLI 명령이 없습니다.",
@@ -4003,7 +4123,7 @@ async function runCli(argv, dependencies) {
 		].includes(argv[0] ?? "")) return writeFailure(dependencies, {
 			code: "COMMAND_NOT_IMPLEMENTED",
 			message: `'${argv[0]}' 명령은 아직 구현되지 않았습니다.`,
-			hint: "현재는 test 명령만 사용할 수 있습니다."
+			hint: "사용 가능한 명령: test, generate, repair, replay, verify. 전체 도움말: mcpeak --help"
 		});
 		return writeFailure(dependencies, {
 			code: "CLI_USAGE",
@@ -4088,7 +4208,8 @@ async function runCli(argv, dependencies) {
 	try {
 		connection = await dependencies.connect({
 			command: input.command,
-			args: input.args
+			args: input.args,
+			...childEnv === void 0 ? {} : { env: childEnv }
 		});
 	} catch (error) {
 		const core = coreError(error);
@@ -4251,7 +4372,8 @@ async function runCli(argv, dependencies) {
 		try {
 			second = await dependencies.connect({
 				command: input.command,
-				args: input.args
+				args: input.args,
+				...childEnv === void 0 ? {} : { env: childEnv }
 			});
 		} catch (error) {
 			const core = coreError(error);
@@ -4489,6 +4611,133 @@ async function runCli(argv, dependencies) {
 	}
 	return allPassed ? 0 : 1;
 }
+/**
+* 재생 원본에서 찾지 못한 호출들을 그린다. `misses` 가 비어 있으면 빈 문자열이다.
+*
+* **MCP 오류 채널을 타지 않는다(#259).** `record` 의 `REPLAY_MISS` 진단은 실패한 툴 호출의
+* MCP 오류 메시지로도 나가는데, 그 채널은 `runner` 가 "테스트 대상 서버가 보낸 텍스트"로
+* 취급해 이스케이프(개행 포함)와 200자 절단을 건다 — 우리 자신이 여러 줄로 공들여 쓴 진단이
+* 서버 텍스트와 똑같이 망가진다. 이 함수는 `record` 가 `finish()` 요약에 구조화해 담아 준
+* 값을 CLI 가 직접 stderr 로 쓴다. `runner` 도 그 이스케이프 규칙도 거치지 않는다.
+*
+* `method`·`url`·`matchKeyPrefix` 는 값 자체는 `record` 가 만들지만 원본은 테스트 대상
+* 서버가 시도한 요청이라, 혹시 모를 제어 문자에 대비해 필드 단위로 이스케이프한다(줄 구조를
+* 만드는 정적 문구는 이스케이프 대상이 아니다 — `process-diagnostics.ts` 와 같은 원칙).
+*/
+function renderReplayMissDiagnostics(misses) {
+	if (misses.length === 0) return "";
+	const body = misses.map((miss) => `  ${escapeTerminalText(miss.method)} ${escapeTerminalText(miss.url)}\n  occurrence ${miss.occurrence} · matchKey ${escapeTerminalText(miss.matchKeyPrefix)}…\n`).join("");
+	return `\nExternal 진단: 재생 원본에서 찾지 못한 호출 ${misses.length}건\n` + body + "→ 이 호출이 녹화된 뒤에 추가되었거나, 요청이 녹화 때와 달라져 다른 matchKey가 되었습니다.\n→ 녹화를 다시 하거나, 요청이 실행마다 달라지는 값을 담고 있는지 확인하세요.\n";
+}
+/**
+* External 세션 요약을 사용자에게 보이는 한 문단으로 옮긴다. `undefined` 는 할 말이 없다는 뜻이다.
+*
+* **순서가 곧 계약이다**(ADR-0057). `consumedCount === 0` 과 `unusedCount > 0` 은 동시에 참일 수
+* 있어서, 조건을 각각 독립적으로 세우면 한 실행에 경고가 두 번 찍힌다. 아래 순서로 먼저 걸리는
+* 하나만 낸다.
+*
+* 갈래를 넷으로 나눈 이유는 **사용자가 다음에 볼 곳이 다르기 때문이다.** 원본이 비어 있는 것
+* (녹화 단계가 아무것도 못 잡았다)과 원본은 찼는데 하나도 안 쓴 것(세션 파일을 잘못 짚었거나
+* 서버의 호출 방식이 바뀌었다)은 같은 `consumedCount === 0` 이지만 원인이 정반대 방향에 있다.
+* 하나로 합치면 [#258](https://github.com/2026-Engineering-Contest/MCPeak/issues/258) 의 실제
+* 경로에서 "녹화된 호출이 재생되지 않았다" 고 말하게 되는데, 그 문장은 녹화가 있었다는 전제를
+* 깔아 사용자를 재생 쪽으로 보낸다. 정작 볼 곳은 그 앞 단계다.
+*
+* 판정만 하고 쓰기는 하지 않는다 — 순수 함수라 배타성 자체를 프로세스 없이 고정할 수 있다.
+*/
+function externalSessionNotice(summary) {
+	if (summary.mode === "record") {
+		if (summary.interactionCount > 0) return void 0;
+		return "\n알림: 이 실행에서 외부 호출이 하나도 녹화되지 않았습니다.\n→ 서버가 외부 API를 호출했다면 지원 범위를 벗어났는지 확인하세요.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	}
+	if (summary.interactionCount === 0) return "\n알림: 이 세션에는 녹화된 외부 호출이 0건입니다. 재생할 것이 없었습니다.\n→ 녹화 실행이 외부 호출을 하나도 잡지 못했다는 뜻입니다. 이 세션은 아무 호출도 막지 못합니다.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	if (summary.consumedCount === 0) return "\n알림: 이 실행에서 녹화된 외부 호출이 하나도 재생되지 않았습니다.\n→ 지원 범위 밖의 호출은 실제 네트워크로 나갔을 수 있습니다.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	if (summary.unusedCount > 0) return `\n알림: 녹화된 외부 호출 ${summary.interactionCount}건 중 ${summary.unusedCount}건이 이번 실행에서 재생되지 않았습니다.\n→ 서버 코드나 실행 경로가 녹화 때와 달라졌을 수 있습니다.
+→ MCPeak은 서버가 \`globalThis.fetch\`로 부른 것만 잡습니다.
+`;
+}
+/**
+* `test` 실행에 External Record/Replay 수명주기를 씌운다.
+*
+* Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+* 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+* 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+*
+* 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+*/
+async function runCli(argv, dependencies) {
+	const mode = externalModeOf(argv);
+	if (mode === void 0) return runCliCore(argv, dependencies);
+	let wiring;
+	try {
+		wiring = await startExternalWiring({
+			mode: mode.mode,
+			sessionPath: mode.path,
+			existingNodeOptions: process.env.NODE_OPTIONS
+		});
+	} catch (error) {
+		return writeFailure(dependencies, {
+			code: "EXTERNAL_SESSION_FAILED",
+			message: "External 세션을 열지 못했습니다.",
+			hint: `${error instanceof Error ? error.message : String(error)}\n→ 세션 파일 경로의 디렉터리가 있는지와 쓰기 권한을 확인하세요.`
+		});
+	}
+	let exitCode;
+	try {
+		exitCode = await runCliCore(argv, dependencies, wiring.env);
+	} catch (error) {
+		await wiring.finish("failed").catch(() => void 0);
+		throw error;
+	}
+	try {
+		const summary = await wiring.finish(exitCode === 0 ? "completed" : "failed");
+		if (summary.mode === "replay") {
+			const missBlock = renderReplayMissDiagnostics(summary.misses);
+			if (missBlock !== "") dependencies.writeStderr(missBlock);
+		}
+		const notice = externalSessionNotice(summary);
+		if (notice !== void 0) dependencies.writeStderr(notice);
+	} catch (error) {
+		return writeFailure(dependencies, {
+			code: "EXTERNAL_SESSION_FAILED",
+			message: "External 세션을 닫지 못했습니다.",
+			hint: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return exitCode;
+}
+/**
+* argv 에서 External 모드를 정한다. **파싱은 `parseTestCommand` 하나만 한다.**
+*
+* 한때 여기서 argv 를 따로 훑었다. 그러면 토큰 소비 규칙이 두 벌이 되고, 두 벌은 갈라진다.
+* 실제로 갈렸다 — `--arg` 는 하이픈으로 시작하는 값을 의도적으로 받으므로
+*
+*     mcpeak test s.json --command node --arg --session=/tmp/x
+*
+* 에서 `parseTestCommand` 는 그 토큰을 **서버 인자**로 소비하는데, 따로 훑는 쪽은 같은 것을
+* replay 지시로 읽었다. 사용자가 요청한 적 없는 세션 파일이 열리고 Bootstrap 이 주입되며,
+* Replay 라 서버의 외부 호출이 전부 실패한다. 원인을 짐작할 방법이 없는 실패다.
+*
+* 파싱 오류는 여기서 삼킨다. 배선은 파싱보다 먼저 서지만 **오류 보고는 기존 경로의 몫**이다.
+* 여기서 던지면 `--session` 이 붙었다는 이유만으로 오류 문구가 달라진다.
+*/
+function externalModeOf(argv) {
+	if (argv[0] !== "test") return void 0;
+	let input;
+	try {
+		input = parseTestCommand(argv.slice(1));
+	} catch {
+		return;
+	}
+	if (input.recordSessionPath !== void 0) return {
+		mode: "record",
+		path: input.recordSessionPath
+	};
+	if (input.sessionPath !== void 0) return {
+		mode: "replay",
+		path: input.sessionPath
+	};
+}
 //#endregion
 Object.defineProperty(exports, "GLOBAL_HELP", {
 	enumerable: true,

package/dist/{test-command-CsJfojut.mjs → test-command-CtQbeyhy.mjs}

@@ -6,7 +6,7 @@ import { REDACTED as REDACTED$1, cassetteClient, loadCassette, matchKey, saveCas
 import { spawn } from "node:child_process";
 import { CommandParseError, tokenizeCommand } from "@mcpeak/core";
 //#region package.json
-var version = "0.9.0";
+var version = "0.10.0";
 //#endregion
 //#region src/cassette-wiring.ts
 /**
@@ -320,7 +320,7 @@ const FINDING_GROUP = {
 };
 //#endregion
 //#region src/help.ts
-const TEST_USAGE = "사용법: mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--determinism] [--reset-cmd <command>] [--json] [--junit <path>] [--repair-bundle <path>] [--stderr-lines <N>]";
+const TEST_USAGE = "사용법: mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--determinism] [--reset-cmd <command>] [--json] [--junit <path>] [--repair-bundle <path>] [--stderr-lines <N>] [--session <path> | --record-session <path>]";
 /**
 * 시험 실행 옵션 설명. `--determinism` 은 툴을 2회 호출하므로 부작용이 있는 서버에서 모르고
 * 쓰면 사고가 난다. 그 경고가 사용법 한 줄에는 들어가지 않는다.
@@ -331,7 +331,31 @@ const TEST_OPTIONS = `옵션:
                         --reset-cmd 와 함께 쓰면 결정론성 확인이 되고, 없으면
                         "2회 결과가 같았다" 까지만 확인합니다
   --reset-cmd <command> 각 시험 실행 전에 이 명령을 한 번 실행합니다. 셸을 거치지
-                        않으므로 파이프나 && 는 쓸 수 없습니다`;
+                        않으므로 파이프나 && 는 쓸 수 없습니다
+  --record-session <path>
+                        서버가 \`globalThis.fetch\` 로 밖에 부른 HTTP 호출만 녹화합니다.
+                        서버는 실제로 실행됩니다. \`node:http\`·\`node:https\` 같은 범위 밖 호출은
+                        잡히지 않아 실제 네트워크로 나갈 수 있습니다
+  --session <path>      녹화한 외부 호출을 재생합니다. 서버는 실제로 실행되지만 외부
+                        API 호출은 \`globalThis.fetch\` 범위 안에서만 가로챕니다.
+                        범위 밖 호출은 실제 네트워크로 나갈 수 있으며, 범위 밖 호출이
+                        의심되는 경우 종료 때 알립니다
+
+두 세션 옵션은 서로, 그리고 \`--determinism\` 과 함께 쓸 수 없습니다. \`--determinism\` 은 서버에
+2회 연결하는데 세션은 연결 하나에 묶여 있어, 2회차가 같은 세션을 쓰면 반복 호출 순번이
+어긋나고 새 세션을 쓰면 비교 기준이 갈라집니다.
+
+세션은 \`--cassette\` 카세트와 다릅니다. **카세트는 우리가 서버에게 물어본 결과**를 남기고,
+**세션은 그 서버가 밖에 물어본 결과**를 남깁니다. 둘은 섞이지 않으며 파일도 따로입니다.
+
+세션 파일에는 외부 API 응답이 저장되므로 .gitignore 를 확인하세요. \`token\`·\`apiKey\` 같은
+이름의 값은 저장 전에 가려집니다.
+
+런타임에 따라 세션 옵션을 쓴 실행에서 \`ExperimentalWarning: SQLite is an experimental
+feature\` 가 stderr 에 한 줄 찍힙니다(실측: Node 22.18.0 에서 나오고 24.16.0 에서는 안 납니다).
+\`node:sqlite\` 를 처음 로드할 때 한 번 나오므로 실행당 한 줄이며, 세션 옵션이 없는 실행에는
+붙지 않습니다. Node 가 그 모듈을 아직 실험적으로 표시한다는 뜻이고, **저장된 녹화는 표준
+SQLite 파일이라 영향받지 않습니다.**`;
 const GENERATE_USAGE = "사용법: mcpeak generate --suite-id <id> --name <name> --out <suite.json> --command <executable> [--arg <value> ...] [--baseline-only] [--provider <codex|claude>] [--model <model>] [--no-dry-run] [--cassette <path>] [--record] [--reset-cmd <command>] [--no-repair] [--force]";
 /**
 * 시험 실행 옵션 설명. 사용법 한 줄로는 `--cassette` 가 무엇을 파일로 남기는지, `--reset-cmd`
@@ -403,7 +427,7 @@ auto 모드(\`--record\` 없는 실행)는 카세트에 있는 요청이면 서
 마스킹해 비교하므로, 비밀값 자체만 바뀐 경우는 감지되지 않습니다.
 
 불일치나 호출 실패가 하나라도 있으면 종료 코드 1 입니다. 확인불가는 실패로 보지 않습니다.`;
-const GLOBAL_HELP = `OhMyMCP — MCP 서버 테스트 프레임워크
+const GLOBAL_HELP = `MCPeak — MCP 서버 테스트 프레임워크
 
 사용법: mcpeak <명령> [옵션]
         mcpeak help [명령]
@@ -833,6 +857,18 @@ function dropSkippedTools(suite, skips) {
 }
 //#endregion
 //#region src/process-diagnostics.ts
+/**
+* core 의 stdio 프로세스 진단인지 구조와 값의 범위로 확인한다.
+* 일부 필드만 있거나 프로세스 상태로 표현할 수 없는 값은 렌더하지 않는다.
+*/
+function processDiagnostics(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	if (!("stderr" in value) || typeof value.stderr !== "string") return void 0;
+	if (!("stderrTruncated" in value) || typeof value.stderrTruncated !== "boolean") return void 0;
+	if (!("exitCode" in value) || !(value.exitCode === null || typeof value.exitCode === "number" && Number.isInteger(value.exitCode))) return void 0;
+	if (!("signal" in value) || !(value.signal === null || typeof value.signal === "string" && value.signal.length > 0)) return void 0;
+	return value;
+}
 /** TAB. 이 모듈만 이스케이프 대상에서 빼는 문자다. 아래 escapeTokens 주석에 근거가 있다. */
 const TAB = 9;
 /**
@@ -2793,8 +2829,14 @@ async function runGenerateCommand(argv, deps) {
 		else if (error instanceof OutputReplaceError) outputReplaceFailure(deps, error.path, error.code);
 		else if (error instanceof LinkUnsupportedError) linkUnsupportedFailure(deps, error.path, error.code);
 		else if (deps.GenerateTestsError !== void 0 && error instanceof deps.GenerateTestsError) generateTestsFailure(deps, error);
-		else if (isCoreClientError(error)) deps.writeStderr(`오류 [GENERATE_CONNECT_FAILED/${error.code}]: ${error.message}\n해결: ${error.hint}\n`);
-		else deps.writeStderr("오류 [GENERATE_FAILED]: baseline suite를 생성하거나 저장하지 못했습니다.\n해결: MCP 서버와 출력 경로를 확인한 뒤 다시 실행하세요.\n");
+		else if (isCoreClientError(error)) {
+			deps.writeStderr(`오류 [GENERATE_CONNECT_FAILED/${error.code}]: ${error.message}\n해결: ${error.hint}\n`);
+			const diagnostics = processDiagnostics(error.diagnostics);
+			if (diagnostics !== void 0 && hasDiagnosticContent(diagnostics)) {
+				const block = renderProcessDiagnostics(diagnostics, { maxLines: DRY_RUN_STDERR_LINES });
+				if (block !== "") deps.writeStderr(`\n${block}`);
+			}
+		} else deps.writeStderr("오류 [GENERATE_FAILED]: baseline suite를 생성하거나 저장하지 못했습니다.\n해결: MCP 서버와 출력 경로를 확인한 뒤 다시 실행하세요.\n");
 		return 1;
 	}
 	try {
@@ -3689,6 +3731,51 @@ function createDeterminismCapture(inner) {
 	};
 }
 //#endregion
+//#region src/external-wiring.ts
+/**
+* `@mcpeak/record/external` 은 **세션 옵션을 실제로 쓸 때만** 불러온다.
+*
+* 정적 import 로 두면 `node:sqlite` 가 CLI 를 띄우는 것만으로 로드되고, Node 22.x 는 그때
+* `ExperimentalWarning: SQLite is an experimental feature` 를 stderr 에 찍는다. 세션을 쓰지도
+* 않은 `mcpeak test` 실행마다 그 줄이 붙는다 — 터미널 출력이 곧 UI 인 도구에서 그냥 손해다.
+* (실제로 `dist-cli-e2e` 의 "stderr 가 비어 있다" 단언이 이걸 잡았다.)
+*
+* 지연 로딩이면 경고를 보는 사람은 External 을 직접 켠 사용자뿐이다. 그 경고를 아예 지울지는
+* ADR-0054 가 남겨 둔 별도 결정이며, 라이브러리가 아니라 CLI 가 정할 몫이다.
+*/
+const loadExternal = () => import("@mcpeak/record/external");
+/** 세션 파일 하나가 세션 하나이므로 식별자를 사용자에게 묻지 않는다. */
+const SESSION_ID = "default";
+async function startExternalWiring(options) {
+	const { createSqliteSessionStore, startExternalCoordinator } = await loadExternal();
+	const store = createSqliteSessionStore({ path: options.sessionPath });
+	let handle;
+	try {
+		handle = options.mode === "record" ? await startExternalCoordinator({
+			mode: "record",
+			sessionId: SESSION_ID,
+			store,
+			...options.existingNodeOptions === void 0 ? {} : { existingNodeOptions: options.existingNodeOptions }
+		}) : await startExternalCoordinator({
+			mode: "replay",
+			sourceSessionId: SESSION_ID,
+			store,
+			...options.existingNodeOptions === void 0 ? {} : { existingNodeOptions: options.existingNodeOptions }
+		});
+	} catch (error) {
+		store.close();
+		throw error;
+	}
+	let settled;
+	return {
+		env: handle.childEnvironment,
+		finish(status) {
+			settled ??= handle.finish(status).finally(() => store.close());
+			return settled;
+		}
+	};
+}
+//#endregion
 //#region src/test-command.ts
 /** --stderr-lines 기본값. 설계 문서 §6. */
 const DEFAULT_STDERR_LINES = 20;
@@ -3737,6 +3824,10 @@ const dictionary = {
 		message: "초기화 명령이 실패했습니다.",
 		hint: "`--reset-cmd` 명령이 단독으로 성공하는지 확인한 뒤 다시 실행하세요."
 	},
+	EXTERNAL_SESSION_FAILED: {
+		message: "External 세션 처리에 실패했습니다.",
+		hint: "세션 파일 경로의 디렉터리가 있는지와 쓰기 권한을 확인하세요."
+	},
 	CLI_INTERNAL_ERROR: {
 		message: "예상하지 못한 CLI 내부 오류가 발생했습니다.",
 		hint: "다시 실행한 뒤 재현 정보와 함께 이슈를 보고하세요."
@@ -3756,6 +3847,30 @@ const fail = (message) => {
 		hint: TEST_USAGE_HINT
 	});
 };
+/**
+* `--name value` 와 `--name=value` 두 형태에서 값을 꺼낸다.
+*
+* 값이 `--` 로 시작하면 거절한다. `--session --json` 처럼 값을 빠뜨리면 다음 옵션이 경로로
+* 먹히고, 그러면 "그런 파일이 없습니다" 라는 엉뚱한 곳에서 실패한다.
+*/
+const readOptionValue = (argv, token, name, index) => {
+	let value;
+	let next = index;
+	if (token === name) {
+		const candidate = argv[++next];
+		if (candidate === void 0) throw new CliCommandError({
+			code: "CLI_USAGE",
+			message: `\`${name}\` 옵션 값이 필요합니다.`,
+			hint: TEST_USAGE_HINT
+		});
+		value = candidate;
+	} else value = token.slice(`${name}=`.length);
+	if (value.trim() === "" || value.startsWith("--")) fail(`\`${name}\` 옵션 값이 필요합니다.`);
+	return {
+		value,
+		index: next
+	};
+};
 function parseTestCommand(argv) {
 	const suitePath = argv[0] ?? "";
 	if (suitePath === "") fail("테스트 명세 JSON 경로가 필요합니다.");
@@ -3766,6 +3881,8 @@ function parseTestCommand(argv) {
 	let determinism = false;
 	let resetCmd;
 	let stderrLines;
+	let sessionPath;
+	let recordSessionPath;
 	const args = [];
 	for (let index = 1; index < argv.length; index += 1) {
 		const token = argv[index] ?? "";
@@ -3859,6 +3976,16 @@ function parseTestCommand(argv) {
 			const parsedLines = Number.parseInt(value, 10);
 			if (!Number.isSafeInteger(parsedLines)) fail("`--stderr-lines` 값은 0 이상의 정수여야 합니다.");
 			stderrLines = parsedLines;
+		} else if (token === "--session" || token.startsWith("--session=")) {
+			if (sessionPath !== void 0) fail("`--session`은 한 번만 사용할 수 있습니다.");
+			const read = readOptionValue(argv, token, "--session", index);
+			sessionPath = read.value;
+			index = read.index;
+		} else if (token === "--record-session" || token.startsWith("--record-session=")) {
+			if (recordSessionPath !== void 0) fail("`--record-session`은 한 번만 사용할 수 있습니다.");
+			const read = readOptionValue(argv, token, "--record-session", index);
+			recordSessionPath = read.value;
+			index = read.index;
 		} else if (token === "--json") {
 			if (json) fail("`--json`은 한 번만 사용할 수 있습니다.");
 			json = true;
@@ -3871,6 +3998,8 @@ function parseTestCommand(argv) {
 		message: "`--command` 옵션이 필요합니다.",
 		hint: TEST_USAGE_HINT
 	});
+	if (sessionPath !== void 0 && recordSessionPath !== void 0) fail("`--session`과 `--record-session`은 함께 쓸 수 없습니다. 재생과 녹화 중 하나만 고르세요.");
+	if (determinism && (sessionPath !== void 0 || recordSessionPath !== void 0)) fail("`--determinism`은 External 세션 옵션과 함께 쓸 수 없습니다.\n→ `--determinism`은 서버에 2회 연결하지만 External 세션은 연결 하나에 묶여 있습니다.\n→ 2회차가 같은 세션을 쓰면 반복 호출 순번이 어긋나고, 새 세션을 쓰면 비교 기준이 갈라집니다.");
 	return Object.freeze({
 		suitePath,
 		command,
@@ -3880,6 +4009,8 @@ function parseTestCommand(argv) {
 		repairBundlePath,
 		determinism,
 		resetCmd,
+		sessionPath,
+		recordSessionPath,
 		stderrLines: stderrLines ?? DEFAULT_STDERR_LINES
 	});
 }
@@ -3954,18 +4085,7 @@ function format(failure) {
 	for (const issue of failure.issues ?? []) result += `\n- [${escapeTerminalText(issue.code)}] ${escapeTerminalText(issue.path)}: ${escapeTerminalText(issue.message)}\n  해결: ${escapeTerminalText(issue.hint)}`;
 	return `${result}\n`;
 }
-/**
-* core 의 McpProcessDiagnostics 인지 구조로 확인한다. core 를 import 하지 않는다.
-* 하나라도 어긋나면 undefined 다. 설계 문서 §4.3.1.
-*/
-function processDiagnostics(value) {
-	if (typeof value !== "object" || value === null) return void 0;
-	if (!("stderr" in value) || typeof value.stderr !== "string") return void 0;
-	if (!("stderrTruncated" in value) || typeof value.stderrTruncated !== "boolean") return void 0;
-	if (!("exitCode" in value) || !(typeof value.exitCode === "number" || value.exitCode === null)) return void 0;
-	if (!("signal" in value) || !(typeof value.signal === "string" || value.signal === null)) return void 0;
-	return value;
-}
+/** AggregateError 내부까지 내려가 core 오류와 검증된 프로세스 진단을 꺼낸다. */
 function coreError(error) {
 	const seen = /* @__PURE__ */ new Set();
 	const visit = (value) => {
@@ -3989,7 +4109,7 @@ function writeFailure(dependencies, failure) {
 	dependencies.writeStderr(format(failure));
 	return 1;
 }
-async function runCli(argv, dependencies) {
+async function runCliCore(argv, dependencies, childEnv) {
 	if (argv.length === 0) return writeFailure(dependencies, {
 		code: "CLI_USAGE",
 		message: "실행할 CLI 명령이 없습니다.",
@@ -4003,7 +4123,7 @@ async function runCli(argv, dependencies) {
 		].includes(argv[0] ?? "")) return writeFailure(dependencies, {
 			code: "COMMAND_NOT_IMPLEMENTED",
 			message: `'${argv[0]}' 명령은 아직 구현되지 않았습니다.`,
-			hint: "현재는 test 명령만 사용할 수 있습니다."
+			hint: "사용 가능한 명령: test, generate, repair, replay, verify. 전체 도움말: mcpeak --help"
 		});
 		return writeFailure(dependencies, {
 			code: "CLI_USAGE",
@@ -4088,7 +4208,8 @@ async function runCli(argv, dependencies) {
 	try {
 		connection = await dependencies.connect({
 			command: input.command,
-			args: input.args
+			args: input.args,
+			...childEnv === void 0 ? {} : { env: childEnv }
 		});
 	} catch (error) {
 		const core = coreError(error);
@@ -4251,7 +4372,8 @@ async function runCli(argv, dependencies) {
 		try {
 			second = await dependencies.connect({
 				command: input.command,
-				args: input.args
+				args: input.args,
+				...childEnv === void 0 ? {} : { env: childEnv }
 			});
 		} catch (error) {
 			const core = coreError(error);
@@ -4489,5 +4611,132 @@ async function runCli(argv, dependencies) {
 	}
 	return allPassed ? 0 : 1;
 }
+/**
+* 재생 원본에서 찾지 못한 호출들을 그린다. `misses` 가 비어 있으면 빈 문자열이다.
+*
+* **MCP 오류 채널을 타지 않는다(#259).** `record` 의 `REPLAY_MISS` 진단은 실패한 툴 호출의
+* MCP 오류 메시지로도 나가는데, 그 채널은 `runner` 가 "테스트 대상 서버가 보낸 텍스트"로
+* 취급해 이스케이프(개행 포함)와 200자 절단을 건다 — 우리 자신이 여러 줄로 공들여 쓴 진단이
+* 서버 텍스트와 똑같이 망가진다. 이 함수는 `record` 가 `finish()` 요약에 구조화해 담아 준
+* 값을 CLI 가 직접 stderr 로 쓴다. `runner` 도 그 이스케이프 규칙도 거치지 않는다.
+*
+* `method`·`url`·`matchKeyPrefix` 는 값 자체는 `record` 가 만들지만 원본은 테스트 대상
+* 서버가 시도한 요청이라, 혹시 모를 제어 문자에 대비해 필드 단위로 이스케이프한다(줄 구조를
+* 만드는 정적 문구는 이스케이프 대상이 아니다 — `process-diagnostics.ts` 와 같은 원칙).
+*/
+function renderReplayMissDiagnostics(misses) {
+	if (misses.length === 0) return "";
+	const body = misses.map((miss) => `  ${escapeTerminalText(miss.method)} ${escapeTerminalText(miss.url)}\n  occurrence ${miss.occurrence} · matchKey ${escapeTerminalText(miss.matchKeyPrefix)}…\n`).join("");
+	return `\nExternal 진단: 재생 원본에서 찾지 못한 호출 ${misses.length}건\n` + body + "→ 이 호출이 녹화된 뒤에 추가되었거나, 요청이 녹화 때와 달라져 다른 matchKey가 되었습니다.\n→ 녹화를 다시 하거나, 요청이 실행마다 달라지는 값을 담고 있는지 확인하세요.\n";
+}
+/**
+* External 세션 요약을 사용자에게 보이는 한 문단으로 옮긴다. `undefined` 는 할 말이 없다는 뜻이다.
+*
+* **순서가 곧 계약이다**(ADR-0057). `consumedCount === 0` 과 `unusedCount > 0` 은 동시에 참일 수
+* 있어서, 조건을 각각 독립적으로 세우면 한 실행에 경고가 두 번 찍힌다. 아래 순서로 먼저 걸리는
+* 하나만 낸다.
+*
+* 갈래를 넷으로 나눈 이유는 **사용자가 다음에 볼 곳이 다르기 때문이다.** 원본이 비어 있는 것
+* (녹화 단계가 아무것도 못 잡았다)과 원본은 찼는데 하나도 안 쓴 것(세션 파일을 잘못 짚었거나
+* 서버의 호출 방식이 바뀌었다)은 같은 `consumedCount === 0` 이지만 원인이 정반대 방향에 있다.
+* 하나로 합치면 [#258](https://github.com/2026-Engineering-Contest/MCPeak/issues/258) 의 실제
+* 경로에서 "녹화된 호출이 재생되지 않았다" 고 말하게 되는데, 그 문장은 녹화가 있었다는 전제를
+* 깔아 사용자를 재생 쪽으로 보낸다. 정작 볼 곳은 그 앞 단계다.
+*
+* 판정만 하고 쓰기는 하지 않는다 — 순수 함수라 배타성 자체를 프로세스 없이 고정할 수 있다.
+*/
+function externalSessionNotice(summary) {
+	if (summary.mode === "record") {
+		if (summary.interactionCount > 0) return void 0;
+		return "\n알림: 이 실행에서 외부 호출이 하나도 녹화되지 않았습니다.\n→ 서버가 외부 API를 호출했다면 지원 범위를 벗어났는지 확인하세요.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	}
+	if (summary.interactionCount === 0) return "\n알림: 이 세션에는 녹화된 외부 호출이 0건입니다. 재생할 것이 없었습니다.\n→ 녹화 실행이 외부 호출을 하나도 잡지 못했다는 뜻입니다. 이 세션은 아무 호출도 막지 못합니다.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	if (summary.consumedCount === 0) return "\n알림: 이 실행에서 녹화된 외부 호출이 하나도 재생되지 않았습니다.\n→ 지원 범위 밖의 호출은 실제 네트워크로 나갔을 수 있습니다.\n→ MCPeak은 서버가 `globalThis.fetch`로 부른 것만 잡습니다.\n";
+	if (summary.unusedCount > 0) return `\n알림: 녹화된 외부 호출 ${summary.interactionCount}건 중 ${summary.unusedCount}건이 이번 실행에서 재생되지 않았습니다.\n→ 서버 코드나 실행 경로가 녹화 때와 달라졌을 수 있습니다.
+→ MCPeak은 서버가 \`globalThis.fetch\`로 부른 것만 잡습니다.
+`;
+}
+/**
+* `test` 실행에 External Record/Replay 수명주기를 씌운다.
+*
+* Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+* 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+* 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+*
+* 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+*/
+async function runCli(argv, dependencies) {
+	const mode = externalModeOf(argv);
+	if (mode === void 0) return runCliCore(argv, dependencies);
+	let wiring;
+	try {
+		wiring = await startExternalWiring({
+			mode: mode.mode,
+			sessionPath: mode.path,
+			existingNodeOptions: process.env.NODE_OPTIONS
+		});
+	} catch (error) {
+		return writeFailure(dependencies, {
+			code: "EXTERNAL_SESSION_FAILED",
+			message: "External 세션을 열지 못했습니다.",
+			hint: `${error instanceof Error ? error.message : String(error)}\n→ 세션 파일 경로의 디렉터리가 있는지와 쓰기 권한을 확인하세요.`
+		});
+	}
+	let exitCode;
+	try {
+		exitCode = await runCliCore(argv, dependencies, wiring.env);
+	} catch (error) {
+		await wiring.finish("failed").catch(() => void 0);
+		throw error;
+	}
+	try {
+		const summary = await wiring.finish(exitCode === 0 ? "completed" : "failed");
+		if (summary.mode === "replay") {
+			const missBlock = renderReplayMissDiagnostics(summary.misses);
+			if (missBlock !== "") dependencies.writeStderr(missBlock);
+		}
+		const notice = externalSessionNotice(summary);
+		if (notice !== void 0) dependencies.writeStderr(notice);
+	} catch (error) {
+		return writeFailure(dependencies, {
+			code: "EXTERNAL_SESSION_FAILED",
+			message: "External 세션을 닫지 못했습니다.",
+			hint: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return exitCode;
+}
+/**
+* argv 에서 External 모드를 정한다. **파싱은 `parseTestCommand` 하나만 한다.**
+*
+* 한때 여기서 argv 를 따로 훑었다. 그러면 토큰 소비 규칙이 두 벌이 되고, 두 벌은 갈라진다.
+* 실제로 갈렸다 — `--arg` 는 하이픈으로 시작하는 값을 의도적으로 받으므로
+*
+*     mcpeak test s.json --command node --arg --session=/tmp/x
+*
+* 에서 `parseTestCommand` 는 그 토큰을 **서버 인자**로 소비하는데, 따로 훑는 쪽은 같은 것을
+* replay 지시로 읽었다. 사용자가 요청한 적 없는 세션 파일이 열리고 Bootstrap 이 주입되며,
+* Replay 라 서버의 외부 호출이 전부 실패한다. 원인을 짐작할 방법이 없는 실패다.
+*
+* 파싱 오류는 여기서 삼킨다. 배선은 파싱보다 먼저 서지만 **오류 보고는 기존 경로의 몫**이다.
+* 여기서 던지면 `--session` 이 붙었다는 이유만으로 오류 문구가 달라진다.
+*/
+function externalModeOf(argv) {
+	if (argv[0] !== "test") return void 0;
+	let input;
+	try {
+		input = parseTestCommand(argv.slice(1));
+	} catch {
+		return;
+	}
+	if (input.recordSessionPath !== void 0) return {
+		mode: "record",
+		path: input.recordSessionPath
+	};
+	if (input.sessionPath !== void 0) return {
+		mode: "replay",
+		path: input.sessionPath
+	};
+}
 //#endregion
 export { runReplayCommand as a, nodeGenerateDependencies as c, GLOBAL_HELP as d, VERIFY_USAGE_HINT as f, parseReplayCommand as i, nodeReviewIO as l, version as m, runCli as n, parseRepairCommand as o, commandHelp as p, ReplayRuntimeUnavailableError as r, runRepairCommand as s, parseTestCommand as t, runGenerateCommand as u };

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@mcpeak/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
-  "description": "OhMyMCP 프레임워크의 CLI 진입점 (얇게 유지)",
+  "description": "MCPeak 프레임워크의 CLI 진입점 (얇게 유지)",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/2026-Engineering-Contest/OhMyMCP.git",
+    "url": "git+https://github.com/2026-Engineering-Contest/MCPeak.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/2026-Engineering-Contest/OhMyMCP#readme",
-  "bugs": "https://github.com/2026-Engineering-Contest/OhMyMCP/issues",
+  "homepage": "https://github.com/2026-Engineering-Contest/MCPeak#readme",
+  "bugs": "https://github.com/2026-Engineering-Contest/MCPeak/issues",
   "publishConfig": {
     "access": "public"
   },
@@ -47,11 +50,11 @@
     "dist"
   ],
   "dependencies": {
-    "@mcpeak/core": "0.3.0",
-    "@mcpeak/runner": "0.8.0",
-    "@mcpeak/generate": "0.5.1",
-    "@mcpeak/record": "0.2.0",
-    "@mcpeak/mock": "0.3.0"
+    "@mcpeak/core": "0.4.0",
+    "@mcpeak/runner": "0.9.0",
+    "@mcpeak/generate": "0.6.0",
+    "@mcpeak/record": "0.3.0",
+    "@mcpeak/mock": "0.4.0"
   },
   "scripts": {
     "build": "tsdown --config-loader native",