session-orchestrator 3.16.0

package/scripts/lib/product-repo-detect.mjs

@@ -0,0 +1,121 @@
+/**
+ * product-repo-detect.mjs — #190
+ * Detects product-repo signals in a repo root. Returns scored signal object.
+ *
+ * Stdlib-only, cross-platform, no zx, never throws.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FRAMEWORK_DEPS = [
+  'next',
+  'nuxt',
+  'astro',
+  '@remix-run/react',
+  '@remix-run/node',
+  '@sveltejs/kit',
+];
+
+const PRODUCT_ENV_PATTERNS = [
+  /^SUPABASE_URL=/m,
+  /^SUPABASE_ANON_KEY=/m,
+  /^STRIPE_[A-Z_]+=/m,
+  /^(NEXT_PUBLIC_)?AUTH0_[A-Z_]+=/m,
+  /^(NEXT_PUBLIC_)?CLERK_[A-Z_]+=/m,
+  /^(NEXT_PUBLIC_)?FIREBASE_[A-Z_]+=/m,
+  /^(NEXT_PUBLIC_)?POSTHOG_[A-Z_]+=/m,
+  /^SENTRY_DSN=/m,
+];
+
+const CONTENT_DIRS = ['src/lib/personas', 'src/content', 'content', 'src/data/personas'];
+
+/**
+ * @param {{ repoRoot: string }} opts
+ * @returns {{
+ *   isProductRepo: boolean,
+ *   framework: string | null,
+ *   contentDirs: string[],
+ *   productEnvMatches: string[],
+ *   score: number,
+ *   signals: { framework: boolean, contentDir: boolean, envVars: boolean }
+ * }}
+ */
+export function detectProductRepo({ repoRoot } = {}) {
+  let framework = null;
+  const pkgPath = join(repoRoot, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      const deps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {}),
+      };
+      for (const dep of FRAMEWORK_DEPS) {
+        if (dep in deps) {
+          framework = dep;
+          break;
+        }
+      }
+    } catch {
+      /* malformed package.json — no framework match */
+    }
+  }
+
+  const contentDirs = CONTENT_DIRS.filter((d) => existsSync(join(repoRoot, d)));
+
+  const productEnvMatches = [];
+  const envPath = join(repoRoot, '.env.local.example');
+  if (existsSync(envPath)) {
+    try {
+      const content = readFileSync(envPath, 'utf8');
+      for (const re of PRODUCT_ENV_PATTERNS) {
+        const m = content.match(re);
+        if (m) productEnvMatches.push(m[0].split('=')[0]);
+      }
+    } catch {
+      /* unreadable — ignore */
+    }
+  }
+
+  const signals = {
+    framework: framework !== null,
+    contentDir: contentDirs.length > 0,
+    envVars: productEnvMatches.length > 0,
+  };
+  const score =
+    (signals.framework ? 2 : 0) + (signals.contentDir ? 1 : 0) + (signals.envVars ? 2 : 0);
+  return {
+    isProductRepo: score >= 2,
+    framework,
+    contentDirs,
+    productEnvMatches,
+    score,
+    signals,
+  };
+}
+
+/**
+ * Check whether CLAUDE.md (or AGENTS.md) already has a `vault:` key in Session Config.
+ * @param {string} configFilePath
+ * @returns {boolean}
+ */
+export function hasVaultConfig(configFilePath) {
+  if (!existsSync(configFilePath)) return false;
+  let text;
+  try {
+    text = readFileSync(configFilePath, 'utf8');
+  } catch {
+    return false;
+  }
+  // Scan only within the Session Config section (bounded by the next ## heading).
+  const startMatch = text.match(/^## Session Config[ \t]*(?:\r?\n|$)/m);
+  if (!startMatch || startMatch.index === undefined) return false;
+  const afterBlock = text.slice(startMatch.index + startMatch[0].length);
+  const nextHeadingMatch = afterBlock.match(/^## /m);
+  const blockContent = nextHeadingMatch
+    ? afterBlock.slice(0, nextHeadingMatch.index)
+    : afterBlock;
+  return /^\s*vault\s*:/m.test(blockContent);
+}

package/scripts/lib/profiles/registry.mjs

@@ -0,0 +1,176 @@
+/**
+ * profiles/registry.mjs — Pure loader for test profile registry.
+ *
+ * Reads `.orchestrator/policy/test-profiles.json`, validates each entry
+ * against profileRegistrySchema, and exposes pure helper accessors.
+ * DI-friendly: accepts an `fs` seam so callers can inject mock file systems.
+ *
+ * Issue: #383 (part 3) — /test command: profile registry schema + seed profiles
+ *
+ * Exports:
+ *   loadProfiles({ profilesPath?, fs? })  → Promise<{ok, profiles?, error?}>
+ *   listProfileNames(profiles)            → string[]
+ *   getProfile(profiles, name)            → {ok, profile?, error?}
+ *   validateProfile(entry)                → {ok, value?, error?}
+ *   ProfileRegistryError
+ */
+
+import fsPromises from 'node:fs/promises';
+import { profileEntrySchema, profileRegistrySchema } from './schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Default path
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PROFILES_PATH = '.orchestrator/policy/test-profiles.json';
+
+// ---------------------------------------------------------------------------
+// ProfileRegistryError
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed error for profile registry failures.
+ * Codes: 'FILE_NOT_FOUND' | 'PARSE_ERROR' | 'SCHEMA_INVALID' | 'UNKNOWN_PROFILE'
+ */
+export class ProfileRegistryError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProfileRegistryError';
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// loadProfiles
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and validate the profiles registry from disk.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.profilesPath] - path to the JSON registry file;
+ *   defaults to `.orchestrator/policy/test-profiles.json`
+ * @param {{ readFile: Function }} [opts.fs] - injected fs/promises (DI seam);
+ *   defaults to the real `fs/promises`
+ * @returns {Promise<{ ok: true, profiles: Record<string, object> } | { ok: false, error: ProfileRegistryError }>}
+ */
+export async function loadProfiles({ profilesPath, fs: fsImpl } = {}) {
+  const filePath = profilesPath ?? DEFAULT_PROFILES_PATH;
+  const fsRead = fsImpl ?? fsPromises;
+
+  let raw;
+  try {
+    raw = await fsRead.readFile(filePath, 'utf8');
+  } catch (err) {
+    const code = err && err.code === 'ENOENT' ? 'FILE_NOT_FOUND' : 'PARSE_ERROR';
+    return {
+      ok: false,
+      error: new ProfileRegistryError(code, `Cannot read profiles file '${filePath}': ${err.message}`),
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      ok: false,
+      error: new ProfileRegistryError('PARSE_ERROR', `Invalid JSON in '${filePath}': ${err.message}`),
+    };
+  }
+
+  const result = profileRegistrySchema.safeParse(parsed);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: new ProfileRegistryError(
+        'SCHEMA_INVALID',
+        `Profile registry schema validation failed: ${result.error.message}`,
+      ),
+    };
+  }
+
+  return { ok: true, profiles: result.data };
+}
+
+// ---------------------------------------------------------------------------
+// listProfileNames
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the sorted list of profile names in the registry.
+ *
+ * @param {Record<string, object>} profiles
+ * @returns {string[]}
+ */
+export function listProfileNames(profiles) {
+  if (profiles === null || typeof profiles !== 'object' || Array.isArray(profiles)) {
+    return [];
+  }
+  return Object.keys(profiles).sort();
+}
+
+// ---------------------------------------------------------------------------
+// getProfile
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve a single profile by name.
+ *
+ * @param {Record<string, object>} profiles
+ * @param {string} name
+ * @returns {{ ok: true, profile: object } | { ok: false, error: ProfileRegistryError }}
+ */
+export function getProfile(profiles, name) {
+  if (profiles === null || typeof profiles !== 'object' || Array.isArray(profiles)) {
+    return {
+      ok: false,
+      error: new ProfileRegistryError('SCHEMA_INVALID', 'profiles must be a non-null object'),
+    };
+  }
+
+  if (typeof name !== 'string' || name.length === 0) {
+    return {
+      ok: false,
+      error: new ProfileRegistryError('UNKNOWN_PROFILE', 'profile name must be a non-empty string'),
+    };
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(profiles, name)) {
+    const available = Object.keys(profiles).sort().join(', ') || '(none)';
+    return {
+      ok: false,
+      error: new ProfileRegistryError(
+        'UNKNOWN_PROFILE',
+        `Profile '${name}' not found. Available: ${available}`,
+      ),
+    };
+  }
+
+  return { ok: true, profile: profiles[name] };
+}
+
+// ---------------------------------------------------------------------------
+// validateProfile
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a raw profile entry object against the schema.
+ *
+ * @param {unknown} entry
+ * @returns {{ ok: true, value: object } | { ok: false, error: ProfileRegistryError }}
+ */
+export function validateProfile(entry) {
+  const result = profileEntrySchema.safeParse(entry);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: new ProfileRegistryError('SCHEMA_INVALID', result.error.message),
+    };
+  }
+  return { ok: true, value: result.data };
+}

package/scripts/lib/profiles/schema.mjs

@@ -0,0 +1,209 @@
+/**
+ * profiles/schema.mjs — Validation schemas for test profile entries.
+ *
+ * Zod was not available in this project's node_modules at implementation time
+ * (issue #383 part 3), so validation is implemented as a hand-rolled validator
+ * that mirrors the Zod schema contract specified in the task brief.
+ *
+ * Exports:
+ *   profileEntrySchema  — validator for a single profile entry
+ *   profileRegistrySchema — validator for a full profiles record
+ *
+ * Both exports expose a `.safeParse(value)` method returning
+ * `{ success: true, data }` or `{ success: false, error: ZodLike }`.
+ */
+
+import { validatePathInsideProject } from '../path-utils.mjs';
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+const VALID_DRIVERS = new Set(['playwright', 'peekaboo']);
+const VALID_MODES = new Set(['headless', 'headed']);
+const NAME_REGEX = /^[a-z0-9-]+$/;
+
+/**
+ * Build a ZodLike error object matching Zod's safeParse error shape.
+ * @param {string} message
+ * @returns {{ issues: Array<{message: string}> }}
+ */
+function makeError(message) {
+  return { issues: [{ message }], message };
+}
+
+/**
+ * Validate a single profile entry and return the parsed (defaulted) value.
+ * Mirrors the Zod schema:
+ *
+ *   name:            string, matches /^[a-z0-9-]+$/, min 1, max 50
+ *   target:          string | null | undefined
+ *   driver:          'playwright' | 'peekaboo'
+ *   mode:            'headless' | 'headed', default 'headless'
+ *   rubric:          string, default 'skills/test-runner/rubric-v1.md'
+ *   checks:          string[] | undefined
+ *   tags:            string[] | undefined
+ *   rubric_features: string[] | undefined
+ *   timeout_ms:      positive integer, default 120000
+ *   description:     string | undefined
+ *
+ * @param {unknown} value
+ * @returns {{ success: true, data: object } | { success: false, error: object }}
+ */
+function parseProfileEntry(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { success: false, error: makeError('profile entry must be a non-null object') };
+  }
+
+  const v = /** @type {Record<string, unknown>} */ (value);
+
+  // name
+  if (typeof v.name !== 'string') {
+    return { success: false, error: makeError('name must be a string') };
+  }
+  if (v.name.length < 1 || v.name.length > 50) {
+    return { success: false, error: makeError('name must be between 1 and 50 characters') };
+  }
+  if (!NAME_REGEX.test(v.name)) {
+    return { success: false, error: makeError('name must match /^[a-z0-9-]+$/') };
+  }
+
+  // target
+  if (v.target !== undefined && v.target !== null && typeof v.target !== 'string') {
+    return { success: false, error: makeError('target must be a string, null, or undefined') };
+  }
+
+  // driver
+  if (!VALID_DRIVERS.has(/** @type {string} */ (v.driver))) {
+    return {
+      success: false,
+      error: makeError(`driver must be one of: ${[...VALID_DRIVERS].join(', ')}`),
+    };
+  }
+
+  // mode (with default)
+  const mode = v.mode === undefined ? 'headless' : v.mode;
+  if (!VALID_MODES.has(/** @type {string} */ (mode))) {
+    return {
+      success: false,
+      error: makeError(`mode must be one of: ${[...VALID_MODES].join(', ')}`),
+    };
+  }
+
+  // rubric (with default)
+  const rubric = v.rubric === undefined ? 'skills/test-runner/rubric-v1.md' : v.rubric;
+  if (typeof rubric !== 'string') {
+    return { success: false, error: makeError('rubric must be a string') };
+  }
+  // SEC-IR-LOW-3 + SEC-Q2-LOW-1: rubric must stay within project root; also reject symlink-escape (CWE-23)
+  // Two-phase guard (Phase 1 lexical + Phase 2 realpath-when-exists) delegated to validatePathInsideProject.
+  const projectRoot = process.cwd();
+  const rubricGuard = validatePathInsideProject(rubric, projectRoot);
+  if (!rubricGuard.ok) {
+    return { success: false, error: makeError('rubric path escapes project root') };
+  }
+
+  // checks (optional array of strings)
+  if (v.checks !== undefined) {
+    if (!Array.isArray(v.checks) || v.checks.some((c) => typeof c !== 'string')) {
+      return { success: false, error: makeError('checks must be an array of strings') };
+    }
+  }
+
+  // tags (optional array of strings)
+  if (v.tags !== undefined) {
+    if (!Array.isArray(v.tags) || v.tags.some((t) => typeof t !== 'string')) {
+      return { success: false, error: makeError('tags must be an array of strings') };
+    }
+  }
+
+  // rubric_features (optional array of strings)
+  if (v.rubric_features !== undefined) {
+    if (!Array.isArray(v.rubric_features) || v.rubric_features.some((f) => typeof f !== 'string')) {
+      return { success: false, error: makeError('rubric_features must be an array of strings') };
+    }
+  }
+
+  // timeout_ms (positive integer, with default)
+  const timeout_ms = v.timeout_ms === undefined ? 120000 : v.timeout_ms;
+  if (
+    typeof timeout_ms !== 'number' ||
+    !Number.isInteger(timeout_ms) ||
+    timeout_ms <= 0
+  ) {
+    return { success: false, error: makeError('timeout_ms must be a positive integer') };
+  }
+  // SEC-PD-LOW-3: V8 setTimeout uses int32 — values > 2^31-1 silently overflow to immediate-fire.
+  // Practical ceiling is 1 hour for test profiles.
+  const MAX_TIMEOUT_MS = 3_600_000;  // 1 hour
+  if (timeout_ms > MAX_TIMEOUT_MS) {
+    return { success: false, error: makeError(`timeout_ms must not exceed ${MAX_TIMEOUT_MS} (1 hour)`) };
+  }
+
+  // description (optional string)
+  if (v.description !== undefined && typeof v.description !== 'string') {
+    return { success: false, error: makeError('description must be a string') };
+  }
+
+  // SEC-Q2-LOW-2 (deep-5): store resolved rubric path (realPath when exists, else lexicalPath)
+  // to defeat post-validation symlink-swap TOCTOU. Mirrors the #405 pattern in config/test.mjs.
+  const resolvedRubric = rubricGuard.realPath ?? rubricGuard.lexicalPath;
+  /** @type {Record<string, unknown>} */
+  const data = {
+    name: v.name,
+    driver: v.driver,
+    mode,
+    rubric: resolvedRubric,
+    timeout_ms,
+  };
+
+  if (v.target !== undefined) data.target = v.target;
+  if (v.checks !== undefined) data.checks = v.checks;
+  if (v.tags !== undefined) data.tags = v.tags;
+  if (v.rubric_features !== undefined) data.rubric_features = v.rubric_features;
+  if (v.description !== undefined) data.description = v.description;
+
+  return { success: true, data };
+}
+
+/**
+ * Validate a full profiles registry (Record<string, profileEntry>).
+ *
+ * @param {unknown} value
+ * @returns {{ success: true, data: Record<string, object> } | { success: false, error: object }}
+ */
+function parseProfileRegistry(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { success: false, error: makeError('profile registry must be a non-null object') };
+  }
+
+  /** @type {Record<string, object>} */
+  const data = {};
+
+  for (const [key, entry] of Object.entries(/** @type {Record<string, unknown>} */ (value))) {
+    const result = parseProfileEntry(entry);
+    if (!result.success) {
+      return {
+        success: false,
+        error: makeError(`profile '${key}': ${result.error.message}`),
+      };
+    }
+    data[key] = result.data;
+  }
+
+  return { success: true, data };
+}
+
+// ---------------------------------------------------------------------------
+// Exports — Zod-compatible safeParse interface
+// ---------------------------------------------------------------------------
+
+export const profileEntrySchema = {
+  /** @param {unknown} value */
+  safeParse: (value) => parseProfileEntry(value),
+};
+
+export const profileRegistrySchema = {
+  /** @param {unknown} value */
+  safeParse: (value) => parseProfileRegistry(value),
+};

package/scripts/lib/qg-command-drift-banner.mjs

@@ -0,0 +1,88 @@
+/**
+ * qg-command-drift-banner.mjs — session-start banner probe for *-command drift detection.
+ *
+ * Detects when CLAUDE.md Session Config `lint-command` / `typecheck-command` /
+ * `test-command` values deviate from project defaults. Returns a structured
+ * banner object `{severity, message}` (or null for silent no-op), mirroring
+ * the contract used by `checkVaultStaleness` and other session-start probes.
+ *
+ * Used by session-start Phase 4 alongside other freshness/drift probes.
+ *
+ * Config-read path: this module reads Session Config exclusively via
+ * `loadCommandsFromSessionConfig` from `./quality-gate.mjs`. That helper
+ * returns a partial object (missing keys are absent — no default substitution),
+ * which means absent `*-command` keys cannot trigger spurious drift against
+ * `PROJECT_DEFAULTS`. Drift is only reported when a value is explicitly set
+ * AND differs from the corresponding `PROJECT_DEFAULTS` entry.
+ *
+ * Cross-references:
+ * - .claude/rules/quality-gates-autofix.md § Session Config Command Injection
+ * - scripts/lib/quality-gate.mjs `loadCommandsFromSessionConfig()`
+ *
+ * @see #525 (Pattern 4 Auto-Fix-Loop residuals)
+ * @see #526 (Pattern 4 banner ecosystem coherence)
+ */
+
+import { loadCommandsFromSessionConfig } from './quality-gate.mjs';
+
+/**
+ * Default *-command values for the session-orchestrator plugin.
+ * Source of truth: CLAUDE.md `## Session Config` block as shipped.
+ *
+ * Override this constant only when the canonical defaults change in CLAUDE.md.
+ */
+export const PROJECT_DEFAULTS = Object.freeze({
+  lint: 'npm run lint',
+  typecheck: 'npm run typecheck',
+  test: 'npm test',
+});
+
+/**
+ * Check for *-command drift.
+ *
+ * Reads Session Config from CLAUDE.md (or AGENTS.md) in `repoRoot` via
+ * `loadCommandsFromSessionConfig` and compares any resolved `lint`,
+ * `typecheck`, and `test` values against PROJECT_DEFAULTS. Returns null
+ * when no drift is detected, or when the config-read returns no recognised
+ * `*-command` keys at all (graceful no-op).
+ *
+ * Important: missing keys do NOT trigger drift. Only explicit overrides
+ * that differ from PROJECT_DEFAULTS produce a banner.
+ *
+ * Marked `async` for backward compatibility with existing callers that
+ * `await` the result; internally the helper is synchronous.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — project root (defaults to process.cwd()).
+ * @returns {Promise<null | {severity: 'warn', message: string}>}
+ */
+export async function checkQgCommandDrift(opts = {}) {
+  const repoRoot = opts.repoRoot ?? process.cwd();
+
+  let cfg;
+  try {
+    cfg = loadCommandsFromSessionConfig(repoRoot);
+  } catch {
+    return null; // graceful no-op on config load failure
+  }
+  if (!cfg || typeof cfg !== 'object') return null;
+
+  const drifts = [];
+  for (const [key, defaultVal] of Object.entries(PROJECT_DEFAULTS)) {
+    const currentVal = cfg[key];
+    // Skip the comparison when the key is absent — missing keys cannot drift.
+    if (typeof currentVal !== 'string' || !currentVal.trim()) continue;
+    if (currentVal !== defaultVal) {
+      drifts.push(`  ${key}-command: "${currentVal}" ← deviates from default "${defaultVal}"`);
+    }
+  }
+  if (drifts.length === 0) return null;
+
+  const message = [
+    '⚠ Session Config drift (*-command keys):',
+    ...drifts,
+    'Verify the overrides are intentional. See .claude/rules/quality-gates-autofix.md § Session Config Command Injection for the RCE-equivalent trust-model.',
+  ].join('\n');
+
+  return { severity: 'warn', message };
+}

package/scripts/lib/quality-gate/diagnostics.mjs

@@ -0,0 +1,92 @@
+/**
+ * scripts/lib/quality-gate/diagnostics.mjs
+ *
+ * Diagnostics-bundle redaction helpers for the auto-fix loop (#521 + #525).
+ * Strips token-shaped strings, secret env-var values, sensitive HTTP headers,
+ * and user-path identifiers before persisting the bundle to disk.
+ *
+ * Extracted from scripts/lib/quality-gate.mjs in #525 to give W4 tests a clean
+ * module surface and isolate redaction concerns from gate-runner concerns.
+ *
+ * @see .claude/rules/quality-gates-autofix.md § Session Config Command Injection
+ * @see scripts/lib/quality-gate.mjs (consumer — writes diagnostics bundle)
+ */
+
+/**
+ * Token-shaped patterns that may appear in diagnostics output (gate command
+ * output lines, corrective_context entries, etc.).  Replace each match with a
+ * placeholder so bundles are safe to attach to issue trackers or share with
+ * support.
+ *
+ * Ordering: more-specific patterns first (long prefixes before short ones) to
+ * prevent partial overlap.
+ */
+const REDACTION_PATTERNS = [
+  [/ghp_[A-Za-z0-9]{36}/g, '***GITHUB_PAT***'],
+  [/glpat-[A-Za-z0-9_-]{20,}/g, '***GITLAB_PAT***'],
+  [/npm_[A-Za-z0-9]{36,}/g, '***NPM_TOKEN***'],
+  [/AKIA[0-9A-Z]{16}/g, '***AWS_ACCESS_KEY***'],
+  [/sk-ant-[A-Za-z0-9_-]{20,}/g, '***ANTHROPIC_KEY***'],
+  [/sbp_[A-Za-z0-9_-]{40,}/g, '***SUPABASE_TOKEN***'],
+  [/sk-[A-Za-z0-9]{40,}/g, '***OPENAI_KEY***'],
+  [/xox[bpae]-[A-Za-z0-9-]+/g, '***SLACK_TOKEN***'],
+  [/sk_(live|test)_[A-Za-z0-9]{24,}/g, '***STRIPE_KEY***'],
+  [/pk_(live|test)_[A-Za-z0-9]{24,}/g, '***STRIPE_PK***'],
+  [/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '***JWT***'],
+  [/https:\/\/(discord(app)?\.com|hooks\.slack\.com)\/[^\s"']+/g, '***WEBHOOK_URL***'],
+  [/Bearer\s+[A-Za-z0-9._-]+/gi, 'Bearer ***REDACTED***'],
+  [/Authorization:\s*Basic\s+[A-Za-z0-9+/=]+/gi, 'Authorization: Basic ***REDACTED***'],
+  [/Cookie:\s*[^\n\r]+/gi, 'Cookie: ***REDACTED***'],
+  [/\/Users\/[^/\s"']+\//g, '/Users/<redacted>/'],
+  [/\/home\/[^/\s"']+\//g, '/home/<redacted>/'],
+];
+
+/**
+ * Matches env-var names that are semantically secret-bearing.
+ * Keys matching this pattern have their VALUES redacted (the key name is kept
+ * so operators can still audit which secret categories were present).
+ */
+const SECRET_ENV_NAME_RE = /^([A-Z][A-Z0-9_]*(?:_TOKEN|_KEY|_SECRET|_PASSWORD|_CREDENTIAL[A-Z_]*))$/;
+
+/**
+ * Redact secrets, env-var values, and user-specific paths from a diagnostics
+ * bundle before writing it to disk.
+ *
+ * Applies two passes:
+ *  1. Strip values of env-var keys that match SECRET_ENV_NAME_RE.
+ *  2. Serialize the bundle to JSON, apply REDACTION_PATTERNS against the full
+ *     JSON string, then parse back.  This catches token-shaped strings nested
+ *     anywhere in the object graph (gate output lines, corrective_context
+ *     entries, error messages) without requiring a recursive string-walker.
+ *
+ * Never throws — on any error the original bundle is returned so the write
+ * still completes (a partially-unredacted bundle is better than a lost bundle).
+ *
+ * @param {object} bundle
+ * @returns {object}
+ */
+export function redactDiagnosticsBundle(bundle) {
+  try {
+    // Deep-clone via JSON round-trip so we never mutate the caller's object.
+    const copy = JSON.parse(JSON.stringify(bundle ?? {}));
+
+    // Pass 1 — redact secret-bearing env-var values.
+    if (copy.env && typeof copy.env === 'object') {
+      for (const key of Object.keys(copy.env)) {
+        if (SECRET_ENV_NAME_RE.test(key)) {
+          copy.env[key] = '***REDACTED***';
+        }
+      }
+    }
+
+    // Pass 2 — regex-replace token/path patterns over the full JSON string.
+    let serialized = JSON.stringify(copy);
+    for (const [re, replacement] of REDACTION_PATTERNS) {
+      serialized = serialized.replace(re, replacement);
+    }
+    return JSON.parse(serialized);
+  } catch {
+    // Return unredacted rather than losing the bundle entirely.
+    return bundle ?? {};
+  }
+}