@0dai-dev/cli 4.3.6 → 4.3.7

package/lib/commands/doctor.js

@@ -1,12 +1,28 @@
 "use strict";
 const shared = require("../shared");
-const { log, T, R, D, fs, path, spawnSync, findRepoScript, SUPPORTED_CLIS, recordExperienceEvent } = shared;
+const {
+  log,
+  T,
+  R,
+  D,
+  fs,
+  path,
+  spawnSync,
+  findRepoScript,
+  repoScriptCandidates,
+  resolvePythonScript,
+  SUPPORTED_CLIS,
+  cliDisplayName,
+  recordExperienceEvent,
+} = shared;
 
 const LOCAL_LAYER_CHECKS = Object.freeze([
   ["ai/VERSION", "ai/VERSION", "error"],
   ["ai/manifest/project.yaml", "ai/manifest/project.yaml", "error"],
   ["ai/manifest/discovery.json", "ai/manifest/discovery.json", "warn"],
   ["ai/manifest/commands.yaml", "ai/manifest/commands.yaml", "warn"],
+  ["ai/manifest/current_state.json", "ai/manifest/current_state.json", "warn"],
+  ["ai/manifest/current_task.json", "ai/manifest/current_task.json", "warn"],
   [".claude/settings.json", ".claude/settings.json", "warn"],
   ["AGENTS.md", "AGENTS.md", "warn"],
 ]);
@@ -25,7 +41,7 @@ function nodePtyProbe() {
       name: "node-pty",
       present: false,
       sev: "warn",
-      hint: "install node-pty for terminal sessions: npm i -g node-pty",
+      hint: "install node-pty in the 0dai CLI package for terminal sessions",
     };
   }
 }
@@ -48,6 +64,149 @@ function ghostAuthStatus(home = process.env.HOME || process.env.USERPROFILE || "
   };
 }
 
+function _ghProbeEnv(env, configDir = "", unsetConfigDir = false) {
+  const next = { ...process.env, ...(env || {}) };
+  if (unsetConfigDir) delete next.GH_CONFIG_DIR;
+  else if (configDir) next.GH_CONFIG_DIR = configDir;
+  return next;
+}
+
+function _probeGhIdentity(spec, options = {}) {
+  const runner = options.spawnSync || spawnSync;
+  const env = options.env || process.env;
+  const timeout = options.timeout || 5000;
+  const configDir = spec.configDir || "";
+  const expectedLogin = spec.expectedLogin || "";
+  const required = !!spec.required;
+  const check = {
+    name: spec.name,
+    role: spec.role,
+    ok: false,
+    sev: "info",
+    status: "unknown",
+    login: "",
+    expected_login: expectedLogin,
+    config_dir: configDir,
+    configured: true,
+    hint: "",
+  };
+
+  if (configDir && !fs.existsSync(configDir)) {
+    check.configured = false;
+    check.status = "missing_config";
+    check.sev = required ? "warn" : "info";
+    check.hint = required
+      ? `configured gh identity dir is missing: ${configDir}`
+      : `not configured: ${configDir}`;
+    return check;
+  }
+
+  let result;
+  try {
+    result = runner("gh", ["api", "user", "--jq", ".login"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+      timeout,
+      env: _ghProbeEnv(env, configDir, !!spec.unsetConfigDir),
+    });
+  } catch (error) {
+    check.status = "probe_failed";
+    check.sev = configDir || required ? "warn" : "info";
+    check.hint = String(error && error.message ? error.message : error).split("\n").slice(-1)[0] || "gh probe failed";
+    return check;
+  }
+
+  if (result && result.error && result.error.code === "ENOENT") {
+    check.status = "gh_missing";
+    check.sev = configDir || required ? "warn" : "info";
+    check.hint = "gh CLI not installed";
+    return check;
+  }
+
+  const exitCode = result && typeof result.status === "number" ? result.status : null;
+  const login = String((result && result.stdout) || "").trim();
+  if (exitCode !== 0 || !login) {
+    check.status = "not_authenticated";
+    check.sev = configDir || required ? "warn" : "info";
+    check.hint = configDir
+      ? `token invalid or expired for ${configDir}; re-auth ${expectedLogin || "the configured review identity"} with gh`
+      : "default gh CLI identity is not authenticated; run: gh auth login";
+    if (exitCode !== null) check.exit_code = exitCode;
+    return check;
+  }
+
+  check.login = login;
+  if (expectedLogin && login !== expectedLogin) {
+    check.status = "login_mismatch";
+    check.sev = "warn";
+    check.hint = `resolves to '${login}', expected '${expectedLogin}'; re-auth the fenced gh config dir`;
+    return check;
+  }
+
+  check.ok = true;
+  check.sev = "ok";
+  check.status = "ok";
+  check.hint = expectedLogin
+    ? `authenticated as expected ${expectedLogin}`
+    : `authenticated as ${login}`;
+  return check;
+}
+
+function collectGitHubIdentityPayload(target, options = {}) {
+  const env = options.env || process.env;
+  const primaryDir = env.OPERATOR_GH_REVIEW_CONFIG_DIR || path.join(target, ".0dai", "gh-lead-0dai-review");
+  const primaryLogin = env.OPERATOR_GH_REVIEW_EXPECTED_LOGIN || "pq1-dev";
+  const fallbackDir = env.OPERATOR_GH_REVIEW_FALLBACK_CONFIG_DIR || "";
+  const fallbackLogin = env.OPERATOR_GH_REVIEW_FALLBACK_LOGIN || "";
+  const legacyPq1Dir = "/root/.config/gh-pq1";
+  const specs = [
+    {
+      role: "default",
+      name: "default gh identity",
+      unsetConfigDir: true,
+    },
+  ];
+  const seenDirs = new Set();
+
+  function addConfig(role, name, configDir, expectedLogin, required = false) {
+    if (!configDir || seenDirs.has(configDir)) return;
+    seenDirs.add(configDir);
+    specs.push({ role, name, configDir, expectedLogin, required });
+  }
+
+  addConfig(
+    "env-gh-config",
+    "GH_CONFIG_DIR identity",
+    env.GH_CONFIG_DIR || "",
+    env.GH_CONFIG_DIR === legacyPq1Dir ? "pq1-dev" : "",
+    true,
+  );
+  addConfig(
+    "review-primary",
+    "pq1-dev review identity",
+    primaryDir,
+    primaryLogin,
+    Boolean(env.OPERATOR_GH_REVIEW_CONFIG_DIR),
+  );
+  if (fallbackDir || fallbackLogin) {
+    addConfig("review-fallback", "fallback review identity", fallbackDir, fallbackLogin, true);
+  }
+  if (legacyPq1Dir !== primaryDir && (env.GH_CONFIG_DIR === legacyPq1Dir || fs.existsSync(legacyPq1Dir))) {
+    addConfig("review-legacy-pq1", "legacy pq1-dev review identity", legacyPq1Dir, "pq1-dev", true);
+  }
+
+  const checks = specs.map((spec) => _probeGhIdentity(spec, options));
+  const warnings = checks.filter((check) => check.sev === "warn" && !check.ok).length;
+  return {
+    status: warnings ? "warn" : "ok",
+    warnings,
+    checks,
+    next_step: warnings
+      ? "Rotate or remove stale fenced gh review credentials; default gh identity is separate from pq1-dev review identity."
+      : "GitHub identity diagnostics are non-blocking.",
+  };
+}
+
 function collectLayerChecks(target) {
   return LOCAL_LAYER_CHECKS.map(([name, relPath, missingSev]) => {
     const fullPath = path.join(target, relPath);
@@ -61,19 +220,290 @@ function collectLayerChecks(target) {
   });
 }
 
-function collectDoctorPayload(target) {
+function parseReleaseVersion(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return match.slice(1, 4).map((part) => Number(part));
+}
+
+function compareReleaseVersions(a, b) {
+  const left = parseReleaseVersion(a);
+  const right = parseReleaseVersion(b);
+  if (!left || !right) return null;
+  return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
+}
+
+function collectLayerVersionFreshness(target, cliVersion = shared.VERSION) {
+  const versionPath = path.join(target, "ai", "VERSION");
+  let current = "";
+  try { current = fs.readFileSync(versionPath, "utf8").trim(); } catch {}
+  const cmp = compareReleaseVersions(current, cliVersion);
+  if (!current) {
+    return {
+      status: "missing",
+      ok: false,
+      sev: "error",
+      current: "",
+      expected: cliVersion,
+      hint: `missing: ${versionPath}`,
+    };
+  }
+  if (cmp === null) {
+    return {
+      status: "unknown",
+      ok: true,
+      sev: "info",
+      current,
+      expected: cliVersion,
+      hint: "ai/VERSION is not a release semver; skipping freshness check",
+    };
+  }
+  if (cmp < 0) {
+    return {
+      status: "stale",
+      ok: false,
+      sev: "warn",
+      current,
+      expected: cliVersion,
+      hint: `ai/VERSION stale: ${current} -> ${cliVersion}; run: 0dai sync`,
+    };
+  }
+  if (cmp > 0) {
+    return {
+      status: "newer",
+      ok: true,
+      sev: "info",
+      current,
+      expected: cliVersion,
+      hint: `project layer ${current} is newer than CLI ${cliVersion}; not recommending sync`,
+    };
+  }
   return {
+    status: "ok",
+    ok: true,
+    sev: "ok",
+    current,
+    expected: cliVersion,
+    hint: "ai/VERSION matches installed CLI",
+  };
+}
+
+function collectDriftPayload(target, options = {}) {
+  const scriptName = "drift_detector.py";
+  const candidates = options.candidates || repoScriptCandidates(target, scriptName);
+  const findScript = options.findRepoScript || resolvePythonScript;
+  const script = Object.prototype.hasOwnProperty.call(options, "script")
+    ? options.script
+    : findScript(target, scriptName);
+
+  if (!script) {
+    return {
+      status: "unavailable",
+      available: false,
+      helper: scriptName,
+      reason: "helper_not_found",
+      message: "drift detector unavailable in this environment",
+      checked_paths: candidates,
+      next_step: "Run from a 0dai repo checkout or sync/install the managed project helper scripts, then rerun: 0dai doctor --drift --json",
+    };
+  }
+
+  const runner = options.spawnSync || spawnSync;
+  const result = runner("python3", [script, "report", "--target", target], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    timeout: options.timeout || 15000,
+  });
+  const exitCode = typeof result.status === "number" ? result.status : null;
+  const stdout = String(result.stdout || "").trim();
+  const stderr = String(result.stderr || "").trim();
+  return {
+    status: exitCode === 0 ? "ok" : "error",
+    available: true,
+    helper: scriptName,
+    script,
+    command: `python3 ${script} report --target ${target}`,
+    exit_code: exitCode,
+    report: stdout,
+    ...(stderr ? { stderr } : {}),
+  };
+}
+
+function _detectAgentKind(env = process.env) {
+  return env.ODAI_AGENT_KIND || env.ODAI_AGENT || env.CLAUDE_AGENT_KIND || "default";
+}
+
+function _readMcpConfigSummary(target) {
+  const configPath = path.join(target, ".mcp.json");
+  const summary = {
+    path: "",
+    configured: false,
+    servers: [],
+    odai_servers: [],
+  };
+  if (!fs.existsSync(configPath)) return summary;
+  summary.path = configPath;
+  try {
+    const data = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const servers = data && data.mcpServers && typeof data.mcpServers === "object"
+      ? Object.keys(data.mcpServers)
+      : [];
+    summary.servers = servers;
+    summary.odai_servers = servers.filter((name) => name.toLowerCase().includes("0dai"));
+    summary.configured = summary.odai_servers.length > 0;
+  } catch {
+    summary.configured = false;
+  }
+  return summary;
+}
+
+function _exposureNextStep(payload) {
+  if (!payload.configured) return "run: 0dai sync --target .";
+  if (payload.status === "green") return "0dai MCP tools exposed";
+  const agent = String(payload.agent || "agent").toLowerCase();
+  const reconnect = agent.includes("codex")
+    ? "restart/reconnect Codex CLI"
+    : agent.includes("claude")
+      ? "restart/reconnect Claude Code"
+      : "restart/reconnect active agent CLI";
+  if (payload.status === "yellow" || payload.status === "red") {
+    return `${reconnect}; fallback: 0dai mcp doctor --json`;
+  }
+  return `set ODAI_EXPOSED_MCP_TOOLS; fallback: 0dai mcp doctor --json`;
+}
+
+function collectMcpExposurePayload(target, options = {}) {
+  const env = options.env || process.env;
+  const agent = options.agent || _detectAgentKind(env);
+  const config = _readMcpConfigSummary(target);
+  const scriptName = "mcp_exposure_check.py";
+  const script = Object.prototype.hasOwnProperty.call(options, "script")
+    ? options.script
+    : resolvePythonScript(target, scriptName);
+  const observedRaw = String(env.ODAI_EXPOSED_MCP_TOOLS || "").trim();
+  const payload = {
+    agent,
+    status: "unknown",
+    configured: config.configured,
+    config_path: config.path,
+    servers: config.servers,
+    odai_servers: config.odai_servers,
+    observed_count: 0,
+    expected_tool_count: 0,
+    missing_required: [],
+    missing_recommended: [],
+    helper: script || "",
+    reason: observedRaw ? "" : "runtime_tool_list_not_reported",
+  };
+
+  if (!script) {
+    payload.reason = "helper_not_found";
+    payload.next_step = _exposureNextStep(payload);
+    return payload;
+  }
+
+  const runner = options.spawnSync || spawnSync;
+  let result;
+  try {
+    result = runner("python3", [script, "--agent", agent], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+      timeout: options.timeout || 5000,
+      env: { ...process.env, ...env },
+    });
+  } catch (error) {
+    payload.reason = "helper_failed";
+    payload.stderr = String(error && error.message ? error.message : error).split("\n").slice(-1)[0] || "";
+    payload.next_step = _exposureNextStep(payload);
+    return payload;
+  }
+  const stdout = String(result.stdout || "").trim();
+  const stderr = String(result.stderr || "").trim();
+  if (result.status !== 0 && !stdout) {
+    payload.reason = "helper_failed";
+    payload.stderr = stderr.split("\n").slice(-1)[0] || "";
+    payload.next_step = _exposureNextStep(payload);
+    return payload;
+  }
+  try {
+    const checked = JSON.parse(stdout);
+    Object.assign(payload, {
+      status: checked.status || "unknown",
+      blocking: !!checked.blocking,
+      anomaly_type: checked.anomaly_type || "",
+      observed_count: Number(checked.observed_count || 0),
+      expected_tool_count: Number(checked.expected_tool_count || 0),
+      required: checked.required || [],
+      recommended: checked.recommended || [],
+      missing_required: checked.missing_required || [],
+      missing_recommended: checked.missing_recommended || [],
+      observed_required: checked.observed_required || [],
+      observed_recommended: checked.observed_recommended || [],
+      contract_tool_count: Number(checked.contract_tool_count || 0),
+      tier_config_tool_count: Number(checked.tier_config_tool_count || 0),
+      contract_tier_count_match: checked.contract_tier_count_match,
+      reason: checked.status === "unknown" && !observedRaw ? "runtime_tool_list_not_reported" : "",
+    });
+  } catch {
+    payload.reason = "helper_output_unparseable";
+  }
+  payload.next_step = _exposureNextStep(payload);
+  return payload;
+}
+
+function formatMcpExposureLine(payload) {
+  const serverText = payload.configured
+    ? `configured: ${payload.odai_servers.join(", ")}`
+    : "not configured";
+  const observed = Number(payload.observed_count || 0);
+  const expected = Number(payload.expected_tool_count || 0);
+  const observedText = observed ? `${observed}/${expected || "?"} observed` : "not reported by runtime";
+  return `${payload.status} (${payload.agent}) — ${serverText}; ${observedText}`;
+}
+
+function printDriftReport(target, options = {}) {
+  const payload = collectDriftPayload(target, options);
+  console.log("\n  drift report:");
+  if (!payload.available) {
+    console.log(`  ${D}${payload.message}${R}`);
+    console.log(`  ${D}reason: ${payload.helper} was not found in the script lookup paths${R}`);
+    console.log(`  ${D}checked:${R}`);
+    for (const candidate of payload.checked_paths) console.log(`    ${D}- ${candidate}${R}`);
+    console.log(`  ${D}next: ${payload.next_step}${R}`);
+    return payload;
+  }
+  if (payload.report) console.log(payload.report);
+  else console.log(`  ${D}drift detector returned no output${R}`);
+  if (payload.status === "error") {
+    console.log(`  ${D}drift detector exited with status ${payload.exit_code ?? "unknown"}${R}`);
+    if (payload.stderr) console.log(`  ${D}${payload.stderr}${R}`);
+  }
+  return payload;
+}
+
+function collectDoctorPayload(target, options = {}) {
+  const payload = {
     binary: "node",
     binary_version: shared.VERSION,
     checks: collectLayerChecks(target),
+    layer_version: collectLayerVersionFreshness(target),
+    mcp_exposure: collectMcpExposurePayload(target, options.mcpExposureOptions || {}),
+    node_pty: nodePtyProbe(),
   };
+  if (options.drift) {
+    payload.drift = collectDriftPayload(target, options.driftOptions || {});
+  }
+  return payload;
 }
 
 function cmdDoctor(target, options = {}) {
   const ai = path.join(target, "ai");
   if (!fs.existsSync(ai)) { log("No 0dai config found. Run: 0dai init"); return; }
   if (options.json) {
-    const payload = collectDoctorPayload(target);
+    const payload = collectDoctorPayload(target, {
+      drift: options.drift,
+      driftOptions: options.driftOptions,
+    });
     console.log(JSON.stringify(payload, null, 2));
     return payload;
   }
@@ -152,6 +582,12 @@ function cmdDoctor(target, options = {}) {
     const mark = check.ok ? `${G}ok${R2}` : check.sev === "error" ? `${E}MISSING${R2}` : `${W}missing${R2}`;
     console.log(`    ${mark.padEnd(22)} ${check.name}`);
   }
+  const layerVersion = collectLayerVersionFreshness(target);
+  if (layerVersion.status === "stale") {
+    warnings++;
+    console.log(`    ${W}warn${R2}`.padEnd(22) + ` ai/VERSION stale ${D}${layerVersion.current} → ${layerVersion.expected}${R2}`);
+    console.log(`      ${D}→ run: 0dai sync${R2}`);
+  }
   // Explain WHY native configs are missing and what to do
   if (missingConfigs.length > 0) {
     const hasDiscovery = fs.existsSync(path.join(ai, "manifest", "discovery.json"));
@@ -171,9 +607,48 @@ function cmdDoctor(target, options = {}) {
     console.log(`    ${mark.padEnd(22)} ${c.name}${hint}`);
   }
 
+  const githubIdentities = collectGitHubIdentityPayload(target, options.githubIdentityOptions || {});
+  console.log("\n  GitHub identities:");
+  for (const check of githubIdentities.checks) {
+    if (!check.ok && check.sev === "warn") warnings++;
+    const mark = check.ok
+      ? `${G}ok${R2}`
+      : check.sev === "warn"
+        ? `${W}warn${R2}`
+        : `${D}not set${R2}`;
+    const expected = check.expected_login ? ` ${D}(expected ${check.expected_login})${R2}` : "";
+    const detail = check.ok && check.login ? ` ${D}(${check.login})${R2}` : "";
+    const hint = check.ok ? "" : `\n      ${D}→ ${check.hint}${R2}`;
+    console.log(`    ${mark.padEnd(22)} ${check.name}${expected}${detail}${hint}`);
+  }
+
+  const mcpExposure = collectMcpExposurePayload(target);
+  console.log("\n  MCP exposure:");
+  const mcpMark = mcpExposure.status === "green"
+    ? `${G}ok${R2}`
+    : mcpExposure.status === "red"
+      ? `${E}missing${R2}`
+      : mcpExposure.status === "yellow"
+        ? `${W}partial${R2}`
+        : `${D}unknown${R2}`;
+  console.log(`    ${mcpMark.padEnd(22)} ${formatMcpExposureLine(mcpExposure)}`);
+  if (mcpExposure.next_step && mcpExposure.status !== "green") {
+    console.log(`      ${D}→ ${mcpExposure.next_step}${R2}`);
+  }
+
+  const nodePty = nodePtyProbe();
+  if (!nodePty.present && nodePty.sev === "warn") warnings++;
+  console.log("\n  terminal sessions:");
+  const terminalMark = nodePty.sev === "ok"
+    ? `${G}ok${R2}`
+    : nodePty.sev === "warn"
+      ? `${W}warn${R2}`
+      : `${D}${nodePty.sev}${R2}`;
+  console.log(`    ${terminalMark.padEnd(22)} ${nodePty.name} ${D}(${nodePty.hint})${R2}`);
+
   console.log("\n  provider profiles:");
   try {
-    const providerScript = findRepoScript(target, "provider_profiles.py");
+    const providerScript = resolvePythonScript(target, "provider_profiles.py");
     if (!providerScript) {
       console.log(`    ${D}—${R2}       unavailable in this environment`);
     } else {
@@ -206,6 +681,7 @@ function cmdDoctor(target, options = {}) {
   let updatesAvailable = 0;
   console.log("\n  agent CLIs:");
   for (const cli of SUPPORTED_CLIS) {
+    const label = cliDisplayName(cli);
     let installed = false, ver = null;
     try {
       const out = _ef2(cli.bin, ["--version"], { timeout: 8000 }).toString().trim();
@@ -224,13 +700,13 @@ function cmdDoctor(target, options = {}) {
       }
       if (latest && ver && latest !== ver) {
         updatesAvailable++;
-        console.log(`    ${W}update${R2}  ${cli.name} ${D}${ver} → ${latest}${R2}`);
+        console.log(`    ${W}update${R2}  ${label} ${D}${ver} → ${latest}${R2}`);
         console.log(`      ${D}→ ${cli.install}${R2}`);
       } else {
-        console.log(`    ${G}ok${R2}      ${cli.name}${ver ? ` ${D}v${ver}${R2}` : ""}`);
+        console.log(`    ${G}ok${R2}      ${label}${ver ? ` ${D}v${ver}${R2}` : ""}`);
       }
     } else {
-      console.log(`    ${D}—${R2}       ${cli.name} ${D}not installed${R2}`);
+      console.log(`    ${D}—${R2}       ${label} ${D}not installed${R2}`);
       console.log(`      ${D}→ ${cli.install}${cli.altAuth ? ` (or ${cli.altAuth})` : ""}${R2}`);
     }
   }
@@ -267,10 +743,15 @@ function cmdDoctor(target, options = {}) {
   });
   if (errors && !options.suppressExitCode) process.exitCode = 1;
 
-  // Drift summary (lightweight — full report via --drift flag)
-  if (!options.drift) {
+  if (options.drift) {
+    const drift = printDriftReport(target, options.driftOptions || {});
+    if (drift.status === "error" && typeof drift.exit_code === "number" && drift.exit_code !== 0) {
+      process.exitCode = drift.exit_code;
+    }
+  } else {
+    // Drift summary (lightweight — full report via --drift flag)
     try {
-      const ds = findRepoScript(target, "drift_detector.py");
+      const ds = resolvePythonScript(target, "drift_detector.py");
       if (ds) {
         const dr = spawnSync("python3", [ds, "report", "--target", target],
                              { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8", timeout: 5000 });
@@ -300,4 +781,17 @@ function cmdDoctor(target, options = {}) {
   }
 }
 
-module.exports = { cmdDoctor, ghostAuthStatus, nodePtyProbe, collectDoctorPayload, collectLayerChecks };
+module.exports = {
+  cmdDoctor,
+  ghostAuthStatus,
+  nodePtyProbe,
+  collectDoctorPayload,
+  collectLayerChecks,
+  collectLayerVersionFreshness,
+  compareReleaseVersions,
+  collectDriftPayload,
+  printDriftReport,
+  collectGitHubIdentityPayload,
+  collectMcpExposurePayload,
+  formatMcpExposureLine,
+};

package/lib/commands/experience.js

@@ -1,12 +1,43 @@
 "use strict";
+const fs = require("fs");
+const path = require("path");
 const shared = require("../shared");
 const { log, D, R, spawnSync, findRepoScript } = shared;
 
+// npm-installed users have no repo checkout. Fall back to the self-contained
+// python experience closure bundled into the package at lib/python/ by
+// scripts/build-python-bundle.js (#4360).
+function resolveBundledScript(name) {
+  const bundled = path.join(__dirname, "..", "python", name);
+  return fs.existsSync(bundled) ? bundled : null;
+}
+
+function resolvePythonScript(target, name) {
+  return findRepoScript(target, name) || resolveBundledScript(name);
+}
+
+function printExperienceHelp() {
+  console.log("Usage: 0dai experience [list|stats|record-json|sync|warnings|dismiss]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  list         Show recent local experience events");
+  console.log("  stats        Summarize local experience events");
+  console.log("  record-json  Record one JSON payload through the repo experience helper");
+  console.log("  sync         Sync eligible events when the repo helper permits it");
+  console.log("  warnings     Show anti-pattern warnings");
+  console.log("  dismiss      Dismiss an anti-pattern warning");
+}
+
 function cmdExperience(target, sub, args) {
-  const experienceScript = findRepoScript(target, "experience_pipeline.py");
+  if (sub === "--help" || sub === "-h" || args.includes("--help") || args.includes("-h")) {
+    printExperienceHelp();
+    process.exit(0);
+  }
+
+  const experienceScript = resolvePythonScript(target, "experience_pipeline.py");
   if (!experienceScript) {
     log("experience pipeline unavailable in this environment");
-    console.log(`  ${D}Expected scripts/experience_pipeline.py in repo checkout${R}`);
+    console.log(`  ${D}Needs scripts/experience_pipeline.py (repo) or the bundled lib/python copy; requires python3${R}`);
     process.exit(1);
   }
 
@@ -34,8 +65,12 @@ function cmdExperience(target, sub, args) {
     if (args.includes("--json")) forwarded.push("--json");
     const limitIdx = args.indexOf("--limit");
     if (limitIdx >= 0 && args[limitIdx + 1]) forwarded.push("--limit", args[limitIdx + 1]);
+  } else if (command === "record-json") {
+    if (args.includes("--json")) forwarded.push("--json");
+    const payloadIdx = args.indexOf("--payload");
+    if (payloadIdx >= 0 && args[payloadIdx + 1]) forwarded.push("--payload", args[payloadIdx + 1]);
   } else if (command === "warnings") {
-    const detectorScript = findRepoScript(target, "anti_pattern_detector.py");
+    const detectorScript = resolvePythonScript(target, "anti_pattern_detector.py");
     if (!detectorScript) { log("anti-pattern detector unavailable"); process.exit(1); }
     const fwd = [detectorScript, "warnings", "--target", target];
     if (args.includes("--json")) fwd.push("--json");
@@ -47,7 +82,7 @@ function cmdExperience(target, sub, args) {
     if (typeof wr.status === "number") process.exit(wr.status);
     process.exit(1);
   } else if (command === "dismiss") {
-    const detectorScript = findRepoScript(target, "anti_pattern_detector.py");
+    const detectorScript = resolvePythonScript(target, "anti_pattern_detector.py");
     if (!detectorScript) { log("anti-pattern detector unavailable"); process.exit(1); }
     const patternId = args.find(a => a && !a.startsWith("-")) || "";
     if (!patternId) { console.log("Usage: 0dai experience dismiss <pattern_id>"); process.exit(1); }
@@ -57,7 +92,7 @@ function cmdExperience(target, sub, args) {
     if (typeof dr.status === "number") process.exit(dr.status);
     process.exit(1);
   } else {
-    console.log("Usage: 0dai experience [list|stats|sync|warnings|dismiss]");
+    printExperienceHelp();
     process.exit(1);
   }