phewsh 0.15.29 → 0.15.31

package/bin/phewsh.js

@@ -66,6 +66,8 @@ const COMMANDS = {
   mcp:     () => require('../commands/mcp')(),
   receipts: () => require('../commands/receipts')(),
   outcomes: () => require('../commands/outcomes')(),
+  truth:   () => require('../commands/truth'),
+  brief:   () => require('../commands/brief'),
   bypass:  () => require('../commands/bypass')(),
   setup:   () => require('../commands/setup')(),
   update:  () => require('../commands/update')(),
@@ -99,6 +101,8 @@ function showHelp() {
   console.log(`    ${cyan('intent')}     ${g('Create, view, evolve .intent/ artifacts')}`);
   console.log(`    ${cyan('gate')}       ${g('Set constraints (budget, time, skill, urgency)')}`);
   console.log(`    ${cyan('context')}    ${g('Export .intent/ for any AI tool')}`);
+  console.log(`    ${cyan('truth')}      ${g('Read-only audit: versions, Git, intent, projections, conflicts')}`);
+  console.log(`    ${cyan('brief')}      ${g('Provider-ready briefing built from verified project truth')}`);
   console.log(`    ${cyan('ai')}         ${g('One-shot prompt with .intent/ context')}
     ${cyan('browse')}     ${g('Read any URL — AI summary in your terminal')}`);
   console.log('');
@@ -185,6 +189,12 @@ if (!command) {
   exitAfterUpdate(0);
 } else if (COMMANDS[command]) {
   COMMANDS[command]();
+} else if (require('../lib/harnesses').HARNESSES[command]) {
+  // `phewsh <harness>` — a doorway shortcut. Launch the session and have it
+  // auto-run /work for that harness (preflight → brief → native handoff →
+  // postflight). This is what the phewsh.com doorways copy as a single command.
+  process.env.PHEWSH_AUTOWORK = command;
+  maybeFirstRunIntro().then(() => COMMANDS.session());
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run 'phewsh help' for available commands.\n`);
   process.exit(1);

package/commands/brief.js

@@ -0,0 +1,13 @@
+const { generateBrief } = require('../lib/brief');
+
+async function main() {
+  const { content } = await generateBrief();
+  console.log(`\n${content}\n`);
+}
+
+module.exports = { main };
+
+main().catch(err => {
+  console.error(`\nBrief unavailable: ${err.message}\n`);
+  process.exitCode = 1;
+});

package/commands/outcomes.js

@@ -170,8 +170,21 @@ function labelInteractive() {
       }
       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])}`);
+        const outcome = OUTCOMES[idx - 1];
+        // A miss is only useful if phewsh learns WHY — that one line is what
+        // /recall surfaces before you repeat it. Match the inline flow.
+        if (outcome === 'reverted' || outcome === 'failed') {
+          console.log(`  ${teal('●')} ${OUTCOME_COLOR[outcome](outcome)}`);
+          rl.question(`  ${slate('why? (one line — Enter to skip)')} ${teal('>')} `, (why) => {
+            labelOutcome(d.id, outcome, why.trim() || null);
+            if (why.trim()) console.log(`  ${slate('noted — /recall will remember why.')}`);
+            i++;
+            next();
+          });
+          return;
+        }
+        labelOutcome(d.id, outcome);
+        console.log(`  ${teal('●')} ${OUTCOME_COLOR[outcome](outcome)}`);
       }
       i++;
       next();

package/commands/session.js

@@ -17,17 +17,30 @@ const intentDir = () => 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, cancelActive } = require('../lib/harnesses');
+const { HARNESSES, interactiveLaunchArgs, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
 const { recordDecision, labelOutcome, pendingDecisions, recentDecisions, outcomeStats, OUTCOMES } = require('../lib/outcomes');
 const { suggest, suggestAll } = require('../lib/suggest');
 const continuity = require('../lib/continuity');
 const selfheal = require('../lib/selfheal');
 const learning = require('../lib/learning');
 const recall = require('../lib/recall');
+const { routeCoach } = require('../lib/route-coach');
 const { closest } = require('../lib/closest');
 const cmdHistory = require('../lib/history');
 const { recordSessionEvent } = require('../lib/receipts-data');
 const configFile = require('../lib/config-file');
+const { loadIntentContext } = require('../lib/intent-context');
+const { auditTruth, formatTruth, quickVerifiedState } = require('../lib/truth');
+const { generateBrief, persistBrief } = require('../lib/brief');
+const {
+  applyReconciliation,
+  captureSnapshot,
+  createPostflight,
+  formatObservedReport,
+  observeCurrent,
+  reconciliationProposal,
+} = require('../lib/lifecycle');
+const { formatSourceContract } = require('../lib/source-contract');
 const { createFailureTracker, createLineDispatcher } = require('../lib/session-input');
 const {
   echoedRows,
@@ -168,24 +181,42 @@ const INTENT_MODES = {
   4: { id: 'review',   label: 'Review',   hint: 'The user wants critical review. Find what is wrong or risky before praising anything. Be specific about severity.' },
 };
 
+const BARE_COMMANDS = {
+  help: '/help',
+  h: '/help',
+  next: '/next',
+  guide: '/next',
+  recommend: '/next',
+  tools: '/harnesses',
+  tool: '/harnesses',
+  agents: '/harnesses',
+  harnesses: '/harnesses',
+  routes: '/provider',
+  route: '/provider',
+  provider: '/provider',
+  status: '/status',
+  truth: '/truth',
+  brief: '/brief',
+  thread: '/thread',
+  outcomes: '/outcomes',
+  clarify: '/clarify',
+  setup: '/setup',
+  work: '/work',
+  quit: '/quit',
+  exit: '/quit',
+};
+
 function loadConfig() {
   return configFile.loadConfig(CONFIG_PATH);
 }
 
 function saveConfig(config) {
-  configFile.saveConfig(CONFIG_PATH, config);
-}
-
-function loadIntentContext() {
-  const files = ['vision.md', 'plan.md', 'next.md'];
-  const loaded = [];
-  for (const file of files) {
-    const p = path.join(intentDir(), file);
-    if (fs.existsSync(p)) {
-      loaded.push({ file, content: fs.readFileSync(p, 'utf-8') });
-    }
+  try {
+    configFile.saveConfig(CONFIG_PATH, config);
+    return true;
+  } catch {
+    return false;
   }
-  return loaded;
 }
 
 function buildSystemPrompt(intentFiles) {
@@ -195,8 +226,8 @@ function buildSystemPrompt(intentFiles) {
     return base + `\n\nNo .intent/ artifacts found in the current directory. The user hasn't set up project context yet — help them think through what they're building if they ask.`;
   }
 
-  const sections = intentFiles.map(({ file, content }) =>
-    `## ${file}\n\n${content.trim()}`
+  const sections = intentFiles.map(({ file, promptContent, content }) =>
+    `## ${file}\n\n${(promptContent || content).trim()}`
   ).join('\n\n---\n\n');
 
   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}`;
@@ -336,16 +367,41 @@ async function main() {
   let sessionMode = null;          // INTENT_MODES id once picked
   let awaitingOutcome = null;      // decision id eligible for 1-4 labeling
   let awaitingWhy = null;          // { id, outcome } — next line is the reason
-  let awaitingWrap = null;         // { block } — y/N to fold shipped work into next.md
+  let awaitingReconcile = null;    // exact proposed append, applied only after y
+  let lastTransitionReport = null; // latest native preflight -> postflight comparison
   let awaitingFallback = null;     // { input, fullSystem, options } after a route failure
   let bootstrapChoices = null;     // root-bootstrap menu entries when no project here
   let nextChoices = null;          // ranked /next suggestions awaiting a numeric pick
   let pendingDidYouMean = null;    // a suggested command; bare Enter accepts + runs it
   let decisionsThisSession = 0;
+  let lastRouteCoachId = null;     // avoid repeating the same best-door hint
 
   // ── The Exhale: animated brand reveal ──────────────────
   await ui.brandReveal();
 
+  // Self-aware, plain-language summary — the value prop made real with THIS
+  // machine's state. Non-technical readers get one warm sentence; the rows
+  // below give engineers the exact facts. Fail-soft: a missing piece just
+  // shortens the line, it never blocks the door.
+  (function narrativeSummary() {
+    try {
+      const toolCount = harnesses.filter(h => h.installed).length;
+      const hasProject = intentFiles.length > 0;
+      const dot = teal('●');
+      const tools = `${toolCount} AI tool${toolCount !== 1 ? 's' : ''}`;
+      if (hasProject && toolCount > 0) {
+        console.log(`  ${dot} ${sage(`${tools} here, all sharing one memory of`)} ${cream(projectName)}${sage(' — so you never start this project over.')}`);
+      } else if (hasProject) {
+        console.log(`  ${dot} ${sage('phewsh holds one verified memory of')} ${cream(projectName)} ${sage('— ready for whatever AI tool you bring.')}`);
+      } else if (toolCount > 0) {
+        console.log(`  ${dot} ${sage(`${tools} here.`)} ${sage('Run')} ${cream('/init')} ${sage('and they all work from one shared project memory.')}`);
+      } else {
+        console.log(`  ${dot} ${sage('Install Claude Code, Codex, or Gemini — phewsh keeps them all on the same page.')}`);
+      }
+      console.log('');
+    } catch { /* the summary is a flourish, never a blocker */ }
+  })();
+
   if (config?.apiKey && !config.apiKey.startsWith('sk-')) {
     // Persist the cleanup so this never nags again — an unusable key
     // (not sk-…) helps nobody, and harness routes need no key at all.
@@ -437,6 +493,20 @@ async function main() {
     row('WEB', sage('local-only (works fine)') + slate(' · /login mirrors this at phewsh.com/intent'));
   }
 
+  // VERIFIED — the product thesis made visible: what's actually true in this
+  // repo right now, checked (not remembered). Fast + offline + fail-soft.
+  try {
+    const v = quickVerifiedState();
+    if (!v.available) {
+      row('VERIFIED', slate('not a git repo here — ') + sage('/truth') + slate(' audits whatever is present'));
+    } else {
+      const parts = [cream('HEAD ' + v.shortHead)];
+      parts.push(v.dirtyCount ? peach(`${v.dirtyCount} uncommitted`) : sage('clean'));
+      if (v.driftCommits > 0) parts.push(ember(`⚠ ${v.driftCommits} commit${v.driftCommits !== 1 ? 's' : ''} since .intent updated`));
+      row('VERIFIED', parts.join(slate(' · ')) + slate('  — /truth · /brief'));
+    }
+  } catch { /* the verified row is a glance, never a blocker */ }
+
   const oStats = outcomeStats();
   if (oStats.total > 0) {
     // Plain language: what phewsh has logged vs what you've taught it. The
@@ -543,13 +613,30 @@ async function main() {
   }
 
   // One subtle line under the menu — the single highest-leverage nudge, if any.
-  function showInlineTip() {
+  function showInlineTip(filter = null) {
     let tip = null;
     try { tip = suggest(buildSuggestState()); } catch { /* never block the prompt on guidance */ }
     if (!tip) return;
+    if (filter && !filter(tip)) return;
     console.log(`  ${teal('⤷')} ${sage(tip.message)} ${cream(tip.command.trim())} ${slate('· /next for options')}`);
   }
 
+  // The front door should steer, not trap. For a plain-language ask, point to
+  // the better native door when the pattern is obvious, then still run the turn.
+  function showRouteCoach(input) {
+    try {
+      const advice = routeCoach(input, {
+        route,
+        harnesses,
+        hasIntentDir: intentFiles.length > 0,
+        turnsThisSession: Math.floor(messages.length / 2),
+      });
+      if (!advice || advice.id === lastRouteCoachId) return;
+      lastRouteCoachId = advice.id;
+      console.log(`  ${peach('↪')} ${sage(advice.message)} ${cream(advice.command)} ${slate('· still sending this turn')}`);
+    } catch { /* route coaching is advisory, never a blocker */ }
+  }
+
   // Open a known project from the bootstrap menu: chdir, reload memory,
   // back to the normal flow. The session is the cockpit; projects swap in.
   function openProjectAt(dir) {
@@ -649,6 +736,7 @@ async function main() {
       lastTurnFailure = null;
       awaitingOutcome = decisionId;
       console.log(slate(`  via ${HARNESSES[harnessId].label} · how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · or keep typing`));
+      showInlineTip((tip) => tip.id === 'capture-intent');
       return true;
     } catch (err) {
       turnInFlight = false;
@@ -699,6 +787,7 @@ async function main() {
         completionTokens: result.completionTokens,
         accessToken: config.supabaseAccessToken,
       });
+      showInlineTip((tip) => tip.id === 'capture-intent');
       return true;
     } catch (err) {
       turnInFlight = false;
@@ -816,10 +905,10 @@ async function main() {
   // so you know it registered. Arguments stay plain. TTY-only, fail-soft.
   const KNOWN_COMMANDS = new Set([
     'quit', 'exit', 'q', 'help', 'h', 'init', 'intent', 'clarify', 'model',
-    'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'run',
+    'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'switch', 'run',
     'clear', 'status', 'key', 'login', 'export', 'push', 'pull', 'serve',
     'sync', 'harnesses', 'fallback', 'outcomes', 'tour', 'update', 'upgrade',
-    'agents', 'context', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
+    'agents', 'context', 'truth', 'brief', 'wrap', 'reconcile', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
     'next', 'recommend', 'guide', 'thread', 'continuity', 'learn', 'stats',
   ]);
   const installedIds = harnesses.filter(h => h.installed).map(h => h.id);
@@ -994,19 +1083,23 @@ async function main() {
       return;
     }
 
-    // /wrap confirmation: y folds the shipped-work block into next.md + heals.
-    if (awaitingWrap) {
-      const { block } = awaitingWrap;
-      awaitingWrap = null;
+    // /reconcile confirmation: apply only the exact diff the user just saw.
+    if (awaitingReconcile) {
+      const proposal = awaitingReconcile;
+      awaitingReconcile = null;
       if (/^(y|yes)$/i.test(input.trim())) {
-        const r = selfheal.appendToNext(block);
+        const r = applyReconciliation(proposal);
         if (r.written) {
-          console.log(`  ${green('✓')} ${sage('Folded into .intent/' + r.file + ' — CLAUDE.md synced too. The record matches the work now.')}`);
+          const healed = selfheal.heal({ force: true });
+          intentFiles = loadIntentContext();
+          systemPrompt = buildSystemPrompt(intentFiles);
+          console.log(`  ${green('✓')} ${sage('Applied the approved diff to ' + r.target + '.')}`);
+          console.log(`  ${slate(healed.healed ? 'Generated Claude context refreshed from the approved intent change.' : 'Intent updated; generated context did not require a write.')}`);
         } else {
-          console.log(`  ${ember('!')} ${sage('Could not write .intent/next.md — left it untouched.')}`);
+          console.log(`  ${ember('!')} ${sage('Reconciliation was not applied: ' + r.reason)}`);
         }
       } else {
-        console.log(`  ${slate('Left .intent/ as-is.')}`);
+        console.log(`  ${slate('No authoritative files were changed.')}`);
       }
       console.log('');
       rl.prompt();
@@ -1016,6 +1109,16 @@ async function main() {
     // Any typed input supersedes a pending "did you mean" offer.
     if (pendingDidYouMean) pendingDidYouMean = null;
 
+    // Exact bare words are front-door controls too. Keep this exact-match only:
+    // "help" opens help; "help me build X" still routes as natural language.
+    if (!input.startsWith('/')) {
+      const bare = input.trim().toLowerCase();
+      if (BARE_COMMANDS[bare]) {
+        await handleInput(BARE_COMMANDS[bare]);
+        return;
+      }
+    }
+
     // A bare number right after a route failure picks the fallback
     if (awaitingFallback) {
       const af = awaitingFallback;
@@ -1267,33 +1370,34 @@ async function main() {
         return;
       }
 
-      // ── /wrap ──────────────────────────────────────────
-      // Fold what you've shipped (git commits since .intent/ was last updated)
-      // back into next.md, then re-sync CLAUDE.md — so the record reflects the
-      // work, not last week. Deterministic from commit subjects; no LLM needed,
-      // so it works even with nothing connected. This is the cure for the drift
-      // that ate phewsh's own dogfood.
+      // ── /wrap + /reconcile ─────────────────────────────
+      // Wrap observes. Reconcile proposes. Only an explicit yes writes intent.
       if (cmd === 'wrap') {
-        const draft = selfheal.wrapDraft();
         console.log('');
-        if (!draft) {
-          console.log(`  ${teal('●')} ${sage('Nothing to fold in — your .intent/ is already current with git (or this isn\'t a repo).')}`);
+        const truth = await auditTruth();
+        const observed = observeCurrent(truth);
+        lastTransitionReport = observed;
+        console.log(formatObservedReport(observed, { title: 'Wrap — observed current state' }));
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'reconcile') {
+        console.log('');
+        const report = lastTransitionReport || observeCurrent(await auditTruth());
+        const proposal = reconciliationProposal(report);
+        if (!proposal.available) {
+          console.log(`  ${ember('!')} ${sage('No reconciliation proposal: ' + proposal.reason)}`);
           console.log('');
           rl.prompt();
           return;
         }
-        const n = draft.commits.length;
-        console.log(`  ${b(cream('Wrap'))} ${slate('— ' + n + ' commit' + (n !== 1 ? 's' : '') + ' shipped since .intent/ was last updated')}`);
-        ui.divider('line');
-        for (const s of draft.commits.slice(0, 12)) {
-          let line = s.replace(/\s+/g, ' ');
-          if (line.length > 70) line = line.slice(0, 69).trimEnd() + '…';
-          console.log(`    ${sage('+')} ${cream(line)}`);
-        }
-        if (n > 12) console.log(`    ${slate('… and ' + (n - 12) + ' more')}`);
-        ui.divider('line');
-        console.log(`  ${sage('Fold this into')} ${cream('.intent/next.md')} ${sage('and re-sync CLAUDE.md?')} ${slate('y/N')}`);
-        awaitingWrap = { block: draft.block };
+        console.log('Reconciliation proposal (no files changed):');
+        console.log(proposal.diff);
+        console.log('');
+        console.log(`  ${sage('Apply this exact diff?')} ${slate('y/N')}`);
+        awaitingReconcile = proposal;
         rl.prompt();
         return;
       }
@@ -1372,7 +1476,10 @@ async function main() {
         console.log(`  ${cream('author .intent/')}`);
         console.log(`    ${teal('/init')}        ${sage('Create .intent/ for this project')}`);
         console.log(`    ${teal('/intent')}      ${sage('Pause and reflect — view or update .intent/ before moving on')}`);
-        console.log(`    ${teal('/wrap')}        ${sage('Fold what you shipped (git) into .intent/ — keeps the record current')}`);
+        console.log(`    ${teal('/truth')}       ${sage('Read-only audit of versions, Git, intent, projections, and conflicts')}`);
+        console.log(`    ${teal('/brief')}       ${sage('Generate the current provider-ready verified briefing')}`);
+        console.log(`    ${teal('/wrap')}        ${sage('Observe changes, contradictions, unknowns, and reconciliation needs')}`);
+        console.log(`    ${teal('/reconcile')}   ${sage('Propose an exact intent diff; writes only after approval')}`);
         console.log(`    ${teal('/clarify')}     ${sage('Turn ideas into .intent/ artifacts')}`);
         console.log(`    ${teal('/gate')}        ${sage('Set constraints (budget, time, skill)')}`);
         console.log(`    ${teal('/context')}     ${sage('Show loaded .intent/ files')}`);
@@ -1398,7 +1505,8 @@ async function main() {
         console.log(`    ${teal('/outcomes')}    ${sage('What worked — tell phewsh, and it learns which tool to trust')}`);
         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('/work')} ${slate('[harness]')} ${sage('Preflight, brief, native handoff, automatic postflight')}`);
+        console.log(`    ${teal('/switch')} ${slate('<harness>')} ${sage('Launch another native tool with a freshly verified briefing')}`);
         console.log(`    ${teal('/run')} ${slate('<prompt>')} ${sage('One-shot prompt (no history)')}`);
         console.log(`    ${teal('esc')}          ${sage('Cancel a running turn · clear the input line')}`);
         console.log(`    ${teal('/clear')}       ${sage('Clear conversation')}`);
@@ -1454,6 +1562,7 @@ async function main() {
           ui.divider('line');
           intentFiles.forEach(f => console.log(`    ${teal('●')} ${cream(f.file)} ${slate('(' + f.content.length + ' chars)')}`));
           ui.divider('line');
+          console.log(formatSourceContract({ compact: true }).split('\n').map(line => `  ${line}`).join('\n'));
         } else {
           console.log(`\n  ${sage('No .intent/ context found in')} ${slate(process.cwd())}`);
           console.log(`  ${sage('Run')} ${cream('/init')} ${sage('to create one')}`);
@@ -1463,6 +1572,23 @@ async function main() {
         return;
       }
 
+      if (cmd === 'truth') {
+        console.log('');
+        console.log(formatTruth(await auditTruth()));
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'brief') {
+        console.log('');
+        const { content } = await generateBrief();
+        console.log(content);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'status') {
         const turns = messages.length / 2;
         config = loadConfig();
@@ -1518,15 +1644,14 @@ async function main() {
       }
 
       if (cmd === 'clarify') {
-        if (!config?.apiKey) {
-          console.log(`\n  ${ember('!')} ${sage('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' });
+          const { spawnSync } = require('child_process');
+          const args = ['clarify'];
+          if (cmdArg) args.push('--text', cmdArg);
+          const res = spawnSync(process.execPath, [path.join(__dirname, '..', 'bin', 'phewsh.js'), ...args], { stdio: 'inherit' });
+          if (res.status !== 0) {
+            console.error(`  ${ember('!')} ${sage('Clarify exited without writing context.')}`);
+          }
           intentFiles = loadIntentContext();
           systemPrompt = buildSystemPrompt(intentFiles);
           if (intentFiles.length > 0) {
@@ -2045,7 +2170,7 @@ async function main() {
           }
           if (!h.installed) continue; // hide the long tail of uninstalled extras
           const via = h.headless ? '' : ' · /work only';
-          rows.push([h.label, `ready — ${h.role}${via}`, 'green']);
+          rows.push([h.label, `ready — ${h.bestFor || h.role}${via}`, 'green']);
         }
         rows.push(['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '... (' + (config.provider || 'anthropic') + ')' : 'not set — optional', config?.apiKey ? 'green' : 'yellow']);
         rows.push(['Fallback', (config?.fallback === 'auto' ? 'auto-switch on failure' : 'ask before switching') + ' — /fallback to change', 'peach']);
@@ -2137,7 +2262,7 @@ async function main() {
           const mode = h.headless ? '' : slate(' · /work only');
           const badge = hStats ? learning.keptBadge(hStats, h.id) : '';
           const rec = badge ? ` ${slate('· ' + badge)}` : '';
-          console.log(`    ${dot} ${cream(h.id.padEnd(11))} ${sage((h.role || h.label).padEnd(20))} ${slate(h.label)}${mode}${rec}${active}`);
+          console.log(`    ${dot} ${cream(h.id.padEnd(11))} ${sage((h.bestFor || h.role || h.label).padEnd(38))} ${slate(h.label)}${mode}${rec}${active}`);
         }
         ui.divider('line');
         const learned = hStats ? learning.learningLine(hStats) : null;
@@ -2231,10 +2356,9 @@ 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.
+      if (cmd === 'work' || cmd === 'switch') {
+        // Native handoff lifecycle: verify -> brief -> release the terminal ->
+        // observe -> reconcile. The harness owns its UI while it runs.
         const target = cmdArg?.trim().toLowerCase() || (route?.type === 'harness' ? route.id : 'claude-code');
         const h = HARNESSES[target];
         if (!h) {
@@ -2247,6 +2371,13 @@ async function main() {
           rl.prompt();
           return;
         }
+
+        const preflightTruth = await auditTruth();
+        const before = captureSnapshot(preflightTruth);
+        const generatedBrief = await generateBrief({ report: preflightTruth });
+        const launchBrief = `${generatedBrief.content}\n\nThis is a PHEWSH transition briefing. Use it as project context, preserve native tool behavior, and verify claims against the repository before acting. When you finish, exit this tool — PHEWSH resumes, runs an automatic postflight comparing what changed against this brief, and offers reconciliation.`;
+        const savedBrief = persistBrief(generatedBrief.content, { project: projectName, route: target });
+        const launch = interactiveLaunchArgs(target, launchBrief, { model: harnessModel });
         const decisionId = recordDecision({
           project: projectName,
           route: target,
@@ -2255,23 +2386,49 @@ async function main() {
         });
         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(`  ${b(cream('Work preflight'))} ${slate('— verified before native handoff')}`);
+        ui.divider('line');
+        console.log(`  ${sage('Route:')} ${cream(h.label)}${harnessModel ? slate(' · model ' + harnessModel) : slate(' · native default model')}`);
+        console.log(`  ${sage('Git:')} ${cream(preflightTruth.git.shortHead || 'unknown')} ${slate('· ' + before.dirty.length + ' uncommitted path(s) before work')}`);
+        console.log(`  ${sage('Truth:')} ${preflightTruth.conflicts.length ? peach(preflightTruth.conflicts.length + ' conflict(s) carried explicitly') : green('no explicit conflicts')}`);
+        console.log(`  ${sage('Brief:')} ${launch.briefingPassed ? green('passed directly to the native harness') : peach('not injectable for this harness; available via /brief')}`);
+        console.log(`  ${sage('Record:')} ${savedBrief.written ? slate('exact briefing saved locally for this transition') : peach('briefing persistence unavailable; launch continues')}`);
+        console.log(`  ${slate('After exit PHEWSH will compare Git, files, intent claims, generated drift, and contradictions.')}`);
+        ui.divider('line');
+        console.log(`  ${teal('●')} ${sage('Handing the terminal to')} ${cream(h.label)} ${slate('— exit to return for postflight')}`);
         console.log('');
+        recordSessionEvent(target, projectName, 'work_started', {
+          taskId: decisionId,
+          summary: `interactive ${h.label} session`,
+          gitHead: before.head,
+          dirtyPaths: before.dirty,
+          briefingHash: savedBrief.hash,
+          briefingFile: savedBrief.file,
+          briefingPassed: launch.briefingPassed,
+        });
         pasteMode(false);
         rl.pause();
         const { spawnSync } = require('child_process');
-        const res = spawnSync(h.bin, [], { stdio: 'inherit' });
+        const res = spawnSync(h.bin, launch.args, { stdio: 'inherit' });
         rl.resume();
         pasteMode(true);
+        const postflight = await createPostflight(before);
+        lastTransitionReport = postflight;
         recordSessionEvent(target, projectName, 'task_complete', {
-          taskId: decisionId, success: res.status === 0, summary: `interactive ${h.label} session`,
+          taskId: decisionId,
+          success: res.status === 0,
+          summary: `interactive ${h.label} session`,
+          gitHeadBefore: before.head,
+          gitHeadAfter: postflight.afterHead,
+          changedFiles: postflight.files,
+          conflicts: postflight.conflicts,
+          briefingHash: savedBrief.hash,
         });
         awaitingOutcome = decisionId;
         console.log('');
-        console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate("how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · or keep typing")}`);
+        console.log(formatObservedReport(postflight, { title: `${h.label} session ended — postflight` }));
+        console.log('');
+        console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate("1 kept · 2 undid · 3 redid · 4 flopped · /reconcile · /switch <tool>")}`);
         console.log('');
         rl.prompt();
         return;
@@ -2341,8 +2498,10 @@ async function main() {
     // Regular input → route it (harness = your subscription, api = your key)
     if (!route) {
       console.log('');
-      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(`  ${sage('That request is valid — phewsh just needs an AI worker behind the door.')}`);
+      console.log(`  ${cream('phewsh setup')} ${sage('detects installed tools and picks a route')}`);
+      console.log(`  ${cream('/key')} ${sage('adds an API key, or install Claude Code / Codex / Gemini and rerun phewsh')}`);
+      console.log(`  ${slate('Once a route exists, plain typing works; no slash command needed.')}`);
       console.log('');
       rl.prompt();
       return;
@@ -2373,6 +2532,8 @@ async function main() {
       return;
     }
 
+    showRouteCoach(input);
+
     const ok = route.type === 'harness'
       ? await runHarnessTurn(input, route.id, fullSystem)
       : await runApiTurn(input, fullSystem);
@@ -2411,6 +2572,14 @@ async function main() {
     console.log(`\n  ${sage('session ended')}\n`);
     process.exit(0);
   });
+
+  // Doorway shortcut: `phewsh <harness>` sets PHEWSH_AUTOWORK so we drop the
+  // user straight into /work for that tool after the front door renders.
+  const autoWork = process.env.PHEWSH_AUTOWORK;
+  if (autoWork && HARNESSES[autoWork]) {
+    delete process.env.PHEWSH_AUTOWORK;
+    handleInput('/work ' + autoWork).catch(() => {});
+  }
 }
 
 main().catch(err => {

package/commands/setup.js

@@ -47,7 +47,8 @@ module.exports = async function setup() {
   for (const h of harnesses) {
     const status = h.installed ? green('✓ installed') : slate('✗ not installed');
     const mode = h.headless ? '' : slate(' · interactive — /work ' + h.id);
-    console.log(`    ${cream(h.label.padEnd(14))} ${status}  ${slate('(' + h.auth + ')')}${mode}`);
+    const fit = h.bestFor ? slate(' · best for ' + h.bestFor) : '';
+    console.log(`    ${cream(h.label.padEnd(14))} ${status}  ${slate('(' + h.auth + ')')}${mode}${fit}`);
   }
   if (installed.length === 0) {
     console.log('');
@@ -95,7 +96,7 @@ module.exports = async function setup() {
   // ── 2. Pick the default route ─────────────────────────
   // Interactive-only harnesses (Hermes, Pi) can't take chat routing — they
   // stay reachable via /work in a session, so they're not default options.
-  const options = chatCapable.map(h => ({ kind: 'harness', id: h.id, label: `${h.label} — your ${h.auth.split(' / ')[0].toLowerCase()}, no API key` }));
+  const options = chatCapable.map(h => ({ kind: 'harness', id: h.id, label: `${h.label} — ${h.bestFor || h.role}; 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?'))}`);

package/commands/truth.js

@@ -0,0 +1,13 @@
+const { auditTruth, formatTruth } = require('../lib/truth');
+
+async function main() {
+  const report = await auditTruth();
+  console.log(`\n${formatTruth(report)}\n`);
+}
+
+module.exports = { main };
+
+main().catch(err => {
+  console.error(`\nTruth audit unavailable: ${err.message}\n`);
+  process.exitCode = 1;
+});