phewsh 0.15.41 → 0.15.43

package/bin/phewsh.js

@@ -3,6 +3,17 @@
 const args = process.argv.slice(2);
 const command = args[0];
 
+// `phewsh shim-preflight <bin>` — called BY the shims on every tool launch.
+// Must be instant and side-effect-free: print the banner, exit. No update
+// check, no network, no session. Intercepted before anything else loads.
+if (command === 'shim-preflight') {
+  try {
+    const bin = args[1] || 'tool';
+    process.stdout.write(require('../lib/shims').preflightBanner(bin) + '\n');
+  } catch { /* a broken banner must never delay the real tool */ }
+  process.exit(0);
+}
+
 // ── ANSI helpers (no chalk dependency)
 const b  = (s) => `\x1b[1m${s}\x1b[0m`;   // bold
 const d  = (s) => `\x1b[2m${s}\x1b[0m`;   // dim
@@ -75,6 +86,7 @@ const COMMANDS = {
   sequence: () => require('../commands/sequence')(),
   seq:     () => require('../commands/sequence')(),
   ambient: () => require('../commands/ambient')(),
+  shim:    () => require('../commands/shim')(),
   hook:    () => require('../commands/hook')(),
   welcome: () => require('../commands/welcome')(),
   intro:   () => require('../commands/welcome')(),
@@ -113,6 +125,7 @@ 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('ambient')}    ${g('Continuity without launching phewsh — enhance your other tools')}`);
+  console.log(`    ${cyan('shim')}       ${g('Guaranteed launch banner — phewsh prints status before each tool')}`);
   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')}`);

package/commands/ambient.js

@@ -19,6 +19,7 @@ const os = require('os');
 const readline = require('readline');
 const { listHarnesses } = require('../lib/harnesses');
 const selfheal = require('../lib/selfheal');
+const slash = require('../lib/slash-commands');
 
 const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
 const LEDGER_FILE = path.join(PHEWSH_DIR, 'ambient.json');
@@ -169,6 +170,7 @@ async function turnOn(skipConfirm) {
 
   const changes = applyClaudeHooks();
   const { written } = selfheal.syncGlobalBaseFiles();
+  const slashWritten = slash.installSlashCommands().written;
   const ledger = loadLedger();
   ledger.applied['claude-code'] = {
     at: new Date().toISOString(),
@@ -184,6 +186,13 @@ async function turnOn(skipConfirm) {
       undo: 'phewsh ambient off',
     };
   }
+  if (slashWritten.length > 0 || ledger.applied.slashCommands) {
+    ledger.applied.slashCommands = {
+      at: new Date().toISOString(),
+      tools: slashWritten.length > 0 ? slashWritten : (ledger.applied.slashCommands || {}).tools || [],
+      undo: 'phewsh ambient off',
+    };
+  }
   ledger.seenHarnesses = harnesses.filter(h => h.installed).map(h => h.id);
   ledger.disabled = false; // explicit enable clears any prior opt-out
   saveLedger(ledger);
@@ -192,6 +201,7 @@ async function turnOn(skipConfirm) {
   console.log(`  ${green('●')} ${b('Ambient is on.')}`);
   changes.forEach(c => console.log(`    ${teal('+')} ${slate(c)}`));
   written.forEach(f => console.log(`    ${teal('+')} ${slate('base file ' + f + ' (machine-wide phewsh awareness)')}`));
+  if (slashWritten.length) console.log(`    ${teal('+')} ${cream('/intent')} ${slate('command added to ' + slashWritten.join(', '))}`);
   console.log('');
   console.log(`  ${sage('Next Claude Code session in a project with')} ${cream('.intent/')} ${sage('starts pre-briefed.')}`);
   if (written.length > 0) {
@@ -204,17 +214,20 @@ async function turnOn(skipConfirm) {
 function turnOff() {
   const removed = removeClaudeHooks();
   const { removed: removedGlobal } = selfheal.removeGlobalBaseFiles();
+  const { removed: removedSlash } = slash.removeSlashCommands();
   const ledger = loadLedger();
   delete ledger.applied['claude-code'];
   delete ledger.applied.globalBase;
+  delete ledger.applied.slashCommands;
   delete ledger.autoEnabledAt;
   ledger.disabled = true; // sticky opt-out — first-run auto-enable must respect this
   saveLedger(ledger);
   console.log('');
-  if (removed.length > 0 || removedGlobal.length > 0) {
+  if (removed.length > 0 || removedGlobal.length > 0 || removedSlash.length > 0) {
     console.log(`  ${green('●')} ${b('Ambient is off.')}`);
     removed.forEach(c => console.log(`    ${peach('-')} ${slate(c)}`));
     removedGlobal.forEach(f => console.log(`    ${peach('-')} ${slate('base file ' + f + ' (phewsh block removed)')}`));
+    if (removedSlash.length) console.log(`    ${peach('-')} ${slate('/intent command removed from ' + removedSlash.join(', '))}`);
     console.log(`  ${sage('Breadcrumb log kept at')} ${cream('~/.phewsh/ambient-sessions.jsonl')} ${sage('— delete it if you want; phewsh never will.')}`);
   } else {
     console.log(`  ${sage('Nothing was applied — nothing to remove.')}`);
@@ -302,6 +315,7 @@ async function ensureAuto() {
   const hasClaude = installed.some(h => h.id === 'claude-code');
   const changes = hasClaude ? applyClaudeHooks() : [];
   const { written } = selfheal.syncGlobalBaseFiles();
+  const slashWritten = slash.installSlashCommands().written;
   // Refresh existing project files only — first-run auto-enable must not dump
   // context files into whatever repo the user happens to be standing in.
   try { selfheal.syncContextFiles({ createMissing: false }); } catch { /* best-effort */ }
@@ -317,6 +331,9 @@ async function ensureAuto() {
   if (written.length > 0) {
     ledger.applied.globalBase = { at: now, files: written, undo: 'phewsh ambient off' };
   }
+  if (slashWritten.length > 0) {
+    ledger.applied.slashCommands = { at: now, tools: slashWritten, undo: 'phewsh ambient off' };
+  }
   ledger.disabled = false;
   ledger.autoEnabledAt = now;
   ledger.seenHarnesses = installed.map(h => h.id);
@@ -327,7 +344,9 @@ async function ensureAuto() {
     console.log(`  ${b(cream('phewsh set itself up across your AI tools'))} ${sage('— so they stay in sync with your project intent.')}`);
     if (hasClaude) console.log(`    ${teal('+')} ${slate('Claude Code gets a brief from a project\'s .intent/ at session start')}`);
     written.forEach(f => console.log(`    ${teal('+')} ${slate('environment note added to ' + f)}`));
-    console.log(`    ${sage('In any project with')} ${cream('.intent/')}${sage(', your tools now read its real intent. This is reversible:')} ${cream('phewsh ambient off')}`);
+    if (slashWritten.length) console.log(`    ${teal('+')} ${cream('/intent')} ${slate('command added to ' + slashWritten.join(', '))}`);
+    console.log(`    ${sage('In any project with')} ${cream('.intent/')}${sage(', your tools now read its real intent. Reversible:')} ${cream('phewsh ambient off')}`);
+    console.log(`    ${sage('Want a guaranteed status line each time you launch a tool?')} ${cream('phewsh shim on')}`);
     console.log('');
   }
 }

package/commands/session.js

@@ -579,6 +579,9 @@ async function main() {
       ambientOn = s.includes('phewsh hook session-start');
     } catch { /* no settings = ambient off */ }
 
+    let shimOn = false;
+    try { shimOn = require('../lib/shims').shimStatus().installed.length > 0; } catch { /* shims off */ }
+
     let pending = 0;
     // Only substantive calls — never nag the user to "judge" a greeting.
     try { pending = pendingDecisions({ project: projectName, substantive: true }).length; } catch { /* best-effort */ }
@@ -601,6 +604,7 @@ async function main() {
       turnsThisSession: Math.floor(messages.length / 2),
       seqStale,
       ambientOn,
+      shimOn,
       commitsSinceIntent: (() => { try { return selfheal.commitsSinceIntent(); } catch { return 0; } })(),
       bestKeeper,
     };

package/commands/shim.js

@@ -0,0 +1,107 @@
+// phewsh shim — install/remove the launch-banner shims.
+//
+//   phewsh shim            status
+//   phewsh shim on [--yes] consent screen, then install shims + PATH line
+//   phewsh shim off        remove shims + PATH line
+//
+// Shims are the GUARANTEE that phewsh is active: phewsh prints a deterministic
+// banner when you launch a tool, then runs the real tool. This is invasive
+// (intercepts your tool commands on PATH + edits your shell rc), so it's an
+// explicit opt-in with a consent screen — never auto-installed.
+
+const readline = require('readline');
+const { listHarnesses } = require('../lib/harnesses');
+const shims = require('../lib/shims');
+
+const b = (s) => `\x1b[1m${s}\x1b[0m`;
+const teal = (s) => `\x1b[38;5;79m${s}\x1b[0m`;
+const sage = (s) => `\x1b[38;5;151m${s}\x1b[0m`;
+const slate = (s) => `\x1b[38;5;247m${s}\x1b[0m`;
+const cream = (s) => `\x1b[38;5;230m${s}\x1b[0m`;
+const peach = (s) => `\x1b[38;5;216m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+async function confirm(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => rl.question(q, a => { rl.close(); res(/^y(es)?$/i.test(a.trim())); }));
+}
+
+function installedBins() {
+  return listHarnesses().filter(h => h.installed).map(h => h.bin);
+}
+
+async function turnOn(skipConfirm) {
+  const bins = installedBins();
+  const resolvable = bins.filter(bin => shims.resolveReal(bin));
+  console.log('');
+  console.log(`  ${b(cream('phewsh shims'))} ${sage('— a guaranteed status banner when you launch your tools')}`);
+  console.log('');
+  if (resolvable.length === 0) {
+    console.log(`  ${yellow('No installed tools found to shim.')} ${slate('Install a coding CLI first.')}`);
+    console.log('');
+    return;
+  }
+  console.log(`  ${sage('When you run any of these, phewsh prints one line, then runs the real tool:')}`);
+  console.log(`    ${slate(resolvable.join('  '))}`);
+  console.log('');
+  console.log(`  ${peach('Exactly what changes:')}`);
+  console.log(`    ${teal('+')} ${slate('tiny scripts in')} ${cream('~/.phewsh/shims/')} ${slate('(each runs the real tool — bricks nothing)')}`);
+  console.log(`    ${teal('+')} ${slate('one PATH line in')} ${cream(shims.detectRcFile())}`);
+  console.log(`  ${sage('Undo anytime:')} ${cream('phewsh shim off')}`);
+  console.log('');
+  if (!skipConfirm) {
+    const ok = await confirm(`  ${b('Install shims?')} ${slate('[y/N] ')}`);
+    if (!ok) { console.log(`  ${sage('Nothing changed.')}\n`); return; }
+  }
+  const { shimmed, skipped, rcFile, rcAdded } = shims.installShims(bins);
+  console.log('');
+  console.log(`  ${green('●')} ${b('Shims installed.')}`);
+  shimmed.forEach(s => console.log(`    ${teal('+')} ${cream(s.bin.padEnd(12))} ${slate('→ ' + s.real)}`));
+  if (skipped.length) console.log(`    ${slate('skipped (no real binary found): ' + skipped.join(', '))}`);
+  if (rcAdded) console.log(`    ${teal('+')} ${slate('PATH line added to ' + rcFile)}`);
+  console.log('');
+  console.log(`  ${peach('Open a new terminal')} ${sage('(or `source ' + rcFile + '`) so the PATH change takes effect.')}`);
+  console.log(`  ${sage('Then launching')} ${cream(shimmed[0] ? shimmed[0].bin : 'your tool')} ${sage('shows the phewsh banner first.')}`);
+  console.log('');
+}
+
+function turnOff() {
+  const { removed, rcFile, rcRemoved } = shims.removeShims();
+  console.log('');
+  if (removed.length || rcRemoved) {
+    console.log(`  ${green('●')} ${b('Shims removed.')}`);
+    if (removed.length) console.log(`    ${peach('-')} ${slate('removed ' + removed.join(', '))}`);
+    if (rcRemoved) console.log(`    ${peach('-')} ${slate('PATH line removed from ' + rcFile)}`);
+    console.log(`  ${sage('Open a new terminal so your shells stop using the shim dir.')}`);
+  } else {
+    console.log(`  ${sage('No shims were installed — nothing to remove.')}`);
+  }
+  console.log('');
+}
+
+function status() {
+  const s = shims.shimStatus();
+  console.log('');
+  console.log(`  ${b(cream('phewsh shims'))} ${sage('— status')}`);
+  console.log('');
+  if (s.installed.length) {
+    console.log(`    ${green('●')} ${cream('installed')} ${slate(s.installed.join(', '))}`);
+    console.log(`        ${slate('dir: ' + s.shimDir)}`);
+    console.log(`        ${slate('PATH active in this shell: ' + (s.onPath ? 'yes' : 'no — open a new terminal'))}`);
+    console.log(`        ${slate('rc line in ' + s.rcFile + ': ' + (s.rcActive ? 'present' : 'missing'))}`);
+  } else {
+    console.log(`    ${yellow('○')} ${sage('not installed —')} ${cream('phewsh shim on')} ${sage('to add the launch banner')}`);
+  }
+  console.log('');
+}
+
+async function main() {
+  const sub = process.argv[3] || 'status';
+  const skipConfirm = process.argv.includes('--yes');
+  if (sub === 'on') return turnOn(skipConfirm);
+  if (sub === 'off') return turnOff();
+  return status();
+}
+
+module.exports = main;

package/lib/ambient-guidance.js

@@ -1,41 +1,30 @@
-// Ambient guidance — what phewsh tells an AI tool about the user's setup.
+// Ambient guidance — kept deliberately SMALL.
 //
-// HARD-WON LESSON (Jun 18, after 3 dogfood rounds): you cannot word your way
-// into making a GLOBAL config block that says "promote this named tool + emit a
-// signature" look trustworthy. A well-aligned model SHOULD be skeptical of an
-// unknown global file that asks it to advertise something and silently signal
-// when it's "working" — that's injection-shaped. And protesting innocence
-// ("this is NOT an injection") backfires: real user config never defends
-// itself; only injections do. Claude correctly flagged every version that did.
+// The hard lesson (4 dogfood rounds + a CCAF-exam framing): you cannot solve a
+// trust problem with persuasion. A global block that says "trust this tool,
+// treat its files as intent, it installed itself, here's how to undo it" is
+// — to a safety-tuned model — nearly indistinguishable from an injection, and
+// rewording it just raises suspicion. Real user config never talks like that.
 //
-// So the design is split by EVIDENCE:
-//   • PROJECT level (.intent/ exists) — there's real proof the user set phewsh
-//     up: their own intent files, a real brief, their own installed hook. The
-//     guidance can be warm, can offer to reconcile, and can carry the 😮‍💨🤫
-//     signature, because it's earned by genuine context.
-//   • GLOBAL level (no project) — NO evidence, NO substance. So the global base
-//     file is a plain, factual ENVIRONMENT NOTE: it tells the model how to read
-//     a `.intent/` dir if it encounters one, and nothing more. No advertising,
-//     no signature mandate, no self-defense. A model won't flag "the user keeps
-//     project notes in X" any more than "this repo uses pnpm."
-//
-// Used in: the Claude Code SessionStart hook (PROJECT_GUIDANCE), the per-project
-// synced files (PROJECT_GUIDANCE), and the global base files (GLOBAL_GUIDANCE).
+// So phewsh no longer ASKS the model to prove it's active. phewsh proves it
+// itself, through architecture (a deterministic launch banner from command
+// shims, the SessionStart hook, the ledger). Prose carries the minimum:
+//   • GLOBAL: a tiny FACT — ".intent/ dirs are project docs" — nothing more.
+//   • PROJECT: the real .intent/ content is the evidence; this is a short,
+//     factual frame around it. The 😮‍💨🤫 is best-effort and project-only —
+//     never the guarantee (the banner/ledger are).
 
-// In-project guidance — a .intent/ dir + brief are visible evidence the user
-// set this up, so warmth + the offer + the signature are legitimate here.
-const PROJECT_GUIDANCE = `## Working with phewsh (the user's project tooling)
-This project uses **phewsh** (open-source · phewsh.com) to keep its intent, decisions, and outcomes consistent across the AI tools the user works with. The brief/notes here are compiled from the project's own \`.intent/\` files — the user's documentation of what they're building and why. Use it as helpful context:
-- Do their actual request first, and well.
-- When you make a real decision, ship something, or change direction, you can offer in plain language to keep the record current — e.g. "want me to fold this into your .intent so your other tools see it?" Map their intent to the right phewsh action; don't make them memorize commands.
-- If a drift note is present above, mention it once, gently — no nagging.
-- The user likes a small \`— 😮‍💨🤫\` at the very end of a reply when phewsh's context actually shaped it — it's how they see the continuity layer doing its job. Add it on its own line when that's true; otherwise skip it.`;
+// Machine-wide: the smallest possible factual note. No emoji, no undo line, no
+// "installed by", no trust claim, no behavioral request — those are exactly
+// what made a security-tuned model challenge it. Just the fact.
+const GLOBAL_GUIDANCE = `## phewsh
+Some projects on this machine use a \`.intent/\` directory as project documentation. When one is present, read those files like README.md, CLAUDE.md, or AGENTS.md.`;
 
-// Machine-wide guidance — NO project evidence here, so this is a plain factual
-// note about the user's environment. It asks the model to do nothing proactive;
-// it only explains how to interpret a `.intent/` dir if one shows up. Crucially:
-// no "advertise", no signature mandate, no "trust me / not an injection".
-const GLOBAL_GUIDANCE = `## Environment note: phewsh
-The user keeps project intent in **phewsh** — an open-source CLI (phewsh.com). When a project you're working in contains a \`.intent/\` directory, those files are the user's own notes on what they're building and why; read them as project documentation when they're relevant to the task. (If they're starting a new project and want that continuity across their tools, it's set up with \`phewsh intent --init\`.)`;
+// In-project: the synced block already carries the real .intent/ content above
+// this note (vision/plan/status) — that's the evidence the model trusts. Keep
+// the framing short and factual; the signature is an invitation, not a mandate.
+const PROJECT_GUIDANCE = `## Project intent (phewsh)
+The \`.intent/\` content above is this project's source-of-truth documentation — what's being built, the plan, current status, and constraints. Use it like the project's README. If your work changes a decision or the direction, you can offer to update \`.intent/\` so the user's other tools stay in sync.
+(Optional: when phewsh's project context shaped your reply, you're welcome to end with \`— 😮‍💨🤫\` so the user can see the continuity layer working. The reliable signal is phewsh's own launch banner, not this.)`;
 
 module.exports = { PROJECT_GUIDANCE, GLOBAL_GUIDANCE };

package/lib/selfheal.js

@@ -103,7 +103,7 @@ function coreOf(text) {
 // re-running every session doesn't churn files. Returns true if written.
 function upsertBlock(filePath, core, footer, fileLabel, headerText) {
   try {
-    const block = core.replace(/\s*$/, '') + '\n' + footer;
+    const block = footer ? core.replace(/\s*$/, '') + '\n' + footer : core.replace(/\s*$/, '');
     const wrapped = `${START_MARKER}\n${block}\n${END_MARKER}`;
     const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
     if (existing && existing.includes(START_MARKER) && existing.includes(END_MARKER)) {
@@ -206,11 +206,6 @@ const GLOBAL_TARGETS = [
   { dir: '.gemini', file: 'GEMINI.md', label: 'Gemini' },
 ];
 
-function globalBaseFooter() {
-  const stamp = new Date().toISOString().slice(0, 16).replace('T', ' ');
-  return `> — installed by phewsh 😮‍💨🤫 · ${stamp} · machine-wide · undo: phewsh ambient off`;
-}
-
 // Returns the list of {dir,file,label,path} targets whose tool dir exists.
 function detectGlobalTargets() {
   const home = os.homedir();
@@ -222,8 +217,12 @@ function detectGlobalTargets() {
 function syncGlobalBaseFiles() {
   try {
     const { GLOBAL_GUIDANCE } = require('./ambient-guidance');
-    const header = '<!-- phewsh writes only the marked block below; edit freely around it. -->\n\n';
-    const footer = globalBaseFooter();
+    // No header, no footer for the GLOBAL note — the marker pair is enough to
+    // find/remove it, and any "installed by phewsh / undo / emoji" metadata is
+    // exactly the self-referential noise that made a safety-tuned model
+    // challenge the block. The block is now just the bare fact, marker-wrapped.
+    const header = '';
+    const footer = '';
     const written = [];
     for (const t of detectGlobalTargets()) {
       if (upsertBlock(t.path, GLOBAL_GUIDANCE, footer, t.label, header)) {

package/lib/shims.js

@@ -0,0 +1,226 @@
+// phewsh shims — the GUARANTEE layer.
+//
+// The lesson from four dogfood rounds: a model can't be relied on to prove
+// phewsh is active (it may flag a prose block, or ignore it). So phewsh proves
+// it ITSELF. A shim is a tiny script named like the user's tool (`claude`,
+// `codex`, …) placed first on PATH. When the user runs `claude`, the shim:
+//   1. prints a deterministic phewsh status banner (phewsh prints it — not the
+//      model, so it's guaranteed), then
+//   2. exec's the REAL tool, unchanged.
+//
+// NON-NEGOTIABLE SAFETY: the shim must ALWAYS run the real tool, even if phewsh
+// is broken, missing, or slow. The banner is best-effort; the hand-off is not.
+// We bake the resolved real path into the shim and add a PATH-stripped fallback,
+// so the user's tools can never be bricked by phewsh.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
+const SHIM_DIR = path.join(PHEWSH_DIR, 'shims');
+
+const RC_START = '# >>> phewsh shims >>>';
+const RC_END = '# <<< phewsh shims <<<';
+const RC_BLOCK = `${RC_START}\nexport PATH="$HOME/.phewsh/shims:$PATH"\n${RC_END}`;
+
+// Resolve a tool's REAL binary, excluding our own shim dir so we never resolve
+// the shim to itself. Returns absolute path or null.
+function resolveReal(bin) {
+  // Only ever called with bins from the fixed harness registry — but keep it
+  // strict anyway so this can never become a shell-injection surface.
+  if (!/^[A-Za-z0-9_.-]+$/.test(bin)) return null;
+  try {
+    const cleanPath = (process.env.PATH || '')
+      .split(path.delimiter)
+      .filter(p => p && path.resolve(p) !== path.resolve(SHIM_DIR))
+      .join(path.delimiter);
+    const cmd = process.platform === 'win32' ? `where ${bin}` : `command -v ${bin}`;
+    const out = execFileSync('sh', ['-c', cmd], {
+      encoding: 'utf-8',
+      env: { ...process.env, PATH: cleanPath },
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    }).trim().split('\n')[0].trim();
+    return out && path.resolve(out) !== path.resolve(SHIM_DIR, bin) ? out : null;
+  } catch { return null; }
+}
+
+// The shim script. POSIX sh. Real path is baked in; phewsh banner is wrapped so
+// any failure is swallowed; the real exec is the last, unconditional step.
+function shimScript(bin, realPath) {
+  return `#!/bin/sh
+# phewsh shim for ${bin} — prints a status banner, then runs the real tool.
+# SAFETY: phewsh is best-effort; the real ${bin} ALWAYS runs.
+phewsh shim-preflight ${bin} 2>/dev/null || true
+REAL="${realPath}"
+if [ -x "$REAL" ]; then exec "$REAL" "$@"; fi
+# Fallback: find the real ${bin} on PATH, excluding our shim dir.
+CLEAN="$(printf '%s' "$PATH" | tr ':' '\\n' | grep -vxF "${SHIM_DIR}" | paste -sd: -)"
+REAL2="$(PATH="$CLEAN" command -v ${bin} 2>/dev/null)"
+if [ -n "$REAL2" ]; then exec "$REAL2" "$@"; fi
+echo "phewsh: could not locate the real '${bin}'." >&2
+exit 127
+`;
+}
+
+// First meaningful line of a markdown file — past YAML frontmatter and headings.
+function firstLine(file, max = 64) {
+  try {
+    let body = fs.readFileSync(file, 'utf-8');
+    if (body.startsWith('---')) { const e = body.indexOf('\n---', 3); if (e !== -1) body = body.slice(e + 4); }
+    const line = body.split('\n').map(l => l.trim())
+      .find(l => l && !l.startsWith('#') && !l.startsWith('>') && !l.startsWith('---'));
+    if (!line) return null;
+    const clean = line.replace(/[*_`]/g, '').replace(/\s+/g, ' ').trim();
+    return clean.length > max ? clean.slice(0, max - 1) + '…' : clean;
+  } catch { return null; }
+}
+
+// How many decisions phewsh has recorded for this project (cwd basename key).
+function decisionCount(cwd) {
+  try {
+    const file = path.join(PHEWSH_DIR, 'outcomes', 'decisions.json');
+    const all = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const key = path.basename(cwd);
+    const list = Array.isArray(all) ? all : (all.decisions || []);
+    return list.filter(d => (d.project || d.cwd && path.basename(d.cwd)) === key).length;
+  } catch { return 0; }
+}
+
+// Per-repo nudge counter — so the "create intent" coaching shows for the first
+// few launches then goes quiet (a coach, not a billboard). Best-effort.
+function bumpNudge(cwd) {
+  try {
+    const file = path.join(PHEWSH_DIR, 'shim-seen.json');
+    let seen = {};
+    try { seen = JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { /* fresh */ }
+    seen[cwd] = (seen[cwd] || 0) + 1;
+    fs.mkdirSync(PHEWSH_DIR, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(seen));
+    return seen[cwd];
+  } catch { return 99; } // on failure, assume "seen" so we don't nag
+}
+
+// Deterministic launch banner — computed by phewsh, offline, fast. Evidence +
+// VALUE + GUIDANCE, not just "active". phewsh prints it, so it's guaranteed.
+const C = { teal: s => `\x1b[38;5;79m${s}\x1b[0m`, sage: s => `\x1b[38;5;151m${s}\x1b[0m`, slate: s => `\x1b[38;5;247m${s}\x1b[0m`, cream: s => `\x1b[38;5;230m${s}\x1b[0m`, peach: s => `\x1b[38;5;216m${s}\x1b[0m` };
+function preflightBanner(bin, cwd = process.cwd()) {
+  try {
+    const intentDir = path.join(cwd, '.intent');
+    if (!fs.existsSync(intentDir)) {
+      // No shared truth here. Coach (first few launches per repo), then go quiet.
+      const n = bumpNudge(cwd);
+      if (n <= 3) {
+        return `${C.sage('😮‍💨🤫 phewsh')} ${C.slate('· no shared project truth here yet')}\n`
+          + `   ${C.slate('so every AI tool stays in sync, create it:')} ${C.cream('phewsh intent --init')} ${C.slate('· → ' + bin)}`;
+      }
+      return `${C.sage('😮‍💨🤫 phewsh active')} ${C.slate('· → ' + bin)}`;
+    }
+    // Truth present — show the value + continuity health.
+    const files = fs.readdirSync(intentDir).filter(f => /\.(md|json)$/.test(f)).length;
+    const vision = firstLine(path.join(intentDir, 'vision.md'));
+    const next = firstLine(path.join(intentDir, 'next.md')) || firstLine(path.join(intentDir, 'status.md'));
+    const decisions = decisionCount(cwd);
+    let health = '✓ intent';
+    try {
+      const { statusDrift } = require('./truth');
+      const d = statusDrift(cwd);
+      if (d && d.tracked) health += d.commitsSince > 0 ? `  ${C.peach('⚠ record ' + d.commitsSince + ' behind')}` : '  ✓ record current';
+    } catch { /* nicety */ }
+
+    const lines = [`${C.sage('😮‍💨🤫 phewsh active')}  ${C.slate(health)}  ${C.slate('· → ' + bin)}`];
+    if (vision) lines.push(`   ${C.slate('vision:')} ${C.cream(vision)}`);
+    if (next) lines.push(`   ${C.slate('next:  ')} ${C.cream(next)}${decisions ? C.slate('  · ' + decisions + ' decisions') : ''}`);
+    else if (decisions) lines.push(`   ${C.slate(decisions + ' decisions · ' + files + ' intent files')}`);
+    return lines.join('\n');
+  } catch {
+    return `😮‍💨🤫 phewsh active · → ${bin}`; // never break the launch
+  }
+}
+
+// ── shell rc (PATH activation) ──────────────────────────────────────────
+function detectRcFile() {
+  const home = os.homedir();
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return path.join(home, '.zshrc');
+  if (shell.includes('bash')) {
+    const bp = path.join(home, '.bashrc');
+    return fs.existsSync(bp) ? bp : path.join(home, '.bash_profile');
+  }
+  // default to zsh rc on macOS, bashrc elsewhere
+  return path.join(home, process.platform === 'darwin' ? '.zshrc' : '.bashrc');
+}
+
+function rcHasBlock(rcFile) {
+  try { return fs.readFileSync(rcFile, 'utf-8').includes(RC_START); } catch { return false; }
+}
+
+function addRcBlock(rcFile) {
+  let existing = '';
+  try { existing = fs.readFileSync(rcFile, 'utf-8'); } catch { /* new file */ }
+  if (existing.includes(RC_START)) return false;
+  const next = (existing.replace(/\s*$/, '') + '\n\n' + RC_BLOCK + '\n').replace(/^\n+/, '');
+  fs.writeFileSync(rcFile, next);
+  return true;
+}
+
+function removeRcBlock(rcFile) {
+  try {
+    const existing = fs.readFileSync(rcFile, 'utf-8');
+    if (!existing.includes(RC_START)) return false;
+    const re = new RegExp('\\n*' + RC_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+      '[\\s\\S]*?' + RC_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\n*', 'g');
+    fs.writeFileSync(rcFile, existing.replace(re, '\n').replace(/^\n+/, ''));
+    return true;
+  } catch { return false; }
+}
+
+// ── install / remove ─────────────────────────────────────────────────────
+// Install shims for the given harness bins that actually resolve to a real
+// binary. Returns { shimmed:[{bin,real}], rcFile, rcAdded, skipped:[bin] }.
+function installShims(bins) {
+  fs.mkdirSync(SHIM_DIR, { recursive: true });
+  const shimmed = [];
+  const skipped = [];
+  for (const bin of bins) {
+    const real = resolveReal(bin);
+    if (!real) { skipped.push(bin); continue; }     // don't shim what we can't hand off to
+    const shimPath = path.join(SHIM_DIR, bin);
+    fs.writeFileSync(shimPath, shimScript(bin, real), { mode: 0o755 });
+    fs.chmodSync(shimPath, 0o755);
+    shimmed.push({ bin, real });
+  }
+  const rcFile = detectRcFile();
+  const rcAdded = shimmed.length > 0 ? addRcBlock(rcFile) : false;
+  return { shimmed, skipped, rcFile, rcAdded };
+}
+
+function removeShims() {
+  const removed = [];
+  try {
+    if (fs.existsSync(SHIM_DIR)) {
+      for (const f of fs.readdirSync(SHIM_DIR)) {
+        fs.unlinkSync(path.join(SHIM_DIR, f));
+        removed.push(f);
+      }
+      fs.rmdirSync(SHIM_DIR);
+    }
+  } catch { /* best-effort */ }
+  const rcFile = detectRcFile();
+  const rcRemoved = removeRcBlock(rcFile);
+  return { removed, rcFile, rcRemoved };
+}
+
+function shimStatus() {
+  let installed = [];
+  try { installed = fs.existsSync(SHIM_DIR) ? fs.readdirSync(SHIM_DIR) : []; } catch { /* none */ }
+  const rcFile = detectRcFile();
+  return { installed, shimDir: SHIM_DIR, rcFile, rcActive: rcHasBlock(rcFile), onPath: (process.env.PATH || '').split(path.delimiter).some(p => path.resolve(p) === path.resolve(SHIM_DIR)) };
+}
+
+module.exports = {
+  SHIM_DIR, resolveReal, preflightBanner, installShims, removeShims, shimStatus,
+  detectRcFile, addRcBlock, removeRcBlock,
+};

package/lib/slash-commands.js

@@ -0,0 +1,94 @@
+// phewsh slash commands — teach ONE verb, not a tool.
+//
+// CG's insight: the first thing a user should learn isn't `phewsh`, it's
+// `/intent`. If every AI tool has `/intent`, the user learns the BEHAVIOR they
+// want (see this project's truth) without learning the implementation. So
+// phewsh installs `/intent` into each harness's NATIVE custom-command slot —
+// a structured, user-invoked channel (not injected prose). It only does
+// something when the user types it, so there's nothing for a model to flag.
+//
+// Each harness has its own format/dir; we only install for tools present, and
+// never clobber a command the user wrote (we mark ours + check the marker).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARKER = 'phewsh-managed';
+
+// The portable prompt `/intent` runs. It's a user-invoked request to surface
+// the project's own .intent/ docs — trusted because the user asked for it.
+const INTENT_PROMPT = `Show me this project's current intent, read from its \`.intent/\` directory. Be concise:
+- **Vision** — what we're building and why
+- **Current objective / next** — what's in flight
+- **Constraints** — budget, time, scope, non-negotiables
+- **Recent decisions** — and any that are still open
+
+If there is no \`.intent/\` directory here, say so and tell me I can create one with \`phewsh intent --init\` so every AI tool I use shares the same project truth.`;
+
+// Tools that support file-based custom slash commands, and how each wants them.
+// parentDir must already exist (the tool is installed) before we write.
+const SLASH_TARGETS = [
+  { id: 'claude-code', parent: '.claude', sub: 'commands', file: 'intent.md', fmt: 'claude' },
+  { id: 'codex',       parent: '.codex',  sub: 'prompts',  file: 'intent.md', fmt: 'codex' },
+  { id: 'gemini',      parent: '.gemini', sub: 'commands', file: 'intent.toml', fmt: 'gemini' },
+];
+
+function bodyFor(fmt) {
+  if (fmt === 'claude') {
+    return `---\ndescription: Show this project's intent — vision, objective, constraints, decisions (phewsh)\n---\n<!-- ${MARKER} · remove with: phewsh ambient off -->\n\n${INTENT_PROMPT}\n`;
+  }
+  if (fmt === 'codex') {
+    return `<!-- ${MARKER} · remove with: phewsh ambient off -->\n${INTENT_PROMPT}\n`;
+  }
+  if (fmt === 'gemini') {
+    const esc = INTENT_PROMPT.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+    return `# ${MARKER} · remove with: phewsh ambient off\ndescription = "Show this project's intent via phewsh"\nprompt = """\n${esc}\n"""\n`;
+  }
+  return INTENT_PROMPT;
+}
+
+function targetPath(t) {
+  return path.join(os.homedir(), t.parent, t.sub, t.file);
+}
+
+// Install /intent for every present tool. Won't overwrite a user's own command
+// (only a file we previously marked, or a fresh write). Returns written ids.
+function installSlashCommands() {
+  const written = [];
+  for (const t of SLASH_TARGETS) {
+    try {
+      if (!fs.existsSync(path.join(os.homedir(), t.parent))) continue; // tool not installed
+      const fp = targetPath(t);
+      if (fs.existsSync(fp)) {
+        const cur = fs.readFileSync(fp, 'utf-8');
+        if (!cur.includes(MARKER)) continue; // user's own /intent — leave it
+        if (cur === bodyFor(t.fmt)) continue; // already current
+      }
+      fs.mkdirSync(path.dirname(fp), { recursive: true });
+      fs.writeFileSync(fp, bodyFor(t.fmt));
+      written.push(t.id);
+    } catch { /* best-effort per tool */ }
+  }
+  return { written };
+}
+
+function removeSlashCommands() {
+  const removed = [];
+  for (const t of SLASH_TARGETS) {
+    try {
+      const fp = targetPath(t);
+      if (fs.existsSync(fp) && fs.readFileSync(fp, 'utf-8').includes(MARKER)) {
+        fs.unlinkSync(fp);
+        removed.push(t.id);
+      }
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
+function detectSlashTargets() {
+  return SLASH_TARGETS.filter(t => fs.existsSync(path.join(os.homedir(), t.parent)));
+}
+
+module.exports = { installSlashCommands, removeSlashCommands, detectSlashTargets, INTENT_PROMPT };

package/lib/suggest.js

@@ -38,6 +38,7 @@ function suggestAll(s = {}) {
     turnsThisSession = 0,
     seqStale = false,
     ambientOn = false,
+    shimOn = false,
     commitsSinceIntent = 0,
     bestKeeper = null,   // { route, label, keptRate, total } from the record, or null
   } = s;
@@ -132,6 +133,18 @@ function suggestAll(s = {}) {
     });
   }
 
+  // 6. Shim off — the guaranteed proof-of-life. phewsh prints a status banner
+  // when you launch any tool, then runs the real tool. Offer once it's not on.
+  if (!shimOn && installedHarnesses.length > 0) {
+    out.push({
+      id: 'enable-shim',
+      priority: 48,
+      message: `See phewsh work every time you launch a tool — a status banner (intent loaded, record current) before Claude/Codex/etc.`,
+      command: 'phewsh shim on',
+      why: 'phewsh prints the proof itself, so it\'s guaranteed; the real tool always runs. Reversible: `phewsh shim off`.',
+    });
+  }
+
   return out.sort((a, b) => b.priority - a.priority);
 }
 

package/package.json

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