@hncode/hncode 0.3.3 → 0.3.5

package/README.md

@@ -118,12 +118,13 @@ Special thanks to the communities behind these projects for pushing the boundari
 
 ## 📄 License
 
-This project is licensed under the [GNU General Public License v3.0](https://github.com/NiceHello666/hncode/blob/main/LICENSE).
+This project is licensed under the [PolyForm Noncommercial License 1.0.0](https://github.com/NiceHello666/hncode/blob/main/LICENSE).
 
 **In short:**
-1. ✅ You can freely use, modify, and share this code
-2. ✅ Must retain author attribution (NiceHello666) and link back to this repository
-3. ❌ Cannot be used for commercial purposes (e.g., selling, as part of paid products)
+1. ✅ Free for noncommercial use — personal projects, learning, research, hobby work, and noncommercial organizations
+2. ✅ You may modify and share it, provided you keep the license text and the noncommercial notice with any copy
+3. ❌ No commercial use of any kind (selling it, shipping it inside a paid product, or using it to run a commercial service)
+4. ℹ️ This is *not* a copyleft license: your own additions do not have to be published. Commercial use requires a separate license from the author.
 
 ---
 

package/README_CN.md

@@ -75,12 +75,13 @@ hncode 从以下几个优秀项目中汲取了灵感：
 
 ## 📄 许可证
 
-本项目的许可受 [GNU General Public License v3.0](https://github.com/NiceHello666/hncode/blob/main/LICENSE) 保护。
+本项目的许可受 [PolyForm Noncommercial License 1.0.0](https://github.com/NiceHello666/hncode/blob/main/LICENSE) 保护。
 
 **简单来说:**
-1. ✅ 你可以自由使用、修改和分享此代码
-2. ✅ 必须保留原作者署名（NiceHello666）并链接回此仓库
-3. ❌ 不得用于商业目的（例如出售、作为付费产品的一部分）
+1. ✅ 非商业用途免费——个人项目、学习、研究、业余爱好，以及非商业组织
+2. ✅ 可以修改和分享，但任何副本都必须附带许可证全文和「不得商用」的声明
+3. ❌ 禁止任何形式的商业使用（出售、作为付费产品的一部分、或用于运营商业服务）
+4. ℹ️ 这**不是** copyleft 许可：你自己新增的部分无需开源。商业使用需向作者单独获取授权。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hncode/hncode",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -22,7 +22,7 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "GPL-3.0-only",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "author": "NiceHello666",
   "keywords": [
     "cli",

package/src/agent-task.js

@@ -176,3 +176,81 @@ export function statusColor(status) {
   if (status === 'completed') return 'gray';
   return 'red';
 }
+
+// ---- background-task transcript card (mirrors kimi-code) --------------------
+// A background task reports its lifecycle as a one-line card in the transcript:
+//
+//     ● agent task completed in background (review the diff)
+//     ✗ bash task failed in background (npm test · exit 1)
+//
+// `phase` drives the bullet colour (started / completed / failed); `headline`
+// and the dim `detail` carry the rest. Ported from kimi-code's
+// formatBackgroundTaskTranscript (apps/kimi-code/src/tui/utils/background-task-status.ts)
+// so the two tools read the same way.
+
+const BG_DETAIL_MAX = 240;
+
+function bgTruncate(value) {
+  if (value === undefined || value === null) return undefined;
+  const collapsed = String(value).trim().replace(/\s+/g, ' ');
+  if (!collapsed) return undefined;
+  return collapsed.length <= BG_DETAIL_MAX ? collapsed : collapsed.slice(0, BG_DETAIL_MAX - 1) + '…';
+}
+
+export function backgroundTaskPhase(status) {
+  if (status === 'running') return 'started';
+  if (status === 'completed') return 'completed';
+  return 'failed';   // failed / timed_out / killed / lost
+}
+
+function bgSubject(kind) {
+  if (kind === 'agent') return 'agent task';
+  if (kind === 'question') return 'question task';
+  return 'bash task';
+}
+
+function bgHeadline(status, kind) {
+  const subject = bgSubject(kind);
+  switch (status) {
+    case 'running': return `${subject} started in background`;
+    case 'completed': return `${subject} completed in background`;
+    case 'failed': return `${subject} failed in background`;
+    case 'timed_out': return `${subject} timed out`;
+    case 'killed': return `${subject} stopped`;
+    case 'lost': return `${subject} lost`;
+    default: return `${subject} ${status}`;
+  }
+}
+
+function bgDetail(task) {
+  const parts = [];
+  const description = bgTruncate(task.description);
+  if (description !== undefined) parts.push(description);
+
+  if (task.status === 'completed' || task.status === 'failed') {
+    if (task.kind === 'process' && task.exitCode !== null && task.exitCode !== undefined) {
+      parts.push(`exit ${task.exitCode}`);
+    }
+  }
+  if (task.status === 'killed') {
+    const reason = bgTruncate(task.stopReason);
+    parts.push(reason !== undefined ? `stopped — ${reason}` : 'stopped');
+  }
+  if (task.status === 'failed') {
+    const reason = bgTruncate(task.stopReason);
+    if (reason !== undefined) parts.push(reason);
+  }
+  if (task.status === 'timed_out') parts.push('timed out');
+  if (task.status === 'lost') parts.push('session restarted before completion');
+
+  return parts.length ? parts.join(' · ') : undefined;
+}
+
+// Build the card payload for a task snapshot.
+export function backgroundTaskCard(task) {
+  return {
+    phase: backgroundTaskPhase(task.status),
+    headline: bgHeadline(task.status, task.kind),
+    detail: bgDetail(task),
+  };
+}

package/src/agent.js

@@ -24,20 +24,10 @@ function hashKey(s) {
   return h.toString(36) + '-' + str.length.toString(36);
 }
 
-// ---- completion guard --------------------------------------------------------
-// A turn is only complete when the model ends it with an actual answer. Models
-// do stop mid-task: the stream ends right after a reasoning block, or with an
-// empty assistant message, and the caller would report "done" for unfinished
-// work. When that happens we tell the model what it did and give it more steps.
-// Bounded, so a model that insists on stopping cannot loop forever.
-export const MAX_NUDGES = 5;
 
-export function nudgeMessage(why) {
-  return `[hncode] Your turn ended without a final answer: ${why}. `
-    + 'This usually means the task is not finished. If the work IS complete, reply with a short '
-    + 'summary of what changed and how you verified it. Otherwise keep going with the tools right '
-    + 'now — do not stop silently.';
-}
+// Final instruction appended to the system prompt (see SYSTEM_PROMPT).
+// (The wording lives in SYSTEM_PROMPT itself, under "Finishing a turn".)
+
 
 // Final instruction appended to the system prompt (see SYSTEM_PROMPT).
 // (The wording lives in SYSTEM_PROMPT itself, under "Finishing a turn".)
@@ -199,7 +189,6 @@ export class Agent {
     let toolCalls = [];
     let emittedEnd = false;
     let thought = '';
-    let nudges = 0;
     // decide whether running out of steps actually left the turn unfinished.
     let hadToolCallsOnFinalStep = false;
 
@@ -252,8 +241,6 @@ export class Agent {
     // No step cap: the loop runs until the model produces a final answer, the
     // user interrupts (Esc / Ctrl-C), or an error ends the turn. maxSteps is
     // kept only for callers that explicitly request a bound (0/undefined = none).
-    // Runaway safety comes from the completion guard (MAX_NUDGES) and the user's
-    // ability to interrupt, not from a fixed tool-round budget.
     const stepLimit = (this.maxSteps > 0) ? this.maxSteps : Infinity;
     for (let step = 0; step < stepLimit; step++) {
       // Process any steer messages collected during the previous step
@@ -278,36 +265,90 @@ export class Agent {
       // preserved rather than simply discarded.
       const maxCtx = this.cfg.maxContextTokens || 512000;
       let usedNow = estimateMessagesTokens(this.messages, this.cfg);
-      if (maxCtx > 0 && usedNow >= maxCtx * 0.85) {
+      if (this.cfg.autoCompact !== false && maxCtx > 0 && usedNow >= maxCtx * 0.85) {
         const before = usedNow;
         // SHELL HOOK: PreCompact — a chance to back up the transcript before the
         // older half is summarized away. Never blocks (the trim must go ahead).
         await runShellHooks(this.hookConfig, 'PreCompact',
           { tokens: usedNow, messages: this.messages }, this.cfg.workspace);
-        const keepN = Math.max(1, Math.ceil(this.messages.length * 0.2));
-        const keep = this.messages.slice(-keepN);
-        const dropped = this.messages.slice(0, this.messages.length - keepN);
-        this.messages = keep;
-        // Ask the model to summarize what was trimmed so far, then prepend it
-        // as a system message so the model retains the conversation arc.
+        // Tell the TUI the trim is under way. Summarizing is a full model
+        // round-trip, so without this the UI sat silent for seconds mid-turn
+        // with no sign anything was happening.
+        this.onEvent({ type: 'compacting', before: usedNow, keep: 0, dropped: 0 });
+        //
+        // ORDER: SUMMARIZE FIRST, THEN TRIM. The summary is generated from the
+        // FULL history so the summarizing model can see what just happened — the
+        // most recent exchange is what tells it what the session is doing now.
+        // Trimming first and summarizing the leftovers summarized only the OLD
+        // part and lost the information the summary needed most.
+        //
+        // The transcript fed to the summarizer is BOUNDED: the full history can
+        // itself exceed the window, in which case the call fails and the trim
+        // would drop everything with nothing to show for it. Keep the MOST RECENT
+        // messages within the budget — they carry the live state — and clip any
+        // single oversized message.
+        const SUMMARY_INPUT_CHARS = 120_000;
+        const perMsgCap = 8_000;
+        const summaryParts = [];
+        let summaryChars = 0;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+          const m = this.messages[i];
+          const raw = typeof m.content === 'string' ? m.content : JSON.stringify(m.content || '');
+          const clipped = raw.length > perMsgCap ? raw.slice(0, perMsgCap) + '\n…[clipped]' : raw;
+          const line = `${m.role}: ${clipped}`;
+          if (summaryChars + line.length > SUMMARY_INPUT_CHARS) break;
+          summaryChars += line.length;
+          summaryParts.unshift(line);
+        }
         let summary = '';
-        if (dropped.length > 0) {
+        if (this.messages.length > 0) {
           const summaryPrompt = [
             { role: 'system', content: 'Summarize the conversation history that follows. Capture the user\'s goals, the key decisions made, files created/modified, and the current state of any ongoing work. Be concise but thorough.' },
-            ...dropped,
+            { role: 'user', content: summaryParts.join('\n\n') },
           ];
           const cfgCopy = { ...this.cfg, maxOutputTokens: Math.min(this.cfg.maxOutputTokens || 4096, 2048) };
           const llm = new LLM(cfgCopy);
           try { summary = await llm.requestText(summaryPrompt); } catch { summary = ''; }
-          if (summary) {
-            this.messages = [{
-              role: 'system',
-              content: `[hncode] Earlier conversation context was auto-compacted to stay within the context window. Summary of what was trimmed:\n\n${summary}`,
-            }, ...this.messages];
-          }
         }
+        // NOW trim. Keep under a TOKEN budget, not a message count: sizes vary by
+        // orders of magnitude (one Read result can dwarf fifty short turns), so a
+        // fixed 20%-of-messages slice could still leave the request above the
+        // threshold or throw away far more than needed. Walk backwards until the
+        // retained tail reaches ~30% of the window; always keep at least the last
+        // two so the newest exchange survives.
+        const keepBudget = Math.max(1, Math.floor(maxCtx * 0.3));
+        let keepFrom = this.messages.length;
+        let keptTokens = 0;
+        while (keepFrom > 0) {
+          const n = this.messages.length - keepFrom;   // already-kept count
+          if (n >= 2 && keptTokens >= keepBudget) break;
+          const cand = this.messages[keepFrom - 1];
+          const t = estimateMessagesTokens([cand], this.cfg) - estimateMessagesTokens([], this.cfg);
+          // Always take at least the last two messages, however big they are.
+          if (n >= 2 && keptTokens + t > keepBudget) break;
+          keptTokens += t;
+          keepFrom--;
+        }
+        // BOUNDARY FIX: never let the kept slice START on a `tool` message whose
+        // assistant(toolCalls) was dropped — most APIs reject a tool result with
+        // no preceding call. Pull the boundary back over any leading tool rows.
+        while (keepFrom > 0 && keepFrom < this.messages.length && this.messages[keepFrom].role === 'tool') {
+          keepFrom--;
+        }
+        const keep = this.messages.slice(keepFrom);
+        const droppedCount = keepFrom;
+        // Final shape: SUMMARY + the most recent messages.
+        // ALWAYS prepend a marker, even when summarization failed. Silently
+        // dropping history left the model (and the user) with no idea that context
+        // was lost; a one-line note makes the gap explicit.
+        this.messages = [{
+          role: 'system',
+          content: summary
+            ? `[hncode] Earlier conversation context was auto-compacted to stay within the context window. Summary of the conversation so far:\n\n${summary}`
+            : `[hncode] ${droppedCount} earlier message(s) were dropped to stay within the context window, and no summary could be generated. Their detail is no longer available.`,
+        }, ...keep];
         usedNow = estimateMessagesTokens(this.messages, this.cfg);
-        this.onEvent({ type: 'compacted', before, after: usedNow, kept: keepN });
+        this.onEvent({ type: 'compacted', before, after: usedNow, kept: keep.length });
       }
       // Live context gauge: report the estimated size of the request about to be
       // sent, so the TUI's context readout is refreshed at every step rather than
@@ -363,18 +404,8 @@ export class Agent {
         for (const msg of steers) this.messages.push({ role: 'user', content: msg });
         continue;
       } else if (!hasText) {
-        if (nudges < MAX_NUDGES) {
-          nudges++;
-          const why = thought.trim()
-            ? 'your last output was reasoning/thinking only, with no answer text'
-            : 'your final message was empty';
-          this.onEvent({ type: 'nudge', reason: why, attempt: nudges, max: MAX_NUDGES });
-          const last = this.messages[this.messages.length - 1];
-          const body = nudgeMessage(why);
-          if (last && last.role === 'user' && typeof last.content === 'string') last.content += '\n\n' + body;
-          else this.messages.push({ role: 'user', content: body });
-          continue;
-        }
+        // No tool calls and no answer text: the model stopped without saying
+        // anything. End the turn.
         break;
       } else {
         // The model produced its answer. A steer typed WHILE that answer was
@@ -512,7 +543,6 @@ export class Agent {
       this.onEvent({
         type: 'incomplete',
         reason: 'the step budget was exhausted while tools were still being called',
-        usedNudges: nudges,
       });
     }
     if (!emittedEnd && this.onEvent) this.onEvent({ type: 'done' });

package/src/config.js

@@ -286,6 +286,12 @@ const b = baseUrl.replace(/\/+$/, '');
     autoUpdate: process.env.HNCODE_AUTO_UPDATE
       ? /^(1|true|yes|on)$/i.test(process.env.HNCODE_AUTO_UPDATE)
       : (root.auto_update === true || root.auto_update === 'true'),
+    // AUTO-COMPACTION (/auto-compact): when true, the agent summarizes older
+    // history once a request reaches 85% of the model context. Default ON. Set
+    // `auto_compact = false` (or HNCODE_AUTO_COMPACT=0) to turn it off.
+    autoCompact: process.env.HNCODE_AUTO_COMPACT
+      ? /^(1|true|yes|on)$/i.test(process.env.HNCODE_AUTO_COMPACT)
+      : !(root.auto_compact === false || root.auto_compact === 'false'),
     // PROMPT CACHE (/cache): explicit cache breakpoints for long stable prefixes.
     // Default ON — it only ever adds provider-recognised markers, and an
     // unsupported field on a non-caching gateway is filtered out in cache.js.
@@ -377,7 +383,7 @@ export function setConfigString(key, value) {
       const opensMultiline = /^"""|^'''/.test(rest) && !/^"""[\s\S]*"""\s*$/.test(rest);
       if (opensMultiline) skipping = true;
       if (!replaced && value !== '' && value != null) {
-        out.push(...renderTomlString(key, String(value)));
+        out.push(...renderTomlString(key, String(value)).split('\n'));
         replaced = true;
       }
       continue;
@@ -386,9 +392,9 @@ export function setConfigString(key, value) {
   }
   while (out.length && out[out.length - 1].trim() === '') out.pop();
   if (!replaced && value !== '' && value != null) {
-    // Insert new root-level keys BEFORE the first [table] section so they
-    // are parsed as root keys, not assigned to a table.
-    const rendered = renderTomlString(key, String(value));
+    // Insert new root-level keys BEFORE the first [table] section so they are
+    // parsed as root keys, not assigned to a table.
+    const rendered = renderTomlString(key, String(value)).split('\n');
     if (firstTableIdx >= 0) {
       out.splice(firstTableIdx, 0, '', ...rendered);
     } else {
@@ -403,13 +409,26 @@ export function setConfigString(key, value) {
 
 // Render `key = <value>` as TOML. Uses a multi-line basic string when the value
 // contains newlines (readable, and TOML-valid), a plain one otherwise.
+//
+// Layout matters: TOML DISCARDS the newline immediately after `"""`, so the
+// value begins on the following line and the closing `"""` must butt up against
+// the last character. The previous form (""" + \n + body + \n + """) parsed back
+// as `value + '\n'`, and because setConfigString writes back whatever it read,
+// every read→write cycle appended another newline (a system prompt gained a
+// blank line per edit).
+//
+//   key = """
+//   <value, verbatim>
+//   """
 function renderTomlString(key, value) {
   if (value.includes('\n')) {
     // Inside """…""" a backslash must be escaped; quotes are fine unless tripled.
     const body = value.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
-    return [`${key} = """`, ...body.split('\n'), '"""'];
+    // `"""` then a newline (discarded by the parser), then the value, then the
+    // closing delimiter on the same line as the value's last line.
+    return [`${key} = """`, ...body.split('\n')].join('\n') + '"""';
   }
-  return [`${key} = "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`];
+  return `${key} = "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 
 // Append (or replace) a [providers.<name>] table in config.toml without
@@ -419,21 +438,30 @@ export function addProvider(name, { base_url, api_key, protocol } = {}) {
   let text = '';
   try { text = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
   const lines = text.split(/\r?\n/);
-  // drop any existing [providers.<name>] block (and its key lines) so we replace it
+  // Drop any existing [providers.<name>] block (and its key lines) so it is
+  // replaced rather than duplicated. Accepts the BARE and QUOTED header forms
+  // (this function writes the quoted one) and unescapes before comparing.
+  const unq = (s) => String(s).replace(/\\(.)/g, '$1');
+  const provRe = /^\s*\[providers\.\s*(?:"((?:[^"\\]|\\.)*)"|([^\]]+))\s*\]\s*$/;
   const out = [];
   let skipping = false;
   for (const ln of lines) {
-    const m = /^\s*\[providers\.([^\]]+)\]\s*$/.exec(ln);
-    if (m) { skipping = m[1] === name; if (skipping) continue; }
+    const m = provRe.exec(ln);
+    if (m) { skipping = unq(m[1] !== undefined ? m[1] : m[2]) === name; if (skipping) continue; }
     else if (/^\s*\[/.test(ln)) skipping = false;
     if (!skipping) out.push(ln);
   }
   while (out.length && out[out.length - 1].trim() === '') out.pop();
   out.push('');
-  out.push(`[providers.${name}]`);
-  if (base_url) out.push(`base_url = "${String(base_url).replace(/"/g, '\\"')}"`);
-  if (api_key) out.push(`api_key = "${String(api_key).replace(/"/g, '\\"')}"`);
-  if (protocol) out.push(`protocol = "${String(protocol).replace(/"/g, '\\"')}"`);
+  // Escape backslashes BEFORE quotes (the other order double-escapes), and quote
+  // the table key too. Raw interpolation meant a provider name or URL holding a
+  // backslash or a quote wrote invalid TOML and broke the ENTIRE config file —
+  // every later launch failed until it was repaired by hand.
+  const q = (v) => `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  out.push(`[providers.${q(name)}]`);
+  if (base_url) out.push(`base_url = ${q(base_url)}`);
+  if (api_key) out.push(`api_key = ${q(api_key)}`);
+  if (protocol) out.push(`protocol = ${q(protocol)}`);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, out.join('\n') + '\n', 'utf8');
   return file;
@@ -449,15 +477,25 @@ export function removeProvider(name) {
   const lines = text.split(/\r?\n/);
   const out = [];
   let skipping = false;
+  // Table headers may be BARE (`[providers.p]`) or QUOTED (`[providers."p"]`) —
+  // addProvider now quotes them so a name containing a quote or backslash stays
+  // valid TOML. Match both and unescape before comparing: with the quoted form
+  // the old bare-only regex captured `"p"` (quotes included), `=== name` never
+  // held, and removeProvider silently deleted nothing.
+  const unq = (s) => String(s).replace(/\\(.)/g, '$1');
+  const provRe = /^\s*\[providers\.\s*(?:"((?:[^"\\]|\\.)*)"|([^\]]+))\s*\]\s*$/;
   // A models key is `[models."provider/modelId"]`; match the provider prefix.
-  const modelRe = /^\s*\[models\."([^"]+)"\]\s*$/;
+  const modelRe = /^\s*\[models\.\s*"((?:[^"\\]|\\.)*)"\s*\]\s*$/;
   for (const ln of lines) {
-    const pm = /^\s*\[providers\.([^\]]+)\]\s*$/.exec(ln);
-    if (pm) { skipping = pm[1] === name; if (skipping) continue; }
+    const pm = provRe.exec(ln);
+    if (pm) {
+      skipping = unq(pm[1] !== undefined ? pm[1] : pm[2]) === name;
+      if (skipping) continue;
+    }
     const mm = modelRe.exec(ln);
     if (mm) {
       // The model key starts with `<provider>/`; skip it if it is this provider's.
-      const keyProvider = mm[1].split('/')[0];
+      const keyProvider = unq(mm[1]).split('/')[0];
       skipping = keyProvider === name;
       if (skipping) continue;
     } else if (/^\s*\[/.test(ln)) {
@@ -484,8 +522,14 @@ export function addModel(provider, modelId, opts = {}) {
   try { text = fs.readFileSync(file, 'utf8'); } catch {}
   const key = modelKey(provider, modelId);
   if (new RegExp(`^\\s*\\[models\\."${escapeRe(key)}"\\]`, 'm').test(text)) return file; // already there
-  const lines = [`[models."${key}"]`, `provider = "${provider}"`, `model = "${modelId}"`];
-  if (opts.display_name) lines.push(`display_name = "${String(opts.display_name).replace(/"/g, '\\"')}"`);
+  // EVERY interpolated string is escaped. These were written raw, so a model id
+  // (or provider) containing a quote or backslash produced malformed TOML and
+  // the ENTIRE config file stopped parsing — every later launch then failed
+  // until the file was repaired by hand. Provider ids and model ids come from
+  // remote APIs, so they are not trusted input.
+  const q = (v) => `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const lines = [`[models.${q(key)}]`, `provider = ${q(provider)}`, `model = ${q(modelId)}`];
+  if (opts.display_name) lines.push(`display_name = ${q(opts.display_name)}`);
   // Persist the context window discovered from /v1/models so resolveConfig can
   // size the context bar per model (not a global 128k).
   if (opts.contextLength) lines.push(`context_length = ${Number(opts.contextLength)}`);

package/src/git.js

@@ -329,4 +329,173 @@ export function statuslineInfo(cwd) {
     deletions: unstaged.deletions + staged.deletions,
     changed: unstaged.files + staged.files,
   };
-}
+}
+// ---- diff / log / push / stash / rebase -------------------------------------
+// Thin wrappers over `git` for the TUI's slash commands. Each returns
+// { ok, ... } and never throws, so a command handler can just print the result.
+
+// Working-tree diff. `staged` shows the index, `path` limits to one file.
+// `stat` returns only the summary line (cheap); otherwise the patch, bounded so a
+// huge change cannot flood the transcript.
+export function diffText(cwd, opts = {}) {
+  const args = ['diff'];
+  if (opts.staged) args.push('--cached');
+  const paths = opts.path ? [opts.path] : [];
+  if (opts.stat) args.push('--stat');
+  const r = runGit(paths.length ? args.concat(['--', ...paths]) : args, cwd);
+  if (!r.ok) return { ok: false, error: r.stderr.trim() || r.error || 'git diff failed', text: '' };
+  let text = r.stdout;
+  if (text.length > 200 * 1024) text = text.slice(0, 200 * 1024) + '\n... [diff truncated]';
+  return { ok: true, text, empty: !text.trim(), error: null };
+}
+
+// Commit history, one commit per line: `<short-sha> <date> <subject>`.
+// `count` defaults to 15; `path` limits to a file's history.
+export function logText(cwd, opts = {}) {
+  const n = Math.max(1, Math.min(500, Number(opts.count) || 15));
+  const args = ['log', `-${n}`, '--pretty=format:%h %ad %s', '--date=short'];
+  if (opts.path) args.push('--', opts.path);
+  const r = runGit(args, cwd);
+  if (!r.ok) return { ok: false, error: r.stderr.trim() || r.error || 'git log failed', text: '' };
+  return { ok: true, text: r.stdout.trim(), empty: !r.stdout.trim(), error: null };
+}
+
+// Push the current (or a named) branch. This is an OUTBOUND operation, so the
+// caller must have confirmed first. `setUpstream` adds -u when the branch has no
+// upstream yet. `force` is opt-in only.
+export function push(cwd, opts = {}) {
+  const branch = String(opts.branch || '').trim();
+  const remote = String(opts.remote || 'origin').trim();
+  const args = ['push'];
+  if (opts.setUpstream) args.push('-u');
+  if (opts.force) args.push('--force-with-lease');   // safer than --force
+  args.push(remote);
+  if (branch) args.push(branch);
+  const r = runGit(args, cwd, { timeoutMs: 120_000 });
+  if (!r.ok) return { ok: false, error: r.stderr.trim() || r.error || 'git push failed', output: r.stdout.trim() };
+  return { ok: true, output: (r.stdout + r.stderr).trim(), error: null };
+}
+
+// Does the branch have an upstream? Used to decide whether push needs -u.
+export function hasUpstream(cwd, branch) {
+  const b = branch || currentBranch(cwd);
+  if (!b) return false;
+  const r = runGit(['rev-parse', '--abbrev-ref', `${b}@{upstream}`], cwd);
+  return r.ok;
+}
+
+// Commits the local branch is ahead/behind its upstream, e.g. "ahead 2, behind 0".
+export function aheadBehind(cwd, branch) {
+  const b = branch || currentBranch(cwd);
+  if (!b) return '';
+  const r = runGit(['rev-list', '--left-right', '--count', `${b}...${b}@{upstream}`], cwd);
+  if (!r.ok) return '';
+  const [ahead, behind] = r.stdout.trim().split(/\s+/);
+  const parts = [];
+  if (Number(ahead)) parts.push(`ahead ${ahead}`);
+  if (Number(behind)) parts.push(`behind ${behind}`);
+  return parts.join(', ');
+}
+
+// ---- stash ------------------------------------------------------------------
+
+export function stashList(cwd) {
+  const r = runGit(['stash', 'list'], cwd);
+  return r.ok ? r.stdout.split('\n').filter(Boolean) : [];
+}
+
+export function stashPush(cwd, message) {
+  const args = ['stash', 'push'];
+  if (message) args.push('-m', String(message));
+  const r = runGit(args, cwd);
+  return r.ok ? { ok: true, output: r.stdout.trim(), error: null }
+    : { ok: false, error: r.stderr.trim() || r.error || 'git stash failed' };
+}
+
+export function stashPop(cwd) {
+  const r = runGit(['stash', 'pop'], cwd);
+  return r.ok ? { ok: true, output: r.stdout.trim(), error: null }
+    : { ok: false, error: r.stderr.trim() || r.error || 'git stash pop failed' };
+}
+
+// ---- rebase -----------------------------------------------------------------
+
+// Rebase the current branch onto `onto`. Returns the git output; on conflict the
+// caller shows git's own message (the user resolves it outside, or with a prompt).
+export function rebase(cwd, onto) {
+  const target = String(onto || '').trim();
+  if (!target) return { ok: false, error: 'a target branch is required' };
+  const r = runGit(['rebase', target], cwd, { timeoutMs: 120_000 });
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || 'git rebase failed' };
+  return { ok: true, output: r.stdout.trim(), error: null };
+}
+
+// ---- async variants (never block the event loop) ----------------------------
+// `runGit` uses spawnSync: on the STARTUP path that freezes the TUI before its
+// first paint, and a cold `git` was measured at ~80-100ms per call (×4 calls).
+// The async form below runs the same command off the main thread, so the frame
+// draws immediately and the badge fills in when the data arrives.
+
+export function runGitAsync(args, cwd, opts = {}) {
+  return new Promise((resolve) => {
+    let child;
+    const timeout = opts.timeoutMs || 30_000;
+    try {
+      child = cp.spawn('git', [...GIT_ENV, ...args], {
+        cwd: cwd || process.cwd(),
+        windowsHide: true,
+        env: { ...process.env, LC_ALL: 'C.UTF-8', LANG: 'C.UTF-8' },
+      });
+    } catch (e) {
+      resolve({ ok: false, stdout: '', stderr: '', code: null, error: e.message });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let done = false;
+    const finish = (r) => { if (!done) { done = true; clearTimeout(timer); resolve(r); } };
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch {}
+      finish({ ok: false, stdout: '', stderr: '', code: null, error: 'git timed out' });
+    }, timeout);
+    if (child.stdout) child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+    if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+    child.on('error', (e) => finish({ ok: false, stdout: '', stderr: '', code: null, error: e.message }));
+    child.on('close', (code) => finish({ ok: code === 0, stdout, stderr, code, error: null }));
+  });
+}
+
+// Async twin of statuslineInfo(). Same shape, same parser — only the four git
+// invocations are concurrent instead of blocking. Each sub-call fails soft, so a
+// non-repo (or a missing git) yields null exactly like the sync version.
+export async function statuslineInfoAsync(cwd) {
+  const inside = await runGitAsync(['rev-parse', '--is-inside-work-tree'], cwd);
+  if (!inside.ok) return null;
+
+  const stat = async (args) => {
+    const r = await runGitAsync(['diff', ...args, '--shortstat'], cwd);
+    if (!r.ok) return { files: 0, insertions: 0, deletions: 0 };
+    const s = r.stdout.trim();
+    const files = /(\d+) files? changed/.exec(s);
+    const ins = /(\d+) insertions?\(\+\)/.exec(s);
+    const del = /(\d+) deletions?\(-\)/.exec(s);
+    return {
+      files: files ? Number(files[1]) : 0,
+      insertions: ins ? Number(ins[1]) : 0,
+      deletions: del ? Number(del[1]) : 0,
+    };
+  };
+
+  const [branchRes, unstaged, staged] = await Promise.all([
+    runGitAsync(['rev-parse', '--abbrev-ref', 'HEAD'], cwd),
+    stat([]),
+    stat(['--cached']),
+  ]);
+  const branch = branchRes.ok ? branchRes.stdout.trim() : '';
+  return {
+    branch: branch || '',
+    insertions: unstaged.insertions + staged.insertions,
+    deletions: unstaged.deletions + staged.deletions,
+    changed: unstaged.files + staged.files,
+  };
+}