zelari-code 1.3.0 → 1.4.1

package/README.md

@@ -37,6 +37,30 @@
 > `src/main/core/`, `src/agents/`, `src/shared/`, `src/types/` paths no longer
 > exist. The published core package is `@zelari/core` (MIT). 9 subpath exports.
 
+## Prerequisites
+
+| Requirement | Version | Notes |
+|---|---|---|
+| **Node.js** | **≥ 20 LTS** | Earlier versions lack stable `fetch`, `AbortController.timeout`, and `node:test`. Works on 20.x and 22.x. |
+| **npm** | **≥ 10** | Ships with Node 20 LTS; tested with npm 10 and 11. |
+| **OS** | Linux, macOS, Windows 10/11 | Tested on Pop!_OS 24.04, macOS 15, Windows 11. Windows requires Git Bash (auto-detected). |
+| **Disk** | ~50 MB for the CLI + `@zelari/core` | Models are not bundled — provider APIs are remote. |
+| **Account + API key** | 1 of: xAI Grok, OpenAI-compatible, GLM/Z.AI, MiniMax, DeepSeek | OAuth Grok supported via `/login grok`. |
+
+### Optional (for v1.3.0 advanced tools)
+
+These are **opt-in** — the CLI runs fine without them. The agent auto-skips a tool if its dependency is missing.
+
+| Tool group | Dependency | Used by |
+|---|---|---|
+| `lsp_*` | Language server on PATH (e.g. `typescript-language-server`, `pyright-langserver`) + Node/Python LSP client libs | `lsp_definition`, `lsp_references`, `lsp_hover`, `lsp_symbols`, `lsp_rename` |
+| `ast_*` | *(none)* | `ast_outline`, `ast_find_symbol` — TypeScript Compiler API, no LSP needed |
+| `semantic_search` | Local embedding model (default `Xenova/all-MiniLM-L6-v2` via `@xenova/transformers`, downloads on first use) | `semantic_search`, `/index` |
+| `browser_check` | Playwright (`npx playwright install chromium` once, ~150 MB) | `browser_check` |
+| diagnostics loop | `eslint` and/or `ruff` on PATH (project-local preferred) | post-edit compile/lint feedback |
+
+Disable any tool group: set `ZELARI_LSP=0`, `ZELARI_AST=0`, `ZELARI_SEMANTIC=0`, `ZELARI_BROWSER=0`, `ZELARI_DIAGNOSTICS=0`.
+
 ## Install
 
 ```bash
@@ -44,7 +68,23 @@ npm install -g zelari-code
 zelari-code
 ```
 
-Requires **Node.js ≥ 20**.
+**Prerequisites:**
+- **Node.js ≥ 20** — required. Without it the agent cannot run `npm`/`tsc`/builds, so zelari-code refuses to boot.
+- **Git** — recommended. Without it, `/diff`, `/undo` and the git sidebar are disabled. Install from <https://git-scm.com>.
+- **Git Bash** (Windows only) — recommended. The agent's `bash` tool needs real POSIX semantics (`ls`, `which`, `$VAR`, `&&`). Ships with Git for Windows.
+
+After install, verify your environment:
+
+```bash
+zelari-code --doctor   # checks shim, bundle, PATH, node/git/bash in the agent shell
+```
+
+> **Why `--doctor` matters on Windows:** the agent runs commands through Git
+> Bash, which inherits a different `PATH` than the Node process. Node can be
+> visible to PowerShell yet invisible to Git Bash (typical when Node was
+> installed for "current user" only). `--doctor`'s `node (agent shell)` row
+> catches this; the boot-time preflight (`runPreflight`) blocks the launch
+> with an actionable message instead of letting the agent fail mid-task.
 
 ### `zelari-code: command not found` (Windows)
 
@@ -64,6 +104,8 @@ source ~/.bashrc
 
 Verify the fix: `where zelari-code` (CMD) or `which zelari-code` (Bash) should print a path.
 
+**Node visible to PowerShell but not to Git Bash?** This is the dual-PATH problem: Node installed for "current user" only reaches the user shell, while Git Bash inherits the system `Path`. Fix: reinstall Node with "Add to PATH for **all users**", or add `C:\Program Files\nodejs\` to the **System** `Path` (not User). Confirm with `zelari-code --doctor` — the `node (agent shell)` row must read OK.
+
 ## First Run
 
 The first time you run `zelari-code` (or whenever your provider config
@@ -72,7 +114,7 @@ the regular TUI:
 
 ```
 ╭─────────────────────────────────────────────────╮
-│ zelari-code v0.6.0 — first-time setup    │
+│ zelari-code v1.3.0 — first-time setup    │
 │ 1/welcome  2/provider  3/model  4/apikey  5/...│
 │                                                 │
 │ Welcome! Let's get you coding in under 2 min.   │
@@ -146,8 +188,12 @@ Full reference: **[docs/GUIDA.md](./docs/GUIDA.md#comandi-slash)** (all flags, e
 | `/steer <text>`, `/steer --interrupt <text>` | Queue follow-up during a run |
 | `/workspace …` | `.zelari/` artifacts + `AGENTS.MD` |
 | `/update`, `/update --yes` | Check / install CLI updates |
+| `/mode [agent\|council\|zelari]` | Switch dispatch mode (shift+tab fallback) |
+| `/checkpoint [label]` | Snapshot the working tree (rollback target) |
+| `/rollback [id\|latest]` | Restore a checkpoint (revert / restore files atomically) |
+| `/index` | Build / refresh the semantic search index |
 
-**TUI:** `shift+tab` cycles **agent** → **council** → **zelari** mode for free-form prompts.
+**TUI:** `shift+tab` cycles **agent** → **council** → **zelari** mode for free-form prompts (with terminal-fallback hardening since v1.3.0). The equivalent command `/mode [agent|council|zelari]` works in any terminal.
 
 ## Headless Mode
 
@@ -185,6 +231,14 @@ Disable auto-check: `ANATHEMA_DEV=1 zelari-code`
 - ⏱️ **Execution timer** — elapsed time of the in-flight turn in the status line (`⏱ 12s`), frozen as `last 34s` when the run completes
 - 🧠 **Provider-agnostic** — OpenAI-compatible APIs (OpenAI, Together, Groq, custom), xAI Grok with OAuth refresh, GLM/Z.AI
 - 🛠️ **Built-in tools** — filesystem (read/write/edit), shell (bash), search (grep), web fetch/search
+- 🧠 **LSP code intelligence** (`lsp_*` tools) — go-to-definition, find references, hover type, document symbols, rename symbol via real language servers (tsserver, pyright, …)
+- 🌲 **AST structural tools** (`ast_*` tools) — symbol outline + find-by-name via the TypeScript compiler API, no language server needed
+- 🔎 **Semantic search** (`semantic_search` + `/index`) — concept-level code search via embeddings, local-first
+- 🌐 **Browser verification** (`browser_check`) — headless browser with click/fill/goto/wait actions, console + network + screenshot capture for visual verification of web work
+- 🔁 **Post-edit diagnostics loop** — after every `edit_file`/`write_file` the harness runs project lint/compile (`eslint`, `ruff`, LSP-pluggable) and surfaces the errors to the model in the same turn (opt out: `ZELARI_DIAGNOSTICS=0`)
+- 💾 **Prompt-cache accounting** — tracks prompt-cache hit rate per provider/model and surfaces it in the status bar (`cache 73%`) so you can see when a session is amortizing its prefix
+- 🧷 **Workspace checkpoints** — `/checkpoint [label]` + `/rollback [id|latest]` use git plumbing to snapshot the working tree (tracked + untracked) and restore it atomically; every zelari-mode mission takes one before starting
+- 🤝 **Sub-agent delegation** (`task` tool) — delegate a focused read-only research sub-task to an isolated sub-agent with its own fresh context, max 12 tool turns, no write/bash/recursion
 - 📚 **23 coding skills** (+ user `SKILL.md` from `.zelari/skills/`, `.claude/skills/`, …)
 - 🔄 **Cross-provider failover** — automatic retry with provider swap on transient errors
 - 📊 **Metrics + skill history** — fire-and-forget logging to `~/.tmp/zelari-code/`
@@ -232,6 +286,16 @@ zelari-code (CLI, proprietary)
 | `ZELARI_MISSION_AUTO=1` | Auto-start Zelari missions (skip the brief confirmation) |
 | `ZELARI_MISSION_MAX_ITER` | Max Zelari mission iterations (default 10) |
 | `ZELARI_MODE_MAX_TOOLS_LUCIFER` | Chairman (Lucifero) tool budget in zelari-mode (default 30) |
+| `ZELARI_DIAGNOSTICS=0` | Disable the post-edit compiler/lint diagnostics loop |
+| `ZELARI_DIAGNOSTICS_TIMEOUT_MS` | Timeout of the diagnostics loop (default 5000) |
+| `ZELARI_AST=0` | Disable AST structural tools (`ast_*`) |
+| `ZELARI_SEMANTIC=0` | Disable semantic search + `/index` |
+| `ZELARI_SEMANTIC_FILE` | Override the embeddings store path |
+| `ZELARI_EMBED_MODEL` | Embedding model id (default `Xenova/all-MiniLM-L6-v2`) |
+| `ZELARI_BROWSER=0` | Disable `browser_check` |
+| `ZELARI_LSP=0` | Disable LSP tools (`lsp_*`) |
+| `ZELARI_CHECKPOINT=0` | Disable automatic workspace checkpoints in zelari-mode |
+| `ZELARI_TOOL_OUTPUT_LINES` | Lines of tool output shown in the TUI (default 8) |
 
 See **[docs/GUIDA.md](./docs/GUIDA.md#variabili-dambiente)** for the full list.
 

package/dist/cli/main.bundled.js

@@ -26534,13 +26534,273 @@ var init_zelariMission = __esm({
   }
 });
 
+// src/cli/utils/prereqChecks.ts
+var prereqChecks_exports = {};
+__export(prereqChecks_exports, {
+  checkAgentBash: () => checkAgentBash,
+  checkAgentGit: () => checkAgentGit,
+  checkAgentNode: () => checkAgentNode,
+  checkMainNode: () => checkMainNode,
+  runPrereqChecks: () => runPrereqChecks
+});
+import { execSync, spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync25 } from "node:fs";
+function resolveAgentShellSync() {
+  if (process.platform !== "win32") {
+    return { bashPath: null, isBash: true, via: "/bin/sh" };
+  }
+  const envShell = process.env.ZELARI_SHELL;
+  if (envShell && envShell.trim().length > 0 && existsSyncSafe2(envShell)) {
+    return { bashPath: envShell, isBash: true, via: `bash (${envShell})` };
+  }
+  const sessionShell = process.env.SHELL;
+  if (sessionShell && sessionShell.trim().length > 0 && existsSyncSafe2(sessionShell)) {
+    return {
+      bashPath: sessionShell,
+      isBash: true,
+      via: `bash (${sessionShell})`
+    };
+  }
+  for (const p3 of STANDARD_BASH_PATHS2) {
+    if (existsSyncSafe2(p3)) {
+      return { bashPath: p3, isBash: true, via: `bash (${p3})` };
+    }
+  }
+  try {
+    const result = spawnSync2("where", ["bash"], {
+      encoding: "utf8",
+      windowsHide: true
+    });
+    if (result.status === 0 && result.stdout) {
+      const first = result.stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+      if (first && existsSyncSafe2(first)) {
+        const trimmed = first.trim();
+        return { bashPath: trimmed, isBash: true, via: `bash (${trimmed})` };
+      }
+    }
+  } catch {
+  }
+  return { bashPath: null, isBash: false, via: "cmd.exe" };
+}
+function existsSyncSafe2(p3) {
+  try {
+    return existsSync25(p3);
+  } catch {
+    return false;
+  }
+}
+function probeTool(tool) {
+  const shell = resolveAgentShellSync();
+  let stdout = "";
+  if (shell.bashPath) {
+    try {
+      const r = spawnSync2(shell.bashPath, ["-c", `${tool} --version`], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true
+      });
+      if (r.status === 0) stdout = (r.stdout || "").trim();
+    } catch {
+    }
+  } else if (process.platform === "win32") {
+    try {
+      stdout = execSync(`${tool} --version`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+  } else {
+    try {
+      stdout = execSync(`${tool} --version`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+  }
+  const m = stdout.match(/(\d+)\.(\d+)\.(\d+)/);
+  return {
+    found: stdout.length > 0,
+    version: m ? `${m[1]}.${m[2]}.${m[3]}` : "",
+    raw: stdout
+  };
+}
+function nodeMissingHint() {
+  const shell = resolveAgentShellSync();
+  if (process.platform === "win32") {
+    return `node is not reachable from the agent's shell (${shell.via}).
+         This usually means Node was installed for "current user" only,
+         while Git Bash inherits the SYSTEM Path. Fix (pick one):
+           - Reinstall Node (https://nodejs.org) and choose
+             "Add to PATH for all users", OR
+           - Add C:\\Program Files\\nodejs\\ to the SYSTEM Path
+             (System Properties \u2192 Environment Variables \u2192 Path), OR
+           - Set ZELARI_SHELL to a bash that already sees node.`;
+  }
+  return `node is not on the agent's shell PATH.
+         Install Node >= ${MIN_NODE_MAJOR} (https://nodejs.org) or, if you use
+         nvm, run \`nvm use <version>\` and reopen this terminal.`;
+}
+function checkAgentNode() {
+  const probe = probeTool("node");
+  if (!probe.found) {
+    return {
+      ok: false,
+      severity: "critical",
+      tool: "node",
+      message: nodeMissingHint()
+    };
+  }
+  const major = Number(probe.version.split(".")[0]);
+  if (!probe.version || Number.isNaN(major)) {
+    return {
+      ok: false,
+      severity: "warn",
+      tool: "node",
+      message: `could not parse node version from "${probe.raw}" (node is reachable, but version check skipped)`
+    };
+  }
+  if (major < MIN_NODE_MAJOR) {
+    return {
+      ok: false,
+      severity: "critical",
+      tool: "node",
+      message: `node ${probe.version} is older than the required >= ${MIN_NODE_MAJOR}.0.0 (from engines.node). Upgrade: https://nodejs.org`
+    };
+  }
+  return {
+    ok: true,
+    severity: "critical",
+    tool: "node",
+    message: `node ${probe.version} (agent shell)`
+  };
+}
+function checkAgentGit() {
+  const probe = probeTool("git");
+  if (!probe.found) {
+    const hint = process.platform === "win32" ? `Install Git for Windows: https://git-scm.com/download/win` : `Install git (e.g. \`brew install git\` on macOS, \`apt install git\` on Debian)`;
+    return {
+      ok: false,
+      severity: "warn",
+      tool: "git",
+      message: `git not found on the agent's shell PATH \u2014 /diff, /undo and the git sidebar will be disabled. ${hint}`
+    };
+  }
+  return {
+    ok: true,
+    severity: "warn",
+    tool: "git",
+    message: `git ${probe.version} (agent shell)`
+  };
+}
+function checkAgentBash() {
+  if (process.platform !== "win32") {
+    return {
+      ok: true,
+      severity: "warn",
+      tool: "bash",
+      message: "POSIX shell always available on this platform"
+    };
+  }
+  const shell = resolveAgentShellSync();
+  if (shell.isBash) {
+    return {
+      ok: true,
+      severity: "warn",
+      tool: "bash",
+      message: `real bash available (${shell.via})`
+    };
+  }
+  return {
+    ok: false,
+    severity: "warn",
+    tool: "bash",
+    message: `no Git Bash found \u2014 the agent's \`bash\` tool falls back to cmd.exe,
+         where POSIX commands (ls, which, $VAR, &&) may fail. Install Git
+         for Windows (https://git-scm.com/download/win) or set ZELARI_SHELL
+         to your bash binary.`
+  };
+}
+function checkMainNode() {
+  try {
+    const raw = execSync("node --version", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    const m = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+    const version2 = m ? `${m[1]}.${m[2]}.${m[3]}` : "";
+    const major = Number(version2.split(".")[0]);
+    if (version2 && !Number.isNaN(major) && major >= MIN_NODE_MAJOR) {
+      return {
+        ok: true,
+        severity: "critical",
+        tool: "node",
+        message: `node ${version2} (main process)`
+      };
+    }
+    return {
+      ok: false,
+      severity: "warn",
+      tool: "node",
+      message: `node present in main process but version unparseable or < ${MIN_NODE_MAJOR}: "${raw}"`
+    };
+  } catch {
+    return {
+      ok: false,
+      severity: "critical",
+      tool: "node",
+      message: "node not found on the main process PATH (zelari-code itself runs on node \u2014 this is unexpected)"
+    };
+  }
+}
+function runPrereqChecks(opts = { mode: "preflight" }) {
+  const checks = [
+    () => checkAgentNode(),
+    () => checkAgentGit(),
+    () => checkAgentBash()
+  ];
+  const results = [];
+  for (const run of checks) {
+    try {
+      results.push(run());
+    } catch (err) {
+      results.push({
+        ok: false,
+        severity: "warn",
+        tool: "node",
+        message: `prereq check crashed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  }
+  const hasCriticalFail = results.some(
+    (r) => !r.ok && r.severity === "critical"
+  );
+  const warnings = results.filter((r) => !r.ok && r.severity === "warn");
+  void opts.mode;
+  return { results, hasCriticalFail, warnings };
+}
+var MIN_NODE_MAJOR, STANDARD_BASH_PATHS2;
+var init_prereqChecks = __esm({
+  "src/cli/utils/prereqChecks.ts"() {
+    "use strict";
+    MIN_NODE_MAJOR = 20;
+    STANDARD_BASH_PATHS2 = [
+      "C:\\Program Files\\Git\\bin\\bash.exe",
+      "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+      "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+      "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe"
+    ];
+  }
+});
+
 // src/cli/utils/doctor.ts
 var doctor_exports = {};
 __export(doctor_exports, {
   runDoctor: () => runDoctor
 });
-import { execSync } from "node:child_process";
-import { existsSync as existsSync29, readFileSync as readFileSync25, readlinkSync, statSync as statSync6 } from "node:fs";
+import { execSync as execSync2 } from "node:child_process";
+import { existsSync as existsSync30, readFileSync as readFileSync25, readlinkSync, statSync as statSync6 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import path32 from "node:path";
@@ -26548,7 +26808,7 @@ function findPackageRoot(start) {
   let dir = start;
   for (let i = 0; i < 6; i += 1) {
     const candidate = path32.join(dir, "package.json");
-    if (existsSync29(candidate)) {
+    if (existsSync30(candidate)) {
       try {
         const pkg = JSON.parse(readFileSync25(candidate, "utf8"));
         if (pkg.name === "zelari-code") return dir;
@@ -26563,7 +26823,7 @@ function findPackageRoot(start) {
 }
 function tryExec(cmd) {
   try {
-    return execSync(cmd, {
+    return execSync2(cmd, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
@@ -26590,7 +26850,7 @@ function checkShim(pkgName) {
   const isWin = process.platform === "win32";
   const shimName = isWin ? "zelari-code.cmd" : "zelari-code";
   const shimPath = path32.join(prefix, shimName);
-  if (!existsSync29(shimPath)) {
+  if (!existsSync30(shimPath)) {
     return FAIL(
       `shim not found at ${shimPath}
          fix:  npm install -g ${pkgName}@latest --force`
@@ -26658,7 +26918,7 @@ function checkNode(pkg) {
 }
 function checkBundle() {
   const bundle = path32.join(packageRoot, "dist", "cli", "main.bundled.js");
-  if (!existsSync29(bundle)) {
+  if (!existsSync30(bundle)) {
     return FAIL(
       `dist/cli/main.bundled.js missing at ${bundle}
          fix:  npm run build:cli   (then reinstall or run via tsx)`
@@ -26709,15 +26969,28 @@ function checkPath() {
          fix (Windows): $env:Path = "$(npm prefix -g);$env:Path"`
   );
 }
+function prereqToCheckResult(r) {
+  if (r.ok) return OK(r.message);
+  return r.severity === "critical" ? FAIL(r.message, "critical") : WARN(r.message);
+}
 function runDoctor() {
   const pkg = readPackageJson3();
   const pkgName = pkg?.name ?? "zelari-code";
   const checks = [
+    // --- install-health checks (main-process probes) ---
     { name: "node", run: () => checkNode(pkg) },
     { name: "bin shim", run: () => checkShim(pkgName) },
     { name: "cli bundle", run: () => checkBundle() },
     { name: "runtime deps", run: () => checkRuntimeDeps() },
-    { name: "PATH", run: () => checkPath() }
+    { name: "PATH", run: () => checkPath() },
+    // --- agent-shell checks (v1.4.0) ---
+    // These probe node/git/bash THROUGH the resolved shell the agent uses.
+    // A pass on "node" + a FAIL on "node (agent shell)" is the tell-tale
+    // signature of the PATH-mismatch bug (node visible to the main process,
+    // invisible to Git Bash) that silently breaks council builds.
+    { name: "node (agent shell)", run: () => prereqToCheckResult(checkAgentNode()) },
+    { name: "git (agent shell)", run: () => prereqToCheckResult(checkAgentGit()) },
+    { name: "bash", run: () => prereqToCheckResult(checkAgentBash()) }
   ];
   console.log(`zelari-code doctor (v${pkg?.version ?? "unknown"})`);
   console.log("platform:", process.platform, process.arch);
@@ -26759,6 +27032,7 @@ var require3, __dirname3, packageRoot, OK, FAIL, WARN;
 var init_doctor = __esm({
   "src/cli/utils/doctor.ts"() {
     "use strict";
+    init_prereqChecks();
     require3 = createRequire2(import.meta.url);
     __dirname3 = path32.dirname(fileURLToPath2(import.meta.url));
     packageRoot = findPackageRoot(__dirname3);
@@ -33931,12 +34205,18 @@ async function handleUpdatePerform(ctx) {
     const { performUpdate: performUpdate2 } = await Promise.resolve().then(() => (init_updater(), updater_exports));
     const res = await performUpdate2();
     if (res.ok) {
+      let prereqBlock = "";
+      try {
+        const { runPrereqChecks: runPrereqChecks2 } = await Promise.resolve().then(() => (init_prereqChecks(), prereqChecks_exports));
+        const { warnings } = runPrereqChecks2({ mode: "preflight" });
+        if (warnings.length > 0) {
+          prereqBlock = "\n\n\u26A0 Prerequisite warnings (the agent may be limited after restart):\n" + warnings.map((w) => `   - ${w.tool}: ${w.message.replace(/\n/g, "\n     ")}`).join("\n") + "\n   Run `zelari-code --doctor` after restart for the full report.";
+        }
+      } catch {
+      }
       appendSystem(
         ctx.setMessages,
-        `[update] \u2705 installed successfully
-
-Please restart zelari-code manually to use the new version.
-(exit with /exit or Ctrl+C, then run \`zelari-code\` again)`
+        "[update] \u2705 installed successfully\n\nPlease restart zelari-code manually to use the new version.\n(exit with /exit or Ctrl+C, then run `zelari-code` again)" + prereqBlock
       );
     } else {
       const output = res.output?.trim() || "(empty)";
@@ -34012,7 +34292,7 @@ async function handlePromoteMember(ctx, memberId) {
 }
 
 // src/cli/branchManager.ts
-import { promises as fs17, existsSync as existsSync25, readFileSync as readFileSync23, writeFileSync as writeFileSync15, mkdirSync as mkdirSync10, statSync as statSync4, rmSync as rmSync2 } from "node:fs";
+import { promises as fs17, existsSync as existsSync26, readFileSync as readFileSync23, writeFileSync as writeFileSync15, mkdirSync as mkdirSync10, statSync as statSync4, rmSync as rmSync2 } from "node:fs";
 import path29 from "node:path";
 import os10 from "node:os";
 var META_FILENAME = "meta.json";
@@ -34034,7 +34314,7 @@ function sessionsPathFor(name, baseDir) {
 }
 function readBranchMeta(name, baseDir) {
   const metaPath = metaPathFor(name, baseDir);
-  if (!existsSync25(metaPath)) {
+  if (!existsSync26(metaPath)) {
     throw new BranchNotFoundError(`Branch "${name}" not found`);
   }
   try {
@@ -34094,7 +34374,7 @@ var SessionNotFoundError = class extends Error {
 };
 function branchExists(name, baseDir = getBranchesBaseDir()) {
   const bp = branchPathFor(name, baseDir);
-  return existsSync25(bp) && existsSync25(metaPathFor(name, baseDir));
+  return existsSync26(bp) && existsSync26(metaPathFor(name, baseDir));
 }
 async function createBranch(name, fromSessionId, baseDir = getBranchesBaseDir(), sessionsBaseDir = getSessionsBaseDir()) {
   if (!name || name.trim().length === 0) {
@@ -34107,7 +34387,7 @@ async function createBranch(name, fromSessionId, baseDir = getBranchesBaseDir(),
     throw new BranchAlreadyExistsError(name);
   }
   const sourcePath = path29.join(sessionsBaseDir, `${fromSessionId}.jsonl`);
-  if (!existsSync25(sourcePath)) {
+  if (!existsSync26(sourcePath)) {
     throw new SessionNotFoundError(`Source session "${fromSessionId}" not found at ${sourcePath}`);
   }
   const branchPath = branchPathFor(name, baseDir);
@@ -34140,7 +34420,7 @@ async function listBranches(baseDir = getBranchesBaseDir()) {
   const results = [];
   for (const entry of entries) {
     const metaPath = metaPathFor(entry, baseDir);
-    if (!existsSync25(metaPath)) continue;
+    if (!existsSync26(metaPath)) continue;
     try {
       const meta3 = readBranchMeta(entry, baseDir);
       const sessionCount = await countSessions(entry, baseDir);
@@ -34676,7 +34956,7 @@ import path31 from "node:path";
 import os11 from "node:os";
 
 // src/cli/skillHistory.ts
-import { promises as fs19, existsSync as existsSync26, statSync as statSync5, renameSync as renameSync4, appendFileSync as appendFileSync3, mkdirSync as mkdirSync11 } from "node:fs";
+import { promises as fs19, existsSync as existsSync27, statSync as statSync5, renameSync as renameSync4, appendFileSync as appendFileSync3, mkdirSync as mkdirSync11 } from "node:fs";
 var SKILL_HISTORY_ROTATE_BYTES = 10 * 1024 * 1024;
 async function readSkillHistory(file2) {
   let raw = "";
@@ -35620,9 +35900,9 @@ function SplashGate({
 init_providerConfig();
 
 // src/cli/wizard/firstRun.ts
-import { existsSync as existsSync27 } from "node:fs";
+import { existsSync as existsSync28 } from "node:fs";
 function shouldRunWizard(input) {
-  const exists = input.exists ?? existsSync27;
+  const exists = input.exists ?? existsSync28;
   if (input.hasResetConfigFlag) {
     return { shouldRun: true, reason: "--reset-config flag forced wizard" };
   }
@@ -36112,7 +36392,7 @@ async function runHeadlessCouncil(opts, provider, model, providerStream) {
 
 // src/cli/skillsMd.ts
 init_skills2();
-import { existsSync as existsSync28, readdirSync as readdirSync4, readFileSync as readFileSync24 } from "node:fs";
+import { existsSync as existsSync29, readdirSync as readdirSync4, readFileSync as readFileSync24 } from "node:fs";
 import { join as join23 } from "node:path";
 import { homedir as homedir6 } from "node:os";
 var CODING_CATEGORIES = /* @__PURE__ */ new Set([
@@ -36190,7 +36470,7 @@ function loadSkillMdSkills(projectRoot = process.cwd(), options = {}) {
   const summary = { loaded: [], skipped: [] };
   const seen = new Set(options.existingIds ?? []);
   for (const dir of skillMdSearchDirs(projectRoot)) {
-    if (!existsSync28(dir)) continue;
+    if (!existsSync29(dir)) continue;
     let entries;
     try {
       entries = readdirSync4(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
@@ -36199,7 +36479,7 @@ function loadSkillMdSkills(projectRoot = process.cwd(), options = {}) {
     }
     for (const entry of entries) {
       const skillPath = join23(dir, entry, "SKILL.md");
-      if (!existsSync28(skillPath)) continue;
+      if (!existsSync29(skillPath)) continue;
       try {
         const parsed = parseSkillMd(readFileSync24(skillPath, "utf8"), skillPath);
         if (!parsed) {
@@ -36225,6 +36505,38 @@ function loadSkillMdSkills(projectRoot = process.cwd(), options = {}) {
 init_skills2();
 init_updater();
 var VERSION = getCurrentVersion();
+function runPreflight() {
+  if (process.env.ZELARI_SKIP_PREFLIGHT === "1") return;
+  if (process.argv.includes("--skip-checks")) return;
+  if (process.env.ANATHEMA_DEV === "1") return;
+  const { runPrereqChecks: runPrereqChecks2 } = (
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    (init_prereqChecks(), __toCommonJS(prereqChecks_exports))
+  );
+  const { results, hasCriticalFail, warnings } = runPrereqChecks2({
+    mode: "preflight"
+  });
+  for (const w of warnings) {
+    console.error(`\x1B[33m[zelari-code] \u26A0 ${w.tool}: ${w.message}\x1B[0m`);
+  }
+  if (hasCriticalFail) {
+    const critical = results.find(
+      (r) => !r.ok && r.severity === "critical"
+    );
+    console.error("");
+    console.error(
+      "\x1B[31m==============================================================\n zelari-code cannot start: a critical prerequisite is missing.\n==============================================================\x1B[0m"
+    );
+    if (critical) {
+      console.error(`
+  ${critical.tool}: ${critical.message}`);
+    }
+    console.error(
+      "\n  Run `zelari-code --doctor` for the full diagnostic report.\n  Bypass this check with ZELARI_SKIP_PREFLIGHT=1 (NOT recommended \u2014\n  the agent will still fail when it tries to run npm/build/tsc)."
+    );
+    process.exit(1);
+  }
+}
 async function backgroundUpdateCheck() {
   if (process.env.ANATHEMA_DEV === "1") return;
   await new Promise((resolve) => setTimeout(resolve, 3e3));
@@ -36264,7 +36576,7 @@ function pickRootComponent() {
   }
   if (argv.includes("--help") || argv.includes("-h")) {
     console.log(
-      "zelari-code \u2014 AI Council coding agent CLI.\n\nUsage: zelari-code [options]\n\nOptions:\n  --version, -v       Print version and exit\n  --help, -h          Print this help and exit\n  --doctor            Diagnose install health (shim, bundle, PATH, deps)\n  --no-wizard         Skip the first-run wizard\n  --reset-config      Re-run the wizard (clears provider.json on commit)\n  --headless          Run a single task without mounting the TUI\n    --task <text>       Task prompt (required in headless mode)\n    --output json|plain Output format (default: json)\n    --council          Use the 6-member council pipeline\n    --provider <id>    Provider override (default: active)\n    --model <id>       Model override (default: provider default)\n\nEnvironment:\n  ZELARI_NO_WIZARD=1  Skip the first-run wizard\n  ANATHEMA_DEV=1      Disable background update check\n"
+      "zelari-code \u2014 AI Council coding agent CLI.\n\nUsage: zelari-code [options]\n\nOptions:\n  --version, -v       Print version and exit\n  --help, -h          Print this help and exit\n  --doctor            Diagnose install health (shim, bundle, PATH, deps,\n                      node/git/bash in the agent shell)\n  --skip-checks       Skip the boot-time prerequisite check\n                      (alias for ZELARI_SKIP_PREFLIGHT=1)\n  --no-wizard         Skip the first-run wizard\n  --reset-config      Re-run the wizard (clears provider.json on commit)\n  --headless          Run a single task without mounting the TUI\n    --task <text>       Task prompt (required in headless mode)\n    --output json|plain Output format (default: json)\n    --council          Use the 6-member council pipeline\n    --provider <id>    Provider override (default: active)\n    --model <id>       Model override (default: provider default)\n\nEnvironment:\n  ZELARI_NO_WIZARD=1    Skip the first-run wizard\n  ZELARI_SKIP_PREFLIGHT=1  Skip the boot prerequisite check\n  ANATHEMA_DEV=1        Disable background update check + preflight\n"
     );
     process.exit(0);
   }
@@ -36314,6 +36626,7 @@ function loadUserSkills() {
 function main() {
   const picked = pickRootComponent();
   if (picked.kind === "done") return;
+  runPreflight();
   loadUserSkills();
   if (picked.kind === "headless") {
     void runHeadless(picked.headlessOpts).then((code) => {