phewsh 0.15.59 → 0.15.61

package/commands/session.js

@@ -73,6 +73,35 @@ function copyToClipboard(text) {
   return false;
 }
 
+// Show the cross-harness handoff — the heart of phewsh's continuity promise:
+// the verified brief that travels to whatever AI tool you pick up next, now
+// rendered as readable markdown instead of raw text and saved so the next tool
+// (or the next phewsh session) inherits it. Best-effort and fail-soft; a
+// handoff that can't generate must never block exit or a switch.
+async function showHandoff({ projectName, route, reason = '', nextHint = true } = {}) {
+  let result = { shown: false, file: null };
+  try {
+    const { content } = await generateBrief();
+    const { renderMarkdown } = require('../lib/md');
+    const saved = persistBrief(content, { project: projectName, route: route || 'unknown' });
+    console.log('');
+    console.log(`  ${teal('●')} ${b(cream('Handoff ready'))}${reason ? ' ' + slate('— ' + reason) : ''}`);
+    console.log(`  ${slate('This is exactly what travels to the next AI tool — nothing re-explained.')}`);
+    ui.divider('line');
+    console.log(renderMarkdown(content));
+    ui.divider('line');
+    if (saved.written) console.log(`  ${slate('saved · ' + saved.file.replace(require('os').homedir(), '~'))}`);
+    copyToClipboard(content);
+    console.log(`  ${slate('copied to clipboard · paste into any tool, or')} ${cream('/use codex')} ${slate('to continue here')}`);
+    if (nextHint) console.log(`  ${slate('full verified brief anytime:')} ${cream('/brief')} ${slate('·')} ${cream('/handoff')}`);
+    console.log('');
+    result = { shown: true, file: saved.file };
+  } catch (err) {
+    console.log(`  ${ember('!')} ${slate('Could not build the handoff: ' + err.message)}`);
+  }
+  return result;
+}
+
 // Sync awareness: compare local .intent/ timestamps with cloud updated_at
 async function checkSyncStatus(config) {
   if (!config?.supabaseUserId || !config?.supabaseAccessToken) return null;
@@ -397,27 +426,31 @@ async function main() {
   // ── 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() {
+  // The welcome beat — warm, plain-language, and continuity-first. This is the
+  // "you made it" moment that frames what phewsh is FOR: one thread across every
+  // AI tool, so you switch harnesses mid-work and nothing gets re-explained.
+  // Non-technical readers get one inviting sentence; the cockpit rows below give
+  // engineers the exact facts. Fail-soft: a missing piece shortens the line, it
+  // never blocks the door.
+  (function welcome() {
     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.')}`);
+      if (hasProject && toolCount > 1) {
+        console.log(`  ${dot} ${sage('Welcome back. One shared memory of')} ${cream(projectName)}${sage(`, and ${tools} that all read it`)} ${slate('— switch tools mid-thought, nothing re-explained.')}`);
       } 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.')}`);
+        console.log(`  ${dot} ${sage('Welcome back. One verified memory of')} ${cream(projectName)} ${sage('— ready for whatever AI tool you reach for next.')}`);
+      } else if (toolCount > 1) {
+        console.log(`  ${dot} ${sage(`Welcome — you made it. ${tools} here; this is where they share one thread.`)} ${slate('/init')} ${sage('to begin.')}`);
+      } else if (toolCount === 1) {
+        console.log(`  ${dot} ${sage('Welcome — you made it. Add Codex or Gemini and phewsh keeps every tool on the same page.')}`);
       } else {
-        console.log(`  ${dot} ${sage('Install Claude Code, Codex, or Gemini — phewsh keeps them all on the same page.')}`);
+        console.log(`  ${dot} ${sage('Welcome — you made it. Install Claude Code, Codex, or Gemini and phewsh keeps them all on the same page.')}`);
       }
       console.log('');
-    } catch { /* the summary is a flourish, never a blocker */ }
+    } catch { /* the welcome is a flourish, never a blocker */ }
   })();
 
   if (config?.apiKey && !config.apiKey.startsWith('sk-')) {
@@ -554,6 +587,10 @@ async function main() {
     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 — your context travels with every route')}`);
+    // One quiet line to the deeper power, without dumping the whole command list:
+    // the moves that make phewsh more than a chat box — true continuity across
+    // harnesses. /help opens everything when they're ready.
+    console.log(`  ${slate('⌄ deeper:')} ${cream('/work')} ${slate('hand to a tool')} ${slate('·')} ${cream('/council')} ${slate('ask them all')} ${slate('·')} ${cream('/handoff')} ${slate('what carries over')} ${slate('·')} ${cream('/help')} ${slate('all')}`);
   }
 
   // Self-aware guidance: snapshot the session's state so phewsh can recommend
@@ -637,6 +674,7 @@ async function main() {
       const tools = continuity.toolsInThread(decisions, { project: projectName });
       const span = tools >= 2 ? slate(` · ${tools} tools, one thread`) : '';
       console.log(`  ${teal('↻')} ${sage('Picking up — ' + line)}${span} ${slate('· /thread')}`);
+      console.log(''); // breathe before "What are you trying to do?"
     } catch { /* continuity is a nicety, never a blocker */ }
   }
 
@@ -704,10 +742,8 @@ async function main() {
   console.log('');
   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(`  ${b(cream('Two ways to get running:'))}`);
+    console.log(`  ${slate('No agent CLI found (Claude Code, Codex, Gemini, Cursor, OpenCode) and no API key yet.')}`);
     console.log('');
     console.log(`    ${teal('/key')}    ${sage('Set an API key (10 seconds)')}`);
     console.log(`    ${teal('/tour')}   ${sage('See what this does (nothing needed)')}`);
@@ -938,7 +974,7 @@ async function main() {
     'sync', 'harnesses', 'fallback', 'outcomes', 'tour', 'update', 'upgrade',
     'agents', 'context', 'truth', 'brief', 'wrap', 'reconcile', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
     'next', 'recommend', 'guide', 'thread', 'continuity', 'learn', 'stats',
-    'pack', 'packs', 'remember', 'commands', 'width',
+    'pack', 'packs', 'remember', 'commands', 'width', 'handoff',
   ]);
   const installedIds = harnesses.filter(h => h.installed).map(h => h.id);
   let turnAbort = null;       // AbortController while an API turn streams
@@ -1346,6 +1382,12 @@ async function main() {
           const h = selfheal.heal();
           if (h.healed) console.log(`  ${teal('↻')} ${sage("Harness context refreshed from .intent/ — you didn't have to")}`);
         } catch { /* self-heal must never block exit */ }
+        // The handoff is given, not asked for: leaving a project hands you the
+        // verified brief that the next AI tool inherits — the continuity promise
+        // made visible on the way out. Only in a real project; never blocks exit.
+        if (intentFiles.length > 0) {
+          await showHandoff({ projectName, route: route?.id, reason: 'carry this into your next tool', nextHint: false });
+        }
         try { require('../lib/intro').farewell(); } catch { /* sign-off is a nicety */ }
         console.log(`  ${sage('session ended · ' + turns + ' exchanges · ' + (totalPromptTokens + totalCompletionTokens) + ' tokens')}`);
         if (decisionsThisSession > 0) {
@@ -1658,6 +1700,7 @@ async function main() {
         console.log('');
         console.log(`  ${cream('session')}`);
         console.log(`    ${teal('/work')} ${slate('[harness]')} ${sage('Preflight, brief, native handoff, automatic postflight')}`);
+        console.log(`    ${teal('/handoff')}     ${sage('See the verified brief the next AI tool inherits — rendered + saved')}`);
         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')}`);
@@ -1785,8 +1828,20 @@ async function main() {
       if (cmd === 'brief') {
         console.log('');
         const { content } = await generateBrief();
-        console.log(content);
+        const { renderMarkdown } = require('../lib/md');
+        console.log(renderMarkdown(content));
         console.log('');
+        console.log(`  ${slate('this is your handoff — it travels to the next AI tool ·')} ${cream('/handoff')} ${slate('to save + copy it')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      // /handoff — explicitly produce, render, save, and copy the cross-harness
+      // handoff so you can SEE what would carry into the next tool.
+      if (cmd === 'handoff') {
+        console.log(`  ${sage('Building your handoff…')}`);
+        await showHandoff({ projectName, route: route?.id, reason: 'what the next AI tool will pick up' });
         rl.prompt();
         return;
       }
@@ -2661,6 +2716,7 @@ async function main() {
         } else {
           console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate('No changes detected. 1 kept · 2 undid · 3 redid · 4 flopped · /reconcile · /switch <tool>')}`);
         }
+        console.log(`  ${slate('continuing elsewhere?')} ${cream('/handoff')} ${slate('shows the updated brief the next tool inherits')}`);
         console.log('');
         rl.prompt();
         return;

package/lib/md.js

@@ -120,4 +120,13 @@ function streamRenderer(write) {
   };
 }
 
-module.exports = { inlineMd, renderLine, streamRenderer };
+// Render a complete markdown string to styled, word-wrapped terminal text —
+// the non-streaming counterpart to streamRenderer, for content we already have
+// in full (a handoff brief, a saved record). Carries fence state across lines
+// so code blocks render literally.
+function renderMarkdown(md) {
+  const state = { inFence: false };
+  return String(md).split('\n').map((line) => renderLine(line, state)).join('\n');
+}
+
+module.exports = { inlineMd, renderLine, streamRenderer, renderMarkdown };

package/package.json

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