chainlesschain 0.162.180 → 0.162.182

package/src/lib/process-execution-broker/index.js

@@ -4,8 +4,8 @@
  *
  * 统一拦截所有子进程执行：
  * - M1: 所有子进程唯一入口，权限检查
- * - **P0-1**: 可审计的平台执行计划（macOS Seatbelt / Linux prlimit；
- *   Windows 原生 Job Object 未实现时明确报告 unavailable）
+ * - **P0-1**: 可审计的平台执行计划（macOS Seatbelt / Linux prlimit /
+ *   Windows Job Object + Restricted Token）
  * - **P0-1**: 凭据代理 default-on（secrets 永远不裸传给子进程）
  * - M3: 集成W3C trace context自动传播
  * - M4: 自动写入Runtime Provenance Ledger (RPL)
@@ -36,9 +36,18 @@ const require = createRequire(import.meta.url);
 import {
   applySandbox as _applySandbox,
   postSpawnSandbox as _postSpawnSandbox,
+  SANDBOX_BOUNDARIES,
 } from "./platform-sandbox.js";
+import { consumeIssuedPluginSandboxExecutionContract } from "../plugin-runtime/bin.js";
 import { credentialAgent } from "./credential-agent.js";
 
+const SUPPORTED_SANDBOX_BOUNDARIES = new Set(Object.values(SANDBOX_BOUNDARIES));
+const SUPPORTED_SANDBOX_PROFILES = new Set([
+  "default",
+  "strict",
+  "network-only",
+]);
+
 // 延迟导入避免循环依赖
 let _traceCtx = null;
 let _rpl = null;
@@ -189,6 +198,222 @@ class ProcessExecutionBroker extends EventEmitter {
     return safe;
   }
 
+  _normalizePluginExecutableIdentity(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const realPath =
+      typeof raw.realPath === "string" && raw.realPath ? raw.realPath : null;
+    const sha256 =
+      typeof raw.sha256 === "string" && /^[a-f0-9]{64}$/i.test(raw.sha256)
+        ? raw.sha256.toLowerCase()
+        : null;
+    if (!realPath || !sha256) return null;
+    return {
+      contractVersion: 1,
+      realPath,
+      sha256,
+      bytes:
+        Number.isSafeInteger(raw.bytes) && raw.bytes >= 0 ? raw.bytes : null,
+      fileId:
+        raw.dev !== undefined && raw.ino !== undefined
+          ? {
+              dev: String(raw.dev),
+              ino: String(raw.ino),
+            }
+          : null,
+      mtimeMs: Number.isFinite(raw.mtimeMs) ? raw.mtimeMs : null,
+      attestation: "realpath-file-id-sha256",
+    };
+  }
+
+  _freezeExecutableIdentity(identity) {
+    if (!identity) return null;
+    return Object.freeze({
+      ...identity,
+      fileId: identity.fileId ? Object.freeze({ ...identity.fileId }) : null,
+    });
+  }
+
+  _normalizePluginRootIdentity(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    if (
+      typeof raw.realPath !== "string" ||
+      !raw.realPath ||
+      raw.dev === undefined ||
+      raw.ino === undefined
+    ) {
+      return null;
+    }
+    return Object.freeze({
+      realPath: raw.realPath,
+      fileId: Object.freeze({
+        dev: String(raw.dev),
+        ino: String(raw.ino),
+      }),
+      attestation: "realpath-directory-file-id",
+    });
+  }
+
+  /**
+   * Normalize the private execution contract produced by agent-core for one
+   * direct, already-attested strict Plugin Node or static-native bin. Plugin
+   * manifests cannot provide this top-level option; they can only add
+   * required boundaries.
+   */
+  _normalizeSandboxExecutionContract(raw, options, requiredBoundaries, launch) {
+    if (raw === undefined) return null;
+    const invalid = (message) => {
+      throw this._sandboxBoundaryError(
+        "invalid_sandbox_execution_contract",
+        message,
+        {
+          requiredBoundaries,
+          missingBoundaries: requiredBoundaries,
+        },
+      );
+    };
+    if (
+      !consumeIssuedPluginSandboxExecutionContract(raw, {
+        origin: options.origin,
+        command: launch?.command,
+        args: launch?.args,
+        cwd: options.cwd,
+        pluginId: options.pluginId,
+        pluginVersion: options.pluginVersion,
+        pluginSource: options.pluginSource,
+        pluginExecutableIdentity: options.pluginExecutableIdentity,
+        requiredBoundaries,
+        sync: launch?.sync === true,
+      })
+    ) {
+      return invalid(
+        "sandboxExecutionContract was not issued for this plugin launch provenance",
+      );
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return invalid("sandboxExecutionContract must be an object");
+    }
+    const supportedKeys = new Set([
+      "contractVersion",
+      "kind",
+      "pluginRoot",
+      "workingDirectory",
+      "runtimePath",
+      "rootIdentity",
+      "entryIdentity",
+      "runtimeIdentity",
+    ]);
+    const unsupportedKey = Object.keys(raw).find(
+      (key) => !supportedKeys.has(key),
+    );
+    if (unsupportedKey) {
+      return invalid(
+        `sandboxExecutionContract contains unsupported field: ${unsupportedKey}`,
+      );
+    }
+    if (
+      raw.contractVersion !== 1 ||
+      ![
+        "strict-plugin-node-bin",
+        "strict-plugin-native-static-elf-bin",
+      ].includes(raw.kind)
+    ) {
+      return invalid("unsupported sandboxExecutionContract kind or version");
+    }
+    if (
+      options.origin !== "plugin:bin" ||
+      typeof options.pluginId !== "string" ||
+      !options.pluginId ||
+      options.shell !== false
+    ) {
+      return invalid(
+        "sandboxExecutionContract is restricted to direct plugin:bin shell:false launches",
+      );
+    }
+
+    for (const [label, value] of [
+      ["pluginRoot", raw.pluginRoot],
+      ["workingDirectory", raw.workingDirectory],
+      ["runtimePath", raw.runtimePath],
+    ]) {
+      if (
+        typeof value !== "string" ||
+        !value ||
+        value.includes("\0") ||
+        !path.isAbsolute(value)
+      ) {
+        return invalid(`sandboxExecutionContract.${label} must be absolute`);
+      }
+    }
+    const entryIdentity = this._normalizePluginExecutableIdentity(
+      raw.entryIdentity,
+    );
+    const runtimeIdentity = this._normalizePluginExecutableIdentity(
+      raw.runtimeIdentity,
+    );
+    const rootIdentity = this._normalizePluginRootIdentity(raw.rootIdentity);
+    if (!rootIdentity || !entryIdentity || !runtimeIdentity) {
+      return invalid(
+        "sandboxExecutionContract requires attested root, entry, and runtime identities",
+      );
+    }
+    if (
+      rootIdentity.realPath !== raw.pluginRoot ||
+      raw.runtimeIdentity?.requestedPath !== path.resolve(process.execPath) ||
+      raw.runtimePath !== runtimeIdentity.realPath ||
+      !path.isAbsolute(entryIdentity.realPath) ||
+      !path.isAbsolute(runtimeIdentity.realPath)
+    ) {
+      return invalid(
+        "sandboxExecutionContract identity paths do not match the launch contract",
+      );
+    }
+
+    const provenanceIdentity = this._normalizePluginExecutableIdentity(
+      options.pluginExecutableIdentity,
+    );
+    if (
+      !provenanceIdentity ||
+      provenanceIdentity.realPath !== entryIdentity.realPath ||
+      provenanceIdentity.sha256 !== entryIdentity.sha256
+    ) {
+      return invalid(
+        "sandboxExecutionContract entry identity does not match plugin provenance",
+      );
+    }
+    const entryRelative = path.relative(
+      path.resolve(raw.pluginRoot),
+      path.resolve(entryIdentity.realPath),
+    );
+    if (
+      entryRelative === "" ||
+      entryRelative === ".." ||
+      entryRelative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(entryRelative)
+    ) {
+      return invalid(
+        "sandboxExecutionContract entry must be inside pluginRoot",
+      );
+    }
+
+    return Object.freeze({
+      contractVersion: 1,
+      kind: raw.kind,
+      pluginRoot: raw.pluginRoot,
+      workingDirectory: raw.workingDirectory,
+      runtimePath: raw.runtimePath,
+      rootIdentity,
+      entryIdentity: this._freezeExecutableIdentity(entryIdentity),
+      runtimeIdentity: this._freezeExecutableIdentity(runtimeIdentity),
+    });
+  }
+
+  _stripPluginControlOptions(options) {
+    delete options.pluginId;
+    delete options.pluginVersion;
+    delete options.pluginSource;
+    delete options.pluginExecutableIdentity;
+  }
+
   _sandboxStrictEnabled() {
     return process.env.CC_SANDBOX_STRICT === "1";
   }
@@ -197,16 +422,98 @@ class ProcessExecutionBroker extends EventEmitter {
     return process.env.CC_SANDBOX_DISABLE === "1";
   }
 
-  _sandboxUnavailablePlan(command, args, options, reason) {
+  /**
+   * Normalize the public per-spawn boundary contract. `requiredBoundaries` is
+   * retained as a top-level alias so callers can adopt the contract without
+   * migrating all spawn options to `sandboxPolicy` in one change.
+   *
+   * @param {Object} options
+   * @returns {{profile: "default"|"strict"|"network-only"|null, requiredBoundaries: string[]}}
+   */
+  _normalizeSandboxPolicy(options = {}, launch = {}) {
+    const rawPolicy = options.sandboxPolicy;
+    if (
+      rawPolicy !== undefined &&
+      (rawPolicy === null ||
+        typeof rawPolicy !== "object" ||
+        Array.isArray(rawPolicy))
+    ) {
+      throw this._sandboxBoundaryError(
+        "invalid_sandbox_policy",
+        "sandboxPolicy must be an object",
+      );
+    }
+
+    const direct = options.requiredBoundaries;
+    const nested = rawPolicy?.requiredBoundaries;
+    for (const [name, value] of [
+      ["requiredBoundaries", direct],
+      ["sandboxPolicy.requiredBoundaries", nested],
+    ]) {
+      if (value !== undefined && !Array.isArray(value)) {
+        throw this._sandboxBoundaryError(
+          "invalid_required_boundaries",
+          `${name} must be an array`,
+        );
+      }
+    }
+
+    const requiredBoundaries = [];
+    for (const boundary of [...(direct || []), ...(nested || [])]) {
+      if (
+        typeof boundary !== "string" ||
+        !SUPPORTED_SANDBOX_BOUNDARIES.has(boundary)
+      ) {
+        throw this._sandboxBoundaryError(
+          "invalid_required_boundary",
+          `Unsupported sandbox boundary: ${String(boundary)}`,
+          {
+            requiredBoundaries,
+            missingBoundaries: [String(boundary)],
+          },
+        );
+      }
+      if (!requiredBoundaries.includes(boundary)) {
+        requiredBoundaries.push(boundary);
+      }
+    }
+
+    const profile = rawPolicy?.profile ?? null;
+    if (profile !== null && !SUPPORTED_SANDBOX_PROFILES.has(profile)) {
+      throw this._sandboxBoundaryError(
+        "invalid_sandbox_profile",
+        `Unsupported sandbox profile: ${String(profile)}`,
+        { requiredBoundaries },
+      );
+    }
+    const executionContract = this._normalizeSandboxExecutionContract(
+      options.sandboxExecutionContract,
+      options,
+      requiredBoundaries,
+      launch,
+    );
+    return { profile, requiredBoundaries, executionContract };
+  }
+
+  _stripSandboxControlOptions(options) {
+    delete options.sandboxPolicy;
+    delete options.requiredBoundaries;
+    delete options.sandboxExecutionContract;
+  }
+
+  _sandboxUnavailablePlan(command, args, options, reason, sandboxPolicy = {}) {
     return {
       contractVersion: 1,
       applied: false,
       platform: process.platform,
-      profile: "default",
+      profile: sandboxPolicy.profile || "default",
       command,
       args: [...(args || [])],
       options: { ...options },
       enforcement: null,
+      backend: null,
+      guarantees: [],
+      requiredBoundaries: [...(sandboxPolicy.requiredBoundaries || [])],
       reason,
       postSpawn: { required: false, mode: "none" },
     };
@@ -219,6 +526,27 @@ class ProcessExecutionBroker extends EventEmitter {
     return error;
   }
 
+  _sandboxBoundaryError(reason, message = reason, metadata = {}) {
+    const error = this._sandboxError(reason, message);
+    error.code = "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
+    error.sandboxFailClosed = true;
+    error.requiredBoundaries = [...(metadata.requiredBoundaries || [])];
+    error.actualGuarantees = [...(metadata.actualGuarantees || [])];
+    error.missingBoundaries = [...(metadata.missingBoundaries || [])];
+    error.sandboxBackend = metadata.sandboxBackend || null;
+    error.sandboxCandidateBackend = metadata.sandboxCandidateBackend || null;
+    error.sandboxRuntimeProbe = metadata.sandboxRuntimeProbe
+      ? { ...metadata.sandboxRuntimeProbe }
+      : null;
+    error.sandboxPolicyAttested =
+      typeof metadata.sandboxPolicyAttested === "boolean"
+        ? metadata.sandboxPolicyAttested
+        : null;
+    error.sandboxPolicyDigest = metadata.sandboxPolicyDigest || null;
+    error.sandboxCandidateReason = metadata.sandboxCandidateReason || null;
+    return error;
+  }
+
   _validateSandboxPlan(plan) {
     if (!plan || typeof plan !== "object") {
       throw this._sandboxError(
@@ -262,6 +590,125 @@ class ProcessExecutionBroker extends EventEmitter {
         "Unavailable sandbox spawn plan must provide a reason",
       );
     }
+    const backend = plan.backend ?? plan.enforcement ?? null;
+    if (plan.applied && typeof backend !== "string") {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Applied sandbox spawn plan must name its backend",
+      );
+    }
+    const guarantees = plan.guarantees ?? [];
+    if (
+      !Array.isArray(guarantees) ||
+      guarantees.some(
+        (boundary) =>
+          typeof boundary !== "string" ||
+          !SUPPORTED_SANDBOX_BOUNDARIES.has(boundary),
+      )
+    ) {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Sandbox spawn plan guarantees must use supported boundary identifiers",
+      );
+    }
+    const candidateBackend = plan.candidateBackend ?? null;
+    if (candidateBackend !== null && typeof candidateBackend !== "string") {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Sandbox candidate backend must be a string",
+      );
+    }
+    const policyAttested = plan.policyAttested ?? null;
+    if (policyAttested !== null && typeof policyAttested !== "boolean") {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Sandbox policy attestation must be boolean",
+      );
+    }
+    const policyDigest = plan.policyDigest ?? null;
+    if (
+      policyDigest !== null &&
+      (typeof policyDigest !== "string" || !/^[a-f0-9]{64}$/.test(policyDigest))
+    ) {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Sandbox policy digest must be a lowercase SHA-256 value",
+      );
+    }
+    let runtimeProbe = null;
+    if (plan.runtimeProbe !== null && plan.runtimeProbe !== undefined) {
+      if (
+        typeof plan.runtimeProbe !== "object" ||
+        Array.isArray(plan.runtimeProbe) ||
+        typeof plan.runtimeProbe.kind !== "string" ||
+        typeof plan.runtimeProbe.attempted !== "boolean" ||
+        typeof plan.runtimeProbe.runnable !== "boolean" ||
+        (plan.runtimeProbe.reason !== null &&
+          typeof plan.runtimeProbe.reason !== "string")
+      ) {
+        throw this._sandboxError(
+          "invalid_sandbox_plan",
+          "Sandbox runtime probe must use the typed probe contract",
+        );
+      }
+      for (const field of [
+        "probeRuntime",
+        "targetRuntime",
+        "contentSnapshotScope",
+        "contentSnapshotMechanism",
+      ]) {
+        if (
+          plan.runtimeProbe[field] !== undefined &&
+          (typeof plan.runtimeProbe[field] !== "string" ||
+            !plan.runtimeProbe[field])
+        ) {
+          throw this._sandboxError(
+            "invalid_sandbox_plan",
+            `Sandbox runtime probe ${field} must be a non-empty string`,
+          );
+        }
+      }
+      for (const field of ["contentSnapshot", "handleAtomic"]) {
+        if (
+          plan.runtimeProbe[field] !== undefined &&
+          typeof plan.runtimeProbe[field] !== "boolean"
+        ) {
+          throw this._sandboxError(
+            "invalid_sandbox_plan",
+            `Sandbox runtime probe ${field} must be boolean`,
+          );
+        }
+      }
+      runtimeProbe = {
+        kind: plan.runtimeProbe.kind,
+        attempted: plan.runtimeProbe.attempted,
+        runnable: plan.runtimeProbe.runnable,
+        reason: plan.runtimeProbe.reason,
+        ...(plan.runtimeProbe.probeRuntime !== undefined
+          ? { probeRuntime: plan.runtimeProbe.probeRuntime }
+          : {}),
+        ...(plan.runtimeProbe.targetRuntime !== undefined
+          ? { targetRuntime: plan.runtimeProbe.targetRuntime }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshot !== undefined
+          ? { contentSnapshot: plan.runtimeProbe.contentSnapshot }
+          : {}),
+        ...(plan.runtimeProbe.handleAtomic !== undefined
+          ? { handleAtomic: plan.runtimeProbe.handleAtomic }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshotScope !== undefined
+          ? {
+              contentSnapshotScope: plan.runtimeProbe.contentSnapshotScope,
+            }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshotMechanism !== undefined
+          ? {
+              contentSnapshotMechanism:
+                plan.runtimeProbe.contentSnapshotMechanism,
+            }
+          : {}),
+      };
+    }
     const postSpawn = plan.postSpawn || { required: false, mode: "none" };
     if (
       postSpawn.required &&
@@ -277,12 +724,54 @@ class ProcessExecutionBroker extends EventEmitter {
       ...plan,
       args: [...plan.args],
       options: { ...plan.options },
+      backend,
+      guarantees: [...new Set(guarantees)],
+      candidateBackend,
+      policyAttested,
+      policyDigest,
+      runtimeProbe,
       postSpawn: { ...postSpawn },
     };
   }
 
-  _prepareSandboxPlan(command, args, options, { sync = false } = {}) {
+  _assertRequiredSandboxBoundaries(plan, requiredBoundaries) {
+    const actualGuarantees = plan.applied ? plan.guarantees : [];
+    const guaranteed = new Set(actualGuarantees);
+    const missingBoundaries = requiredBoundaries.filter(
+      (boundary) => !guaranteed.has(boundary),
+    );
+    if (missingBoundaries.length > 0) {
+      throw this._sandboxBoundaryError(
+        "required_boundaries_unsatisfied",
+        `Sandbox backend ${plan.backend || plan.candidateBackend || "unavailable"} cannot satisfy required boundaries: ${missingBoundaries.join(", ")}`,
+        {
+          requiredBoundaries,
+          actualGuarantees,
+          missingBoundaries,
+          sandboxBackend: plan.backend,
+          sandboxCandidateBackend: plan.candidateBackend,
+          sandboxRuntimeProbe: plan.runtimeProbe,
+          sandboxPolicyAttested: plan.policyAttested,
+          sandboxPolicyDigest: plan.policyDigest,
+          sandboxCandidateReason: plan.candidateBackend ? plan.reason : null,
+        },
+      );
+    }
+    return {
+      ...plan,
+      requiredBoundaries: [...requiredBoundaries],
+    };
+  }
+
+  _prepareSandboxPlan(
+    command,
+    args,
+    options,
+    { sync = false, sandboxPolicy = {} } = {},
+  ) {
     const strict = this._sandboxStrictEnabled();
+    const requiredBoundaries = sandboxPolicy.requiredBoundaries || [];
+    const profile = strict ? "strict" : sandboxPolicy.profile || "default";
     let disabledReason = null;
     if (this._sandboxDisabledByEnvironment()) {
       disabledReason = "disabled_by_environment";
@@ -300,58 +789,104 @@ class ProcessExecutionBroker extends EventEmitter {
           `Sandbox is unavailable in strict mode: ${disabledReason}`,
         );
       }
-      return this._sandboxUnavailablePlan(
+      const unavailablePlan = this._sandboxUnavailablePlan(
         command,
         args,
         options,
         disabledReason,
+        { ...sandboxPolicy, profile },
+      );
+      return this._assertRequiredSandboxBoundaries(
+        unavailablePlan,
+        requiredBoundaries,
       );
     }
 
-    const plan = this._validateSandboxPlan(
-      this._sandboxAdapter.applySandbox(
-        command,
-        args || [],
-        options,
-        "default",
-      ),
+    const adapterRequest = Object.freeze({
+      profile,
+      requiredBoundaries: Object.freeze([...requiredBoundaries]),
+      sync,
+      ...(sandboxPolicy.executionContract
+        ? { executionContract: sandboxPolicy.executionContract }
+        : {}),
+    });
+    // Keep the legacy string profile in argument four. The built-in adapter
+    // reserves argument five for runtime injection, so the typed request is
+    // additive in argument six and legacy injected adapters can ignore it.
+    const rawPlan = this._sandboxAdapter.applySandbox(
+      command,
+      args || [],
+      options,
+      profile,
+      undefined,
+      adapterRequest,
     );
+    let plan;
+    try {
+      plan = this._validateSandboxPlan(rawPlan);
+      plan = this._assertRequiredSandboxBoundaries(plan, requiredBoundaries);
 
-    if (!plan.applied && strict) {
-      throw this._sandboxError(
-        plan.reason || "sandbox_unavailable",
-        `Sandbox is unavailable in strict mode: ${
-          plan.reason || "unknown reason"
-        }`,
-      );
-    }
-
-    if (plan.applied && plan.postSpawn.required) {
-      if (typeof this._sandboxAdapter.postSpawnSandbox !== "function") {
+      if (!plan.applied && strict) {
         throw this._sandboxError(
-          "post_spawn_adapter_unavailable",
-          "Required post-spawn sandbox adapter is unavailable",
+          plan.reason || "sandbox_unavailable",
+          `Sandbox is unavailable in strict mode: ${
+            plan.reason || "unknown reason"
+          }`,
         );
       }
-      if (sync) {
-        throw this._sandboxError(
-          "post_spawn_unavailable_for_sync",
-          "spawnSync cannot satisfy required post-spawn sandbox enforcement",
-        );
+
+      if (plan.applied && plan.postSpawn.required) {
+        if (typeof this._sandboxAdapter.postSpawnSandbox !== "function") {
+          throw this._sandboxError(
+            "post_spawn_adapter_unavailable",
+            "Required post-spawn sandbox adapter is unavailable",
+          );
+        }
+        if (sync) {
+          throw this._sandboxError(
+            "post_spawn_unavailable_for_sync",
+            "spawnSync cannot satisfy required post-spawn sandbox enforcement",
+          );
+        }
+        if (
+          (strict || requiredBoundaries.length > 0) &&
+          plan.postSpawn.mode !== "sync"
+        ) {
+          throw this._sandboxError(
+            "async_post_spawn_disallowed_in_strict_mode",
+            "Fail-closed sandbox enforcement requires synchronous post-spawn enforcement",
+          );
+        }
       }
-      if (strict && plan.postSpawn.mode !== "sync") {
-        throw this._sandboxError(
-          "async_post_spawn_disallowed_in_strict_mode",
-          "Strict sandbox mode requires synchronous post-spawn enforcement",
-        );
+      return plan;
+    } catch (error) {
+      if (typeof rawPlan?.cleanup === "function") {
+        try {
+          rawPlan.cleanup();
+        } catch {
+          // Preserve the boundary/contract failure that prevented execution.
+        }
       }
+      throw error;
     }
-    return plan;
   }
 
   _applySandboxAudit(auditEntry, plan, applied) {
     auditEntry.sandboxed = applied;
     auditEntry.sandboxProfile = plan?.profile || null;
+    auditEntry.sandboxRequired = [...(plan?.requiredBoundaries || [])];
+    auditEntry.sandboxGuarantees = applied ? [...(plan?.guarantees || [])] : [];
+    auditEntry.sandboxBackend = plan?.backend || null;
+    auditEntry.sandboxCandidateBackend = plan?.candidateBackend || null;
+    auditEntry.sandboxRuntimeProbe = plan?.runtimeProbe
+      ? { ...plan.runtimeProbe }
+      : null;
+    auditEntry.sandboxPolicyAttested =
+      typeof plan?.policyAttested === "boolean" ? plan.policyAttested : null;
+    auditEntry.sandboxPolicyDigest = plan?.policyDigest || null;
+    auditEntry.sandboxCandidateReason = plan?.candidateBackend
+      ? plan?.reason || null
+      : null;
     auditEntry.sandboxEnforcement = applied
       ? plan?.enforcement || "platform"
       : null;
@@ -365,6 +900,30 @@ class ProcessExecutionBroker extends EventEmitter {
     auditEntry.sandboxState = "denied";
     auditEntry.sandboxReason =
       error.sandboxReason || "sandbox_initialization_failed";
+    auditEntry.sandboxRequired = [
+      ...(error.requiredBoundaries || auditEntry.sandboxRequired || []),
+    ];
+    auditEntry.sandboxGuarantees = [
+      ...(error.actualGuarantees || auditEntry.sandboxGuarantees || []),
+    ];
+    auditEntry.sandboxMissing = [...(error.missingBoundaries || [])];
+    auditEntry.sandboxBackend =
+      error.sandboxBackend || auditEntry.sandboxBackend || null;
+    auditEntry.sandboxCandidateBackend =
+      error.sandboxCandidateBackend ||
+      auditEntry.sandboxCandidateBackend ||
+      null;
+    auditEntry.sandboxRuntimeProbe = error.sandboxRuntimeProbe
+      ? { ...error.sandboxRuntimeProbe }
+      : auditEntry.sandboxRuntimeProbe || null;
+    auditEntry.sandboxPolicyAttested =
+      typeof error.sandboxPolicyAttested === "boolean"
+        ? error.sandboxPolicyAttested
+        : (auditEntry.sandboxPolicyAttested ?? null);
+    auditEntry.sandboxPolicyDigest =
+      error.sandboxPolicyDigest || auditEntry.sandboxPolicyDigest || null;
+    auditEntry.sandboxCandidateReason =
+      error.sandboxCandidateReason || auditEntry.sandboxCandidateReason || null;
     auditEntry.deniedReason = `sandbox-init-failed: ${error.message}`;
     auditEntry.endTime = Date.now();
     auditEntry.durationMs = auditEntry.endTime - startTime;
@@ -391,7 +950,11 @@ class ProcessExecutionBroker extends EventEmitter {
     if (!plan.applied || !plan.postSpawn.required) {
       this._applySandboxAudit(auditEntry, plan, plan.applied);
       if (plan.applied) this._stats.sandboxed++;
-      const ready = Promise.resolve({ applied: plan.applied });
+      const ready = Promise.resolve({
+        applied: plan.applied,
+        backend: plan.backend,
+        guarantees: plan.applied ? [...plan.guarantees] : [],
+      });
       proc.sandboxReady = ready;
       return;
     }
@@ -403,7 +966,7 @@ class ProcessExecutionBroker extends EventEmitter {
       this._applySandboxAudit(auditEntry, plan, false);
       auditEntry.sandboxState = "failed";
       auditEntry.sandboxReason = `post_spawn_failed: ${error.message}`;
-      if (this._sandboxStrictEnabled()) {
+      if (this._sandboxStrictEnabled() || plan.requiredBoundaries.length > 0) {
         if (typeof proc.once === "function") proc.once("error", () => {});
         try {
           proc.kill?.();
@@ -423,7 +986,7 @@ class ProcessExecutionBroker extends EventEmitter {
     }
 
     if (postSpawnResult && typeof postSpawnResult.then === "function") {
-      if (this._sandboxStrictEnabled()) {
+      if (this._sandboxStrictEnabled() || plan.requiredBoundaries.length > 0) {
         Promise.resolve(postSpawnResult).catch(() => {});
         if (typeof proc.once === "function") proc.once("error", () => {});
         try {
@@ -442,7 +1005,11 @@ class ProcessExecutionBroker extends EventEmitter {
         () => {
           this._applySandboxAudit(auditEntry, plan, true);
           this._stats.sandboxed++;
-          return { applied: true };
+          return {
+            applied: true,
+            backend: plan.backend,
+            guarantees: [...plan.guarantees],
+          };
         },
         (error) => {
           this._applySandboxAudit(auditEntry, plan, false);
@@ -463,7 +1030,11 @@ class ProcessExecutionBroker extends EventEmitter {
 
     this._applySandboxAudit(auditEntry, plan, true);
     this._stats.sandboxed++;
-    proc.sandboxReady = Promise.resolve({ applied: true });
+    proc.sandboxReady = Promise.resolve({
+      applied: true,
+      backend: plan.backend,
+      guarantees: [...plan.guarantees],
+    });
   }
 
   _credentialBoundaryEnabled() {
@@ -527,6 +1098,35 @@ class ProcessExecutionBroker extends EventEmitter {
     };
   }
 
+  _createCredentialContext(command, options, executionId, decision) {
+    if (typeof this._credentialAgent.createBrokerContext !== "function") {
+      return options.credentialContext;
+    }
+    const supplied = options.credentialContext || {};
+    return this._credentialAgent.createBrokerContext({
+      approvalId: `${executionId}:${decision}`,
+      process: command,
+      host:
+        supplied.target?.host ??
+        supplied.host ??
+        options.credentialTarget?.host ??
+        options.credentialTargetHost ??
+        null,
+      ttlMs: supplied.ttlMs ?? options.credentialTtlMs,
+      maxUses: supplied.maxUses ?? options.credentialMaxUses,
+    });
+  }
+
+  _stripCredentialControlOptions(options) {
+    delete options.credentialContext;
+    delete options.credentialApproved;
+    delete options.credentialApprovalId;
+    delete options.credentialTarget;
+    delete options.credentialTargetHost;
+    delete options.credentialTtlMs;
+    delete options.credentialMaxUses;
+  }
+
   _recordCredentialReport(auditEntry, report) {
     const filtered = report?.filtered === true;
     auditEntry.credentialFiltered = filtered;
@@ -629,8 +1229,28 @@ class ProcessExecutionBroker extends EventEmitter {
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
+      sandboxRequired: [],
+      sandboxGuarantees: [],
+      sandboxBackend: null,
     };
 
+    let sandboxPolicy;
+    try {
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: false,
+      });
+      auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
+    } catch (sandboxPolicyError) {
+      this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
+      sandboxPolicyError.auditEntry = auditEntry;
+      throw sandboxPolicyError;
+    }
+
     if (decision === "deny" || decision === "prompt") {
       auditEntry.deniedReason = isDangerous
         ? "dangerous_command"
@@ -658,6 +1278,8 @@ class ProcessExecutionBroker extends EventEmitter {
 
     // 传播traceparent环境变量
     const spawnOpts = this._sanitizeOptions(options);
+    this._stripSandboxControlOptions(spawnOpts);
+    this._stripPluginControlOptions(spawnOpts);
     if (traceCtx) {
       spawnOpts.env = { ...(spawnOpts.env || process.env) };
       spawnOpts.env.TRACEPARENT = traceCtx.traceparent;
@@ -665,6 +1287,12 @@ class ProcessExecutionBroker extends EventEmitter {
 
     // P0-1: Credential filtering (default-on) — strip secrets from env/args
     if (this._credentialBoundaryEnabled()) {
+      spawnOpts.credentialContext = this._createCredentialContext(
+        command,
+        spawnOpts,
+        executionId,
+        decision,
+      );
       const credentialBoundary = this._applyCredentialBoundary(
         command,
         args,
@@ -675,14 +1303,21 @@ class ProcessExecutionBroker extends EventEmitter {
       args = credentialBoundary.args;
       auditEntry.args = [...args];
       this._recordCredentialReport(auditEntry, credentialBoundary.report);
+      this._stripCredentialControlOptions(spawnOpts);
     }
 
     // P0-1: Platform sandbox wrapping — apply macOS/Windows/Linux sandbox
     let sandboxPlan;
     try {
-      sandboxPlan = this._prepareSandboxPlan(command, args || [], spawnOpts);
+      sandboxPlan = this._prepareSandboxPlan(command, args || [], spawnOpts, {
+        sandboxPolicy,
+      });
     } catch (sandboxErr) {
-      if (this._sandboxStrictEnabled()) {
+      if (
+        this._sandboxStrictEnabled() ||
+        sandboxErr.sandboxFailClosed ||
+        sandboxPolicy.requiredBoundaries.length > 0
+      ) {
         this._recordSandboxDenial(auditEntry, sandboxErr, startTime);
         sandboxErr.auditEntry = auditEntry;
         throw sandboxErr;
@@ -695,6 +1330,7 @@ class ProcessExecutionBroker extends EventEmitter {
         args || [],
         spawnOpts,
         `sandbox_init_failed: ${sandboxErr.message}`,
+        sandboxPolicy,
       );
     }
     command = sandboxPlan.command;
@@ -722,6 +1358,13 @@ class ProcessExecutionBroker extends EventEmitter {
     );
     try {
       this._runPostSpawnSandbox(proc, sandboxPlan, auditEntry);
+      auditEntry.pid = proc.pid;
+      if (Number.isSafeInteger(proc.sandboxWrapperPid)) {
+        auditEntry.sandboxWrapperPid = proc.sandboxWrapperPid;
+      }
+      if (Number.isSafeInteger(proc.sandboxTargetPid)) {
+        auditEntry.sandboxTargetPid = proc.sandboxTargetPid;
+      }
     } catch (postSpawnError) {
       cleanupSandbox();
       this._recordSandboxDenial(auditEntry, postSpawnError, startTime);
@@ -809,8 +1452,28 @@ class ProcessExecutionBroker extends EventEmitter {
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
+      sandboxRequired: [],
+      sandboxGuarantees: [],
+      sandboxBackend: null,
     };
 
+    let sandboxPolicy;
+    try {
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: true,
+      });
+      auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
+    } catch (sandboxPolicyError) {
+      this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
+      sandboxPolicyError.auditEntry = auditEntry;
+      throw sandboxPolicyError;
+    }
+
     if (decision === "deny" || decision === "prompt") {
       auditEntry.deniedReason = isDangerous
         ? "dangerous_command"
@@ -831,6 +1494,8 @@ class ProcessExecutionBroker extends EventEmitter {
     }
 
     const spawnOpts = this._sanitizeOptions(options);
+    this._stripSandboxControlOptions(spawnOpts);
+    this._stripPluginControlOptions(spawnOpts);
     if (traceCtx) {
       spawnOpts.env = { ...(spawnOpts.env || process.env) };
       spawnOpts.env.TRACEPARENT = traceCtx.traceparent;
@@ -838,6 +1503,12 @@ class ProcessExecutionBroker extends EventEmitter {
 
     // P0-1: Credential filtering agent — strip secrets from env/args before spawn
     if (this._credentialBoundaryEnabled()) {
+      spawnOpts.credentialContext = this._createCredentialContext(
+        command,
+        spawnOpts,
+        executionId,
+        decision,
+      );
       const credentialBoundary = this._applyCredentialBoundary(
         command,
         args,
@@ -848,6 +1519,7 @@ class ProcessExecutionBroker extends EventEmitter {
       args = credentialBoundary.args;
       auditEntry.args = [...args];
       this._recordCredentialReport(auditEntry, credentialBoundary.report);
+      this._stripCredentialControlOptions(spawnOpts);
     }
 
     // P0-1: Platform sandbox wrapping (sync path)
@@ -855,9 +1527,14 @@ class ProcessExecutionBroker extends EventEmitter {
     try {
       sandboxPlan = this._prepareSandboxPlan(command, args || [], spawnOpts, {
         sync: true,
+        sandboxPolicy,
       });
     } catch (sandboxErr) {
-      if (this._sandboxStrictEnabled()) {
+      if (
+        this._sandboxStrictEnabled() ||
+        sandboxErr.sandboxFailClosed ||
+        sandboxPolicy.requiredBoundaries.length > 0
+      ) {
         this._recordSandboxDenial(auditEntry, sandboxErr, startTime);
         sandboxErr.auditEntry = auditEntry;
         throw sandboxErr;
@@ -870,6 +1547,7 @@ class ProcessExecutionBroker extends EventEmitter {
         args || [],
         spawnOpts,
         `sandbox_init_failed: ${sandboxErr.message}`,
+        sandboxPolicy,
       );
     }
     command = sandboxPlan.command;
@@ -929,10 +1607,29 @@ class ProcessExecutionBroker extends EventEmitter {
       pty: true,
       sandboxed: false,
       sandboxReason: "native_pty_host_boundary",
+      sandboxRequired: [],
+      sandboxGuarantees: [],
+      sandboxBackend: null,
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
     };
+    let sandboxPolicy;
+    try {
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: false,
+      });
+      auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
+    } catch (sandboxPolicyError) {
+      this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
+      sandboxPolicyError.auditEntry = auditEntry;
+      throw sandboxPolicyError;
+    }
     if (policy === "deny" || policy === "prompt") {
       auditEntry.deniedReason = `policy_${policy}`;
       auditEntry.endTime = Date.now();
@@ -947,16 +1644,34 @@ class ProcessExecutionBroker extends EventEmitter {
       error.auditEntry = auditEntry;
       throw error;
     }
+    if (sandboxPolicy.requiredBoundaries.length > 0) {
+      const sandboxError = this._sandboxBoundaryError(
+        "required_boundaries_unsatisfied",
+        `Native PTY host cannot satisfy required boundaries: ${sandboxPolicy.requiredBoundaries.join(", ")}`,
+        {
+          requiredBoundaries: sandboxPolicy.requiredBoundaries,
+          missingBoundaries: sandboxPolicy.requiredBoundaries,
+        },
+      );
+      this._recordSandboxDenial(auditEntry, sandboxError, startTime);
+      sandboxError.auditEntry = auditEntry;
+      throw sandboxError;
+    }
 
     const spawnOptions = { ...options, args: [...auditEntry.args] };
+    this._stripSandboxControlOptions(spawnOptions);
+    this._stripPluginControlOptions(spawnOptions);
     delete spawnOptions.origin;
     delete spawnOptions.policy;
     delete spawnOptions.scope;
-    delete spawnOptions.pluginId;
-    delete spawnOptions.pluginVersion;
-    delete spawnOptions.pluginSource;
     try {
       if (this._credentialBoundaryEnabled()) {
+        spawnOptions.credentialContext = this._createCredentialContext(
+          command,
+          spawnOptions,
+          executionId,
+          policy,
+        );
         const credentialBoundary = this._applyCredentialBoundary(
           command,
           args,
@@ -967,6 +1682,7 @@ class ProcessExecutionBroker extends EventEmitter {
         spawnOptions.args = credentialBoundary.args;
         auditEntry.args = [...credentialBoundary.args];
         this._recordCredentialReport(auditEntry, credentialBoundary.report);
+        this._stripCredentialControlOptions(spawnOptions);
       }
       const filteredArgs = spawnOptions.args || [];
       delete spawnOptions.args;
@@ -1156,5 +1872,5 @@ class ProcessExecutionBroker extends EventEmitter {
 }
 
 const broker = new ProcessExecutionBroker();
-export { broker as executionBroker };
+export { broker as executionBroker, SANDBOX_BOUNDARIES };
 export default broker;