phewsh 0.12.4 → 0.13.1

package/README.md

@@ -83,7 +83,9 @@ These artifacts become persistent context for AI conversations, both in the shel
 ## All Commands
 
 ```bash
-phewsh                    # Interactive AI session with .intent/ context
+phewsh                    # The front door — routes through your installed agents
+phewsh setup              # Guided setup: pick your default route (60 seconds)
+phewsh outcomes           # Decision record — what was kept, reverted, or failed
 phewsh serve              # Live execution bridge for web app
 phewsh clarify            # AI-assisted artifact generation
 phewsh intent --init      # Create .intent/ without entering the shell
@@ -114,6 +116,24 @@ while a local bridge is running (`phewsh serve` or `phewsh mcp serve` — the
 first executes tasks directly via Claude Code, the second routes them to
 live connected agents; both record identical receipts).
 
+## Outcomes
+
+A receipt says *what ran*. An outcome says *what became of it*. Every routed
+action in a session records a decision; label it when you actually know —
+seconds later or three weeks later:
+
+```bash
+# in a session, right after a response: type 1-4
+# 1 kept · 2 reverted · 3 superseded · 4 failed
+
+phewsh outcomes           # totals, kept-rate by route and mode, recent decisions
+phewsh outcomes label     # label anything still pending
+```
+
+Over time this becomes the record no platform keeps for you: which decisions
+held up, which model is most reliable for which kind of work, and where your
+effort actually went.
+
 ## Sync
 
 CLI and web ([phewsh.com/intent](https://phewsh.com/intent)) share the same cloud via Supabase.

package/bin/phewsh.js

@@ -64,6 +64,9 @@ const COMMANDS = {
   watch:   () => require('../commands/watch')(),
   mcp:     () => require('../commands/mcp')(),
   receipts: () => require('../commands/receipts')(),
+  outcomes: () => require('../commands/outcomes')(),
+  bypass:  () => require('../commands/bypass')(),
+  setup:   () => require('../commands/setup')(),
   update:  () => require('../commands/update')(),
   serve:   () => require('../commands/serve')(),
   sequence: () => require('../commands/sequence')(),
@@ -83,7 +86,8 @@ function showHelp() {
   console.log(`  ${g('The loop: define .intent/ → sync → every AI tool reads → work → repeat')}`);
   console.log('');
   console.log(`  ${b(w('get started'))}`);
-  console.log(`    ${cyan('phewsh')}           ${g('Open a session — create, plan, and work')}`);
+  console.log(`    ${cyan('phewsh')}           ${g('Open a session — routes through your installed agents')}`);
+  console.log(`    ${cyan('phewsh setup')}      ${g('Guided setup — pick your default route (60 seconds)')}`);
   console.log(`    ${cyan('phewsh clarify')}    ${g('Turn a messy idea into .intent/ artifacts')}`);
   console.log('');
   console.log(`  ${b(w('author .intent/'))}`);
@@ -100,6 +104,8 @@ function showHelp() {
   console.log(`    ${cyan('serve')}      ${g('Execution bridge — run from phewsh.com/intent')}`);
   console.log(`    ${cyan('mcp')}        ${g('Connect AI agents via MCP protocol')}`);
   console.log(`    ${cyan('receipts')}   ${g('Proof trail — what agents actually did, with evidence')}`);
+  console.log(`    ${cyan('outcomes')}   ${g('Decision record — what was kept, reverted, or failed')}`);
+  console.log(`    ${cyan('bypass')}     ${g('Went around phewsh? Record why — 10 seconds, no guilt')}`);
   console.log('');
   console.log(`  ${b(w('configure'))}`);
   console.log(`    ${cyan('login')}      ${g('Identity + API key + cloud sync')}`);

package/commands/bypass.js

@@ -0,0 +1,87 @@
+// phewsh bypass — record the moment you reached past phewsh.
+//
+// Every bypass is the most valuable data in the dogfood experiment: it
+// directly identifies why the front door fails. Make it 10 seconds, no guilt.
+//
+//   phewsh bypass                 Quick picker
+//   phewsh bypass 2               By number (1-7)
+//   phewsh bypass faster          By name
+//   phewsh bypass 7 "was on my phone"   Reason + note
+
+const readline = require('readline');
+const ui = require('../lib/ui');
+const { BYPASS_REASONS, recordBypass, bypassStats } = require('../lib/outcomes');
+
+const { b, teal, sage, slate, cream, ember } = ui;
+
+const LABELS = {
+  'forgot': 'Forgot phewsh existed in the moment',
+  'faster': 'Direct was faster',
+  'needed-editing': 'Needed interactive file editing',
+  'needed-context': 'Needed that tool\'s own context/memory',
+  'model-quality': 'Needed that model\'s quality',
+  'phewsh-in-the-way': 'phewsh got in the way',
+  'other': 'Something else',
+};
+
+function resolveReason(arg) {
+  if (!arg) return null;
+  const n = parseInt(arg, 10);
+  if (n >= 1 && n <= BYPASS_REASONS.length) return BYPASS_REASONS[n - 1];
+  const match = BYPASS_REASONS.find(r => r === arg || r.startsWith(arg));
+  return match || null;
+}
+
+function confirm(reason, count) {
+  console.log(`\n  ${teal('●')} ${sage('Bypass recorded:')} ${cream(LABELS[reason])}`);
+  console.log(`  ${slate(`${count} total — no guilt, this is the experiment working. phewsh outcomes shows the pattern.`)}\n`);
+}
+
+module.exports = function bypass() {
+  const args = process.argv.slice(3);
+
+  if (args[0] === 'stats') {
+    const stats = bypassStats();
+    console.log('');
+    console.log(`  ${b(cream('Bypasses'))} ${slate('— why the front door got skipped')}`);
+    ui.divider('line');
+    if (stats.total === 0) {
+      console.log(`  ${sage('None recorded. When you catch yourself in Claude Code directly:')} ${cream('phewsh bypass')}`);
+    } else {
+      console.log(`  ${cream(String(stats.total))} ${sage('total')}`);
+      for (const [reason, count] of Object.entries(stats.byReason).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${cream(String(count).padStart(3))}  ${sage(LABELS[reason])}`);
+      }
+    }
+    console.log('');
+    return;
+  }
+
+  const reason = resolveReason(args[0]);
+  if (reason) {
+    const note = args.slice(1).join(' ');
+    confirm(reason, recordBypass(reason, note));
+    return;
+  }
+  if (args[0]) {
+    console.log(`\n  ${ember('!')} ${sage('Unknown reason. Pick 1-7 or:')} ${cream(BYPASS_REASONS.join(', '))}\n`);
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${b(cream('You opened something directly instead of phewsh — why?'))}`);
+  BYPASS_REASONS.forEach((r, i) => {
+    console.log(`    ${teal(String(i + 1))} ${sage(LABELS[r])}`);
+  });
+  console.log('');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question(`  ${teal('>')} ${slate('1-7, enter = cancel: ')}`, (answer) => {
+    rl.close();
+    const picked = resolveReason(answer.trim());
+    if (!picked) {
+      console.log(`  ${slate('Cancelled.')}\n`);
+      return;
+    }
+    confirm(picked, recordBypass(picked));
+  });
+};

package/commands/outcomes.js

@@ -0,0 +1,171 @@
+// phewsh outcomes — the accumulated record of decisions and what became of them.
+//
+//   phewsh outcomes                  Stats + recent decisions
+//   phewsh outcomes label            Interactively label pending decisions
+//   phewsh outcomes label <id> <o>   Label one decision directly
+
+const readline = require('readline');
+const ui = require('../lib/ui');
+const {
+  OUTCOMES, recordDecision, labelOutcome,
+  pendingDecisions, recentDecisions, outcomeStats, bypassStats,
+} = require('../lib/outcomes');
+
+const { b, teal, peach, sage, slate, cream, ember, green } = ui;
+
+const OUTCOME_COLOR = {
+  kept: green, reverted: ember, superseded: peach, failed: ember,
+};
+
+function fmtAgo(ts) {
+  const ms = Date.now() - new Date(ts).getTime();
+  const mins = Math.floor(ms / 60000);
+  if (mins < 60) return `${mins}m`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h`;
+  return `${Math.floor(hrs / 24)}d`;
+}
+
+// Pad the raw word before coloring — ANSI codes break padEnd's width math
+function outcomeBadge(d, width = 10) {
+  if (!d.outcome) return slate('pending'.padEnd(width));
+  return OUTCOME_COLOR[d.outcome](d.outcome.padEnd(width));
+}
+
+function showBypasses() {
+  const bypasses = bypassStats();
+  if (bypasses.total === 0) return;
+  console.log('');
+  console.log(`  ${b(cream('Bypasses'))} ${slate('— why the front door got skipped')}`);
+  for (const [reason, count] of Object.entries(bypasses.byReason).sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${cream(String(count).padStart(3))}  ${sage(reason)}`);
+  }
+}
+
+function showStats() {
+  const stats = outcomeStats();
+  const labeled = stats.total - stats.pending;
+
+  console.log('');
+  console.log(`  ${b(cream('Outcomes'))} ${slate('— what your decisions became')}`);
+  ui.divider('line');
+
+  if (stats.total === 0) {
+    console.log(`  ${sage('Nothing recorded yet.')}`);
+    console.log(`  ${slate('Work through a phewsh session — every routed action records a decision.')}`);
+    console.log(`  ${slate('Label them 1-4 as you learn what held up.')}`);
+    showBypasses();
+    console.log('');
+    return;
+  }
+
+  console.log(`  ${cream(String(stats.total))} ${sage('decisions')} ${slate('·')} ${cream(String(labeled))} ${sage('labeled')} ${slate('·')} ${cream(String(stats.pending))} ${sage('pending')}`);
+  if (labeled > 0) {
+    console.log(`  ${green(stats.kept + ' kept')} ${slate('·')} ${ember(stats.reverted + ' reverted')} ${slate('·')} ${peach(stats.superseded + ' superseded')} ${slate('·')} ${ember(stats.failed + ' failed')}`);
+  }
+
+  const routes = Object.entries(stats.byRoute);
+  if (routes.length > 0) {
+    console.log('');
+    console.log(`  ${b(cream('By route'))}`);
+    for (const [route, r] of routes.sort((a, b) => b[1].total - a[1].total)) {
+      const rate = r.total > 0 ? Math.round((r.kept / r.total) * 100) : 0;
+      console.log(`    ${cream(route.padEnd(14))} ${sage(`${r.total} labeled`)} ${slate('·')} ${green(`${rate}% kept`)}`);
+    }
+  }
+
+  const modes = Object.entries(stats.byMode);
+  if (modes.length > 0) {
+    console.log('');
+    console.log(`  ${b(cream('By mode'))}`);
+    for (const [mode, m] of modes.sort((a, b) => b[1].total - a[1].total)) {
+      const rate = m.total > 0 ? Math.round((m.kept / m.total) * 100) : 0;
+      console.log(`    ${cream(mode.padEnd(14))} ${sage(`${m.total} labeled`)} ${slate('·')} ${green(`${rate}% kept`)}`);
+    }
+  }
+
+  const recent = recentDecisions(8);
+  if (recent.length > 0) {
+    console.log('');
+    console.log(`  ${b(cream('Recent'))}`);
+    for (const d of recent) {
+      console.log(`    ${slate(d.id.padEnd(10))} ${outcomeBadge(d)} ${slate(fmtAgo(d.ts).padStart(3))} ${sage(d.summary.slice(0, 56))}`);
+    }
+  }
+
+  showBypasses();
+
+  if (stats.pending > 0) {
+    console.log('');
+    console.log(`  ${sage('Label pending decisions:')} ${cream('phewsh outcomes label')}`);
+  }
+  console.log('');
+}
+
+function labelInteractive() {
+  const pending = pendingDecisions();
+  if (pending.length === 0) {
+    console.log(`\n  ${teal('●')} ${sage('No pending decisions — everything is labeled.')}\n`);
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${b(cream(`${pending.length} pending decision${pending.length !== 1 ? 's' : ''}`))}`);
+  console.log(`  ${slate('1 kept · 2 reverted · 3 superseded · 4 failed · enter = skip · q = quit')}`);
+  ui.divider('line');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let i = 0;
+
+  const next = () => {
+    if (i >= pending.length) {
+      rl.close();
+      console.log(`\n  ${teal('●')} ${sage('Done.')}\n`);
+      return;
+    }
+    const d = pending[i];
+    console.log('');
+    console.log(`  ${slate(d.id)} ${sage(fmtAgo(d.ts) + ' ago')} ${slate('·')} ${cream(d.route)} ${slate('·')} ${sage(d.project)}`);
+    console.log(`  ${cream(d.summary)}`);
+    rl.question(`  ${teal('>')} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === 'q') {
+        rl.close();
+        console.log(`\n  ${sage('Stopped — the rest stay pending.')}\n`);
+        return;
+      }
+      const idx = parseInt(a, 10);
+      if (idx >= 1 && idx <= 4) {
+        labelOutcome(d.id, OUTCOMES[idx - 1]);
+        console.log(`  ${teal('●')} ${OUTCOME_COLOR[OUTCOMES[idx - 1]](OUTCOMES[idx - 1])}`);
+      }
+      i++;
+      next();
+    });
+  };
+  next();
+}
+
+module.exports = function outcomes() {
+  const args = process.argv.slice(3);
+  const sub = args[0];
+
+  if (sub === 'label') {
+    const id = args[1];
+    const outcome = args[2];
+    if (id && outcome) {
+      try {
+        const d = labelOutcome(id, outcome);
+        if (d) console.log(`\n  ${teal('●')} ${sage('Labeled')} ${cream(d.summary.slice(0, 50))} ${slate('→')} ${OUTCOME_COLOR[outcome](outcome)}\n`);
+        else console.log(`\n  ${ember('!')} ${sage('No unique decision matching')} ${cream(id)}\n`);
+      } catch (err) {
+        console.log(`\n  ${ember('!')} ${sage(err.message)}\n`);
+      }
+      return;
+    }
+    labelInteractive();
+    return;
+  }
+
+  showStats();
+};

package/commands/session.js

@@ -16,6 +16,9 @@ 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 { HARNESSES, listHarnesses, runViaHarness } = require('../lib/harnesses');
+const { recordDecision, labelOutcome, pendingDecisions, OUTCOMES } = require('../lib/outcomes');
+const { recordSessionEvent } = require('../lib/receipts-data');
 
 // Brand palette shortcuts
 const { b, d, w, g, green, cyan, yellow,
@@ -98,6 +101,43 @@ const MODELS = {
 
 const DEFAULT_MODEL = 'claude-sonnet';
 
+// ── Routing: where plain typed input goes ─────────────────────────────────
+// A route is either an installed harness (your existing subscription — no
+// API key needed in phewsh) or the direct API (your key). Precedence:
+// explicit config.defaultRoute → API key if set → first installed harness.
+
+function resolveRoute(config, harnesses) {
+  const installed = harnesses.filter(h => h.installed);
+  const preferred = config?.defaultRoute;
+  if (preferred === 'api' && config?.apiKey) return { type: 'api' };
+  if (preferred && installed.some(h => h.id === preferred)) {
+    return { type: 'harness', id: preferred };
+  }
+  if (config?.apiKey) return { type: 'api' };
+  if (installed.length > 0) return { type: 'harness', id: installed[0].id };
+  return null;
+}
+
+function routeLabel(route, config) {
+  if (!route) return 'no route — /setup';
+  if (route.type === 'api') {
+    return `API (${config?.provider === 'openrouter' ? 'OpenRouter' : 'Anthropic'} key)`;
+  }
+  const h = HARNESSES[route.id];
+  return `${h.label} (your ${h.auth.split(' / ')[0].toLowerCase()})`;
+}
+
+// ── Intent modes: "What are you trying to do?" ────────────────────────────
+// Picked by number at the start of a session. Shapes the system prompt; the
+// route stays whatever it is. Mode 5 is a route switcher, handled inline.
+
+const INTENT_MODES = {
+  1: { id: 'build',    label: 'Build',    hint: 'The user is in execution mode. Bias toward concrete next steps, working code, and shipping. Flag scope creep — it is their most common failure pattern.' },
+  2: { id: 'research', label: 'Research', hint: 'The user is exploring. Compare options honestly, surface trade-offs, and say what you would pick and why. Do not pad.' },
+  3: { id: 'decide',   label: 'Decide',   hint: 'The user needs to make a decision. Force clarity: name the actual decision, the options, the constraints from .intent/, and give one recommendation with reasoning. Small constrained choices beat big vague ones.' },
+  4: { id: 'review',   label: 'Review',   hint: 'The user wants critical review. Find what is wrong or risky before praising anything. Be specific about severity.' },
+};
+
 function loadConfig() {
   if (!fs.existsSync(CONFIG_PATH)) return null;
   try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); } catch { return null; }
@@ -134,6 +174,17 @@ function buildSystemPrompt(intentFiles) {
   return `${base}\n\nThe user has structured intent artifacts for this project. Use them as primary context — stay aligned with their vision, plan, and next actions.\n\n${sections}`;
 }
 
+// Harness CLIs are one-shot — fold the recent conversation into the prompt
+// so a session through Claude Code / Codex still feels continuous.
+function buildHarnessPrompt(messages, input) {
+  const tail = messages.slice(-6);
+  if (tail.length === 0) return input;
+  const transcript = tail
+    .map(m => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content.slice(0, 1500)}`)
+    .join('\n\n');
+  return `Conversation so far:\n\n${transcript}\n\n---\n\nUser: ${input}\n\nRespond to the last user message.`;
+}
+
 async function streamChat(apiKey, messages, systemPrompt, modelId) {
   const body = { model: modelId, max_tokens: 2048, messages, stream: true };
   if (systemPrompt) body.system = systemPrompt;
@@ -207,22 +258,22 @@ async function main() {
   let totalPromptTokens = 0;
   let totalCompletionTokens = 0;
 
+  // ── Detect capabilities, resolve the route ──────────────
+  const harnesses = listHarnesses();
+  const installedHarnesses = harnesses.filter(h => h.installed);
+  let route = resolveRoute(config, harnesses);
+  let sessionMode = null;          // INTENT_MODES id once picked
+  let awaitingOutcome = null;      // decision id eligible for 1-4 labeling
+  let decisionsThisSession = 0;
+
   // ── The Exhale: animated brand reveal ──────────────────
   await ui.brandReveal();
 
-  // ── First-run welcome ──────────────────────────────────
-  if (!config?.apiKey) {
-    console.log(`  ${b(cream('Welcome to phewsh.'))}`);
-    console.log('');
-    console.log(`    ${teal('/key')}    ${sage('Set your API key (takes 10 seconds)')}`);
-    console.log(`    ${teal('/init')}   ${sage('Create .intent/ for this project')}`);
-    console.log(`    ${teal('/tour')}   ${sage('See what this does (no key needed)')}`);
-    console.log('');
-  } else if (!config.apiKey.startsWith('sk-')) {
-    console.log(`  ${ember('!')} ${sage('Stored API key looks invalid.')}`);
-    console.log(`  ${sage('Run')} ${cream('/key')} ${sage('to set a new one')}`);
+  if (config?.apiKey && !config.apiKey.startsWith('sk-')) {
+    console.log(`  ${ember('!')} ${sage('Stored API key looks invalid — ignoring it.')} ${slate('/key to replace')}`);
     console.log('');
     config.apiKey = null;
+    route = resolveRoute(config, harnesses);
   }
 
   // ── Project status (compact) ────────────────────────────
@@ -232,9 +283,23 @@ async function main() {
   } else {
     statusParts.push(slate('no .intent/ — run /init'));
   }
-  statusParts.push(sage(MODELS[currentModel].name));
+  statusParts.push(sage('via ' + routeLabel(route, config)));
   console.log(`  ${statusParts.join(slate('  ·  '))}`);
 
+  // Capabilities: what's installed on this machine, no setup required
+  if (installedHarnesses.length > 0) {
+    const caps = harnesses.map(h =>
+      h.installed ? `${teal('✓')} ${sage(h.label)}` : slate(`✗ ${h.label}`)
+    ).join(slate(' · '));
+    console.log(`  ${caps}`);
+  }
+
+  // Decisions from past sessions still waiting on an outcome
+  const pendingPast = pendingDecisions();
+  if (pendingPast.length > 0) {
+    console.log(`  ${peach('◌')} ${sage(`${pendingPast.length} decision${pendingPast.length !== 1 ? 's' : ''} awaiting outcome`)} ${slate('— /outcomes to label')}`);
+  }
+
   // Sync status (one-line, non-blocking)
   if (config?.supabaseUserId && intentFiles.length > 0) {
     const syncResult = await Promise.race([
@@ -253,10 +318,20 @@ async function main() {
   }
 
   console.log('');
-  if (!config?.apiKey) {
-    console.log(`  ${cream('/key')} ${sage('to start ·')} ${cream('/tour')} ${sage('to explore ·')} ${cream('/help')} ${sage('for more')}`);
+  if (!route) {
+    // Nothing to route through: no key, no agent CLIs found on this machine.
+    console.log(`  ${b(cream('Welcome to phewsh.'))}`);
+    console.log('');
+    console.log(`  ${sage('No agent CLI found (Claude Code, Codex, Gemini, Cursor, OpenCode)')}`);
+    console.log(`  ${sage('and no API key set. Either one gets you running:')}`);
+    console.log('');
+    console.log(`    ${teal('/key')}    ${sage('Set an API key (10 seconds)')}`);
+    console.log(`    ${teal('/tour')}   ${sage('See what this does (nothing needed)')}`);
+    console.log(`  ${slate('Or install Claude Code / Codex — phewsh uses their login automatically.')}`);
   } else {
-    console.log(`  ${ui.randomTip()}`);
+    console.log(`  ${b(cream('What are you trying to do?'))}`);
+    console.log(`  ${teal('1')} ${sage('Build')}  ${slate('·')}  ${teal('2')} ${sage('Research')}  ${slate('·')}  ${teal('3')} ${sage('Decide')}  ${slate('·')}  ${teal('4')} ${sage('Review')}  ${slate('·')}  ${teal('5')} ${sage('Ask another model')}`);
+    console.log(`  ${slate('pick a number, or just type — both work')}`);
   }
   console.log('');
 
@@ -277,6 +352,49 @@ async function main() {
       return;
     }
 
+    // A bare 1-4 right after a routed action labels its outcome
+    if (awaitingOutcome && /^[1-4]$/.test(input)) {
+      const outcome = OUTCOMES[parseInt(input, 10) - 1];
+      try {
+        labelOutcome(awaitingOutcome, outcome);
+        const color = outcome === 'kept' ? green : outcome === 'superseded' ? peach : ember;
+        console.log(`  ${teal('●')} ${sage('outcome:')} ${color(outcome)}`);
+      } catch { /* decision vanished — nothing to do */ }
+      awaitingOutcome = null;
+      console.log('');
+      rl.prompt();
+      return;
+    }
+
+    // A bare 1-5 on an empty conversation picks an intent mode
+    if (messages.length === 0 && !awaitingOutcome && /^[1-5]$/.test(input)) {
+      const n = parseInt(input, 10);
+      if (n === 5) {
+        console.log('');
+        console.log(`  ${b(cream('Ask another model — switch the route'))}`);
+        for (const h of harnesses) {
+          if (h.installed) console.log(`    ${teal('/use ' + h.id.padEnd(12))} ${sage(h.label)} ${slate('(' + h.auth + ')')}`);
+        }
+        if (config?.apiKey) console.log(`    ${teal('/use api'.padEnd(17))} ${sage('Direct API')} ${slate('(your key)')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+      sessionMode = INTENT_MODES[n].id;
+      console.log('');
+      console.log(`  ${teal('●')} ${cream(INTENT_MODES[n].label)} ${sage('mode · via ' + routeLabel(route, config))}`);
+      if (sessionMode === 'review' && route?.id !== 'codex' && installedHarnesses.some(h => h.id === 'codex')) {
+        console.log(`  ${slate('tip: a second model reviews more honestly — /use codex')}`);
+      }
+      if (sessionMode === 'build' && route?.type === 'harness') {
+        console.log(`  ${slate('tip: when this needs real file edits, /work drops you into ' + HARNESSES[route.id].label + ' and brings you back')}`);
+      }
+      console.log(`  ${sage('Describe it.')}`);
+      console.log('');
+      rl.prompt();
+      return;
+    }
+
     // Slash commands
     if (input.startsWith('/')) {
       const parts = input.slice(1).split(/\s+/);
@@ -291,6 +409,10 @@ async function main() {
         }
         console.log('');
         console.log(`  ${sage('session ended · ' + turns + ' exchanges · ' + (totalPromptTokens + totalCompletionTokens) + ' tokens')}`);
+        if (decisionsThisSession > 0) {
+          const stillPending = pendingDecisions().length;
+          console.log(`  ${sage(decisionsThisSession + ' decision' + (decisionsThisSession !== 1 ? 's' : '') + ' recorded')}${stillPending > 0 ? slate(` · ${stillPending} awaiting outcome — phewsh outcomes label`) : ''}`);
+        }
         console.log('');
         process.exit(0);
       }
@@ -316,16 +438,23 @@ async function main() {
         console.log(`    ${teal('/serve')}       ${sage('Execution bridge for phewsh.com/intent')}`);
         console.log(`    ${teal('/sync')}        ${sage('Check sync status')}`);
         console.log('');
+        console.log(`  ${cream('route — where your typing goes')}`);
+        console.log(`    ${teal('/use')} ${slate('<route>')}  ${sage('Switch: claude-code, codex, gemini, cursor, opencode, api')}`);
+        console.log(`    ${teal('/harnesses')}   ${sage('Agent CLIs detected on this machine')}`);
+        console.log(`    ${teal('/provider')}    ${sage('Current route + what\'s available')}`);
+        console.log(`    ${teal('/outcomes')}    ${sage('Decision record — kept/reverted/superseded/failed')}`);
+        console.log('');
         console.log(`  ${cream('session')}`);
+        console.log(`    ${teal('/work')} ${slate('[harness]')} ${sage('Hand off to interactive Claude Code/Codex — outcome on return')}`);
         console.log(`    ${teal('/run')} ${slate('<prompt>')} ${sage('One-shot prompt (no history)')}`);
         console.log(`    ${teal('/clear')}       ${sage('Clear conversation')}`);
         console.log(`    ${teal('/status')}      ${sage('Session stats')}`);
         console.log(`    ${teal('/quit')}        ${sage('Exit')}`);
         console.log('');
         console.log(`  ${cream('configure')}`);
-        console.log(`    ${teal('/key')}         ${sage('Set API key')}`);
+        console.log(`    ${teal('/key')}         ${sage('Set API key (optional — harnesses need none)')}`);
         console.log(`    ${teal('/login')}       ${sage('Identity + cloud sync')}`);
-        console.log(`    ${teal('/model')} ${slate('<name>')} ${sage('Switch model (sonnet, opus, haiku)')}`);
+        console.log(`    ${teal('/model')} ${slate('<name>')} ${sage('Switch API model (sonnet, opus, haiku)')}`);
         console.log(`    ${teal('/update')}      ${sage('Update phewsh')}`);
         console.log(`    ${teal('/tour')}        ${sage('Quick walkthrough')}`);
         console.log('');
@@ -388,10 +517,11 @@ async function main() {
           ['Tokens', `${totalPromptTokens} in → ${totalCompletionTokens} out`],
           ['Project', projectName, 'cyan'],
           ['Context', intentFiles.length > 0 ? intentFiles.map(f => f.file).join(', ') : 'none', intentFiles.length > 0 ? 'green' : 'yellow'],
-          ['Model', MODELS[currentModel].name],
-          ['Provider', MODELS[currentModel].provider],
+          ['Route', routeLabel(route, config), 'green'],
+          ['Mode', sessionMode || 'none'],
+          ['Decisions', `${decisionsThisSession} this session`],
           ['User', config?.email || slate('not logged in')],
-          ['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '...' : 'not set', config?.apiKey ? 'green' : 'yellow'],
+          ['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '...' : 'not set — optional', config?.apiKey ? 'green' : 'yellow'],
         ]);
         rl.prompt();
         return;
@@ -587,6 +717,20 @@ async function main() {
         return;
       }
 
+      if (cmd === 'setup') {
+        try {
+          const { execSync } = require('child_process');
+          execSync(`node ${path.join(__dirname, '..', 'bin', 'phewsh.js')} setup`, { stdio: 'inherit' });
+          config = loadConfig();
+          route = resolveRoute(config, harnesses);
+          console.log(`  ${teal('●')} ${sage('Route now:')} ${cream(routeLabel(route, config))}`);
+        } catch (err) {
+          console.error(`  ${sage('Setup failed:')} ${err.message}`);
+        }
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'key') {
         if (cmdArg) {
           const apiKey = cmdArg.trim();
@@ -606,6 +750,7 @@ async function main() {
             saveConfig(config);
             console.log(`  ${teal('●')} ${sage('API key saved. You\'re ready — just type.')}\n`);
           }
+          if (!route || route.type !== 'harness') route = resolveRoute(config, harnesses);
           rl.prompt();
           return;
         }
@@ -637,6 +782,7 @@ async function main() {
             else config.provider = 'anthropic';
             saveConfig(config);
             console.log(`\n  ${teal('●')} ${sage('API key saved. You\'re ready — just type naturally.')}\n`);
+            if (!route || route.type !== 'harness') route = resolveRoute(config, harnesses);
           }
           rl.prompt();
         });
@@ -678,14 +824,73 @@ async function main() {
         return;
       }
 
-      if (cmd === 'provider') {
-        const model = MODELS[currentModel];
-        ui.statusPanel('Provider', [
-          ['API', 'Anthropic (direct)'],
-          ['Model', model.name, 'cyan'],
-          ['Endpoint', 'api.anthropic.com/v1/messages'],
-          ['Key', config?.apiKey ? config.apiKey.slice(0, 8) + '...' : 'not set', config?.apiKey ? 'green' : 'yellow'],
-        ]);
+      if (cmd === 'provider' || cmd === 'route') {
+        const rows = [
+          ['Route', routeLabel(route, config), 'green'],
+        ];
+        for (const h of harnesses) {
+          rows.push([h.label, h.installed ? `installed (${h.auth})` : 'not installed', h.installed ? 'green' : undefined]);
+        }
+        rows.push(['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '... (' + (config.provider || 'anthropic') + ')' : 'not set — optional', config?.apiKey ? 'green' : 'yellow']);
+        if (route?.type === 'api') rows.push(['Model', MODELS[currentModel].name, 'cyan']);
+        ui.statusPanel('Provider', rows);
+        console.log(`  ${slate('switch:')} ${cream('/use <' + harnesses.filter(h => h.installed).map(h => h.id).concat(config?.apiKey ? ['api'] : []).join('|') + '>')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'use') {
+        if (!cmdArg) {
+          console.log(`  ${sage('Current route:')} ${cream(routeLabel(route, config))}`);
+          console.log(`  ${sage('Usage:')} ${cream('/use <claude-code|codex|gemini|cursor|opencode|api>')}`);
+          rl.prompt();
+          return;
+        }
+        const target = cmdArg.trim().toLowerCase();
+        if (target === 'api') {
+          if (!config?.apiKey) {
+            console.log(`  ${ember('!')} ${sage('No API key set — run /key first.')}`);
+          } else {
+            route = { type: 'api' };
+            console.log(`  ${teal('●')} ${sage('Routing via')} ${cream(routeLabel(route, config))}`);
+          }
+        } else if (HARNESSES[target]) {
+          if (!harnesses.find(h => h.id === target)?.installed) {
+            console.log(`  ${ember('!')} ${sage(HARNESSES[target].label + ' is not installed on this machine.')}`);
+          } else {
+            route = { type: 'harness', id: target };
+            console.log(`  ${teal('●')} ${sage('Routing via')} ${cream(routeLabel(route, config))} ${slate('— no API key, your subscription')}`);
+          }
+        } else {
+          console.log(`  ${sage('Unknown route. Options:')} ${cream(Object.keys(HARNESSES).join(', ') + ', api')}`);
+        }
+        console.log(`  ${slate('make it stick across sessions: phewsh setup')}`);
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'harnesses' || cmd === 'agents') {
+        console.log('');
+        console.log(`  ${b(cream('Agent CLIs on this machine'))} ${slate('— each carries its own login, no API key')}`);
+        ui.divider('line');
+        for (const h of harnesses) {
+          const active = route?.type === 'harness' && route.id === h.id ? ` ${teal('● active')}` : '';
+          const status = h.installed ? green('installed') : slate('not installed');
+          console.log(`    ${cream(h.id.padEnd(12))} ${sage(h.label.padEnd(14))} ${status}${active}`);
+        }
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'outcomes') {
+        try {
+          // execSync so the labeling prompt owns stdin while it runs
+          const { execSync } = require('child_process');
+          const outcomesArgs = cmdArg ? ' ' + cmdArg : '';
+          execSync(`node ${path.join(__dirname, '..', 'bin', 'phewsh.js')} outcomes${outcomesArgs}`, { stdio: 'inherit' });
+        } catch { /* user quit mid-labeling — fine */ }
         rl.prompt();
         return;
       }
@@ -759,14 +964,69 @@ async function main() {
         return;
       }
 
+      if (cmd === 'work') {
+        // Real work needs the real harness. Hand the terminal over to an
+        // interactive session, take it back when they exit, ask the outcome.
+        // phewsh stays the front door AND the return point.
+        const target = cmdArg?.trim().toLowerCase() || (route?.type === 'harness' ? route.id : 'claude-code');
+        const h = HARNESSES[target];
+        if (!h) {
+          console.log(`  ${sage('Unknown harness. Options:')} ${cream(Object.keys(HARNESSES).join(', '))}`);
+          rl.prompt();
+          return;
+        }
+        if (!harnesses.find(x => x.id === target)?.installed) {
+          console.log(`  ${ember('!')} ${sage(h.label + ' is not installed on this machine.')}`);
+          rl.prompt();
+          return;
+        }
+        const decisionId = recordDecision({
+          project: projectName,
+          route: target,
+          mode: sessionMode,
+          summary: `interactive ${h.label} session in ${projectName}`,
+        });
+        decisionsThisSession++;
+        console.log('');
+        console.log(`  ${teal('●')} ${sage('Handing the terminal to')} ${cream(h.label)} ${slate('— exit to come back to phewsh')}`);
+        if (fs.existsSync(path.join(process.cwd(), 'CLAUDE.md')) || intentFiles.length > 0) {
+          console.log(`  ${slate('your .intent/ context rides along via CLAUDE.md')}`);
+        }
+        console.log('');
+        rl.pause();
+        const { spawnSync } = require('child_process');
+        const res = spawnSync(h.bin, [], { stdio: 'inherit' });
+        rl.resume();
+        recordSessionEvent(target, projectName, 'task_complete', {
+          taskId: decisionId, success: res.status === 0, summary: `interactive ${h.label} session`,
+        });
+        awaitingOutcome = decisionId;
+        console.log('');
+        console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate('outcome? 1 kept · 2 reverted · 3 superseded · 4 failed · or keep typing')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'run') {
         if (!cmdArg) {
           console.log(`  ${sage('Usage:')} ${cream('/run <prompt>')}`);
           rl.prompt();
           return;
         }
+        if (route?.type === 'harness') {
+          try {
+            await runViaHarness(route.id, systemPrompt, cmdArg);
+            console.log(slate(`  via ${HARNESSES[route.id].label} · one-shot, no history`));
+          } catch (err) {
+            console.error(`\n  ${ember('!')} ${err.message}\n`);
+          }
+          console.log('');
+          rl.prompt();
+          return;
+        }
         if (!config?.apiKey) {
-          console.log(`  ${ember('!')} ${sage('No API key. Run /key to set one.')}`);
+          console.log(`  ${ember('!')} ${sage('No API key and no agent CLI installed. /key or install Claude Code.')}`);
           rl.prompt();
           return;
         }
@@ -803,10 +1063,51 @@ async function main() {
       return;
     }
 
-    // Regular input → send to AI
-    if (!config?.apiKey) {
+    // Regular input → route it (harness = your subscription, api = your key)
+    if (!route) {
       console.log('');
-      console.log(`  ${sage('Type')} ${cream('/key')} ${sage('to set your API key first.')}`);
+      console.log(`  ${sage('No route yet —')} ${cream('/key')} ${sage('to set an API key, or install Claude Code / Codex')}`);
+      console.log(`  ${slate('phewsh uses installed agent CLIs automatically, no key needed.')}`);
+      console.log('');
+      rl.prompt();
+      return;
+    }
+
+    const modeHint = sessionMode
+      ? Object.values(INTENT_MODES).find(m => m.id === sessionMode)?.hint
+      : null;
+    const fullSystem = modeHint ? `${systemPrompt}\n\n${modeHint}` : systemPrompt;
+
+    // Every routed action is a decision — recorded before it runs,
+    // labeled (1-4) when the outcome is known.
+    const decisionId = recordDecision({
+      project: projectName,
+      route: route.type === 'api' ? 'api' : route.id,
+      mode: sessionMode,
+      summary: input,
+    });
+    decisionsThisSession++;
+
+    if (route.type === 'harness') {
+      try {
+        const output = await runViaHarness(route.id, fullSystem, buildHarnessPrompt(messages, input));
+        messages.push({ role: 'user', content: input });
+        messages.push({ role: 'assistant', content: (output || '').trim() });
+        recordSessionEvent(route.id, projectName, 'task_complete', {
+          taskId: decisionId, success: true, summary: input.slice(0, 140),
+        });
+        awaitingOutcome = decisionId;
+        console.log(slate(`  via ${HARNESSES[route.id].label} · outcome? 1 kept · 2 reverted · 3 superseded · 4 failed · or keep typing`));
+      } catch (err) {
+        try { labelOutcome(decisionId, 'failed'); } catch { /* keep going */ }
+        recordSessionEvent(route.id, projectName, 'task_complete', {
+          taskId: decisionId, success: false, summary: input.slice(0, 140),
+        });
+        console.error(`\n  ${ember('!')} ${err.message}`);
+        if (installedHarnesses.length > 1 || config?.apiKey) {
+          console.log(`  ${slate('switch routes with /use — /provider shows what\'s available')}`);
+        }
+      }
       console.log('');
       rl.prompt();
       return;
@@ -816,15 +1117,16 @@ async function main() {
     console.log('');
 
     try {
-      const result = await streamChat(config.apiKey, messages, systemPrompt, MODELS[currentModel].id);
+      const result = await streamChat(config.apiKey, messages, fullSystem, MODELS[currentModel].id);
       messages.push({ role: 'assistant', content: result.content });
 
       if (result.promptTokens) totalPromptTokens += result.promptTokens;
       if (result.completionTokens) totalCompletionTokens += result.completionTokens;
 
       if (result.promptTokens || result.completionTokens) {
-        console.log(slate(`  ${result.promptTokens || '?'}→${result.completionTokens || '?'} tokens · ${MODELS[currentModel].name}`));
+        console.log(slate(`  ${result.promptTokens || '?'}→${result.completionTokens || '?'} tokens · ${MODELS[currentModel].name} · outcome? 1-4 or keep typing`));
       }
+      awaitingOutcome = decisionId;
 
       trackSap({
         userId: config.supabaseUserId,
@@ -835,6 +1137,7 @@ async function main() {
         accessToken: config.supabaseAccessToken,
       });
     } catch (err) {
+      try { labelOutcome(decisionId, 'failed'); } catch { /* keep going */ }
       console.error(`\n  ${err.message}\n`);
       messages.pop();
     }

package/commands/setup.js

@@ -0,0 +1,137 @@
+// phewsh setup — guided setup, hermes-style.
+//
+// Detects what's already on the machine (agent CLIs carry their own login),
+// lets you pick the default route, optionally adds an API key. Ends with one
+// instruction: type `phewsh`.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const ui = require('../lib/ui');
+const { HARNESSES, listHarnesses } = require('../lib/harnesses');
+
+const { b, teal, sage, slate, cream, ember, green } = ui;
+
+const CONFIG_DIR = path.join(os.homedir(), '.phewsh');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+function loadConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); } catch { return {}; }
+}
+
+function saveConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+function ask(rl, prompt) {
+  return new Promise(resolve => rl.question(prompt, a => resolve(a.trim())));
+}
+
+module.exports = async function setup() {
+  const config = loadConfig();
+  const harnesses = listHarnesses();
+  const installed = harnesses.filter(h => h.installed);
+
+  console.log('');
+  console.log(`  ${b(cream('phewsh setup'))}`);
+  ui.divider('line');
+  console.log('');
+  console.log(`  ${sage('phewsh routes your work through tools you already pay for.')}`);
+  console.log(`  ${sage('No API key required — agent CLIs carry their own login.')}`);
+  console.log('');
+
+  // ── 1. What's on this machine ─────────────────────────
+  console.log(`  ${b(cream('Detected on this machine'))}`);
+  for (const h of harnesses) {
+    const status = h.installed ? green('✓ installed') : slate('✗ not installed');
+    console.log(`    ${cream(h.label.padEnd(14))} ${status}  ${slate('(' + h.auth + ')')}`);
+  }
+  if (installed.length === 0) {
+    console.log('');
+    console.log(`  ${ember('!')} ${sage('No agent CLIs found. Install one (recommended) or use an API key:')}`);
+    console.log(`    ${slate('Claude Code:')}  ${cream('npm install -g @anthropic-ai/claude-code')}`);
+    console.log(`    ${slate('Codex CLI:')}    ${cream('npm install -g @openai/codex')}`);
+  }
+  console.log('');
+
+  // Agent-run (no TTY): auto-configure instead of asking questions nobody
+  // can answer. Pick the first installed harness; humans can change it later.
+  if (!process.stdin.isTTY) {
+    if (installed.length > 0) {
+      config.defaultRoute = installed[0].id;
+      saveConfig(config);
+      console.log(`  ${teal('●')} ${sage('Auto-configured (non-interactive): default route =')} ${cream(installed[0].label)} ${slate('— no API key needed')}`);
+      console.log(`  ${slate('Change anytime: run `phewsh setup` in your own terminal, or /use inside a session.')}`);
+    } else if (config.apiKey) {
+      config.defaultRoute = 'api';
+      saveConfig(config);
+      console.log(`  ${teal('●')} ${sage('Auto-configured: default route = API (existing key found)')}`);
+    } else {
+      console.log(`  ${ember('!')} ${sage('Nothing to configure yet — no agent CLI installed and no API key.')}`);
+      console.log(`  ${slate('Install Claude Code or Codex (or set a key), then rerun phewsh setup.')}`);
+    }
+    console.log('');
+    console.log(`  ${sage('Start working:')}  ${cream('phewsh')}`);
+    console.log('');
+    return;
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  // ── 2. Pick the default route ─────────────────────────
+  const options = installed.map(h => ({ kind: 'harness', id: h.id, label: `${h.label} — your ${h.auth.split(' / ')[0].toLowerCase()}, no API key` }));
+  options.push({ kind: 'api', id: 'api', label: 'Direct API — bring your own Anthropic/OpenRouter key' });
+
+  console.log(`  ${b(cream('Where should phewsh route your work by default?'))}`);
+  options.forEach((o, i) => {
+    const current = (config.defaultRoute === o.id) ? ` ${teal('● current')}` : '';
+    console.log(`    ${teal(String(i + 1))} ${sage(o.label)}${current}`);
+  });
+  console.log('');
+
+  const answer = await ask(rl, `  ${teal('>')} ${slate(`1-${options.length}, enter = ${options[0] ? '1' : 'skip'}: `)}`);
+  const idx = answer === '' ? 0 : parseInt(answer, 10) - 1;
+  const choice = options[idx];
+
+  if (!choice) {
+    console.log(`  ${slate('Skipped — phewsh will auto-detect each session.')}`);
+  } else if (choice.kind === 'harness') {
+    config.defaultRoute = choice.id;
+    saveConfig(config);
+    console.log(`  ${teal('●')} ${sage('Default route:')} ${cream(HARNESSES[choice.id].label)} ${slate('— no API key needed')}`);
+  } else {
+    // ── 3. API key, only if they chose the API route ────
+    config.defaultRoute = 'api';
+    if (config.apiKey) {
+      console.log(`  ${teal('●')} ${sage('Default route: API — using your existing key')} ${slate('(' + config.apiKey.slice(0, 8) + '...)')}`);
+      saveConfig(config);
+    } else {
+      console.log('');
+      console.log(`  ${sage('Anthropic:')} ${cream('console.anthropic.com/settings/keys')} ${slate('(sk-ant-...)')}`);
+      console.log(`  ${sage('OpenRouter:')} ${cream('openrouter.ai/keys')} ${slate('(sk-or-...)')}`);
+      const key = await ask(rl, `  ${sage('Paste your API key (enter to skip):')}\n  ${teal('>')} `);
+      if (key) {
+        config.apiKey = key;
+        config.provider = key.startsWith('sk-or-') ? 'openrouter' : 'anthropic';
+        console.log(`  ${teal('●')} ${sage('Key saved.')}`);
+      } else {
+        delete config.defaultRoute;
+        console.log(`  ${slate('No key — phewsh will fall back to any installed agent CLI.')}`);
+      }
+      saveConfig(config);
+    }
+  }
+
+  rl.close();
+
+  // ── 4. Done ───────────────────────────────────────────
+  console.log('');
+  ui.divider('line');
+  console.log(`  ${teal('●')} ${b(cream('Setup complete.'))}`);
+  console.log('');
+  console.log(`  ${sage('Start working:')}  ${cream('phewsh')}`);
+  console.log(`  ${slate('Optional: phewsh login (cloud sync) · phewsh intent --init (.intent/ for a project)')}`);
+  console.log('');
+};

package/lib/harnesses.js

@@ -40,6 +40,7 @@ function listHarnesses() {
 /**
  * Run a prompt through a harness, streaming stdout to the terminal.
  * stderr is buffered and only surfaced on failure (codex/gemini chat on it).
+ * Resolves with the full stdout text so callers can keep conversation history.
  */
 function runViaHarness(id, systemPrompt, userPrompt) {
   const h = HARNESSES[id];
@@ -51,13 +52,14 @@ function runViaHarness(id, systemPrompt, userPrompt) {
     // Some harnesses (codex exec, gemini) wait for stdin EOF before running.
     child.stdin.end();
 
+    let stdout = '';
     let stderr = '';
     process.stdout.write('\n');
-    child.stdout.on('data', (d) => process.stdout.write(d));
+    child.stdout.on('data', (d) => { process.stdout.write(d); stdout += d.toString(); });
     child.stderr.on('data', (d) => { stderr += d.toString(); });
     child.on('close', (code) => {
       process.stdout.write('\n');
-      if (code === 0) resolve();
+      if (code === 0) resolve(stdout);
       else reject(new Error(`${h.label} exited ${code}${stderr ? `\n  ${stderr.trim().split('\n').slice(-3).join('\n  ')}` : ''}`));
     });
     child.on('error', (e) => reject(new Error(`Could not run ${h.bin}: ${e.message}`)));

package/lib/outcomes.js

@@ -0,0 +1,159 @@
+// Outcome-labeled decision history — the dataset PHEWSH accumulates that
+// platform chat logs don't: not just "I did X" but "X was kept / reverted /
+// superseded / failed."
+//
+// Every routed action in a phewsh session records a decision (pending).
+// The user labels it when the outcome is actually known — seconds later or
+// three weeks later. `phewsh outcomes` shows what accumulates.
+//
+// Storage: ~/.phewsh/outcomes/decisions.json (append-only, never capped —
+// this file IS the asset).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const OUTCOMES_DIR = path.join(os.homedir(), '.phewsh', 'outcomes');
+const DECISIONS_FILE = path.join(OUTCOMES_DIR, 'decisions.json');
+
+const OUTCOMES = ['kept', 'reverted', 'superseded', 'failed'];
+
+function load() {
+  try { return JSON.parse(fs.readFileSync(DECISIONS_FILE, 'utf-8')); } catch { return []; }
+}
+
+function save(decisions) {
+  fs.mkdirSync(OUTCOMES_DIR, { recursive: true });
+  fs.writeFileSync(DECISIONS_FILE, JSON.stringify(decisions, null, 2));
+}
+
+/** Record a routed action as a pending decision. Returns the decision id. */
+function recordDecision({ project, route, mode, summary }) {
+  const decisions = load();
+  // Short enough to display whole and retype: 5 timestamp chars + 3 random
+  const id = 'd' + Date.now().toString(36).slice(-5) + Math.random().toString(36).slice(2, 5);
+  decisions.push({
+    id,
+    ts: new Date().toISOString(),
+    project: project || path.basename(process.cwd()),
+    route: route || 'unknown',
+    mode: mode || null,
+    summary: (summary || '').slice(0, 200),
+    outcome: null,
+    labeledAt: null,
+  });
+  save(decisions);
+  return id;
+}
+
+/** Label a decision by id (or unambiguous id prefix). Returns the decision or null. */
+function labelOutcome(idOrPrefix, outcome) {
+  if (!OUTCOMES.includes(outcome)) {
+    throw new Error(`Outcome must be one of: ${OUTCOMES.join(', ')}`);
+  }
+  const decisions = load();
+  const matches = decisions.filter(d => d.id === idOrPrefix || d.id.startsWith(idOrPrefix));
+  if (matches.length !== 1) return null;
+  matches[0].outcome = outcome;
+  matches[0].labeledAt = new Date().toISOString();
+  save(decisions);
+  return matches[0];
+}
+
+/** Unlabeled decisions, oldest first. */
+function pendingDecisions({ project = null } = {}) {
+  return load()
+    .filter(d => !d.outcome && (!project || d.project === project))
+    .sort((a, b) => a.ts.localeCompare(b.ts));
+}
+
+/** Most recent decisions (labeled or not), newest first. */
+function recentDecisions(limit = 10, { project = null } = {}) {
+  return load()
+    .filter(d => !project || d.project === project)
+    .sort((a, b) => b.ts.localeCompare(a.ts))
+    .slice(0, limit);
+}
+
+/**
+ * The Day-14 view: totals, per-route reliability, per-mode patterns.
+ * Only labeled decisions count toward outcome rates — pending is honest noise.
+ */
+function outcomeStats({ project = null } = {}) {
+  const all = load().filter(d => !project || d.project === project);
+  const labeled = all.filter(d => d.outcome);
+
+  const stats = {
+    total: all.length,
+    pending: all.length - labeled.length,
+    kept: 0, reverted: 0, superseded: 0, failed: 0,
+    byRoute: {},
+    byMode: {},
+  };
+
+  for (const d of labeled) {
+    stats[d.outcome]++;
+    const r = (stats.byRoute[d.route] ||= { total: 0, kept: 0, reverted: 0, superseded: 0, failed: 0 });
+    r.total++; r[d.outcome]++;
+    if (d.mode) {
+      const m = (stats.byMode[d.mode] ||= { total: 0, kept: 0, reverted: 0, superseded: 0, failed: 0 });
+      m.total++; m[d.outcome]++;
+    }
+  }
+
+  return stats;
+}
+
+// ── Bypasses — the failure dataset ─────────────────────────────────────────
+// Every time the user opens Claude Code (or anything) directly instead of
+// phewsh, the reason why is the most valuable thing they can record. It
+// directly identifies why the front door fails.
+
+const BYPASSES_FILE = path.join(OUTCOMES_DIR, 'bypasses.json');
+
+const BYPASS_REASONS = [
+  'forgot',
+  'faster',
+  'needed-editing',
+  'needed-context',
+  'model-quality',
+  'phewsh-in-the-way',
+  'other',
+];
+
+function loadBypasses() {
+  try { return JSON.parse(fs.readFileSync(BYPASSES_FILE, 'utf-8')); } catch { return []; }
+}
+
+function recordBypass(reason, note = '') {
+  if (!BYPASS_REASONS.includes(reason)) {
+    throw new Error(`Reason must be one of: ${BYPASS_REASONS.join(', ')}`);
+  }
+  const bypasses = loadBypasses();
+  bypasses.push({
+    ts: new Date().toISOString(),
+    project: path.basename(process.cwd()),
+    reason,
+    note: note.slice(0, 200),
+  });
+  fs.mkdirSync(OUTCOMES_DIR, { recursive: true });
+  fs.writeFileSync(BYPASSES_FILE, JSON.stringify(bypasses, null, 2));
+  return bypasses.length;
+}
+
+function bypassStats() {
+  const bypasses = loadBypasses();
+  const byReason = {};
+  for (const b of bypasses) byReason[b.reason] = (byReason[b.reason] || 0) + 1;
+  return {
+    total: bypasses.length,
+    byReason,
+    recent: bypasses.slice(-8).reverse(),
+  };
+}
+
+module.exports = {
+  OUTCOMES, DECISIONS_FILE, BYPASS_REASONS, BYPASSES_FILE,
+  recordDecision, labelOutcome, pendingDecisions, recentDecisions, outcomeStats,
+  recordBypass, bypassStats,
+};

package/package.json

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