impel-cli 0.15.3 → 0.16.1

package/src/installRecovery/tools.js

@@ -0,0 +1,648 @@
+// Typed local tool registry for install recovery.
+//
+// The recovery model never receives shell access: it selects one of these
+// tools by name and the CLI runs the corresponding reviewed implementation.
+// Every result is redacted and bounded before it can reach the model.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  environmentValue,
+  findNativeBinary,
+  nativeCommandInvocation,
+  nativeSpawnInvocation,
+} from "../nativeProcess.js";
+import { IMPEL_CLI_PROFILES_DIR, tenantCliProfilePaths } from "../cliProfiles.js";
+import { CONFIG_DIR } from "../config.js";
+import { redactInstallRecoveryText } from "./redact.js";
+
+const MAX_OUTPUT_CHARS = 8_000;
+const BINARY_TOOLS = ["claude", "codex", "npm", "node", "powershell"];
+
+/**
+ * Risk classes decide who has to approve a call:
+ *   read   — no approval; inspects state only.
+ *   safe   — mutates only Impel-owned state or retries an idempotent step;
+ *            pre-approved by an explicit `--repair`, otherwise confirmed.
+ *   system — runs a vendor installer or edits the user PATH; always requires
+ *            an interactive confirmation.
+ */
+export const INSTALL_RECOVERY_TOOLS = Object.freeze({
+  inspect_runtime: {
+    risk: "read",
+    description:
+      "Report bounded runtime facts: OS, architecture, Node.js version, PATH entry count, and TTY state. Call this first when the failure cause is unclear.",
+    schema: {},
+  },
+  inspect_path: {
+    risk: "read",
+    description:
+      "List sanitized PATH entries and whether each directory exists. Use when a tool installed correctly but is not discoverable.",
+    schema: {},
+  },
+  inspect_processes: {
+    risk: "read",
+    description:
+      "List running processes relevant to installers (claude, codex, node, npm, powershell, installers). Use for EBUSY/EPERM/locked-file failures.",
+    schema: {},
+  },
+  check_binary: {
+    risk: "read",
+    description:
+      "Locate one executable and run its bounded `--version` check. Reports the discovered path and version output.",
+    schema: {
+      tool: { type: "string", enum: BINARY_TOOLS, required: true },
+    },
+  },
+  read_profile: {
+    risk: "read",
+    description:
+      "Read a bounded, sanitized copy of one Impel-owned profile file (Claude settings.json or Codex config.toml). Use to diagnose profile parse or configuration errors.",
+    schema: {
+      profile: { type: "string", enum: ["claude_settings", "codex_config"], required: true },
+    },
+  },
+  probe_gateway: {
+    risk: "read",
+    description:
+      "Run a synthetic authenticated probe against the Impel gateway. Reports reachable/rejected status; never sends user content.",
+    schema: {},
+  },
+  check_auth_helper: {
+    risk: "read",
+    description:
+      "Run the tenant's Impel-owned app token helper with a bounded timeout and classify the result (works, missing, stale interpreter/CLI path, or failing). Use when managed apps report auth/credential failures.",
+    schema: {},
+  },
+  check_health: {
+    risk: "read",
+    description:
+      "Run every goal health check for this recovery session and report pass/fail per goal. The installation counts as fixed only when all goals pass. Call this after any repair.",
+    schema: {},
+  },
+  repair_impel_profile: {
+    risk: "safe",
+    description:
+      "Atomically regenerate the Impel-managed CLI profiles (Claude settings + Codex config) for the selected tenant. Touches only Impel-owned files.",
+    schema: {},
+  },
+  cleanup_impel_staging: {
+    risk: "safe",
+    description:
+      "Remove validated stale Impel-owned staging directories (interrupted installs). Only exact known staging roots are eligible; no paths can be supplied.",
+    schema: {},
+  },
+  retry_step: {
+    risk: "safe",
+    description:
+      "Re-run one idempotent installer step that failed (for example the npm self-update or the gateway verification). Use after fixing the underlying cause.",
+    schema: {
+      step: { type: "string", required: true, maxLength: 128 },
+    },
+  },
+  install_vendor_cli: {
+    risk: "system",
+    description:
+      "Run the official vendor installer for one missing CLI (Windows only). Uses the vendor's checksum-verifying native installer; requires the user's confirmation.",
+    schema: {
+      tool: { type: "string", enum: ["claude", "codex"], required: true },
+    },
+  },
+  install_vendor_app: {
+    risk: "system",
+    description:
+      "Install or rebuild the isolated Impel desktop app profile(s) using the signed vendor app. Requires the user's confirmation.",
+    schema: {
+      target: { type: "string", enum: ["claude", "codex", "all"], required: true },
+    },
+  },
+  repair_user_path: {
+    risk: "system",
+    description:
+      "Add one verified vendor install directory to the user PATH (Windows only). The directory comes from local discovery, never from you. Requires the user's confirmation.",
+    schema: {
+      tool: { type: "string", enum: ["claude", "codex"], required: true },
+    },
+  },
+  report_outcome: {
+    risk: "read",
+    description:
+      "Finish the recovery session. Use status \"fixed\" only after check_health reports every goal passing; otherwise use \"blocked\" and give the user one concrete manual step.",
+    schema: {
+      status: { type: "string", enum: ["fixed", "blocked"], required: true },
+      summary: { type: "string", required: true, maxLength: 2_000 },
+      user_action: { type: "string", maxLength: 2_000 },
+    },
+  },
+});
+
+export function installRecoveryToolDefinitions() {
+  return Object.entries(INSTALL_RECOVERY_TOOLS).map(([name, tool]) => ({
+    name,
+    description: tool.description,
+    input_schema: {
+      type: "object",
+      properties: Object.fromEntries(
+        Object.entries(tool.schema).map(([key, spec]) => [
+          key,
+          { type: spec.type, ...(spec.enum ? { enum: spec.enum } : {}) },
+        ])
+      ),
+      required: Object.entries(tool.schema)
+        .filter(([, spec]) => spec.required)
+        .map(([key]) => key),
+      additionalProperties: false,
+    },
+  }));
+}
+
+/** Validate a model-proposed call. Returns normalized input or null. */
+export function validateInstallRecoveryToolCall(name, input) {
+  const tool = INSTALL_RECOVERY_TOOLS[name];
+  if (!tool) return null;
+  const value = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const keys = Object.keys(tool.schema);
+  if (!Object.keys(value).every((key) => keys.includes(key))) return null;
+  const normalized = {};
+  for (const key of keys) {
+    const spec = tool.schema[key];
+    const supplied = value[key];
+    if (supplied === undefined || supplied === null) {
+      if (spec.required) return null;
+      continue;
+    }
+    if (typeof supplied !== "string") return null;
+    if (spec.enum && !spec.enum.includes(supplied)) return null;
+    if (supplied.length > (spec.maxLength || 512)) return null;
+    normalized[key] = supplied;
+  }
+  return normalized;
+}
+
+export function installRecoveryToolRisk(name) {
+  return INSTALL_RECOVERY_TOOLS[name]?.risk || null;
+}
+
+function result(outcome, summary, details = {}) {
+  return {
+    outcome,
+    summary: redactInstallRecoveryText(summary).slice(0, 2_000),
+    ...(details.output
+      ? { output: redactInstallRecoveryText(details.output).slice(0, MAX_OUTPUT_CHARS) }
+      : {}),
+    ...(Number.isInteger(details.exitCode) ? { exitCode: details.exitCode } : {}),
+  };
+}
+
+function runBounded(io, command, args, context, options = {}) {
+  return io.spawnSync(command, args, {
+    encoding: "utf8",
+    env: context.environment,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeout || 15_000,
+    windowsHide: true,
+    ...(options.windowsVerbatimArguments !== undefined
+      ? { windowsVerbatimArguments: options.windowsVerbatimArguments }
+      : {}),
+  });
+}
+
+function inspectRuntime(context) {
+  const pathEntries = String(environmentValue(context.environment, "PATH") || "")
+    .split(context.platform === "win32" ? ";" : path.delimiter)
+    .filter(Boolean);
+  return result("succeeded", "Collected bounded runtime metadata.", {
+    output: JSON.stringify({
+      platform: context.platform,
+      architecture: process.arch,
+      nodeVersion: process.version,
+      pathEntries: pathEntries.length,
+      tty: Boolean(context.isTTY),
+      tenantSelected: Boolean(context.tenantId),
+    }),
+  });
+}
+
+function inspectPath(context) {
+  const entries = String(environmentValue(context.environment, "PATH") || "")
+    .split(context.platform === "win32" ? ";" : path.delimiter)
+    .filter(Boolean)
+    .slice(0, 64)
+    .map((entry) => {
+      let exists = false;
+      try {
+        exists = fs.statSync(entry).isDirectory();
+      } catch {
+        exists = false;
+      }
+      return `${exists ? "ok " : "missing "}${entry}`;
+    });
+  return result("succeeded", `PATH has ${entries.length} inspected entries.`, {
+    output: entries.join("\n"),
+  });
+}
+
+function inspectProcesses(context, io) {
+  const invocation = context.platform === "win32"
+    ? { command: "tasklist.exe", args: ["/fo", "csv", "/nh"] }
+    : { command: "ps", args: ["-Ao", "comm="] };
+  const run = runBounded(io, invocation.command, invocation.args, context, { timeout: 10_000 });
+  if (run?.error || run?.status !== 0) {
+    return result("failed", "Could not inspect running installer processes.", {
+      exitCode: run?.status,
+      output: run?.error?.message || run?.stderr,
+    });
+  }
+  const relevant = String(run.stdout || "")
+    .split(/\r?\n/gu)
+    .filter((line) => /claude|chatgpt|codex|impel|node|npm|powershell|msiexec|installer/iu.test(line))
+    .slice(0, 40)
+    .join("\n");
+  return result(
+    "succeeded",
+    relevant ? "Found potentially relevant running processes." : "No relevant running process was found.",
+    { output: relevant || "none" }
+  );
+}
+
+function checkBinary(input, context, io) {
+  const binary = io.findNativeBinary(input.tool, context.environment, context.platform);
+  if (!binary) {
+    return result("failed", `${input.tool} is not installed or not discoverable on PATH or in known install locations.`);
+  }
+  const invocation = nativeSpawnInvocation(binary, ["--version"], context.environment, context.platform);
+  const run = runBounded(io, invocation.command, invocation.args, context, {
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+  });
+  return run?.status === 0 && !run?.error
+    ? result("succeeded", `${input.tool} passed its bounded version check.`, {
+        output: `path: ${binary}\nversion: ${String(run.stdout || "").trim()}`,
+      })
+    : result("failed", `${input.tool} was found but failed its bounded version check.`, {
+        exitCode: run?.status,
+        output: `path: ${binary}\n${run?.error?.message || run?.stderr || ""}`,
+      });
+}
+
+function readProfile(input, context) {
+  if (!context.tenantId) return result("failed", "No tenant is selected; profiles have not been created yet.");
+  const paths = tenantCliProfilePaths(context.tenantId);
+  const filePath = input.profile === "claude_settings"
+    ? path.join(paths.claudeConfigDir, "settings.json")
+    : path.join(paths.codexHome, "config.toml");
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    return result("failed", `The profile file could not be read (${error?.code || error?.message}).`);
+  }
+  return result("succeeded", `Read the Impel-owned ${input.profile} profile.`, {
+    output: raw.slice(0, 4_000),
+  });
+}
+
+function checkAuthHelper(context, io) {
+  if (!context.tenantId) {
+    return result("failed", "No tenant is selected; the app token helper has not been created yet.");
+  }
+  if (context.platform === "win32") {
+    return result("failed", "Windows managed apps do not use a shell token helper; check the CLI profiles instead.");
+  }
+  const helperPath = path.join(
+    CONFIG_DIR,
+    "apps",
+    "tenants",
+    context.tenantId,
+    "bin",
+    "token"
+  );
+  if (!fs.existsSync(helperPath)) {
+    return result("failed", "The tenant app token helper is missing; repair_impel_profile regenerates it.");
+  }
+  const run = io.spawnSync(helperPath, [], {
+    encoding: "utf8",
+    env: context.environment,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 20_000,
+    windowsHide: true,
+  });
+  if (run?.error) {
+    return result("failed", `The app token helper could not be executed (${run.error.code || run.error.message}).`);
+  }
+  if (run.status === 0 && /impel_/u.test(String(run.stdout || ""))) {
+    return result("succeeded", "The app token helper runs and emits a credential.");
+  }
+  const stderr = String(run.stderr || "");
+  const classified = /Cannot find module|MODULE_NOT_FOUND/iu.test(stderr)
+    ? "its embedded impel-cli path no longer exists"
+    : /No such file or directory|not found|no usable node/iu.test(stderr)
+      ? "its embedded node runtime path no longer exists"
+      : /SyntaxError/iu.test(stderr)
+        ? "it points at an incompatible impel-cli checkout"
+        : "it exited without emitting a credential";
+  return result(
+    "failed",
+    `The app token helper is broken: ${classified}. repair_impel_profile rewrites it with current paths.`,
+    { exitCode: run.status, output: stderr.slice(0, 2_000) }
+  );
+}
+
+async function probeGateway(context) {
+  if (typeof context.probeGateway !== "function") {
+    return result("failed", "Gateway verification is unavailable in this recovery context.");
+  }
+  const probe = await context.probeGateway();
+  if (probe?.reachable && !probe?.rejected) {
+    return result("succeeded", `Gateway responded with HTTP ${probe.status}.`);
+  }
+  return result(
+    "failed",
+    probe?.rejected
+      ? `Gateway rejected the credential with HTTP ${probe.status}. A fresh PAT from the Impel gateway settings page usually fixes this.`
+      : `Gateway could not be reached: ${probe?.error || "unknown error"}.`
+  );
+}
+
+async function checkHealth(context) {
+  if (typeof context.runGoals !== "function") {
+    return result("failed", "No goal health checks were configured for this session.");
+  }
+  const report = await context.runGoals();
+  const lines = report.results.map(
+    (goal) => `${goal.ok ? "pass" : "FAIL"} ${goal.id}: ${goal.description}${goal.detail ? ` — ${goal.detail}` : ""}`
+  );
+  return result(
+    report.passed ? "succeeded" : "failed",
+    report.passed
+      ? "All goal health checks pass."
+      : `${report.results.filter((goal) => !goal.ok).length} goal health check(s) still failing.`,
+    { output: lines.join("\n") || "no goals configured" }
+  );
+}
+
+async function repairImpelProfile(context) {
+  if (typeof context.repairProfiles !== "function") {
+    return result("failed", "Impel profile repair is unavailable in this recovery context.");
+  }
+  const outcome = await context.repairProfiles();
+  return outcome === false
+    ? result("failed", "The Impel profile could not be repaired.")
+    : result("succeeded", "The Impel-managed profiles were regenerated.");
+}
+
+const STAGING_ENTRY_RE = /\.(?:tmp|previous)-\d+$/u;
+const STAGING_SCAN_DEPTH = 6;
+const STAGING_SCAN_LIMIT = 40;
+
+function managedStagingPath(candidate, roots) {
+  const resolved = path.resolve(candidate);
+  return roots.some((root) => {
+    const managedRoot = `${path.resolve(root)}${path.sep}`;
+    return resolved.startsWith(managedRoot) && STAGING_ENTRY_RE.test(path.basename(resolved));
+  });
+}
+
+/** Impel-owned roots that installer staging artifacts can appear under. */
+export function impelManagedStagingRoots(environment = process.env) {
+  const roots = [
+    path.join(CONFIG_DIR, "apps"),
+    IMPEL_CLI_PROFILES_DIR,
+    path.join(CONFIG_DIR, "vendor"),
+  ];
+  const appHome = environmentValue(environment, "IMPEL_APP_HOME");
+  if (appHome) roots.push(appHome);
+  return roots;
+}
+
+/** Bounded walk of the managed roots for `*.tmp-<pid>` / `*.previous-<pid>` leftovers. */
+export function discoverImpelStagingPaths(roots, io = { readdirSync: fs.readdirSync }) {
+  const found = [];
+  const walk = (directory, depth) => {
+    if (depth > STAGING_SCAN_DEPTH || found.length >= STAGING_SCAN_LIMIT) return;
+    let entries;
+    try {
+      entries = io.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (found.length >= STAGING_SCAN_LIMIT) return;
+      const full = path.join(directory, entry.name);
+      if (STAGING_ENTRY_RE.test(entry.name)) {
+        found.push(full);
+        continue;
+      }
+      if (entry.isDirectory() && !entry.isSymbolicLink()) walk(full, depth + 1);
+    }
+  };
+  for (const root of roots) walk(root, 0);
+  return found;
+}
+
+function cleanupStaging(context, io) {
+  const roots = context.managedRoots || impelManagedStagingRoots(context.environment);
+  const candidates = context.stagingPaths
+    || discoverImpelStagingPaths(roots, { readdirSync: io.readdirSync || fs.readdirSync });
+  const removable = candidates.filter((candidate) => managedStagingPath(candidate, roots));
+  for (const candidate of removable) {
+    io.rmSync(candidate, { recursive: true, force: true });
+  }
+  return result(
+    "succeeded",
+    removable.length
+      ? `Removed ${removable.length} stale Impel-owned staging path(s).`
+      : "No validated stale Impel staging path was present.",
+    removable.length ? { output: removable.join("\n") } : {}
+  );
+}
+
+async function retryStep(input, context) {
+  if (typeof context.retryStep !== "function") {
+    return result("failed", "The failed step cannot be retried in this process.");
+  }
+  const outcome = await context.retryStep(input.step);
+  return outcome === false
+    ? result("failed", "The step failed again.")
+    : result("succeeded", "The step completed on retry.");
+}
+
+async function installVendorCli(input, context) {
+  if (context.platform !== "win32" || typeof context.installVendorClis !== "function") {
+    return result("failed", "Automated vendor CLI installation is unavailable on this platform.");
+  }
+  const outcome = await context.installVendorClis(input.tool);
+  return outcome?.binaries?.[input.tool]
+    ? result("succeeded", `${input.tool} installed and passed verification.`)
+    : result("failed", `${input.tool} installation did not reach a verified state.`);
+}
+
+async function installVendorApp(input, context) {
+  if (typeof context.installVendorApp !== "function") {
+    return result("failed", "Vendor app installation is unavailable in this recovery context.");
+  }
+  const installed = await context.installVendorApp(input.target);
+  return installed === false
+    ? result("failed", `The ${input.target} vendor app did not install cleanly.`)
+    : result("succeeded", `The ${input.target} vendor app installation completed.`);
+}
+
+function repairUserPath(input, context, io) {
+  if (context.platform !== "win32") {
+    return result("failed", "User PATH repair is currently available only on Windows.");
+  }
+  const binary = io.findNativeBinary(input.tool, context.environment, context.platform);
+  if (!binary || !path.win32.isAbsolute(binary)) {
+    return result("failed", `${input.tool} has no trusted absolute install path to add.`);
+  }
+  const verification = nativeSpawnInvocation(binary, ["--version"], context.environment, "win32");
+  const verified = runBounded(io, verification.command, verification.args, context, {
+    windowsVerbatimArguments: verification.windowsVerbatimArguments,
+  });
+  if (verified?.status !== 0 || verified?.error) {
+    return result("failed", `${input.tool}'s discovered install path did not pass its bounded version check.`, {
+      exitCode: verified?.status,
+      output: verified?.error?.message || verified?.stderr,
+    });
+  }
+  const directory = path.win32.dirname(binary);
+  const currentPath = String(environmentValue(context.environment, "PATH") || "");
+  const entries = currentPath.split(";").filter(Boolean);
+  if (!entries.some((entry) => entry.toLowerCase() === directory.toLowerCase())) {
+    context.environment.PATH = [directory, currentPath].filter(Boolean).join(";");
+  }
+  const powershell = nativeCommandInvocation(
+    "powershell",
+    [
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      "$d=$env:IMPEL_RECOVERY_PATH; $p=[Environment]::GetEnvironmentVariable('Path','User'); $a=@($p -split ';' | Where-Object { $_ }); if (-not ($a | Where-Object { $_ -ieq $d })) { [Environment]::SetEnvironmentVariable('Path',(($a + $d) -join ';'),'User') }",
+    ],
+    context.environment,
+    "win32"
+  );
+  const run = io.spawnSync(powershell.command, powershell.args, {
+    encoding: "utf8",
+    env: { ...context.environment, IMPEL_RECOVERY_PATH: directory },
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 15_000,
+    windowsHide: true,
+    windowsVerbatimArguments: powershell.windowsVerbatimArguments,
+  });
+  return run?.status === 0 && !run?.error
+    ? result("succeeded", `${input.tool}'s trusted install directory was added to the user PATH.`)
+    : result("failed", `Could not add ${input.tool}'s install directory to the user PATH.`, {
+        exitCode: run?.status,
+        output: run?.error?.message || run?.stderr,
+      });
+}
+
+/**
+ * Execute one validated tool call. `context.confirmed` must already reflect
+ * the approval decision for mutating tools; unconfirmed mutations return a
+ * "declined" result instead of running.
+ */
+export async function executeInstallRecoveryTool(name, rawInput, context = {}, dependencies = {}) {
+  const input = validateInstallRecoveryToolCall(name, rawInput);
+  if (input === null) {
+    return result("failed", "Refused an unknown or malformed recovery tool call.");
+  }
+  const risk = installRecoveryToolRisk(name);
+  if (risk !== "read" && context.confirmed !== true) {
+    return result("declined", "The local mutation was not approved on this machine.");
+  }
+  const resolvedContext = {
+    platform: process.platform,
+    environment: process.env,
+    isTTY: process.stdin.isTTY,
+    ...context,
+  };
+  const io = { spawnSync, findNativeBinary, rmSync: fs.rmSync, ...dependencies };
+  switch (name) {
+    case "inspect_runtime": return inspectRuntime(resolvedContext);
+    case "inspect_path": return inspectPath(resolvedContext);
+    case "inspect_processes": return inspectProcesses(resolvedContext, io);
+    case "check_binary": return checkBinary(input, resolvedContext, io);
+    case "read_profile": return readProfile(input, resolvedContext);
+    case "check_auth_helper": return checkAuthHelper(resolvedContext, io);
+    case "probe_gateway": return probeGateway(resolvedContext);
+    case "check_health": return checkHealth(resolvedContext);
+    case "repair_impel_profile": return repairImpelProfile(resolvedContext);
+    case "cleanup_impel_staging": return cleanupStaging(resolvedContext, io);
+    case "retry_step": return retryStep(input, resolvedContext);
+    case "install_vendor_cli": return installVendorCli(input, resolvedContext);
+    case "install_vendor_app": return installVendorApp(input, resolvedContext);
+    case "repair_user_path": return repairUserPath(input, resolvedContext, io);
+    case "report_outcome":
+      return result("succeeded", "Outcome recorded.");
+    default:
+      return result("failed", "Refused an unregistered recovery tool.");
+  }
+}
+
+/**
+ * Known-fingerprint repairs that run before any inference. Each entry is a
+ * tool call the engine executes under the normal approval rules.
+ */
+export function deterministicInstallRecoveryPlan(failure, platform = process.platform) {
+  const text = `${failure.step} ${failure.errorCode || ""} ${failure.message}`.toLowerCase();
+  const plan = [];
+  if (/profile|config\.toml|settings\.json/u.test(text)) {
+    plan.push({
+      tool: "repair_impel_profile",
+      input: {},
+      reason: "The failure mentions an Impel-managed profile file; regenerate it.",
+    });
+  }
+  if (/staging|\.tmp-|incomplete app/u.test(text)) {
+    plan.push({
+      tool: "cleanup_impel_staging",
+      input: {},
+      reason: "The failure mentions stale staging state from an interrupted install.",
+    });
+  }
+  if (platform === "win32" && /installer completed.*not.*verif|not discoverable|stale path/u.test(text)) {
+    const tool = /claude/u.test(text) ? "claude" : /codex/u.test(text) ? "codex" : null;
+    if (tool) {
+      plan.push({
+        tool: "repair_user_path",
+        input: { tool },
+        reason: "The installer finished but the command is not on PATH; add the verified install directory.",
+      });
+    }
+  }
+  if (/busy|eperm|ebusy|locked/u.test(text)) {
+    plan.push({
+      tool: "inspect_processes",
+      input: {},
+      reason: "The failure looks like a file lock; find the blocking process.",
+    });
+  }
+  if (/npm install|self-update|update failed/u.test(text)) {
+    plan.push({
+      tool: "retry_step",
+      input: { step: failure.step },
+      reason: "Transient npm/network failures often succeed on a clean retry.",
+    });
+  }
+  if (/provider auth command|cannot find module|module_not_found|token helper/u.test(text)) {
+    plan.push(
+      {
+        tool: "check_auth_helper",
+        input: {},
+        reason: "The failure mentions the app auth helper; classify how it is broken.",
+      },
+      {
+        tool: "repair_impel_profile",
+        input: {},
+        reason: "Regenerating Impel-owned profiles rewrites the token helper with current paths.",
+      }
+    );
+  }
+  return plan;
+}