phasegate 0.254.0 → 0.283.0

package/scripts/harness/main.ts

@@ -22,6 +22,9 @@
  * @work-item-id WI-217
  * @work-item-id WI-219
  * @work-item-id WI-291
+ * @work-item-id WI-300
+ * @work-item-id WI-306
+ * @work-item-id WI-308
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -45,6 +48,7 @@ import { createBiomeAstEngineModule } from "./biome-ast-engine/composition-root.
 import { buildCiGovernance } from "./ci-governance/composition-root.js";
 import { toPhaseConfigSection } from "./config-foundation/application/mappers/phase-config-section-mapper.js";
 import { toValidatorSystemConfig } from "./config-foundation/application/mappers/validator-system-config-mapper.js";
+import { toWorldModelConfig } from "./config-foundation/application/mappers/world-model-config-mapper.js";
 import { createConfigFoundationModule } from "./config-foundation/composition-root.js";
 import { ConfigValidationError } from "./config-foundation/domain/errors/config-validation-error.js";
 import type { HarnessConfigV2 } from "./config-foundation/domain/harness-config.js";
@@ -690,8 +694,8 @@ Options:
   --agent <claude|codex|both>     Agent context and hook targets (default: both)
   --skills <core|all>             Rendered agent context skill mode (default: all)
   --workflow <standard|strict>    Rendered agent context workflow mode (default: standard)
-  --with-husky                    Include Husky hook targets
-  --with-ci                       Include GitHub Actions target
+  --with-husky                    Include Husky hook targets (opt-in; omitted by default)
+  --with-ci                       Include GitHub Actions target (opt-in; omitted by default)
   --personal                      Use local-only install: no package.json, agent docs, Husky, CI, .gitignore, GitHub CLI, secrets, or CI setting writes.
                                   With --agent claude, initializes .phasegate-local config/settings/skills and ignored .claude shims.
   --json                          Output machine-readable JSON
@@ -1851,7 +1855,18 @@ function emitV2SchemaWarningOnce(sourcePath: string): void {
   );
 }
 
-async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
+/**
+ * 不正 config でも fail-open（警告 + 既定設定で続行）にするコマンド。
+ * GitHub #40: config 検証の fail-closed が dispatch より上流にあると、pre-tool-use hook
+ * 経由で Write/Edit/Bash が全遮断され、config 自身を修復する経路が消える（自己修復
+ * デッドロック）。hook（エージェントのツール遮断点）と doctor（自己診断）は復旧経路
+ * として常に起動可能でなければならない。validate / ci-check 等の検査系コマンドは
+ * fail-closed を維持する（gated スコープへの書き込みは hook 内の phase-gate 判定が
+ * 引き続き fail-closed でブロックする）。
+ */
+const CONFIG_FAIL_OPEN_COMMANDS: ReadonlySet<string> = new Set(["hook", "doctor"]);
+
+async function loadResolvedConfig(command?: string): Promise<HarnessConfigV2 | undefined> {
   try {
     const configModule = createConfigFoundationModule();
     const result = await configModule.usecases.loadResolvedConfigUseCase.execute();
@@ -1862,6 +1877,15 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
   } catch (error) {
     if (error instanceof ConfigValidationError) {
       process.stderr.write(`Invalid phasegate.config.json: ${error.message}\n`);
+      if (command !== undefined && CONFIG_FAIL_OPEN_COMMANDS.has(command)) {
+        process.stderr.write(
+          "Warning: continuing with default settings so diagnosis and self-repair stay possible. Fix the reported path in phasegate.config.json to restore full gating.\n",
+        );
+        return undefined;
+      }
+      process.stderr.write(
+        "Recovery: fix the reported path/type in phasegate.config.json (or restore it from version control). `phasegate doctor` and agent hooks remain available while the config is invalid.\n",
+      );
       process.exit(2);
     }
     if (error instanceof ConfigNotFoundError) {
@@ -1881,24 +1905,41 @@ async function loadWorldResolvedConfig() {
   try {
     const configModule = createConfigFoundationModule();
     const result = await configModule.usecases.loadResolvedConfigUseCase.execute();
-    return {
-      designDocsRoot: result.config.paths.designDocs,
-      inceptionRoot: result.config.paths.inceptionDocs,
-      requirementMatrixPath: result.config.layers.L3.requirementMatrixPath,
-    };
+    return toWorldModelConfig(result.config);
   } catch (error) {
     if (error instanceof ConfigNotFoundError) return undefined;
     throw error;
   }
 }
 
+/**
+ * WI-308: pipe接続されたstdout / stderrのpending writeを完了してから終了状態へ移る。
+ * `process.exit()`はNodeのstream queueを待たないため、64 KiB超のJSONを切断し得る。
+ */
+async function finishCliExit(exitCode: number): Promise<void> {
+  const drain = (stream: NodeJS.WriteStream): Promise<void> =>
+    new Promise((resolvePromise, reject) => {
+      stream.write("", (error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolvePromise();
+      });
+    });
+
+  await Promise.all([drain(process.stdout), drain(process.stderr)]);
+  process.exitCode = exitCode;
+}
+
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const command = args[0];
 
   if (!command || command === "--help" || command === "help") {
     printUsage();
-    process.exit(0);
+    await finishCliExit(0);
+    return;
   }
 
   const rootDir = getProjectRoot();
@@ -1907,19 +1948,21 @@ async function main(): Promise<void> {
   if (command === "--version" || command === "version") {
     const version = await getHarnessVersion(harnessRoot);
     console.log(`phasegate v${version}`);
-    process.exit(0);
+    await finishCliExit(0);
+    return;
   }
 
   // Pre-dispatch: 全 subcommand で --help / -h を最優先で解釈し usage 出力 (副作用走行を防ぐ — WI-091 finding #3)
   if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
     printSubcommandHelp(command);
-    process.exit(0);
+    await finishCliExit(0);
+    return;
   }
 
   const json = hasFlag(args, "--json");
 
   // Cross-unit wiring: 設定を先に解決し、各Unit に注入する
-  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig();
+  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig(command);
 
   try {
     switch (command) {
@@ -2188,8 +2231,8 @@ async function main(): Promise<void> {
           console.log("  • Q&A about phasegate concepts: invoke /phasegate-toolkit-guide");
           console.log("  • Diagnose & tune phasegate.config.json: invoke /phasegate-config-doctor");
         }
-        process.exit(hasStructuredInstallError(installResult) ? 1 : 0);
-        break;
+        await finishCliExit(hasStructuredInstallError(installResult) ? 1 : 0);
+        return;
       }
 
       case "update-skills": {
@@ -2214,8 +2257,8 @@ async function main(): Promise<void> {
         });
         if (!json) console.log("phasegate update-skills is deprecated; running phasegate reconcile.");
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "doctor": {
@@ -2241,14 +2284,14 @@ async function main(): Promise<void> {
           agent,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "emit-agent-rules": {
         console.log(emitAgentRulesBlock());
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       case "scaffold-wi": {
@@ -2274,8 +2317,8 @@ async function main(): Promise<void> {
           inceptionRoot: parseFlag(args, "--root") ?? configuredPersonalRoot,
         });
         console.log(`Created ${descriptionPath}`);
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       case "install": {
@@ -2323,8 +2366,8 @@ async function main(): Promise<void> {
           force: hasFlag(args, "--force"),
           includeClaude,
           includeCodex,
-          includeHusky: !personal,
-          includeCi: !personal,
+          includeHusky: !personal && hasFlag(args, "--with-husky"),
+          includeCi: !personal && hasFlag(args, "--with-ci"),
           skillSet: skillSetRaw,
           workflow: parseWorkflowMode(workflowRaw),
           agent,
@@ -2332,8 +2375,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "setup:agent": {
@@ -2415,8 +2458,8 @@ async function main(): Promise<void> {
           console.log("Validation:");
           for (const command of plan.validation) console.log(`- ${command}`);
         }
-        process.exit(hasStructuredInstallError(installResult) ? 1 : 0);
-        break;
+        await finishCliExit(hasStructuredInstallError(installResult) ? 1 : 0);
+        return;
       }
 
       case "config:plan": {
@@ -2446,7 +2489,8 @@ async function main(): Promise<void> {
               for (const operation of applyResult.appliedOperations)
                 console.log(`- ${operation.op} ${operation.pointer}`);
             }
-            process.exit(0);
+            await finishCliExit(0);
+            return;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             if (json) {
@@ -2460,7 +2504,8 @@ async function main(): Promise<void> {
             } else {
               console.error(`Error: ${message}`);
             }
-            process.exit(1);
+            await finishCliExit(1);
+            return;
           }
         }
         if (json) {
@@ -2474,8 +2519,8 @@ async function main(): Promise<void> {
           console.log("Validation:");
           for (const validation of plan.validations) console.log(`- ${validation}`);
         }
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       case "session": {
@@ -2496,7 +2541,8 @@ async function main(): Promise<void> {
                 `Full Mode session started: ${session.workItemId} unit=${session.unit} expiresAt=${session.expiresAt}`,
               );
             }
-            process.exit(0);
+            await finishCliExit(0);
+            return;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             if (json) {
@@ -2504,7 +2550,8 @@ async function main(): Promise<void> {
             } else {
               console.error(`Error: ${message}`);
             }
-            process.exit(2);
+            await finishCliExit(2);
+            return;
           }
         }
         if (subcommand === "end") {
@@ -2517,7 +2564,8 @@ async function main(): Promise<void> {
             } else {
               console.log("No Full Mode session was active.");
             }
-            process.exit(0);
+            await finishCliExit(0);
+            return;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             if (json) {
@@ -2525,7 +2573,8 @@ async function main(): Promise<void> {
             } else {
               console.error(`Error: ${message}`);
             }
-            process.exit(2);
+            await finishCliExit(2);
+            return;
           }
         }
         console.error("Error: session subcommand must be begin or end.");
@@ -2552,8 +2601,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "reconcile": {
@@ -2577,8 +2626,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── config-foundation ──
@@ -2593,8 +2642,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "disable-feature": {
@@ -2608,8 +2657,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "list-features": {
@@ -2618,8 +2667,8 @@ async function main(): Promise<void> {
           list: true,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "migrate": {
@@ -2631,8 +2680,8 @@ async function main(): Promise<void> {
             json,
           });
           console.log(result.text);
-          process.exit(result.exitCode);
-          break;
+          await finishCliExit(result.exitCode);
+          return;
         }
         const mod = createConfigFoundationModule();
         const targetVersion = parseFlag(args, "--schema") ?? "v3";
@@ -2642,8 +2691,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── harness-error ──
@@ -2657,8 +2706,8 @@ async function main(): Promise<void> {
           failOnError,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "validate-fix": {
@@ -2672,8 +2721,8 @@ async function main(): Promise<void> {
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "list-errors": {
@@ -2685,8 +2734,8 @@ async function main(): Promise<void> {
           layer,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── traceability-model ──
@@ -2698,8 +2747,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "work-items:status": {
@@ -2714,8 +2763,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── world-model ──
@@ -2791,8 +2840,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── adr-foundation ──
@@ -2807,8 +2856,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "validate-adr": {
@@ -2821,8 +2870,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── biome-ast-engine ──
@@ -2832,8 +2881,8 @@ async function main(): Promise<void> {
         const mod = createBiomeAstEngineModule(rootDir, { l1Config, architecture });
         const result = await mod.harnessLintCommandHandler.execute(args.slice(1));
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── validator-system ──
@@ -2860,8 +2909,8 @@ async function main(): Promise<void> {
         if ((layer === "L2" || layer === "all") && format !== "ci") {
           await printStoryReflectionValidationSummary(rootDir, unit);
         }
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── quick-mode / ci-check ──
@@ -2916,8 +2965,8 @@ async function main(): Promise<void> {
           format,
           failOnFullRequired,
         });
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── harness-api ──
@@ -3077,7 +3126,16 @@ async function main(): Promise<void> {
         }
         const { createAttestationModule } = await import("./attestation/index.js");
         const pkgVersion = await getHarnessVersion(harnessRoot);
-        const mod = createAttestationModule(rootDir, { pkgVersion });
+        const worldModule = createWorldModelModule({
+          rootDir,
+          resolvedConfig: await loadWorldResolvedConfig(),
+        });
+        const mod = createAttestationModule(rootDir, {
+          pkgVersion,
+          worldSnapshotRootProvider: {
+            getWorldSnapshotRoot: async () => (await worldModule.worldSnapshotRootFacade.read()).worldSnapshotRoot,
+          },
+        });
         const result = await mod.attestHandler.handle({
           out: parseFlag(args, "--out") ?? ".harness/attestation.json",
           requirePass: hasFlag(args, "--require-pass"),
@@ -3085,8 +3143,8 @@ async function main(): Promise<void> {
           mode: parseFlag(args, "--mode"),
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "phasegate:verify-attestation": {
@@ -3103,8 +3161,8 @@ async function main(): Promise<void> {
           emitJson: json,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── ci-governance ──
@@ -3127,7 +3185,8 @@ Options:
 Examples:
   phasegate ci:generate-template --type aidlc-gate
   phasegate ci:generate-template --preset strict --type pre-commit --render`);
-          process.exit(0);
+          await finishCliExit(0);
+          return;
         }
         const flagError = validateKnownFlags(args.slice(1), ["--preset", "--type", "--render", "--json", "--help"]);
         if (flagError !== null) {
@@ -3141,8 +3200,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.generateCiTemplateHandler.handle({ presetId, templateType, render, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "ci:migrate-agents-md": {
@@ -3152,8 +3211,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.migrateAgentsMdHandler.handle({ dryRun, validateOnly, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "ci:auto-refresh-agent-context": {
@@ -3163,8 +3222,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.refreshAgentContextHandler.handle({ dryRun, apply, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "refresh-claude-md": {
@@ -3174,8 +3233,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.refreshClaudeMdHandler.handle({ dryRun, apply, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "p2:check-agent-context": {
@@ -3185,8 +3244,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.checkAgentContextHandler.handle({ thresholdDays, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "ci:check-repetition": {
@@ -3196,8 +3255,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.checkRepetitionHandler.handle({ errorCode, reset, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "baseline": {
@@ -3219,8 +3278,8 @@ Examples:
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "scaffold-design": {
@@ -3240,8 +3299,8 @@ Examples:
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "integrity:pin": {
@@ -3250,8 +3309,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.integrityHandler.pin({ dryRun, format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "integrity:verify": {
@@ -3259,8 +3318,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.integrityHandler.verify({ format });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── skill-quality ──
@@ -3275,8 +3334,8 @@ Examples:
         const passed = hasFlag(args, "--passed");
         const result = await mod.executeTddCycleHandler.handle({ unit, storyId, description, phase, passed });
         console.log(result.message);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "skill:check-coverage": {
@@ -3285,8 +3344,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.checkCoverageHandler.handle({ storyId, format });
         console.log(result.message);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "skill:collect-lessons": {
@@ -3297,8 +3356,8 @@ Examples:
         const writeArtifact = hasFlag(args, "--write-artifact");
         const result = await mod.collectLessonsHandler.handle({ storyId, sources, writeArtifact });
         console.log(result.message);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "skill:apply-cascade-update": {
@@ -3307,8 +3366,8 @@ Examples:
         const dryRun = hasFlag(args, "--dry-run");
         const result = await mod.applyCascadeUpdateHandler.handle({ storyId, dryRun, format: json ? "json" : "human" });
         console.log(result.message);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "skill:validate-structure": {
@@ -3317,8 +3376,8 @@ Examples:
         const format = json ? "json" : "human";
         const result = await mod.validateSkillStructureHandler.handle({ skillFile, format });
         console.log(result.message);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── regression-suite ──
@@ -3329,8 +3388,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `K-Requirements: ${result.passedCount}/${result.totalCount} passed`;
         console.log(output);
-        process.exit(result.failedCount > 0 ? 1 : 0);
-        break;
+        await finishCliExit(result.failedCount > 0 ? 1 : 0);
+        return;
       }
 
       case "regression:run-gng-gate": {
@@ -3340,8 +3399,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `GnG Gate: ${result.passedCount}/${result.totalCount} passed`;
         console.log(output);
-        process.exit(result.failedCount > 0 ? 1 : 0);
-        break;
+        await finishCliExit(result.failedCount > 0 ? 1 : 0);
+        return;
       }
 
       case "regression:run-agent-guard": {
@@ -3351,8 +3410,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `Agent Independence: ${result.passedCount}/${result.totalCount} passed`;
         console.log(output);
-        process.exit(result.failedCount > 0 ? 1 : 0);
-        break;
+        await finishCliExit(result.failedCount > 0 ? 1 : 0);
+        return;
       }
 
       case "regression:run-k14-k15": {
@@ -3362,8 +3421,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `K14/K15: ${result.passedCount}/${result.totalCount} passed`;
         console.log(output);
-        process.exit(result.failedCount > 0 ? 1 : 0);
-        break;
+        await finishCliExit(result.failedCount > 0 ? 1 : 0);
+        return;
       }
 
       case "regression:configure-ci-gate": {
@@ -3379,8 +3438,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `CI gate configured: suites=${result.requiredSuiteIds.join(",")}, threshold=${result.coverageThreshold}%`;
         console.log(output);
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       case "regression:analyze-migration": {
@@ -3391,8 +3450,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `Migration analysis: total=${result.totalCount}, migrated=${result.migratedCount}, modified=${result.modifiedCount}, skipped=${result.skippedCount}`;
         console.log(output);
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       case "regression:migrate-v0-tests": {
@@ -3403,8 +3462,8 @@ Examples:
           ? JSON.stringify(result, null, 2)
           : `Migration: total=${result.totalCount}, migrated=${result.migratedCount}, modified=${result.modifiedCount}, skipped=${result.skippedCount}`;
         console.log(output);
-        process.exit(0);
-        break;
+        await finishCliExit(0);
+        return;
       }
 
       // ── phase2-extensions ──
@@ -3413,8 +3472,8 @@ Examples:
         const p2args = args.slice(1);
         const result = await mod.checkFreshnessHandler.handle(p2args);
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "p2:validate-pointers": {
@@ -3422,8 +3481,8 @@ Examples:
         const p2args = args.slice(1);
         const result = await mod.validatePointersHandler.handle(p2args);
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "p2:generate-e2e-template": {
@@ -3431,8 +3490,8 @@ Examples:
         const p2args = args.slice(1);
         const result = await mod.generateE2ETemplateHandler.handle(p2args);
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "p2:check-initial-creation": {
@@ -3440,8 +3499,8 @@ Examples:
         const p2args = args.slice(1);
         const result = await mod.checkInitialCreationExpirationHandler.handle(p2args);
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── agent integration / hooks ──
@@ -3500,7 +3559,8 @@ Examples:
       case "delegate-sonnet": {
         if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
           printSubcommandHelp("delegate-sonnet");
-          process.exit(0);
+          await finishCliExit(0);
+          return;
         }
         if (!hasFlag(args, "--dry-run") && (await isModelDelegationDisabled(rootDir))) {
           console.error(
@@ -3509,7 +3569,8 @@ Examples:
               message: "phasegate delegate-sonnet is disabled by modelRouting.delegation=none",
             }),
           );
-          process.exit(1);
+          await finishCliExit(1);
+          return;
         }
         const { spawn } = await import("node:child_process");
         const scriptPath = join(harnessRoot, "scripts/delegate-sonnet.sh");
@@ -3559,7 +3620,8 @@ Examples:
             }
             console.log("");
           }
-          process.exit(0);
+          await finishCliExit(0);
+          return;
         }
 
         if (subCommand === "info") {
@@ -3573,7 +3635,8 @@ Examples:
           try {
             const content = await fs.readFile(skillMdPath, "utf-8");
             console.log(content);
-            process.exit(0);
+            await finishCliExit(0);
+            return;
           } catch {
             console.error(`Skill not found: ${skillName}`);
             console.error(`Expected: ${skillMdPath}`);
@@ -3589,12 +3652,13 @@ Examples:
       default:
         console.error(`Unknown command: ${command}`);
         printUsage();
-        process.exit(2);
+        await finishCliExit(2);
+        return;
     }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown error occurred";
     console.error(`Fatal: ${message}`);
-    process.exit(2);
+    await finishCliExit(2);
   }
 }