@moretea-labs/forge 1.7.0 → 1.7.1

package/scripts/check-agent-tooling.sh

@@ -1,1533 +1,4 @@
 #!/bin/bash
 set -euo pipefail
-
-if command -v node >/dev/null 2>&1; then
-  RUNTIME_BIN="$(command -v node)"
-elif command -v bun >/dev/null 2>&1; then
-  RUNTIME_BIN="$(command -v bun)"
-elif [[ -x "${HOME}/.bun/bin/bun" ]]; then
-  RUNTIME_BIN="${HOME}/.bun/bin/bun"
-else
-  echo "check-agent-tooling.sh requires node or bun" >&2
-  exit 1
-fi
-
-exec "$RUNTIME_BIN" - "$@" <<'NODE_EOF'
-const fs = require("fs");
-const crypto = require("crypto");
-const os = require("os");
-const path = require("path");
-const { spawnSync } = require("child_process");
-
-const argv = process.argv.slice(2);
-let jsonOutput = false;
-let checkUpdates = false;
-let strictReadiness = false;
-let hostMode = "both";
-
-function usage() {
-  console.log(`Usage: scripts/check-agent-tooling.sh [--json] [--check-updates] [--strict-readiness] [--host claude|codex|both]`);
-}
-
-for (let index = 0; index < argv.length; index += 1) {
-  const arg = argv[index];
-  if (arg === "--json") {
-    jsonOutput = true;
-    continue;
-  }
-  if (arg === "--check-updates") {
-    checkUpdates = true;
-    continue;
-  }
-  if (arg === "--strict-readiness") {
-    strictReadiness = true;
-    continue;
-  }
-  if (arg === "--host") {
-    const next = argv[index + 1];
-    if (!next) {
-      console.error("--host requires claude, codex, or both");
-      process.exit(1);
-    }
-    hostMode = next;
-    index += 1;
-    continue;
-  }
-  if (arg === "--help" || arg === "-h") {
-    usage();
-    process.exit(0);
-  }
-  console.error(`Unknown argument: ${arg}`);
-  usage();
-  process.exit(1);
-}
-
-if (!["claude", "codex", "both"].includes(hostMode)) {
-  console.error(`Unsupported host: ${hostMode}`);
-  process.exit(1);
-}
-
-const HOME = os.homedir();
-const REPO_ROOT = process.cwd();
-const SELECTED_HOSTS = hostMode === "both" ? ["claude", "codex"] : [hostMode];
-const WAZA_SOURCE_REPO = "tw93/Waza";
-const WAZA_SOURCE_URL = "https://github.com/tw93/Waza.git";
-const WAZA_RAW_BASE_URL = "https://raw.githubusercontent.com/tw93/Waza/main";
-const WAZA_MANAGED_SKILLS = ["think", "hunt", "check", "health"];
-const WAZA_SHARED_RULES = ["anti-patterns.md", "chinese.md", "durable-context.md", "english.md"];
-const CODEX_AUTOMATION_SKILLS = ["health", "check", "mermaid"];
-const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
-const CODEGRAPH_GLOBAL_INSTALL_COMMAND = `bun add -g ${CODEGRAPH_PACKAGE} && forge tools configure codegraph --target codex --location global`;
-const GBRAIN_INSTALL_COMMAND = "bun install -g github:garrytan/gbrain";
-const GBRAIN_INSTALL_NOTE =
-  "Install from GitHub; npm registry package gbrain is an unrelated GPU library and does not ship this CLI.";
-const CODEGRAPH_MCP_CONFIGURE_COMMAND = "forge tools configure codegraph --target <codex|claude|both> --location global";
-const CODEGRAPH_LOCAL_INSTALL_COMMAND = "bun install";
-const CODEGRAPH_ENSURE_COMMAND = [
-  ".ai/harness/scripts/ensure-codegraph.sh",
-  "scripts/ensure-codegraph.sh",
-].find((relPath) => fs.existsSync(path.join(REPO_ROOT, relPath)));
-const CODEGRAPH_ENSURE_BASH_COMMAND = CODEGRAPH_ENSURE_COMMAND
-  ? `bash ${CODEGRAPH_ENSURE_COMMAND}`
-  : null;
-const WAZA_STAGING_ROOT = path.join(HOME, ".agents");
-const WAZA_STAGING_DIR = path.join(WAZA_STAGING_ROOT, "skills");
-const WAZA_STAGING_RULES_DIR = path.join(WAZA_STAGING_ROOT, "rules");
-let timeoutBin;
-const HOSTS = {
-  claude: {
-    label: "Claude Code",
-    agentLabel: "Claude Code",
-    skillsDir: path.join(HOME, ".claude", "skills"),
-    gstackDir: path.join(HOME, ".claude", "skills", "gstack"),
-    configPath: path.join(HOME, ".claude", "settings.json"),
-  },
-  codex: {
-    label: "Codex",
-    agentLabel: "Codex",
-    skillsDir: path.join(HOME, ".codex", "skills"),
-    gstackDir: path.join(HOME, ".codex", "skills", "gstack"),
-    configPath: path.join(HOME, ".codex", "config.toml"),
-  },
-};
-
-function readText(filePath) {
-  try {
-    return fs.readFileSync(filePath, "utf8");
-  } catch (_error) {
-    return "";
-  }
-}
-
-function readJson(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch (_error) {
-    return null;
-  }
-}
-
-function fileIsExecutable(filePath) {
-  try {
-    fs.accessSync(filePath, fs.constants.X_OK);
-    return true;
-  } catch (_error) {
-    return false;
-  }
-}
-
-function detectTimeoutBin() {
-  if (timeoutBin !== undefined) return timeoutBin;
-  timeoutBin = resolvePathCommand("timeout") || "";
-  return timeoutBin;
-}
-
-function commandCapability(command, requiredFor, owner, required = false) {
-  const binPath = resolvePathCommand(command);
-  return {
-    name: command,
-    status: binPath ? "present" : "missing",
-    path: binPath,
-    owner,
-    required,
-    required_for: requiredFor,
-  };
-}
-
-function detectSymlinkCapability() {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-symlink-check-"));
-  const source = path.join(tmpDir, "source");
-  const link = path.join(tmpDir, "link");
-  try {
-    fs.writeFileSync(source, "ok\n");
-    fs.symlinkSync(source, link);
-    return {
-      name: "symlink",
-      status: "supported",
-      path: null,
-      owner: "platform-filesystem",
-      required: false,
-      required_for: "installed-copy link mode and host skill aliasing; copy mode remains the fallback",
-    };
-  } catch (error) {
-    return {
-      name: "symlink",
-      status: "unsupported",
-      path: null,
-      owner: "platform-filesystem",
-      required: false,
-      required_for: "installed-copy link mode and host skill aliasing; copy mode remains the fallback",
-      reason: String(error?.message || error),
-    };
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-}
-
-function run(command, args, options = {}) {
-  const timeoutMs = options.timeoutMs ?? 0;
-  const externalTimeout = timeoutMs > 0 ? detectTimeoutBin() : "";
-  const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
-  const spawnCommand = externalTimeout || command;
-  const spawnArgs = externalTimeout ? ["--kill-after=1s", `${timeoutSeconds}s`, command, ...args] : args;
-  const result = spawnSync(spawnCommand, spawnArgs, {
-    cwd: options.cwd ?? REPO_ROOT,
-    encoding: "utf8",
-    env: { ...process.env, ...(options.env ?? {}) },
-    timeout: externalTimeout ? timeoutMs + 1000 : timeoutMs,
-  });
-
-  return {
-    ok: result.status === 0 && !result.error,
-    status: result.status,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-    error: result.error ? String(result.error.message || result.error) : "",
-    timed_out: result.error?.code === "ETIMEDOUT" || result.status === 124,
-  };
-}
-
-function parseJson(text) {
-  try {
-    return JSON.parse(text);
-  } catch (_error) {
-    return null;
-  }
-}
-
-function sha1(text) {
-  return crypto.createHash("sha1").update(text).digest("hex");
-}
-
-function sha1Buffer(buffer) {
-  return crypto.createHash("sha1").update(buffer).digest("hex");
-}
-
-function parseSkillVersion(text) {
-  const match = text.match(/^\s*version:\s*["']?([^"'\n]+)["']?/m);
-  return match ? match[1].trim() : null;
-}
-
-function resolveRealPath(filePath) {
-  try {
-    return fs.realpathSync(filePath);
-  } catch (_error) {
-    return null;
-  }
-}
-
-function readSkillFile(filePath) {
-  const content = readText(filePath);
-  if (!content) {
-    return {
-      exists: false,
-      version: null,
-      hash: null,
-    };
-  }
-
-  return {
-    exists: true,
-    version: parseSkillVersion(content),
-    hash: sha1(content),
-  };
-}
-
-function readFileHash(filePath) {
-  try {
-    return {
-      exists: true,
-      hash: sha1Buffer(fs.readFileSync(filePath)),
-    };
-  } catch (_error) {
-    return {
-      exists: false,
-      hash: null,
-    };
-  }
-}
-
-function collectDirectoryHashes(dirPath) {
-  try {
-    if (!fs.statSync(dirPath).isDirectory()) return null;
-  } catch (_error) {
-    return null;
-  }
-
-  const files = {};
-  function visit(currentDir, relativeDir) {
-    let entries = [];
-    try {
-      entries = fs.readdirSync(currentDir, { withFileTypes: true });
-    } catch (_error) {
-      return;
-    }
-    for (const entry of entries) {
-      const absolutePath = path.join(currentDir, entry.name);
-      const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
-      let stat;
-      try {
-        stat = fs.statSync(absolutePath);
-      } catch (_error) {
-        continue;
-      }
-      if (stat.isDirectory()) {
-        visit(absolutePath, relativePath);
-      } else if (stat.isFile()) {
-        files[relativePath] = sha1Buffer(fs.readFileSync(absolutePath));
-      }
-    }
-  }
-
-  visit(dirPath, "");
-  return files;
-}
-
-function compareFileMaps(localFiles, referenceFiles) {
-  const missing = [];
-  const extra = [];
-  const changed = [];
-  const localKeys = new Set(Object.keys(localFiles || {}));
-  const referenceKeys = new Set(Object.keys(referenceFiles || {}));
-
-  for (const key of [...referenceKeys].sort()) {
-    if (!localKeys.has(key)) {
-      missing.push(key);
-    } else if (localFiles[key] !== referenceFiles[key]) {
-      changed.push(key);
-    }
-  }
-
-  for (const key of [...localKeys].sort()) {
-    if (!referenceKeys.has(key)) {
-      extra.push(key);
-    }
-  }
-
-  return { missing, extra, changed };
-}
-
-function inspectDirectorySync(localDir, stagingDir) {
-  const localFiles = collectDirectoryHashes(localDir);
-  const stagingFiles = collectDirectoryHashes(stagingDir);
-
-  if (!localFiles && !stagingFiles) {
-    return {
-      status: "unknown",
-      missing_files: [],
-      extra_files: [],
-      changed_files: [],
-    };
-  }
-
-  if (!localFiles && stagingFiles) {
-    return {
-      status: "missing-local",
-      missing_files: Object.keys(stagingFiles).sort(),
-      extra_files: [],
-      changed_files: [],
-    };
-  }
-
-  if (localFiles && !stagingFiles) {
-    return {
-      status: "unknown",
-      missing_files: [],
-      extra_files: [],
-      changed_files: [],
-    };
-  }
-
-  const diff = compareFileMaps(localFiles, stagingFiles);
-  const clean = diff.missing.length === 0 && diff.extra.length === 0 && diff.changed.length === 0;
-  return {
-    status: clean ? "synced" : "drift",
-    missing_files: diff.missing,
-    extra_files: diff.extra,
-    changed_files: diff.changed,
-  };
-}
-
-function summarizeStatus(hostStatuses) {
-  const values = Object.values(hostStatuses);
-  const presentCount = values.filter((entry) => entry.present).length;
-  if (presentCount === 0) return "missing";
-  if (presentCount === values.length) return "present";
-  return "partial";
-}
-
-function detectRepoGstackTeamMode() {
-  const claudeMd = readText(path.join(REPO_ROOT, "CLAUDE.md"));
-  const settings = readText(path.join(REPO_ROOT, ".claude", "settings.json"));
-  const hookPath = path.join(REPO_ROOT, ".claude", "hooks", "check-gstack.sh");
-
-  if (settings.includes("check-gstack.sh") || fs.existsSync(hookPath) || claudeMd.includes("## gstack (REQUIRED")) {
-    return {
-      status: "required",
-      reason: "Repo has gstack enforcement traces (required CLAUDE.md section or check-gstack hook).",
-    };
-  }
-
-  if (claudeMd.includes("## gstack")) {
-    return {
-      status: "optional",
-      reason: "Repo has a gstack guidance section in CLAUDE.md but no enforcement hook.",
-    };
-  }
-
-  return {
-    status: "not-detected",
-    reason: "No repo-local gstack team-mode traces detected in CLAUDE.md or the shared .ai/hooks/ layer.",
-  };
-}
-
-function detectGstack() {
-  const hostStatuses = {};
-
-  for (const host of SELECTED_HOSTS) {
-    const meta = HOSTS[host];
-    const present = fs.existsSync(meta.gstackDir);
-    const versionFile = path.join(meta.gstackDir, "VERSION");
-    const gitDir = path.join(meta.gstackDir, ".git");
-    const version = present && fs.existsSync(versionFile) ? readText(versionFile).trim() : "";
-    let updateStatus = checkUpdates ? "unknown" : "not-checked";
-    let origin = "";
-    let head = "";
-    let remoteHead = "";
-    let updateReason = "";
-
-    if (present && checkUpdates && fs.existsSync(gitDir)) {
-      const originResult = run("git", ["-C", meta.gstackDir, "remote", "get-url", "origin"], { timeoutMs: 1000 });
-      if (originResult.ok) {
-        origin = originResult.stdout.trim();
-      }
-
-      const headResult = run("git", ["-C", meta.gstackDir, "rev-parse", "HEAD"], { timeoutMs: 1000 });
-      if (headResult.ok) {
-        head = headResult.stdout.trim();
-      }
-
-      const remoteResult = run("git", ["-C", meta.gstackDir, "ls-remote", "--symref", "origin", "HEAD"], { timeoutMs: 1500 });
-      if (remoteResult.ok) {
-        const match = remoteResult.stdout.match(/^([0-9a-f]+)\s+HEAD$/m);
-        remoteHead = match ? match[1] : "";
-      }
-
-      if (head && remoteHead) {
-        updateStatus = head === remoteHead ? "up-to-date" : "update-available";
-        updateReason = head === remoteHead
-          ? "Local gstack matches origin/HEAD."
-          : "Local gstack HEAD differs from origin/HEAD."
-      } else if (origin || head) {
-        updateStatus = "unknown";
-        updateReason = remoteResult.timed_out
-          ? "Timed out while checking gstack origin/HEAD."
-          : "Unable to resolve both local and remote HEAD for gstack."
-      }
-    } else if (present) {
-      updateStatus = checkUpdates ? "unknown" : "not-checked";
-      updateReason = fs.existsSync(gitDir)
-        ? "Update checks were skipped."
-        : "gstack install is present but not a full git checkout in this host path.";
-    }
-
-    hostStatuses[host] = {
-      label: meta.label,
-      present,
-      path: meta.gstackDir,
-      version: version || null,
-      origin: origin || null,
-      head: head || null,
-      remote_head: remoteHead || null,
-      update_status: updateStatus,
-      reason: present
-        ? (updateReason || `Detected gstack at ${meta.gstackDir}.`)
-        : `Missing gstack at ${meta.gstackDir}.`,
-      install_command: host === "claude"
-        ? "git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup"
-        : `${fs.existsSync(HOSTS.claude.gstackDir) ? "cd ~/.claude/skills/gstack" : "git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack"} && ./setup --host codex`,
-      upgrade_command: host === "claude"
-        ? "cd ~/.claude/skills/gstack && git pull && ./setup"
-        : "cd ~/.claude/skills/gstack && git pull && ./setup --host codex",
-    };
-  }
-
-  const repoTeamMode = detectRepoGstackTeamMode();
-  const status = summarizeStatus(hostStatuses);
-  const selectedMeta = Object.values(hostStatuses);
-  const installCommand = SELECTED_HOSTS.length === 2
-    ? "git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup && ./setup --host codex"
-    : selectedMeta[0].install_command;
-  const upgradeCommand = SELECTED_HOSTS.length === 2
-    ? "cd ~/.claude/skills/gstack && git pull && ./setup && ./setup --host codex"
-    : selectedMeta[0].upgrade_command;
-
-  return {
-    name: "gstack",
-    status,
-    reason: status === "present"
-      ? `Detected gstack in all requested hosts (${SELECTED_HOSTS.join(", ")}).`
-      : status === "partial"
-        ? `Detected gstack in ${selectedMeta.filter((entry) => entry.present).length}/${selectedMeta.length} requested hosts.`
-        : "gstack is missing from all requested hosts.",
-    hosts: hostStatuses,
-    repo_team_mode: repoTeamMode,
-    install_command: installCommand,
-    upgrade_command: upgradeCommand,
-    impact: {
-      complex_tasks: status === "present" ? "full" : status === "partial" ? "degraded" : "missing",
-      simple_tasks: "unaffected",
-      knowledge_tasks: "unaffected",
-    },
-  };
-}
-
-function summarizeWazaStatus(hostStatuses) {
-  const values = Object.values(hostStatuses);
-  const fullCount = values.filter((entry) => entry.status === "present").length;
-  const installedCount = values.reduce((count, entry) => count + entry.installed_skills.length, 0);
-  if (fullCount === values.length) return "present";
-  if (installedCount > 0) return "partial";
-  return "missing";
-}
-
-function fetchWazaUpstreamSkills() {
-  if (!checkUpdates) {
-    return {
-      status: "not-checked",
-      reason: "Update checks were skipped.",
-      skills: {},
-      rules: {},
-    };
-  }
-
-  const skills = {};
-  const rules = {};
-  const failures = [];
-
-  for (const skill of WAZA_MANAGED_SKILLS) {
-    const url = `${WAZA_RAW_BASE_URL}/skills/${skill}/SKILL.md`;
-    const result = run("curl", ["-fsSL", "--max-time", "5", url], { timeoutMs: 7000 });
-    if (!result.ok || !result.stdout) {
-      failures.push(`skills/${skill}/SKILL.md`);
-      continue;
-    }
-
-    skills[skill] = {
-      version: parseSkillVersion(result.stdout),
-      hash: sha1(result.stdout),
-      source_url: url,
-    };
-  }
-
-  for (const rule of WAZA_SHARED_RULES) {
-    const url = `${WAZA_RAW_BASE_URL}/rules/${rule}`;
-    const result = run("curl", ["-fsSL", "--max-time", "5", url], { timeoutMs: 7000 });
-    if (!result.ok || !result.stdout) {
-      failures.push(`rules/${rule}`);
-      continue;
-    }
-
-    rules[rule] = {
-      hash: sha1(result.stdout),
-      source_url: url,
-    };
-  }
-
-  if (failures.length > 0) {
-    return {
-      status: "unknown",
-      reason: `Unable to fetch upstream Waza files for: ${failures.join(", ")}.`,
-      skills,
-      rules,
-    };
-  }
-
-  return {
-    status: "fetched",
-    reason: "Fetched upstream Waza SKILL.md and shared rule files from GitHub raw URLs.",
-    skills,
-    rules,
-  };
-}
-
-function hostUsesStagingSkillSymlinks(host) {
-  const meta = HOSTS[host];
-  const presentSkillDirs = WAZA_MANAGED_SKILLS
-    .map((skill) => path.join(meta.skillsDir, skill))
-    .filter((skillDir) => fs.existsSync(skillDir));
-
-  if (presentSkillDirs.length === 0) return false;
-
-  const stagingRealPath = resolveRealPath(WAZA_STAGING_DIR) || WAZA_STAGING_DIR;
-  return presentSkillDirs.every((skillDir) => {
-    const realPath = resolveRealPath(skillDir);
-    return realPath
-      ? realPath.startsWith(`${WAZA_STAGING_DIR}${path.sep}`) || realPath.startsWith(`${stagingRealPath}${path.sep}`)
-      : false;
-  });
-}
-
-function resolveWazaRulePath(host, rule) {
-  const meta = HOSTS[host];
-  const hostRulesPath = path.join(path.dirname(meta.skillsDir), "rules", rule);
-  if (fs.existsSync(hostRulesPath)) return hostRulesPath;
-  if (hostUsesStagingSkillSymlinks(host)) {
-    return path.join(WAZA_STAGING_RULES_DIR, rule);
-  }
-  return hostRulesPath;
-}
-
-function inspectWazaSharedRule(host, rule, upstreamRules) {
-  const localFile = resolveWazaRulePath(host, rule);
-  const stagingFile = path.join(WAZA_STAGING_RULES_DIR, rule);
-  const local = readFileHash(localFile);
-  const staging = readFileHash(stagingFile);
-  const upstream = upstreamRules[rule] || null;
-
-  return {
-    name: rule,
-    path: localFile,
-    real_path: resolveRealPath(localFile),
-    present: local.exists,
-    hash: local.hash,
-    staging_present: staging.exists,
-    staging_hash: staging.hash,
-    staging_sync: local.exists && staging.exists
-      ? (local.hash === staging.hash ? "synced" : "drift")
-      : staging.exists
-        ? "missing-local"
-        : "unknown",
-    upstream_hash: upstream?.hash || null,
-    stale_status: !checkUpdates
-      ? "not-checked"
-      : upstream?.hash && local.exists
-        ? (local.hash === upstream.hash ? "up-to-date" : "stale")
-        : upstream?.hash
-          ? "missing-local"
-          : "unknown",
-  };
-}
-
-function inspectWazaSkill(host, skill, skillLock, skillItems, upstreamSkills) {
-  const meta = HOSTS[host];
-  const skillDir = path.join(meta.skillsDir, skill);
-  const skillFile = path.join(skillDir, "SKILL.md");
-  const stagingFile = path.join(WAZA_STAGING_DIR, skill, "SKILL.md");
-  const stagingDir = path.join(WAZA_STAGING_DIR, skill);
-  const local = readSkillFile(skillFile);
-  const staging = readSkillFile(stagingFile);
-  const directorySync = inspectDirectorySync(skillDir, stagingDir);
-  const upstream = upstreamSkills[skill] || null;
-  let symlinkTarget = null;
-
-  try {
-    const stat = fs.lstatSync(skillDir);
-    if (stat.isSymbolicLink()) {
-      symlinkTarget = fs.readlinkSync(skillDir);
-    }
-  } catch (_error) {
-    symlinkTarget = null;
-  }
-
-  const skillCliItem = skillItems.find((item) => item.name === skill);
-  const skillCliAgents = Array.isArray(skillCliItem?.agents) ? skillCliItem.agents : [];
-  const sourceLock = skillLock?.skills?.[skill] || null;
-
-  return {
-    name: skill,
-    path: skillFile,
-    real_path: resolveRealPath(skillFile),
-    symlink_target: symlinkTarget,
-    present: local.exists,
-    version: local.version,
-    hash: local.hash,
-    source_locked: sourceLock?.source === WAZA_SOURCE_REPO,
-    source_repo: sourceLock?.source || null,
-    skills_cli_agents: skillCliAgents,
-    staging_present: staging.exists,
-    staging_version: staging.version,
-    staging_hash: staging.hash,
-    staging_sync: directorySync.status,
-    staging_missing_files: directorySync.missing_files,
-    staging_extra_files: directorySync.extra_files,
-    staging_changed_files: directorySync.changed_files,
-    upstream_version: upstream?.version || null,
-    upstream_hash: upstream?.hash || null,
-    stale_status: !checkUpdates
-      ? "not-checked"
-      : upstream?.hash && local.exists
-        ? (local.hash === upstream.hash ? "up-to-date" : "stale")
-        : upstream?.hash
-          ? "missing-local"
-          : "unknown",
-  };
-}
-
-function detectWaza() {
-  const skillLockPath = path.join(HOME, ".agents", ".skill-lock.json");
-  const skillLock = readJson(skillLockPath);
-  const skillsBin = resolvePathCommand("skills");
-  const skillsResult = skillsBin
-    ? run(skillsBin, ["ls", "-g", "--json"], { timeoutMs: 1500 })
-    : { ok: false, status: null, stdout: "", stderr: "", error: "skills CLI is not installed", timed_out: false };
-  const skillItems = skillsResult.ok ? parseJson(skillsResult.stdout) || [] : [];
-  const wazaEntries = Object.entries(skillLock?.skills || {}).filter(([, meta]) => meta?.source === WAZA_SOURCE_REPO);
-  const upstream = fetchWazaUpstreamSkills();
-  const hostStatuses = {};
-
-  for (const host of SELECTED_HOSTS) {
-    const skills = WAZA_MANAGED_SKILLS.map((skill) => inspectWazaSkill(host, skill, skillLock, skillItems, upstream.skills));
-    const sharedRules = WAZA_SHARED_RULES.map((rule) => inspectWazaSharedRule(host, rule, upstream.rules));
-    const installedSkills = skills.filter((entry) => entry.present).map((entry) => entry.name);
-    const missingSkills = skills.filter((entry) => !entry.present).map((entry) => entry.name);
-    const driftSkills = skills.filter((entry) => entry.staging_sync === "drift").map((entry) => entry.name);
-    const unsyncedSkills = skills
-      .filter((entry) => entry.staging_sync === "drift" || entry.staging_sync === "missing-local")
-      .map((entry) => entry.name);
-    const staleSkills = skills.filter((entry) => entry.stale_status === "stale").map((entry) => entry.name);
-    const installedSharedRules = sharedRules.filter((entry) => entry.present).map((entry) => entry.name);
-    const missingSharedRules = sharedRules.filter((entry) => !entry.present).map((entry) => entry.name);
-    const driftSharedRules = sharedRules.filter((entry) => entry.staging_sync === "drift").map((entry) => entry.name);
-    const unsyncedSharedRules = sharedRules
-      .filter((entry) => entry.staging_sync === "drift" || entry.staging_sync === "missing-local")
-      .map((entry) => entry.name);
-    const staleSharedRules = sharedRules
-      .filter((entry) => entry.stale_status === "stale" || entry.stale_status === "missing-local")
-      .map((entry) => entry.name);
-    const status = missingSkills.length === 0 ? "present" : installedSkills.length > 0 ? "partial" : "missing";
-    const stagingSync = status === "missing"
-      ? "missing"
-      : unsyncedSkills.length > 0 || unsyncedSharedRules.length > 0
-        ? "drift"
-        : skills.every((entry) => entry.staging_sync === "synced") && sharedRules.every((entry) => entry.staging_sync === "synced")
-          ? "synced"
-          : "unknown";
-    const staleStatus = !checkUpdates
-      ? "not-checked"
-      : staleSkills.length > 0 || staleSharedRules.length > 0
-        ? "stale"
-        : skills.every((entry) => entry.stale_status === "up-to-date") && sharedRules.every((entry) => entry.stale_status === "up-to-date")
-          ? "up-to-date"
-          : "unknown";
-    const sharedRulesStagingSync = unsyncedSharedRules.length > 0
-      ? "drift"
-      : sharedRules.every((entry) => entry.staging_sync === "synced")
-        ? "synced"
-        : "unknown";
-    const sharedRulesStaleStatus = !checkUpdates
-      ? "not-checked"
-      : staleSharedRules.length > 0
-        ? "stale"
-        : sharedRules.every((entry) => entry.stale_status === "up-to-date")
-          ? "up-to-date"
-          : "unknown";
-
-    hostStatuses[host] = {
-      label: HOSTS[host].label,
-      path: HOSTS[host].skillsDir,
-      status,
-      present: status === "present",
-      installed_skills: installedSkills,
-      missing_skills: missingSkills,
-      drift_skills: driftSkills,
-      stale_skills: staleSkills,
-      shared_rules: installedSharedRules,
-      missing_shared_rules: missingSharedRules,
-      drift_shared_rules: driftSharedRules,
-      stale_shared_rules: staleSharedRules,
-      shared_rules_staging_sync: sharedRulesStagingSync,
-      shared_rules_stale_status: sharedRulesStaleStatus,
-      versions: Object.fromEntries(skills.filter((entry) => entry.present).map((entry) => [entry.name, entry.version])),
-      staging_sync: stagingSync,
-      stale_status: staleStatus,
-      skills,
-      shared_rule_details: sharedRules,
-      reason: status === "present"
-        ? `Detected all ${WAZA_MANAGED_SKILLS.length} Waza skills for ${HOSTS[host].label} from the real host skill path.`
-        : status === "partial"
-          ? `Detected ${installedSkills.length}/${WAZA_MANAGED_SKILLS.length} Waza skills for ${HOSTS[host].label}; missing ${missingSkills.join(", ")}.`
-          : `No Waza skills detected at ${HOSTS[host].skillsDir}.`,
-    };
-  }
-
-  const staleSkillSet = new Set();
-  const staleRuleSet = new Set();
-  for (const host of Object.values(hostStatuses)) {
-    for (const skill of host.stale_skills) staleSkillSet.add(skill);
-    for (const rule of host.stale_shared_rules) staleRuleSet.add(rule);
-  }
-  const updateStatus = !checkUpdates
-    ? "not-checked"
-    : upstream.status === "unknown"
-      ? "unknown"
-      : staleSkillSet.size > 0 || staleRuleSet.size > 0
-        ? "update-available"
-        : "up-to-date";
-  const updateReason = !checkUpdates
-    ? "Update checks were skipped."
-    : upstream.status === "unknown"
-      ? upstream.reason
-      : staleSkillSet.size > 0 || staleRuleSet.size > 0
-        ? `Upstream Waza files differ for: ${[
-            ...[...staleSkillSet].sort().map((skill) => `skills/${skill}/SKILL.md`),
-            ...[...staleRuleSet].sort().map((rule) => `rules/${rule}`),
-          ].join(", ")}.`
-        : "Local Waza SKILL.md and shared rule files match upstream GitHub raw content.";
-
-  const status = summarizeWazaStatus(hostStatuses);
-  const installCommand = `npx -y skills add tw93/Waza -g -a ${
-    hostMode === "both" ? "claude-code codex" : hostMode === "claude" ? "claude-code" : "codex"
-  } -s think hunt check health -y`;
-  const rulesList = WAZA_SHARED_RULES.join(" ");
-  const syncCommand = `for d in ${WAZA_MANAGED_SKILLS.join(" ")}; do rsync -a --delete ~/.agents/skills/$d/ ~/.codex/skills/$d/; done; mkdir -p ~/.codex/rules; for f in ${rulesList}; do cp ~/.agents/rules/$f ~/.codex/rules/$f; done`;
-
-  return {
-    name: "waza",
-    status,
-    reason: status === "present"
-      ? `Detected Waza in all requested real host paths (${SELECTED_HOSTS.join(", ")}).`
-      : status === "partial"
-        ? "Waza is installed for some requested host paths or only partially installed."
-        : "No managed Waza skills were found in the requested real host paths.",
-    source_lock_file: fs.existsSync(skillLockPath) ? skillLockPath : null,
-    source_repo: WAZA_SOURCE_REPO,
-    source_url: WAZA_SOURCE_URL,
-    managed_skills: WAZA_MANAGED_SKILLS,
-    shared_rules: WAZA_SHARED_RULES,
-    primary_host: "codex",
-    codex_primary_path: path.join(HOME, ".codex", "skills"),
-    staging_cache_path: WAZA_STAGING_DIR,
-    staging_rules_path: WAZA_STAGING_RULES_DIR,
-    sync_mode: "codex-first-copy-from-staging",
-    host_drift_policy: "report-per-host-directory-rule-staging-and-upstream-drift",
-    skills_cli_status: skillsResult.ok ? "available" : skillsResult.timed_out ? "timed-out" : "unavailable",
-    source_lock_entries: wazaEntries.map(([name]) => name).sort(),
-    upstream_status: upstream.status,
-    upstream_reason: upstream.reason,
-    upstream_skills: upstream.skills,
-    upstream_rules: upstream.rules,
-    hosts: hostStatuses,
-    update_status: updateStatus,
-    update_reason: updateReason,
-    install_command: installCommand,
-    stage_command: "npx -y skills update",
-    sync_command: syncCommand,
-    verify_command: `for d in ${WAZA_MANAGED_SKILLS.join(" ")}; do diff -qr ~/.agents/skills/$d ~/.codex/skills/$d; done; for f in ${rulesList}; do cmp -s ~/.agents/rules/$f ~/.codex/rules/$f; done`,
-    upgrade_command: `npx -y skills update && ${syncCommand}`,
-    impact: {
-      complex_tasks: "unaffected",
-      simple_tasks: status === "present" ? "full" : status === "partial" ? "degraded" : "missing",
-      knowledge_tasks: "unaffected",
-    },
-  };
-}
-
-function detectRuntimeCapabilities(waza) {
-  return {
-    bun: commandCapability(
-      "bun",
-      "forge-owned global installs, local package dependency install, and test/runtime execution",
-      "forge",
-      true
-    ),
-    npm: commandCapability(
-      "npm",
-      "npm registry readbacks, publish gates, and opt-in update checks; not used for forge-owned global install repair",
-      "npm-registry",
-      false
-    ),
-    npx: commandCapability(
-      "npx",
-      "external Skills CLI bootstrap/update commands for Waza and Mermaid",
-      "external-skills-cli",
-      false
-    ),
-    skills_cli: {
-      name: "skills_cli",
-      status: waza.skills_cli_status === "available" ? "available" : waza.skills_cli_status,
-      path: null,
-      owner: "external-skills-cli",
-      required: false,
-      required_for: "Waza/Mermaid external skill bootstrap; forge reports this as an explicit exception boundary",
-      command: "skills ls -g --json",
-    },
-    bash: commandCapability(
-      "bash",
-      "forge helper scripts, migration, setup checks, and contract verification wrappers",
-      "forge",
-      true
-    ),
-    rsync: commandCapability(
-      "rsync",
-      "Waza staging-to-Codex sync and installed-copy runtime mirroring",
-      "platform-filesystem",
-      false
-    ),
-    symlink: detectSymlinkCapability(),
-  };
-}
-
-function inspectCodexAutomationSkill(skill) {
-  const skillFile = path.join(HOSTS.codex.skillsDir, skill, "SKILL.md");
-  const local = readSkillFile(skillFile);
-
-  return {
-    name: skill,
-    path: skillFile,
-    real_path: resolveRealPath(skillFile),
-    present: local.exists,
-    version: local.version,
-    hash: local.hash,
-  };
-}
-
-function detectCodexAutomationProfile() {
-  const skills = CODEX_AUTOMATION_SKILLS.map((skill) => inspectCodexAutomationSkill(skill));
-  const installedSkills = skills.filter((entry) => entry.present).map((entry) => entry.name);
-  const missingSkills = skills.filter((entry) => !entry.present).map((entry) => entry.name);
-  const status = missingSkills.length === 0 ? "present" : installedSkills.length > 0 ? "partial" : "missing";
-
-  return {
-    name: "codex_automation_profile",
-    status,
-    reason: status === "present"
-      ? "Detected all required Codex automation skills from the Codex runtime path."
-      : status === "partial"
-        ? `Detected ${installedSkills.length}/${CODEX_AUTOMATION_SKILLS.length} required Codex automation skills; missing ${missingSkills.join(", ")}.`
-        : "No required Codex automation skills were found in the Codex runtime path.",
-    required_skills: CODEX_AUTOMATION_SKILLS,
-    optional_skills: [],
-    mode: "codex-runtime-reference",
-    source: HOSTS.codex.skillsDir,
-    routes: {
-      workflow_health: "waza:health",
-      review_gate: "waza:check",
-      architecture_diagram: "mermaid",
-    },
-    vendoring_policy: "do-not-vendor-skill-body",
-    installed_skills: installedSkills,
-    missing_skills: missingSkills,
-    skills,
-  };
-}
-
-function detectGbrainMcp(host) {
-  const meta = HOSTS[host];
-  const content = readText(meta.configPath);
-  if (!content) {
-    return {
-      status: "disabled",
-      reason: `No ${meta.label} config found at ${meta.configPath}.`,
-    };
-  }
-
-  if (host === "codex") {
-    if (/\[mcp_servers\.(gbrain|gbrain_http)\]/.test(content)) {
-      return {
-        status: "configured",
-        reason: "Codex config contains a gbrain MCP server entry.",
-      };
-    }
-
-    return {
-      status: "disabled",
-      reason: "Codex config does not contain a gbrain MCP server entry.",
-    };
-  }
-
-  if (/gbrain/i.test(content)) {
-    return {
-      status: "configured",
-      reason: "Claude settings contain a gbrain reference.",
-    };
-  }
-
-  return {
-    status: "disabled",
-    reason: "Claude settings do not contain a gbrain MCP configuration.",
-  };
-}
-
-function isGbrainFastOnlyConnectionSkip(doctorJson) {
-  if (!doctorJson || doctorJson.status !== "warnings") return false;
-  if (!Array.isArray(doctorJson.checks)) return false;
-  const warnings = doctorJson.checks.filter((entry) => entry?.status === "warn" || entry?.status === "warning");
-  if (warnings.length !== 1) return false;
-  const warning = warnings[0];
-  const message = String(warning.message || "");
-  return warning.name === "connection"
-    && (/Skipping DB checks \((--fast mode|"--fast mode)/i.test(message) || /fast mode skipped DB checks/i.test(message));
-}
-
-function detectGbrain() {
-  const gbrainBin = resolvePathCommand("gbrain");
-  let versionResult = gbrainBin
-    ? run(gbrainBin, ["--version"], { timeoutMs: 1000 })
-    : { ok: false, stdout: "", timed_out: false };
-  if (!versionResult.ok && versionResult.timed_out) {
-    versionResult = run(gbrainBin, ["--version"], { timeoutMs: 1000 });
-  }
-  const present = versionResult.ok;
-  const version = present ? versionResult.stdout.trim().replace(/^gbrain\s+/i, "") : null;
-  let doctorCommand = ["doctor", "--json", "--fast"];
-  let doctorResult = present ? run(gbrainBin, doctorCommand, { timeoutMs: 1500 }) : null;
-  let doctorJson = doctorResult?.ok ? parseJson(doctorResult.stdout) : null;
-  if (present && !doctorJson) {
-    doctorCommand = ["doctor", "--json"];
-    doctorResult = run(gbrainBin, doctorCommand, { timeoutMs: 1500 });
-    doctorJson = doctorResult?.ok ? parseJson(doctorResult.stdout) : null;
-  }
-  const checkUpdateResult = present && checkUpdates ? run(gbrainBin, ["check-update", "--json"], { timeoutMs: 1500 }) : null;
-  const checkUpdateJson = checkUpdateResult?.ok ? parseJson(checkUpdateResult.stdout) : null;
-  const integrationsResult = present ? run(gbrainBin, ["integrations", "list", "--json"], { timeoutMs: 1500 }) : null;
-  const integrationsJson = integrationsResult?.ok ? parseJson(integrationsResult.stdout) : null;
-  const integrationsAvailable = integrationsJson
-    ? Object.values(integrationsJson).reduce((count, value) => count + (Array.isArray(value) ? value.length : 0), 0)
-    : 0;
-  const mcpHosts = {};
-
-  for (const host of SELECTED_HOSTS) {
-    mcpHosts[host] = {
-      label: HOSTS[host].label,
-      ...detectGbrainMcp(host),
-    };
-  }
-
-  const mcpConfigured = Object.values(mcpHosts).some((entry) => entry.status === "configured");
-  const acceptedFastWarning = doctorCommand.join(" ") === "doctor --json --fast" && isGbrainFastOnlyConnectionSkip(doctorJson);
-  const status = !present
-    ? "missing"
-    : (doctorJson?.status === "ok" || acceptedFastWarning ? "present" : doctorJson?.status === "warnings" ? "warning" : "warning");
-  const updateStatus = !checkUpdates
-    ? "not-checked"
-    : checkUpdateJson?.update_available
-      ? "update-available"
-      : checkUpdateJson
-        ? "up-to-date"
-        : "unknown";
-
-  return {
-    name: "gbrain",
-    required: false,
-    status,
-    reason: !present
-      ? "gbrain CLI is not installed; install the official GitHub package, not npm registry package gbrain."
-      : acceptedFastWarning
-        ? "gbrain CLI is present; fast doctor only skipped DB checks."
-      : doctorJson
-        ? `gbrain CLI is present; doctor status is ${doctorJson.status}.`
-        : "gbrain CLI is present, but doctor output could not be parsed.",
-    cli_present: present,
-    version,
-    doctor_command: present ? `gbrain ${doctorCommand.join(" ")}` : null,
-    doctor: doctorJson,
-    update_status: updateStatus,
-    update_reason: checkUpdateJson?.error
-      ? `gbrain check-update returned ${checkUpdateJson.error}.`
-      : checkUpdateResult?.timed_out
-        ? "gbrain check-update timed out before update status could be determined."
-      : updateStatus === "update-available"
-        ? "gbrain check-update reports a newer version."
-        : updateStatus === "up-to-date"
-          ? "gbrain check-update did not find a newer version."
-          : "gbrain update status is unknown.",
-    integrations_available: integrationsAvailable,
-    mcp_hosts: mcpHosts,
-    install_command: GBRAIN_INSTALL_COMMAND,
-    install_note: GBRAIN_INSTALL_NOTE,
-    upgrade_command: checkUpdateJson?.upgrade_command || "gbrain upgrade",
-    sync_command: "gbrain sync --repo <path>",
-    impact: {
-      complex_tasks: "unaffected",
-      simple_tasks: "unaffected",
-      knowledge_tasks: !present
-        ? "missing"
-        : mcpConfigured
-          ? "full"
-          : "manual-only",
-    },
-  };
-}
-
-function detectCodeGraphMcp(host) {
-  const meta = HOSTS[host];
-  const content = readText(meta.configPath);
-  function claudeEntryResult(entry, source) {
-    if (!entry || typeof entry !== "object") return null;
-    if (entry.alwaysLoad === true) {
-      return {
-        status: "configured",
-        always_load: true,
-        tool_search: "always-load",
-        reason: `${source} contains a codegraph MCP server entry with alwaysLoad=true.`,
-      };
-    }
-    return {
-      status: "deferred",
-      always_load: false,
-      tool_search: "deferred",
-      reason: `${source} contains a codegraph MCP server entry, but alwaysLoad is not true; Claude Code MCP Tool Search may defer CodeGraph tools.`,
-    };
-  }
-  function claudeTextFallback(source, sourcePath) {
-    return {
-      status: "deferred",
-      always_load: false,
-      tool_search: "unknown",
-      reason: `${source} contains a codegraph MCP server entry at ${sourcePath}, but alwaysLoad could not be verified.`,
-    };
-  }
-
-  if (!content) {
-    if (host === "claude") {
-      const claudeRootConfig = path.join(HOME, ".claude.json");
-      const rootJson = readJson(claudeRootConfig);
-      const rootEntry = claudeEntryResult(rootJson?.mcpServers?.codegraph, `Claude root config at ${claudeRootConfig}`);
-      if (rootEntry) return rootEntry;
-      const rootContent = readText(claudeRootConfig);
-      if (/codegraph/i.test(rootContent)) {
-        return claudeTextFallback("Claude root config", claudeRootConfig);
-      }
-    }
-
-    return {
-      status: "missing",
-      reason: `No ${meta.label} config found at ${meta.configPath}.`,
-    };
-  }
-
-  if (host === "codex") {
-    if (/\[mcp_servers\.codegraph\]/.test(content)) {
-      return {
-        status: "configured",
-        reason: "Codex config contains a codegraph MCP server entry.",
-      };
-    }
-
-    return {
-      status: "missing",
-      reason: "Codex config does not contain a codegraph MCP server entry.",
-    };
-  }
-
-  const settingsJson = readJson(meta.configPath);
-  const settingsEntry = claudeEntryResult(settingsJson?.mcpServers?.codegraph, `Claude settings at ${meta.configPath}`);
-  if (settingsEntry) return settingsEntry;
-  if (/"mcpServers"\s*:\s*{[\s\S]*"codegraph"/i.test(content)) {
-    return claudeTextFallback("Claude settings", meta.configPath);
-  }
-
-  const claudeRootConfig = path.join(HOME, ".claude.json");
-  const rootJson = readJson(claudeRootConfig);
-  const rootEntry = claudeEntryResult(rootJson?.mcpServers?.codegraph, `Claude root config at ${claudeRootConfig}`);
-  if (rootEntry) return rootEntry;
-  const rootContent = readText(claudeRootConfig);
-  if (/"mcpServers"\s*:\s*{[\s\S]*"codegraph"/i.test(rootContent)) {
-    return claudeTextFallback("Claude root config", claudeRootConfig);
-  }
-
-  return {
-    status: "missing",
-    reason: "Claude config does not contain a codegraph MCP server entry.",
-  };
-}
-
-function parseCodeGraphProjectStatus(output) {
-  if (/Not initialized/i.test(output)) return "not-initialized";
-  if (/Index is up to date/i.test(output)) return "up-to-date";
-  if (/Pending Changes/i.test(output) || /Run "codegraph sync/i.test(output)) return "stale";
-  if (/CodeGraph Status/i.test(output)) return "unknown";
-  return "unavailable";
-}
-
-function resolvePathCommand(command) {
-  const pathValue = process.env.PATH || "";
-  for (const dir of pathValue.split(path.delimiter)) {
-    if (!dir) continue;
-    const candidate = path.join(dir, command);
-    if (fileIsExecutable(candidate)) return candidate;
-  }
-  return null;
-}
-
-function codeGraphPackageDeclared() {
-  const pkg = readJson(path.join(REPO_ROOT, "package.json"));
-  if (!pkg || typeof pkg !== "object") return false;
-  return Boolean(
-    pkg.devDependencies?.[CODEGRAPH_PACKAGE] ||
-      pkg.dependencies?.[CODEGRAPH_PACKAGE] ||
-      pkg.optionalDependencies?.[CODEGRAPH_PACKAGE]
-  );
-}
-
-function codeGraphPlatformPackageName() {
-  return `${CODEGRAPH_PACKAGE}-${process.platform}-${process.arch}`;
-}
-
-function codeGraphPlatformBundleBin() {
-  if (process.platform === "win32") return null;
-  return path.join(REPO_ROOT, "node_modules", codeGraphPlatformPackageName(), "bin", "codegraph");
-}
-
-function resolveCodeGraphBinary() {
-  const allowRepoLocal = process.env.AGENTIC_DEV_CODEGRAPH_ALLOW_REPO_LOCAL !== "0";
-  const allowGlobal = process.env.AGENTIC_DEV_CODEGRAPH_ALLOW_GLOBAL !== "0";
-  const localCandidates = [];
-  const localOverride = process.env.AGENTIC_DEV_CODEGRAPH_LOCAL_BIN;
-  const globalOverride = process.env.AGENTIC_DEV_CODEGRAPH_GLOBAL_BIN;
-
-  if (localOverride) localCandidates.push(localOverride);
-  if (allowRepoLocal) {
-    localCandidates.push(codeGraphPlatformBundleBin());
-    localCandidates.push(path.join(REPO_ROOT, "node_modules", ".bin", "codegraph"));
-  }
-
-  let localBinPath = null;
-  for (const candidate of localCandidates) {
-    if (candidate && fileIsExecutable(candidate)) {
-      localBinPath = candidate;
-      break;
-    }
-  }
-
-  let globalBinPath = null;
-  if (allowGlobal) {
-    if (globalOverride && fileIsExecutable(globalOverride)) {
-      globalBinPath = globalOverride;
-    } else if (!globalOverride) {
-      globalBinPath = resolvePathCommand("codegraph");
-    }
-  }
-
-  if (localBinPath) {
-    return {
-      source: "local",
-      bin_path: localBinPath,
-      local_bin_path: localBinPath,
-      global_bin_path: globalBinPath,
-      global_fallback_used: false,
-    };
-  }
-
-  if (globalBinPath) {
-    return {
-      source: "global",
-      bin_path: globalBinPath,
-      local_bin_path: null,
-      global_bin_path: globalBinPath,
-      global_fallback_used: true,
-    };
-  }
-
-  return {
-    source: "missing",
-    bin_path: null,
-    local_bin_path: null,
-    global_bin_path: null,
-    global_fallback_used: false,
-  };
-}
-
-function codeGraphVersion(binPath) {
-  if (!binPath) return null;
-  const result = run(binPath, ["--version"], { timeoutMs: 1000 });
-  if (result.ok) return result.stdout.trim() || null;
-  if (result.timed_out) {
-    const retry = run(binPath, ["--version"], { timeoutMs: 1000 });
-    if (retry.ok) return retry.stdout.trim() || null;
-  }
-  return null;
-}
-
-function detectCodeGraph() {
-  const resolution = resolveCodeGraphBinary();
-  const cliPresent = Boolean(resolution.bin_path);
-  const version = codeGraphVersion(resolution.bin_path);
-  const globalVersion = resolution.global_bin_path && resolution.global_bin_path !== resolution.bin_path
-    ? codeGraphVersion(resolution.global_bin_path)
-    : resolution.source === "global"
-      ? version
-      : null;
-  const localVersion = resolution.source === "local" ? version : null;
-  const packageDeclared = codeGraphPackageDeclared();
-  const mcpHosts = {};
-
-  for (const host of SELECTED_HOSTS) {
-    mcpHosts[host] = {
-      label: HOSTS[host].label,
-      ...detectCodeGraphMcp(host),
-    };
-  }
-
-  const selectedMcpConfigured = SELECTED_HOSTS.every((host) => mcpHosts[host]?.status === "configured");
-  const statusResult = cliPresent ? run(resolution.bin_path, ["status", "."], { timeoutMs: 1500 }) : null;
-  const statusOutput = `${statusResult?.stdout || ""}\n${statusResult?.stderr || ""}`;
-  const projectIndexStatus = cliPresent ? parseCodeGraphProjectStatus(statusOutput) : "unavailable";
-  const indexInitialized = fs.existsSync(path.join(REPO_ROOT, ".codegraph"))
-    || ["up-to-date", "stale", "unknown"].includes(projectIndexStatus);
-  const updateResult = cliPresent && checkUpdates
-    ? run("npm", ["view", CODEGRAPH_PACKAGE, "version", "--json"], { timeoutMs: 3000 })
-    : null;
-  const latestVersion = updateResult?.ok ? (parseJson(updateResult.stdout) || updateResult.stdout.trim().replace(/^"|"$/g, "")) : null;
-  const updateStatus = !checkUpdates
-    ? "not-checked"
-    : latestVersion && version
-      ? (String(latestVersion) === String(version) ? "up-to-date" : "update-available")
-      : "unknown";
-  const localDependencyMissing = packageDeclared && resolution.source === "global";
-  const status = !cliPresent
-    ? "missing"
-    : localDependencyMissing || !selectedMcpConfigured || projectIndexStatus === "not-initialized" || projectIndexStatus === "unavailable"
-      ? "partial"
-      : projectIndexStatus === "stale" || projectIndexStatus === "unknown"
-        ? "warning"
-        : "present";
-
-  return {
-    name: "codegraph",
-    status,
-    reason: !cliPresent
-      ? "CodeGraph CLI is not installed."
-      : localDependencyMissing
-        ? "CodeGraph global fallback is present, but this repo declares a local dev dependency that is not installed."
-      : !selectedMcpConfigured
-        ? "CodeGraph CLI is present, but one or more selected host MCP configs are missing or deferred."
-        : projectIndexStatus === "not-initialized"
-          ? "CodeGraph CLI and MCP are present, but this repo has not been indexed."
-          : projectIndexStatus === "unavailable"
-            ? "CodeGraph CLI and MCP are present, but project index status could not be read."
-          : projectIndexStatus === "stale"
-            ? "CodeGraph is configured, but this repo index has pending changes."
-            : projectIndexStatus === "unknown"
-              ? "CodeGraph is configured, but this repo index status is unknown."
-            : "CodeGraph CLI, selected host MCP config, and project index are ready.",
-    package: CODEGRAPH_PACKAGE,
-    primary_host: "codex",
-    cli_present: cliPresent,
-    source: resolution.source,
-    bin_path: resolution.bin_path,
-    local_bin_path: resolution.local_bin_path,
-    global_bin_path: resolution.global_bin_path,
-    global_fallback_used: resolution.global_fallback_used,
-    version,
-    local_version: localVersion,
-    global_version: globalVersion,
-    dependency_declared: packageDeclared,
-    drift: localVersion && globalVersion && localVersion !== globalVersion
-      ? { local: localVersion, global: globalVersion, using: resolution.source }
-      : null,
-    latest_version: latestVersion,
-    update_status: updateStatus,
-    update_reason: !checkUpdates
-      ? "Update checks were skipped."
-      : updateResult?.timed_out
-        ? "CodeGraph npm version check timed out."
-        : latestVersion && version
-          ? (String(latestVersion) === String(version) ? "Local CodeGraph matches npm latest." : "npm reports a newer CodeGraph version.")
-          : "CodeGraph update status is unknown.",
-    mcp_hosts: mcpHosts,
-    project_index: {
-      status: projectIndexStatus,
-      initialized: indexInitialized,
-      path: path.join(REPO_ROOT, ".codegraph"),
-      command: "codegraph status .",
-    },
-    install_command: packageDeclared ? CODEGRAPH_LOCAL_INSTALL_COMMAND : CODEGRAPH_GLOBAL_INSTALL_COMMAND,
-    ensure_command: packageDeclared ? CODEGRAPH_ENSURE_BASH_COMMAND : null,
-    mcp_install_command: CODEGRAPH_MCP_CONFIGURE_COMMAND,
-    init_command: packageDeclared && CODEGRAPH_ENSURE_BASH_COMMAND ? `${CODEGRAPH_ENSURE_BASH_COMMAND} --init` : "codegraph init -i .",
-    sync_command: packageDeclared && CODEGRAPH_ENSURE_BASH_COMMAND ? `${CODEGRAPH_ENSURE_BASH_COMMAND} --sync` : "codegraph sync .",
-    upgrade_command: packageDeclared && CODEGRAPH_ENSURE_BASH_COMMAND ? `bun update @colbymchenry/codegraph && ${CODEGRAPH_ENSURE_BASH_COMMAND} --sync` : `bun add -g ${CODEGRAPH_PACKAGE}@latest && codegraph sync .`,
-    uninstall_command: "codegraph uninstall --target codex --location global --yes",
-    readiness: {
-      required_for: "codex-agent-code-navigation",
-      hook_policy: "do-not-block-hooks",
-      user_setup: "one-terminal-command-or-authorized-agent-action",
-    },
-    impact: {
-      code_navigation: status === "present" ? "full" : status === "warning" ? "stale-index" : "missing",
-      hook_correctness: "unaffected",
-    },
-  };
-}
-
-const wazaReport = detectWaza();
-const report = {
-  generated_at: new Date().toISOString(),
-  repo_root: REPO_ROOT,
-  hosts: SELECTED_HOSTS,
-  check_updates: checkUpdates,
-  runtime_capabilities: detectRuntimeCapabilities(wazaReport),
-  tools: {
-    gstack: detectGstack(),
-    waza: wazaReport,
-    codex_automation_profile: detectCodexAutomationProfile(),
-    gbrain: detectGbrain(),
-    codegraph: detectCodeGraph(),
-  },
-};
-
-const strictFailures = [];
-if (strictReadiness && ["missing", "partial"].includes(report.tools.codegraph.status)) {
-  strictFailures.push(`CodeGraph readiness is ${report.tools.codegraph.status}: ${report.tools.codegraph.reason}`);
-}
-
-function printText(result) {
-  console.log("External Tooling Report");
-  console.log(`Hosts: ${result.hosts.join(", ")}`);
-  console.log("");
-
-  console.log("Runtime capabilities");
-  for (const capability of Object.values(result.runtime_capabilities || {})) {
-    const required = capability.required ? "required" : "optional";
-    const pathBits = capability.path ? ` at ${capability.path}` : "";
-    console.log(`  - ${capability.name}: ${capability.status} (${required})${pathBits}`);
-    console.log(`    owner=${capability.owner}; required_for=${capability.required_for}`);
-  }
-  console.log("");
-
-  const gstack = result.tools.gstack;
-  console.log(`gstack [${gstack.status}]`);
-  for (const host of SELECTED_HOSTS) {
-    const entry = gstack.hosts[host];
-    const versionBits = entry.version ? ` v${entry.version}` : "";
-    const updateBits = entry.update_status && entry.update_status !== "not-checked" ? `, ${entry.update_status}` : "";
-    console.log(`  - ${entry.label}: ${entry.present ? "present" : "missing"}${versionBits}${updateBits}`);
-  }
-  console.log(`  - Team mode: ${gstack.repo_team_mode.status} (${gstack.repo_team_mode.reason})`);
-  console.log(`  - Impact: complex=${gstack.impact.complex_tasks}`);
-  console.log(`  - Install: ${gstack.install_command}`);
-  console.log(`  - Upgrade: ${gstack.upgrade_command}`);
-  console.log("");
-
-  const waza = result.tools.waza;
-  console.log(`Waza [${waza.status}]`);
-  console.log(`  - Source lock: ${waza.source_lock_file || "not found"}`);
-  console.log(`  - Primary: ${waza.primary_host} (${waza.codex_primary_path})`);
-  console.log(`  - Staging: ${waza.staging_cache_path}`);
-  console.log(`  - Skills CLI: ${waza.skills_cli_status}`);
-  for (const host of SELECTED_HOSTS) {
-    const entry = waza.hosts[host];
-    const versionBits = Object.entries(entry.versions)
-      .map(([name, version]) => `${name}@${version || "unknown"}`)
-      .join(", ");
-    console.log(`  - ${entry.label}: ${entry.status}, ${entry.installed_skills.length}/${waza.managed_skills.length} skills, sync=${entry.staging_sync}, stale=${entry.stale_status}`);
-    if (versionBits) {
-      console.log(`    versions: ${versionBits}`);
-    }
-    console.log(`    shared rules: ${entry.shared_rules.length}/${waza.shared_rules.length}, sync=${entry.shared_rules_staging_sync}, stale=${entry.shared_rules_stale_status}`);
-    if (entry.missing_skills.length) {
-      console.log(`    missing: ${entry.missing_skills.join(", ")}`);
-    }
-    if (entry.drift_skills.length) {
-      console.log(`    drift: ${entry.drift_skills.join(", ")}`);
-    }
-    if (entry.stale_skills.length) {
-      console.log(`    stale: ${entry.stale_skills.join(", ")}`);
-    }
-    if (entry.missing_shared_rules.length) {
-      console.log(`    missing shared rules: ${entry.missing_shared_rules.join(", ")}`);
-    }
-    if (entry.drift_shared_rules.length) {
-      console.log(`    drift shared rules: ${entry.drift_shared_rules.join(", ")}`);
-    }
-    if (entry.stale_shared_rules.length) {
-      console.log(`    stale shared rules: ${entry.stale_shared_rules.join(", ")}`);
-    }
-  }
-  console.log(`  - Updates: ${waza.update_status} (${waza.update_reason})`);
-  console.log(`  - Impact: simple=${waza.impact.simple_tasks}`);
-  console.log(`  - Install: ${waza.install_command}`);
-  console.log(`  - Stage: ${waza.stage_command}`);
-  console.log(`  - Sync Codex: ${waza.sync_command}`);
-  console.log(`  - Verify: ${waza.verify_command}`);
-  console.log("");
-
-  const codexAutomation = result.tools.codex_automation_profile;
-  console.log(`Codex automation profile [${codexAutomation.status}]`);
-  console.log(`  - Required: ${codexAutomation.required_skills.join(", ")}`);
-  console.log(`  - Source: ${codexAutomation.source}`);
-  console.log(`  - Mode: ${codexAutomation.mode}`);
-  if (codexAutomation.missing_skills.length) {
-    console.log(`  - Missing: ${codexAutomation.missing_skills.join(", ")}`);
-  }
-  console.log(`  - Routes: health=${codexAutomation.routes.workflow_health}, check=${codexAutomation.routes.review_gate}, diagram=${codexAutomation.routes.architecture_diagram}`);
-  console.log(`  - Vendoring: ${codexAutomation.vendoring_policy}`);
-  console.log("");
-
-  const gbrain = result.tools.gbrain;
-  console.log(`gbrain [${gbrain.status}]`);
-  console.log(`  - CLI: ${gbrain.cli_present ? `present${gbrain.version ? ` (v${gbrain.version})` : ""}` : "missing"}`);
-  if (gbrain.doctor?.status) {
-    console.log(`  - Doctor: ${gbrain.doctor.status} (score ${gbrain.doctor.health_score ?? "n/a"})`);
-  }
-  for (const host of SELECTED_HOSTS) {
-    const entry = gbrain.mcp_hosts[host];
-    console.log(`  - ${entry.label} MCP: ${entry.status}`);
-  }
-  if (gbrain.integrations_available) {
-    console.log(`  - Integrations available: ${gbrain.integrations_available}`);
-  }
-  console.log(`  - Updates: ${gbrain.update_status} (${gbrain.update_reason})`);
-  console.log(`  - Impact: knowledge=${gbrain.impact.knowledge_tasks}`);
-  console.log(`  - Install: ${gbrain.install_command}`);
-  console.log(`  - Upgrade: ${gbrain.upgrade_command}`);
-  console.log(`  - Manual sync: ${gbrain.sync_command}`);
-  console.log("");
-
-  const codegraph = result.tools.codegraph;
-  console.log(`CodeGraph [${codegraph.status}]`);
-  console.log(`  - CLI: ${codegraph.cli_present ? `present${codegraph.version ? ` (v${codegraph.version})` : ""} via ${codegraph.source}` : "missing"}`);
-  if (codegraph.drift) {
-    console.log(`  - Drift: local=${codegraph.drift.local}, global=${codegraph.drift.global}, using=${codegraph.drift.using}`);
-  }
-  for (const host of SELECTED_HOSTS) {
-    const entry = codegraph.mcp_hosts[host];
-    const suffix = entry.tool_search ? ` (${entry.tool_search})` : "";
-    console.log(`  - ${entry.label} MCP: ${entry.status}${suffix}`);
-  }
-  console.log(`  - Project index: ${codegraph.project_index.status}`);
-  console.log(`  - Updates: ${codegraph.update_status} (${codegraph.update_reason})`);
-  console.log(`  - Impact: code-navigation=${codegraph.impact.code_navigation}, hooks=${codegraph.impact.hook_correctness}`);
-  console.log(`  - Install deps: ${codegraph.install_command}`);
-  if (codegraph.ensure_command) {
-    console.log(`  - Ensure: ${codegraph.ensure_command}`);
-  }
-  console.log(`  - Init index: ${codegraph.init_command}`);
-  console.log(`  - Sync index: ${codegraph.sync_command}`);
-}
-
-if (jsonOutput) {
-  console.log(JSON.stringify(report, null, 2));
-} else {
-  printText(report);
-}
-
-if (strictFailures.length > 0) {
-  for (const failure of strictFailures) {
-    console.error(`[readiness] ${failure}`);
-  }
-  process.exit(2);
-}
-NODE_EOF
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "check-agent-tooling.sh" "$@"