aether-code 0.43.1 → 0.43.3

package/src/sessions.js

@@ -0,0 +1,167 @@
+// Session persistence. Saves conversation state to ~/.aether/sessions/ so
+// users can close the terminal, come back tomorrow, and resume exactly
+// where they left off. Auto-saves after every agent turn.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+
+const SESSIONS_DIR = path.join(os.homedir(), ".aether", "sessions");
+const MAX_SESSIONS = 50;
+const STALE_DAYS = 14;
+
+function ensureDir() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+function cwdHash(cwd) {
+  return crypto.createHash("sha256").update(cwd.toLowerCase()).digest("hex").slice(0, 12);
+}
+
+function sessionPath(id) {
+  return path.join(SESSIONS_DIR, `${id}.json`);
+}
+
+export function generateSessionId(cwd) {
+  const hash = cwdHash(cwd);
+  const ts = Date.now().toString(36);
+  return `${hash}-${ts}`;
+}
+
+export function saveSession(session) {
+  ensureDir();
+  const data = {
+    id: session.id,
+    cwd: session.cwd,
+    model: session.model ?? null,
+    modelName: session.modelName ?? "Aether Core",
+    messages: session.messages ?? [],
+    credits: session.credits ?? 0,
+    tokensIn: session.tokensIn ?? 0,
+    tokensOut: session.tokensOut ?? 0,
+    createdAt: session.createdAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    summary: session.summary ?? "",
+    turnCount: session.turnCount ?? 0,
+  };
+  const filePath = sessionPath(data.id);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch { /* windows */ }
+  pruneOldSessions();
+  return data;
+}
+
+export function loadSession(id) {
+  const filePath = sessionPath(id);
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function deleteSession(id) {
+  try {
+    fs.unlinkSync(sessionPath(id));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function listSessions(filterCwd) {
+  ensureDir();
+  let files;
+  try {
+    files = fs.readdirSync(SESSIONS_DIR).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const sessions = [];
+  for (const f of files) {
+    try {
+      const raw = fs.readFileSync(path.join(SESSIONS_DIR, f), "utf8");
+      const data = JSON.parse(raw);
+      if (filterCwd && data.cwd?.toLowerCase() !== filterCwd.toLowerCase()) continue;
+      sessions.push({
+        id: data.id,
+        cwd: data.cwd,
+        model: data.model,
+        modelName: data.modelName,
+        summary: data.summary,
+        turnCount: data.turnCount ?? 0,
+        messageCount: data.messages?.length ?? 0,
+        credits: data.credits ?? 0,
+        createdAt: data.createdAt,
+        updatedAt: data.updatedAt,
+      });
+    } catch {
+      continue;
+    }
+  }
+  sessions.sort((a, b) => (b.updatedAt || "").localeCompare(a.updatedAt || ""));
+  return sessions;
+}
+
+export function findRecentSession(cwd, maxAgeMs = 24 * 60 * 60 * 1000) {
+  const sessions = listSessions(cwd);
+  if (sessions.length === 0) return null;
+  const newest = sessions[0];
+  if (!newest.updatedAt) return null;
+  const age = Date.now() - new Date(newest.updatedAt).getTime();
+  if (age > maxAgeMs) return null;
+  if (newest.messageCount < 2) return null;
+  return newest;
+}
+
+function pruneOldSessions() {
+  let files;
+  try {
+    files = fs.readdirSync(SESSIONS_DIR).filter((f) => f.endsWith(".json"));
+  } catch {
+    return;
+  }
+  if (files.length <= MAX_SESSIONS) return;
+  const entries = [];
+  for (const f of files) {
+    try {
+      const stat = fs.statSync(path.join(SESSIONS_DIR, f));
+      entries.push({ file: f, mtime: stat.mtimeMs });
+    } catch {
+      continue;
+    }
+  }
+  entries.sort((a, b) => b.mtime - a.mtime);
+  const cutoff = Date.now() - STALE_DAYS * 24 * 60 * 60 * 1000;
+  for (const e of entries.slice(MAX_SESSIONS)) {
+    if (e.mtime < cutoff) {
+      try { fs.unlinkSync(path.join(SESSIONS_DIR, e.file)); } catch { /* ignore */ }
+    }
+  }
+}
+
+export function extractSummary(messages) {
+  if (!messages || messages.length === 0) return "";
+  const firstUser = messages.find((m) => m.role === "user");
+  if (!firstUser || typeof firstUser.content !== "string") return "";
+  const text = firstUser.content
+    .replace(/\[environment\][\s\S]*?\[\/environment\]\s*/g, "")
+    .replace(/\[project\][\s\S]*?\[\/project\]\s*/g, "")
+    .replace(/=== LOADED SKILLS[\s\S]*?---\s*/g, "")
+    .trim();
+  return text.length > 120 ? text.slice(0, 117) + "..." : text;
+}
+
+export function formatAge(isoDate) {
+  if (!isoDate) return "unknown";
+  const ms = Date.now() - new Date(isoDate).getTime();
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/src/setup.js

@@ -107,17 +107,21 @@ 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();
+      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."));
+      }
       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 || "FREE"} · Balance: ${me.balance.toLocaleString()} credits`),
+          c.gray(`\nPlan: ${me.plan} · Balance: ${me.balance.toLocaleString()} credits`),
       );
       console.log("");
       saved = true;
@@ -129,8 +133,6 @@ 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,6 +16,7 @@ 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) ─────────────────────── */
 
@@ -200,7 +201,7 @@ export const TOOL_DEFINITIONS = [
     function: {
       name: "ask_user",
       description:
-        "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.",
+        "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.",
       parameters: {
         type: "object",
         properties: {
@@ -222,6 +223,125 @@ 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 ─────────────────────── */
@@ -409,6 +529,13 @@ 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) {
@@ -646,26 +773,39 @@ 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;
-  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}` };
+  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}` };
+    }
   }
   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) };
 }
 
@@ -709,7 +849,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/0.7) Gecko/20100101 Firefox/130.0",
+          `Mozilla/5.0 (compatible; aether-code/${getVersion()}) 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",
       },
@@ -782,11 +922,28 @@ 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 approved = await confirm(c.yellow("Run this command?"), opts.autoYes);
+  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);
   if (!approved) return { ok: false, output: "User declined the command." };
 
   return new Promise((resolve) => {
@@ -828,6 +985,226 @@ 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.