@abelxiaoxing/cadence 1.2.4 → 1.3.0

package/README.md

@@ -71,6 +71,46 @@ npm install -g @abelxiaoxing/cadence
 
 本包要求 Node.js `>=22.13.0`，以使用稳定可用的内置 `node:sqlite`；不从参考仓库源安装，也不维护 Pi 主机版本兼容矩阵。
 
+## OpenSpec 启动与平台范围
+
+Design finalization 和 Implement delivery 加载共用无 shell 的 OpenSpec 适配层：读取已安装 `@fission-ai/openspec` 的 `package.json` 中 `bin` 声明，再以 Node 执行 JS 入口；不直接执行 Windows npm 的 `.cmd`，也不调用 `npx`、自动下载或切换 CLI 版本。
+
+默认按宿主 `PATH` 定位 OpenSpec，支持 npm 全局默认/自定义 prefix，以及 Unix npm/Bun 的入口符号链接。
+不搜索当前目录，不自动信任 consumer repository 内的 CLI；第一个已发现安装损坏时明确失败，不偷偷选用后续版本。
+版本管理器的任意包装脚本、原生 exe 和 PowerShell 脚本不作为可执行回退。
+
+特殊安装可在**启动宿主之前**配置以下环境变量（不属于 Worker 请求参数）：
+
+| 变量                         | 含义                                                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `ABEL_OPENSPEC_PACKAGE_ROOT` | 已安装 `@fission-ai/openspec` 的绝对包目录，包含 `package.json`；不是 `.cmd` 或 JS 文件路径。显式配置代表操作者信任该安装。 |
+| `ABEL_OPENSPEC_NODE`         | Node 原生可执行文件的绝对路径，例如 `C:\Program Files\nodejs\node.exe`；默认复用 Node 宿主。非 Node 宿主必须显式配置。      |
+
+配置无效不会退回 PATH。
+Windows 环境变量名按不区分大小写读取。
+更换全局安装或 PATH 后应重启宿主，确保它继承新环境。
+
+两个 CLI 子进程各有 30 秒超时、每个输出流 4 MiB 上限，关闭 stdin、禁用 OpenSpec telemetry，并在返回检查结果前等待两者结束。
+校验报告的 exit 1 与 `valid: false` 被识别为 strict-invalid；无法启动、协议异常、超时、取消、输出超限分别给出安全诊断。
+诊断只暴露 command、phase、reason、允许列表中的 systemCode 和 exitCode，不返回原始 stderr、绝对路径或环境变量。
+inspection 不可用时不再级联误报 traceability 输入缺失，且绝不生成成功的 ready 收据。
+
+平台契约 CI 使用 Linux、Windows、macOS × Node 22.13.0/24.13.0，显式安装 OpenSpec 1.5.0，验证真实 npm 全局入口、严格校验、Design finalization、失败重试和 proof-bound delivery 加载。
+状态协议要求布尔字段 `isComplete`，用于判断 1.5.0 的规划产物是否齐全；若另有 `isPlanningComplete`，该字段也必须为布尔值，且两者均为 `true` 才视为规划完成。
+CLI 的其他版本必须满足相同 JSON 协议；新增支持版本应加入契约测试。
+
+**此矩阵不代表原生 Implement 隔离已全平台可用。**
+当前隔离后端仍为 Linux Bubblewrap；Windows/macOS 的原生隔离、ACL 与完整文件应用语义需要单独实现和验收，缺少隔离能力时保持暂停，不降级为主工作区直接执行。
+
+本地可用 `CADENCE_REAL_OPENSPEC=1` 启用真实 CLI 测试（Windows 可用 PowerShell 设置 `$env:CADENCE_REAL_OPENSPEC = "1"`），然后运行：
+
+```sh
+bun run test:target test/openspec-cli.test.ts test/design-delivery.integration.test.ts
+```
+
+未启用时，真实 CLI 用例明确跳过，其他适配层回归测试照常执行。
+`bun run check` 的 JS 语法扫描使用 Node 遍历，不依赖 Unix `find`/`xargs`。
+
 ## Worker 路由（Worker routes）
 
 路由配置是可选的：没有项目级或用户级文件时，三个包内 Agent 默认继承当前父模型，因此首次 Design、Implement 或 Diagnose 不需要预先配置 endpoint。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "pack:check": "node scripts/pack-check.mjs",
     "traceability:check": "node scripts/traceability-check.mjs",
     "verify": "bun run check && bun run lint && bun run test && bun run pack:check",
-    "check": "find skills test scripts -name '*.mjs' -type f -print0 | xargs -0 -r -n1 node --check && tsc --noEmit",
+    "check": "node scripts/check-syntax.mjs && tsc --noEmit",
     "lint": "biome check . && rumdl check .",
     "test": "vitest run",
     "test:target": "vitest run",

package/src/design-control.ts

@@ -27,6 +27,7 @@ import {
   DesignJournal,
   type DesignStatusProjection,
 } from "./design-journal.ts";
+import { OpenSpecCliError, type OpenSpecDiagnostic } from "./openspec-cli.ts";
 import { RunStore } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
 import type { ResolvedStateRoot } from "./state-root.ts";
@@ -131,11 +132,17 @@ export interface DesignControllerOptions {
 export class DesignFinalizationError extends Error {
   readonly diagnostics: readonly string[];
 
-  constructor(diagnostics: readonly string[]) {
+  readonly openSpecDiagnostic?: Readonly<OpenSpecDiagnostic>;
+
+  constructor(
+    diagnostics: readonly string[],
+    openSpecDiagnostic?: Readonly<OpenSpecDiagnostic>,
+  ) {
     const normalized = [...new Set(diagnostics)].sort();
     super("design-finalization-invalid");
     this.name = "DesignFinalizationError";
     this.diagnostics = Object.freeze(normalized);
+    this.openSpecDiagnostic = openSpecDiagnostic;
   }
 }
 
@@ -934,9 +941,12 @@ export class DesignController {
       removeSafeFile(this.consumerRoot, readyPath);
       const diagnostics = new Set<string>();
       let inspection: DesignOpenSpecInspection | undefined;
+      let openSpecDiagnostic: Readonly<OpenSpecDiagnostic> | undefined;
       try {
         inspection = await this.#inspectOpenSpec(this.consumerRoot, change);
-      } catch {
+      } catch (error) {
+        if (error instanceof OpenSpecCliError)
+          openSpecDiagnostic = error.diagnostic;
         diagnostics.add("design-openspec-unavailable");
       }
       if (inspection) {
@@ -1004,7 +1014,7 @@ export class DesignController {
       let traceability:
         | ReturnType<typeof assessDeliveryTraceability>
         | undefined;
-      if (compiled) {
+      if (compiled && inspection) {
         const tasks = artifactBytes.get("tasks.md");
         const specs = [...artifactBytes]
           .filter(
@@ -1035,7 +1045,7 @@ export class DesignController {
         !traceability?.ok ||
         diagnostics.size > 0
       ) {
-        throw new DesignFinalizationError([...diagnostics]);
+        throw new DesignFinalizationError([...diagnostics], openSpecDiagnostic);
       }
       const gateAReceipt = compileGateAReceipt({
         change,

package/src/index.ts

@@ -4,7 +4,6 @@
 // workflow routing (abel-design/implement/diagnose provenance) in the prompts
 // integration; abel-init and ordinary prompts never activate dispatch.
 import { AsyncLocalStorage } from "node:async_hooks";
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   lstatSync,
@@ -17,7 +16,6 @@ import {
 import { homedir } from "node:os";
 import path, { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
 import type {
   AgentToolResult,
   AgentToolUpdateCallback,
@@ -59,6 +57,10 @@ import {
 } from "./design-control.ts";
 import { canonicalJson, hashCanonicalValue } from "./implement-graph.ts";
 import { BubblewrapIsolationBackend } from "./isolation-backend.ts";
+import {
+  inspectOpenSpecDelivery,
+  type OpenSpecDeliveryInspection,
+} from "./openspec-cli.ts";
 import { PACKET_ACTIONS, PacketRuntime } from "./packet-runtime.ts";
 import { ParentPayloadBridge } from "./parent-payload-bridge.ts";
 import { runtimeForWorkerRoute } from "./parent-provider.ts";
@@ -91,6 +93,11 @@ import {
   type WorkflowDeliverySource,
 } from "./workflow-engine.ts";
 
+export {
+  inspectOpenSpecDelivery,
+  type OpenSpecDeliveryInspection,
+} from "./openspec-cli.ts";
+
 export const DISPATCH_TOOL = "abel_dispatch";
 const DESIGN_PARENT_READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
 
@@ -589,7 +596,16 @@ function safeDesignFailure(
     error instanceof DesignFinalizationError ||
     error instanceof DesignPlanValidationError ||
     error instanceof DeliveryValidationError
-      ? error.diagnostics
+      ? error instanceof DesignFinalizationError
+        ? [
+            ...error.diagnostics.filter(
+              (code) =>
+                !error.openSpecDiagnostic ||
+                code !== "design-openspec-unavailable",
+            ),
+            ...(error.openSpecDiagnostic ? [error.openSpecDiagnostic] : []),
+          ]
+        : error.diagnostics
       : [];
   const diagnostics = rawDiagnostics
     .flatMap((candidate) => {
@@ -625,6 +641,10 @@ function safeDesignFailure(
                 "dependencyTaskId",
                 "producerTaskId",
                 "producerPhase",
+                "command",
+                "reason",
+                "systemCode",
+                "exitCode",
               ].includes(entry[0]) &&
               typeof entry[1] === "string" &&
               SAFE_DESIGN_ERROR_CODE.test(entry[1])
@@ -681,15 +701,6 @@ export type WorkflowControlEngineFactory = (
 ) => WorkflowControlEngine | Promise<WorkflowControlEngine>;
 
 const PACKAGE_DELIVERY_MAX_BYTES = 16 * 1024 * 1024;
-const execFileAsync = promisify(execFile);
-
-export interface OpenSpecDeliveryInspection {
-  change: string;
-  schema: string;
-  planningComplete: boolean;
-  strictValid: boolean;
-  artifactPaths: string[];
-}
 
 export interface PackageDeliverySourceOptions {
   inspectOpenSpec?: (
@@ -783,96 +794,6 @@ function readPackageDeliveryFile(
   return readFileSync(target);
 }
 
-function deliveryRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-function parseCommandJson(
-  value: string,
-  code: string,
-): Record<string, unknown> {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw new Error(code);
-  }
-  const record = deliveryRecord(parsed);
-  if (!record) throw new Error(code);
-  return record;
-}
-
-export async function inspectOpenSpecDelivery(
-  consumerRoot: string,
-  change: string,
-): Promise<OpenSpecDeliveryInspection> {
-  const [statusExecution, validationExecution] = await Promise.all([
-    execFileAsync("openspec", ["status", "--change", change, "--json"], {
-      cwd: consumerRoot,
-      encoding: "utf8",
-      maxBuffer: 4 * 1024 * 1024,
-    }),
-    execFileAsync(
-      "openspec",
-      ["validate", change, "--strict", "--json", "--no-interactive"],
-      {
-        cwd: consumerRoot,
-        encoding: "utf8",
-        maxBuffer: 4 * 1024 * 1024,
-      },
-    ),
-  ]);
-  const status = parseCommandJson(
-    statusExecution.stdout,
-    "delivery-openspec-status-invalid",
-  );
-  const validation = parseCommandJson(
-    validationExecution.stdout,
-    "delivery-openspec-validation-invalid",
-  );
-  const changeRoot = path.resolve(consumerRoot, "openspec", "changes", change);
-  const artifactPathsRecord = deliveryRecord(status.artifactPaths);
-  const artifactPaths = artifactPathsRecord
-    ? Object.values(artifactPathsRecord).flatMap((entry) => {
-        const record = deliveryRecord(entry);
-        if (!record || !Array.isArray(record.existingOutputPaths)) return [];
-        return record.existingOutputPaths.flatMap((candidate) => {
-          if (typeof candidate !== "string") return [];
-          const resolved = path.resolve(candidate);
-          const relative = path.relative(changeRoot, resolved);
-          return relative &&
-            !relative.startsWith(`..${path.sep}`) &&
-            relative !== ".." &&
-            !path.isAbsolute(relative)
-            ? [relative.split(path.sep).join("/")]
-            : [];
-        });
-      })
-    : [];
-  const items = Array.isArray(validation.items) ? validation.items : [];
-  const strictValid =
-    items.length === 1 &&
-    deliveryRecord(items[0])?.id === change &&
-    deliveryRecord(items[0])?.valid === true;
-  if (
-    status.changeName !== change ||
-    typeof status.schemaName !== "string" ||
-    artifactPaths.length === 0
-  ) {
-    throw new Error("delivery-openspec-status-invalid");
-  }
-  return {
-    change,
-    schema: status.schemaName,
-    planningComplete:
-      status.isPlanningComplete === true && status.isComplete === true,
-    strictValid,
-    artifactPaths: [...new Set(artifactPaths)].sort(),
-  };
-}
-
 export function packageDeliverySource(
   consumerRoot: string,
   options: PackageDeliverySourceOptions = {},

package/src/openspec-cli.ts

@@ -0,0 +1,494 @@
+import { execFile } from "node:child_process";
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+const PACKAGE_NAME = "@fission-ai/openspec";
+export const OPENSPEC_LIMITS = Object.freeze({
+  timeoutMs: 30_000,
+  maxBuffer: 4 * 1024 * 1024,
+});
+
+type Command = "resolve" | "status" | "validate";
+type Phase = "resolution" | "spawn" | "execution" | "protocol";
+type Reason =
+  | "installation-not-found"
+  | "installation-invalid"
+  | "runtime-unavailable"
+  | "cwd-unavailable"
+  | "terminated"
+  | "unsafe-installation"
+  | "launch-failed"
+  | "timeout"
+  | "cancelled"
+  | "output-limit"
+  | "exit-nonzero"
+  | "json-invalid"
+  | "schema-invalid"
+  | "change-invalid";
+
+/** Only code-owned, non-secret fields may cross the Design failure boundary. */
+export interface OpenSpecDiagnostic {
+  code: "design-openspec-unavailable";
+  command: Command;
+  phase: Phase;
+  reason: Reason;
+  systemCode?: string;
+  exitCode?: string;
+}
+
+export class OpenSpecCliError extends Error {
+  readonly diagnostic: Readonly<OpenSpecDiagnostic>;
+
+  constructor(
+    command: Command,
+    phase: Phase,
+    reason: Reason,
+    detail: { systemCode?: string; exitCode?: number } = {},
+  ) {
+    super("design-openspec-unavailable");
+    this.name = "OpenSpecCliError";
+    this.diagnostic = Object.freeze({
+      code: "design-openspec-unavailable",
+      command,
+      phase,
+      reason,
+      ...(["ENOENT", "EINVAL", "EACCES", "EPERM", "ENOEXEC", "E2BIG"].includes(
+        detail.systemCode ?? "",
+      )
+        ? { systemCode: detail.systemCode }
+        : {}),
+      ...(Number.isSafeInteger(detail.exitCode) && (detail.exitCode ?? -1) >= 0
+        ? { exitCode: String(detail.exitCode) }
+        : {}),
+    });
+  }
+}
+
+export interface OpenSpecCliOptions {
+  /** Trusted operator configuration, never a Worker-supplied command string. */
+  environment?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxBuffer?: number;
+}
+
+export interface OpenSpecInvocation {
+  executable: string;
+  entry: string;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function inside(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function envValue(
+  environment: NodeJS.ProcessEnv,
+  name: string,
+): string | undefined {
+  // Match Node's lexicographic, case-insensitive environment selection on Windows.
+  const key = Object.keys(environment)
+    .sort()
+    .find((candidate) =>
+      process.platform === "win32"
+        ? candidate.toUpperCase() === name.toUpperCase()
+        : candidate === name,
+    );
+  return key === undefined ? undefined : environment[key];
+}
+
+function packageEntry(root: string): string {
+  const canonicalRoot = realpathSync(root);
+  const manifestPath = realpathSync(path.join(canonicalRoot, "package.json"));
+  const manifestStat = lstatSync(manifestPath);
+  if (
+    !inside(canonicalRoot, manifestPath) ||
+    !manifestStat.isFile() ||
+    manifestStat.size > 1024 * 1024
+  )
+    throw new Error("manifest-limit");
+  const manifest = record(JSON.parse(readFileSync(manifestPath, "utf8")));
+  const bin =
+    typeof manifest?.bin === "string"
+      ? manifest.bin
+      : record(manifest?.bin)?.openspec;
+  if (
+    manifest?.name !== PACKAGE_NAME ||
+    typeof bin !== "string" ||
+    path.isAbsolute(bin)
+  )
+    throw new Error("manifest-invalid");
+  const entry = realpathSync(path.resolve(canonicalRoot, bin));
+  if (
+    !inside(canonicalRoot, entry) ||
+    !/\.(?:cjs|mjs|js)$/iu.test(entry) ||
+    !lstatSync(entry).isFile()
+  )
+    throw new Error("entry-invalid");
+  return entry;
+}
+
+function canonicalConsumerRoot(consumerRoot: string): string {
+  try {
+    const root = realpathSync(consumerRoot);
+    if (!lstatSync(root).isDirectory()) throw new Error("cwd-invalid");
+    return root;
+  } catch (error) {
+    throw new OpenSpecCliError("resolve", "resolution", "cwd-unavailable", {
+      systemCode: (error as NodeJS.ErrnoException).code,
+    });
+  }
+}
+
+function commandIn(directory: string): string | undefined {
+  const names =
+    process.platform === "win32"
+      ? ["openspec.exe", "openspec.cmd", "openspec"]
+      : ["openspec"];
+  // Windows filesystems are usually case-insensitive; reject ambiguous names.
+  const entries = process.platform === "win32" ? readdirSync(directory) : names;
+  for (const name of names) {
+    const matches = entries.filter((entry) => entry.toLowerCase() === name);
+    if (matches.length > 1) throw new Error("ambiguous-command");
+    if (matches.length === 1) {
+      const candidate = path.join(directory, matches[0]);
+      if (lstatSync(candidate, { throwIfNoEntry: false })) return candidate;
+    }
+  }
+  return undefined;
+}
+
+/** Resolve once per inspection. Never execute or parse a shell shim. */
+export function resolveOpenSpecInvocation(
+  consumerRoot: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): OpenSpecInvocation {
+  const configuredRoot = envValue(environment, "ABEL_OPENSPEC_PACKAGE_ROOT");
+  const configuredNode = envValue(environment, "ABEL_OPENSPEC_NODE");
+  const node =
+    configuredNode ??
+    (process.release.name === "node" && !process.versions.bun
+      ? process.execPath
+      : undefined);
+  let executable: string;
+  try {
+    if (!node || !path.isAbsolute(node) || /\.(?:cmd|bat|ps1)$/iu.test(node)) {
+      throw new Error("runtime-invalid");
+    }
+    executable = realpathSync(node);
+    if (!lstatSync(executable).isFile()) throw new Error("runtime-invalid");
+  } catch {
+    throw new OpenSpecCliError("resolve", "resolution", "runtime-unavailable");
+  }
+  if (configuredRoot !== undefined) {
+    try {
+      if (!path.isAbsolute(configuredRoot)) throw new Error("root-invalid");
+      return { executable, entry: packageEntry(configuredRoot) };
+    } catch {
+      throw new OpenSpecCliError(
+        "resolve",
+        "resolution",
+        "installation-invalid",
+      );
+    }
+  }
+
+  const consumer = canonicalConsumerRoot(consumerRoot);
+  const directories = (envValue(environment, "PATH") ?? "").split(
+    path.delimiter,
+  );
+  for (const directory of directories) {
+    // Do not introduce implicit cwd search or automatically trust repository CLIs.
+    if (!path.isAbsolute(directory)) continue;
+    let command: string | undefined;
+    let canonicalDirectory: string;
+    try {
+      canonicalDirectory = realpathSync(directory);
+      if (inside(consumer, canonicalDirectory)) continue;
+      command = commandIn(canonicalDirectory);
+    } catch {
+      continue;
+    }
+    if (!command) continue;
+    try {
+      const target = realpathSync(command);
+      if (inside(consumer, target)) {
+        throw new OpenSpecCliError(
+          "resolve",
+          "resolution",
+          "unsafe-installation",
+        );
+      }
+      // npm Windows/custom prefix and Unix global layouts. Symlinked npm/Bun
+      // entries are also discovered by walking their real target's ancestors.
+      const layoutRoots = [
+        path.join(canonicalDirectory, "node_modules", PACKAGE_NAME),
+        path.resolve(canonicalDirectory, "../lib/node_modules", PACKAGE_NAME),
+      ];
+      const roots: string[] = [];
+      let ancestor = path.dirname(target);
+      for (let depth = 0; depth < 8; depth++) {
+        roots.push(ancestor);
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor) break;
+        ancestor = parent;
+      }
+      // A real symlink target identifies the selected version more precisely
+      // than an adjacent global installation.
+      const linked = lstatSync(command).isSymbolicLink();
+      const candidates = linked ? roots : layoutRoots;
+      for (const root of candidates) {
+        let entry: string;
+        try {
+          entry = packageEntry(root);
+          if (linked && entry !== target) continue;
+        } catch {
+          continue;
+        }
+        if (inside(consumer, entry)) {
+          throw new OpenSpecCliError(
+            "resolve",
+            "resolution",
+            "unsafe-installation",
+          );
+        }
+        return { executable, entry };
+      }
+    } catch (error) {
+      if (error instanceof OpenSpecCliError) throw error;
+    }
+    // A broken/shadowing installation must not silently select another version.
+    throw new OpenSpecCliError("resolve", "resolution", "installation-invalid");
+  }
+  throw new OpenSpecCliError("resolve", "resolution", "installation-not-found");
+}
+
+interface CommandResult {
+  stdout: string;
+  exitCode: number;
+}
+
+function execute(
+  invocation: OpenSpecInvocation,
+  command: "status" | "validate",
+  args: string[],
+  consumerRoot: string,
+  options: OpenSpecCliOptions,
+): Promise<CommandResult> {
+  return new Promise((resolve, reject) => {
+    let child: ReturnType<typeof execFile> | undefined;
+    const abort = () => child?.kill("SIGKILL");
+    const failLaunch = (error: unknown) => {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      reject(
+        new OpenSpecCliError(command, "spawn", "launch-failed", {
+          systemCode: typeof code === "string" ? code : undefined,
+        }),
+      );
+    };
+    try {
+      child = execFile(
+        invocation.executable,
+        [invocation.entry, ...args],
+        {
+          cwd: consumerRoot,
+          env: {
+            ...(options.environment ?? process.env),
+            OPENSPEC_TELEMETRY: "0",
+          },
+          encoding: "utf8",
+          shell: false,
+          windowsHide: true,
+          timeout: options.timeoutMs ?? OPENSPEC_LIMITS.timeoutMs,
+          maxBuffer: options.maxBuffer ?? OPENSPEC_LIMITS.maxBuffer,
+          // This adapter launches a single Node CLI, not a shell/process tree.
+          killSignal: "SIGKILL",
+        },
+        (error, stdout) => {
+          options.signal?.removeEventListener("abort", abort);
+          if (options.signal?.aborted) {
+            return reject(
+              new OpenSpecCliError(command, "execution", "cancelled"),
+            );
+          }
+          if (!error) return resolve({ stdout, exitCode: 0 });
+          const code = error.code;
+          if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+            return reject(
+              new OpenSpecCliError(command, "execution", "output-limit"),
+            );
+          }
+          if (error.killed) {
+            return reject(
+              new OpenSpecCliError(command, "execution", "timeout"),
+            );
+          }
+          if (error.signal) {
+            return reject(
+              new OpenSpecCliError(command, "execution", "terminated"),
+            );
+          }
+          if (typeof code === "number")
+            return resolve({ stdout, exitCode: code });
+          reject(
+            new OpenSpecCliError(command, "spawn", "launch-failed", {
+              systemCode: typeof code === "string" ? code : undefined,
+            }),
+          );
+        },
+      );
+      child.stdin?.end();
+      options.signal?.addEventListener("abort", abort, { once: true });
+      if (options.signal?.aborted) abort();
+    } catch (error) {
+      options.signal?.removeEventListener("abort", abort);
+      failLaunch(error);
+    }
+  });
+}
+
+function parseJson(result: CommandResult, command: "status" | "validate") {
+  if (
+    result.exitCode !== 0 &&
+    !(command === "validate" && result.exitCode === 1)
+  ) {
+    throw new OpenSpecCliError(command, "execution", "exit-nonzero", result);
+  }
+  try {
+    const parsed = record(JSON.parse(result.stdout));
+    if (!parsed) throw new Error("not-object");
+    return parsed;
+  } catch {
+    throw new OpenSpecCliError(command, "protocol", "json-invalid", result);
+  }
+}
+
+export interface OpenSpecDeliveryInspection {
+  change: string;
+  schema: string;
+  planningComplete: boolean;
+  strictValid: boolean;
+  artifactPaths: string[];
+}
+
+export async function inspectOpenSpecDelivery(
+  consumerRoot: string,
+  change: string,
+  options: OpenSpecCliOptions = {},
+): Promise<OpenSpecDeliveryInspection> {
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/u.test(change)) {
+    throw new OpenSpecCliError("resolve", "resolution", "change-invalid");
+  }
+  for (const limit of [options.timeoutMs, options.maxBuffer]) {
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+      throw new Error("openspec-limit-invalid");
+    }
+  }
+  if (options.signal?.aborted) {
+    throw new OpenSpecCliError("resolve", "execution", "cancelled");
+  }
+  consumerRoot = canonicalConsumerRoot(consumerRoot);
+  options = {
+    ...options,
+    environment: { ...(options.environment ?? process.env) },
+  };
+  const invocation = resolveOpenSpecInvocation(
+    consumerRoot,
+    options.environment,
+  );
+  // allSettled ensures neither child outlives a failed inspection. Both have
+  // bounded time/output; deterministic status-first diagnostics avoid races.
+  const results = await Promise.allSettled([
+    execute(
+      invocation,
+      "status",
+      ["status", "--change", change, "--json"],
+      consumerRoot,
+      options,
+    ),
+    execute(
+      invocation,
+      "validate",
+      ["validate", change, "--strict", "--json", "--no-interactive"],
+      consumerRoot,
+      options,
+    ),
+  ]);
+  const executions = results.map((result) => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
+  });
+  const status = parseJson(executions[0], "status");
+  const validation = parseJson(executions[1], "validate");
+  const changeRoot = path.resolve(consumerRoot, "openspec", "changes", change);
+  const paths = record(status.artifactPaths);
+  const artifactPaths: string[] = [];
+  let invalidPaths = !paths;
+  for (const entry of Object.values(paths ?? {})) {
+    const outputs = record(entry)?.existingOutputPaths;
+    if (!Array.isArray(outputs)) {
+      invalidPaths = true;
+      continue;
+    }
+    for (const candidate of outputs) {
+      if (typeof candidate !== "string" || candidate.includes("\0")) {
+        invalidPaths = true;
+        continue;
+      }
+      // Relative CLI output is relative to its cwd, not the extension process.
+      const resolved = path.resolve(consumerRoot, candidate);
+      const relative = path.relative(changeRoot, resolved);
+      if (!relative || !inside(changeRoot, resolved)) {
+        invalidPaths = true;
+        continue;
+      }
+      artifactPaths.push(relative.split(path.sep).join("/"));
+    }
+  }
+  if (
+    status.changeName !== change ||
+    typeof status.schemaName !== "string" ||
+    !status.schemaName ||
+    ("isPlanningComplete" in status &&
+      typeof status.isPlanningComplete !== "boolean") ||
+    typeof status.isComplete !== "boolean" ||
+    invalidPaths ||
+    artifactPaths.length === 0
+  )
+    throw new OpenSpecCliError("status", "protocol", "schema-invalid");
+  const items = Array.isArray(validation.items) ? validation.items : [];
+  const item = record(items[0]);
+  if (
+    items.length !== 1 ||
+    item?.id !== change ||
+    typeof item.valid !== "boolean" ||
+    (executions[1].exitCode !== 0 && item.valid)
+  ) {
+    throw new OpenSpecCliError(
+      "validate",
+      "protocol",
+      "schema-invalid",
+      executions[1],
+    );
+  }
+  return {
+    change,
+    schema: status.schemaName,
+    // OpenSpec 1.5.0 reports artifact completion only as isComplete.
+    // When a separate planning flag is present, both flags must be true.
+    planningComplete: status.isComplete && status.isPlanningComplete !== false,
+    strictValid: item.valid,
+    artifactPaths: [...new Set(artifactPaths)].sort(),
+  };
+}