aether-code 0.43.0 → 0.43.1

package/src/setup.js

@@ -107,21 +107,17 @@ export async function runSetup() {
       continue;
     }
 
+    // Tentative save so the API client picks it up
+    writeConfigFile({ apiKey: key });
     process.stdout.write(c.gray("Verifying..."));
     try {
-      const me = await fetchBalance(key);
-      writeConfigFile({ apiKey: key });
-      if (process.env.AETHER_API_KEY && process.env.AETHER_API_KEY !== key) {
-        process.env.AETHER_API_KEY = key;
-        console.log(c.yellow(" ⚠ AETHER_API_KEY env var was set to a different key — overriding for this session."));
-        console.log(c.yellow("   Update your shell profile to avoid this next time."));
-      }
+      const me = await fetchBalance();
       console.log(c.green(" ●"));
       console.log("");
       console.log(c.green(c.bold("Setup complete.")));
       console.log(
         c.gray(`Saved to ${CONFIG_PATH} (mode 0600).`) +
-          c.gray(`\nPlan: ${me.plan} · Balance: ${me.balance.toLocaleString()} credits`),
+          c.gray(`\nPlan: ${me.plan || "FREE"} · Balance: ${me.balance.toLocaleString()} credits`),
       );
       console.log("");
       saved = true;
@@ -133,6 +129,8 @@ export async function runSetup() {
       } else {
         console.log(errorLine(err.message || String(err)));
       }
+      // Roll back the bad save so we don't leave a broken key on disk
+      writeConfigFile({ apiKey: "" });
     }
   }
 

package/src/tools.js

@@ -16,7 +16,6 @@ import { c } from "./render.js";
 import { promptChoice } from "./menu.js";
 import { unifiedDiff, summarizeWrite } from "./diff.js";
 import { getConfig } from "./config.js";
-import { getVersion } from "./version.js";
 
 /* ─────────────────────── Tool definitions (sent to model) ─────────────────────── */
 
@@ -201,7 +200,7 @@ export const TOOL_DEFINITIONS = [
     function: {
       name: "ask_user",
       description:
-        "Ask the user a single multiple-choice question and wait for their answer. Use this ONLY when the request is genuinely ambiguous AND the answer materially changes what you build — e.g. which platform/framework/language, the scope, or an irreversible decision. Ask BEFORE building when a wrong assumption would waste real work. Give 2–5 concrete options, each with a short description; put the best default first. Do NOT use it for trivial choices, things you can infer, or to confirm permission to act — just build when the task is clear.",
+        "Ask the user a single multiple-choice question ONLY when you literally cannot proceed without their input — e.g. the task names two incompatible platforms and you don't know which one. NEVER use this tool to answer a question the user asked YOU — if they ask 'what color is this?', 'what does this code do?', 'explain X', etc., respond with TEXT, not a quiz. NEVER use it to present analysis, findings, or answers as multiple-choice options. NEVER use it for trivial choices, things you can infer, or to confirm permission — just act. The ONLY valid use is: a genuinely ambiguous BUILD request where picking wrong wastes real work (which framework, which language, which scope). Give 2–5 concrete options with short descriptions; put the best default first.",
       parameters: {
         type: "object",
         properties: {
@@ -223,125 +222,6 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
-  /* ─────────────────────── Git tools ─────────────────────── */
-  {
-    type: "function",
-    function: {
-      name: "git_status",
-      description:
-        "Show the working tree status — staged, unstaged, and untracked files. Auto-executes (read-only). Use this before committing to see what's changed.",
-      parameters: {
-        type: "object",
-        properties: {},
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_diff",
-      description:
-        "Show a unified diff of changes. By default shows unstaged changes. Set staged=true for staged changes, or pass base/head for branch comparisons (e.g. base='main' head='HEAD'). Optionally limit to specific file(s).",
-      parameters: {
-        type: "object",
-        properties: {
-          staged: { type: "boolean", description: "Show staged (--cached) diff instead of unstaged. Default: false." },
-          base: { type: "string", description: "Base ref for comparison (e.g. 'main', 'HEAD~3'). When set, shows diff between base and head." },
-          head: { type: "string", description: "Head ref for comparison. Default: 'HEAD' when base is set." },
-          files: {
-            type: "array",
-            description: "Limit diff to these file paths.",
-            items: { type: "string" },
-          },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_log",
-      description:
-        "Show recent commit history with hash, author, date, and message. Defaults to 15 commits. Use this to understand what's been done recently, find commit hashes, or check the commit style before committing.",
-      parameters: {
-        type: "object",
-        properties: {
-          count: { type: "number", description: "Number of commits to show (1-50). Default: 15." },
-          oneline: { type: "boolean", description: "Compact one-line format. Default: false." },
-          file: { type: "string", description: "Show only commits that touched this file." },
-          branch: { type: "string", description: "Show commits on this branch instead of HEAD." },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_commit",
-      description:
-        "Stage files and create a commit. If no files are specified, stages all modified/new files (git add -A). The user will see what's being committed and confirm. Use git_status first to see what's changed, and git_log to match the commit message style.",
-      parameters: {
-        type: "object",
-        properties: {
-          message: { type: "string", description: "Commit message. Be concise — focus on WHY, not WHAT." },
-          files: {
-            type: "array",
-            description: "Specific files to stage. If omitted, stages everything (git add -A).",
-            items: { type: "string" },
-          },
-        },
-        required: ["message"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_branch",
-      description:
-        "Create and/or switch to a branch. If the branch exists, switches to it. If it doesn't, creates it from the current HEAD (or from 'base' if specified) and switches to it.",
-      parameters: {
-        type: "object",
-        properties: {
-          name: { type: "string", description: "Branch name to create or switch to." },
-          base: { type: "string", description: "Create the branch from this ref instead of HEAD." },
-        },
-        required: ["name"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_push",
-      description:
-        "Push the current branch to the remote. Sets upstream tracking (-u origin) on first push. The user will confirm before pushing.",
-      parameters: {
-        type: "object",
-        properties: {
-          force: { type: "boolean", description: "Force push (--force-with-lease). Use only when explicitly asked. Default: false." },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_create_pr",
-      description:
-        "Create a GitHub pull request using the `gh` CLI. Requires `gh` to be installed and authenticated. Pushes the branch first if needed. The user will confirm before creating.",
-      parameters: {
-        type: "object",
-        properties: {
-          title: { type: "string", description: "PR title. Keep under 72 chars." },
-          body: { type: "string", description: "PR body/description. Markdown supported." },
-          base: { type: "string", description: "Target branch to merge into. Default: repo default (usually main)." },
-          draft: { type: "boolean", description: "Create as a draft PR. Default: false." },
-        },
-        required: ["title", "body"],
-      },
-    },
-  },
 ];
 
 /* ─────────────────────── Argument validation ─────────────────────── */
@@ -529,13 +409,6 @@ export async function executeTool(call, opts) {
     web_fetch: () => webFetch(args, opts),
     todo_write: () => todoWrite(args, opts),
     ask_user: () => askUser(args, opts),
-    git_status: () => gitStatus(args, opts),
-    git_diff: () => gitDiff(args, opts),
-    git_log: () => gitLog(args, opts),
-    git_commit: () => gitCommit(args, opts),
-    git_branch: () => gitBranch(args, opts),
-    git_push: () => gitPush(args, opts),
-    git_create_pr: () => gitCreatePr(args, opts),
   };
   const fn = handlers[name];
   if (!fn) {
@@ -773,39 +646,26 @@ async function webSearch(args, opts) {
     return { ok: false, output: "Web search requires AETHER_API_KEY. Set it and try again." };
   }
   const max = Number.isInteger(args.max_results) ? Math.min(10, Math.max(1, args.max_results)) : 5;
-  const maxRetries = 2;
-  const baseDelay = 500;
   let res;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      res = await fetch(`${baseUrl}/api/v1/web-search`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${apiKey}`,
-          "User-Agent": `aether-code/${getVersion()}`,
-        },
-        body: JSON.stringify({ query: args.query, max_results: max }),
-      });
-      if (res.status >= 500 && attempt < maxRetries) {
-        res.body?.cancel().catch(() => {});
-        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-        continue;
-      }
-      break;
-    } catch (e) {
-      if (attempt < maxRetries) {
-        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-        continue;
-      }
-      return { ok: false, output: `web_search network error: ${e.message}` };
-    }
+  try {
+    res = await fetch(`${baseUrl}/api/v1/web-search`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "User-Agent": "aether-code/web-search",
+      },
+      body: JSON.stringify({ query: args.query, max_results: max }),
+    });
+  } catch (e) {
+    return { ok: false, output: `web_search network error: ${e.message}` };
   }
   let data = null;
   try { data = await res.json(); } catch { /* non-JSON */ }
   if (!res.ok) {
     return { ok: false, output: data?.error || `web_search HTTP ${res.status}` };
   }
+  // Hand the model just the array — that's all it needs to decide which URL to fetch.
   return { ok: true, output: JSON.stringify(data.results ?? [], null, 2) };
 }
 
@@ -849,7 +709,7 @@ async function webFetch(args, opts) {
       headers: {
         // Looking like a normal browser dodges many anti-bot pages.
         "User-Agent":
-          `Mozilla/5.0 (compatible; aether-code/${getVersion()}) Gecko/20100101 Firefox/130.0`,
+          "Mozilla/5.0 (compatible; aether-code/0.7) Gecko/20100101 Firefox/130.0",
         Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
         "Accept-Language": "en-US,en;q=0.9",
       },
@@ -922,28 +782,11 @@ export function htmlToText(html) {
   return s.trim();
 }
 
-const CATASTROPHIC_CMD_RE = new RegExp(
-  [
-    String.raw`rm\s+-(r|f|rf|fr)\w*\s+[/~](?!\S*node_modules)(?!\S*dist)(?!\S*\.next)(?!\S*build)`,
-    String.raw`del\s+/[sfq]+\s+[cC]:\\`,
-    String.raw`format\s+[a-zA-Z]:`,
-    String.raw`mkfs\.`,
-    String.raw`dd\s+.*of=/dev/[sh]d`,
-    String.raw`:\(\)\s*\{\s*:\|:`,
-    String.raw`>\s*/dev/[sh]d`,
-    String.raw`rd\s+/[sq]+\s+[cC]:\\`,
-  ].join("|"),
-);
-
 async function runShell(args, opts) {
   if (typeof args.command !== "string") return { ok: false, output: "command is required" };
   const cwd = args.cwd ? resolveSafe(args.cwd, opts) : opts.cwd;
   console.log(c.yellow("$ ") + c.bold(args.command) + (args.cwd ? c.dim(`  (cwd: ${args.cwd})`) : ""));
-  const forceReview = CATASTROPHIC_CMD_RE.test(args.command);
-  if (forceReview) {
-    console.log(c.red(c.bold("  ⚠ DESTRUCTIVE COMMAND DETECTED")) + c.gray(" — requires manual confirmation"));
-  }
-  const approved = await confirm(c.yellow("Run this command?"), forceReview ? false : opts.autoYes);
+  const approved = await confirm(c.yellow("Run this command?"), opts.autoYes);
   if (!approved) return { ok: false, output: "User declined the command." };
 
   return new Promise((resolve) => {
@@ -985,226 +828,6 @@ async function runShell(args, opts) {
   });
 }
 
-/* ─────────────────────── Git tools ─────────────────────── */
-
-function runGit(gitArgs, cwd, timeoutMs = 30_000) {
-  return new Promise((resolve) => {
-    const child = spawn("git", gitArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let killed = false;
-    const timer = setTimeout(() => { killed = true; child.kill("SIGTERM"); }, timeoutMs);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      const truncate = (t) => (t.length > 30_000 ? t.slice(0, 30_000) + "\n…(truncated)" : t);
-      resolve({ code, killed, stdout: truncate(stdout), stderr: truncate(stderr) });
-    });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ code: 1, killed: false, stdout: "", stderr: `git spawn error: ${err.message}` });
-    });
-  });
-}
-
-async function gitStatus(_args, opts) {
-  const r = await runGit(["status", "--short", "--branch", "-u"], opts.cwd);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git status failed" };
-  const lines = r.stdout.trim().split("\n");
-  const branchLine = lines[0] || "";
-  const files = lines.slice(1).filter((l) => l.trim());
-  const staged = [];
-  const unstaged = [];
-  const untracked = [];
-  for (const line of files) {
-    const x = line[0];
-    const y = line[1];
-    const name = line.slice(3);
-    if (x === "?") { untracked.push(name); continue; }
-    if (x !== " " && x !== "?") staged.push({ status: x, file: name });
-    if (y !== " " && y !== "?") unstaged.push({ status: y, file: name });
-  }
-  const result = {
-    branch: branchLine.replace(/^## /, ""),
-    staged,
-    unstaged,
-    untracked,
-    clean: staged.length === 0 && unstaged.length === 0 && untracked.length === 0,
-  };
-  return { ok: true, output: JSON.stringify(result, null, 2) };
-}
-
-async function gitDiff(args, opts) {
-  const gitArgs = ["diff", "--stat", "--patch"];
-  if (args.staged) gitArgs.push("--cached");
-  if (args.base) {
-    const head = args.head || "HEAD";
-    gitArgs.length = 0;
-    gitArgs.push("diff", args.base + "..." + head, "--stat", "--patch");
-  }
-  if (Array.isArray(args.files) && args.files.length > 0) {
-    gitArgs.push("--");
-    for (const f of args.files) gitArgs.push(f);
-  }
-  const r = await runGit(gitArgs, opts.cwd, 60_000);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git diff failed" };
-  if (!r.stdout.trim()) return { ok: true, output: "(no changes)" };
-  return { ok: true, output: r.stdout };
-}
-
-async function gitLog(args, opts) {
-  const count = Math.min(50, Math.max(1, args.count ?? 15));
-  const gitArgs = ["log", `-${count}`];
-  if (args.oneline) {
-    gitArgs.push("--oneline");
-  } else {
-    gitArgs.push("--format=%h %an (%ar)%n  %s%n");
-  }
-  if (args.branch) gitArgs.push(args.branch);
-  if (args.file) { gitArgs.push("--"); gitArgs.push(args.file); }
-  const r = await runGit(gitArgs, opts.cwd);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git log failed" };
-  if (!r.stdout.trim()) return { ok: true, output: "(no commits)" };
-  return { ok: true, output: r.stdout };
-}
-
-async function gitCommit(args, opts) {
-  if (typeof args.message !== "string" || !args.message.trim()) {
-    return { ok: false, output: "commit message is required" };
-  }
-  // Stage files
-  const filesToStage = Array.isArray(args.files) && args.files.length > 0 ? args.files : null;
-  if (filesToStage) {
-    const addR = await runGit(["add", "--", ...filesToStage], opts.cwd);
-    if (addR.code !== 0) return { ok: false, output: `git add failed: ${addR.stderr}` };
-  } else {
-    const addR = await runGit(["add", "-A"], opts.cwd);
-    if (addR.code !== 0) return { ok: false, output: `git add -A failed: ${addR.stderr}` };
-  }
-  // Show what's staged
-  const staged = await runGit(["diff", "--cached", "--stat"], opts.cwd);
-  if (!staged.stdout.trim()) {
-    return { ok: false, output: "Nothing to commit — no staged changes after git add." };
-  }
-  console.log(c.dim(staged.stdout));
-  console.log(c.cyan("commit message: ") + c.bold(args.message));
-  const approved = await confirm(c.yellow("Create this commit?"), opts.autoYes);
-  if (!approved) {
-    await runGit(["reset", "HEAD"], opts.cwd);
-    return { ok: false, output: "User declined the commit. Staged changes have been unstaged." };
-  }
-  const commitR = await runGit(["commit", "-m", args.message], opts.cwd);
-  if (commitR.code !== 0) return { ok: false, output: `git commit failed: ${commitR.stderr}` };
-  // Get the commit hash for confirmation
-  const hashR = await runGit(["rev-parse", "--short", "HEAD"], opts.cwd);
-  const hash = hashR.stdout.trim();
-  return { ok: true, output: `Committed ${hash}: ${args.message}\n${commitR.stdout}` };
-}
-
-async function gitBranch(args, opts) {
-  if (typeof args.name !== "string" || !args.name.trim()) {
-    return { ok: false, output: "branch name is required" };
-  }
-  // Check if branch exists
-  const checkR = await runGit(["rev-parse", "--verify", args.name], opts.cwd);
-  if (checkR.code === 0) {
-    // Branch exists, switch to it
-    const switchR = await runGit(["checkout", args.name], opts.cwd);
-    if (switchR.code !== 0) return { ok: false, output: `git checkout failed: ${switchR.stderr}` };
-    return { ok: true, output: `Switched to existing branch '${args.name}'` };
-  }
-  // Create new branch
-  const createArgs = ["checkout", "-b", args.name];
-  if (args.base) createArgs.push(args.base);
-  const createR = await runGit(createArgs, opts.cwd);
-  if (createR.code !== 0) return { ok: false, output: `git checkout -b failed: ${createR.stderr}` };
-  return { ok: true, output: `Created and switched to new branch '${args.name}'${args.base ? ` from ${args.base}` : ""}` };
-}
-
-async function gitPush(args, opts) {
-  // Get current branch name
-  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
-  if (branchR.code !== 0) return { ok: false, output: `Cannot determine current branch: ${branchR.stderr}` };
-  const branch = branchR.stdout.trim();
-  if (!branch || branch === "HEAD") {
-    return { ok: false, output: "Cannot push — HEAD is detached. Checkout a branch first." };
-  }
-  const pushArgs = ["push", "-u", "origin", branch];
-  if (args.force) pushArgs.splice(1, 0, "--force-with-lease");
-  console.log(c.yellow("$ ") + c.bold(`git ${pushArgs.join(" ")}`));
-  const approved = await confirm(c.yellow(`Push '${branch}' to origin?`), opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the push." };
-  const r = await runGit(pushArgs, opts.cwd, 60_000);
-  if (r.code !== 0) return { ok: false, output: `git push failed: ${r.stderr}` };
-  return { ok: true, output: `Pushed '${branch}' to origin.\n${r.stderr}${r.stdout}`.trim() };
-}
-
-async function gitCreatePr(args, opts) {
-  if (typeof args.title !== "string" || !args.title.trim()) {
-    return { ok: false, output: "PR title is required" };
-  }
-  if (typeof args.body !== "string") {
-    return { ok: false, output: "PR body is required" };
-  }
-  // Check if gh CLI is available
-  const ghCheck = await runGit(["--version"], opts.cwd);
-  void ghCheck;
-  const ghVerify = new Promise((resolve) => {
-    const child = spawn("gh", ["--version"], { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let out = "";
-    child.stdout.on("data", (d) => { out += d.toString(); });
-    child.on("close", (code) => resolve({ code, stdout: out }));
-    child.on("error", () => resolve({ code: 1, stdout: "" }));
-  });
-  const ghResult = await ghVerify;
-  if (ghResult.code !== 0) {
-    return { ok: false, output: "GitHub CLI (gh) is not installed or not in PATH. Install it: https://cli.github.com" };
-  }
-  // Push branch first if needed
-  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
-  const branch = branchR.stdout.trim();
-  const trackR = await runGit(["config", "--get", `branch.${branch}.remote`], opts.cwd);
-  if (trackR.code !== 0 || !trackR.stdout.trim()) {
-    console.log(c.gray(`Branch '${branch}' has no remote — pushing first...`));
-    const pushR = await runGit(["push", "-u", "origin", branch], opts.cwd, 60_000);
-    if (pushR.code !== 0) return { ok: false, output: `Failed to push branch: ${pushR.stderr}` };
-    console.log(c.gray("Pushed."));
-  }
-  // Build gh pr create command
-  console.log(c.cyan("PR title: ") + c.bold(args.title));
-  const bodyPreview = args.body.length > 200 ? args.body.slice(0, 197) + "..." : args.body;
-  console.log(c.gray(bodyPreview));
-  if (args.base) console.log(c.gray(`base: ${args.base}`));
-  if (args.draft) console.log(c.gray("(draft PR)"));
-  const approved = await confirm(c.yellow("Create this pull request?"), opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the PR." };
-  const ghArgs = ["pr", "create", "--title", args.title, "--body", args.body];
-  if (args.base) { ghArgs.push("--base"); ghArgs.push(args.base); }
-  if (args.draft) ghArgs.push("--draft");
-  return new Promise((resolve) => {
-    const child = spawn("gh", ghArgs, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => child.kill("SIGTERM"), 30_000);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (code !== 0) {
-        resolve({ ok: false, output: `gh pr create failed (exit ${code}): ${stderr || stdout}` });
-      } else {
-        const prUrl = stdout.trim();
-        resolve({ ok: true, output: `Pull request created: ${prUrl}\n${stderr}`.trim() });
-      }
-    });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ ok: false, output: `gh spawn error: ${err.message}` });
-    });
-  });
-}
-
 /* ─────────────────────── todo_write ─────────────────────── */
 
 // Module-level singleton holding the current todo list for this CLI session.

package/src/update-check.js

@@ -1,10 +1,12 @@
-// Startup update check — like Claude Code / npm itself nudging you when a newer
-// version is published. Never throws, bounded by a short timeout so it can't
-// slow or block startup; silent when offline or already current.
+// Startup update check + auto-update. On every REPL launch, checks the npm
+// registry and silently installs the latest version in the background if one
+// exists. Never throws, bounded by a short timeout so it can't slow startup.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
 import { c } from "./render.js";
 
 export function currentVersion() {
@@ -27,10 +29,65 @@ export function cmpVersion(a, b) {
   return 0;
 }
 
+const COOLDOWN_FILE = join(tmpdir(), "aether-update-ts");
+const COOLDOWN_MS = 3600_000; // 1 hour
+
+/**
+ * Check for updates. If a newer version exists on npm, spawn a background
+ * `npm install -g` to auto-install it. Returns a one-line status message
+ * or null. Cooldown: only checks once per hour.
+ */
+export async function autoUpdate({ fetchImpl = fetch, timeoutMs = 2000 } = {}) {
+  const current = currentVersion();
+  if (!current) return null;
+
+  // Skip if we checked less than 1 hour ago
+  try {
+    const ts = parseInt(readFileSync(COOLDOWN_FILE, "utf8"), 10);
+    if (Date.now() - ts < COOLDOWN_MS) return null;
+  } catch { /* no file or parse error — check now */ }
+
+  try {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl("https://registry.npmjs.org/aether-code/latest", { signal: ac.signal });
+    } finally {
+      clearTimeout(t);
+    }
+    if (!res || !res.ok) return null;
+    const latest = (await res.json())?.version;
+
+    // Write cooldown regardless of whether an update is available
+    try { writeFileSync(COOLDOWN_FILE, String(Date.now())); } catch { /* ignore */ }
+
+    if (!latest || cmpVersion(latest, current) <= 0) return null;
+
+    // Spawn background npm install — detached so it doesn't block the CLI.
+    // On Windows, `npm` is a cmd script, so shell:true is required.
+    const child = spawn("npm", ["install", "-g", `aether-code@${latest}`], {
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      windowsHide: true,
+    });
+    child.unref();
+
+    return (
+      c.cyan("↑ auto-updating ") +
+      c.gray(current) + c.gray(" → ") + c.bold(c.green(latest)) +
+      c.gray("  (background — applies next launch)")
+    );
+  } catch {
+    /* offline / aborted / parse error — stay silent */
+  }
+  return null;
+}
+
 /**
- * Resolve a one-line "update available" nudge if the npm registry has a newer
- * version than the installed one — otherwise null. Bounded to ~2s; any failure
- * (offline, timeout, registry hiccup) resolves to null silently.
+ * Legacy nudge-only check (kept for the test suite). Same as before: returns
+ * a one-line "update available" string or null.
  */
 export async function checkForUpdate({ fetchImpl = fetch, timeoutMs = 2000 } = {}) {
   const current = currentVersion();