wispy-cli 2.7.11 → 2.7.12

package/bin/wispy.mjs

@@ -23,6 +23,47 @@ const rootDir = join(__dirname, "..");
 const args = process.argv.slice(2);
 const command = args[0];
 
+// ── Global flags parsed early ─────────────────────────────────────────────────
+
+/**
+ * Extract a flag value: --flag value or --flag=value
+ * Returns the value string or null if not found.
+ */
+function extractFlag(flagNames, removeFromArgs = false) {
+  for (const flag of Array.isArray(flagNames) ? flagNames : [flagNames]) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx + 1 < args.length) {
+      const value = args[idx + 1];
+      if (removeFromArgs) { args.splice(idx, 2); }
+      return value;
+    }
+    // --flag=value form
+    const prefix = flag + "=";
+    const eqIdx = args.findIndex(a => a.startsWith(prefix));
+    if (eqIdx !== -1) {
+      const value = args[eqIdx].slice(prefix.length);
+      if (removeFromArgs) { args.splice(eqIdx, 1); }
+      return value;
+    }
+  }
+  return null;
+}
+
+/** Returns true if a boolean flag is present. */
+function hasFlag(flag) {
+  return args.includes(flag);
+}
+
+// Parse global flags (order doesn't matter, remove from args so REPL doesn't see them)
+const globalProfile = extractFlag(["--profile", "-p"], true);
+const globalPersonality = extractFlag(["--personality"], true);
+const globalJsonMode = hasFlag("--json");
+if (globalJsonMode) { args.splice(args.indexOf("--json"), 1); }
+
+// Expose for submodules via env
+if (globalProfile) process.env.WISPY_PROFILE = globalProfile;
+if (globalPersonality) process.env.WISPY_PERSONALITY = globalPersonality;
+
 // ── Flags ─────────────────────────────────────────────────────────────────────
 
 if (args.includes("--version") || command === "--version" || command === "-v") {
@@ -44,9 +85,12 @@ AI workspace assistant — chat, automate, and orchestrate from the terminal.
 Usage:
   wispy                        Start interactive REPL
   wispy <message>              One-shot chat
+  wispy exec <message>         Non-interactive one-shot (CI/pipeline friendly)
   wispy setup                  Run first-time setup wizard
   wispy config [show|get|set|delete|reset|path|edit]
                                Manage configuration
+  wispy features [list|enable|disable]
+                               Manage feature flags
   wispy model                  Show or change AI model
   wispy doctor                 Check system health
   wispy browser [tabs|attach|navigate|screenshot|doctor]
@@ -69,9 +113,12 @@ Usage:
 
 Options:
   -w, --workstream <name>      Set active workstream
+  -p, --profile <name>         Use a named config profile
   --session <id>               Resume a session
   --model <name>               Override AI model
   --provider <name>            Override AI provider
+  --personality <name>         Set personality (pragmatic|concise|explanatory|friendly|strict)
+  --json                       Output JSONL events (for exec command, CI/pipeline use)
   --help, -h                   Show this help
   --version, -v                Show version
 `);
@@ -529,6 +576,131 @@ if (command === "improve") {
   process.exit(0);
 }
 
+// ── Features ──────────────────────────────────────────────────────────────────
+
+if (command === "features") {
+  try {
+    const { FeatureManager } = await import(join(rootDir, "core/features.mjs"));
+    const fm = new FeatureManager();
+    const sub = args[1];
+
+    if (!sub || sub === "list") {
+      const features = await fm.list();
+      const stageOrder = { stable: 0, experimental: 1, development: 2 };
+      features.sort((a, b) => (stageOrder[a.stage] ?? 9) - (stageOrder[b.stage] ?? 9) || a.name.localeCompare(b.name));
+
+      const stageLabel = { stable: "stable", experimental: "experimental", development: "development" };
+      const stageColors = { stable: "\x1b[32m", experimental: "\x1b[33m", development: "\x1b[31m" };
+      const reset = "\x1b[0m";
+      const dim = "\x1b[2m";
+
+      console.log(`\n  Feature Flags (${features.length})\n`);
+      let lastStage = null;
+      for (const f of features) {
+        if (f.stage !== lastStage) {
+          console.log(`  ${stageColors[f.stage] ?? ""}── ${f.stage} ──${reset}`);
+          lastStage = f.stage;
+        }
+        const status = f.enabled ? "\x1b[32m✓ on \x1b[0m" : "\x1b[2m✗ off\x1b[0m";
+        const changed = f.enabled !== f.default ? " \x1b[33m(overridden)\x1b[0m" : "";
+        console.log(`  ${status}  ${f.name.padEnd(25)} ${dim}${f.description}${reset}${changed}`);
+      }
+      console.log("");
+      console.log(`  ${dim}Use: wispy features enable <name> / wispy features disable <name>${reset}\n`);
+    } else if (sub === "enable") {
+      const name = args[2];
+      if (!name) { console.error("Usage: wispy features enable <name>"); process.exit(1); }
+      const result = await fm.enable(name);
+      console.log(`  ✓ Feature "${name}" enabled.`);
+    } else if (sub === "disable") {
+      const name = args[2];
+      if (!name) { console.error("Usage: wispy features disable <name>"); process.exit(1); }
+      const result = await fm.disable(name);
+      console.log(`  ✓ Feature "${name}" disabled.`);
+    } else {
+      console.error(`Unknown subcommand: ${sub}`);
+      console.log("Available: list, enable <name>, disable <name>");
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error("Features error:", err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── Exec (non-interactive one-shot with optional JSONL output) ────────────────
+
+if (command === "exec") {
+  try {
+    // Message is everything after "exec" and any flags
+    const messageArgs = args.slice(1).filter(a => !a.startsWith("--") && !a.startsWith("-p"));
+    const message = messageArgs.join(" ").trim();
+
+    if (!message) {
+      console.error("Usage: wispy exec <message> [--json] [--profile <name>] [--personality <name>]");
+      process.exit(1);
+    }
+
+    // Load config (with optional profile)
+    const { loadConfigWithProfile } = await import(join(rootDir, "core/config.mjs"));
+    const { WispyEngine } = await import(join(rootDir, "core/engine.mjs"));
+    const { createEmitter } = await import(join(rootDir, "lib/jsonl-emitter.mjs"));
+
+    const profileName = globalProfile;
+    const profileConfig = await loadConfigWithProfile(profileName);
+
+    // Apply config overrides from profile
+    if (profileConfig.provider) process.env.WISPY_PROVIDER = process.env.WISPY_PROVIDER || profileConfig.provider;
+    if (profileConfig.model)    process.env.WISPY_MODEL = process.env.WISPY_MODEL || profileConfig.model;
+
+    const personality = globalPersonality || profileConfig.personality || null;
+
+    const engine = new WispyEngine({
+      personality,
+      workstream: process.env.WISPY_WORKSTREAM ?? "default",
+    });
+
+    const initResult = await engine.init({ skipMcp: false });
+    if (!initResult) {
+      if (globalJsonMode) {
+        const emitter = createEmitter(true);
+        emitter.error(new Error("No AI provider configured"));
+        emitter.done({ tokens: {}, duration_ms: 0 });
+      } else {
+        console.error("⚠️  No AI provider configured. Run `wispy setup` or set an API key.");
+      }
+      process.exit(1);
+    }
+
+    const emitter = createEmitter(globalJsonMode);
+
+    const result = await engine.processMessage(null, message, {
+      emitter,
+      personality,
+      skipSkillCapture: true,
+      skipUserModel: true,
+    });
+
+    if (!globalJsonMode) {
+      // Normal output: just print the assistant response
+      console.log(result.content);
+    }
+    // In JSON mode, everything was already emitted via the emitter
+  } catch (err) {
+    if (globalJsonMode) {
+      const { createEmitter } = await import(join(rootDir, "lib/jsonl-emitter.mjs"));
+      const emitter = createEmitter(true);
+      emitter.error(err);
+      emitter.done({ tokens: {}, duration_ms: 0 });
+    } else {
+      console.error("Exec error:", err.message);
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // ── Continuity ────────────────────────────────────────────────────────────────
 
 if (command === "where") {

package/core/config.mjs

@@ -133,6 +133,40 @@ export async function saveConfig(config) {
   await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
 }
 
+/**
+ * Load config with a named profile merged on top.
+ * Profile keys override base config keys, but unset keys remain from base.
+ * The "profiles" map itself is stripped from the merged result.
+ *
+ * @param {string|null} profileName - Profile name to apply, or null for base config
+ * @returns {Promise<object>} Merged configuration object
+ */
+export async function loadConfigWithProfile(profileName) {
+  const config = await loadConfig();
+  if (!profileName) return config;
+
+  const profiles = config.profiles ?? {};
+  const profile = profiles[profileName];
+
+  if (!profile) {
+    throw new Error(`Profile "${profileName}" not found. Available profiles: ${Object.keys(profiles).join(", ") || "(none)"}`);
+  }
+
+  // Merge: profile overrides base config, but unset keys are kept from base
+  // Strip the "profiles" map from the result so it doesn't leak into engine
+  const { profiles: _profiles, ...base } = config;
+  return { ...base, ...profile };
+}
+
+/**
+ * List available profile names from config.
+ * @returns {Promise<string[]>}
+ */
+export async function listProfiles() {
+  const config = await loadConfig();
+  return Object.keys(config.profiles ?? {});
+}
+
 /**
  * Returns true if no config exists or onboarded flag is not set.
  */

package/core/engine.mjs

@@ -15,6 +15,19 @@ import path from "node:path";
 import { readFile, writeFile, mkdir, appendFile } from "node:fs/promises";
 
 import { WISPY_DIR, CONVERSATIONS_DIR, MEMORY_DIR, MCP_CONFIG_PATH, detectProvider, PROVIDERS } from "./config.mjs";
+import { NullEmitter } from "../lib/jsonl-emitter.mjs";
+
+/**
+ * Personality presets that modify the system prompt.
+ * Set via config, profile, or --personality CLI flag.
+ */
+export const PERSONALITIES = {
+  pragmatic: "Be direct and action-oriented. Minimize explanation, maximize execution. Show code, not words.",
+  concise: "Keep responses extremely brief. One-liners when possible. No filler.",
+  explanatory: "Explain your reasoning step by step. Help the user understand, not just get an answer.",
+  friendly: "Be warm and encouraging. Use casual language. Celebrate small wins.",
+  strict: "Follow instructions precisely. No creative interpretation. Verify before acting.",
+};
 import { ProviderRegistry } from "./providers.mjs";
 import { ToolRegistry } from "./tools.mjs";
 import { SessionManager } from "./session.mjs";
@@ -58,6 +71,8 @@ export class WispyEngine {
       ?? process.env.WISPY_WORKSTREAM
       ?? process.argv.find((a, i) => (process.argv[i-1] === "-w" || process.argv[i-1] === "--workstream"))
       ?? "default";
+    // Personality: from config, or null (use default Wispy personality)
+    this._personality = config.personality ?? null;
   }
 
   get activeWorkstream() { return this._activeWorkstream; }
@@ -130,7 +145,7 @@ export class WispyEngine {
    *
    * @param {string|null} sessionId - Session ID (null = create new)
    * @param {string} userMessage - The user's message
-   * @param {object} opts - Options: { onChunk, systemPrompt, workstream, noSave }
+   * @param {object} opts - Options: { onChunk, systemPrompt, workstream, noSave, emitter, personality }
    * @returns {object} { role: "assistant", content: string, usage? }
    */
   async processMessage(sessionId, userMessage, opts = {}) {
@@ -161,10 +176,25 @@ export class WispyEngine {
       session = this.sessions.create({ workstream: opts.workstream ?? this._activeWorkstream });
     }
 
+    // JSONL emitter (no-op by default)
+    const emitter = opts.emitter ?? new NullEmitter();
+
+    // Emit start event
+    emitter.start({
+      model: this.providers.model ?? "unknown",
+      session_id: session.id,
+    });
+
+    // Emit user message event
+    emitter.message("user", userMessage);
+
+    // Resolve personality for this call
+    const personality = opts.personality ?? this._personality ?? null;
+
     // Build messages array for the provider
     let systemPrompt;
     try {
-      systemPrompt = opts.systemPrompt ?? await this._buildSystemPrompt(userMessage);
+      systemPrompt = opts.systemPrompt ?? await this._buildSystemPrompt(userMessage, { personality });
     } catch {
       systemPrompt = "You are Wispy 🌿 — a helpful AI assistant in the terminal.";
     }
@@ -195,11 +225,13 @@ export class WispyEngine {
     }).catch(() => {});
 
     // Run agentic loop with error handling
+    const _startMs = Date.now();
     let responseText;
     try {
-      responseText = await this._agentLoop(messages, session, opts);
+      responseText = await this._agentLoop(messages, session, { ...opts, emitter });
     } catch (err) {
       responseText = this._friendlyError(err);
+      emitter.error(err);
       this.audit.log({
         type: EVENT_TYPES.ERROR,
         sessionId: session.id,
@@ -207,6 +239,13 @@ export class WispyEngine {
       }).catch(() => {});
     }
 
+    // Emit assistant message + done events
+    emitter.message("assistant", responseText);
+    emitter.done({
+      tokens: { ...(this.providers.sessionTokens ?? {}) },
+      duration_ms: Date.now() - _startMs,
+    });
+
     // Audit: log outgoing response
     this.audit.log({
       type: EVENT_TYPES.MESSAGE_SENT,
@@ -308,9 +347,13 @@ export class WispyEngine {
       const toolCallMsg = { role: "assistant", toolCalls: result.calls, content: "" };
       messages.push(toolCallMsg);
 
+      const loopEmitter = opts.emitter ?? new NullEmitter();
+
       for (const call of result.calls) {
         if (opts.onToolCall) opts.onToolCall(call.name, call.args);
+        loopEmitter.toolCall(call.name, call.args);
 
+        const _toolStartMs = Date.now();
         let toolResult;
         try {
           // Enforce 60s timeout on individual tool calls
@@ -328,7 +371,9 @@ export class WispyEngine {
           }
         }
 
+        const _toolDuration = Date.now() - _toolStartMs;
         if (opts.onToolResult) opts.onToolResult(call.name, toolResult);
+        loopEmitter.toolResult(call.name, toolResult, _toolDuration);
 
         messages.push({
           role: "tool_result",
@@ -783,17 +828,32 @@ export class WispyEngine {
 
   // ── System prompt ────────────────────────────────────────────────────────────
 
-  async _buildSystemPrompt(lastUserMessage = "") {
+  async _buildSystemPrompt(lastUserMessage = "", opts = {}) {
+    const personality = opts.personality ?? this._personality ?? null;
+
     const parts = [
       "You are Wispy 🌿 — a small ghost that lives in terminals.",
       "You float between code, files, and servers. You're playful, honest, and curious.",
       "",
-      "## Personality",
-      "- Playful with a bit of humor, but serious when working",
-      "- Always use casual speech (반말). Never formal/polite speech.",
-      "- Honest — if you don't know, say so.",
-      "- Concise — don't over-explain.",
-      "",
+    ];
+
+    // Inject personality override if set
+    if (personality && PERSONALITIES[personality]) {
+      parts.push(`## Personality Override (${personality})`);
+      parts.push(PERSONALITIES[personality]);
+      parts.push("");
+    } else {
+      parts.push(
+        "## Personality",
+        "- Playful with a bit of humor, but serious when working",
+        "- Always use casual speech (반말). Never formal/polite speech.",
+        "- Honest — if you don't know, say so.",
+        "- Concise — don't over-explain.",
+        "",
+      );
+    }
+
+    parts.push(
       "## Speech rules",
       "- ALWAYS end your response with exactly one 🌿 emoji (signature)",
       "- Use 🌿 ONLY at the very end, not in the middle",
@@ -805,7 +865,7 @@ export class WispyEngine {
       `You have ${this.tools.getDefinitions().length} tools available: ${this.tools.getDefinitions().map(t => t.name).join(", ")}.`,
       "Use them proactively. Briefly mention what you're doing.",
       "",
-    ];
+    );
 
     // Load user model personalization
     try {

package/core/harness.mjs

@@ -13,12 +13,145 @@
  */
 
 import { EventEmitter } from "node:events";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 
 import { EVENT_TYPES } from "./audit.mjs";
 
+// ── Approval gate constants ────────────────────────────────────────────────────
+
+// Tools that require approval depending on security mode
+const DANGEROUS_TOOLS = new Set([
+  "run_command", "write_file", "file_edit", "delete_file",
+  "spawn_subagent", "browser_navigate",
+]);
+
+// Tools that ALWAYS require approval (even in yolo mode)
+const ALWAYS_APPROVE = new Set(["delete_file"]);
+
+// System-path prefixes — writing here requires approval even in balanced mode
+const SYSTEM_PATH_PREFIXES = ["/usr", "/etc", "/System", "/bin", "/sbin", "/Library/LaunchDaemons"];
+
+const APPROVALS_PATH = path.join(os.homedir(), ".wispy", "approvals.json");
+
+const DEFAULT_ALLOWLIST = {
+  run_command: ["npm test", "npm run build", "git status", "git diff", "ls"],
+  write_file: [],
+  file_edit: [],
+  delete_file: [],
+  spawn_subagent: [],
+  browser_navigate: [],
+};
+
+// ── Allowlist manager ─────────────────────────────────────────────────────────
+
+export class ApprovalAllowlist {
+  constructor() {
+    this._list = null; // lazy load
+  }
+
+  async _load() {
+    if (this._list !== null) return;
+    try {
+      const raw = await readFile(APPROVALS_PATH, "utf8");
+      this._list = JSON.parse(raw);
+    } catch {
+      this._list = { ...DEFAULT_ALLOWLIST };
+    }
+  }
+
+  async _save() {
+    await mkdir(path.dirname(APPROVALS_PATH), { recursive: true });
+    await writeFile(APPROVALS_PATH, JSON.stringify(this._list, null, 2) + "\n", "utf8");
+  }
+
+  async matches(toolName, args) {
+    await this._load();
+    const patterns = this._list[toolName] ?? [];
+    if (patterns.length === 0) return false;
+
+    // Get a string representation of args for matching
+    const argStr = _getArgString(toolName, args);
+    if (!argStr) return false;
+
+    return patterns.some(pattern => {
+      // Glob-style: "*" matches everything
+      if (pattern === "*") return true;
+      // Prefix match or exact match
+      if (pattern.endsWith("*")) return argStr.startsWith(pattern.slice(0, -1));
+      return argStr === pattern || argStr.startsWith(pattern);
+    });
+  }
+
+  async add(toolName, pattern) {
+    await this._load();
+    if (!this._list[toolName]) this._list[toolName] = [];
+    if (!this._list[toolName].includes(pattern)) {
+      this._list[toolName].push(pattern);
+      await this._save();
+    }
+  }
+
+  async clear() {
+    this._list = {};
+    await this._save();
+  }
+
+  async reset() {
+    this._list = { ...DEFAULT_ALLOWLIST };
+    await this._save();
+  }
+
+  async getAll() {
+    await this._load();
+    return { ...this._list };
+  }
+}
+
+// Singleton allowlist instance
+const globalAllowlist = new ApprovalAllowlist();
+
+function _getArgString(toolName, args) {
+  if (!args) return "";
+  if (toolName === "run_command") return args.command ?? "";
+  if (toolName === "write_file" || toolName === "file_edit") return args.path ?? "";
+  if (toolName === "delete_file") return args.path ?? "";
+  if (toolName === "browser_navigate") return args.url ?? "";
+  if (toolName === "spawn_subagent") return args.task ?? "";
+  return JSON.stringify(args);
+}
+
+/**
+ * Determine if a tool+args needs approval based on security mode.
+ * @param {string} toolName
+ * @param {object} args
+ * @param {string} mode - "careful" | "balanced" | "yolo"
+ * @returns {boolean}
+ */
+function _needsApproval(toolName, args, mode) {
+  if (ALWAYS_APPROVE.has(toolName)) return true;
+  if (!DANGEROUS_TOOLS.has(toolName)) return false;
+
+  if (mode === "careful") return true;
+
+  if (mode === "balanced") {
+    // Only destructive tools or writes to system paths
+    if (toolName === "delete_file") return true;
+    if (toolName === "write_file" || toolName === "file_edit") {
+      const filePath = args?.path ?? "";
+      const resolved = filePath.replace(/^~/, os.homedir());
+      return SYSTEM_PATH_PREFIXES.some(prefix => resolved.startsWith(prefix));
+    }
+    return false;
+  }
+
+  // yolo: only ALWAYS_APPROVE (handled above)
+  return false;
+}
+
+export { globalAllowlist };
+
 // ── Receipt ────────────────────────────────────────────────────────────────────
 
 export class Receipt {
@@ -349,6 +482,7 @@ export class Harness extends EventEmitter {
     this.permissions = permissions;
     this.audit = audit;
     this.config = config;
+    this.allowlist = globalAllowlist;
 
     // Sandbox config per-tool: "preview" | "diff" | null
     this._sandboxModes = {

package/core/index.mjs

@@ -9,7 +9,8 @@ export { SessionManager, Session, sessionManager } from "./session.mjs";
 export { ProviderRegistry } from "./providers.mjs";
 export { ToolRegistry } from "./tools.mjs";
 export { MCPClient, MCPManager, ensureDefaultMcpConfig } from "./mcp.mjs";
-export { loadConfig, saveConfig, detectProvider, isFirstRun, PROVIDERS, WISPY_DIR, CONFIG_PATH, MCP_CONFIG_PATH, SESSIONS_DIR, CONVERSATIONS_DIR, MEMORY_DIR } from "./config.mjs";
+export { loadConfig, saveConfig, loadConfigWithProfile, listProfiles, detectProvider, isFirstRun, PROVIDERS, WISPY_DIR, CONFIG_PATH, MCP_CONFIG_PATH, SESSIONS_DIR, CONVERSATIONS_DIR, MEMORY_DIR } from "./config.mjs";
+export { FeatureManager, getFeatureManager, FEATURE_REGISTRY } from "./features.mjs";
 export { OnboardingWizard, isFirstRun as checkFirstRun, printStatus } from "./onboarding.mjs";
 export { MemoryManager } from "./memory.mjs";
 export { CronManager } from "./cron.mjs";

package/core/providers.mjs

@@ -169,6 +169,16 @@ export class ProviderRegistry {
             functionCall: { name: tc.name, args: tc.args },
           })),
         });
+      } else if (m.images && m.images.length > 0) {
+        // Multimodal message with images (Google format)
+        const parts = m.images.map(img => ({
+          inlineData: { mimeType: img.mimeType, data: img.data },
+        }));
+        if (m.content) parts.push({ text: m.content });
+        contents.push({
+          role: m.role === "assistant" ? "model" : "user",
+          parts,
+        });
       } else {
         contents.push({
           role: m.role === "assistant" ? "model" : "user",

package/core/session.mjs

@@ -93,6 +93,109 @@ export class SessionManager {
     });
   }
 
+  /**
+   * List all sessions from disk with metadata (for CLI listing / picking).
+   * Returns sorted by updatedAt descending (most recent first).
+   *
+   * @param {object} options
+   * @param {string} [options.workstream] - Filter by workstream (default: current dir sessions only via all=false)
+   * @param {boolean} [options.all] - Include sessions from all workstreams
+   * @param {number} [options.limit] - Max sessions to return (default: 50)
+   * @returns {Array<{id, workstream, channel, chatId, createdAt, updatedAt, model, messageCount, firstMessage, cwd}>}
+   */
+  async listSessions(options = {}) {
+    const { workstream = null, all: showAll = false, limit = 50 } = options;
+    let files;
+    try {
+      files = await readdir(SESSIONS_DIR);
+    } catch {
+      return [];
+    }
+
+    const sessionFiles = files.filter(f => f.endsWith(".json"));
+    const results = [];
+
+    for (const file of sessionFiles) {
+      const id = file.replace(".json", "");
+      const filePath = path.join(SESSIONS_DIR, file);
+      try {
+        const [raw, fileStat] = await Promise.all([
+          readFile(filePath, "utf8"),
+          stat(filePath),
+        ]);
+        let data;
+        try { data = JSON.parse(raw); } catch { continue; }
+        if (!data || !data.id) continue;
+
+        // Apply workstream filter
+        if (!showAll && workstream && data.workstream !== workstream) continue;
+
+        const messages = Array.isArray(data.messages) ? data.messages : [];
+        const userMessages = messages.filter(m => m.role === "user");
+        const firstMessage = userMessages[0]?.content ?? messages[0]?.content ?? "";
+
+        results.push({
+          id: data.id,
+          workstream: data.workstream ?? "default",
+          channel: data.channel ?? null,
+          chatId: data.chatId ?? null,
+          createdAt: data.createdAt ?? fileStat.birthtime.toISOString(),
+          updatedAt: data.updatedAt ?? fileStat.mtime.toISOString(),
+          model: data.model ?? null,
+          messageCount: messages.length,
+          firstMessage: firstMessage.slice(0, 120),
+          cwd: data.cwd ?? null,
+        });
+      } catch {
+        continue;
+      }
+    }
+
+    // Sort by updatedAt descending
+    results.sort((a, b) => new Date(b.updatedAt) - new Date(a.updatedAt));
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Load a session by ID and return the full session (alias for load with better name).
+   * Returns null if not found.
+   */
+  async loadSession(id) {
+    return this.getOrLoad(id);
+  }
+
+  /**
+   * Fork a session: copy its message history into a new session.
+   * The new session starts from the same history but diverges from here.
+   *
+   * @param {string} id - Source session ID
+   * @param {object} opts - Additional options for the new session (workstream, etc.)
+   * @returns {Session} - The new forked session
+   */
+  async forkSession(id, opts = {}) {
+    // Load source session
+    const source = await this.getOrLoad(id);
+    if (!source) {
+      throw new Error(`Session not found: ${id}`);
+    }
+
+    // Create a new session with same metadata
+    const forked = this.create({
+      workstream: opts.workstream ?? source.workstream,
+      channel: opts.channel ?? null,
+      chatId: opts.chatId ?? null,
+    });
+
+    // Copy message history (deep copy)
+    forked.messages = source.messages.map(m => ({ ...m }));
+    forked.updatedAt = new Date().toISOString();
+
+    // Save the forked session
+    await this.save(forked.id);
+
+    return forked;
+  }
+
   /**
    * Add a message to a session.
    */

package/lib/commands/review.mjs

@@ -0,0 +1,272 @@
+/**
+ * lib/commands/review.mjs — Code review mode for Wispy
+ *
+ * wispy review                       Review uncommitted changes
+ * wispy review --base <branch>       Review against base branch
+ * wispy review --commit <sha>        Review specific commit
+ * wispy review --title <title>       Add context title
+ * wispy review --json                Output as JSON
+ */
+
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { WispyEngine } from "../../core/engine.mjs";
+
+const CODE_REVIEW_SYSTEM_PROMPT = `You are a senior code reviewer. Analyze the following diff and provide:
+1. A brief summary of the changes
+2. Issues found, categorized by severity (critical, warning, info)
+3. Specific line-level comments with suggestions
+4. An overall assessment (approve, request-changes, comment)
+
+Be constructive and specific. Reference line numbers when possible.
+
+Format your response as follows:
+## Summary
+[Brief summary of what changed]
+
+## Issues Found
+### Critical
+[List critical issues, or "None" if clean]
+
+### Warnings
+[List warnings, or "None"]
+
+### Info
+[List informational notes, or "None"]
+
+## File Comments
+[File-by-file comments with line references]
+
+## Assessment
+**Verdict:** [approve | request-changes | comment]
+[Brief overall assessment]`;
+
+/**
+ * Get git diff based on options.
+ */
+function getDiff(options = {}) {
+  const { base, commit, staged, cwd = process.cwd() } = options;
+  const execOpts = { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" };
+
+  let diff = "";
+
+  if (commit) {
+    // Review a specific commit
+    try {
+      diff = execSync(`git show ${commit}`, execOpts);
+    } catch (err) {
+      throw new Error(`Failed to get commit ${commit}: ${err.stderr?.slice(0, 200) ?? err.message}`);
+    }
+  } else if (base) {
+    // Review changes since base branch
+    try {
+      diff = execSync(`git diff ${base}...HEAD`, execOpts);
+    } catch (err) {
+      throw new Error(`Failed to diff against ${base}: ${err.stderr?.slice(0, 200) ?? err.message}`);
+    }
+  } else {
+    // Default: all uncommitted changes (staged + unstaged + untracked summary)
+    try {
+      const stageDiff = execSync("git diff --cached", execOpts);
+      const unstaged = execSync("git diff", execOpts);
+      diff = [stageDiff, unstaged].filter(Boolean).join("\n");
+
+      // Also include untracked file names if any
+      try {
+        const untracked = execSync("git ls-files --others --exclude-standard", execOpts).trim();
+        if (untracked) {
+          diff += `\n\n# Untracked files:\n${untracked.split("\n").map(f => `# + ${f}`).join("\n")}`;
+        }
+      } catch {}
+    } catch (err) {
+      throw new Error(`Failed to get git diff: ${err.stderr?.slice(0, 200) ?? err.message}`);
+    }
+  }
+
+  return diff.trim();
+}
+
+/**
+ * Get some context about the repo.
+ */
+function getRepoContext(cwd = process.cwd()) {
+  const execOpts = { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" };
+  const context = {};
+
+  try {
+    context.branch = execSync("git rev-parse --abbrev-ref HEAD", execOpts).trim();
+  } catch {}
+
+  try {
+    context.lastCommit = execSync("git log -1 --pretty=%B", execOpts).trim().slice(0, 200);
+  } catch {}
+
+  try {
+    const stat = execSync("git diff --stat", execOpts).trim();
+    context.stat = stat.slice(0, 500);
+  } catch {}
+
+  return context;
+}
+
+/**
+ * Parse the AI review response into structured JSON.
+ */
+function parseReviewResponse(text) {
+  const result = {
+    summary: "",
+    issues: { critical: [], warning: [], info: [] },
+    fileComments: [],
+    assessment: { verdict: "comment", explanation: "" },
+    raw: text,
+  };
+
+  // Extract summary
+  const summaryMatch = text.match(/## Summary\n([\s\S]*?)(?=##|$)/);
+  if (summaryMatch) result.summary = summaryMatch[1].trim();
+
+  // Extract issues
+  const criticalMatch = text.match(/### Critical\n([\s\S]*?)(?=###|##|$)/);
+  if (criticalMatch) {
+    const content = criticalMatch[1].trim();
+    if (content && content.toLowerCase() !== "none") {
+      result.issues.critical = content.split("\n").filter(l => l.trim() && l.trim() !== "-").map(l => l.replace(/^[-*•]\s*/, "").trim());
+    }
+  }
+
+  const warningsMatch = text.match(/### Warning[s]?\n([\s\S]*?)(?=###|##|$)/);
+  if (warningsMatch) {
+    const content = warningsMatch[1].trim();
+    if (content && content.toLowerCase() !== "none") {
+      result.issues.warning = content.split("\n").filter(l => l.trim() && l.trim() !== "-").map(l => l.replace(/^[-*•]\s*/, "").trim());
+    }
+  }
+
+  const infoMatch = text.match(/### Info\n([\s\S]*?)(?=###|##|$)/);
+  if (infoMatch) {
+    const content = infoMatch[1].trim();
+    if (content && content.toLowerCase() !== "none") {
+      result.issues.info = content.split("\n").filter(l => l.trim() && l.trim() !== "-").map(l => l.replace(/^[-*•]\s*/, "").trim());
+    }
+  }
+
+  // Extract assessment
+  const assessmentMatch = text.match(/## Assessment\n([\s\S]*?)(?=##|$)/);
+  if (assessmentMatch) {
+    const assessText = assessmentMatch[1].trim();
+    const verdictMatch = assessText.match(/\*\*Verdict:\*\*\s*(approve|request-changes|comment)/i);
+    if (verdictMatch) result.assessment.verdict = verdictMatch[1].toLowerCase();
+    result.assessment.explanation = assessText.replace(/\*\*Verdict:\*\*[^\n]*\n?/, "").trim();
+  }
+
+  return result;
+}
+
+/**
+ * Main review handler.
+ */
+export async function handleReviewCommand(args = []) {
+  // Parse args
+  const options = {
+    base: null,
+    commit: null,
+    title: null,
+    json: false,
+    cwd: process.cwd(),
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--base" && args[i + 1]) { options.base = args[++i]; }
+    else if (args[i] === "--commit" && args[i + 1]) { options.commit = args[++i]; }
+    else if (args[i] === "--title" && args[i + 1]) { options.title = args[++i]; }
+    else if (args[i] === "--json") { options.json = true; }
+  }
+
+  // Check git
+  try {
+    execSync("git rev-parse --is-inside-work-tree", {
+      cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    console.error("❌ Not inside a git repository.");
+    process.exit(1);
+  }
+
+  // Get the diff
+  let diff;
+  try {
+    diff = getDiff(options);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!diff) {
+    console.log("✅ Nothing to review — no changes found.");
+    process.exit(0);
+  }
+
+  const context = getRepoContext(options.cwd);
+
+  // Build review prompt
+  let prompt = "";
+  if (options.title) prompt += `# ${options.title}\n\n`;
+  if (context.branch) prompt += `**Branch:** \`${context.branch}\`\n`;
+  if (options.base) prompt += `**Review type:** Changes since \`${options.base}\`\n`;
+  if (options.commit) prompt += `**Commit:** \`${options.commit}\`\n`;
+  if (context.stat) prompt += `\n**Stats:**\n\`\`\`\n${context.stat}\n\`\`\`\n`;
+  prompt += `\n**Diff:**\n\`\`\`diff\n${diff.slice(0, 50_000)}\n\`\`\``;
+
+  if (diff.length > 50_000) {
+    prompt += `\n\n*(diff truncated — ${diff.length} chars total)*`;
+  }
+
+  // Show what we're reviewing
+  if (!options.json) {
+    if (options.commit) {
+      console.log(`\n🔍 Reviewing commit ${options.commit}...`);
+    } else if (options.base) {
+      console.log(`\n🔍 Reviewing changes since ${options.base}...`);
+    } else {
+      console.log("\n🔍 Reviewing uncommitted changes...");
+    }
+    if (context.stat) {
+      console.log(`\n${context.stat}\n`);
+    }
+    process.stdout.write("🌿 ");
+  }
+
+  // Send to AI
+  let reviewText = "";
+  try {
+    const engine = new WispyEngine();
+    const initResult = await engine.init({ skipMcp: true });
+    if (!initResult) {
+      console.error("❌ No AI provider configured. Set an API key to use code review.");
+      process.exit(1);
+    }
+
+    const response = await engine.processMessage(null, prompt, {
+      systemPrompt: CODE_REVIEW_SYSTEM_PROMPT,
+      onChunk: options.json ? null : (chunk) => process.stdout.write(chunk),
+      noSave: true,
+      skipSkillCapture: true,
+      skipUserModel: true,
+    });
+
+    reviewText = response.content;
+    try { engine.destroy(); } catch {}
+  } catch (err) {
+    console.error(`❌ Review failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!options.json) {
+    console.log("\n");
+    return;
+  }
+
+  // JSON output
+  const structured = parseReviewResponse(reviewText);
+  console.log(JSON.stringify(structured, null, 2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wispy-cli",
-  "version": "2.7.11",
+  "version": "2.7.12",
   "description": "🌿 Wispy — AI workspace assistant with trustworthy execution (harness, receipts, approvals, diffs)",
   "license": "MIT",
   "author": "Minseo & Poropo",