serpentstack 0.2.5 → 0.2.9

package/lib/commands/persistent.js

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import { execFile, spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-import { info, success, warn, error, confirm, bold, dim, green, cyan, yellow, red, printBox, printHeader } from '../utils/ui.js';
+import { info, success, warn, error, bold, dim, green, cyan, yellow, red, divider, printBox, printHeader } from '../utils/ui.js';
 import {
   parseAgentMd,
   discoverAgents,
@@ -22,6 +22,9 @@ import {
   getEffectiveModel,
   isAgentEnabled,
 } from '../utils/config.js';
+import { detectModels, modelShortName } from '../utils/models.js';
+
+// ─── Helpers ────────────────────────────────────────────────
 
 function which(cmd) {
   return new Promise((resolve) => {
@@ -29,74 +32,139 @@ function which(cmd) {
   });
 }
 
-function modelShortName(model) {
-  if (model.includes('haiku')) return 'Haiku';
-  if (model.includes('sonnet')) return 'Sonnet';
-  if (model.includes('opus')) return 'Opus';
-  if (model.includes('ollama') || model.includes(':')) return model.split('/').pop();
-  return model;
+async function ask(rl, label, defaultValue) {
+  const hint = defaultValue ? ` ${dim(`[${defaultValue}]`)}` : '';
+  const answer = await rl.question(`  ${green('?')} ${bold(label)}${hint}: `);
+  return answer.trim() || defaultValue || '';
 }
 
-async function askQuestion(rl, label, hint, defaultValue) {
-  const defaultHint = defaultValue ? ` ${dim(`[${defaultValue}]`)}` : '';
-  const hintStr = hint ? ` ${dim(hint)}` : '';
-  const answer = await rl.question(`  ${green('?')} ${bold(label)}${hintStr}${defaultHint}: `);
-  return answer.trim() || defaultValue || '';
+async function askYesNo(rl, label, defaultYes = true) {
+  const hint = defaultYes ? dim('[Y/n]') : dim('[y/N]');
+  const answer = await rl.question(`  ${green('?')} ${label} ${hint} `);
+  const val = answer.trim().toLowerCase();
+  if (defaultYes) return val !== 'n' && val !== 'no';
+  return val === 'y' || val === 'yes';
+}
+
+// ─── Model Picker ───────────────────────────────────────────
+
+async function pickModel(rl, agentName, currentModel, available) {
+  const choices = [];
+
+  // Local models first (free, fast, recommended)
+  if (available.local.length > 0) {
+    console.log(`    ${dim('── Local')} ${green('free')} ${dim('──────────────────────')}`);
+    for (const m of available.local) {
+      const isCurrent = m.id === currentModel;
+      const idx = choices.length;
+      choices.push(m);
+      const marker = isCurrent ? green('>') : ' ';
+      const num = dim(`${idx + 1}.`);
+      const label = isCurrent ? bold(m.name) : m.name;
+      const params = m.params ? dim(` ${m.params}`) : '';
+      const quant = m.quant ? dim(` ${m.quant}`) : '';
+      const size = m.size ? dim(` (${m.size})`) : '';
+      const tag = isCurrent ? green(' \u2190 current') : '';
+      console.log(`  ${marker} ${num} ${label}${params}${quant}${size}${tag}`);
+    }
+  }
+
+  // Cloud models (require API key, cost money)
+  if (available.cloud.length > 0) {
+    const apiNote = available.hasApiKey ? green('key ✓') : yellow('needs API key');
+    console.log(`    ${dim('── Cloud')} ${apiNote} ${dim('─────────────────────')}`);
+    for (const m of available.cloud) {
+      const isCurrent = m.id === currentModel;
+      const idx = choices.length;
+      choices.push(m);
+      const marker = isCurrent ? green('>') : ' ';
+      const num = dim(`${idx + 1}.`);
+      const label = isCurrent ? bold(m.name) : m.name;
+      const provider = m.provider ? dim(` (${m.provider})`) : '';
+      const tag = isCurrent ? green(' \u2190 current') : '';
+      console.log(`  ${marker} ${num} ${label}${provider}${tag}`);
+    }
+  }
+
+  // If current model isn't in either list, add it
+  if (!choices.some(c => c.id === currentModel)) {
+    choices.unshift({ id: currentModel, name: modelShortName(currentModel), tier: 'custom' });
+    // Re-render isn't needed since we'll just note it
+    console.log(`    ${dim(`Current: ${modelShortName(currentModel)} (not in detected models)`)}`);
+  }
+
+  const currentIdx = choices.findIndex(c => c.id === currentModel);
+  const defaultNum = currentIdx >= 0 ? currentIdx + 1 : 1;
+
+  const answer = await rl.question(`    ${dim(`Enter 1-${choices.length}`)} ${dim(`[${defaultNum}]`)}: `);
+  const idx = parseInt(answer.trim(), 10) - 1;
+
+  const selected = (idx >= 0 && idx < choices.length) ? choices[idx] : choices[Math.max(0, currentIdx)];
+
+  // Warn about cloud model costs
+  if (selected.tier === 'cloud' && available.local.length > 0) {
+    warn(`Cloud models cost tokens per heartbeat cycle. Consider a local model for persistent agents.`);
+  }
+  if (selected.tier === 'cloud' && !available.hasApiKey) {
+    warn(`No API key detected. Run ${bold('openclaw configure')} to set up authentication.`);
+  }
+
+  return selected.id;
 }
 
 // ─── Terminal Spawning ──────────────────────────────────────
 
-/**
- * Open a new terminal window/tab running the given command.
- * Returns the method used ('terminal', 'iterm', 'fallback').
- */
 function openInTerminal(title, command, cwd) {
   const platform = process.platform;
   const termProgram = process.env.TERM_PROGRAM || '';
+  const safeCwd = cwd.replace(/'/g, "'\\''").replace(/"/g, '\\"');
+  const safeCmd = command.replace(/"/g, '\\"');
 
   if (platform === 'darwin') {
     if (termProgram === 'iTerm.app') {
-      // iTerm2: open a new tab
-      const script = `
-        tell application "iTerm"
-          tell current window
-            create tab with default profile
-            tell current session
-              set name to "${title}"
-              write text "cd ${escapeShell(cwd)} && ${command}"
-            end tell
-          end tell
-        end tell
-      `;
+      const script = `tell application "iTerm"
+  tell current window
+    create tab with default profile
+    tell current session
+      set name to "${title}"
+      write text "cd '${safeCwd}' && ${safeCmd}"
+    end tell
+  end tell
+end tell`;
       spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
-      return 'iterm';
-    } else {
-      // Terminal.app: open a new tab
-      const script = `
-        tell application "Terminal"
-          activate
-          do script "cd ${escapeShell(cwd)} && ${command}"
-        end tell
-      `;
-      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
-      return 'terminal';
+      return 'iTerm';
     }
-  } else if (platform === 'linux') {
-    // Try common Linux terminal emulators
+    const script = `tell application "Terminal"
+  activate
+  do script "cd '${safeCwd}' && ${safeCmd}"
+end tell`;
+    spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+    return 'Terminal';
+  }
+
+  if (platform === 'linux') {
+    const shellCmd = `cd '${safeCwd}' && ${command}; exec bash`;
     const terminals = [
-      ['gnome-terminal', ['--title', title, '--', 'bash', '-c', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
-      ['xterm', ['-title', title, '-e', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
-      ['konsole', ['--new-tab', '-e', 'bash', '-c', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
+      ['gnome-terminal', ['--title', title, '--', 'bash', '-c', shellCmd]],
+      ['kitty', ['--title', title, 'bash', '-c', shellCmd]],
+      ['alacritty', ['--title', title, '-e', 'bash', '-c', shellCmd]],
+      ['wezterm', ['start', '--', 'bash', '-c', shellCmd]],
+      ['konsole', ['--new-tab', '-e', 'bash', '-c', shellCmd]],
+      ['xterm', ['-title', title, '-e', 'bash', '-c', shellCmd]],
     ];
-
     for (const [bin, args] of terminals) {
       try {
-        spawn(bin, args, { stdio: 'ignore', detached: true }).unref();
-        return bin;
+        const child = spawn(bin, args, { stdio: 'ignore', detached: true });
+        child.unref();
+        // Verify it didn't immediately fail
+        const alive = child.pid && !child.killed;
+        if (alive) return bin;
       } catch { continue; }
     }
-  } else if (platform === 'win32') {
-    spawn('cmd.exe', ['/c', 'start', 'cmd', '/k', `cd /d ${cwd} && ${command}`], {
+  }
+
+  if (platform === 'win32') {
+    spawn('cmd.exe', ['/c', 'start', `"${title}"`, 'cmd', '/k', `cd /d "${cwd}" && ${command}`], {
       stdio: 'ignore', detached: true,
     }).unref();
     return 'cmd';
@@ -105,10 +173,6 @@ function openInTerminal(title, command, cwd) {
   return null;
 }
 
-function escapeShell(str) {
-  return str.replace(/'/g, "'\\''");
-}
-
 // ─── Stop Flow ──────────────────────────────────────────────
 
 function stopAllAgents(projectDir) {
@@ -118,156 +182,33 @@ function stopAllAgents(projectDir) {
   if (running.length === 0) {
     info('No agents are currently running.');
     console.log();
-    return;
+    return 0;
   }
 
-  console.log(`  ${dim('Stopping')} ${bold(String(running.length))} ${dim('agent(s)...')}`);
-  console.log();
-
   let stopped = 0;
   for (const { name, pid } of running) {
     try {
       process.kill(pid, 'SIGTERM');
       removePid(projectDir, name);
       cleanWorkspace(projectDir, name);
-      success(`${bold(name)} stopped ${dim(`(PID ${pid})`)}`);
+      success(`Stopped ${bold(name)} ${dim(`(PID ${pid})`)}`);
       stopped++;
     } catch (err) {
       if (err.code === 'ESRCH') {
         removePid(projectDir, name);
-        success(`${bold(name)} already stopped`);
-        stopped++;
+        // Don't count already-dead processes as "stopped"
       } else {
         error(`Failed to stop ${bold(name)}: ${err.message}`);
       }
     }
   }
 
-  console.log();
-  success(`${green(String(stopped))} agent(s) stopped`);
-  console.log();
-}
-
-// ─── Configure Project ──────────────────────────────────────
-
-async function configureProject(projectDir, existingConfig) {
-  const rl = createInterface({ input: stdin, output: stdout });
-  const templateDefaults = detectTemplateDefaults(projectDir);
-  const existing = existingConfig?.project || {};
-
-  const defaults = {
-    name: existing.name || templateDefaults?.name || '',
-    language: existing.language || templateDefaults?.language || '',
-    framework: existing.framework || templateDefaults?.framework || '',
-    devCmd: existing.devCmd || templateDefaults?.devCmd || '',
-    testCmd: existing.testCmd || templateDefaults?.testCmd || '',
-    conventions: existing.conventions || templateDefaults?.conventions || '',
-  };
-
-  if (templateDefaults && !existing.name) {
-    console.log();
-    info('Detected SerpentStack template — defaults pre-filled');
-  }
-
-  console.log();
-  console.log(`  ${bold('Configure your project')}`);
-  console.log(`  ${dim('Press Enter to accept defaults shown in [brackets].')}`);
-  console.log();
-
-  try {
-    const project = {
-      name: await askQuestion(rl, 'Project name', '(e.g., Acme API)', defaults.name),
-      language: await askQuestion(rl, 'Primary language', '(e.g., Python, TypeScript)', defaults.language),
-      framework: await askQuestion(rl, 'Framework', '(e.g., FastAPI, Next.js)', defaults.framework),
-      devCmd: await askQuestion(rl, 'Dev server command', '(e.g., make dev)', defaults.devCmd),
-      testCmd: await askQuestion(rl, 'Test command', '(e.g., make test)', defaults.testCmd),
-      conventions: await askQuestion(rl, 'Key conventions', '(brief)', defaults.conventions),
-    };
-
-    console.log();
-
-    // Update SOUL.md with project context
-    const soulPath = join(projectDir, '.openclaw/SOUL.md');
-    if (existsSync(soulPath)) {
-      let soul = readFileSync(soulPath, 'utf8');
-
-      const projectContext = [
-        `# ${project.name} — Persistent Development Agents`,
-        '',
-        `**Project:** ${project.name}`,
-        `**Language:** ${project.language}`,
-        `**Framework:** ${project.framework}`,
-        `**Dev server:** \`${project.devCmd}\``,
-        `**Tests:** \`${project.testCmd}\``,
-        `**Conventions:** ${project.conventions}`,
-        '',
-        '---',
-        '',
-      ].join('\n');
-
-      const dashIndex = soul.indexOf('---');
-      if (dashIndex !== -1) {
-        soul = projectContext + soul.slice(dashIndex + 3).trimStart();
-      } else {
-        soul = projectContext + soul;
-      }
-
-      writeFileSync(soulPath, soul, 'utf8');
-      success(`Updated ${bold('.openclaw/SOUL.md')} with ${green(project.name)} project context`);
-    }
-
-    return project;
-  } finally {
-    rl.close();
-  }
-}
-
-// ─── Configure Single Agent ─────────────────────────────────
-
-async function configureAgent(rl, name, agentMd, existingAgent) {
-  const currentEnabled = existingAgent?.enabled !== false;
-  const currentModel = existingAgent?.model || agentMd.meta.model || 'anthropic/claude-haiku-4-20250414';
-
-  const enableStr = await askQuestion(rl, 'Enabled?', '(y/n)', currentEnabled ? 'y' : 'n');
-  const enabled = enableStr.toLowerCase() !== 'n';
-
-  let model = currentModel;
-  if (enabled) {
-    model = await askQuestion(rl, 'Model', '(e.g., anthropic/claude-haiku-4-20250414, ollama/llama3)', currentModel);
-  }
-
-  return { enabled, model };
-}
-
-// ─── Install OpenClaw ───────────────────────────────────────
-
-async function installOpenClaw() {
-  console.log();
-  warn('OpenClaw is not installed.');
-  console.log();
-  console.log(`  ${dim('OpenClaw is the persistent agent runtime. Each agent')}`);
-  console.log(`  ${dim('opens in its own terminal window.')}`);
-  console.log();
-
-  const install = await confirm('Install OpenClaw now? (npm install -g openclaw@latest)');
-  if (!install) {
-    console.log();
-    info('Install manually when ready:');
-    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
-    console.log(`  ${dim('$')} ${bold('serpentstack persistent')}`);
+  if (stopped > 0) {
     console.log();
-    return false;
+    success(`${stopped} agent(s) stopped`);
   }
-
-  console.log();
-  info('Installing OpenClaw...');
-  await new Promise((resolve, reject) => {
-    const child = spawn('npm', ['install', '-g', 'openclaw@latest'], { stdio: 'inherit' });
-    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`npm install exited with code ${code}`)));
-  });
   console.log();
-  success('OpenClaw installed');
-  return true;
+  return stopped;
 }
 
 // ─── Agent Status ───────────────────────────────────────────
@@ -279,17 +220,17 @@ function getAgentStatus(projectDir, name, config) {
   return { status: 'stopped', pid: null };
 }
 
-function printAgentStatus(name, agentMd, config, statusInfo) {
+function printAgentLine(name, agentMd, config, statusInfo) {
   const model = getEffectiveModel(name, agentMd.meta, config);
   const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
   const modelStr = modelShortName(model);
 
   if (statusInfo.status === 'running') {
-    console.log(`  ${green('\u25CF')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${green(`PID ${statusInfo.pid}`)}`);
+    console.log(`    ${green('●')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${green(`PID ${statusInfo.pid}`)}`);
   } else if (statusInfo.status === 'disabled') {
-    console.log(`  ${dim('\u25CB')} ${dim(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('disabled')}`);
+    console.log(`    ${dim('○')} ${dim(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('disabled')}`);
   } else {
-    console.log(`  ${yellow('\u25CB')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('stopped')}`);
+    console.log(`    ${yellow('○')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('ready')}`);
   }
 }
 
@@ -300,144 +241,254 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
 
   printHeader();
 
-  // --stop flag
+  // ── Stop ──
   if (stop) {
     stopAllAgents(projectDir);
     return;
   }
 
-  // Check workspace exists
+  // ── Preflight checks ──
   const soulPath = join(projectDir, '.openclaw/SOUL.md');
   if (!existsSync(soulPath)) {
     error('No .openclaw/ workspace found.');
-    console.log();
     console.log(`  Run ${bold('serpentstack skills')} first to download the workspace files.`);
     console.log();
     process.exit(1);
   }
 
-  // Discover agents
   const agents = discoverAgents(projectDir);
   if (agents.length === 0) {
     error('No agents found in .openclaw/agents/');
-    console.log();
     console.log(`  Run ${bold('serpentstack skills')} to download the default agents,`);
     console.log(`  or create your own at ${bold('.openclaw/agents/<name>/AGENT.md')}`);
     console.log();
     process.exit(1);
   }
 
+  // Check OpenClaw early — don't waste time configuring if it's missing
+  const hasOpenClaw = await which('openclaw');
+  if (!hasOpenClaw) {
+    warn('OpenClaw is not installed.');
+    console.log();
+    console.log(`  ${dim('OpenClaw is the persistent agent runtime.')}`);
+    console.log(`  ${dim('Install it first, then re-run this command:')}`);
+    console.log();
+    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
+    console.log(`  ${dim('$')} ${bold('serpentstack persistent')}`);
+    console.log();
+    process.exit(1);
+  }
+
   cleanStalePids(projectDir);
 
-  // Parse all AGENT.md files
+  // Parse agent definitions
   const parsed = [];
   for (const agent of agents) {
     try {
       const agentMd = parseAgentMd(agent.agentMdPath);
       parsed.push({ ...agent, agentMd });
     } catch (err) {
-      error(`${bold(agent.name)}: ${err.message}`);
+      warn(`Skipping ${bold(agent.name)}: ${err.message}`);
     }
   }
-
   if (parsed.length === 0) {
-    error('No valid agents found. Check your AGENT.md files.');
+    error('No valid AGENT.md files found.');
     console.log();
     process.exit(1);
   }
 
-  // Load or create config
+  // Load config
   let config = readConfig(projectDir) || { project: {}, agents: {} };
   const needsSetup = !config.project?.name || reconfigure;
 
-  if (needsSetup) {
-    // First time or --reconfigure: full setup
-    console.log(`  ${bold('Project Setup')}`);
+  // Detect models in background while we show status
+  const modelsPromise = detectModels();
 
-    config.project = await configureProject(projectDir, config);
+  // ── If configured, show status dashboard ──
+  if (!needsSetup) {
+    console.log(`  ${bold(config.project.name)} ${dim(`— ${config.project.framework}`)}`);
+    console.log(`  ${dim(`Dev: ${config.project.devCmd} · Test: ${config.project.testCmd}`)}`);
     console.log();
 
-    // Configure agents
-    console.log(`  ${bold('Agent Configuration')}`);
+    for (const { name, agentMd } of parsed) {
+      const statusInfo = getAgentStatus(projectDir, name, config);
+      printAgentLine(name, agentMd, config, statusInfo);
+    }
     console.log();
 
-    const rl = createInterface({ input: stdin, output: stdout });
-    try {
-      for (const { name, agentMd } of parsed) {
-        const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
-        console.log(`  ${bold(name)}  ${dim(agentMd.meta.description || '')}`);
-        console.log(`    ${dim(`Schedule: ${schedule || 'none'}`)}`);
+    // Determine what to do
+    const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
+    const runningNames = new Set(listPids(projectDir).map(p => p.name));
+    const startable = enabledAgents.filter(a => !runningNames.has(a.name));
 
-        const agentConfig = await configureAgent(rl, name, agentMd, config.agents?.[name]);
-        config.agents[name] = agentConfig;
+    if (startable.length === 0 && runningNames.size > 0) {
+      info('All enabled agents are running.');
+      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --stop')} ${dim('to stop them.')}`);
+      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --reconfigure')} ${dim('to change settings.')}`);
+      console.log();
+      return;
+    }
 
-        const status = agentConfig.enabled ? green('enabled') : dim('disabled');
-        console.log(`    ${dim('\u2192')} ${status}${agentConfig.enabled ? `, ${dim(modelShortName(agentConfig.model))}` : ''}`);
-        console.log();
-      }
-    } finally {
-      rl.close();
+    if (startable.length === 0) {
+      info('No agents are enabled.');
+      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --reconfigure')} ${dim('to enable agents.')}`);
+      console.log();
+      return;
     }
 
-    writeConfig(projectDir, config);
-    success(`Saved ${bold('.openclaw/config.json')}`);
+    // Start startable agents
+    await launchAgents(projectDir, startable, config, soulPath);
+    return;
+  }
+
+  // ── First-time setup / reconfigure ──
+  if (reconfigure) {
+    info('Reconfiguring...');
     console.log();
   }
 
-  // Show current status
-  console.log(`  ${bold('Agents')}`);
-  console.log();
+  const rl = createInterface({ input: stdin, output: stdout });
+  let configDirty = false;
 
-  for (const { name, agentMd } of parsed) {
-    const statusInfo = getAgentStatus(projectDir, name, config);
-    printAgentStatus(name, agentMd, config, statusInfo);
-  }
-  console.log();
+  try {
+    // ── Project configuration ──
+    const templateDefaults = detectTemplateDefaults(projectDir);
+    const existing = config.project || {};
+    const defaults = {
+      name: existing.name || templateDefaults?.name || '',
+      language: existing.language || templateDefaults?.language || '',
+      framework: existing.framework || templateDefaults?.framework || '',
+      devCmd: existing.devCmd || templateDefaults?.devCmd || '',
+      testCmd: existing.testCmd || templateDefaults?.testCmd || '',
+      conventions: existing.conventions || templateDefaults?.conventions || '',
+    };
 
-  // Determine which agents can be started
-  const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
-  const runningNames = new Set(listPids(projectDir).map(p => p.name));
-  const startableAgents = enabledAgents.filter(a => !runningNames.has(a.name));
-  const runningAgents = enabledAgents.filter(a => runningNames.has(a.name));
+    if (templateDefaults && !existing.name) {
+      info('Detected SerpentStack template — defaults pre-filled');
+      console.log();
+    }
 
-  if (startableAgents.length === 0 && runningAgents.length > 0) {
-    info('All enabled agents are already running.');
+    divider('Project');
+    console.log(`  ${dim('Press Enter to keep defaults.')}`);
     console.log();
 
-    const doStop = await confirm('Stop all agents?');
-    if (doStop) {
+    config.project = {
+      name: await ask(rl, 'Project name', defaults.name),
+      language: await ask(rl, 'Primary language', defaults.language),
+      framework: await ask(rl, 'Framework', defaults.framework),
+      devCmd: await ask(rl, 'Dev server command', defaults.devCmd),
+      testCmd: await ask(rl, 'Test command', defaults.testCmd),
+      conventions: await ask(rl, 'Key conventions', defaults.conventions),
+    };
+    configDirty = true;
+
+    // Update SOUL.md
+    if (existsSync(soulPath)) {
+      let soul = readFileSync(soulPath, 'utf8');
+      const ctx = [
+        `# ${config.project.name} \u2014 Persistent Development Agents`,
+        '',
+        `**Project:** ${config.project.name}`,
+        `**Language:** ${config.project.language}`,
+        `**Framework:** ${config.project.framework}`,
+        `**Dev server:** \`${config.project.devCmd}\``,
+        `**Tests:** \`${config.project.testCmd}\``,
+        `**Conventions:** ${config.project.conventions}`,
+        '', '---', '',
+      ].join('\n');
+      const dashIdx = soul.indexOf('---');
+      soul = dashIdx !== -1 ? ctx + soul.slice(dashIdx + 3).trimStart() : ctx + soul;
+      writeFileSync(soulPath, soul, 'utf8');
+    }
+    console.log();
+    success(`Updated ${bold('.openclaw/SOUL.md')}`);
+    console.log();
+
+    // ── Agent configuration ──
+    const available = await modelsPromise;
+
+    if (available.local.length > 0) {
+      info(`${available.local.length} local model(s) detected via Ollama`);
+    } else {
+      warn('No local models found. Install Ollama and pull a model for free persistent agents:');
+      console.log(`  ${dim('$')} ${bold('ollama pull llama3.2')}`);
+    }
+    if (available.hasApiKey) {
+      info('API key configured for cloud models');
+    }
+    console.log();
+
+    divider('Agents');
+    console.log(`  ${dim('Enable/disable each agent and pick a model.')}`);
+    console.log();
+
+    for (const { name, agentMd } of parsed) {
+      const existingAgent = config.agents?.[name];
+      const currentEnabled = existingAgent?.enabled !== false;
+      const currentModel = existingAgent?.model || 'ollama/llama3.2';
+      const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
+
+      console.log(`  ${bold(name)}  ${dim(agentMd.meta.description || '')}`);
+      console.log(`    ${dim(`Schedule: ${schedule || 'none'}`)}`);
+
+      const enabled = await askYesNo(rl, `Enable ${bold(name)}?`, currentEnabled);
+
+      let model = currentModel;
+      if (enabled) {
+        console.log();
+        model = await pickModel(rl, name, currentModel, available);
+      }
+
+      config.agents[name] = { enabled, model };
+
+      const status = enabled ? green('\u2713 enabled') : dim('\u2717 disabled');
+      const modelLabel = enabled ? `, ${modelShortName(model)}` : '';
+      console.log(`    ${status}${modelLabel}`);
+      console.log();
+    }
+
+    configDirty = true;
+  } finally {
+    rl.close();
+    // Only save if we completed configuration
+    if (configDirty) {
+      writeConfig(projectDir, config);
+      success(`Saved ${bold('.openclaw/config.json')}`);
       console.log();
-      stopAllAgents(projectDir);
     }
-    return;
   }
 
-  if (startableAgents.length === 0) {
-    info('No agents are enabled. Run with --reconfigure to enable agents.');
+  // Show status and launch
+  for (const { name, agentMd } of parsed) {
+    const statusInfo = getAgentStatus(projectDir, name, config);
+    printAgentLine(name, agentMd, config, statusInfo);
+  }
+  console.log();
+
+  const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
+  if (enabledAgents.length === 0) {
+    info('No agents enabled. Run with --reconfigure to enable agents.');
     console.log();
     return;
   }
 
-  // Let user pick which agents to start
+  await launchAgents(projectDir, enabledAgents, config, soulPath);
+}
+
+// ─── Launch Flow ────────────────────────────────────────────
+
+async function launchAgents(projectDir, agentsToStart, config, soulPath) {
   const rl = createInterface({ input: stdin, output: stdout });
   const toStart = [];
 
   try {
-    if (startableAgents.length === 1) {
-      const a = startableAgents[0];
-      const start = await confirm(`Start ${bold(a.name)}?`);
-      if (start) toStart.push(a);
-    } else {
-      console.log(`  ${dim('Which agents would you like to start?')}`);
-      console.log();
+    divider('Launch');
+    console.log();
 
-      for (const agent of startableAgents) {
-        const model = getEffectiveModel(agent.name, agent.agentMd.meta, config);
-        const answer = await rl.question(`  ${green('?')} Start ${bold(agent.name)} ${dim(`(${modelShortName(model)})`)}? ${dim('[Y/n]')} `);
-        if (answer.trim().toLowerCase() !== 'n') {
-          toStart.push(agent);
-        }
-      }
+    for (const agent of agentsToStart) {
+      const model = getEffectiveModel(agent.name, agent.agentMd.meta, config);
+      const yes = await askYesNo(rl, `Start ${bold(agent.name)} ${dim(`(${modelShortName(model)})`)}?`, true);
+      if (yes) toStart.push(agent);
     }
   } finally {
     rl.close();
@@ -450,16 +501,8 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
     return;
   }
 
-  // Check OpenClaw
-  const hasOpenClaw = await which('openclaw');
-  if (!hasOpenClaw) {
-    const installed = await installOpenClaw();
-    if (!installed) return;
-  }
-
   console.log();
 
-  // Start each agent in its own terminal window
   const sharedSoul = readFileSync(soulPath, 'utf8');
   let started = 0;
 
@@ -475,24 +518,19 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
       const absWorkspace = resolve(workspacePath);
       const absProject = resolve(projectDir);
 
-      // Build the openclaw command
-      const openclawCmd = `OPENCLAW_STATE_DIR="${join(absWorkspace, '.state')}" openclaw start --workspace "${absWorkspace}"`;
+      const openclawCmd = `OPENCLAW_STATE_DIR='${join(absWorkspace, '.state')}' openclaw start --workspace '${absWorkspace}'`;
 
-      // Try to open in a new terminal window
-      const method = openInTerminal(
-        `SerpentStack: ${name}`,
-        openclawCmd,
-        absProject,
-      );
+      const method = openInTerminal(`SerpentStack: ${name}`, openclawCmd, absProject);
 
       if (method) {
-        // Record PID tracking (we won't have the exact PID from the terminal,
-        // but we record a placeholder so --stop can find/kill it)
-        success(`${bold(name)} opened in new ${method} window ${dim(`(${modelShortName(effectiveModel)})`)}`);
+        // For terminal-spawned agents, record workspace path so we can track it
+        // The terminal process will create its own PID — we record ours as a marker
+        writePid(projectDir, name, -1); // -1 = terminal-managed
+        success(`${bold(name)} opened in ${method} ${dim(`(${modelShortName(effectiveModel)})`)}`);
         started++;
       } else {
-        // Fallback: start in background if no terminal method works
-        warn(`Could not open terminal for ${bold(name)} — starting in background`);
+        // Fallback: background process
+        warn(`No terminal detected \u2014 starting ${bold(name)} in background`);
         const child = spawn('openclaw', ['start', '--workspace', absWorkspace], {
           stdio: 'ignore',
           detached: true,
@@ -501,7 +539,7 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
         });
         child.unref();
         writePid(projectDir, name, child.pid);
-        success(`${bold(name)} started in background ${dim(`PID ${child.pid}`)}`);
+        success(`${bold(name)} started ${dim(`PID ${child.pid}`)}`);
         started++;
       }
     } catch (err) {
@@ -511,18 +549,12 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
 
   console.log();
   if (started > 0) {
-    success(`${green(String(started))} agent(s) launched`);
+    success(`${started} agent(s) launched — fangs out 🐍`);
     console.log();
     printBox('Manage agents', [
-      `${dim('$')} ${bold('serpentstack persistent')}                ${dim('# view status + start agents')}`,
-      `${dim('$')} ${bold('serpentstack persistent --stop')}         ${dim('# stop all agents')}`,
-      `${dim('$')} ${bold('serpentstack persistent --reconfigure')}  ${dim('# change models, enable/disable')}`,
-      '',
-      `${dim('Each agent runs in its own terminal window.')}`,
-      `${dim('Close a window to stop that agent.')}`,
+      `${dim('$')} ${bold('serpentstack persistent')}                ${dim('# status + start')}`,
+      `${dim('$')} ${bold('serpentstack persistent --stop')}         ${dim('# stop all')}`,
+      `${dim('$')} ${bold('serpentstack persistent --reconfigure')}  ${dim('# change models')}`,
     ]);
-  } else {
-    error('No agents were started. Check the errors above.');
-    console.log();
   }
 }