phewsh 0.9.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # phewsh
 
-Turn intent into action.
+Turn intent into action. Structure your thinking, execute your next step.
 
 ## Install
 
@@ -8,24 +8,64 @@ Turn intent into action.
 npm install -g phewsh
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-phewsh intent --init      # Create .intent/ in any project
-phewsh intent --status    # Check artifact state and next actions
-phewsh intent --open      # Open the web compass
-phewsh intent --evolve    # Update artifacts as the project grows
+phewsh              # enter the interactive shell
+```
+
+Inside the shell:
+
+```
+/init       Create .intent/ artifacts
+/clarify    AI-assisted artifact generation
+/push       Sync local to cloud
+/pull       Sync cloud to local
+/context    View loaded artifacts
+/sync       Check sync status
+/help       All commands
 ```
 
 ## What it does
 
-`phewsh intent --init` asks what you're building and what success looks like, then creates three structured artifacts in `.intent/`:
+Creates three structured artifacts in `.intent/`:
 
 - **vision.md** — The north star. Why this exists and where it's going.
 - **plan.md** — The strategy. Phases, systems, sequence, constraints.
-- **next.md** — Right now. Executable checklist with copy-paste commands.
+- **next.md** — Right now. Executable checklist with next actions.
+
+These artifacts become persistent context for AI conversations, both in the shell and across tools.
+
+## Sync
+
+CLI and web (phewsh.com/intent) share the same cloud via Supabase.
+
+```bash
+phewsh login        # authenticate
+phewsh push         # upload .intent/ to cloud
+phewsh pull         # download from cloud
+```
+
+Sync is manual. The CLI shows status on startup:
+
+```
+↓ Cloud is newer (2h ago) — run /pull
+↑ Local changes not pushed (15m ago) — run /push
+↕ synced
+```
 
-Drop `.intent/` in any project and your AI tools gain full context instantly.
+The `/intent` Claude Code skill writes local files only — run `phewsh push` after using it.
+
+## Non-interactive mode
+
+```bash
+phewsh intent --init      # Create .intent/ without entering the shell
+phewsh intent --status    # Check artifact state
+phewsh clarify            # AI-assisted artifact generation
+phewsh ai run "prompt"    # One-shot AI with .intent/ context
+phewsh push               # Sync to cloud
+phewsh pull               # Sync from cloud
+```
 
 ## Web app
 

package/bin/phewsh.js

@@ -46,8 +46,10 @@ const COMMANDS = {
   login:   () => require('../commands/login'),
   ai:      () => require('../commands/ai'),
   style:   () => require('../commands/style'),
-  music:   () => require('../commands/music'),
+  mbhd:    () => require('../commands/mbhd'),
   sap:     () => require('../commands/sap'),
+  mcp:     () => require('../commands/mcp')(),
+  serve:   () => require('../commands/serve')(),
   help:    showHelp,
   version: showVersion,
 };
@@ -72,9 +74,11 @@ function showHelp() {
   console.log(`    ${w('intent')}    Manage .intent/ artifacts — status, open, evolve`);
   console.log(`    ${w('ai')}        One-shot AI prompt (reads .intent/)`);
   console.log(`    ${w('login')}     Set up identity, API key, and cloud sync`);
+  console.log(`    ${w('serve')}     Start live execution bridge for the web app`);
+  console.log(`    ${w('mcp')}       Connect AI agents — setup, sync, status`);
   console.log(`    ${w('sap')}       Sustainable AI Protocol — usage and accountability`);
   console.log(`    ${w('style')}     Build your style identity — ingest, profile, sync`);
-  console.log(`    ${w('music')}     MBHD music engine`);
+  console.log(`    ${w('mbhd')}      MBHD music engine`);
   console.log('');
   console.log(`  ${b('Quick start')}`);
   console.log(`    ${g('phewsh login')}                          Set up identity + API key`);

package/commands/{music.js → mbhd.js}

@@ -1,6 +1,6 @@
 const { execSync } = require('child_process');
 
-const WEB_URL = 'https://phewsh.com/music';
+const WEB_URL = 'https://phewsh.com/mbhd';
 
 console.log(`\n  🎵 Opening MBHD Music Engine...\n`);
 

package/commands/mcp.js

@@ -0,0 +1,368 @@
+// phewsh mcp — Set up and sync the PHEWSH MCP server for agent connectivity
+//
+// Usage:
+//   phewsh mcp setup    — Install MCP server deps + configure Claude Code
+//   phewsh mcp sync     — Sync local .intent/ + cloud projects → ~/.phewsh/projects.json
+//   phewsh mcp status   — Check what agents can see right now
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
+const PROJECTS_FILE = path.join(PHEWSH_DIR, 'projects.json');
+const RESULTS_DIR = path.join(PHEWSH_DIR, 'results');
+const SESSIONS_DIR = path.join(PHEWSH_DIR, 'sessions');
+const INTENT_DIR = path.join(process.cwd(), '.intent');
+
+// ANSI helpers
+const b = (s) => `\x1b[1m${s}\x1b[0m`;
+const d = (s) => `\x1b[2m${s}\x1b[0m`;
+const g = (s) => `\x1b[90m${s}\x1b[0m`;
+const w = (s) => `\x1b[97m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+function ensureDirs() {
+  [PHEWSH_DIR, RESULTS_DIR, SESSIONS_DIR].forEach(dir => {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  });
+}
+
+function loadLocalProject() {
+  if (!fs.existsSync(INTENT_DIR)) return null;
+
+  const project = {
+    id: 'local',
+    name: path.basename(process.cwd()),
+    source: 'local',
+    artifacts: {},
+    actions: [],
+    decisionGate: null,
+  };
+
+  const files = ['vision.md', 'plan.md', 'next.md', 'status.md', 'narrative.md'];
+  for (const file of files) {
+    const filePath = path.join(INTENT_DIR, file);
+    if (fs.existsSync(filePath)) {
+      const kind = file.replace('.md', '');
+      project.artifacts[kind] = {
+        kind,
+        content: fs.readFileSync(filePath, 'utf-8'),
+      };
+      if (kind === 'vision') {
+        const firstLine = project.artifacts[kind].content.split('\n').find(l => l.trim().length > 5);
+        if (firstLine) project.name = firstLine.replace(/^#+\s*/, '').trim().slice(0, 60);
+      }
+    }
+  }
+
+  // Read project.json for gate, actions, constraints
+  const metaPath = path.join(INTENT_DIR, 'project.json');
+  if (fs.existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      Object.assign(project, meta);
+    } catch { /* ignore */ }
+  }
+
+  return Object.keys(project.artifacts).length > 0 ? project : null;
+}
+
+async function loadCloudProjects() {
+  const configPath = path.join(PHEWSH_DIR, 'config.json');
+  if (!fs.existsSync(configPath)) return [];
+
+  let config;
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch { return []; }
+  if (!config?.supabaseAccessToken || !config?.supabaseUserId) return [];
+
+  try {
+    const { select, refreshSession } = require('../lib/supabase');
+
+    // Refresh token if needed
+    if (config.supabaseRefreshToken) {
+      const session = await refreshSession(config.supabaseRefreshToken);
+      if (session?.access_token) {
+        config.supabaseAccessToken = session.access_token;
+        config.supabaseRefreshToken = session.refresh_token;
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+      }
+    }
+
+    const projects = await select(
+      'projects',
+      `user_id=eq.${config.supabaseUserId}&select=id,name,archetype,freeform_text,pps_json`,
+      config.supabaseAccessToken
+    );
+
+    // Also fetch artifacts for each project
+    const enriched = [];
+    for (const p of projects) {
+      const artifacts = await select(
+        'artifacts',
+        `project_id=eq.${p.id}&user_id=eq.${config.supabaseUserId}&select=kind,content`,
+        config.supabaseAccessToken
+      ).catch(() => []);
+
+      const artifactsMap = {};
+      for (const a of artifacts) {
+        artifactsMap[a.kind] = { kind: a.kind, content: a.content };
+      }
+
+      enriched.push({
+        id: p.id,
+        name: p.name,
+        source: 'cloud',
+        archetype: p.archetype,
+        tldr: p.freeform_text?.slice(0, 200),
+        artifacts: artifactsMap,
+        actions: p.pps_json?.actions || [],
+        decisionGate: p.pps_json?.decisionGate || null,
+      });
+    }
+    return enriched;
+  } catch (err) {
+    console.log(g(`  Could not fetch cloud projects: ${err.message}`));
+    return [];
+  }
+}
+
+function findMcpServerPath() {
+  // Check common locations
+  const candidates = [
+    path.join(__dirname, '..', '..', 'mcp', 'src', 'index.js'),  // monorepo sibling
+    path.join(process.cwd(), 'mcp', 'src', 'index.js'),           // cwd
+  ];
+
+  // Also check if @phewsh/mcp-server is globally installed
+  try {
+    const globalPath = execSync('npm root -g', { encoding: 'utf-8' }).trim();
+    candidates.push(path.join(globalPath, '@phewsh', 'mcp-server', 'src', 'index.js'));
+  } catch { /* not installed globally */ }
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return path.resolve(p);
+  }
+  return null;
+}
+
+async function setup() {
+  console.log('');
+  console.log(`  ${b(w('PHEWSH MCP Setup'))}`);
+  console.log(`  ${g('Connect your AI agents to your project intelligence')}`);
+  console.log('');
+
+  ensureDirs();
+
+  // 1. Find or install MCP server
+  let serverPath = findMcpServerPath();
+
+  if (!serverPath) {
+    console.log(`  ${yellow('MCP server not found locally.')}`);
+    console.log(`  ${g('Install it:')}`);
+    console.log(`    npm install -g @phewsh/mcp-server`);
+    console.log('');
+    console.log(`  ${g('Or if you have the phewsh repo:')}`);
+    console.log(`    cd mcp && npm install`);
+    console.log('');
+    return;
+  }
+
+  console.log(`  ${green('Found MCP server:')} ${g(serverPath)}`);
+
+  // 2. Check if deps are installed
+  const mcpDir = path.dirname(path.dirname(serverPath));
+  const nodeModules = path.join(mcpDir, 'node_modules');
+  if (!fs.existsSync(nodeModules)) {
+    console.log(`  ${yellow('Installing dependencies...')}`);
+    try {
+      execSync('npm install', { cwd: mcpDir, stdio: 'pipe' });
+      console.log(`  ${green('Dependencies installed.')}`);
+    } catch (err) {
+      console.log(`  ${yellow('Failed to install deps.')} Run manually: cd ${mcpDir} && npm install`);
+    }
+  }
+
+  // 3. Generate settings.json snippet
+  const claudeSettingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const snippet = {
+    mcpServers: {
+      phewsh: {
+        command: 'node',
+        args: [serverPath],
+      },
+    },
+  };
+
+  console.log('');
+  console.log(`  ${b('Add this to')} ${w(claudeSettingsPath)}${b(':')}`);
+  console.log('');
+  console.log(g('  ' + JSON.stringify(snippet, null, 2).split('\n').join('\n  ')));
+  console.log('');
+
+  // Check if already configured
+  if (fs.existsSync(claudeSettingsPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf-8'));
+      if (existing.mcpServers?.phewsh) {
+        console.log(`  ${green('Already configured in Claude Code settings.')}`);
+      } else {
+        console.log(`  ${yellow('Not yet configured.')} Add the snippet above to your settings.`);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // 4. Sync projects
+  console.log('');
+  console.log(`  ${g('Running initial sync...')}`);
+  await sync();
+}
+
+async function sync() {
+  ensureDirs();
+
+  const projects = [];
+  let localCount = 0;
+  let cloudCount = 0;
+
+  // Load local project
+  const local = loadLocalProject();
+  if (local) {
+    projects.push(local);
+    localCount = 1;
+  }
+
+  // Load cloud projects
+  const cloud = await loadCloudProjects();
+  // Deduplicate — if local project matches a cloud one by name, prefer local
+  for (const cp of cloud) {
+    if (!projects.find(p => p.name === cp.name)) {
+      projects.push(cp);
+      cloudCount++;
+    }
+  }
+
+  // Write projects.json
+  fs.writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2));
+
+  console.log('');
+  console.log(`  ${green('Synced')} ${b(projects.length + '')} project${projects.length !== 1 ? 's' : ''} → ${g(PROJECTS_FILE)}`);
+  if (localCount > 0) console.log(`    ${localCount} from local .intent/`);
+  if (cloudCount > 0) console.log(`    ${cloudCount} from cloud`);
+  projects.forEach(p => {
+    const actions = p.actions || [];
+    const pending = actions.filter(a => a.state === 'intended').length;
+    const progress = actions.length > 0
+      ? ` (${actions.filter(a => a.state === 'reconciled').length}/${actions.length} tasks)`
+      : '';
+    console.log(`    ${g('•')} ${p.name}${progress}${pending > 0 ? ` — ${pending} pending` : ''}`);
+  });
+  console.log('');
+}
+
+async function status() {
+  ensureDirs();
+
+  console.log('');
+  console.log(`  ${b(w('PHEWSH MCP Status'))}`);
+  console.log('');
+
+  // Check projects.json
+  if (fs.existsSync(PROJECTS_FILE)) {
+    try {
+      const projects = JSON.parse(fs.readFileSync(PROJECTS_FILE, 'utf-8'));
+      console.log(`  ${green('projects.json:')} ${projects.length} project${projects.length !== 1 ? 's' : ''}`);
+      projects.forEach(p => {
+        const actions = p.actions || [];
+        const pending = actions.filter(a => a.state === 'intended').length;
+        console.log(`    ${g('•')} ${p.name} [${p.source || 'unknown'}]${pending > 0 ? ` — ${yellow(pending + ' pending')}` : ''}`);
+      });
+    } catch {
+      console.log(`  ${yellow('projects.json:')} exists but unreadable`);
+    }
+  } else {
+    console.log(`  ${yellow('projects.json:')} not found. Run ${w('phewsh mcp sync')} first.`);
+  }
+
+  // Check results
+  if (fs.existsSync(RESULTS_DIR)) {
+    const resultFiles = fs.readdirSync(RESULTS_DIR).filter(f => f.endsWith('.json'));
+    const blockers = resultFiles.filter(f => f.startsWith('blocker_'));
+    const completions = resultFiles.filter(f => !f.startsWith('blocker_'));
+    if (resultFiles.length > 0) {
+      console.log(`  ${green('results:')} ${completions.length} completion${completions.length !== 1 ? 's' : ''}, ${blockers.length} blocker${blockers.length !== 1 ? 's' : ''}`);
+    } else {
+      console.log(`  ${g('results:')} none yet`);
+    }
+  }
+
+  // Check sessions
+  if (fs.existsSync(SESSIONS_DIR)) {
+    const sessionFiles = fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.json'));
+    if (sessionFiles.length > 0) {
+      let totalEvents = 0;
+      for (const f of sessionFiles) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, f), 'utf-8'));
+          totalEvents += data.length;
+        } catch { /* skip */ }
+      }
+      console.log(`  ${green('sessions:')} ${totalEvents} events across ${sessionFiles.length} project${sessionFiles.length !== 1 ? 's' : ''}`);
+    } else {
+      console.log(`  ${g('sessions:')} none yet`);
+    }
+  }
+
+  // Check MCP server
+  const serverPath = findMcpServerPath();
+  if (serverPath) {
+    console.log(`  ${green('server:')} ${g(serverPath)}`);
+  } else {
+    console.log(`  ${yellow('server:')} not found. Run ${w('phewsh mcp setup')}`);
+  }
+
+  // Check Claude Code config
+  const claudeSettingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  if (fs.existsSync(claudeSettingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf-8'));
+      if (settings.mcpServers?.phewsh) {
+        console.log(`  ${green('claude code:')} configured`);
+      } else {
+        console.log(`  ${yellow('claude code:')} settings exist but phewsh not configured`);
+      }
+    } catch {
+      console.log(`  ${yellow('claude code:')} settings unreadable`);
+    }
+  } else {
+    console.log(`  ${g('claude code:')} no settings.json found`);
+  }
+
+  console.log('');
+}
+
+async function main() {
+  const subcommand = process.argv[3] || 'status';
+
+  switch (subcommand) {
+    case 'setup':
+      await setup();
+      break;
+    case 'sync':
+      await sync();
+      break;
+    case 'status':
+      await status();
+      break;
+    default:
+      console.log(`\n  ${b('phewsh mcp')} — Connect AI agents to your project intelligence\n`);
+      console.log(`  ${w('setup')}    Install and configure the MCP server`);
+      console.log(`  ${w('sync')}     Sync projects → ~/.phewsh/projects.json`);
+      console.log(`  ${w('status')}   Check what agents can see right now`);
+      console.log('');
+  }
+}
+
+module.exports = main;

package/commands/serve.js

@@ -0,0 +1,277 @@
+// phewsh serve — HTTP bridge server for live execution from the web UI
+//
+// Starts a local server that the PHEWSH web app connects to for live task execution.
+// When running, the web UI shows a green "Live" indicator and "Run Live" buttons.
+//
+// Usage:
+//   phewsh serve              Start on default port (7483)
+//   phewsh serve --port 8080  Start on custom port
+
+const http = require('http');
+const { execSync, spawn } = require('child_process');
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+const b = (s) => `\x1b[1m${s}\x1b[0m`;
+const g = (s) => `\x1b[90m${s}\x1b[0m`;
+const w = (s) => `\x1b[97m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+
+// ─── Configuration ─────────────────────────────────────────────────────────
+
+function getPort() {
+  const idx = process.argv.indexOf('--port');
+  if (idx !== -1 && process.argv[idx + 1]) return parseInt(process.argv[idx + 1], 10);
+  return 7483;
+}
+
+// ─── Runtime Detection ─────────────────────────────────────────────────────
+
+function detectRuntimes() {
+  const runtimes = [];
+
+  // Check for Claude Code CLI
+  try {
+    execSync('which claude', { stdio: 'pipe' });
+    runtimes.push({ id: 'claude-code', label: 'Claude Code', connected: true });
+  } catch {
+    runtimes.push({ id: 'claude-code', label: 'Claude Code', connected: false });
+  }
+
+  // Always report human as available
+  runtimes.push({ id: 'human', label: 'You', connected: true });
+  runtimes.push({ id: 'generic', label: 'AI Draft', connected: false });
+
+  return runtimes;
+}
+
+// ─── Job Queue ─────────────────────────────────────────────────────────────
+
+const jobs = new Map();
+
+function createJob(actionId, runtimeId, packet) {
+  const jobId = crypto.randomUUID();
+  jobs.set(jobId, {
+    jobId,
+    actionId,
+    runtimeId,
+    packet,
+    status: 'queued',
+    statusText: 'Queued — waiting to execute',
+    result: null,
+    error: null,
+    createdAt: new Date().toISOString(),
+  });
+  return jobId;
+}
+
+async function executeJob(jobId) {
+  const job = jobs.get(jobId);
+  if (!job) return;
+
+  job.status = 'executing';
+  job.statusText = 'Starting execution...';
+
+  const { runtimeId, packet } = job;
+
+  if (runtimeId === 'claude-code') {
+    await executeViaClaude(job, packet);
+  } else {
+    job.status = 'error';
+    job.error = `Runtime ${runtimeId} not supported for live execution yet`;
+    job.statusText = 'Unsupported runtime';
+  }
+}
+
+async function executeViaClaude(job, packet) {
+  // Build a prompt from the dispatch packet
+  const prompt = [
+    `# Task: ${packet.objective?.task || 'Execute task'}`,
+    '',
+    packet.objective?.task || '',
+    '',
+    packet.context?.plan ? `## Context\n${packet.context.plan}` : '',
+    '',
+    packet.verification?.criteria?.length
+      ? `## Verify\n${packet.verification.criteria.map(c => `- ${c}`).join('\n')}`
+      : '',
+    '',
+    '## Instructions',
+    'Execute this task and report the result. Be specific about what you did and what the outcome was.',
+    'If the task involves code, show the relevant code. If it involves commands, show what you ran.',
+  ].filter(Boolean).join('\n');
+
+  return new Promise((resolve) => {
+    job.statusText = 'Launching Claude Code...';
+
+    // Use claude CLI with --print flag for non-interactive output
+    const child = spawn('claude', ['-p', prompt, '--output-format', 'text'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+      cwd: process.cwd(),
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      // Update status with last line of output as progress indicator
+      const lines = stdout.trim().split('\n').filter(l => l.trim());
+      if (lines.length > 0) {
+        const lastLine = lines[lines.length - 1].trim().slice(0, 80);
+        job.statusText = lastLine || 'Working...';
+      }
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0 && stdout.trim()) {
+        job.status = 'done';
+        job.result = stdout.trim();
+        job.statusText = 'Complete';
+        console.log(`  ${green('✓')} Job ${job.jobId.slice(0, 8)} completed`);
+      } else {
+        job.status = 'error';
+        job.error = stderr.trim() || `Claude exited with code ${code}`;
+        job.statusText = 'Failed';
+        console.log(`  ${yellow('✗')} Job ${job.jobId.slice(0, 8)} failed: ${job.error.slice(0, 100)}`);
+      }
+      resolve();
+    });
+
+    child.on('error', (err) => {
+      job.status = 'error';
+      job.error = err.message;
+      job.statusText = 'Failed to start';
+      console.log(`  ${yellow('✗')} Job ${job.jobId.slice(0, 8)} error: ${err.message}`);
+      resolve();
+    });
+  });
+}
+
+// ─── HTTP Server ───────────────────────────────────────────────────────────
+
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      try { resolve(JSON.parse(body)); }
+      catch { reject(new Error('Invalid JSON')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function cors(res) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+
+function json(res, data, status = 200) {
+  cors(res);
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+function main() {
+  const port = getPort();
+  const runtimes = detectRuntimes();
+  const hasClaudeCode = runtimes.find(r => r.id === 'claude-code')?.connected;
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+
+    // CORS preflight
+    if (req.method === 'OPTIONS') {
+      cors(res);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Health check
+    if (url.pathname === '/health' && req.method === 'GET') {
+      return json(res, {
+        status: 'ok',
+        runtimes: detectRuntimes(),
+        version: require('../package.json').version,
+        uptime: process.uptime(),
+      });
+    }
+
+    // Dispatch a task
+    if (url.pathname === '/dispatch' && req.method === 'POST') {
+      try {
+        const body = await parseBody(req);
+        const { actionId, runtimeId, packet } = body;
+
+        if (!actionId || !runtimeId || !packet) {
+          return json(res, { error: 'Missing actionId, runtimeId, or packet' }, 400);
+        }
+
+        const jobId = createJob(actionId, runtimeId, packet);
+        console.log(`  ${cyan('→')} Dispatched job ${jobId.slice(0, 8)} for ${runtimeId}: ${packet.objective?.task?.slice(0, 60) || 'task'}`);
+
+        // Start execution in background
+        executeJob(jobId);
+
+        return json(res, { jobId, status: 'queued' });
+      } catch (err) {
+        return json(res, { error: err.message }, 400);
+      }
+    }
+
+    // Check job status
+    const statusMatch = url.pathname.match(/^\/status\/(.+)$/);
+    if (statusMatch && req.method === 'GET') {
+      const jobId = statusMatch[1];
+      const job = jobs.get(jobId);
+      if (!job) return json(res, { error: 'Job not found' }, 404);
+      return json(res, {
+        jobId: job.jobId,
+        status: job.status,
+        statusText: job.statusText,
+        result: job.result,
+        error: job.error,
+      });
+    }
+
+    // 404
+    json(res, { error: 'Not found' }, 404);
+  });
+
+  server.listen(port, () => {
+    console.log('');
+    console.log(`  ${b(w('PHEWSH Serve'))} ${g('v' + require('../package.json').version)}`);
+    console.log(`  ${g('Live execution bridge for phewsh.com/intent')}`);
+    console.log('');
+    console.log(`  ${green('●')} Running on ${w(`http://localhost:${port}`)}`);
+    console.log('');
+    console.log(`  ${b('Connected runtimes:')}`);
+    runtimes.forEach(r => {
+      const status = r.connected ? green('● connected') : g('○ not found');
+      console.log(`    ${r.label}: ${status}`);
+    });
+    if (!hasClaudeCode) {
+      console.log('');
+      console.log(`  ${yellow('Tip:')} Install Claude Code CLI for live task execution`);
+      console.log(`  ${g('https://docs.anthropic.com/en/docs/claude-code')}`);
+    }
+    console.log('');
+    console.log(`  ${g('Open phewsh.com/intent → Work tab to see the Live indicator')}`);
+    console.log(`  ${g('Press Ctrl+C to stop')}`);
+    console.log('');
+  });
+}
+
+module.exports = main;

package/commands/session.js

@@ -12,6 +12,10 @@ const CONFIG_DIR = path.join(os.homedir(), '.phewsh');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
 const INTENT_DIR = path.join(process.cwd(), '.intent');
 
+const { select, refreshSession: refreshSess } = require('../lib/supabase');
+const { readPPS } = require('../lib/pps');
+const { push, pull, ensureValidToken } = require('./sync');
+
 const b = (s) => `\x1b[1m${s}\x1b[0m`;
 const d = (s) => `\x1b[2m${s}\x1b[0m`;
 const w = (s) => `\x1b[97m${s}\x1b[0m`;
@@ -20,6 +24,79 @@ const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 
+// Sync awareness: compare local .intent/ timestamps with cloud updated_at
+async function checkSyncStatus(config) {
+  if (!config?.supabaseUserId || !config?.supabaseAccessToken) return null;
+  if (!fs.existsSync(INTENT_DIR)) return null;
+
+  try {
+    const token = await ensureValidToken(config);
+    if (!token) return null;
+
+    const pps = readPPS(INTENT_DIR);
+    const cloudId = pps?.adapters?.phewsh?.cloud_id;
+    const projectName = path.basename(process.cwd());
+
+    // Find cloud project
+    const query = cloudId
+      ? `id=eq.${cloudId}&user_id=eq.${config.supabaseUserId}&select=id,updated_at`
+      : `name=eq.${encodeURIComponent(projectName)}&user_id=eq.${config.supabaseUserId}&select=id,updated_at`;
+
+    const projects = await select('projects', query, token);
+    if (projects.length === 0) return { status: 'local-only' };
+
+    const project = projects[0];
+
+    // Get latest cloud artifact updated_at
+    const artifacts = await select(
+      'artifacts',
+      `project_id=eq.${project.id}&user_id=eq.${config.supabaseUserId}&select=kind,updated_at&order=updated_at.desc&limit=1`,
+      token
+    );
+
+    const cloudTime = artifacts.length > 0
+      ? new Date(artifacts[0].updated_at).getTime()
+      : new Date(project.updated_at).getTime();
+
+    // Get latest local file mtime
+    const localFiles = ['vision.md', 'plan.md', 'next.md'];
+    let latestLocal = 0;
+    for (const file of localFiles) {
+      const filePath = path.join(INTENT_DIR, file);
+      if (fs.existsSync(filePath)) {
+        const mtime = fs.statSync(filePath).mtimeMs;
+        if (mtime > latestLocal) latestLocal = mtime;
+      }
+    }
+
+    if (latestLocal === 0) return { status: 'local-only' };
+
+    const drift = Math.abs(cloudTime - latestLocal);
+    // Within 60 seconds = synced
+    if (drift < 60000) return { status: 'synced' };
+
+    if (cloudTime > latestLocal) {
+      const ago = formatAgo(Date.now() - cloudTime);
+      return { status: 'cloud-newer', ago };
+    } else {
+      const ago = formatAgo(Date.now() - latestLocal);
+      return { status: 'local-newer', ago };
+    }
+  } catch {
+    return null; // Network error — silently skip
+  }
+}
+
+function formatAgo(ms) {
+  const mins = Math.floor(ms / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  return `${days}d ago`;
+}
+
 const MODELS = {
   'claude-sonnet': { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', provider: 'anthropic' },
   'claude-opus': { id: 'claude-opus-4-6', name: 'Claude Opus 4.6', provider: 'anthropic' },
@@ -149,6 +226,26 @@ async function main() {
   if (config?.email) {
     console.log(`  ${g('  user:')} ${config.email}`);
   }
+
+  // Sync status check (non-blocking, 3s timeout)
+  if (config?.supabaseUserId && intentFiles.length > 0) {
+    const syncResult = await Promise.race([
+      checkSyncStatus(config),
+      new Promise(resolve => setTimeout(() => resolve(null), 3000)),
+    ]);
+    if (syncResult) {
+      if (syncResult.status === 'cloud-newer') {
+        console.log(`  ${yellow('↓')} Cloud is newer (${syncResult.ago}) — run /pull`);
+      } else if (syncResult.status === 'local-newer') {
+        console.log(`  ${yellow('↑')} Local changes not pushed (${syncResult.ago}) — run /push`);
+      } else if (syncResult.status === 'synced') {
+        console.log(`  ${green('↕')} ${g('synced')}`);
+      } else if (syncResult.status === 'local-only') {
+        console.log(`  ${g('↕ not linked to cloud — run /push to sync')}`);
+      }
+    }
+  }
+
   console.log('');
   console.log(`  ${g('type naturally · /help for commands · /quit to exit')}`);
   console.log('');
@@ -193,10 +290,16 @@ async function main() {
 
   ${w('project')}
     ${g('/init')}        Create .intent/ artifacts in this directory
+    ${g('/clarify')}     AI-assisted artifact generation
     ${g('/context')}     Show loaded .intent/ files
     ${g('/reload')}      Reload .intent/ context from disk
     ${g('/status')}      Show session stats
 
+  ${w('sync')}
+    ${g('/push')}        Push .intent/ to cloud
+    ${g('/pull')}        Pull .intent/ from cloud (reloads context)
+    ${g('/sync')}        Check sync status
+
   ${w('configuration')}
     ${g('/login')}       Set up identity + cloud sync
     ${g('/key')}         Set or update your API key
@@ -286,6 +389,94 @@ async function main() {
         return;
       }
 
+      if (cmd === 'clarify') {
+        if (!config?.apiKey) {
+          console.log(`\n  ${yellow('⚠')} No API key. Run /key to set one.\n`);
+          rl.prompt();
+          return;
+        }
+        try {
+          const { execSync } = require('child_process');
+          const args = cmdArg ? `--text "${cmdArg.replace(/"/g, '\\"')}"` : '';
+          execSync(`node ${path.join(__dirname, 'clarify.js')} ${args}`, { stdio: 'inherit' });
+          // Reload context after clarify
+          intentFiles = loadIntentContext();
+          systemPrompt = buildSystemPrompt(intentFiles);
+          if (intentFiles.length > 0) {
+            console.log(`  ${green('●')} Context loaded: ${intentFiles.map(f => f.file).join(', ')}`);
+          }
+        } catch (err) {
+          console.error(`  ${g('Clarify failed:')} ${err.message}`);
+        }
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'push') {
+        if (!config?.supabaseUserId) {
+          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          rl.prompt();
+          return;
+        }
+        try {
+          const token = await ensureValidToken(config);
+          if (!token) { console.log(`\n  ${yellow('⚠')} Session expired. Run /login.\n`); rl.prompt(); return; }
+          await push(config, token);
+        } catch (err) {
+          console.error(`  ${yellow('⚠')} Push failed: ${err.message}\n`);
+        }
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'pull') {
+        if (!config?.supabaseUserId) {
+          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          rl.prompt();
+          return;
+        }
+        try {
+          const token = await ensureValidToken(config);
+          if (!token) { console.log(`\n  ${yellow('⚠')} Session expired. Run /login.\n`); rl.prompt(); return; }
+          await pull(config, token);
+          // Reload context after pull
+          intentFiles = loadIntentContext();
+          systemPrompt = buildSystemPrompt(intentFiles);
+          if (intentFiles.length > 0) {
+            console.log(`  ${green('●')} Context reloaded: ${intentFiles.map(f => f.file).join(', ')}`);
+          }
+        } catch (err) {
+          console.error(`  ${yellow('⚠')} Pull failed: ${err.message}\n`);
+        }
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'sync') {
+        // Show sync status
+        if (!config?.supabaseUserId) {
+          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          rl.prompt();
+          return;
+        }
+        const syncResult = await checkSyncStatus(config);
+        if (!syncResult) {
+          console.log(`\n  ${g('Could not check sync status')}\n`);
+        } else if (syncResult.status === 'cloud-newer') {
+          console.log(`\n  ${yellow('↓')} Cloud is newer (${syncResult.ago}) — run /pull\n`);
+        } else if (syncResult.status === 'local-newer') {
+          console.log(`\n  ${yellow('↑')} Local changes not pushed (${syncResult.ago}) — run /push\n`);
+        } else if (syncResult.status === 'synced') {
+          console.log(`\n  ${green('↕')} In sync\n`);
+        } else if (syncResult.status === 'local-only') {
+          console.log(`\n  ${g('↕ Not linked to cloud — run /push to sync')}\n`);
+        }
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'login') {
         try {
           const { execSync } = require('child_process');

package/commands/sync.js

@@ -113,6 +113,7 @@ async function push(config, token) {
     if (!localPPS.adapters.phewsh) localPPS.adapters.phewsh = {};
     localPPS.adapters.phewsh.cloud_id = project.id;
     localPPS.adapters.phewsh.last_synced = new Date().toISOString();
+    localPPS.adapters.phewsh.last_updated_by = 'cli';
     writePPS(INTENT_DIR, localPPS);
   }
 
@@ -164,7 +165,7 @@ async function pull(config, token, cloudId = null) {
     // Keep any local adapter links
     if (localPPS?.adapters) merged.adapters = { ...project.pps_json.adapters, ...localPPS.adapters };
     merged.adapters = merged.adapters || {};
-    merged.adapters.phewsh = { cloud_id: project.id, last_synced: new Date().toISOString() };
+    merged.adapters.phewsh = { cloud_id: project.id, last_synced: new Date().toISOString(), last_updated_by: 'pull' };
     writePPS(INTENT_DIR, merged);
     pulled.push('pps.json');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"