chainlesschain 0.162.163 → 0.162.164

package/src/lib/capability-manifest.js

@@ -0,0 +1,319 @@
+/**
+ * Canonical capability manifest — the single source the CLI capability output,
+ * the VS Code / JetBrains negotiation, the protocol docs, the compatibility
+ * fixture, the behavior matrix and the release-notes capability diff all project
+ * from (P1-9 "Capability Manifest 与脱敏诊断包" of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md).
+ *
+ * Today the wire-protocol capability surface is hand-authored in THREE places
+ * that can silently drift:
+ *   - [[capability-negotiation.js]]: `PROTOCOL_FEATURES`, `FEATURE_MIN_VERSION`,
+ *     and the private `FEATURE_TO_FIELD` map.
+ *   - [[headless-manifest.js]]: `buildAgentCapabilities().features` (the
+ *     `cc agent --capabilities` output).
+ *   - the Java twin + the shared negotiation fixture.
+ * A new v2 field added to one list but not the others parses wrong on the peer
+ * that missed it. This module is the ONE definition; every other shape is a pure
+ * projection of it, and a drift-guard test asserts the live hand-authored
+ * constants still equal the projection (see capability-manifest.test.js).
+ *
+ * Pure: no fs / process / clock. Projections are deterministic so a caller can
+ * regenerate docs/fixtures and diff them against the checked-in copies in CI.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * THE canonical manifest. `wireFeatures` is the negotiable additive per-line
+ * field set (order mirrors capability-negotiation.js `PROTOCOL_FEATURES`);
+ * `runtimeFeatures` are the boolean capability flags that change what the CLI
+ * can DO (not the shape of a line the client must parse) and are NOT negotiated.
+ */
+export const CAPABILITY_MANIFEST = Object.freeze({
+  name: "chainlesschain-cli",
+  protocolVersion: 1,
+  minProtocolVersion: 1,
+
+  wireFeatures: Object.freeze([
+    Object.freeze({
+      key: "event_seq",
+      field: "seq",
+      minVersion: 1,
+      description:
+        "every stream-json stdout line carries a monotonic per-run `seq`",
+    }),
+    Object.freeze({
+      key: "tool_use_id",
+      field: "tool_use_id",
+      minVersion: 1,
+      description:
+        'tool_use / tool_result lines carry a pairing `id` ("tu-<n>")',
+    }),
+    Object.freeze({
+      key: "trace_id",
+      field: "trace_id",
+      minVersion: 1,
+      description:
+        "each line carries a run-scoped, caller-injectable `trace_id` for IDE ↔ CLI correlation",
+    }),
+  ]),
+
+  // Boolean capability flags (buildAgentCapabilities().features truthy keys).
+  runtimeFeatures: Object.freeze([
+    "bare",
+    "safe_mode",
+    "ephemeral",
+    "background",
+    "worktree",
+    "checkpoint",
+    "json_schema_output",
+    "partial_messages",
+    "interactive_approvals",
+    "permission_prompt_tool",
+    "remote_control",
+  ]),
+
+  mcpFeatures: Object.freeze([
+    "config_file",
+    "registry",
+    "tool_search",
+    "oauth",
+    "managed_allowlist",
+  ]),
+  sandboxEngines: Object.freeze(["docker", "bubblewrap"]),
+
+  permissionModes: Object.freeze([
+    "default",
+    "manual",
+    "auto",
+    "dontAsk",
+    "plan",
+    "acceptEdits",
+    "bypassPermissions",
+  ]),
+  outputFormats: Object.freeze(["text", "json", "stream-json"]),
+  inputFormats: Object.freeze(["text", "stream-json"]),
+});
+
+const manifestOr = (m) =>
+  m && typeof m === "object" ? m : CAPABILITY_MANIFEST;
+const wireFeaturesOf = (m) =>
+  Array.isArray(manifestOr(m).wireFeatures) ? manifestOr(m).wireFeatures : [];
+
+/**
+ * The negotiable wire feature keys, in canonical declared order — the value
+ * capability-negotiation.js `PROTOCOL_FEATURES` must equal.
+ * @returns {string[]}
+ */
+export function toProtocolFeatures(m = CAPABILITY_MANIFEST) {
+  return wireFeaturesOf(m).map((f) => f.key);
+}
+
+/**
+ * Feature → minimum protocol version, ONLY for features gated above the base
+ * version (a v1-additive field is absent, matching an empty
+ * `FEATURE_MIN_VERSION` today). Adding a v2 feature here flows the gate to the
+ * negotiator automatically.
+ * @returns {Record<string, number>}
+ */
+export function toFeatureMinVersion(m = CAPABILITY_MANIFEST) {
+  const out = {};
+  for (const f of wireFeaturesOf(m)) {
+    if (Number(f.minVersion) > 1) out[f.key] = Number(f.minVersion);
+  }
+  return out;
+}
+
+/**
+ * Feature → the stream line field it gates (the value of the private
+ * `FEATURE_TO_FIELD` map in capability-negotiation.js).
+ * @returns {Record<string, string>}
+ */
+export function toFieldGate(m = CAPABILITY_MANIFEST) {
+  const out = {};
+  for (const f of wireFeaturesOf(m)) out[f.key] = f.field;
+  return out;
+}
+
+/**
+ * The server negotiation offer shape consumed by
+ * capability-negotiation.js `negotiateProtocol(server, …)`.
+ * @returns {{protocolVersion:number, minProtocolVersion:number, features:string[]}}
+ */
+export function toServerOffer(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  return {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    features: toProtocolFeatures(mm),
+  };
+}
+
+/**
+ * The `features` object of `cc agent --capabilities`
+ * (buildAgentCapabilities().features): every runtime flag true, every wire
+ * feature true, plus the nested `mcp` object and `sandbox_engines` list. A test
+ * asserts the live buildAgentCapabilities().features deep-equals this.
+ * @returns {object}
+ */
+export function toAgentFeatureFlags(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const flags = {};
+  for (const key of mm.runtimeFeatures || []) flags[key] = true;
+  for (const f of wireFeaturesOf(mm)) flags[f.key] = true;
+  flags.mcp = {};
+  for (const key of mm.mcpFeatures || []) flags.mcp[key] = true;
+  flags.sandbox_engines = [...(mm.sandboxEngines || [])];
+  return flags;
+}
+
+/**
+ * A deterministic capability fixture the VS Code / JetBrains twins can pin and
+ * assert against (the "Compatibility Fixture" the gap doc asks for). Order- and
+ * clock-independent; a `digest` lets a peer detect any change in one compare.
+ * @returns {object}
+ */
+export function buildCompatFixture(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const body = {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    features: toProtocolFeatures(mm),
+    featureFields: toFieldGate(mm),
+    featureMinVersion: toFeatureMinVersion(mm),
+    permissionModes: [...(mm.permissionModes || [])],
+    outputFormats: [...(mm.outputFormats || [])],
+    inputFormats: [...(mm.inputFormats || [])],
+  };
+  return { ...body, digest: capabilityDigest(mm) };
+}
+
+/**
+ * A stable digest of the whole capability surface (no RNG/clock) — one string
+ * that changes iff any projected capability changed. Handy as a CI drift check.
+ * @returns {string} 16-hex-char sha256 prefix
+ */
+export function capabilityDigest(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const canonical = {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    wire: wireFeaturesOf(mm)
+      .map((f) => [f.key, f.field, Number(f.minVersion) || 1])
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
+    runtime: [...(mm.runtimeFeatures || [])].sort(),
+    mcp: [...(mm.mcpFeatures || [])].sort(),
+    sandbox: [...(mm.sandboxEngines || [])].sort(),
+    permissionModes: [...(mm.permissionModes || [])].sort(),
+    outputFormats: [...(mm.outputFormats || [])].sort(),
+    inputFormats: [...(mm.inputFormats || [])].sort(),
+  };
+  return createHash("sha256")
+    .update(JSON.stringify(canonical))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * A behavior matrix row per wire feature — feature × min version × gated field ×
+ * negotiable × description. Consumed by renderProtocolDoc and by a test that a
+ * doc table matches the code.
+ * @returns {Array<{feature:string, minVersion:number, field:string, negotiable:boolean, description:string}>}
+ */
+export function renderBehaviorMatrix(m = CAPABILITY_MANIFEST) {
+  return wireFeaturesOf(m).map((f) => ({
+    feature: f.key,
+    minVersion: Number(f.minVersion) || 1,
+    field: f.field,
+    negotiable: true,
+    description: String(f.description || ""),
+  }));
+}
+
+/**
+ * Render the protocol capability section as Markdown (a generated doc a CI job
+ * diffs against the checked-in copy). Deterministic; ends with a trailing
+ * newline so a byte compare is stable.
+ * @returns {string}
+ */
+export function renderProtocolDoc(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const lines = [];
+  lines.push("# Agent Protocol Capability Manifest (generated)");
+  lines.push("");
+  lines.push(
+    `Protocol version **${mm.protocolVersion}** (negotiates down to **${mm.minProtocolVersion}**).`,
+  );
+  lines.push("");
+  lines.push("## Negotiable wire features");
+  lines.push("");
+  lines.push("| Feature | Min version | Line field | Description |");
+  lines.push("| ------- | ----------- | ---------- | ----------- |");
+  for (const row of renderBehaviorMatrix(mm)) {
+    lines.push(
+      `| \`${row.feature}\` | ${row.minVersion} | \`${row.field}\` | ${row.description} |`,
+    );
+  }
+  lines.push("");
+  lines.push("## Permission modes");
+  lines.push("");
+  lines.push((mm.permissionModes || []).map((x) => `\`${x}\``).join(", "));
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Capability diff for release notes: what changed between a previous and a next
+ * manifest (or a manifest and the current canonical one). Additive vs removed vs
+ * min-version/field changes, plus any protocol-version bump.
+ *
+ * @param {object} prev  a manifest (or its compat fixture)
+ * @param {object} [next=CAPABILITY_MANIFEST]
+ * @returns {{protocolChange:{from:number,to:number}|null,
+ *            addedWireFeatures:string[], removedWireFeatures:string[],
+ *            changedWireFeatures:Array<{feature:string, from:object, to:object}>,
+ *            addedRuntimeFeatures:string[], removedRuntimeFeatures:string[]}}
+ */
+export function diffCapabilities(prev, next = CAPABILITY_MANIFEST) {
+  const wireMap = (m) => {
+    const out = new Map();
+    for (const f of wireFeaturesOf(m)) {
+      out.set(f.key, {
+        field: f.field,
+        minVersion: Number(f.minVersion) || 1,
+      });
+    }
+    return out;
+  };
+  const runtimeSet = (m) => new Set(manifestOr(m).runtimeFeatures || []);
+
+  const p = wireMap(prev);
+  const n = wireMap(next);
+  const addedWireFeatures = [...n.keys()].filter((k) => !p.has(k)).sort();
+  const removedWireFeatures = [...p.keys()].filter((k) => !n.has(k)).sort();
+  const changedWireFeatures = [];
+  for (const [key, nv] of n) {
+    const pv = p.get(key);
+    if (pv && (pv.field !== nv.field || pv.minVersion !== nv.minVersion)) {
+      changedWireFeatures.push({ feature: key, from: pv, to: nv });
+    }
+  }
+
+  const pr = runtimeSet(prev);
+  const nr = runtimeSet(next);
+  const addedRuntimeFeatures = [...nr].filter((k) => !pr.has(k)).sort();
+  const removedRuntimeFeatures = [...pr].filter((k) => !nr.has(k)).sort();
+
+  const pVer = Number(manifestOr(prev).protocolVersion) || 1;
+  const nVer = Number(manifestOr(next).protocolVersion) || 1;
+  const protocolChange = pVer === nVer ? null : { from: pVer, to: nVer };
+
+  return {
+    protocolChange,
+    addedWireFeatures,
+    removedWireFeatures,
+    changedWireFeatures,
+    addedRuntimeFeatures,
+    removedRuntimeFeatures,
+  };
+}

package/src/lib/capability-negotiation.js

@@ -36,31 +36,42 @@
  * fixture __tests__/fixtures/capability-negotiation-cases.json.
  */
 
+import {
+  CAPABILITY_MANIFEST,
+  toProtocolFeatures,
+  toFeatureMinVersion,
+  toFieldGate,
+} from "./capability-manifest.js";
+
 /** The current protocol version the CLI speaks (mirror of PROTOCOL_VERSION). */
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = CAPABILITY_MANIFEST.protocolVersion;
 
 /**
  * The oldest protocol version the CLI can still speak end-to-end (the N-1 in
  * "N / N-1"). At v1 there is no older line shape, so min === current; once v2
  * ships this drops to 1 so a v1-only client negotiates a v1 session.
  */
-export const PROTOCOL_MIN_VERSION = 1;
+export const PROTOCOL_MIN_VERSION = CAPABILITY_MANIFEST.minProtocolVersion;
 
 /**
  * The wire-protocol features subject to negotiation — the additive per-line
  * fields a client may or may not understand. Runtime capabilities (bare,
  * worktree, mcp, …) are NOT negotiated: they change what the CLI can do, not
  * the shape of a line the client must parse.
+ *
+ * P1-9: projected from the single canonical [[capability-manifest.js]] so the
+ * negotiator, `cc agent --capabilities`, the protocol docs and the Java twin can
+ * no longer drift — add a v2 field to the manifest ONCE and it flows here.
  */
-export const PROTOCOL_FEATURES = ["event_seq", "tool_use_id", "trace_id"];
+export const PROTOCOL_FEATURES = toProtocolFeatures();
 
 /**
  * Minimum protocol version a feature requires. Empty today (every current
- * feature is a v1 additive field). When a v2 field lands, add it here so an
- * N-1 (v1) session drops it automatically.
+ * feature is a v1 additive field). When a v2 field lands, bump its manifest
+ * `minVersion` and an N-1 (v1) session drops it automatically.
  * @type {Record<string, number>}
  */
-export const FEATURE_MIN_VERSION = {};
+export const FEATURE_MIN_VERSION = toFeatureMinVersion();
 
 function intOr(value, fallback) {
   const n = Number(value);
@@ -185,12 +196,12 @@ export function negotiateProtocol(server = {}, clientOffer = null, opts = {}) {
   };
 }
 
-/** Feature key → the stream line field it gates. */
-const FEATURE_TO_FIELD = {
-  event_seq: "seq",
-  trace_id: "trace_id",
-  tool_use_id: "tool_use_id",
-};
+/**
+ * Feature key → the stream line field it gates. P1-9: projected from the
+ * canonical [[capability-manifest.js]] so this map can't drift from the
+ * negotiated feature list.
+ */
+const FEATURE_TO_FIELD = toFieldGate();
 
 /**
  * Fold a negotiation result into a live field-gate the emitter reads per line:

package/src/lib/diagnostic-bundle.js

@@ -0,0 +1,230 @@
+/**
+ * De-identified diagnostic bundle assembler + mandatory secret-scan export gate
+ * (IDE gap P1-9 "脱敏诊断包" of CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-
+ * 07-13.md).
+ *
+ * When an IDE session misbehaves, a one-click diagnostic export is the fastest
+ * path to a fix — but a naive dump of "everything about the session" leaks
+ * source, keys and terminal output. The gap doc pins the contract exactly: a
+ * bundle carries version, platform, capability, connection state, redaction
+ * events, trace, reconnect history, and process/port/lockfile/worktree
+ * summaries; it does NOT carry source code, API keys, cookies, full environment
+ * variables, or unpermitted terminal output; and "导出前必须运行 Secret Scan".
+ *
+ * This module assembles that bundle from caller-supplied signals and runs the
+ * §8.1 recall-first scanner ([[secret-scan.js]]) as a fail-closed export gate.
+ * It reuses the canonical capability projection ([[capability-manifest.js]]) so
+ * the bundle never invents a second capability truth.
+ *
+ * Pure: no fs / process / clock / RNG — the caller collects the raw signals
+ * (which processes, which ports, the env object) and this module shapes, de-
+ * identifies and gates them. Timestamps, if any, are passed in.
+ */
+
+import { redactSecrets, scanSecrets, SURFACES } from "./secret-scan.js";
+import { buildCompatFixture } from "./capability-manifest.js";
+import { isSecretEnvName } from "./credential-guard.js";
+
+/** The categories deliberately EXCLUDED from every bundle (never assembled). */
+export const EXCLUDED_BY_DEFAULT = Object.freeze([
+  "source code body",
+  "API keys / tokens",
+  "cookies",
+  "full environment variable values",
+  "unpermitted terminal output",
+]);
+
+/**
+ * Summarize an environment WITHOUT any values: variable NAMES only, with the
+ * secret-named ones flagged (via isSecretEnvName). Honors the contract "默认不
+ * 包含完整环境变量" — a name is metadata, a value may be a credential.
+ * @param {object} env
+ * @returns {{count:number, names:string[], secretNames:string[]}}
+ */
+export function summarizeEnv(env) {
+  if (!env || typeof env !== "object") {
+    return { count: 0, names: [], secretNames: [] };
+  }
+  const names = Object.keys(env).sort();
+  const secretNames = names.filter((n) => isSecretEnvName(n));
+  return { count: names.length, names, secretNames };
+}
+
+/** Recursively redact every string in a value (arrays/objects walked). */
+function deepRedact(value, depth = 0) {
+  if (depth > 64) return value;
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map((v) => deepRedact(v, depth + 1));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value))
+      out[k] = deepRedact(value[k], depth + 1);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Recursively scan a value for any residual secret, returning findings with a
+ * dotted path so the gate can name WHERE a leak survived. Read-only.
+ * @returns {Array<{path:string, category:string}>}
+ */
+export function scanBundleForSecrets(value, path = "", depth = 0) {
+  if (depth > 64) return [];
+  const findings = [];
+  if (typeof value === "string") {
+    for (const f of scanSecrets(value)) {
+      findings.push({ path: path || "(root)", category: f.category });
+    }
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) =>
+      findings.push(...scanBundleForSecrets(v, `${path}[${i}]`, depth + 1)),
+    );
+  } else if (value && typeof value === "object") {
+    for (const k of Object.keys(value)) {
+      findings.push(
+        ...scanBundleForSecrets(value[k], path ? `${path}.${k}` : k, depth + 1),
+      );
+    }
+  }
+  return findings;
+}
+
+const asArray = (v) => (Array.isArray(v) ? v : []);
+const asString = (v) =>
+  typeof v === "string" ? v : v == null ? "" : String(v);
+
+/**
+ * Assemble the diagnostic bundle from caller-supplied signals, de-identifying
+ * as it goes. Free-text fields are secret-redacted; env is reduced to names;
+ * terminal output is included ONLY with explicit permission (and still
+ * redacted). Excluded categories are never assembled in the first place.
+ *
+ * @param {object} input
+ * @param {string} [input.version]
+ * @param {object|string} [input.platform]
+ * @param {object} [input.capability]        defaults to the canonical compat fixture
+ * @param {string} [input.connectionState]
+ * @param {Array}  [input.reconnectHistory]  [{at?, reason?}] — reasons redacted
+ * @param {object} [input.trace]             {traceId, spanCount} summary (no content)
+ * @param {Array}  [input.redactionEvents]   [{surface, category, count}] — what was scrubbed
+ * @param {Array}  [input.processes]         [{pid, name, cpu?}] metadata
+ * @param {Array<number|object>} [input.ports]
+ * @param {Array<string>} [input.lockfiles]
+ * @param {Array}  [input.worktrees]         [{path, branch}]
+ * @param {object} [input.env]               reduced to names only
+ * @param {string} [input.terminalOutput]    included only when opts.includeTerminalOutput
+ * @param {string} [input.notes]
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeTerminalOutput=false]
+ * @returns {object} the assembled (already-redacted) bundle
+ */
+export function buildDiagnosticBundle(input = {}, opts = {}) {
+  const includeTerminal = opts.includeTerminalOutput === true;
+
+  const redactionEvents = asArray(input.redactionEvents)
+    .map((e) => ({
+      surface: SURFACES.includes(e?.surface) ? e.surface : "unknown",
+      category: asString(e?.category),
+      count: Number(e?.count) || 0,
+    }))
+    .filter((e) => e.category);
+
+  const bundle = {
+    schema: "cc-diagnostic-bundle/v1",
+    meta: {
+      version: asString(input.version) || null,
+      platform:
+        input.platform && typeof input.platform === "object"
+          ? input.platform
+          : asString(input.platform) || null,
+      excluded: [...EXCLUDED_BY_DEFAULT],
+    },
+    capability:
+      input.capability && typeof input.capability === "object"
+        ? input.capability
+        : buildCompatFixture(),
+    connection: {
+      state: asString(input.connectionState) || null,
+      reconnectHistory: asArray(input.reconnectHistory).map((r) => ({
+        at: r?.at ?? null,
+        reason: asString(r?.reason),
+      })),
+    },
+    trace: input.trace
+      ? {
+          traceId: asString(input.trace.traceId) || null,
+          spanCount: Number(input.trace.spanCount) || 0,
+        }
+      : null,
+    redactionEvents,
+    runtime: {
+      processes: asArray(input.processes).map((p) => ({
+        pid: p?.pid ?? null,
+        name: asString(p?.name),
+        cpu: p?.cpu ?? null,
+      })),
+      ports: asArray(input.ports).map((p) =>
+        typeof p === "object" && p
+          ? { port: Number(p.port) || null, proto: asString(p.proto) || null }
+          : { port: Number(p) || null, proto: null },
+      ),
+      lockfiles: asArray(input.lockfiles).map((f) => asString(f)),
+      worktrees: asArray(input.worktrees).map((w) => ({
+        path: asString(w?.path),
+        branch: asString(w?.branch) || null,
+      })),
+    },
+    // env is reduced to NAMES only up front (values never enter the bundle).
+    env: summarizeEnv(input.env),
+    notes: input.notes != null ? asString(input.notes) : null,
+  };
+
+  // Terminal output is unpermitted by default: dropped entirely, with a marker
+  // so the reader knows it was withheld (not merely absent).
+  if (includeTerminal && input.terminalOutput != null) {
+    bundle.terminalOutput = asString(input.terminalOutput);
+  } else {
+    bundle.terminalOutput = null;
+    bundle.terminalOutputWithheld = input.terminalOutput != null;
+  }
+
+  // Single de-identification pass over the WHOLE assembled bundle: every string
+  // field is secret-redacted regardless of which section it landed in, so the
+  // export gate is guaranteed clean no matter which signal carried a secret.
+  // env is already values-free, so its names (metadata) pass through untouched.
+  return deepRedact(bundle);
+}
+
+/**
+ * The mandatory pre-export gate ("导出前必须运行 Secret Scan"). Deep-scans the
+ * assembled bundle; fail-closed: if ANY residual secret survives, `ok` is false
+ * and `blocked` is true — the caller must NOT export it. On a clean bundle the
+ * gate returns it ready for export.
+ *
+ * @param {object} bundle  a buildDiagnosticBundle() result
+ * @returns {{ok:boolean, blocked:boolean, findings:Array, bundle:object}}
+ */
+export function secretScanGate(bundle) {
+  const findings = scanBundleForSecrets(bundle);
+  const ok = findings.length === 0;
+  return { ok, blocked: !ok, findings, bundle };
+}
+
+/**
+ * One-call assembly + gate. Builds the de-identified bundle and runs the secret
+ * scan. When the gate is clean, returns the exportable bundle; when it is not
+ * (should never happen given assembly redacts, but defense-in-depth), returns
+ * `ok:false` and the leak locations, and does NOT hand back an exportable body.
+ *
+ * @returns {{ok:boolean, bundle:(object|null), findings:Array}}
+ */
+export function exportDiagnosticBundle(input = {}, opts = {}) {
+  const bundle = buildDiagnosticBundle(input, opts);
+  const gate = secretScanGate(bundle);
+  return {
+    ok: gate.ok,
+    bundle: gate.ok ? bundle : null,
+    findings: gate.findings,
+  };
+}