wisp-agents 0.7.0 → 0.9.0

package/server/adapters/grok.js

@@ -0,0 +1,251 @@
+// Grok Build adapter — drives `grok --prompt-file … --output-format streaming-messages-json`
+// (Claude Code's stream-json shape, with grok's own tool names).
+//
+// grok has no flag for an extra MCP server (and its GROK_CONFIG overlay can't add one), but an
+// agent definition passed with `--agent <file>` can declare `mcpServers`. So each turn writes a
+// throwaway agent file that inherits the full stock prompt and only adds wisp's server; the model
+// reaches it through grok's `use_tool` as `wisp__ask_user`. The protocol goes in with `--rules`.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
+
+const BIN = process.env.WISP_GROK_BIN || 'grok';
+
+const PERMISSION_MODES = {
+  plan: 'plan',
+  edits: 'acceptEdits',
+  auto: 'bypassPermissions',
+};
+const EFFORT_ORDER = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+export default {
+  id: 'grok',
+  name: 'Grok',
+  askTool: 'wisp__ask_user',
+  models: [{ id: '', label: 'Default', hint: 'Whatever Grok is set to' }],
+  efforts: ['low', 'medium', 'high', 'xhigh'],
+
+  resumeCommand({ resumeId, model, effort }) {
+    return [BIN, ...(resumeId ? ['--resume', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['--reasoning-effort', effort] : [])];
+  },
+
+  async detect() {
+    const found = await detectVersion(BIN);
+    if (!found.available) return found;
+    // `grok models` prints "  * grok-4.7 (default)" / "  - grok-4.6" lines.
+    const ids = [...(await quietOutput(BIN, ['models'])).matchAll(/^\s+[*-]\s+([\w.\-/:]+)/gm)].map((m) => m[1]);
+    if (!ids.length) return found;
+    const meta = cachedModels();
+    const models = ids.map((id) => {
+      const info = meta[id]?.info || {};
+      const efforts = info.supports_reasoning_effort === false ? [] : effortsOf(info.reasoning_efforts);
+      return { id, label: info.name || id, hint: clip(info.description || id, 60), ...(efforts && { efforts }) };
+    });
+    return { ...found, models: [this.models[0], ...models] };
+  },
+
+  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, onEvent }) {
+    // grok -p doesn't read stdin, and a prompt in argv is capped on Windows: hand it over as a file.
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'wisp-grok-'));
+    const promptFile = path.join(tmp, 'prompt.md');
+    fs.writeFileSync(promptFile, prompt + attachmentNote(attachments));
+
+    const args = [
+      '--prompt-file', promptFile,
+      '--output-format', 'streaming-messages-json',
+      '--permission-mode', PERMISSION_MODES[mode] || 'acceptEdits',
+      '--rules', systemPrompt,
+      // A headless run can't answer grok's own question tool; wisp's ask_user (or a question block) replaces it.
+      '--disallowed-tools', 'ask_user_question',
+      '--no-auto-update',
+    ];
+    if (model) args.push('--model', model);
+    if (effort) args.push('--reasoning-effort', effort);
+    if (resumeId) args.push('--resume', resumeId);
+    if (Object.keys(mcpServers).length) {
+      const agentFile = path.join(tmp, 'wisp.md');
+      fs.writeFileSync(agentFile, agentDefinition(mcpServers));
+      args.push('--agent', agentFile);
+    }
+
+    const files = fileTracker(cwd);
+    const pending = new Map(); // tool_use_id -> { name, input }
+    let session = null;
+    let sawResult = false;
+    let error = null;
+
+    const handle = spawnJsonl({
+      bin: BIN,
+      args,
+      cwd,
+      env: { ...process.env, GROK_DISABLE_AUTOUPDATER: '1' },
+      onEvent,
+      onJson(msg) {
+        if (msg.session_id && msg.session_id !== session) onEvent({ type: 'session', id: (session = msg.session_id) });
+        // Subagent traffic carries its parent's tool id; only the main conversation is shown.
+        if (msg.parent_tool_use_id) return;
+        switch (msg.type) {
+          case 'assistant':
+            for (const part of msg.message?.content || []) {
+              if (part.type === 'text' && part.text?.trim()) onEvent({ type: 'text', text: part.text });
+              else if (part.type === 'thinking') onEvent({ type: 'thinking' });
+              else if (part.type === 'server_tool_use') onEvent({ type: 'tool', kind: 'web', label: `Searching the web: ${clip(part.input?.query, 50)}` });
+              else if (part.type === 'tool_use') {
+                const input = part.input || {};
+                pending.set(part.id, { name: part.name, input });
+                if (part.name === 'write' && input.file_path) files.remember(input.file_path);
+                // Streamed once answered, so "waiting" would land after "You answered"; the trail has both.
+                if (part.name === 'use_tool' && input.tool_name === 'wisp__ask_user') continue;
+                onEvent({ type: 'tool', ...describeTool(part.name, input, cwd) });
+              }
+            }
+            break;
+          case 'user':
+            for (const part of msg.message?.content || []) {
+              if (part.type !== 'tool_result') continue;
+              const call = pending.get(part.tool_use_id);
+              pending.delete(part.tool_use_id);
+              if (!call) continue;
+              if (part.is_error) onEvent({ type: 'tool_error', name: call.name, text: clip(flatten(part.content), 400) });
+              else {
+                const change = captureChange(call.name, call.input, cwd, files);
+                if (change) onEvent({ type: 'change', ...change });
+              }
+            }
+            break;
+          case 'result':
+            sawResult = true;
+            onEvent({
+              type: 'result',
+              text: msg.is_error ? (msg.errors || []).join('\n') || msg.result || `grok stopped: ${msg.subtype}` : msg.result ?? '',
+              isError: !!msg.is_error || (msg.subtype && msg.subtype !== 'success'),
+              stats: {
+                costUsd: msg.total_cost_usd || undefined, // 0 means "not reported", never free
+                durationMs: msg.duration_ms,
+                turns: msg.num_turns,
+                inputTokens: msg.usage?.input_tokens,
+                outputTokens: msg.usage?.output_tokens,
+              },
+            });
+            break;
+          case 'error':
+            error = msg.message || 'grok reported an error.';
+            break;
+        }
+      },
+      onClose({ code, signal, stderr, stopped }) {
+        if (sawResult) return;
+        onEvent({ type: 'result', isError: true, stopped, text: error || stderr || `grok exited with ${signal || `code ${code}`}` });
+      },
+    });
+    handle.done.finally(() => fs.rmSync(tmp, { recursive: true, force: true }));
+    return handle;
+  },
+};
+
+// `prompt_mode: full` keeps grok's stock system prompt; the body adds nothing.
+function agentDefinition(mcpServers) {
+  const servers = Object.entries(mcpServers).map(([name, srv]) => ({
+    name,
+    command: srv.command,
+    args: srv.args || [],
+    env: srv.env || {},
+    tool_timeout_sec: ASK_TIMEOUT_MS / 1000,
+    startup_timeout_sec: 60,
+  }));
+  // YAML is a superset of JSON, so JSON values need no escaping of their own.
+  return `---\nname: wisp\ndescription: A task launched by wisp\nprompt_mode: full\nagents_md: true\nmcpServers: ${JSON.stringify(servers)}\n---\n`;
+}
+
+// grok caches the model catalog, with each model's reasoning levels, in $GROK_HOME.
+function cachedModels() {
+  try {
+    const home = process.env.GROK_HOME || path.join(os.homedir(), '.grok');
+    return JSON.parse(fs.readFileSync(path.join(home, 'models_cache.json'), 'utf8')).models || {};
+  } catch {
+    return {};
+  }
+}
+
+function effortsOf(list) {
+  if (!Array.isArray(list)) return undefined;
+  const rank = (id) => (EFFORT_ORDER.includes(id) ? EFFORT_ORDER.indexOf(id) : EFFORT_ORDER.length);
+  return list.map((e) => e.id).filter(Boolean).sort((a, b) => rank(a) - rank(b));
+}
+
+function describeTool(name, input, cwd) {
+  const f = rel(input.target_file || input.file_path || input.path || input.target_directory, cwd);
+  switch (name) {
+    case 'read_file':
+      return { kind: 'read', label: `Reading ${f}`, file: f };
+    case 'search_replace':
+      return { kind: 'edit', label: `Editing ${f}`, file: f };
+    case 'write':
+      return { kind: 'edit', label: `Writing ${f}`, file: f };
+    case 'run_terminal_command':
+    case 'run_terminal_cmd':
+      return { kind: 'run', label: input.description ? clip(input.description) : `Running ${clip(input.command, 60)}`, detail: input.command };
+    case 'grep':
+      return { kind: 'search', label: `Searching for “${clip(input.pattern, 40)}”` };
+    case 'list_dir':
+      return { kind: 'search', label: `Listing ${isDir(input.target_directory, cwd) ? '.' : f || '.'}` };
+    case 'web_search':
+      return { kind: 'web', label: `Searching the web: ${clip(input.query, 50)}` };
+    case 'web_fetch':
+      return { kind: 'web', label: `Reading ${clip(input.url, 60)}` };
+    case 'spawn_subagent':
+    case 'task':
+      return { kind: 'agent', label: `Delegating: ${clip(input.description || input.prompt, 60)}` };
+    case 'todo_write': {
+      const active = input.todos?.find((t) => t.status === 'in_progress' && t.content);
+      return { kind: 'plan', label: active ? clip(active.content) : 'Planning' };
+    }
+    case 'enter_plan_mode':
+    case 'exit_plan_mode':
+      return { kind: 'plan', label: 'Planning' };
+    case 'search_tool':
+      return { kind: 'search', label: `Looking up tools: ${clip(input.query, 50)}` };
+    case 'use_tool':
+      return describeMcp(String(input.tool_name || ''), input.tool_input || {});
+    default:
+      return { kind: 'tool', label: `Using ${name.replace(/_/g, ' ')}` };
+  }
+}
+
+// grok passes absolute paths, also for the project root itself (which rel() leaves as is).
+function isDir(dir, cwd) {
+  try {
+    return !!dir && fs.realpathSync(path.resolve(cwd, dir)) === fs.realpathSync(cwd);
+  } catch {
+    return false;
+  }
+}
+
+// MCP tools are called through `use_tool` with a `server__tool` name.
+function describeMcp(tool, input) {
+  switch (tool) {
+    case 'wisp__ask_user':
+      return { kind: 'wait', label: 'Waiting for your answer' };
+    case 'wisp__delegate':
+      return { kind: 'agent', label: `Delegating to ${clip([...new Set((input.tasks || []).map((t) => t.subagent))].join(', ') || 'subagents', 60)}` };
+    case 'wisp__subagent_results':
+      return { kind: 'agent', label: 'Waiting on subagents' };
+    default:
+      return { kind: 'tool', label: `Using ${tool.split('__').join(' · ') || 'an integration'}` };
+  }
+}
+
+// Called once a tool succeeded. grok may stream a batch of tool calls after running them, so the
+// "before" side of a write can't come from disk at tool_use time: the tracker supplies it.
+function captureChange(name, input, cwd, files) {
+  const file = input.file_path;
+  if (!file) return null;
+  if (name === 'search_replace' && typeof input.old_string === 'string' && input.old_string) {
+    files.change(file); // keep the tracker's snapshot current for later writes
+    return { file: rel(file, cwd), op: 'edit', edits: [{ before: input.old_string, after: input.new_string ?? '' }] };
+  }
+  if (name === 'search_replace' || name === 'write') return files.change(file);
+  return null;
+}

package/server/adapters/index.js

@@ -29,8 +29,9 @@ import codex from './codex.js';
 import opencode from './opencode.js';
 import cursor from './cursor.js';
 import antigravity from './antigravity.js';
+import grok from './grok.js';
 
-export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity].map((a) => [a.id, a]));
+export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity, grok].map((a) => [a.id, a]));
 
 const detected = new Map();
 
@@ -41,7 +42,8 @@ export async function listAgents() {
       const found = await detected.get(a.id);
       // Only a hit is cached: a CLI installed while wisp is running shows up on the next call.
       if (!found.available) detected.delete(a.id);
-      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], ...found };
+      // delegates: can lead a team of subagents (needs wisp's MCP server injected).
+      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], delegates: a.askTool !== null, ...found };
     }),
   );
 }

package/server/adapters/opencode.js

@@ -38,7 +38,7 @@ export default {
     return { ...found, models: [this.models[0], ...models] };
   },
 
-  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, onEvent }) {
+  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, delegating = false, onEvent }) {
     // The prompt goes on stdin; `run` appends piped stdin to the (empty) message.
     const args = ['run', '--format', 'json'];
     if (mode === 'plan') args.push('--agent', 'plan');
@@ -60,6 +60,8 @@ export default {
         ...inline,
         mcp: { ...inline.mcp, ...mcp },
         experimental: { ...inline.experimental, mcp_timeout: ASK_TIMEOUT_MS },
+        // Its built-in `task` subagents would bypass the user's team.
+        ...(delegating && { permission: { ...(typeof inline.permission === 'object' ? inline.permission : inline.permission && { '*': inline.permission }), task: 'deny' } }),
       });
     }
 
@@ -169,6 +171,10 @@ function describeTool(name, input, cwd) {
     }
     case 'wisp_ask_user':
       return { kind: 'wait', label: 'Waiting for your answer' };
+    case 'wisp_delegate':
+      return { kind: 'agent', label: `Delegated to ${clip([...new Set((input.tasks || []).map((t) => t.subagent))].join(', ') || 'subagents', 60)}` };
+    case 'wisp_subagent_results':
+      return { kind: 'agent', label: 'Collected subagent reports' };
     default:
       return { kind: 'tool', label: `Using ${name.replace(/_/g, ' ')}` };
   }

package/server/checkpoint.js

@@ -0,0 +1,348 @@
+// Per-turn git checkpoints, single-file revert, turn rollback, and action command execution.
+
+import { execFileSync, spawn as nodeSpawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { killTree } from './proc.js';
+import { MAX_SNAPSHOT, rel } from './adapters/common.js';
+
+const MAX_EXEC_OUTPUT = 32 * 1024;
+const EXEC_TIMEOUT_MS = 60_000;
+
+function git(cwd, args, opts = {}) {
+  return execFileSync('git', args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5000,
+    ...opts,
+  });
+}
+
+function tryGit(cwd, args, opts) {
+  try {
+    return git(cwd, args, opts).toString('utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+// Snapshot the working tree before a turn starts. `git stash create` writes a commit object
+// holding tracked working-tree and index changes without touching HEAD, the index, or the stash
+// reflog; if the tree is clean it prints nothing and HEAD is the snapshot. Pinning the SHA under
+// refs/wisp/checkpoints/<session>/<turn> keeps `git gc` from collecting it.
+export function captureCheckpoint(cwd, sessionId, turnId) {
+  if (!cwd || !fs.existsSync(cwd)) return null;
+  const head = tryGit(cwd, ['rev-parse', '--verify', 'HEAD']);
+  if (!head) return null;
+  const stash = tryGit(cwd, ['stash', 'create']);
+  const commit = stash || head;
+  if (sessionId && turnId) {
+    tryGit(cwd, ['update-ref', `refs/wisp/checkpoints/${sessionId}/${turnId}`, commit]);
+  }
+  const branch = tryGit(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']) || '';
+  const untrackedRaw = tryGit(cwd, ['ls-files', '--others', '--exclude-standard'], { maxBuffer: 2 * 1024 * 1024 });
+  const untracked = untrackedRaw ? untrackedRaw.split('\n').filter(Boolean).slice(0, 500) : [];
+  return {
+    commit,
+    head,
+    dirty: !!stash,
+    branch,
+    untracked,
+    at: Date.now(),
+  };
+}
+
+// The first turn in a worktree made for it: clean, at its base commit, so the checkpoint is known
+// without asking git (captureCheckpoint's synchronous calls held up every launch, once per run).
+// The base commit stays reachable from the base branch, so it needs no pinning ref.
+export function freshCheckpoint(wt) {
+  return { commit: wt.head, head: wt.head, dirty: false, branch: wt.branch, untracked: [], at: Date.now() };
+}
+
+export function cleanupCheckpoints(cwd, sessionId) {
+  if (!cwd || !sessionId || !fs.existsSync(cwd)) return;
+  const refs = tryGit(cwd, ['for-each-ref', '--format=%(refname)', `refs/wisp/checkpoints/${sessionId}/`]);
+  if (!refs) return;
+  for (const ref of refs.split('\n').filter(Boolean)) {
+    tryGit(cwd, ['update-ref', '-d', ref]);
+  }
+}
+
+export function readGitFile(cwd, commit, file) {
+  if (!cwd || !commit || !file || path.isAbsolute(file)) return null;
+  const gitPath = `./${file.split(path.sep).join('/')}`;
+  try {
+    const out = git(cwd, ['show', `${commit}:${gitPath}`], { maxBuffer: 8 * MAX_SNAPSHOT });
+    return out.length <= MAX_SNAPSHOT ? out.toString('utf8') : '';
+  } catch {
+    return null;
+  }
+}
+
+function readDiskSnapshot(abs) {
+  try {
+    const st = fs.statSync(abs);
+    if (!st.isFile()) return null;
+    return st.size <= MAX_SNAPSHOT ? fs.readFileSync(abs, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeDiskSnapshot(abs, content) {
+  if (content === null || content === undefined) {
+    fs.rmSync(abs, { force: true });
+    return;
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf8');
+}
+
+function resolveInsideCwd(cwd, file) {
+  if (!file || typeof file !== 'string') {
+    throw Object.assign(new Error('file path required'), { status: 400 });
+  }
+  const abs = path.resolve(cwd, file);
+  const relPath = path.relative(cwd, abs);
+  if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
+    throw Object.assign(new Error(`File lies outside the project folder: ${file}`), { status: 400 });
+  }
+  return { abs, relPath: rel(file, cwd) || relPath };
+}
+
+function findChangeEntry(turn, file, cwd) {
+  if (!turn?.changes?.length) return null;
+  const r = rel(file, cwd);
+  return (
+    turn.changes.find((c) => c.file === file || c.file === r) ||
+    turn.changes.find((c) => c.file.endsWith('/' + file) || file.endsWith('/' + c.file))
+  );
+}
+
+const sessionDir = (session) => session.worktree?.cwd || session.cwd;
+
+// Revert (or re-apply when restore=true) a single file's changes from `turn`.
+export function revertFileChange(session, turn, file, { restore = false } = {}) {
+  const cwd = sessionDir(session);
+  const { abs, relPath } = resolveInsideCwd(cwd, file);
+  const entry = findChangeEntry(turn, file, cwd);
+  const commit = turn.checkpoint?.commit;
+  if (!entry && !commit) {
+    throw Object.assign(new Error(`No captured changes or checkpoint for ${relPath}`), { status: 404 });
+  }
+
+  if (restore) {
+    if (entry?.afterSnapshot !== undefined) {
+      writeDiskSnapshot(abs, entry.afterSnapshot);
+    } else if (entry?.edits?.length) {
+      if (entry.op === 'create' || entry.op === 'write') {
+        writeDiskSnapshot(abs, entry.edits.at(-1).after ?? '');
+      } else {
+        let cur = readDiskSnapshot(abs) ?? '';
+        for (const e of entry.edits) {
+          if (e.before && cur.includes(e.before)) cur = cur.replace(e.before, e.after ?? '');
+        }
+        writeDiskSnapshot(abs, cur);
+      }
+    } else {
+      throw Object.assign(new Error(`Nothing to re-apply for ${relPath}`), { status: 400 });
+    }
+    if (entry) entry.reverted = false;
+    if (turn.changes?.every((c) => !c.reverted)) delete turn.rolledBackAt;
+    return { file: entry?.file || relPath, reverted: false };
+  }
+
+  // Save what is currently on disk so the user can Undo / Re-apply in one click.
+  const currentOnDisk = readDiskSnapshot(abs);
+  if (entry) entry.afterSnapshot = currentOnDisk;
+
+  // 1. Prefer the exact pre-turn file content recorded when the turn first touched the file.
+  if (entry && entry.beforeFile !== undefined) {
+    writeDiskSnapshot(abs, entry.op === 'create' ? null : entry.beforeFile);
+  } else if (commit) {
+    // 2. Otherwise check the turn's git checkpoint commit.
+    const fromGit = readGitFile(cwd, commit, entry?.file || relPath);
+    if (fromGit !== null) {
+      writeDiskSnapshot(abs, fromGit);
+    } else if (entry?.op === 'create' || !(turn.checkpoint?.untracked || []).includes(entry?.file || relPath)) {
+      writeDiskSnapshot(abs, null);
+    } else if (entry?.edits?.length) {
+      reverseEditsOnDisk(abs, entry);
+    }
+  } else if (entry) {
+    // 3. Fallback for non-git folders or legacy turns.
+    if (entry.op === 'create') {
+      writeDiskSnapshot(abs, null);
+    } else if (entry.op === 'write' && entry.edits?.[0]?.before !== undefined) {
+      writeDiskSnapshot(abs, entry.edits[0].before);
+    } else {
+      reverseEditsOnDisk(abs, entry);
+    }
+  }
+
+  if (entry) entry.reverted = true;
+  return { file: entry?.file || relPath, reverted: true };
+}
+
+function reverseEditsOnDisk(abs, entry) {
+  const cur = readDiskSnapshot(abs);
+  if (cur === null) return;
+  let next = cur;
+  for (const e of [...(entry.edits || [])].reverse()) {
+    if (e.after && next.includes(e.after)) {
+      next = next.replace(e.after, e.before ?? '');
+    }
+  }
+  writeDiskSnapshot(abs, next);
+}
+
+// Restore the project working tree to the state before `turn` ran (or undo that rollback when restore=true).
+export function rollbackToTurn(session, turn, { restore = false } = {}) {
+  const cwd = sessionDir(session);
+  const idx = session.turns.indexOf(turn);
+  if (idx < 0) throw Object.assign(new Error('No such turn'), { status: 404 });
+  const affected = session.turns.slice(idx);
+  const touchedFiles = [...new Set(affected.flatMap((t) => (t.changes || []).map((c) => c.file)))];
+
+  if (restore) {
+    const pre = turn.preRollback;
+    if (!pre) {
+      for (const t of affected) {
+        for (const c of t.changes || []) {
+          revertFileChange(session, t, c.file, { restore: true });
+        }
+        delete t.rolledBackAt;
+      }
+      return { files: touchedFiles, rolledBack: false };
+    }
+    if (pre.commit) {
+      tryGit(cwd, ['checkout', pre.commit, '--', '.']);
+      tryGit(cwd, ['read-tree', 'HEAD']);
+    }
+    for (const [relFile, content] of Object.entries(pre.files || {})) {
+      const { abs } = resolveInsideCwd(cwd, relFile);
+      writeDiskSnapshot(abs, content);
+    }
+    for (const t of affected) {
+      delete t.rolledBackAt;
+      for (const c of t.changes || []) c.reverted = false;
+    }
+    return { files: Object.keys(pre.files || {}).length ? Object.keys(pre.files) : touchedFiles, rolledBack: false };
+  }
+
+  const cp = turn.checkpoint;
+  const preUntracked = new Set(cp?.untracked || []);
+  const curUntrackedRaw = cp?.commit ? tryGit(cwd, ['ls-files', '--others', '--exclude-standard'], { maxBuffer: 2 * 1024 * 1024 }) : null;
+  const curUntracked = curUntrackedRaw ? curUntrackedRaw.split('\n').filter(Boolean).slice(0, 500) : [];
+  const newUntracked = curUntracked.filter((f) => !preUntracked.has(f));
+
+  // Snapshot current state of all affected files + new untracked files + git tree before rolling back so Undo works.
+  const preFiles = {};
+  for (const f of [...new Set([...touchedFiles, ...newUntracked])]) {
+    try {
+      const { abs } = resolveInsideCwd(cwd, f);
+      preFiles[f] = readDiskSnapshot(abs);
+    } catch {}
+  }
+  const preCp = captureCheckpoint(cwd, session.id, `${turn.id}-undo`);
+  turn.preRollback = { commit: preCp?.commit || null, files: preFiles };
+
+  if (cp?.commit) {
+    // Find any tracked files added since the checkpoint commit so we can remove them too.
+    const addedRaw = tryGit(cwd, ['diff', '--name-only', '--diff-filter=D', 'HEAD', cp.commit]) || '';
+    const addedTracked = addedRaw.split('\n').filter(Boolean);
+
+    // Restore tracked files from the checkpoint commit.
+    tryGit(cwd, ['checkout', cp.commit, '--', '.']);
+    // Keep the git index aligned with HEAD rather than the stash commit's tree.
+    tryGit(cwd, ['read-tree', 'HEAD']);
+
+    for (const f of [...addedTracked, ...newUntracked]) {
+      try {
+        const { abs } = resolveInsideCwd(cwd, f);
+        fs.rmSync(abs, { force: true });
+      } catch {}
+    }
+
+    // Restore or remove untracked files touched in the affected turns.
+    for (const t of affected.slice().reverse()) {
+      for (const c of t.changes || []) {
+        try {
+          const { abs, relPath } = resolveInsideCwd(cwd, c.file);
+          const inGit = readGitFile(cwd, cp.commit, relPath) !== null;
+          if (!inGit) {
+            if (c.op === 'create' || (!preUntracked.has(relPath) && c.beforeFile === null)) {
+              fs.rmSync(abs, { force: true });
+            } else if (typeof c.beforeFile === 'string') {
+              writeDiskSnapshot(abs, c.beforeFile);
+            }
+          }
+        } catch {}
+      }
+    }
+  } else {
+    // Non-git folder or turn without a git checkpoint: revert each turn's captured file changes in reverse.
+    for (const t of affected.slice().reverse()) {
+      for (const c of [...(t.changes || [])].reverse()) {
+        revertFileChange(session, t, c.file, { restore: false });
+      }
+    }
+  }
+
+  const now = Date.now();
+  for (const t of affected) {
+    t.rolledBackAt = now;
+    for (const c of t.changes || []) c.reverted = true;
+  }
+  return { files: touchedFiles, rolledBack: true, commit: cp?.head || cp?.commit || null };
+}
+
+// Run a shell command from an actionable presentation block inside `cwd`.
+export function execCommand(cwd, command, { timeoutMs = EXEC_TIMEOUT_MS } = {}) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return Promise.reject(Object.assign(new Error('command required'), { status: 400 }));
+  const t0 = Date.now();
+
+  return new Promise((resolve) => {
+    const child = nodeSpawn(cmd, {
+      cwd,
+      env: { ...process.env, PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', CI: '1' },
+      shell: true,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    const append = (chunk) => {
+      if (out.length < MAX_EXEC_OUTPUT) out += chunk.toString('utf8').slice(0, MAX_EXEC_OUTPUT - out.length);
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        command: cmd,
+        output: (out ? `${out}\n` : '') + err.message,
+        exitCode: 1,
+        durationMs: Date.now() - t0,
+      });
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const suffix = timedOut ? `\n[timed out after ${Math.round(timeoutMs / 1000)}s]` : '';
+      resolve({
+        command: cmd,
+        output: (out.replace(/\s+$/, '') + suffix).trim(),
+        exitCode: timedOut ? 124 : (code ?? 1),
+        durationMs: Date.now() - t0,
+      });
+    });
+  });
+}