phasegate 0.229.0 → 0.264.0

package/scripts/harness/main.ts

@@ -21,6 +21,10 @@
  * @work-item-id WI-213
  * @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 からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -44,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";
@@ -92,6 +97,12 @@ import {
 import { createSkillQualityHandlers } from "./skill-quality/composition-root.js";
 import { createTraceabilityModelModule } from "./traceability-model/composition-root.js";
 import { createValidatorSystemModule } from "./validator-system/composition-root.js";
+import {
+  createWorldModelModule,
+  WorldDeriveCommandHandler,
+  WorldInspectCommandHandler,
+  WorldPinCommandHandler,
+} from "./world-model/index.js";
 
 /**
  * main.ts (scripts/harness/main.ts) から2階層上がパッケージルート。
@@ -232,6 +243,9 @@ Commands:
   phasegate:generate-matrix      Generate requirement-test matrix (--requirements, --tests, --out, --json)
   phasegate:attest               Produce a signed-attestation record of ci-check (--out <path>, --require-pass, --mode <unsigned-poc|signed>, --json)
   phasegate:verify-attestation   Verify an attestation record's integrity (<file>, --json)
+  world:inspect                  Inspect the read-only World snapshot (--format human|json, --json)
+  world:pin                      Preview or apply an endpoint pin (--constraint, --endpoint, --apply)
+  world:derive                   Derive obligations (--write, --out, --format human|json, --json)
 
 Gate semantics:
   phasegate:complete-check       Gate: lint + all validators; exits 1 on failure
@@ -780,6 +794,35 @@ Options:
   "phasegate:check-ready": `Usage: phasegate phasegate:check-ready
 
 Check whether the harness is ready (config valid, hooks deployed).`,
+  "world:inspect": `Usage: phasegate world:inspect [options]
+
+Inspect the read-only World snapshot without writing declarations or generated reports.
+
+Options:
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
+  "world:pin": `Usage: phasegate world:pin --constraint <id> --endpoint <claimant|premise> [options]
+
+Preview a current endpoint digest. Use --apply to atomically update phasegate.world-constraints.json.
+
+Options:
+  --constraint <id>              pgw:v1:constraint ID
+  --endpoint <role>              claimant or premise
+  --apply                        Atomically apply the candidate
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
+  "world:derive": `Usage: phasegate world:derive [options]
+
+Derive the immutable World obligation report. Default mode is pure and read-only.
+
+Options:
+  --write                        Persist the raw obligation report
+  --out <path>                   Override report path (requires --write)
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
   "phasegate:complete-check": `Usage: phasegate phasegate:complete-check
 
 Run completion check (used by Stop hook). Validates phase-gate, metadata, and test-quality.`,
@@ -1838,13 +1881,45 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
   }
 }
 
+async function loadWorldResolvedConfig() {
+  try {
+    const configModule = createConfigFoundationModule();
+    const result = await configModule.usecases.loadResolvedConfigUseCase.execute();
+    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();
@@ -1853,19 +1928,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 = await loadResolvedConfig();
+  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig();
 
   try {
     switch (command) {
@@ -2134,8 +2211,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": {
@@ -2160,8 +2237,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": {
@@ -2187,14 +2264,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": {
@@ -2220,8 +2297,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": {
@@ -2278,8 +2355,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "setup:agent": {
@@ -2361,8 +2438,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": {
@@ -2392,7 +2469,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) {
@@ -2406,7 +2484,8 @@ async function main(): Promise<void> {
             } else {
               console.error(`Error: ${message}`);
             }
-            process.exit(1);
+            await finishCliExit(1);
+            return;
           }
         }
         if (json) {
@@ -2420,8 +2499,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": {
@@ -2442,7 +2521,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) {
@@ -2450,7 +2530,8 @@ async function main(): Promise<void> {
             } else {
               console.error(`Error: ${message}`);
             }
-            process.exit(2);
+            await finishCliExit(2);
+            return;
           }
         }
         if (subcommand === "end") {
@@ -2463,7 +2544,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) {
@@ -2471,7 +2553,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.");
@@ -2498,8 +2581,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "reconcile": {
@@ -2523,8 +2606,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.stdout);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── config-foundation ──
@@ -2539,8 +2622,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "disable-feature": {
@@ -2554,8 +2637,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "list-features": {
@@ -2564,8 +2647,8 @@ async function main(): Promise<void> {
           list: true,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "migrate": {
@@ -2577,8 +2660,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";
@@ -2588,8 +2671,8 @@ async function main(): Promise<void> {
           configPath,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── harness-error ──
@@ -2603,8 +2686,8 @@ async function main(): Promise<void> {
           failOnError,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "validate-fix": {
@@ -2618,8 +2701,8 @@ async function main(): Promise<void> {
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "list-errors": {
@@ -2631,8 +2714,8 @@ async function main(): Promise<void> {
           layer,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── traceability-model ──
@@ -2644,8 +2727,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": {
@@ -2660,8 +2743,60 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
+      }
+
+      // ── world-model ──
+      case "world:inspect": {
+        let handler: WorldInspectCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldInspectCommandHandler;
+        } catch (error) {
+          handler = WorldInspectCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+      }
+
+      case "world:pin": {
+        let handler: WorldPinCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldPinCommandHandler;
+        } catch (error) {
+          handler = WorldPinCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+      }
+
+      case "world:derive": {
+        let handler: WorldDeriveCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldDeriveCommandHandler;
+        } catch (error) {
+          handler = WorldDeriveCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
       }
 
       // ── phase-dependency-model ──
@@ -2685,8 +2820,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── adr-foundation ──
@@ -2701,8 +2836,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "validate-adr": {
@@ -2715,8 +2850,8 @@ async function main(): Promise<void> {
           json,
         });
         console.log(result.text);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── biome-ast-engine ──
@@ -2726,8 +2861,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 ──
@@ -2754,8 +2889,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 ──
@@ -2810,8 +2945,8 @@ async function main(): Promise<void> {
           format,
           failOnFullRequired,
         });
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── harness-api ──
@@ -2971,7 +3106,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"),
@@ -2979,8 +3123,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": {
@@ -2997,8 +3141,8 @@ async function main(): Promise<void> {
           emitJson: json,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       // ── ci-governance ──
@@ -3021,7 +3165,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) {
@@ -3035,8 +3180,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": {
@@ -3046,8 +3191,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": {
@@ -3057,8 +3202,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": {
@@ -3068,8 +3213,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": {
@@ -3079,8 +3224,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": {
@@ -3090,8 +3235,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": {
@@ -3113,8 +3258,8 @@ Examples:
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "scaffold-design": {
@@ -3134,8 +3279,8 @@ Examples:
           format,
         });
         console.log(result.output);
-        process.exit(result.exitCode);
-        break;
+        await finishCliExit(result.exitCode);
+        return;
       }
 
       case "integrity:pin": {
@@ -3144,8 +3289,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": {
@@ -3153,8 +3298,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 ──
@@ -3169,8 +3314,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": {
@@ -3179,8 +3324,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": {
@@ -3191,8 +3336,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": {
@@ -3201,8 +3346,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": {
@@ -3211,8 +3356,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 ──
@@ -3223,8 +3368,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": {
@@ -3234,8 +3379,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": {
@@ -3245,8 +3390,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": {
@@ -3256,8 +3401,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": {
@@ -3273,8 +3418,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": {
@@ -3285,8 +3430,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": {
@@ -3297,8 +3442,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 ──
@@ -3307,8 +3452,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": {
@@ -3316,8 +3461,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": {
@@ -3325,8 +3470,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": {
@@ -3334,8 +3479,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 ──
@@ -3394,7 +3539,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(
@@ -3403,7 +3549,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");
@@ -3453,7 +3600,8 @@ Examples:
             }
             console.log("");
           }
-          process.exit(0);
+          await finishCliExit(0);
+          return;
         }
 
         if (subCommand === "info") {
@@ -3467,7 +3615,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}`);
@@ -3483,12 +3632,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);
   }
 }